Building complex DLLs

Before you attempt to build complex DLLs, it is important to understand the differences between the terms DLL, DLL code, and DLL application.

A DLL (Dynamic Link Library) is a file containing executable code and data bound to a program at run time. The code and data in a DLL can be shared by several applications simultaneously. It is important to note that compiling code with the DLL option does not mean that the produced executable will be a DLL. To create a DLL, you must use the #pragma export or EXPORTALL compiler option.

DLL code is code that can use a DLL. The following are DLL code:

C++ code
C code compiled using the DLL or XPLINK option

Code written in languages other than C++ and compiled without the DLL or XPLINK option is non-DLL code.

A DLL application is an application that can use exported functions or variables that are bound with DLL code. All of the source files that make up a DLL application do not need to be compiled with the DLL or XPLINK option, only the source files that reference exported functions and exported global variables.

If you link DLL code with non-DLL code, the resulting DLL or DLL application is called complex. You might compile your code as non-DLL for the following reasons:

Source modules do not use C or C++.
To prevent problems which occur when a non-DLL function pointer call uses DLL code. This problem takes place when a function makes a call through a function pointer that points to a function entry rather than a function descriptor.

For complex DLLs and DLL applications that you compile without XPLINK, you can use the CBA suboption of the DLL|NODLL compiler option. With this suboption, a call is made, through a function pointer, to the z/OS® Language Environment®, for each function call, at run time. This call eliminates the error that would occur when a non-DLL function pointer passes a value to DLL code.

Note: In this information, unless otherwise specified, all references to the DLL|NODLL compiler option assume suboption NOCBA. For more information, see the DLL compiler option in z/OS XL C/C++ User's Guide.

If you specify the XPLINK compiler option, the CBA and NOCBA suboptions of DLL and NODLL are ignored.

There are two ways to combine XPLINK and non-XPLINK code in the same application:

Compile each entire DLL with XPLINK or without XPLINK. The only interaction between XPLINK and non-XPLINK code occurs at a DLL or fetch() boundary.
Use the OS_UPSTACK, OS_NOSTACK, and OS31_NOSTACK linkage directive. For more information, see the description of the linkage pragma in z/OS XL C/C++ Language Reference.

The steps for creating a complex DLL or DLL application are:

Determining how to compile your source modules.
Modifying the source modules that do not meet all the DLL rules.
Compiling the source modules to produce DLL code and non-DLL code as determined in the previous steps.
Binding your DLL or DLL application.

The focus of this topic is step 1 and step 2. You perform step 3 the same way you would for any other C or C++ application. Binding your code explains step 4.