DosSearchPath

Bindings:  C, MASM 

This call provides a general path search mechanism that allows 
applications to find files residing along paths.  The path string may come 
from the process environment, or be supplied directly by the caller. 

 DosSearchPath     (Control, PathRef, FileName, ResultBuffer, 
                   ResultBufferLen) 
 

 Control (USHORT) - input 
    A word bit vector that controls the behavior of DosSearchPath. 

    Bit       Description 

    15-3      Reserved bits, must be zero. 

    2         Ignore network errors bit. The Ignore Network Errors Bit 
              controls whether the search will abort if it encounters a 
              network error or will continue the search with the next 
              element.  This allows one to place network paths in the PATH 
              variable and be able to find executables in components of 
              the PATH variable even if the network returns an error, for 
              example, if a server is down.  If the Ignore Network Errors 
              Bit = 0, DosSearchPath will abort the search if it 
              encounters an error from the network.  If the Ignore Network 
              Errors Bit = 1, DosSearchPath will continue on the search if 
              it encounters network errors. 

    1         Path source bit.  The path source bit determines how 
              DosSearchPath interprets the PathRef argument. 

              0 = The PathRef points to the actual search path. The search 
              path string may be anywhere in the calling process's address 
              space.  Therefore, it may be in the environment, but is not 
              required. 

              1 = The PathRef points to the name of an environment 
              variable in the process environment, and that environment 
              variable contains the search path. 

    0         Implied current bit. The implied current bit controls 
              whether the current directory is implicitly on the front of 
              the search path. 

              0 = DosSearchPath only searches the current directory if it 
              appears in the search path. 

              1 = DosSearchPath searches the current working directory 
              before it searches the directories in the search path. 

              For example, implied current bit = 0 and path = ".\;a;b" is 
              equivalent to implied current bit = 1 and path = "a;b". 

 PathRef (PSZ) - input 
    Address of the path. If the path source bit of control = 0, PathRef is 
    the search path that may be anywhere in the caller's address space. 

    A search path consists of a sequence of paths separated by a semicolon 
    (;).  It is a single ASCIIZ string.  The directories are searched in 
    the order they appear in the path. 

    If the path source bit of control = 1, PathRef is the name of an 
    environment variable, that contains the search path. 

    A search path consists of a sequence of paths separated by ";". It is 
    a single ASCIIZ string.  The directories are searched in the order 
    they appear in the path.  Paths that contain ";"s should be quoted. 
     For example: 

    "c:&this  is  ;  one directory path";thisisanother
    

    Environment variable names are simply strings that match name strings 
    in the environment.  The equal (=) sign is not part of the name. 

 FileName (PSZ) - input 
    Address of the ASCIIZ file name. It may contain global file name 
    characters.  If FileName does contain global file name characters, 
    they remain in the result path returned in ResultBuffer.  This allows 
    applications like CMD.EXE to feed the output directly to DosFindFirst. 
     If there are no global file name characters in FileName, the 
    resulting path returned in ResultBuffer is a full qualified name, and 
    may be passed directly to DosOpen, or any other system call. 

 ResultBuffer (PBYTE) - output 
    Address of the pathname of the file, if found. If FileName is found in 
    one of the directories along the path, its full pathname is returned 
    in ResultBuffer (with global file name characters from FileName left 
    in place.) Do not depend on the contents of ResultBuffer being 
    meaningful if DosSearchPath returns a non-zero return code. 

 ResultBufferLen (USHORT) - input 
    Length, in bytes, of the ResultBuffer. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    1         ERROR_INVALID_FUNCTION 
    2         ERROR_FILE_NOT_FOUND 
    87        ERROR_INVALID_PARAMETER 
    111       ERROR_BUFFER_OVERFLOW 
    203       ERROR_ENVVAR_NOT_FOUND 
 
 Remarks 

 PathRef always points to an ASCIIZ string. Let DPATH be an environment 
 variable in the environment segment of the process. 

 "DPATH=c:\sysdir;c:\init"  /* in the environment */
 

 The following two code fragments are equivalent: 

 DosScanEnv("DPATH", &PathRef);
 DosSearchPath(0, /* Path Source Bit = 0 */
     PathRef, "myprog.ini", &ResultBuffer, ResultBufLen);
 
 DosSearchPath(2, /* Path Source Bit = 1 */
     "DPATH", "myprog.ini", &ResultBuffer, ResultBufLen);
 

 They both use the search path stored as DPATH in the environment segment. 
  In the first case, the application uses DosScanEnv to find the variable: 
 in the second case DosSearchPath calls DosScanEnv for the application. 

 DosSearchPath does not check for consistency or formatting on the names. 
  It does a DosFindFirst on a series of names it constructs from PathRef 
 and FileName. 

 To determine the size of the returned path name, the ResultBuffer must be 
 scanned for the ASCIIZ terminator. 

 DosQSysInfo must be used by an application to determine the maximum path 
 length supported by OS/2.  The returned value should be used to 
 dynamically allocate buffers that are to be used to store paths.