dllload() — Load the dynamic link library and connect it to the application

Standards

Format

#include <dll.h>

dllhandle *dllload(const char *dllName);

General description

Loads the dynamic link library (DLL) into memory (if it has not been previously loaded) and connects it to the application. The function that called the DLL receives a handle that uniquely identifies the requested DLL for subsequent explicit requests for that DLL.

A different handle is returned for each successful call to dllload(). A DLL is physically loaded only once, even though there may be many calls to dllload(). C++ constructors are run only once.

The dllName identifies the DLL load module to be loaded. It must be a character string terminated with the NULL character. The DLL module must be a member of a PDS or an alias to it.

This function is not available under SPC, MTF and CSP environments.

The dllName identifies the DLL load to be loaded. It must be a character string, terminated with the NULL character. The DLL module must be a member of a PDS or an alias to it.

If the file argument contains a single slash ('/'), it is used as the z/OS® UNIX file system path name for the DLL. If the environment variable LIBPATH is set, each directory listed will be searched for the DLL. Otherwise, the current directory will be searched.

If the file argument begins with two slashes ('//'), then an attempt is made to load the DLL from the caller's MVS™ load library search order (in order: STEPLIB/JOBLIB, LPA, Link List). The DLL name must be eight characters or less, and is converted to uppercase. Note that qualified DLL names are not supported and the MVS load library search order is used (for example, update or use STEPLIB to specify any number of qualifiers to be included in the search).

Under CICS® environment, the search sequence for DLL load modules is the same as that used for dynamically loaded CICS modules. Loading DLLs from the z/OS UNIX file system is not supported under CICS.

For more information about how DLLs are loaded and how the search sequence is used, see the topic about in z/OS Language Environment Programming Guide.

Returned value

If successful, dllload() returns a unique handle that identifies the DLL.

If unsuccessful, dllload() returns NULL and may set errno to one of the following values:

Error Code

Description

ELEFENCE

The DLL contains a member language not supported on this version of the operating system.

ENOEXEC

The new process image file has the appropriate access permission but is not in the proper format.

Note: Reason codes further qualify the errno. For most of the reason codes, see z/OS UNIX System Services Messages and Codes.

For ENOEXEC, the reason codes are:

Reason Code	Explanation
X'xxxx0C27'	The target z/OS UNIX file system file is not in the correct format to be an executable file.
X'xxxx0C31'	The target z/OS UNIX file system file is built at a level that is higher than that supported by the running system.

Usage notes

1. More detailed diagnostic information is available through the _EDC_DLL_DIAG environment variable, and the Language Environment® DLL Failure control block (CEEDLLF) chain.

Example

/* CELEBDL1

   The following example shows how to invoke dllload() functions
   from a simple C application.

 */
#include <stdio.h>
#include <dll.h>

main() {
    dllhandle *handle;
    char *name="stream";

    handle = dllload(name);
    if (handle == NULL) {
       perror("failed on dllload of stream DLL");
       exit(-1);
    }
}

Related information

• dll.h — DLL functions
• dlopen() — Gain access to a dynamic link library
• dllfree() — Free the supplied dynamic link library
• dllqueryfn() — Obtain a pointer to a dynamic link library function
• dllqueryvar() — Obtain a pointer to a dynamic link library variable