Runtime environment variables

The COBOL runtime library uses the following runtime-only environment variables.

assignment-name
The user-defined word that you specify (in the ASSIGN clause) for the external file-name for a COBOL file; for example, OUTPUTFILE in the following ASSIGN clause:

SELECT CARPOOL ASSIGN TO OUTPUTFILE

At run time, you set the environment variable to the name of the system file that you want to associate with the COBOL file. For example:


export OUTPUTFILE=january.car_results

After you issue the command above, input/output statements for COBOL file CARPOOL operate on system file january.car_results in the current directory.

If you do not set the environment variable, or set it to the empty string, COBOL uses the literal name of the environment variable as the system file-name (OUTPUTFILE in the current directory for the ASSIGN example above).

The ASSIGN clause can specify a file stored in a file system other than the default, such as the standard language file system (STL) or the record sequential delimited file system (RSD). For example:


SELECT CARPOOL ASSIGN TO STL-OUTPUTFILE

In this case, you still set environment variable OUTPUTFILE (not STL-OUTPUTFILE).

CICS_TK_SFS_SERVER
Specifies the fully qualified CICS® SFS server name. For example:

export CICS_TK_SFS_SERVER=/.:/cics/sfs/sfsServer
COBOL_BCD_NOVALIDATE
Specifies if the packed-decimal data item is validated prior to conversion and arithmetic operations.

When this environment variable is set to 1, the digit and sign validation done prior to conversion and arithmetic operations is skipped.

Using this environment variable does not affect the numeric class test that tests whether a data item IS NUMERIC or IS NOT NUMERIC.

COBPATH
Specifies the directory paths to be used by the COBOL runtime to locate dynamically accessed programs such as shared libraries. COBPATH is searched first (and if not set, defaults to the current directory ("./")), followed by LD_LIBRARY_PATH.
For example:
export COBPATH=/pgmpath/pgmshlib
COBRTOPT
Specifies the COBOL runtime options.

Separate runtime options by a comma or a colon. Use parentheses or equal signs (=) as the delimiter for suboptions. Options are not case sensitive. For example, the following two commands are equivalent:


export COBRTOPT="CHECK(ON):UPSI(00000000)"
export COBRTOPT=check=on,upsi=00000000

If you specify more than one setting for a given runtime option, the rightmost such setting prevails.

The defaults for individual runtime options apply. For details, see the related reference about runtime options.

EBCDIC_CODEPAGE
Specifies an EBCDIC code page applicable to the EBCDIC data processed by programs compiled with the CHAR(EBCDIC) or CHAR(S390) compiler option.

To set the EBCDIC code page, issue the following command, where codepage is the name of the code page to be used:


export EBCDIC_CODEPAGE=codepage

If EBCDIC_CODEPAGE is not set, the default EBCDIC code page is selected based on the current locale, as described in the related reference about the locales and code pages supported. When the CHAR(EBCDIC) compiler option is in effect and multiple EBCDIC code pages are applicable to the locale in effect, you must set the EBCDIC_CODEPAGE environment variable unless the default EBCDIC code page for the locale is acceptable.

CICS_SFS_DATA_VOLUME
Specifies the name of the SFS data volume on which SFS files are to be created. For example:

export CICS_SFS_DATA_VOLUME=sfs_SFS_SERV

This data volume must have been defined to the SFS server that your application accesses.

If this variable is not set, the default name sfs_SSFS_SERVER is used.

CICS_SFS_INDEX_VOLUME
Specifies the name of the SFS data volume on which alternate index files are to be created. For example:

export CICS_SFS_INDEX_VOLUME=sfs_SFS_SERV

This data volume must have been defined to the SFS server that your application accesses.

If this variable is not set, alternate index files are created on the same data volume as the corresponding base index files.

CICS_VSAM_AUTO_FLUSH
Specifies whether all changes to CICS SFS files for each input-output operation are committed to disk before control is returned to the application (that is, whether the operational force feature of SFS is enabled). You can improve the performance of applications that use SFS files by specifying OFF for this environment variable. For example:

export CICS_VSAM_AUTO_FLUSH=OFF

When this environment variable is set to OFF, SFS uses a lazy-write strategy; that is, changes to SFS files might not be committed to disk until the files are closed.

If SFS client-side caching is in effect (that is, environment variable CICS_VSAM_CACHE is set to a valid nonzero value), the setting of CICS_VSAM_AUTO_FLUSH is ignored. Operational force is disabled.

