# Compaq COBOL
Reference Manual

Previous | Contents | Index

All user-defined words in a program, except segment-numbers and level-numbers, can belong to only one of these sets. User-defined words in each set must be unique, except as described in the rules for uniqueness of reference. (See Section 6.2).

Except for section-names, paragraph-names, segment numbers, and level-numbers, all user-defined words must contain at least one alphabetic character. Segment-numbers and level-numbers need not be unique. Any segment-number or level-number can be the same as any other segment-number or level-number.

### 1.2.1.2 System-Names

System-names are COBOL words that refer to the program's operating environment. The same COBOL word can be used in a program as both a user-defined word and a system-name. The compiler determines the word's class from its context.

The system-names are as follows:

> ALPHA
> ASCII
> CARD-READER
> CONSOLE
> CONTIGUOUS
> CONTIGUOUS-BEST-TRY
> C01
> DEFERRED-WRITE
> EBCDIC
> EXTENSION
> FILL-SIZE
> LINE-PRINTER
> LOCK-HOLDING
> MASS-INSERT
> OPERATOR
> PAPER-TAPE-PUNCH
> PAPER-TAPE-READER
> PREALLOCATION
> PRINT-CONTROL
> SWITCH
> VAX
> WINDOW

### 1.2.1.3 Reserved Words

A reserved word can be used only as specified in the general formats. It cannot be a user-defined word. (See Appendix A for a list of reserved words.)

The three types of reserved words follow:

- Required words
- Optional words
- Special-purpose words

Required Word
A required word must be used when its format is used in a program.

The two types of required words are keywords and special character words. In general formats, keywords are uppercase and underlined. Arithmetic operators and relation characters are special character words; they are not underlined in the general format.

In the following sample format, the keywords are COMPUTE, ROUNDED, SIZE, ERROR, NOT, and END-COMPUTE. The equal sign (=) is a special-character word.

Optional Words
In general formats, uppercase words that are not underlined are optional words. They can make a program more human-readable, but have no semantic effect. In the previous sample format, ON is an optional word.

Special-Purpose Words
The two types of special-purpose words are figurative constants and special registers. Figurative constants name and refer to specific constant values and are described in detail in Section 1.2.3. Special registers name and refer to special storage areas that the compiler provides.

The Compaq COBOL special registers are primarily used to store information related to or produced by specific Compaq COBOL features. Table 1-3 shows the special registers, their usage, and their descriptions.

