# Compaq COBOL
Reference Manual

Previous | Contents | Index

# Chapter 4
Environment Division

Function

The Environment Division describes the program's physical environment. It also specifies input-output control and describes special control techniques and hardware characteristics.

The Environment Division can contain two sections:

- Configuration Section (see Section 4.1, CONFIGURATION Section)
- Input-Output Section (see Section 4.2, INPUT-OUTPUT Section)

Syntax Rules

1. The Environment Division follows the Identification Division.
2. The general format defines the order of appearance of Environment Division entries.
3. A contained program cannot include a Configuration Section.

General Rule

Explicit or implicit Configuration Section entries in a program containing other programs apply to each contained program.

# 4.1 CONFIGURATION Section

The Configuration Section can contain three paragraphs:

- SOURCE-COMPUTER paragraph (see Section 4.1.1, SOURCE-COMPUTER)
- OBJECT-COMPUTER paragraph (see Section 4.1.2, OBJECT-COMPUTER)
- SPECIAL-NAMES paragraph (see Section 4.1.3, SPECIAL-NAMES)

The Configuration Section must not be stated in a program that is contained within another program. If Configuration Section entries are stated in a program that contains other programs, they apply to each contained program.

## 4.1.1 SOURCE-COMPUTER

Function

The SOURCE-COMPUTER paragraph specifies the computer on which the source program is to be compiled.

> ### computer-type

> is a user-defined word that names the computer.

Syntax Rule

The words ALPHA and VAX are system-names. They are not reserved words, and are for documentation only.

General Rules

1. If the WITH DEBUGGING MODE clause is not used, this paragraph is for documentation only.
2. All clauses of the SOURCE-COMPUTER paragraph apply to the program that specifies them. They also apply to any program contained within that program.
3. If you include the WITH DEBUGGING MODE clause in a program, or if you specify the `conditionals` command-line option, all conditional compilation lines are compiled. Otherwise, the compiler treats all conditional compilation lines as comment lines. (See Section 1.3.1 for additional information about source line interpretation.)

## 4.1.2 OBJECT-COMPUTER

Function

The OBJECT-COMPUTER paragraph describes the computer on which the program is to execute.

> ### computer-type

> is a user-defined word that names the computer.

> ### integer

> is a numeric literal that has no digits to the right of the assumed decimal point.

> ### alpha-name

> is the name of a collating sequence defined in the ALPHABET clause of the SPECIAL-NAMES paragraph.

> ### segment-number

> is an integer from 1 to 49.

Syntax Rule

The words ALPHA and VAX are system-names. They are not reserved words, and are for documentation only.

General Rules

1. All clauses of the OBJECT-COMPUTER paragraph apply to the program that explicitly or implicitly specifies them. They also apply to any program contained within that program.
2. The MEMORY SIZE clause is for documentation only. It has no effect on program execution.
3. The PROGRAM COLLATING SEQUENCE clause causes the program to use the collating sequence of alpha-name to determine the truth value of nonnumeric comparisons in:
   - Relation conditions
   - Condition-name conditions
   - Report description entries, the CONTROL clause
4. The PROGRAM COLLATING SEQUENCE clause also applies to nonnumeric merge and sort keys. However, the COLLATING SEQUENCE phrase in a MERGE or SORT statement takes precedence over the PROGRAM COLLATING SEQUENCE clause.
5. If there is no PROGRAM COLLATING SEQUENCE clause, the program uses the NATIVE collating sequence.
6. The SEGMENT-LIMIT clause is for documentation only.

Additional References

- Section 4.1.3, SPECIAL-NAMES Paragraph
- Section 5.3.2, SD (Sort-Merge File Description)
- Section 6.5.1, Relation Conditions
- Section 6.5.3, Condition-Name Condition
- Section 6.7, Segmentation

Additionally, refer to the information on SORT and MERGE statements in the Compaq COBOL User Manual.

Examples

1. Computer name only:

       OBJECT-COMPUTER. Alpha.

2. No computer name (if the computer is not specified, then no other clause can appear):

       OBJECT-COMPUTER.

