dllload() — Load the dynamic link library and connect it to the application
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
C Library | both |
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.
AMODE
of the application
must be the same as the AMODE
of the DLL load module.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).
- If the POSIX(ON) runtime option is specified, then the z/OS UNIX file system is searched first for the DLL, and if not found, the MVS load library is searched.
- If the POSIX(OFF) runtime option is specified, then the MVS load library is searched first for the DLL, and if not found, the z/OS UNIX file system is searched.
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
- 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);
}
}