Table 1-3 Special Registers
Special Register | Usage---Description
--- | ---
RETURN-CODE (Alpha) | X/OPEN---Names a Compaq COBOL special register that may be used to set a return value for a calling program or to retrieve the value returned from a called program. It is represented by PIC S9(9) USAGE IS COMP. It is implicitly defined with GLOBAL scope. The RETURN-CODE register is initialized with the platform-specific success code. On OpenVMS Alpha, it is initialized to one. On Tru64 UNIX it is initialized to zero. The RETURN-CODE special register can be set by a called program, prior to the execution of a STOP RUN or EXIT PROGRAM statement, to pass a value to the calling program or the execution environment. For a calling program, it can be read, subsequent to the CALL, to obtain the value of the RETURN-CODE set by the called program. On Tru64 UNIX the main program sets the shell variable `status` to the value of the RETURN-CODE. On OpenVMS Alpha the main program sets the symbol $STATUS to the value of the RETURN-CODE. If you use the GIVING phrase on the CALL statement or on the Procedure Division header, specifying a data item as its argument, this data item (instead of RETURN-CODE) receives the return value. Note that you can specify the special register RETURN-CODE as the argument to GIVING, in which case RETURN-CODE receives the return value. For more information on the relationship between the GIVING phrase and the RETURN-CODE special register, see Table 6_7 in Chapter 6. Because the reserved word RETURN-CODE is one of the X/Open reserved words, you cannot use the `noxopen` keyword in the `reserved_words` compiler option if you want to use the RETURN-CODE special register. For related information, see Section 6.8 for the syntax and description of the GIVING phrase of the Procedure Divison header; and the CALL statement for the syntax and description of CALL GIVING. <>
LINAGE-COUNTER | LINAGE files---A line counter that the compiler provides when a file description entry contains a LINAGE clause. Its value is the number of the current record within the page body. (See the Section 5.3.31 clause in Chapter 5.) The implicit size of LINAGE-COUNTER is nine decimal digits represented by PIC S9(9) COMP. You can qualify LINAGE-COUNTER with a file-name. Procedure Division statements and the SOURCE clause of the Report Section can access the value of LINAGE-COUNTER but cannot change its value. LINAGE-COUNTER is global if file-name is global and external if file-name is external.
PAGE-COUNTER | REPORT WRITER---A page counter that the compiler provides for each report in the Report Section of the Data Division. You can qualify PAGE-COUNTER with a report-name. Its value is the number of the current page within a report. The implicit size of PAGE-COUNTER is six unsigned decimal digits represented by PIC 9(6) COMP. The Report Writer Control System (RWCS) maintains the value of PAGE-COUNTER and uses this value to number the pages of a report. The SOURCE clause of the Report Section can reference PAGE-COUNTER. The values in PAGE-COUNTER range from 1 to 999999 and can be altered by Procedure Division statements.
LINE-COUNTER | REPORT WRITER---A line counter that the compiler generates for each report in the Report Section of the Data Division. It may be qualified by a report-name. Its value is the number of the current line within a page. (See PAGE-COUNTER.) The implicit size of LINE-COUNTER is six unsigned decimal digits represented by PIC 9(6) COMP. The Report Writer Control System (RWCS) maintains the value of LINE-COUNTER and uses this value to determine the vertical positioning of a report. The SOURCE clause of the Report Section can reference LINE-COUNTER. The values in LINE-COUNTER range from 0 to 999999. Procedure Division statements can access the values in LINE-COUNTER; however, only the RWCS can change its value.
RMS-STS 1 (OpenVMS) | RMS---Contains the primary RMS status value of an I/O operation. (RMS-STV contains the secondary value.) RMS-STS provides additional information on COBOL File Status values resulting from I/O operations. 2 It is represented by PIC S9(9) USAGE IS COMP. You must qualify RMS-STS with a file-name. If the file-name is global, RMS-STS is also global. If the file-name is external, RMS-STS is also external. Before the program opens the file for the first time, the value of RMS-STS is undefined. After your program executes an OPEN or CLOSE statement, RMS-STS is set to the value of the STS field in the associated file access block (FAB). After executing a READ, WRITE, REWRITE, DELETE, START, or UNLOCK statement, RMS-STS is set to the value of the STS field in the associated record access block (RAB).
RMS-STV 1 (OpenVMS) | RMS---Contains the secondary (RMS-STS is primary) RMS status value of an I/O operation. The interpretation of this value is dependent on the value in RMS-STS. It is represented by PIC S9(9) USAGE IS COMP. You must qualify RMS-STV with a file-name. If the file-name is global, RMS-STV is also global. If the file-name is external, RMS-STV is also external. The value in RMS-STV is undefined prior to the initial OPEN of the file. After your program executes an OPEN or CLOSE statement, RMS-STV is set to the value of the STV field in the associated FAB. After executing a READ, WRITE, REWRITE, DELETE, or START statement, RMS-STV is set to the value of the STV field in the associated RAB.
RMS-FILENAME 1 (OpenVMS) | RMS---Names the complete RMS filename. It consists of 255 alphanumeric characters represented by PIC X(255) USAGE IS DISPLAY. You must qualify it with a file-name. If the file-name is global, RMS-FILENAME is also global. If the file-name is external, RMS-FILENAME is also external. Before the program opens the file for the first time, the value of RMS-FILENAME is undefined. For each COBOL OPEN statement, RMS-FILENAME is set to the complete RMS file specification string of file-name: for example, DBB1:[COBOL]MASTER.DAT.
RMS-CURRENT-STS 1 (OpenVMS) | RMS---Names a Compaq COBOL exception condition register. It contains the primary RMS status value of the most recent RMS I/O operation, regardless of the file operated on. (RMS-CURRENT-STV contains the secondary value.) It is represented by PIC S9(9) USAGE IS COMP. Since this register can contain the primary RMS status value for any file, you must not qualify it with a file-name. After your program executes any RMS I/O operation, it sets RMS-CURRENT-STS to the value contained in RMS-STS for that file.
RMS-CURRENT-STV 1 (OpenVMS) | RMS---Names a Compaq COBOL exception condition register. It contains the secondary RMS status value of the most recent RMS I/O operation, regardless of the file operated on. (RMS-CURRENT-STS contains the primary value.) It is represented by PIC S9(9) USAGE IS COMP. Since this register can contain the secondary RMS status value for any file, you must not qualify it with a file-name. After your program executes any RMS I/O operation, it sets RMS-CURRENT-STV to the value contained in RMS-STV for that file.
RMS-CURRENT-FILENAME 1 (OpenVMS) | RMS---Names a Compaq COBOL exception condition register. It contains the complete RMS file specification string of the file most recently operated on by an I/O statement. It consists of 255 alphanumeric characters represented by PIC X(255) USAGE IS DISPLAY. Since this register can contain the file-name for any file, you must not qualify it with a file-name. After your program executes any I/O operation, it sets RMS-CURRENT-FILENAME to the string contained in RMS-FILENAME for that file.