3. With PROGRAM COLLATING SEQUENCE clause:

       OBJECT-COMPUTER. Alpha
           PROGRAM COLLATING SEQUENCE IS ALPH-A.

   The SPECIAL-NAMES paragraph must define ALPH-A.
4. With PROGRAM COLLATING SEQUENCE clause:

       OBJECT-COMPUTER. Alpha
           SEQUENCE IS EBCDIC.

   The SPECIAL-NAMES paragraph must define EBCDIC.
   If EBCDIC refers to the EBCDIC collating sequence, the SPECIAL-NAMES paragraph must contain the following clause:

       ALPHABET EBCDIC IS EBCDIC

## 4.1.3 SPECIAL-NAMES

Function

The SPECIAL-NAMES paragraph: (1) associates compiler features and logical names (on OpenVMS systems) or environment variables (on Tru64 UNIX systems) with user-defined mnemonic-names, (2) provides a way to reference command-line arguments and (on Tru64 UNIX) environment variables or (on OpenVMS) logical names with user-defined mnemonic names, (3) defines symbolic-characters, (4) specifies the currency sign, (5) selects the decimal point, (6) relates alphabet-names to character sets or collating sequences, (7) relates class-names to character sets, (8) provides for cursor positioning for an ACCEPT (Format 5) statement, and (9) provides information on the cause of termination of an ACCEPT (Format 5) statement.

> ### device-name

> is a user-defined word for a device. Only the ACCEPT and DISPLAY statements can refer to it.

> ### argument-number

> is a user-defined word that contains the current argument position indicator number when used with DISPLAY, or the count of command line arguments when used with ACCEPT. Only the ACCEPT and DISPLAY statements can refer to it.

> ### argument-value

> is a user-defined word that contains the value of the current command line argument as indicated by the current ARGUMENT-NUMBER. Only the ACCEPT and DISPLAY statements can refer to it.

> ### environment-name

> is a user-defined word that contains the name of an environment variable or system logical. Only the ACCEPT and DISPLAY statements can refer to it.

> ### environment-value

> is a user-defined word that contains the value of the environment variable or logical named by the current ENVIRONMENT-NAME. Only the ACCEPT and DISPLAY statements can refer to it.

> ### top-of-page-name

> is a user-defined word for the top of a page. Only the WRITE statement can refer to it.

> ### switch-num

> is the number of a program switch. Its value can range from 1 to 16.

> ### switch-name

> is a mnemonic-name for the program switch.

> ### cond-name

> is a condition-name for the on or off status of the switch. It always possesses the global attribute. Its truth value is true when the STATUS phrase matches the status of the switch, false when it does not.

> ### alpha-name

> is the user-defined word for a character set, collating sequence, or both. It always possesses the global attribute.

> ### first-literal

> is a literal. It specifies either: (1) the value of one or more alphabet characters, or (2) the first in a range of values.

> ### last-literal

> is a literal. It specifies the last in a range of values.

> ### lit

> is a literal. It specifies an alphabet character value.

> ### symbol-char

> is a user-defined word that names the symbolic-character. It always possesses the global attribute. The same symbol-char cannot appear more than once in the SYMBOLIC CHARACTERS clause.

> ### char-val

> is an integer that indicates the ordinal position of a character in the native character set.

> ### class-name

> is the user-defined word for a class. It always possesses a global attribute.

> ### char

> is a one-character nonnumeric literal that specifies the currency symbol. It cannot be a symbolic-character or figurative constant.

> ### literal-7 (Alpha)

> is an alphanumeric literal. It cannot be a figurative constant.

> ### literal-8 (Alpha)

> is an alphanumeric literal consisting of a single character. It cannot be a figurative constant. No two occurrences of literal-8 can have the same value.

> ### cursor-position (Alpha)

> is a data item declared in the Working-Storage Section of the program. It is either an elementary unsigned numeric integer either four or six characters in length, described as USAGE IS DISPLAY, or a group item either four or six characters in length, consisting of two elementary unsigned data items.

> ### crt-status-code (Alpha)

> is a group data item three characters in length, declared in the Working-Storage Section of the program. <>

Syntax Rules

