Microsoft KB Archive/65290

How to Search for Environment Strings in an OS/2 COBOL Program

PSS ID Number: Q65290 Article last modified on 11-21-1990

4.00 OS/2

Summary: A protected mode Microsoft COBOL Professional Development System (PDS) version 4.00 program can search the environment table for a variable and obtain the string value that the variable is equal to. This is accomplished by calling the OS/2 API function DosScanEnv. The sample program below demonstrates how this is done. This information applies to Microsoft COBOL Professional Development System (PDS) version 4.00 for MS OS/2.

More Information: COBOL PDS 4.00 can call OS/2 API functions directly by prefixing their names with a double underscore (__) and linking with the OS2.LIB library. DosScanEnv takes the following parameters:

Note that in COBOL, a DWORD has a picture clause of 9(8) COMP-5 and an ASCIIZ is a PIC X data item terminated with a null (ASCII 0). Furthermore, data items prefixed with PTR must be passed BY REFERENCE. For more information about calling OS/2 API functions from COBOL, see Chapter 14, “Interfacing with OS/2 API Routines,” in the “Microsoft COBOL Professional Development System 4.0: Operating Guide” included with the product. For more information on DosScanEnv, see page 556 of “Advanced OS/2 Programming” by Ray Duncan (Microsoft Press, 1989). Following is a sample program (SCANENV.CBL) that prompts the user for the name of an environment variable and displays its value, if the variable exists. To compile and link the program, enter the following commands at the OS/2 command prompt: cobol scanenv; link scanenv,,,coblib os2;

SCANENV.CBL
IDENTIFICATION DIVISION. PROGRAM-ID. ScanEnv. * COBOL will use OS/2 API calling convention, not its default. SPECIAL-NAMES. CALL-CONVENTION 3 IS OS2API. DATA DIVISION. WORKING-STORAGE SECTION. *  Contains the environment variable name. 01 VariableName  PIC X(9). *  Receives the full address of the value of VariableName. 01 ValueAddress  PIC 9(8) COMP-5. *  Segment address of the value of VariableName. 01 ValueSegment  PIC 9(5). *  Offset address of the value of VariableName. 01 ValueOffset   PIC 9(5). *  Used to read in the bytes of the value of VariableName. 01 Byte          PIC X.  *   Receives error from API function call. 01 ErrorCode     PIC S9(4) COMP-5. PROCEDURE DIVISION. *   Prompt the user for an environment variable name, convert *   it to uppercase, and terminate it with ASCII 0 (a null). DISPLAY &quot;Enter the name of an environment variable:&quot;. ACCEPT VariableName(1:8). INSPECT VariableName REPLACING FIRST &quot; &quot; BY X&quot;00&quot;. CALL &quot;CBL_TOUPPER&quot; USING VariableName, BY VALUE 9 SIZE 4. *   Make the API call. CALL OS2API &quot;__DosScanEnv&quot; USING BY REFERENCE VariableName, BY REFERENCE ValueAddress RETURNING   ErrorCode. *   Check if environment variable was found. IF ErrorCode = 0 THEN DISPLAY VariableName &quot;=&quot; WITH NO ADVANCING *      Compute segment and offset addresses of the value. COMPUTE ValueSegment = ValueAddress / 65536 COMPUTE ValueAddress = ValueAddress * 65536 COMPUTE ValueOffset = ValueAddress / 65536 *      Read and display bytes until a null is found. NOTE: *      The subprogram X&quot;85&quot; reads a byte at a given address. PERFORM UNTIL Byte = X&quot;00&quot; CALL X&quot;85&quot; USING ValueSegment, ValueOffset, Byte DISPLAY Byte WITH NO ADVANCING COMPUTE ValueOffset = ValueOffset + 1 END-PERFORM ELSE DISPLAY &quot;ERROR &quot; ErrorCode END-IF. STOP RUN. Copyright Microsoft Corporation 1990.