### Used Environment Variables

Environment variables can be managed via the operating system or via the FLCL 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 `FLCL_CONFIG_FILE`, `FLCL_DEFAULT_OWNER_ID`, `LANG` and other environment variables in JCL.

Example with a z/OS DD name allocation:

     //STDENV   DD *
     FLCL_CONFIG_FILE=GLOBAL.FLCL.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:

- convert all characters to upper case
- replace all dots (`.`) by underline (`_`)

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.

- LANG (&FLANGLC_&FLANGCC.&FLANGCS) - The default language and CCSID/encoding string for this platform (Format: de_DE.UTF-8 or de_DE.IBM-1141)
- HOME - To determine the home directory on UNIX/WIN
- USER - To determine the current user id on UNIX/WIN
- CUSER - To determine the current user in upper case
- Cuser - To determine the current user in title case
- cuser - To determine the current user in lower case
- SYSUID - To determine the current user id on z/OS
- ENVID (&FLENVID) - The current environment qualifier for key label templates (default value is 'T' or the first valid letter of &SYSCLONE on z/OS)
- OWNERID - Used for current owner if not already defined (used in key label templates (can also be used in file names))
- HOSTNAME - Current host name
- MAILADDR - The email address used as sender for outgoing emails (only relevant on z/OS with SYSOUT format set to MAIL)
- CLE_QUIET - Disables the normal log output of the command line executer (must set to YES or ON)
  - YES - Yes, do it (same as ON)
  - ON - Activate it (same as YES)
  - NO - No, don't do it (same as OFF)
  - OFF - Deactivate it (same as NO)
- CLE_SILENT - Disables log and errors messages of the command line executer (must set to YES or ON)
  - YES - Yes, do it (same as ON)
  - ON - Activate it (same as YES)
  - NO - No, don't do it (same as OFF)
  - OFF - Deactivate it (same as NO)
- CLP_NOW - The current point in time used for predefined constants (0tYYYY/MM/DD.HH:MM:SS)
- CLP_STRING_CCSID - CCSID used for interpretation of critical punctuation character on EBCDIC systems (default is taken from LANG)
- CLP_DEFAULT_DCB - The default record format and record length in C file mode format (default is 'recfm=VB, lrecl=516' only for z/OS)
- CLP_SYMTAB_STATISTICS - Print symbol table statistics to STDERR stream at close (must set to YES or ON)
  - YES - Yes, do it (same as ON)
  - ON - Activate it (same as YES)
  - NO - No, don't do it (same as OFF)
  - OFF - Deactivate it (same as NO)
- CLP_MALLOC_STATISTICS - Print memory allocation statistics to STDERR stream at close (must set to YES or ON)
  - YES - Yes, do it (same as ON)
  - ON - Activate it (same as YES)
  - NO - No, don't do it (same as OFF)
  - OFF - Deactivate it (same as NO)
- FL_PLATFORM - Platform definition (WIN/UNX/MAC/ZOS/USS/BS2[.B/.L]) for emulation at read or write operations
  - WIN - Choose Windows as platform (CRLF)
  - UNX - Choose Unix derivative as platform (LF)
  - ZOS - Choose ZOS as platform (NL)
  - USS - Choose USS of ZOS as platform (NL)
  - VSE - Choose VSE as platform (NL)
  - BS2 - Choose BS2000-OSD as platform (NL)
  - MAC - Choose MAC as platform (CR)
- FL_DEFAULT_ASCII_CCSID - Default CCSID for ASCII character sets (if ASCII machine and LANG, then default is taken from LANG else default is 'ISO-8859-1'))
- FL_DEFAULT_EBCDIC_CCSID - Default CCSID for EBCDIC character sets (if EBCDIC machine and LANG, then default is taken from LANG else default is 'IBM-1047'))
- FL_PGP_PREF_SYMALG_AES128 (&FLPA128) - Invert order of preferred symmetric algorithms from AES256/192/128 to AES128/192/256 in PGP certificates
  - YES - Yes, do it (same as ON)
  - ON - Activate it (same as YES)
  - NO - No, don't do it (same as OFF)
  - OFF - Deactivate it (same as NO)
