DosScanEnv (OS/2 1.x)

From EDM2
Jump to: navigation, search

This call scans (searches) an environment segment for an environment variable.

Syntax

DosScanEnv (EnvVarName, ResultPointer)

Parameters

EnvVarName (PSZ) - input 
Address of the name of the environment variable. Do not include a trailing " = ", since this is not part of the name.
ResultPointer (PSZ FAR *) - output 
Address where the system returns the pointer to the environment string. ResultPointer points to the first character of the string that is the value of the environment variable and can be passed directly into DosSearchPath.

Return Code

rc (USHORT) - return
Return code descriptions are:
  • 0 NO_ERROR
  • 203 ERROR_ENVVAR_NOT_FOUND

Remarks

Assume that the process' environment contains:

"DPATH=c:\sysdir;c:\libdir"
   |
   À---- ResultPointer points here after the
         following call to DosScanEnv:

  DosScanEnv("DPATH", &ResultPointer);

As noted above, ResultPointer points to the first character of the value of the environment variable.

Bindings

C

#define INCL_DOSQUEUES

USHORT  rc = DosScanEnv(EnvVarName, ResultPointer);

PSZ              EnvVarName;    /* Environment variable name string */
PSZ FAR *        ResultPointer; /* Search result pointer (returned) */

USHORT           rc;            /* return code */

MASM

EXTRN  DosScanEnv:FAR
INCL_DOSQUEUES      EQU 1

PUSH@  ASCIIZ  EnvVarName    ;Environment variable name string
PUSH@  DWORD   ResultPointer ;Search result pointer (returned)
CALL   DosScanEnv

Returns WORD

Example

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);
}