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:

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:

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 word ALPHA is a system-name. It is not a reserved word, and is 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 word ALPHA is a system-name. It is not a reserved word, and is 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:
  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

Additionally, see 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 Alpha systems) or environment variables (on Tru64 UNIX and Windows NT systems) with user-defined mnemonic-names, (2) provides a way to reference command-line arguments and (on Tru64 UNIX and Windows NT) environment variables or (on OpenVMS Alpha) 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.

cursor-position

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

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:
  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

  1. The device-name clause associates a device with a user-defined word (device-name).
    On Tru64 UNIX and Windows NT, the device name is derived from an environment variable, if that environment variable exists. Otherwise, the defaults are as follows:
    System-Name Tru64 UNIX and Windows NT
    Environment Variable     		Tru64 UNIX and Windows NT 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 Alpha
    Logical Name     		OpenVMS Alpha 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 COB$INPUT SYS$INPUT
    SYSOUT COB$OUTPUT SYS$OUTPUT
    SYSERR 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 the Compaq COBOL User Manual for more information.) <>

top-of-page-name Clause

  1. 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

  1. 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 or Windows NT 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.

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

ALPHABET Clause

  1. The ALPHABET clause relates a name to a character code set, collating sequence, or both.
    The ALPHABET clause specifies:
  2. ASCII refers to the character set defined in American National Standard X3.4-1968, "Code for Information Interchange."
  3. STANDARD-1 refers to the ASCII character set.
  4. 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."
  5. 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.
  6. EBCDIC refers to the EBCDIC character set or collating sequence. It is defined in Appendix B, Character Sets.
  7. 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.
  8. 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

  1. 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.
  2. The value of each nonnumeric literal specifies the actual character in the native character set.
  3. 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.
  4. 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.
  5. 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

  1. 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.
  2. The compiler assigns each character in the set a successive ascending position in the collating sequence or character code set.
  3. 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.
  4. 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

  1. 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

  2. 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).
  3. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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

  1. In the CURRENCY SIGN clause, char specifies the PICTURE clause currency symbol. It can be any printable character from the computer character set except:
  2. The CURRENCY SIGN clause cannot contain a symbolic-character or figurative constant.
  3. If there is no CURRENCY SIGN clause, the default currency sign used for the PICTURE clause is the "$" symbol, unless (on OpenVMS only) the logical name SYS$CURRENCY is defined at DCL command level as a different character. 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 only 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"").

DECIMAL-POINT IS COMMA Clause

  1. The DECIMAL-POINT IS COMMA clause exchanges the functions of the comma and period in: (1) the PICTURE clause character-string and (2) numeric literals.

CURSOR IS Clause

  1. The CURSOR IS clause specifies the initial position of the cursor at the start of an ACCEPT (Format 5) statement. If cursor-position is within an input or update field on the screen, then the initial cursor position is at the start of that field. If the CURSOR IS clause is not specified, or if cursor-position is not within an input or update field on the screen, the cursor's initial position is at the start of the first input or update field of the screen. The cursor-position is updated upon completion of the ACCEPT statement to contain the position of the cursor when the ACCEPT terminated.
  2. In the CURSOR IS clause, if cursor-position is four characters in length, the first two characters represent the line number, and the second two the column number. If cursor-position is six characters in length, the first three characters represent the line number, and the second three the column number.

CRT STATUS IS Clause

  1. If the CRT STATUS IS clause is specified, crt-status-code is updated after every ACCEPT (Format 5) statement. The first two characters are a termination code that indicates the cause of the termination of the ACCEPT operation. (The third character is currently not defined, and is reserved for future use.) The termination codes are explained in Table 4-1.

    Command Line Arguments

  2. The ARGUMENT-NUMBER and ARGUMENT-VALUE clauses are used to process command line arguments. The DISPLAY statement is used to select and modify the values, and the ACCEPT statement is used to retrieve the values.

    Environment Variables and System Logicals

  3. The ENVIRONMENT-NAME and ENVIRONMENT-VALUE clauses are used to process environment variables and system logicals. The DISPLAY statement is used to select and modify the values, and the ACCEPT statement is used to retrieve the values.

Table 4-1 CRT STATUS Termination Codes
First Character Second Character Meaning
`0' `0' Terminator key pressed by the operator; normal completion
`0' `1' Auto-skip out of the last field; normal completion
`1' x`00'---x`1A' User-defined function key number for F1--F20 and the Find through Next keys 1
`9' x`00' No items falling within the screen 1

1The second character contains a hexadecimal value. An example of how to examine this value is given in the Examples section.

Previous Next Contents Index