Environment Variables

The Environment Variable Concept

The ISO/ANSI C standard requires that a C library include the getenv function, which retrieves the value of a named environment variable. Both the name and value are character strings. The ISO/ANSI C standard does not describe the meaning of environment variables, how they might be set, or even whether it is possible to define them. However, the getenv function should be similar to the getenv function under the UNIX environment, and if the host operating system has a facility similar to UNIX environment variables, getenv should provide a means of accessing that facility.

These properties are fundamental to the behavior of UNIX environment variables:

Environment variables can be set and tested by shell commands. For example,
```
 export HOME=/u/george
 
```
A program can modify its own environment by adding or replacing variables; however, these changes are local to the program.
When one program calls another (for example, using the system function), the calling program's environment variables are passed to the called program. The communication is one way; that is, the caller passes the environment to the called program, but any changes the called program makes to its environment are not available to the caller.
Special forms of the exec function enable a program to pass control to another program with a specially built environment.
Because all running programs have a shell as an ancestor, the environment maintained by the shell is inherited by all of a session's environments, subject to modification by specific programs.

Secondary properties of UNIX environment variables include

Both environment variable names and environment variable values are case sensitive and have no practical length limits.
The shell only permits environment variable names containing alphanumeric characters and underscores. (However, C programs can have defined variables not described by this rule.) By convention, environment variables meaningful to the system are entirely in uppercase, leaving lowercase names for individual applications.
Each program has an external variable, environ, which addresses the list of environment variables. Many older programs access environ for environmental information rather than calling getenv.
The only portable way of modifying the environment is by using environ. Some versions of the UNIX environment implement functions like putenv to modify the environment, but these functions are not portable.

The most difficult aspect of implementing environment variables under the MVS and CMS operating systems is that native methods for invoking other programs (ATTACH, CMSCALL) do not provide for a list of variables. For this reason, the SAS/C environment variable implementations provide somewhat different semantics in which variables are shared by all programs in a session, regardless of how the programs are invoked. The implementation was modeled after CMS global variables (also called GLOBALV variables) so that C environment variables could be used as a way of accessing and modifying these variables under CMS. This implementation is adequate for porting many UNIX programs that use environment variables, in particular, for all programs that do not modify their own environment. SAS/C software implements environment variables similar to GLOBALV under CMS, TSO, and CICS. Also, for programs running under the OpenEdition shell, the environment variable implementation complies with POSIX.1 and traditional UNIX usage.

CMS Global Variables

CMS global variables are similar to C environment variables but have many differences in the details. Some of the differences are

Global variables can be manipulated from the CMS command line using the GLOBALV command.
Global variables are shared between all programs in a session. Changes made by one program are visible to all other programs.
There are several forms of global variables: storage, session, and lasting. Storage variables retain their values only until the next IPL command of CMS; session variables last until the end of a session; lasting variables keep their values across CMS sessions.
Global variables are initialized from files with known names and formats. By editing the files, you can change the initial values used for global variables the next time you invoke CMS.
Global variables are organized into groups of related variables with a default group named UNNAMED.
Environment variable names are translated to uppercase letters automatically. Both names and values are limited to 255 characters.
CMS does not provide an interface for a program to determine the names of all defined global variables.

SAS/C Environment Variables

SAS/C combines elements of UNIX environment variables and CMS global variables in its own environment variable implementation. The interface has been made as portable as is reasonable, but there is still a large amount of system dependency in this implementation. The most important extensions are environment variable scopes and environment variable groups.

Environment Variable Scopes

SAS/C defines three scopes of environment variables: program, external, and permanent.

Program-scope environment variables

are most similar to UNIX environment variables. They are strictly local to a program; thus, changes to a program-scope variable are not visible to any other program. Program-scope environment variables are not passed to invoked programs unless one of the OpenEdition exec functions is used.

Program-scope environment variables are set in one of two ways. First, they may be specified on the program's command line as described in Chapter 8, "Run-Time Argument Processing," in the SAS/C Compiler and Library User's Guide, Fourth Edition . Or, for programs invoked by the OpenEdition exec system call, they may be passed by the caller of exec.

There are no limits on the size of program scope variable names or values. The names are case insensitive; that is, home, Home, and HOME are considered to identify the same variable. (See OpenEdition Considerations for an exception.)

External-Scope Environment Variables

correspond to CMS storage GLOBALV variables. They can be set outside of a program using a system command such as GLOBALV for CMS or PUTENV for TSO. Any changes made by a program are visible to other programs, but all such changes are lost at the end of a session. External-scope environment variables are case insensitive and may have length limitations imposed by the host system.

