DLL | NODLL

Pragma equivalent

None.

Purpose

Generates object code for DLLs or DLL applications.

Syntax

For C and IPA Link:


   .-NODLL-.  .-(NOCBA)-.   
>>-+-DLL---+--+---------+--------------------------------------><
              '-(CBA)---'

For C++:


   .-DLL---.  .-(NOCBA)-.   
>>-+-NODLL-+--+---------+--------------------------------------><
              '-(CBA)---'

Defaults

For a C compile and the IPA link step, the default option is NODLL(NOCBA). For a C++ compile, the default option is DLL(NOCBA).

Parameters

NOCALLBACKANY: This is the default. If you specify NOCALLBACKANY, no changes will be made to the function pointer in your compile unit. The abbreviation for NOCALLBACKANY is NOCBA.
CALLBACKANY: If you specify CALLBACKANY, all calls through function pointers will accommodate function pointers created by applications compiled without the DLL option. This accommodation accounts for the incompatibility of function pointers created with and without the DLL compiler option. The abbreviation for CALLBACKANY is CBA.
Note: Function pointers defined with extern "C++" linkage are never subject to CALLBACKANY accomodation because C++ always uses DLL linkage; as a function pointer will inherit extern "C++" linkage by virtue of appearing in a C++ program unless there is an explicit specification otherwise, you need to specify DLL(CALLBACKANY) and supply appropriate extern "?" linkage specifications for your function pointers to get CALLBACKANY accomodation.

The CALLBACKANY suboption is not supported when the XPLINK option is used. When function pointers having their origins (that is, where the address of a function is taken and assigned to a function pointer) in XPLINK code in the same or another DLL, or NOXPLINK NODLL code in another DLL, or non-XPLINK DLL code in another DLL, are passed to exported XPLINK functions, the compiler inserts code to check whether or not the function pointers received as actual arguments are valid (useable directly) XPLINK function pointers, and converts them if required. This provides results that are similar in many respects to the function pointer conversion provided when DLL(CALLBACKANY) is specified for non-XPLINK code. Other function pointers that have their origins in non-XPLINK code, including function pointer parameters passed to non-exported functions or otherwise acquired, are not converted automatically by XPLINK compiled code. Use of such function pointers will cause the application to fail.

Usage

When the DLL option is in effect, the compiler is instructed to produce DLL code. The DLL code can export or import functions and external variables.

Note: You should write your code according to the rules listed in the z/OS XL C/C++ Programming Guide, and compile with the NOCALLBACKANY suboption. In addition, make sure that the high-order bit in function pointer is off. If the high-order bit is on, the code that makes the CALLBACKANY call acts as though there are no passed parameters. Use the suboption CALLBACKANY only when you have calls through function pointers and C code compiled without the DLL option. CALLBACKANY causes all calls through function pointers to incur overhead because of internally generated calls to library routines that determine whether the function pointed to is in a DLL (in which case internal control structures need to be updated), or not. This overhead is unnecessary in an environment where all function pointers were created either in C++ code or in C code compiled with the DLL option.

For information on how to create or use DLLs, and on when to use the appropriate DLL options and suboptions, see z/OS XL C/C++ Programming Guide.

Notes:

If NODLL is specified for C++, it will be ignored.
You must use the LONGNAME and RENT options with the DLL option. If you use the DLL option without RENT and LONGNAME, the z/OS® XL C compiler automatically turns them on. However, when the XPLINK option is used, though RENT and LONGNAME are the default options, both NOLONGNAME and NORENT are allowed.
In code compiled with the XPLINK compiler option, function pointers are compared using the address of the descriptor. No special considerations, such as dereferencing, are required to initialize the function pointer prior to comparison.
In code compiled with the NOXPLINK compiler option, you cannot cast a non-zero integer const type to a DLL function pointer type as shown in the following example:
```
void (*foo)();

void main() {
             /* ... */

         if (foo != (void (*)()) (50L) ) {
             /* do something other than calling foo */
         }
}
```
This conditional expression will cause an abend at execution time because the function pointer (with value 50L) needs to be dereferenced to perform the comparison. The compiler will check for this type of casting problem if you use the CHECKOUT(CAST) option along with the DLL option. See CHECKOUT | NOCHECKOUT (C only) for more information on obtaining diagnostic information for C applications.

IPA effects

The IPA compile step generates information for the IPA link step. The CALLBACKANY option also affects the regular object module if you request one by specifying the IPA(OBJECT) option.

The IPA link step accepts the DLL compiler option, but ignores it.

The IPA link step uses information from the IPA compile step to classify an IPA object module as DLL or non-DLL as follows:

C code that is compiled with the DLL option is classified as DLL.
C++ code is classified as DLL
C code that is compiled with the NODLL option is classified as non-DLL.

Note: If you are using IPA and specify the DLL compiler option, your code should export at least one function.

Each partition is initially empty and is set as DLL or non-DLL, when the first subprogram (function or method) is placed in the partition. The setting is based on the DLL or non-DLL classification of the IPA object module which contained the subprogram. Procedures from IPA object modules with incompatible DLL values will not be inlined. This results in reduced performance. For best performance, compile your application as all DLL code or all non-DLL code.

The IPA link step allows you to input a mixture of IPA objects that are compiled with DLL(CBA) and DLL(NOCBA). The IPA link step does not convert function pointers from the IPA Objects that are compiled with the option DLL(NOCBA).

You should only export subprograms (functions and C++ methods) or variables that you need for the interface to the final DLL. If you export subprograms or variables unnecessarily (for example, by using the EXPORTALL option), you severely limit IPA optimization. Global variables are not coalesced, and inlined code is not 100% pruned.

Predefined macros

For C, __DLL__ is predefined to 1 when the DLL option is in effect; otherwise it is undefined.
For C++, __DLL__ is always predefined to 1.