Loading DLLs

When you load an AMODE 64 DLL for the first time, either implicitly or via an explicit dllload() or dlopen(), writable static area is initialized. If the DLL is written in C++ and contains static objects, then their constructors are run.

You can load DLLs from a z/OS UNIX file system as well as from conventional data sets. The following list specifies the order of a search for unambiguous and ambiguous file names.

• Unambiguous file names
  • If the file has an unambiguous z/OS UNIX name (it starts with a ./ or contains a /), the file is searched for only in the z/OS UNIX file system.
  • If the file has an unambiguous MVS™ name, and starts with two slashes (//), the file is only searched for in MVS.
• Ambiguous file names

  For ambiguous cases, the settings for POSIX are checked.

  • When specifying the POSIX(ON) runtime option, the runtime library attempts to load the DLL as follows:
    1. An attempt is made to load the DLL from the z/OS UNIX file system by using the system service BPX4LOD. For more information about BPX4LOD, see loadhfs (BPX1LOD, BPX4LOD) — Load a program into storage by path name in z/OS UNIX System Services Programming: Assembler Callable Services Reference.

       If the environment variable LIBPATH is set, each directory that is listed will be searched for the DLL. Otherwise, the current directory will be searched for the DLL. Searches for the DLL in the z/OS UNIX file system are case-sensitive.

    2. If the DLL is found and contains an external link name of eight characters or less, the uppercase external link name is used to attempt a LOAD from the caller's MVS load library search order. If the DLL is not found or the external link name is more than eight characters, then the load fails.
    3. If the DLL is found and its sticky bit is on, any suffix is stripped off. Next, the name is converted to uppercase, and the base DLL name is used to attempt a LOAD from the caller's MVS load library search order. If the DLL is not found or the base DLL name is more than eight characters, the version of the DLL in the z/OS UNIX file system is loaded.
    4. If the DLL is found and does not fall into one of the previous two cases, a load from the z/OS UNIX file system is attempted.
    If the DLL could not be loaded from the z/OS UNIX file system because the file was not found or the application doesn't have sufficient authority to search for or read that file (that is, BPX4LOD fails with errnos ENOENT, ENOSYS, or EACCESS), then an attempt is made to load the DLL from the caller's MVS load library search order. For all other failures from BPX4LOD, the load of the DLL is terminated.

    • For an implicit DLL load, the error is reported with the errno and errnojr displayed in message CEE3512S.
    • For an explicit DLL load with dllload(), the service returns with the failing errno and errnojr values set.
    • For an explicit DLL load with dlopen(), the dlerror() service will return the failing error.

    Correct the indicated error and rerun the application.

    If the DLL could not be loaded from the z/OS UNIX file system, an attempt is made to load the DLL from the caller's MVS load library search order. This is done by calling the LOAD service with the DLL name, which must be eight characters or less (it will be converted to uppercase). LOAD searches for it in the following sequence:

    1. Runtime library services (if active)
    2. Job pack area (JPA)
    3. TASKLIB
    4. STEPLIB or JOBLIB. If both are allocated, the system searches STEPLIB and ignores JOBLIB.
    5. LPA
    6. Libraries in the linklist
  • When POSIX(OFF) is specified the sequence is reversed.
    • An attempt to load the DLL is made from the caller's MVS load library search order.
    • If the DLL could not be loaded from the caller's MVS load library, then an attempt is made to load the DLL from the z/OS UNIX file system.

Changing the search order for DLLs while the application is running (for example, changing LIBPATH) might result in errors if ambiguous file names are used.