DosScanEnv

Description

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

Syntax

#define INCL_DOSFILEMGR
#define INCL_DOSMISC
#include <os2.h>

PSZ       pszName;    /*  Address of the name of the environment variable. */
PSZ      *ppszValue;  /*  A pointer to the PSZ in which a pointer to the environment string is returned by the system. */
APIRET    ulrc;       /*  Return Code. */ 

ulrc = DosScanEnv(pszName, ppszValue);

Parameters

pszName (PSZ) - input

Address of the name of the environment variable. Do not include a trailing equal sign ( = ), since this is not part of the name.

ppszValue (PSZ *) - output

A pointer to the PSZ in which a pointer to the environment string is returned by the system.

ppszValue points to the first character of the string that is the value of the environment variable, and can be passed directly to DosSearchPath.

Return Code

ulrc (APIRET) - returns

DosScanEnv returns the following values:

• 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.

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