Getting Environmental Information

Introduction

Most C programs run in a standard operating environment that requires no modification to the SAS/C Library. However, in a nonstandard environment, the L$UENVER routine must be modified to provide information about the special operating environment.

The L$UENVR Routine

L$UENVR is a routine called by the SAS/C Library as part of initialization every time the main function of a C program executes. L$UENVR returns information about the operating system and the current environment.

This description of L$UENVR has two objectives:

L$UENVR Source Code

A sample version of L$UENVR source code is provided on the installation tape (in member L$UENVR).

See your SAS Software Representative for SAS/C software products for the location of this member.

This sample returns information about the standard systems (MVS and CMS) under which the compiler runs. The sample is included so that L$UENVR can be modified by a site to indicate special environments. Comments in the code describe how to make any necessary modifications.

Your site normally does not need to change L$UENVR unless you are running programs in a nonstandard environment. For example, changes in the L$UENVR source code are needed to run C programs under a system (such as ROSCOE) that is different from the systems for which the compiler was developed. Note that the operation of the library in such special environments is not guaranteed, but if the environment resembles a normal MVS or CMS environment closely enough, execution is possible.

Environment Descriptor Block

The L$UENVR routine stores information about the operating system in an environment descriptor block. L$UENVR is called using standard IBM linkage. Register 1 addresses an area in which the environment descriptor block will be built. (This block is mapped by the ENVDB DSECT, which is present in the sample macro library.) Fifty-six bytes that can be used for work space follow the standard 72-byte save area addressed by register 13.

The environment descriptor block is 48 bytes and contains the information shown in the following table.

Table 13.1 Environment Descriptor Block


Offset(decimal) Length(bytes)   Description

                                      
                                                                
   0               2               halfword length of the block                    
                                   (48) (decimal)                         
                                                                
   2               8               environment name (blank padded),                 
                                   for example, MVS/SP,VM/SP                 
                                                                
   10              1               environment version number (integer)                 
                                                                
   11              1               environment release number (integer)                
                                                                
   12              1               environment modification level (integer)                
                                                                
   13              1               submodification level,if appropriate                 
                                                                
   14              8               subenvironment name, if applicable;                
                                   for example, TSO--a subenvironment of MVS                  
                                                                
   22              1               subenvironment version number (integer)                
                                                                
   23              1               subenvironment release number (integer)                
                                                                
   24              1               subenvironment modification level (integer)                   
                                                                
   25              1               subenvironment submodification level               
                                                                
   26              1               environment number (see ENVDB DSECT for codes)                 
                                                                
   27              1               supported function flags. These flags       
                                   are set by L$UENVR to show whether           
                                   specific functions are available.

   28              1               XA support flags X'80=XA architecture,                   
                                   X'40'=PSW in XA format                
                                                                
   29              1               time sharing flags X'80'= program                 
                                   executing interactively                   
                                                                
   30              1               system function flags: X'80' = dynamic                    
                                   allocation  supported X'40' = SPIE                  
                                   or ESPIE supported X'20'=ESTAE or                  
                                   ABNEXIT supported                   
                                                                
   31              18              reserved                     
 

Any undefined or meaningless items in the environment descriptor block should be stored as 0s. If you modify L$UENVR, a new set of information is created for the special environment in which compiled programs will run.

Note: If you modify L$UENVR, do not change the information in the descriptor block for the standard systems (MVS and CMS) because the library may malfunction.

Caution

The information may be unavailable or incorrect unless the L$UENVR source code is examined and changed as necessary by a systems programmer familiar with the local operating systems.

Local operating system conventions or modifications may cause these functions to return incorrect or misleading values. Contact your SAS Software Representative for C Compiler products to confirm that L$UENVR provides the information required.

Function Descriptions

Descriptions of each system interface function follow. Each description includes a synopsis, a description, discussions of return values and portability issues, and an example. Also, errors, cautions, diagnostics, implementation details, and usage notes are included if appropriate.

envlevel -- Get Subenvironment Information

SYNOPSIS

 #include <lclib.h>

 char *envlevel(void);
 

DESCRIPTION

envlevel gets the subenvironment version number, release number, modification level, and submodification level. This information is stored in bytes 22 through 25 of the environment descriptor block. If no subenvironment is active, envlevel contains the same information as syslevel.

A null character is stored for any piece of information that is not meaningful on the current system.

RETURN VALUE

envlevel returns a pointer to a character sequence containing four pieces of information: subenvironment version number, release number, modification level, and submodification level.

The type of information returned by envlevel is site-dependent. For example, under TSO/E, the release number field contains the release of TSO/E. Under CMS, it typically contains the CMS release number. None of the other bytes are meaningful.

CAUTION

See "Caution" under The L$UENVR Routine .

EXAMPLE