1. In the first-literal phrase of the ALPHABET or CLASS clauses:
   - If alpha-name is in the PROGRAM COLLATING SEQUENCE clause, the ALPHABET clause cannot specify any character more than once.
   - If the ALSO or THRU phrase appears, first-literal must be one character long.
   - Numeric literals must be unsigned integers from 1 to 256.
   - If last-literal or lit is nonnumeric, it must be one character long.
   - THRU and THROUGH are equivalent.
2. If the first-literal phrase appears, alpha-name cannot be referenced in a CODE-SET clause.
3. The following are accessible only by ACCEPT and DISPLAY statements:

   > argument-count
   > argument-value
   > environment-name
   > environment-value

General Rules

1. All clauses of the SPECIAL-NAMES paragraph apply to the program defining them and to all programs contained within that program.

device-name Clause

2. The device-name clause associates a device with a user-defined word (device-name).
   On Tru64 UNIX, the device name is derived from an environment variable, if that environment variable exists. Otherwise, the defaults are as follows:

   System-Name | Tru64 UNIX Environment Variable | Tru64 UNIX Default File Name
   --- | --- | ---
   CARD-READER | COBOL_CARDREADER | `stdin`
   PAPER-TAPE-READER | COBOL_PAPERTAPEREADER | `stdin`
   CONSOLE | COBOL_CONSOLE | `stderr`
   LINE-PRINTER | COBOL_LINEPRINTER | `stdout`
   PAPER-TAPE-PUNCH | COBOL_PAPERTAPEPUNCH | `stdout`
   SYSIN | COBOL_INPUT | `stdin`
   SYSOUT | COBOL_OUTPUT | `stdout`
   SYSERR | COBOL_ERROR | `stderr`

   The input device for the ACCEPT statement is derived from COBOL_INPUT, if defined, and defaults to `stdin` . The output device for the DISPLAY statement is derived from COBOL_OUTPUT, if defined, and defaults to `stdout` . <>
   On OpenVMS, the file-name is derived from a logical name if that logical name exists. Otherwise, the defaults are as follows:

   System-Name | OpenVMS Logical Name | OpenVMS Default File Name
   --- | --- | ---
   CARD-READER | COB$CARDREADER | SYS$INPUT
   PAPER-TAPE-READER | COB$PAPERTAPEREADER | SYS$INPUT
   CONSOLE | COB$CONSOLE | SYS$ERROR
   LINE-PRINTER | COB$LINEPRINTER | SYS$OUTPUT
   PAPER-TAPE-PUNCH | COB$PAPERTAPEPUNCH | SYS$OUTPUT
   SYSIN (Alpha) | COB$INPUT | SYS$INPUT
   SYSOUT (Alpha) | COB$OUTPUT | SYS$OUTPUT
   SYSERR (Alpha) | COB$ERROR | SYS$ERROR

   The input device for the ACCEPT statement is derived from COB$INPUT, if defined, and defaults to SYS$INPUT. The output device for the DISPLAY statement is derived from COB$OUTPUT, if defined, and defaults to SYS$OUTPUT. (See the ACCEPT and DISPLAY statements in Chapter 6, Procedure Division, and refer to the Compaq COBOL User Manual for more information.) <>

top-of-page-name Clause

3. The system-name C01 refers to the first line of a logical page. Only the ADVANCING phrase of the WRITE statement can refer to the top-of-page-name equated to C01. (See the Section 6.8.43 statement in Chapter 6, Procedure Division.)

SWITCH Clause

4. The ON STATUS (or OFF STATUS) phrase of the SWITCH clause associates the status of switch-name with a corresponding cond-name. The program uses a switch-status condition in the Procedure Division to test the switch.
   Switches can also be read from the OpenVMS Alpha logical name COB$SWITCHES or the Tru64 UNIX environment variable COBOL_SWITCHES.
   The compiler interprets SWITCH n and SWITCH-n (where n represents a number from 1 to 8) as identical clauses. For example, SWITCH 1 is equivalent to SWITCH-1.

Refer to the Compaq COBOL User Manual for more information on using switches.

ALPHABET Clause