Permanent-Scope Environment Variables

correspond to CMS lasting GLOBALV variables. Their behavior is the same as external-scope variables except that changes to these variables persist to future sessions.

SAS/C implements program-scope environment variables in all environments. It implements external- and permanent-scope environment variables under TSO, CMS, and CICS.

When a program calls the getenv function to retrieve the value of an environment variable, the scopes are searched in order. That is, first the program-scope variables are checked, then the external-scope variables, and then the permanent-scope variables. This enables you or the program to override the usual value with a more temporary value for the duration of a program or session.

When a program calls the putenv or setenv function to modify or add an environment variable, the change is made at program scope unless some other scope is explicitly specified. Thus, a portable program that changes its own environment will not affect any other program. Scopes are indicated to putenv by a prefix on the environment variable name followed by a colon, for example, external:TZ. Because colons are not commonly used in UNIX environment variable names, this extension has little effect on portability.

Environment Variable Groups

Another extension in the SAS/C environment variable implementation supports group names for external- and permanent-scope variables. If an external- or permanent-scope environment variable name contains a period, the portion of the name before the period is considered to be the group name. For example, the variable name LC370.MACLIBS defines the variable MACLIBS in the group LC370. An environment variable without a group name is considered to have a default group name of CENV.

CMS group names are limited to eight characters. For this reason, in certain cases, environment variable names containing periods may behave differently in different scopes. For example, the two environment variables TOOLONGFORME.NAME and TOOLONGFORANYONE.NAME refer to the same variable for an external scope but different variables for a program scope. This should not be a problem in normal usage.

Because environment variables in traditional UNIX usage do not normally contain periods, this extension does not ordinarily cause portability problems.

OpenEdition Considerations

The POSIX standards implemented by OpenEdition make certain requirements on the C library that are not compatible with the SAS/C environment variable implementation defined in the previous section. These requirements are

POSIX.1 requires that environment variable names be case sensitive. For compatibility with CMS, SAS/C treats environment variable names as case insensitive. This problem is handled in two ways:
- For programs called by the shell (or more generally by any exec function), program-scope environment variables are considered case sensitive. For all other programs, these names remain case insensitive for compatibility with CMS and previous releases.
- For non-exec-linkage programs, the original form of the variable is preserved even though the case of an environment variable is not considered significant. (That is, the variable MyName is stored as MyName, not as myname or MYNAME even though these are all names for the same variable.) If a program calls exec to pass control to an exec-linkage program, the called program receives the environment variables with their original case information intact.
POSIX.1 requires that all environment variables be accessible by the external variable environ. SAS/C now makes the program-scope environment variables accessible by environ for all programs. However, variables of other scopes are never accessible by environ. Similarly, when an exec function is called, only the program-scope environment variables are passed to the called program.
POSIX.1 requires that it be possible to modify the environment variable list by manipulating environ and the list it addresses. SAS/C supports this modification but does not recommend it. The POSIX.1a function setenv should be used to update the environment whenever possible. In particular, you should not use both setenv and update environ simultaneously. This is a restriction stated by the POSIX.1a draft standard.
The POSIX use of the environ variable is not strictly ISO/ANSI conforming because environ is in the name space reserved by ISO/ANSI for users. For this reason, the name environ is accessible only to programs compiled with the posix option. Additionally, the name environ is valid only in the main load module of a program. To access environ from another load module, declare
```
 extern char ***_environ;
 
```
and use *_environ in place of environ. This produces correct results in any load module but is not portable. _environ can be used in programs that are not compiled with the posix option.
SAS/C supports the POSIX.1a clearenv function, which removes all environment variables. It has an effect only on program-scope variables. That is, external- and permanent-scope variables are unaffected.

Environment Variables under CMS

External- and permanent-scope environment variables are implemented as CMS global and lasting variables under CMS. CMS limits the names and values of these variables to 255 characters. See the CMS Command Reference for more information on GLOBALV.

Environment Variables under TSO

Under TSO, environment variables are implemented as a SAS/C extension. SAS/C provides GETENV and PUTENV TSO commands enabling you to inspect and modify environment variables without writing a C program to do so. These commands are described in Chapter 6, "Executing C Programs," in the SAS/C Compiler and Library User's Guide, Fourth Edition .

Note: Under CMS, when you update a permanent-scope environment variable, the new value is also assigned to the external-scope variable of the same name.