This example formats and prints the envname/envlevel and sysname/syslevel information.
 #include <stdio.h>
 #include <string.h>
 #include <ctype.h>
 #include <lclib.h>

 main()
 {
    char  *sysptr, *envptr, sysstr[16], envstr[16];

    envptr = envlevel();
    sprintf(envstr, "%02x %02x %02x %02x",
            *envptr, *(envptr + 1), *(envptr + 2), *(envptr + 3));
    printf("Envname/Envlevel  =  %-8s %s\n", envname(), envstr);

    sysptr = syslevel();
    sprintf(sysstr, "%02x %02x %02x %02x",
            *sysptr, *(sysptr + 1), *(sysptr + 2), *(sysptr + 3));
    printf("Sysname/Syslevel  =  %-8s %s\n", sysname(), sysstr);
 }
 

envname -- Get Subenvironment Name

SYNOPSIS

 #include <lclib.h>

 char *envname(void);
 

DESCRIPTION

envname gets the subenvironment name stored in bytes 14 through 21 of the environment descriptor block.

RETURN VALUE

envname returns a pointer to the string containing the subenvironment name. Under MVS, if the program is running under TSO, envname returns either "TSO" or "TSO/E". Under CMS, envname returns "CMS". For an OpenEdition child process, or a program called with exec-linkage, envname returns "OpenMVS", even if invoked under TSO.

If no special subenvironment is active, envname returns the same information as sysname.

CAUTION

See "Caution" under The L$UENVR Routine .

EXAMPLE

 #include <lclib.h>
 #include <stdlib.h>
 #include <lcstring.h>

    if (memcmp(envname(), "TSO", 3) == 0)
       system("TSO: DELETE TEMP.FILE");
    else if (memcmp(envname(),"CMS", 3) == 0)
       system("CMS: ERASE TEMP FILE A");
    else if (memcmp(envname(), "OpenMVS", 7) == 0)
       system("sh: rm temp.file");
    .
    .
    .
 
envname is also illustrated in the example for envlevel.

intractv -- Indicate Interactive Execution

SYNOPSIS

 #include <lclib.h>

 int intractv(void);
 

DESCRIPTION

intractv indicates whether a program is executing interactively. The time-sharing flag is stored in byte 29 of the environment descriptor block.

Execution under MVS-batch, including execution of the TSO terminal monitor program, is not interactive. TSO executes programs interactively. CMS execution is normally interactive. However, if there is no interactive console associated with the executing program, a C program under CMS is considered noninteractive. Consult the systems programmer at your local site to determine under what conditions a program is considered noninteractive for CMS.

RETURN VALUE

Except for OpenEdition programs called with exec-linkage, intractv returns a nonzero integer if a program is executing interactively; otherwise, it returns 0.

For a program called with exec-linkage, intractv returns whether or not a TSO terminal is accessible. Therefore, in most cases of exec-linkage, intractv returns 0; however, for a program invoked via the oeattach or oeattache function under TSO, interactive returns nonzero.

CAUTION

See "Caution" under The L$UENVR Routine .

EXAMPLE

 #include <lclib.h>
 #include <stdio.h>
 #include <string.h>

 FILE *in_file;
 char *sys_file;

       /* Issue prompt only if running interactively.           */ 
    if (intractv()) {
       printf("Enter data:");
       fflush(stdout);

       /* Perform other functions to read data in interactively.*/ 
       .
       .
       .
    }
 
       /* Otherwise, obtain input from DATA file.               */ 
    else {
       if (memcmp(sysname(), "CMS", 3) == 0)
          sys_file = "DATA FILE A1";
       else
          sys_file = "SYSIN";
       in_file = fopen(sys_file, "r");
    }
 

syslevel -- Get Operating System Information

SYNOPSIS

 #include <lclib.h>

 char *syslevel(void);
 

DESCRIPTION

syslevel gets the operating system version number, release number, modification level, and submodification level stored in bytes 10 through 13 of the environment descriptor block.

A null character is stored for any piece of information that is not meaningful on the current system.

RETURN VALUE

syslevel returns a pointer to the character sequence containing the operating system version number, release number, modification level, and submodification level.

The type of information returned by syslevel is site-dependent. An example of typical information provided under MVS is the version and release number of MVS. Under CMS, only the release number is meaningful; this is the release of the VM control program (CP).

CAUTION

See "Caution" under The L$UENVR Routine .

EXAMPLE

syslevel is illustrated in the example for envlevel.

sysname -- Get Operating System Name

SYNOPSIS

 #include <lclib.h>

 char *sysname(void);
 

DESCRIPTION

sysname gets the operating system name from bytes 2 through 9 in the environment descriptor block.

RETURN VALUE

sysname returns a pointer to a string containing the operating system name.

Under MVS, the string returned by sysname is "VS1", "MVS", or "MVS/SP". Under CMS, "VM/SP", "VM/XA SP", "VM/HPO", "VM/XA", or "VM/ESA" is returned.

CAUTION

See "Caution" under The L$UENVR Routine .

EXAMPLE

 #include <lclib.h>
 #include <string.h>

 char *pathname;

    if (strcmp(sysname(), "VM/SP") == 0)
       pathname = "PRINTER";
    else
       pathname = "SYSPRINT";
    .
    .
    .
 
sysname is also illustrated in the example for envlevel.

RELATED FUNCTIONS

uname


Copyright (c) 1998 SAS Institute Inc. Cary, NC, USA. All rights reserved.