- FL_ALLOW_LOW_ENTROPY - If defined and no source of entropy is available, the random number generate is seeded with a low entropy which may result in weak encryption keys
- FL_DEFAULT_CHAR_MODE (&FLCHARM) - Default error handling if character not available in target character set [STOP]
  - STOP - Stop at the first non-convertible character
  - IGNORE - Ignore non-convertible characters
  - SUBSTITUTE - Substitute non-convertible characters
  - IDENTITY - Copy non-convertible characters (supported only for single byte conversions)
  - TRANSLIT - Activate ICONV transliteration and ignore the rest (MODE=IGNORE SYSTAB=ICONV)
- FL_DEFAULT_PGPCCAPARA - Default PGP IBM-CCA (ICSF) parameter (normally not required, only profile and pin (if applicable) or trust store name)
- FL_DEFAULT_PGPP11PARA - Default PGP PKCS#11 parameter (LIB=/usr/lib/libsofthsm2,PIN=f'pkcs11.pin')
- FL_DEFAULT_PGPRNGPARA - Default PGP key ring parameter (pub='pubrng.pgp',sec='secrng.pgp',pass=f'keyring.pwd')
- FL_DEFAULT_CCALIB - Default path/name of CCA library (not required for ICSF)
- FL_DEFAULT_CCAPKDS - Default path/name of CCA public key data set
- FL_DEFAULT_P11LIB - Default path/name of PKCS#11 library
- FL_DEFAULT_P11PIN - Default PIN/passphrase for PKCS#11 token (it is not recommended to use this if authentication is required)
- FL_DEFAULT_P11SLOT - Default PKCS#11 slot number
- FL_DEFAULT_RNGPUBFIL - Default public key file for key ring implementation
- FL_DEFAULT_RNGSECFIL - Default secret key file for key ring implementation
- FL_DEFAULT_RNGPASSWD - Default password for key ring implementation (it is not recommended to use this if authentication is required)
- FL_INFO_BLOCK_SIZE - Set a custom block size for the INFO command (useful mainly for PGP files)
- FL_USAGE_SYSLOG_IDENT (&FLOGIDT) - Activate usage logging to SYSLOG on each platform (in addition to the usage log stream on z/OS)
- FL_DEACTIVATE_HW_CRYPTO_ACCELERATION - Deactivate hardware acceleration for cryptographic operations (enforce use of software implementation)
- FL_PRIMARY_SPACE_TRK (&FLPRISP) - Default primary space in tracks (only relevant on mainframes, default is 600)
- FL_SECONDARY_SPACE_TRK (&FLSECSP) - Default secondary space in tracks (only relevant on mainframes, default is 1200)
- FL_DIRECTORY_BLOCKS (&FLDIRBL) - Default directory blocks (only relevant on mainframes, default is 45)
- FL_ZEDC_SUPPORT (&FLZEDC) - Controls use of RCF1951 (GZIP) compression in FLAM4 ADC modules (ON, OFF, AUTO(default), threshold (nnn) in percent)
- FL_SSH_HOME_DIR - Directory containing SSH key files and known_hosts file (/home/user/.ssh)
- FL_GZ_EXPANSION_FACTOR (&FLGZEXP) - Expansion factor for GZIP decompression (default is 5)
- FL_GZ_COMPRESSION_FACTOR (&FLGZCMP) - Compression factor for GZIP compression (default is 2)
- FL_BZ_EXPANSION_FACTOR (&FLBZEXP) - Expansion factor for BZIP2 decompression (default is 6)
- FL_BZ_COMPRESSION_FACTOR (&FLBZCMP) - Compression factor for BZIP2 compression (default is 2)
- FL_XZ_EXPANSION_FACTOR (&FLXZEXP) - Expansion factor for XZ decompression (default is 10)
- FL_XZ_COMPRESSION_FACTOR (&FLXZCMP) - Compression factor for XZ compression (default is 2)
- FL_ZS_EXPANSION_FACTOR (&FLZSEXP) - Expansion factor for ZSTD decompression (default is 10)
- FL_ZS_COMPRESSION_FACTOR (&FLSZCMP) - Compression factor for ZSTD compression (default is 2)
- FL_KEY_EXPIRE_WARN_DAYS (&FLKEYWD) - Amount of days to warn before a key will expire (default is 90 (3 months))
- FL_RETURN_IF_LOG_WARNING (&FLRLOGW) - If set to OFF, the completion code 0 is returned instead of 1 if a relevant warning is written to the log
  - YES - Yes, do it (same as ON)
  - ON - Activate it (same as YES)
  - NO - No, don't do it (same as OFF)
  - OFF - Deactivate it (same as NO)