1Procedure Division statements can access the values or strings stored in the RMS special registers; however, only the RMS facility can change the contents of the registers. Refer to the Compaq COBOL User Manual for programming examples. For an explanation and a listing of RMS STS and STV values, refer to the OpenVMS System Messages and Recovery Procedures Reference Manual, an archived manual available on the OpenVMS Documentation CD-ROM, or the online OpenVMS Help Message utility. Refer to the OpenVMS Record Management Services Reference Manual for information on RMS. (RMS is on OpenVMS systems only.)
2The FILE STATUS data item (see Section 6.6.8, I-O Status) provides the primary source of status information for the file I-O verbs, and RMS-STS and RMS-STV provide supplementary information.

<>

### 1.2.1.4 Function-Names

A function-name is the name of a function as shown in Table 7-1, Intrinsic Functions. Note that function-names are not reserved words and may appear in a different context in a program as a user-defined word or a system-name.

## 1.2.2 Literals

A literal is a character-string whose value is specified by: (1) the ordered set of characters it contains, or (2) a reserved word that is a figurative constant.

Compaq COBOL provides two types of literals: numeric and nonnumeric. Numeric literals include floating-point literals and nonnumeric literals include hexadecimal and national literals. Floating-point, hexadecimal, and national literals are Compaq extensions. The following two sections describe literals in detail.

### 1.2.2.1 Numeric Literals

A numeric literal is a character string of 1 to 33 characters on Alpha or 1 to 20 characters on VAX, selected from the digits 0 to 9, the plus sign (+), the minus sign (-), and the decimal point (.).

The value of a numeric literal is the algebraic quantity represented by the characters in the literal.

Syntax Rules

1. A numeric literal must contain at least 1 digit and not more than 31 digits on Alpha or 18 digits on VAX.
2. A numeric literal must not contain more than one sign character, which must be the leftmost character. If the literal is unsigned, its value is positive.
3. A numeric literal must not contain more than one decimal point. The decimal point is treated as an assumed decimal point. It can be used anywhere in the literal except as the rightmost character.
   If a numeric literal contains no decimal point, it is an integer.
4. The compiler treats a numeric literal enclosed in quotation marks as a nonnumeric literal.

Table 1-4 provides examples of numeric literals.

Table 1-4 Numeric Literals
Literal | Value
--- | ---
12 | 12
0.12000 | 0.12
-123456789012345678 | -123456789012345678
000000003 | 3
-34.455445555 | -34.455445555
0 | 0
+0.000000000001 | +0.000000000001
+0000000000001 | +1

Floating-Point Literals

A floating-point literal, a Compaq extension to numeric literals, is a character-string whose value is specified by 4 to 37 characters on Alpha or 4 to 24 characters on VAX, selected from the digits 0 to 9, the plus sign (+), the minus sign (-), the decimal point (.), and the letter E (uppercase or lowercase).

You can use floating-point literals to achieve a wider range of numeric literal values.

Syntax Rules

1. A floating-point literal must be between 4 and 37 (Alpha) or 24 (VAX) characters in length.
2. A floating-point literal must contain the following characters:
   - At least 1 digit to the left of the E
   - A decimal point to the left of the E
   - An E (uppercase or lowercase)
   - At least 1 digit to the right of the E
3. The maximum number of characters to the left of the E is 33 (Alpha) or 20 (VAX), of which no more than 31 (18 on VAX) can be digits.
4. The maximum number of characters to the right of the E is 4 (Alpha) or 3 (VAX), of which no more than 3 (2 on VAX) can be digits.
5. A floating-point literal must not contain more than two sign characters as follows:
   - The first character of the literal
   - The first character following the E
