Rational Developer for System z
COBOL for Windows, Version 7.5, Programming Guide


Runtime environment variables

The COBOL runtime library uses the following environment variables. Case does not matter.

assignment-name
Any COBOL file that you want to specify in an ASSIGN clause. This use of assignment-name follows the rules for a COBOL word. For example:

SET OUTPUTFILE=d:\january\results.car

You must set all assignment-names.

If you make an assignment to a user-defined word that is not set as an environment variable, the assignment is made to a file that has the literal name of the user-defined word (OUTPUTFILE in the example below). If the assignment is valid, this file is written to the current directory.

After you set an assignment-name, you can use that environment variable as a COBOL user-defined word in an ASSIGN clause.

Based on the previous SET statement, a COBOL source program could include the following SELECT and ASSIGN clause:

SELECT CARPOOL ASSIGN TO OUTPUTFILE

Because OUTPUTFILE is defined in an environment variable, the statement above results in data being written to the file d:\january\results.car.

You can use ASSIGN to specify a file stored in an alternate file system such as the standard language file system (STL), record sequential delimited file system (RSD), or Btrieve file system.

CLASSPATH
Specifies directory paths of Java™ .class files required for an OO application.
COBJVMINITOPTIONS
Specifies Java virtual machine (JVM) options used when COBOL initializes a JVM.
COBMSGS
Specifies the name of a file to which runtime error messages will be written.

To capture runtime error messages in a file, use the SET command to set COBMSGS to a file-name. If your program has a runtime error that terminates the application, the file that COBMSGS is set to will contain an error message that indicates the reason for termination.

If COBMSGS is not set, error messages are written to the terminal.

COBPATH
Specifies the directory paths to be used by the COBOL run time to locate dynamically accessed programs such as .DLL (dynamic link library) files.

This variable must be set to run programs that require dynamic loading. For example:

SET COBPATH=C:\pgmpath\pgmdll
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:

SET COBRTOPT=TRAP=ON,errcount
SET COBRTOPT=trap(on):ERRCOUNT

The defaults for individual runtime options apply. For details, see the related reference below 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:

SET 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 below 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.

LANG
Specifies the locale (as described in the related task about using environment variables to specify a locale). LANG also influences the value of the NLSPATH environment variable as described below.

For example, the following command sets the language locale name to U.S. English:

SET LANG=en_US
LC_ALL
Specifies the locale. A locale setting that uses LC_ALL overrides any setting that uses LANG or any other LC_xx environment variable (as described in the related task about using environment variables to specify a locale).
LC_COLLATE
Specifies the collation behavior for the locale. This setting is overridden if LC_ALL if specified.
LC_CTYPE
Specifies the code page for the locale. This setting is overridden if LC_ALL if specified.
LC_MESSAGES
Specifies the language for messages for the locale. This setting is overridden if LC_ALL if specified.
LC_TIME
Determines the locale for date and time formatting information. This setting is overridden if LC_ALL if specified.
LOCPATH
Specifies the search path for the locale information database. The path is a semicolon-separated list of directory names.

LOCPATH is used for any operations that reference the locale, including locale-based comparisons of alphanumeric data items.

NLSPATH
Specifies the full path name of message catalogs and help files. NLSPATH must always be set, and is given an initial value during installation.

When you set NLSPATH, be sure to add to NLSPATH rather than replace it. Other programs might use this environment variable. For example:

SET NLSPATH=C:\cobolpath\MESSAGES\%L\%N;%NLSPATH%

%L and %N must be uppercase. %L is substituted by the value specified by the LANG environment variable. %N is substituted by the message catalog name used by COBOL.

Messages in the following languages are included with the product:

cs_CZ
Czech
de_DE
German
en_US
English
es_ES
Spanish
fr_FR
French
hu_HU
Hungarian
ja_JP
Japanese
ko_KR
Korean
pl_PL
Polish
pt_BR
Brazilian Portuguese
ru_RU
Russian
zh_CN
Simplified Chinese (People's Republic of China)
zh_TW
Traditional Chinese (Taiwan)

You can specify the languages for the messages and for the locale setting differently. For example, you can set the environment variable LANG to en_US and set the environment variable LC_ALL to ja_JP.IBM-943. In this example, any COBOL compiler or runtime messages will be in English, whereas native ASCII (DISPLAY or DISPLAY-1) data in the program is treated as encoded in code page IBM-943 (ASCII Japanese code page).

The compiler uses the combination of the NLSPATH and the LANG environment variable values to access the message catalog. If NLSPATH is validly set but LANG is not set to one of the locale values shown above, a warning message is generated and the compiler defaults to the en_US message catalog. If the NLSPATH value is invalid, a terminating error message is generated.

The runtime library also uses NLSPATH to access the message catalog. If NLSPATH is not set correctly, runtime messages appear in an abbreviated form.

 
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. Set them to files, not existing directory names.

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.

For example, the following command defines CONSOLE:

SET CONSOLE=c:\mypath\terminal.txt

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

SPECIAL-NAMES.
    CONSOLE IS terminal
    . . .
    DISPLAY 'Hello World' UPON terminal
TMP
Specifies the location of temporary work files (if needed) for SORT and MERGE functions. The defaults vary and are set by the sort utility installation program.

For example:

SET TMP=c:\shared\temp
TZ
Describes the time-zone information to be used by the locale. TZ has the following format:

SET TZ=SSS[+|-]nDDD[,sm,sw,sd,st,em,ew,ed,et,shift]

The defaults depend on the current locale.

When TZ is not present, the default is EST5EDT, the default locale value. When only the standard time zone is specified, the default value of n (difference in hours from GMT) is 0 instead of 5.

If you supply values for any of sm, sw, sd, st, em, ew, ed, et, or shift, you must supply values for all of them. If any of these values is not valid, the entire statement is considered invalid and the time-zone information is not changed.

For example:

SET TZ=CST6CDT

The preceding statement sets the standard time zone to CST, sets the daylight savings time to CDT, and sets a difference of six hours between CST and UTC. It does not set any values for the start and end of daylight savings time.

Other possible values are PST8PDT for Pacific United States and MST7MDT for Mountain United States.

related tasks
Using environment variables to specify a locale
Identifying files

related references
Locales and code pages that are supported
TZ environment parameter variables
CHAR
Runtime options


Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)