Used Environment Variables

Environment variables can be managed via the operating system or via the FLAM4 configuration. The latter can be managed with the built-in functions SETENV, GETENV and DELENV. To list the current state of all usable environment variables the built-in function LSTENV can be used. For help messages for each usable environment variable please use HLPENV. There are also some platform-specific mechanisms that can be used to set environment variables:

Linux, Windows, USS and other Unix-like OS

Environment variables are read from the file .stdenv in the current working directory or the user's home directory. The file in the home directory is only considered if the file does not exist in the working directory or cannot be read.

Mainframe systems

DD:STDENV or the data set name &SYSUID..STDENV can alternatively be used to set environment variables.

The STDENV file allows to define the FLAM4_CONFIG_FILE, FLAM4_DEFAULT_OWNER_ID, LANG and other environment variables in JCL.

Example with a z/OS DD name allocation:

 //STDENV   DD *
 FLAM4_CONFIG_FILE=GLOBAL.FLAM4.CONFIG
 LANG=de_DE.IBM-1141
 HOME=/u/hugo
 USER=hugo
 ENVID=T
 /*

The definition of the LANG variable outside of the program configuration file is recommended, so that the system character set is defined in each situation. The program configuration filename is used as is. No placeholder substitutions (e.g. <USER>) are possible.

It might be useful to have a dedicated environment per user on mainframes. In such a case, it makes sense to define the environment in a dedicated file for each user.

 //STDENV   DD DSN=USER.ENVIR(&SYSUID.), DSP=SHR

Since z/OSv2r1 you can also use exported JCL symbols like environment variables. The exported JCL symbols have lower priority than the same environment variable. The service CEEGTJS is called dynamically and the language environment must be in the STEPLIB concatenation to use it. Additionally, all z/OS system symbols can be used in the string replacement (<&LDAY>). The environment variables have the highest priority, followed by the exported JCL symbols. System symbols have the lowest priority. If the variable name is not found, then no replacement is done and the angle brackets are kept in place.

 //E0       EXPORT SYMLIST=*
 //S1       SET    BLKSIZE=27886
 //S3       SET    LRECL=128
Default record format

For z/OS, the default record format and record length for non-existent output files is recfm=VB, lrecl=516. An attempt is made to open an existing file with recfm=* for overwriting (DISP=OLD). If this fails, another attempt is made with recfm=VB, lrecl=516 to write a new file (DISP=NEW). The environment variable CLP_DEFAULT_DCB can be used to change this default file mode string.

See "Keyword Parameters for File Mode" for fopen() in z/OS XL C/C++ Runtime Library Reference for more information and for the correct syntax. Beside recfm with a valid record format (not + or *) and lrecl, the space parameter can be set. All other file mode parameters are managed by CLP.

Property file vs. environment variables

Beside all the environment variables managed by CLE it is possible to set all properties as environment variables to override the hard coded default values with CLP. If a property is defined as environment variable and in a property file, then the value in the property file overrides the setting in the environment. The environment variable name for each property is built by the rules below:

To get a list and help for all properties please use the built-in function GENPROP to generate property files. The properties can be defined per owner, per program and globally. The owner-specific definition overrides the program specific definition and the program-specific definition overrides the global definition.

Examples:

CONV_READ_TEXT_ENL2LF=OFF #in general the 0x15 to 0x25 conversion is off#
HUGO_FLCL_CONV_READ_TEXT_ENL2LF=ON # for owner 'hugo' the conversion is on#

The value string behind the sign (including the comment) will be used as supplement for the command line processor. Aliases are not supported in this case. You can only define properties for the main argument. If a string must be enclosed with apostrophe, please don't use double quotation marks because these are used in addition if a new property file is built based on the environment settings.

FLCL_ICNV_FROM='IBM-1141'         # this is the best solution 
FLCL_ICNV_TO=UTF-8                # "UTF-8" could result in errors

See Appendix Properties for the current property file content.

Usable environment variables

Below you can find the list of static environment variables.

Beside the static environment variables there a lot of dynamic formed environment variables supported.

FLAM specific handling of environment variables

On platforms (mainly mainframe systems) where system symbols are available, some of the environment variables can be pre-defined over corresponding system variables. See install.txt or use built-in function HLPENV (in parenthesis the corresponding system symbols are listed).

Trailing whitespace is removed from variable values before being used. A system symbol must start with & or an alphabetic character followed by alphanumeric characters.

Boolean environment variables

Many environment variables accept a boolean value that enables or disables a feature. Boolean values are matched case-insensitively. The following values are accepted:

All three forms are equivalent and can be written in any combination of upper and lower case (e.g. on, Yes, y all enable a feature). The accepted values are listed in the help for each variable (use built-in function HLPENV for details).

Considerations for the LANG variable

The environment variable LANG is also used on EBCDIC systems to interpret several syntax characters correctly, which depend on the codepage. See chapter special EBCDIC code page support for how the CCSID can be defined. It is important to set this variable to the correct value on EBCDIC systems. If this environment variable is not set, files and literals are interpreted in IBM-1047 on z/OS and USS. If you use another CCSID for entry, you must define the environment variable LANG to enable correct parsing for strings that contain special characters like ~. We recommend defining the corresponding system variables (&FLANGLC, &FLANGCC and &FLANGCS) via SYS1.PARMLIB(IEASYMxx) on z/OS (see also install.txt). These three system symbols are used to build the environment variable LANG based on the string below:

    "&FLANGLC_&FLANGCC.&FLANGCS"

For example with the definitions below

   SYMDEF(&FLANGLC='de')
   SYMDEF(&FLANGCC='DE')
   SYMDEF(&FLANGCS='IBM1141')

the environment variable below is defined.

   LANG=de_DE.IBM1141

The language code (de) is important for correctly selecting the default CCSID if an ASCII code page was detected.

Considerations for the ENVID variable

The ENVID variable is normally one character to separate test and production environments. On z/OS the default is simply the first letter of system symbol &SYSCLONE or if not defined (on all platforms) 'T' for test.

Considerations for the FLAM4MF variable family (only Microfocus Enterprise Server)

The variable FLAM4MF and (if needed) FLAM4MF_TRACEFILE should be set in the environment of the Microfocus Enterprise Server instance where the FLAM or FLUC record interfaces are used. To define static and dynamic system variables, the FLAM4MF_STATIC/DYNAMIC_SYSVAR environment variable can be used to read the system variables to the environment. The second file was mainly introduce for the MF-EDZ JCL user exit, which can be used to provide the dynamic symbols like JOBNAME as keyword=value pair as the dynamic file. All the files read to build the environment undergo automatic ASCII and EBCDIC detection. A semicolon can be used to mark the end of a keyword-value pair (an inline FB80 encoding in JCL on EDZ does not contain newline characters).

To undefine an environment variable, there must be no characters behind the equal sign. To replace a variable with nothing upon use, the environment variable must be set to one or more whitespace character(s). Trailing whitespace is removed from the value string, so a value which contains only whitespace characters will result in an empty string upon substitution.

For Micro Focus EDZ environments, the DD name SYSVAR is supported to define system variables. The function used to read the keyword=value pairs automatically detects if EBCDIC is used (character > 0x80) and converts the lines automatically to the local character set.

Other used system symbols on z/OS

The LE-less part of FLAM can only use system symbols. Below is a list of available variables:

*&FLREUCEE - Activate reuse of language environment in FLAM ZEDC support *&FLOGQL1 - First qualifier to specify the FLAM usage log stream name *&FLOGQL2 - Second qualifier to specify the FLAM usage log stream name *&FLOGQL3 - Third qualifier to specify the FLAM usage log stream name

See install.txt for z/OS for more information.

Other ways to define environment variables

On Unix platforms the '/etc/profile' or .bashrc or command line can be used to export environment variables. On windows under system control global or user specific environment variables can be defined. On z/OS additional the DD:CEEOPTS can be used to define environment variables, see example for ZEDC usage below:

//CEEOPTS  DD *
ENVAR("_HZC_COMPRESSION_METHOD=software,
       _HZC_DEFLATE_THRESHOLD=1,
       _HZC_INFLATE_THRESHOLD=1")
/*

Additional with global relevance the environment variables can also be defined over the PARMLIB member CEEPRMxx on z/OS, see examples for all 3 environments below:

CEECOPT(ALL31(ON), ENVAR('TZ=EST5EDT') )
CEEDOPT(ALL31(ON), ENVAR('TZ=EST5EDT') )
CELQDOPT(ALL31(ON), ENVAR('TZ=EST5EDT') )

from 'Specifying environment variables' of IBM z/OS documentation.