5. The ALPHABET clause relates a name to a character code set, collating sequence, or both.
   The ALPHABET clause specifies:
   - A character code set, when alpha-name is in a CODE-SET clause in the FILE-CONTROL paragraph or file description entry.
   - A collating sequence, when alpha-name is in: (1) the PROGRAM COLLATING SEQUENCE clause in the OBJECT-COMPUTER paragraph or (2) the COLLATING SEQUENCE phrase of a SORT or MERGE statement.
6. ASCII refers to the character set defined in American National Standard X3.4-1968, "Code for Information Interchange."
7. STANDARD-1 refers to the ASCII character set.
8. STANDARD-2 refers to the international version of the ISO 7-bit code. It is defined in International Standard 646, "7-Bit Coded Character Set for Information Processing Interchange."
9. NATIVE refers to the native character set. It consists of 256 characters. The lowest-valued 128 characters are the ASCII character set. The highest-valued 128 characters are reserved for later standardization and definition by Compaq.
10. EBCDIC refers to the EBCDIC character set or collating sequence. It is defined in Appendix B, Character Sets.
11. The character with the highest ordinal position in the program collating sequence equals the figurative constant HIGH-VALUE, except when this figurative constant is specified as a literal in the SPECIAL-NAMES paragraph. If more than one character has the highest position, HIGH-VALUE is the last character you specify.
12. The character with the lowest ordinal position in the program collating sequence equals the figurative constant LOW-VALUE, except when this figurative constant is specified as a literal in the SPECIAL-NAMES paragraph. If more than one character has the lowest position, LOW-VALUE is the first character you specify.

Literals in the ALPHABET Clause

13. The value of each numeric literal specifies the ordinal number of a character in the native character set. For example, 66 refers to the ASCII character A.
14. The value of each nonnumeric literal specifies the actual character in the native character set.
15. If the literal contains more than one character, the compiler interprets each character from left to right. It assigns each a successive ascending position in the collating sequence or character code set.
16. The order of appearance of literals in the ALPHABET clause specifies each character's ordinal number in ascending sequence. If the ALPHABET clause defines a character code set, the ordinal number identifies the character's relative position in the set.
17. Any unspecified characters in the native collating sequence have higher positions in the new collating sequence than all specified characters. The relative order of the unspecified characters is the same as in the native collating sequence.
    For example, the following clauses are equivalent:

        ALPHABET XYZ IS 2 4

        ALPHABET XYZ IS 2 4 1 3 5 6 7

        ALPHABET XYZ IS 2 4 1

THROUGH Phrase

18. The THROUGH phrase specifies a set of contiguous characters in the native character set. The first character is first-literal; the last character is last-literal.
19. The compiler assigns each character in the set a successive ascending position in the collating sequence or character code set.
20. The THROUGH phrase can specify the set of contiguous characters in either ascending or descending order. For example, "L" THRU "H" assigns successively higher numbers to L, K, J, I, and H.
21. The ALSO phrase assigns first-literal and each lit to the same position in the collating sequence or character code set. For example, "A" ALSO "$" causes the characters A and $ to be equivalent in comparisons when the associated alpha-name is in the PROGRAM COLLATING SEQUENCE clause.

SYMBOLIC CHARACTERS Clause

22. Each symbol-char corresponds to the char-val in the same relative position. In the following example, CARRIAGE-RET corresponds to 14 and ESCAPE to 28:

        SYMBOLIC CHARACTERS CARRIAGE-RET ESCAPE ARE 14 28

23. If the IN phrase is not specified, symbol-char represents the character, in the native character set, that has the ordinal position specified by char-val.

    Note The ordinal position is one greater than the internal representation of the character. For example, the character A is in ordinal position 66. Its internal representation is decimal 65 (hexadecimal 41).

24. If the IN phrase is specified, char-val represents the character that has the ordinal position specified by the IN alpha-name phrase.

CLASS Clause

25. The CLASS clause relates a name to a specified set of characters in that clause. class-name can be referenced only in a class condition. The characters specified by the values of the literals in this clause define the set of characters of which this class-name consists.
26. The value of each numeric literal specifies the ordinal number of a character in the native character set. This value must not exceed the value that represents the number of characters in the native character set.
27. The value of each nonnumeric literal specifies the actual character in the native character set. If the nonnumeric literal contains multiple characters, each character in the literal is included in the set of characters identified by class-name.
28. The THROUGH phrase specifies a set of contiguous characters in the native character set. The first character is first-literal; the last character is last-literal. The characters specified by a given THROUGH phrase can be specified in ascending or descending order.

