DosSetExtLIBPATH

Defines the current path to be searched before or after the system LIBPATH when locating DLLs.

Syntax

DosSetExtLIBPATH (pszExtLIBPATH, flags)

Parameters

pszExtLIBPATH (PSZ) - input

Extended LIBPATH string.

This buffer has a maximum size of 1024 bytes.

A pointer to a NULL string removes the extended LIBPATH.

flags (ULONG) - input

Flag indicating when the new path is searched.

Possible values are described in the following list:

BEGIN_LIBPATH (1) The new path is searched before the LIBPATH.

END_LIBPATH (2) The new path is searched after the LIBPATH.

Return Code

ulrc (APIRET) - returns

DosSetExtLIBPATH returns one of the following values:

• 0 NO_ERROR
• 8 ERROR_NOT_ENOUGH_MEMORY
• 87 ERROR_INVALID_PARAMETER
• 161 ERROR_BAD_PATHNAME

Remarks

The LIBPATH string is an environment variable found in the CONFIG.SYS file consisting of a set of paths. If a fully-qualified path is not specified when a module is loaded, the system searches these paths to find the DLL.

There are two extended LIBPATH strings, BeginLIBPATH and EndLIBPATH. BeginLIBPATH is searched before the system LIBPATH, and EndLIBPATH is searched after both BeginLIBPATH and the system LIBPATH. These extended LIBPATHs can be set either from the command line using the "SET" command, or by calling DosSetExtLIBPATH. When DosSetExtLIBPATH is called, all modifications become specific to that process. Initial settings can be set for all processes in the system by setting the values in CONFIG.SYS using the "set" command.

Note: The extended LIBPATHs are not true environment variables, and do not appear when querying the environment.

Every process inherits the settings of BeginLIBPATH and EndLIBPATH from the process that starts it. If the extended library paths are initialized in CONFIG.SYS, those extended library paths become the initial settings for new processes. If a process changes BeginLIBPATH or EndLIBPATH and starts a new process, the new child process inherits the changed contents. Child processes that inherit their parent's extended LIBPATHs maintain their own copy. Modifications made by the parent after the child has been created have no effect on the children.

This function permits the use of two symbols within the path string: %BeginLIBPATH% and %EndLIBPATH%. These symbols are replaced with the current string settings for the extended library paths. For example, if BeginLIBPATH is set to

d:\MYDLLS;

and your application calls

DosSetExtLIBPATH("d:\TOMSDLLS;%BeginLIBPATH%;d:\JOESDLLS;", 1);

the resulting BeginLIBPATH is

d:\TOMSDLLS;d:\MYDLLS;d:\JOESDLLS;

The LIBPATHs strings are only searched when the specified DLL is not currently loaded. The only way to guarantee that the DLL being used is the correct version is to set the fully-qualified path in DosLoadModule. When a request is made to load a module and a path is not specified, the system searches the paths in the LIBPATH string and uses the first instance of the specified DLL it finds. If the new paths are added to the search strings, the system does not check those directories to see if a different version exists. Consequently, if two processes started from different directories use the same DLL, but different versions of that DLL exist in both directories, the version of the DLL loaded by the first process is the one used by both processes. The only way to prevent this from occurring is to specify the path to the DLL when DosLoadModule is called.

Consequently, if one process sets its BeginLIBPATH to C:\PROCESS1\DLL and loads the DLL MYAPP.DLL from that directory, and then a second process sets its BeginLIBPATH to C:\PROCESS2\DLL and there is for a different version of MYAPP.DLL in C:\PROCESS2\DLL, the second process will link to the DLL from C:\PROCESS1\DLL since it was already loaded.

Both BeginLIBPATH and EndLIBPATH can be set from the command line using the SET command. For more information about setting LIBPATHS from the command line, see the OS/2 Command Reference.

Example Code

This example updates the paths to be searched before and after the system LIBPATH, when locating a DLL.

 
 #define INCL_DOSMISC
 #define INCL_DOSERRORS
 #include <os2.h>
 #include <stdio.h>

 int main(VOID) {

 UCHAR   uchBeginLIBPATH[512] = "";       /* Begin LIBPATH value returned */
 UCHAR   uchEndLIBPATH[512]   = "";       /* End LIBPATH value returned   */
 APIRET  rc                   = NO_ERROR;    /* Return code               */

    rc = DosSetExtLIBPATH("C:\\TOOL_X\\VERS_20\\DLL",
                          BEGIN_LIBPATH);    /* Add to beginning LIBPATH */
    if (rc != NO_ERROR) {
        printf("DosSetExtLIBPATH error: return code = %u\n", rc);
        return 1;
    }

    rc = DosSetExtLIBPATH("C:\\TOOL_X\\VERS_10\\DLL",
                          END_LIBPATH);      /* Add to ending LIBPATH   */
    if (rc != NO_ERROR) {
        printf("DosSetExtLIBPATH error: return code = %u\n", rc);
        return 1;
    }

    rc = DosQueryExtLIBPATH(uchBeginLIBPATH,
                            BEGIN_LIBPATH);   /* Query the BeginLIBPATH */
    if (rc != NO_ERROR) {
        printf("DosQueryExtLIBPATH error: return code = %u\n", rc);
        return 1;
    }

    rc = DosQueryExtLIBPATH(uchEndLIBPATH,
                            END_LIBPATH);     /* Query the EndLIBPATH   */
    if (rc != NO_ERROR) {
        printf("DosQueryExtLIBPATH error: return code = %u\n", rc);
        return 1;
    }

    printf(" BeginLIBPATH = %s\n", uchBeginLIBPATH);
    printf("   EndLIBPATH = %s\n", uchEndLIBPATH);

  return NO_ERROR;
}

Related Functions

• DosQueryExtLIBPATH