Loading DLLs

When you load a DLL for the first time, either implicitly or via an explicit dllload() or dlopen(), writable static 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. This is done using the system service BPX1LOD. For more information on this service, see z/OS UNIX System Services Programming: Assembler Callable Services Reference.

       If the environment variable LIBPATH is set, each directory listed will be searched for the DLL. Otherwise the current directory will be searched for the DLL. Note that a search for the DLL in the z/OS UNIX file system is 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 does not have sufficient authority to search for or read that file (that is, BPX1LOD 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 BPX1LOD, 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, the dllload() service returns with the failing errno and errnojr values set. 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

    For more information, see z/OS MVS Initialization and Tuning Guide

  • 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.

Recommendation: All DLLs used by an application should be referred to by unique names, whether ambiguous or not. Using multiple names for the same DLL (for example, aliases or symbolic links) might result in a decrease in DLL load performance. The use of symbolic links by themselves will not degrade performance, as long as the application refers to the DLL solely through the symbolic link name. To help ensure this, when building an application with implicit DLL references always use the same side deck for each DLL. Also, make sure that explicit DLL references with dllload() specify the same DLL name (case matters for loads).

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.