CURRENCY SIGN Clause

29. In the CURRENCY SIGN clause, char specifies the PICTURE clause currency symbol. It can be any printable character from the computer character set except:
    - 0 through 9
    - A, B, C, D, P, R, S, V, X, Z, the lowercase characters a to z, or the space
    - Asterisk (*), plus sign (+), minus sign (-), comma (,), period (.), semicolon (;), quotation mark ("), equal sign (=), slash (/), left parenthesis ( ( ), or right parenthesis ( ) )
30. The CURRENCY SIGN clause cannot contain a symbolic-character or figurative constant.
31. If there is no CURRENCY SIGN clause, the default currency sign used for the PICTURE clause is the "$" symbol.
    On OpenVMS, if you define the logical name SYS$CURRENCY at DCL command level prior to compilation, the quoted character string to which you define it will be the currency string. To do this, prior to compiling the COBOL program, issue the following DCL command:

        $ DEFINE SYS$CURRENCY "quoted-character-string"

    The COBOL compiler will utilize the first character of this string as the currency symbol for the program.
    Subsequently, the system default value of SYS$CURRENCY can be restored for the process with the following DCL command:

        $ DEASSIGN SYS$CURRENCY   <>

    The default currency sign can also be established based on the `nationality` compiler option, depending on the keyword, as follows:

    US (default) | The default currency sign and symbol are the dollar sign ($), and Japanese language support features are disabled.
    JAPAN | The default currency sign and symbol are the Yen sign (¥) (which is not overridden by a SYS$CURRENCY definition), and Japanese language support features are enabled, including national character user-defined-words, data items (PIC N), and literals (N"").

CURRENCY SIGN Clause (Alpha)

32. To use CURRENCY SIGN IS literal-7, you must compile the program with the /RESERVED_WORDS=200X qualifier. Without that qualifier, you can specify only CURRENCY SIGN IS char, and specify it only once.
33. The CURRENCY SIGN IS literal-7 clause specifies a currency string that is placed into numeric-edited data items when they are used as receiving items and de-edited from a data item when the data item is used as a sending item that has a numeric or numeric-edited receiving item. The clause also determines which symbol shall be used in a picture character string to specify the presence of this currency string. This symbol is referred to as the currency symbol.
    literal-7 represents the value of the currency string.
    If the CURRENCY SIGN clause is specified with the PICTURE SYMBOL phrase, literal-8 is the currency symbol; if the clause is specified without the PICTURE SYMBOL phrase, literal-7 is the currency symbol, and it must be one character in length.
    If the currency symbol is a lowercase letter, it is treated as its uppercase equivalent.
34. If the PICTURE SYMBOL phrase is not specified, literal-7 must consist of a single character that is not one of the following:
    - 0 through 9
    - A, B, C, D, E, N, P, R, S, V, X, Z, or the lowercase equivalents; or the space
    - Asterisk (*), plus sign (+), minus sign (-), comma (,), period (.), semicolon (;), quotation mark ("), equal sign (=), slash (/), left parenthesis ( ( ), or right parenthesis ( ) )
35. If the PICTURE SYMBOL phrase is specified, literal-7 can have any length and:
    - Must contain at least one nonspace character, and
    - Can consist of any characters from the computer's character set except for the digits 0 through 9 and the characters asterisk (*), plus sign (+), minus sign (-), comma (,), and period (.)
36. literal-8 can be any character from the computer's character set except for the following:
    - 0 through 9
    - A, B, C, D, E, N, P, R, S, V, X, Z, or the lowercase equivalents; or the space
    - Asterisk (*), plus sign (+), minus sign (-), comma (,), period (.), semicolon (;), quotation mark ("), equal sign (=), slash (/), left parenthesis ( ( ), or right parenthesis ( ) )
    <>

Previous | Next | Contents | Index