DosSearchPath searches directory paths for t he name of a file object. The file specification can include metacharacters (global file name characters).

The path string used in the search consists of directory paths separated by semicolons. The caller can supply the path string, or it can supply the name of an environment variable whose value is the path string to be searched. The caller can request that the current working directory be searched before the path string is searched.

If the caller specifies an environment variable, DosSearchPath uses DosScanEnv to find the path string. DosScanEnv searches the environment segme nt for an environment variable name; for example, DPATH. The result pointer points to the string that is the value of the environment variable. The call to DosScanEnv can be made direct ly by the application, or it can be invoked by DosSearchPath.

If the file is found, its full path name is returned, with metacharacters left in place. The results might not be meaningful if a buffer overflow occurs.

As an example, assume that a string such as the following exists in the environment:

    DPATH=C:\SYSDIR;C:\INIT

The following code fragment illustrates a method for searching directory paths to find a file.

    #define INCL_DOSFILEMGR   /* File system values */
    #define INCL_DOSMISC
    #include <os2.h>
    #include <stdio.h>

    #define ResultBufLen 255

INT main(VOID)
{
    PSZ  pszPathRef="";
    UCHAR achResultBuffer[ResultBufLen};
    PSZ   pszFile="OS2.INI";

    DosScanEnv("DPATH",
               &pszPathRef);

    DosSearchPath(0,                   /* Path source bit=0 */
                  pszPathRef,
                  pszFile,
                  achResultBuffer,
                  ResultBufLen);

    printf("Result 1: %s\n",
           achResultBuffer);

    DosSearchPath(2,                   /* Path source bit=1 */
                  (PSZ)"DPATH",
                  pszFile,
                  achResultBuffer,
                  ResultBufLen);

    printf("Result 2: %s\n",
           achResultBuffer);

    return;

}