Environment variable names are limited under TSO to 254 characters, and values are limited to 255 characters.

TSO Technical Notes for Environment Variables

This section describes technical aspects of the SAS/C TSO environment variable implementation.

Accessing the Environment Variable File

The following strategy is used to locate the PERMANENT environment variable file:

If the DDname C@ENV is defined, the file allocated to that DDname is used. If this fails and TSO is running in batch, no attempt is made to allocate a file and no PERMANENT environment variables are assumed to exist.
If the DDname C@ENV is not defined, the data set userid.C@ENV.PERM is allocated to the DDname. Note that the first data set qualifier is always the userid even when it differs from the user's default TSO prefix.
If the data set userid.C@ENV.PERM does not exist, it is created if the request is a putenv function with a PERMANENT scope. If the request is a getenv function, the file is not created.

Environment Variable File Format

Each line of userid.C@ENV.PERM either defines an environment variable or a group. The variables of each group are defined after the group definition. Variables defined before the first group are part of the default group CENV. A line of the form =group defines a group, and a line of the form var=value defines a variable. If var=value uses more than 254 characters, it takes up two lines in the file and is split at the equal sign.

Assume that the content of a userid.C@ENV.PERM file is as follows:

 NAME=Fred
 MISC.AVERYLONGNAME= averylongvalue

In this example, two PERMANENT environment variables are defined: NAME has a value of Fred, and MISC.AVERYLONGNAME has a value of averylongvalue.

Environment Variable Implementation

This information is provided for TSO systems programmers. Most users will not need this information.

TSO environment variables are kept in subpool 78 memory for the life of the session. They are located through an anchor field at offset 260 from the RLGB (relogon buffer), which is a field reserved by IBM. Before using this field, the C environment variable routines check the field to see if it is already being used by either IBM or the site. If the field is unavailable, then EXTERNAL environment variables are also stored in a file, rather than in memory. In this case, access is slower because the variables are not in memory.

If the DDname T@ENV is allocated, the DDname is used for EXTERNAL environment variables. If T@ENV is not allocated, a temporary data set is created and allocated to this DDname.

The TSO environment variable implementation stores environment variables in shared subpool 78 storage. If a task that does not share subpool 78 with the rest of TSO invokes putenv, the putenv function fails. Also, use of setenv by such tasks may involve substantial extra processing.

Environment Variables under MVS Batch

Only program-scope environment variables are supported under MVS batch, except when you run the TSO terminal monitor program. The argument redirection facility described in Chapter 8, "Run-Time Argument Processing," in the SAS/C Compiler and Library User's Guide, Fourth Edition enables you to define as many environment variables as you require without concern for the 100-character limit on the JCL PARM string.

Environment Variables under CICS

Environment Variable Implementation

Nonprogram-scope environment variables are stored in a temporary storage queue, which exists until it is manually deleted or the CICS region (or temporary storage) is cold started. Thus, the lifetime of a queue can vary considerably. Some sites cold start their regions every night. If CICS crashes during the day, it could also be cold started at that time. Generally, environment variables persist for the duration of a session connection (logon to logoff), but they could persist between connections.

By default, the library uses the VTAM netname as a queue name and only accesses the first record in the queue. The queue name is set in the user-replaceable routine L$UEVQN. This routine enables a site to use some other scheme for assigning a queue name, including the option of sharing a single queue between all programs. See the source code in the SASC.SOURCE data set (under MVS) or the LSU MACLIB (under CMS) for complete details.

Because Temporary Storage is a shared facility on CICS, some potential problems exist with the technique of using the VTAM netname as a queue name. Some of those problems are:

VTAM netnames can be reused on some systems so that one user could wind up with another user's environment variables.
Someone other than you might logon to the terminal where you were sitting; they would then get your environment variables.
A user logging on might access the environment variables defined by the previous user of the terminal.

Scope and Size of CICS Environment Variables

Only program- and external-scope environment variables are supported under CICS (that is, there is no support for permanent or lasting environment variables). Note that for CICS, session scope is considered to be the same as external or storage scope.

Environment variable names are limited in CICS to 254 characters, and values are limited to 255 characters.

SAS/C Supplied Transactions to Inspect and Modify Environment Variables

SAS/C provides a transaction that enables you to inspect and modify environment variables without writing a program to do so. You invoke the transaction to set the environment variables of interest; then, in a separate step, you invoke your application transaction. See the SAS/C CICS User's Guide, Second Edition for more information.