DosSearchPath

Finds files residing along paths. The path string may come from the process environment, or be supplied directly by the caller.

Syntax

DosSearchPath(flag, pszPathOrName, pszFilename, pBuf, cbBuf)

Parameters

flag (ULONG) - input

A word bit vector that controls the behavior of DosSearchPath. This parameter contains the following bit fields:

31-3 - Reserved; must be 0.

2 - SEARCH_IGNORENETERRS (0x00000004)

Ignore Network Errors bit. This bit controls whether the search will abort if it encounters a network error, or will continue the search with the next element. This allows you 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 is 0, DosSearchPath will end the search if it encounters an error from the network. If the Ignore Network Errors Bit is 1, DosSearchPath will continue the search if it encounters network errors.

1 - SEARCH_ENVIRONMENT (0x00000002)

Path Source bit. This bit determines how DosSearchPath interprets pszPathOrName

0 pszPathOrName 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 szPathOrName. points to the name of an environment variable in the process environment, and that environment variable contains the search path.

0 - SEARCH_CUR_DIRECTORY (0x00000001)

Implied Current bit. This 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".

pszPathOrName (PSZ) - input

Address of the path.

If the Path Source bit of flag is 0, pszPathOrName is the search path that may be anywhere in the caller's address space.

If the Path Source bit of flag is 1, pszPathOrName is the name of an environment variable that contains the search path.

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. Paths that contain semicolons 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.

pszFilename (PSZ) - input

Address of the ASCIIZ file name.

It may contain global file-name characters. If pszFilename does contain global file-name characters, they remain in the result path returned in pBuf. This allows applications like CMD.EXE to pass the output directly to DosFindFirst. If there are no global file-name characters in pszFilename, the resulting path returned in pBuf is a fully qualified name, and may be passed directly to DosOpen, or any other system function.

pBuf (PBYTE) - output

Address of the path name of the file, if found.

If pszFilename is found in one of the directories along the path, its full path name is returned in pBuf (with global file-name characters from pszFilename left in place). The contents of pBuf are not meaningful if DosSearchPath returns a nonzero return code.

cbBuf (ULONG) - input

The length, in bytes, of pBuf.

Return Code

ulrc (APIRET) - returns

DosSearchPath returns one of the following values:

• 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

pszPathOrName 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 issues DosScanEnv to find the variable; in the second case, DosSearchPath issues DosScanEnv for the application.

DosSearchPath does not check for consistency or formatting of the names. It issues DosFindFirst on a series of names that it builds from pszPathOrName and pszFilename

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

An application must issue DosQuerySysInfo to determine the maximum path length that the operating system supports. The returned value should be used to dynamically allocate buffers that are to be used to store paths.

Example Code

This example scans the environment segment for the "PATH" variable and displays it. It then searches the path, plus the current directory of the "VIEW.EXE" program.

 #define INCL_DOS
 #define INCL_DOSERRORS       /* DOS error values */
 #include <os2.h>
 #include <stdio.h>

int main(VOID) {
   PSZ       PathValue         = "";        /* PATH environment variable  */
   UCHAR     SearchResult[256] = "";        /* Result of PATH search      */
   APIRET    rc                = NO_ERROR;  /* Return code                */

   rc=DosScanEnv("PATH",&PathValue);  /* Get contents of PATH environment
                                         variable                         */
   if (rc != NO_ERROR) {
       printf("DosScanEnv error: return code = %u\n",rc);
       return 1;
   } else {
       printf("PATH is:\n%s\n\n", PathValue);
   }
      /* Scan the current directory and path for the VIEW.EXE program.
         Ignore any errors from network drives which may not be in use. */

   rc=DosSearchPath(SEARCH_CUR_DIRECTORY | SEARCH_IGNORENETERRS,
                    PathValue,               /* Path value just obtained */
                    "VIEW.EXE",              /* Name of file to look for */
                    SearchResult,            /* Result of the search     */
                    sizeof(SearchResult));   /* Length of search buffer  */

   if (rc != NO_ERROR) {
       printf("DosSearchPath error: return code = %u\n",rc);
       return 1;
   } else {
       printf("Found desired file -- %s\n", SearchResult);
   }
  return NO_ERROR;
 }

Related Functions

• DosFindFirst
• DosFindNext
• DosQuerySysInfo
• DosScanEnv