6. If the first character of the literal is not a sign character, the literal is positive.
7. If the first character following the E is not a sign character, the value of the numeric component following the E is positive.
8. A floating-point literal must contain only one decimal point that can appear only to the left of the E.
9. A comma must be used in place of the decimal point, if the DECIMAL POINT IS COMMA clause is specified.

The value of a floating-point literal is the algebraic quantity represented by the characters in the literal that precede the E multiplied by ten raised to the power of the algebraic quantity represented by the characters in the literal following
the E.

Table 1-5 provides a few examples of floating-point literals.

Table 1-5 Floating-Point Literals
Literal | Value
--- | ---
1.6e5 | 160000.0
3.2E-3 | 0.0032
-1.e4 | -10000.0
0.002e+6 | 2000.0
-.8E-2 | -0.008

### 1.2.2.2 Nonnumeric Literals

A nonnumeric literal is a character-string of 0 to 256 characters. It is delimited on both ends by quotation marks (") or apostrophes ('). A nonnumeric literal delimited by apostrophes is treated in the same manner as a nonnumeric literal delimited by quotation marks.

The value of a nonnumeric literal is the value of the characters in the character-string. It does not include the quotation marks (or apostrophes) that delimit the character-string. All other punctuation characters in the nonnumeric literal are part of its value.

The compiler truncates nonnumeric literals to a maximum of 256 characters.

Syntax Rules

1. A space, left parenthesis, or pseudo-text delimiter (==) must immediately precede the opening quotation mark (or apostrophe).
2. The closing quotation mark (or apostrophe) must be immediately followed by one of the following:
   - Space
   - Comma
   - Semicolon
   - Period
   - Right parenthesis
   - Pseudo-text delimiter
3. If a nonnumeric literal is delimited by quotation marks ("), two consecutive quotation mark characters in the literal represent one quotation mark character.
4. If a nonnumeric literal is delimited by apostrophes ('), two consecutive apostrophes in the literal represent one apostrophe (').

Table 1-6 provides examples of nonnumeric literals. In these examples, s represents a space character.

Table 1-6 Nonnumeric Literals
Literal | Value
--- | ---
"ABC" | ABC
"01" | 01
"s01" | s01
"D""E""F" | D"E"F
"a.b" | a.b
'GHI' | GHI
'02' | 02
's02' | s02
'c.d' | c.d
"""" | "
'""' | ""
'''' | '
"''" | ''
'J""K' | J""K
"J""""K" | J""K
'J''''K' | J''K
"J''K" | J''K
'L''M''N' | L'M'N
"L'M'N" | L'M'N
'O"P"Q' | O"P"Q
"O""P""Q" | O"P"Q
'R""S""T' | R""S""T
"R""""S""""T" | R""S""T
'U''''V''''W' | U''V''W
"U''V''W" | U''V''W

Hexadecimal Literals

A hexadecimal literal (a Compaq extension to nonnumeric literals) is a character string of 2 to 256 hexadecimal digits. On the left it is delimited by the separator X (or x) immediately followed by a quotation mark (") or apostrophe ('); on the right it is delimited by a matching quotation mark or apostrophe. For example:

    03 HEX_VAL PIC X VALUE X"00".

The character string consists only of pairs of hexadecimal digits representing a byte value ranging from 00 to FF; hence, only the characters 0 to 9, A to F, and a to f are valid.

The value of a hexadecimal literal is the composite value of the paired hexadecimal representations. The compiler truncates hexadecimal literals to a maximum of 128 hexadecimal representations (pairs of hexadecimal digits).

A hexadecimal literal can be used interchangeably wherever a nonnumeric literal can appear in Compaq COBOL syntax. (Thus, hexadecimal literals cannot be used as operands in arithmetic statements.)

Syntax Rules

1. A space, left parenthesis, or pseudo-text delimiter (==) must immediately precede the opening character X (or x).
2. The closing quotation mark or apostrophe must be immediately followed by one of the following:
   - Space
   - Comma
   - Semicolon
   - Period
   - Right parenthesis
   - Pseudo-text delimiter

Table 1-7 provides examples of hexadecimal literals.

Table 1-7 Hexadecimal Literals
Literal | Value
--- | ---
X"00" | NUL
x"0D" | CR
x"2424" | $$
X'7b7a' | {z

National Literals

National literals can be from 0 to 128 2-byte characters (hence 256 bytes). The syntax is:

      VALUE N"".

National literals are made available when /NATIONALITY=JAPAN or `-nationality japan` is specified.

Previous | Next | Contents | Index