- FL_FAVE_LIBRARY - Set default library for anti virus scanning (default is 'libfave')
- FL_FAVE_FUNCTION - Set default function for anti virus scanning (default is 'CLAMAVC')
- FL_FAVE_PARAMETER - Set default parameter for anti virus scanning (default is 'clamav.daemon:3310')
- FL_CLAMAV_DAEMON - Set default communication parameter for ClamAV client (default is 'clamav.daemon:3310:10')
- FL_AVSCAN_READ - If defined, anti virus scanning when reading is activated (corresponding default values must be defined)
- FL_AVSCAN_WRITE - If defined, anti virus scanning when writing is activated (corresponding default values must be defined)
- FL_AVSCAN_COMPRESS - If defined, anti virus scanning is done on a compressed GZIP data stream (must be supported by service provider)
- FL_SYSOUT_MAIL_CLASS (&FLSOMC) - Default class for SYSOUT allocation if FORMAT.MAIL() is used (only on z/OS)
- FL_SYSOUT_MAIL_WRITER (&FLSOMW) - Default program for SYSOUT allocation if FORMAT.MAIL() is used (only on z/OS)
- FL_LITERAL_CACHE_SIZE (&FLITCS) - Size of the hash table used (by power of 2) for the literal cache (8>=x<=20 (256 to 1.048.576 entries))
- FL_RECORD_FORMAT_MAPPING (&FLRECFM) - If this variable is not set to DATATYPE (is the default), records with length field (RECF=VAR) are used
  - DATATYPE - Binary data as binary (RECF=BIN), Text as text (RECF=TXT)
- FL_IBM_UNICODE_SERVICE (&FLIBMUS) - Define use of z/OS Unicode Services for simple character conversions to lower performance [AUTO]
  - AUTO - Use it, if behavior the same and faster
  - ON - Activate it (with round trip conversion)
  - OFF - Deactivate it (no use of Unicode Services)
- FLAM4MF - Enable Microfocus Enterprise Server support for FLAM and FLUC record interfaces (ccsid/yes/no)
- FLAM4MF_TRACEFILE - Enable a trace file for the MF-EDZ stubs supporting the record interface (Windows or Linux filename)
- FLAM4MF_STATIC_SYSVAR - Static system variables are read from filename into the environment (filename in EBCDIC or ASCII, Syntax: 'SYMBOL=value', also use 'DD:SYSVAR')
- FLAM4MF_DYNAMIC_SYSVAR - Dynamic system variables are read from filename into the environment (in conjunction with the JCL User Exit of MF-EDZ to add dynamic variables)
- _EDC_ZERO_RECLEN (&FLZRECL) - Used for handling of empty records (see dedicated chapter below) on z/OS

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

- FLCL_CONFIG_FILE - the configuration filename (default is '$HOME/.flcl.config' on UNIX/WIN or '&SYSUID..FLCL.CONFIG' on mainframes)
- FLCL_DEFAULT_OWNER_ID - the default owner ID (default is 'limes')
- owner_FLCL_command_PROPERTY_FILENAME - To override default property file names
- path_argument - to override the hard coded default property value

##### 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 round brackets 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.

###### 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 to define 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 new line 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.