gtpa2m18Application Programming

Dynamic Link Library (DLL) Support

To use DLLs, you must use one of the following compilers:

Note:
There is no IBM VM compiler that supports the DLL compiler option. All applications that use the DLL compiler option must be compiled on an IBM MVS system. See the TPF Migration Guide: Program Update Tapes for more information about C/C++ compilers.

Several terms are defined to help you understand DLLs. Also see "E-Type Program Chart and Program Attributes" for more information about where DLLs and DLL applications fit into the realm of TPF executable E-type programs and their characteristics and attributes.

See the IBM C/C++ programming guide and user's guide for the compiler used by your installation for a more thorough discussion of DLL support. See "IBM High-Level Language Books" for a list of C and C++ compiler publications on the System/390 platform.

Terminology and Concepts

 Definition side-deck 
A directive file that contains an IMPORT control statement for each function and variable exported by the DLL. When you build a DLL, a definition side-deck is automatically created and written to the SYSDEFSD DDname by the prelinker. You must include this definition side-deck when you prelink a DLL application that imports any of those functions or variables from a DLL.

 Dynamic link library (DLL) 
A collection of one or more functions or variables gathered in a load module and executable or accessible from a separate DLL application load module.

 DLL application 
An application that can reference imported functions or imported variables in a DLL.

 Function descriptor 
An internal control block that contains the function address and its associated writable static area (WSA). In the TPF system, a function descriptor can be thought of as a dynamic linkage call stub in contrast to the static linkage call stubs that are generated offline by the DLM stub generator tool (STUB) and the library interface tool (LIBI) before link-edit time.

 Variable descriptor 
An internal control block that contains the variable address. This control block is a dynamic linkage call stub.

The following are concepts to be aware of:

Linkage

The connection or link between the DLL application that uses the DLL and the DLL functions or variables is made dynamically while the application is being run rather than statically when the application is built. You can, therefore, call a function or use a variable in a load module other than the one that contains the definition. You can use DLLs both implicitly and explicitly. When an application calls an imported function or references an imported variable, the DLL is implicitly loaded. This is referred to as load-on-call. For an explicit call, the application uses explicit source-level calls to one or more run-time services to connect the reference to the definition. These connections are made at run time.

The CISO run-time library has been updated with several application programming interfaces (APIs) that allow a load module to explicitly call these run-time services:

See the TPF C/C++ Language Support User's Guide for more information about these services.

Functions or variables in DLLs can be called or referenced only through DLL linkage. The DLL cannot be called with TPF enter/back services.

Definition Side-Deck

When you link-edit a DLL or DLL application, in addition to specifying the included object files, you must also specify the definition side-deck inputs if the DLL or DLL application imports from other DLLs. A definition side-deck is automatically generated by the prelinker and contains IMPORT control statements for functions and variables exported by a DLL. The linkage editor resolves external functions in the following search order:

  1. Those functions explicitly included in text decks (this is from the original list of included object files in a load module build script)
  2. Those functions in included EXPORT data set members
  3. Those functions for which static stubs exist in stub data sets concatenated under the SYSLIB data set. These stubs are created with the STUB tool.

Using sample load module FOOG, the following is an example of code that exports functions and variables and its resulting definition side-deck:

     #pragma export(foo)
     #pragma export(goo)
     int foo()
     {
     ...
     }
     int goo()
     {
     ...
     }
     int keep_it_hidden()
     {
     ...
     }
     ...
 
     #pragma export (hooVar)
     #pragma export (gooVar)
     int hooVar;
     int gooVar;
     int keep_it_hidden_variable;
 
     Definition Side-Deck produced:
 
           IMPORT CODE 'FOOG' foo
           IMPORT CODE 'FOOG' goo
           IMPORT DATA 'FOOG' hooVar
           IMPORT DATA 'FOOG' gooVar

The C load module build tool (CBLD) has been updated to handle definition side-decks and DLLs. See "ISO-C Load Module Build Tool (CBLD)" for more information about CBLD.

DLLs and Subsystem Dependencies

User exit function is_dll_user_ss_shared is in source file USUD, which is in DLM USUD. Adding shared user subsystem DLL names to the table in this module allows for those DLLs to be accessed by applications running in other subsystems. See TPF System Installation Support Reference for more information about this user exit.