DosSearchPath (OS/2 1.x)

From EDM2
Jump to: navigation, search

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.

Syntax

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

Parameters

Control (USHORT) - input 
A word bit vector that controls the behavior of DosSearchPath.
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.

Return Code

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.

Binding

C

#define INCL_DOSQUEUES

USHORT  rc = DosSearchPath(Control, PathRef, FileName, ResultBuffer,
                             ResultBufferLen);

USHORT  Control;         /* Function control vector */
PSZ     PathRef;         /* Search path reference string */
PSZ     FileName;        /* File name string */
PBYTE   ResultBuffer;    /* Search result buffer (returned) */
USHORT  ResultBufferLen; /* Search result buffer length */

USHORT  rc;              /* return code */

MASM

EXTRN  DosSearchPath:FAR
INCL_DOSQUEUES      EQU 1

PUSH   WORD    Control         ;Function control vector
PUSH@  ASCIIZ  PathRef         ;Search path reference string
PUSH@  ASCIIZ  FileName        ;File name string
PUSH@  OTHER   ResultBuffer    ;Search result buffer (returned)
PUSH   WORD    ResultBufferLen ;Search result buffer length
CALL   DosSearchPath

Returns WORD

Example Code

The following example scans the environment segment for the PATH variable and prints its value. It then searches the path given by inserting the current directory into the value of the PATH variable for the file named "cmd.exe", and prints the full filename.

#define INCL_DOS

#include <os2.h>

#define ENVVARNAME            "PATH"    /* Environment variable name */
#define FILENAME              "cmd.exe" /* File for which to search */
#define SEARCH_CUR_DIRECTORY  0x03      /* Search control - current dir., */
                                        /*   then environment variable */

main()
{
  PSZ FAR   *ResultPointer;    /* Environment scan result pointer (returned) */
  BYTE      ResultBuffer[128]; /* Path search result (returned) */
  USHORT    rc;                /* return code */

  /** Scan environment segment for PATH; notice the far-string pointer **/
  /**   specification ("%Fs") used to print.                           **/

  if(!(rc=DosScanEnv(ENVVARNAME,       /* Environment variable name */
                     &ResultPointer))) /* Scan result pointer (returned) */
    printf("%s is %Fs\n", ENVVARNAME, ResultPointer);

  /** Search current directory + PATH variable for "cmd.exe"   **/
  if(!(rc=DosSearchPath(SEARCH_CUR_DIRECTORY, /* Search control vector */
                        ENVVARNAME,           /* Search path reference string */
                        FILENAME,             /* File name string */
                        ResultBuffer,         /* Search result (returned) */
                        sizeof(ResultBuffer)))) /* Length of search result */
    printf("Found desired file -- %s\n", ResultBuffer);
}