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 HFS 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 HFS name (it starts with a ./ or contains a /), the file is searched for only in the HFS.
    • 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 HFS. This is done using the system service BPX4LOD. 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 HFS 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 HFS is loaded.
      4. If the DLL is found and does not fall into one of the previous two cases, a load from the HFS is attempted.
      If the DLL could not be loaded from the HFS 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 re-run the application.

      If the DLL could not be loaded from the HFS, 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 HFS.

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 symlinks) may result in a decrease in DLL load performance. The use of HFS 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 HFS loads).

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