If SFS client-side caching is not in effect, the value of CICS_VSAM_AUTO_FLUSH defaults to ON.

CICS_VSAM_CACHE
Specifies whether client-side caching is enabled for SFS files. You can improve the performance of applications that use SFS files by enabling client-side caching.

CICS_VSAM_CACHE syntax

Read syntax diagramSkip visual syntax diagramread-and-insert-cache-sizeread-cache-size: insert-cache-size: flag, flag

Size units are in numbers of pages. A size of zero indicates that caching is disabled. The possible flags are:

ALLOW_DIRTY_READS
Removes the restriction for read caching that the files being accessed must be locked.
INSERTS_DESPITE_UNIQUE_INDICES
Removes the restriction for insert caching that inserts are cached only if all active indices for clustered files and all active alternate indices for entry-sequenced and relative files allow duplicates.

For example, the following command sets the read-cache size to 16 pages and the insert-cache size to 64 pages. It also enables dirty reads and enables inserts despite unique indices:


export CICS_VSAM_CACHE=16:64:ALLOW_DIRTY_READS, \
    INSERTS_DESPITE_UNIQUE_INDICES

By default, client-side caching is not enabled.

CICS_SFS_CACHE_<filename>
Specifies whether client-side caching is enabled for a specific SFS file, where you can replace <filename> with the SFS file name. If the file name contains (.) characters, you must replace them with (_) (underscore). This setting would help to enable client-side cache based on file operation (read or write) done on any specific file. You can specify CICS_SFS_CACHE_<filename> using the same syntax specification as the CICS_SFS_CACHE setting.
For example, to enable file specific client-side caching for a file with the name VSAM.FILE1.TESTFILE, which is always used for SFS write operation, the environment can be specified only to enable WRITE operation cache:
export CICS_SFS_CACHE_FILE1_TESTFILE=0:512
CICS_SFS_RDM_CACHE
Specifies whether client-side caching is disabled for SFS files used for random read operation. Specify the environment value as 0 to disable client side read operation cache for all files that are opened for random read operation:
export CICS_SFS_RDM_CACHE=0

The CICS_SFS_CACHE setting is a global setting that is applicable for all SFS files, and it is not recommended to set read operation cache for files that are opened for random read operations. The CICS_VSAM_RDM_CACHE setting can be used to disable the SFS client-side read operation cache.

CICS_SFS_PREALLOC_<filename>
Specifies the number of pre-allocated pages for a file, when your program creates the file for the first time on the SFS server. You can replace <filename> with the SFS file name. If the file name contains (.) characters, you must replace them with (_) (underscore). For example, to create a SFS file named TESTFILE and pre-allocate 2000 pages, set the following environment variable:
export CICS_SFS_PREALLOC_TESTFILE=2000
COBCORE
Specifies that the location of core files generated by the runtime will be placed. If not specified, the default is the current working directory. If the name ends with a percent character (%), a file name with the program name and timestamp is created.
COBOUTDIR
Specifies a directory where all files create by COBOL DISPLAY statements (SYSOUT, CONSOLE, SYSPUNCH), and core files (COBCORE) are created, if the variable does not include a path.
PATH
Specifies the directory paths of executable programs.
SYSIN, SYSIPT, SYSOUT, SYSLIST, SYSLST, CONSOLE, SYSPUNCH, SYSPCH
These COBOL environment names are used as the environment variable names that correspond to the mnemonic names used in ACCEPT and DISPLAY statements.

If the environment variable is not set, by default SYSIN and SYSIPT are directed to the logical input device (keyboard). SYSOUT, SYSLIST, SYSLST, and CONSOLE are directed to the system logical output device (screen). SYSPUNCH and SYSPCH are not assigned a default value and are not valid unless you explicitly define them. If value of any of these variables ends with a percent character (%), a file name with the program name and timestamp is created.

For example, the following command defines CONSOLE:


export CONSOLE=/users/mypath/myfile

CONSOLE could then be used in conjunction with the following source code:


SPECIAL-NAMES.
    CONSOLE IS terminal
    . . .
    DISPLAY 'Hello World' UPON terminal
VFS_MONGODB_DATABASE

Specifies the database to use for programs that use the MongoDB file system.

VFS_MONGODB_URI

Specifies the connection URI that identifies the location of your MongoDB server.

Related references  
CHAR  
Runtime options