# Compaq COBOL
Reference Manual

Previous | Contents | Index

## 6.1.1 Compiler-Directing Statements and Sentences

A compiler-directing statement causes the compiler to take an action during compilation. The verbs COPY, REPLACE, RECORD, and USE define compiler-directing statements. A compiler-directing sentence can contain other statements but it must contain only one compiler-directing statement. The compiler-directing statement must be the last statement in the sentence and must be followed immediately by a period.

## 6.1.2 Imperative Statements and Sentences

An imperative statement specifies an unconditional action for the program. It must contain a verb and the verb's operands, and cannot contain any conditional phrases. For example, the following statements are imperative:

    OPEN INPUT FILE-A

    COMPUTE C = A + B

However, the following statement is not imperative because it contains the phrase, ON SIZE ERROR, which makes the program's action conditional:

    COMPUTE C = A + B ON SIZE ERROR PERFORM NUM-TOO-BIG.

In the Procedure Division rules, an imperative statement can be a sequence of consecutive imperative statements. The sequence must end with: (1) a separator period or (2) any phrase associated with a statement that contains the imperative statement. For example, the following sentence contains a sequence of two imperative statements following the AT END phrase.

    READ FILE-A AT END PERFORM NO-MORE-RECS
                       DISPLAY "No more records."     END-READ.

An imperative sentence contains only imperative statements and ends with a separator period.

## 6.1.3 Conditional Statements and Sentences

A conditional statement determines a condition's truth value. (A truth value is either a yes or no answer to the question, "Is the condition true?".) The statement uses the truth value generated by the program to determine subsequent program action.

Conditional statements are as follows:

- An EVALUATE, IF, RETURN, or SEARCH statement
- An ACCEPT statement with the [NOT] AT END or [NOT] ON EXCEPTION phrase
- A DISPLAY statement with the [NOT] ON EXCEPTION phrase
- A READ statement with the [NOT] AT END or [NOT] INVALID KEY phrase
- A WRITE statement with the [NOT] INVALID KEY or [NOT] END-OF-PAGE phrase
- A DELETE, REWRITE, or START statement with the [NOT] INVALID KEY phrase
- An arithmetic statement (ADD, COMPUTE, DIVIDE, MULTIPLY, SUBTRACT) with the [NOT] ON SIZE ERROR phrase
- A STRING or UNSTRING statement with the [NOT] ON OVERFLOW phrase
- A CALL statement with the [NOT] ON EXCEPTION or [NOT] ON OVERFLOW phrase

A conditional sentence is a conditional statement that ends with a separator period. It can include an optional preceding imperative statement. For example, the following sentence is conditional even though it contains the imperative statement, GO TO PROC-A:

    READ FILEA AT END GO TO PROC-A.

The program interprets this sentence to mean "If not at the end of the file, read the next record; otherwise, go to PROC-A."

## 6.1.4 Scope of Statements

Scope terminators delimit the scope of some Procedure Division statements.

The scope of statements contained (nested) in other statements can also terminate implicitly. When statements are contained in other statements, a separator period (that terminates the sentence) terminates all nested statements as well.

In the following example, the separator period terminates the IF, MOVE, and PERFORM statements:

    IF ITEMA = ITEMB
       MOVE ITEMC TO ITEMB
       PERFORM PROCA.

In the following example, the ELSE phrase of the IF statement terminates the scope of the READ and the first MOVE statements:

    IF ITEMA = ITEMB
       READ FILEA
            AT END MOVE ITEMC TO ITEMB
    ELSE
       MOVE ITEMD TO ITEME.

A delimited-scope statement is a special category of statement used in structured programming. A delimited-scope statement is any statement that includes its explicit scope terminator. See Section 6.3.4 for a list of explicit scope terminators.

A delimited-scope statement can be nested in another delimited-scope statement with the same verb. Then, each explicit scope terminator terminates the statement that begins with the closest unpaired preceding occurrence of the verb.

In the following example, the END-IF after the ADD statements (line 8) terminates the IF on line 5. The END-IF after the SUBTRACT (line 10) terminates the IF on line 3. The scope of the first IF statement (line 1) is terminated by the separator period on line 11.

1. `IF ITEMA = ITEMB`
2. `MULTIPLY ITEMH BY ITEMI`
3. `IF ITEMI > 18`
4. `MOVE ITEMC TO ITEMD`
5. `IF ITEMD > ITEME`
6. `ADD ITEME TO ITEMF`
7. `ADD ITEMG TO ITEMH`
8. `END-IF`
9. `SUBTRACT 6 FROM ITEMH`
10. `END-IF`
11. `PERFORM PROCA.`

# 6.2 Uniqueness of Reference

Every user-defined name in a COBOL program names a resource. (See the section on User-Defined Words in Section 1.2.1.) To use a resource, however, a statement in a COBOL program must contain a reference that uniquely identifies that resource. Qualification, reference modification, and subscripting or indexing allow unique and unambiguous references to that resource. Qualified procedure-names allow uniqueness of reference to procedures, and qualified condition-names allow uniqueness of reference to condition-names.

When you assign the same name in separate (contained) programs to two or more occurrences of a resource, certain conventions apply that limit the scope of names. Name scoping and scope of names are COBOL language terms that describe the methods for resolving references to user-defined words in a contained program environment. (See Section 6.2.6, Scope of Names.)

Some user-defined words can be made available to every program in the run unit. (See the Section 5.3.21 clause in Chapter 5.) These words are called external data. Other user-defined words can be made available to programs contained within the program that defines that resource. (See the Section 5.3.25 clause in Chapter 5.) These words are called global data.

## 6.2.1 Qualification

A reference to a user-defined word is unique if one or more of the following conditions exists:

- No other name has the same spelling, including hyphenation.
- It is part of a REDEFINES clause. (The reference following the word REDEFINES is unique because of the placement of the REDEFINES clause.) See the Syntax Rules for the Section 5.3.40 clause.
- Scoping rules make it unique. (See Section 6.2.6, Scope of Names.)

A nonunique name within a hierarchy of names can be used in more than one place in your program. Unless you are redefining it, you must refer to this nonunique name using one or more higher-level names in the hierarchy. These higher-level names are called qualifiers. Using them to achieve uniqueness of reference is called qualification.

To make your reference unique, you need not specify all available qualifiers for a name, only those necessary to eliminate ambiguity.

Consider the following two record descriptions:

    01 REC1.
        05 ITEMA       PIC XX.
        05 ITEMB       PIC X(20).

    01 REC2.
        05  GROUP1.
            10  ITEMA  PIC 9(5).
            10  ITEMB  PIC X(3).
        05  GROUP2.
            10  ITEMC  PIC X(4).
            10  ITEMD  PIC X(8).

ITEMA and ITEMB appear in both record descriptions. Therefore, you must use qualifiers when you refer to these items in Procedure Division statements. For example, all of the following references to ITEMA are unique: ITEMA OF GROUP1, ITEMA OF REC1, ITEMA IN GROUP1 OF REC2.

Regardless of the preceding, you cannot use the same data-name as:

- The name of an external record and as the name of any other external data item in any program contained within or containing the program describing the external data record
- The name of an item possessing the global attribute and as the name of any other data item in the program describing the global data item

When a program is contained within a program or contains another program, specific conventions apply. (See Section 6.2.6.)

The general formats for qualification are as follows:

The following syntax rules apply to qualification:

1. Each reference to a nonunique, user-defined name must use a sequence of qualifiers that eliminates ambiguity from the reference.
2. A name can be qualified even if it does not need qualification. If more than one set of qualifiers ensures uniqueness, any set can be used.
3. IN and OF are equivalent.
4. In Format 1, each qualifier must be either the name associated with a level indicator, the name of a group to which the item being qualified is subordinate, or the name of a condition variable with which the condition-name being qualified is associated. (See Section 6.2.5.) Qualifiers must be ordered from least- to most-inclusive levels in the hierarchy.
5. In Format 7, each qualifier must be the name of a group to which the item being qualified is subordinate. Qualifiers must be ordered from least- to most-inclusive levels in the hierarchy.
6. In Format 1, data-name-2 can be a record-name.
7. If the program contains explicit references to a paragraph-name, the paragraph-name cannot appear more than once in the same section. When a section-name qualifies a paragraph-name, the word SECTION cannot appear. A paragraph-name need not be qualified in a reference from within the same section. You cannot reference a paragraph-name or section-name from any other program.
8. On OpenVMS, in Format 3, a COPY statement that accesses an OpenVMS Alpha Librarian library-record must qualify text-name with library-name. <>
9. In Format 3, on Tru64 UNIX systems, the library-name for the COPY statement will direct COPY to access the text-name file from the library-name subdirectory. <>
   See Chapter 8 for information on the COPY statement.
10. If the program has more than one file description entry with a LINAGE clause, every reference to LINAGE-COUNTER must be qualified.
11. If the program has more than one report description entry, every Procedure Division reference to LINE-COUNTER must be qualified.
12. In the Report Section, an unqualified reference to LINE-COUNTER is qualified implicitly by the name of the report in whose report description entry the reference is made. Whenever the LINE-COUNTER of a different report is referenced, LINE-COUNTER must be qualified explicitly by the report name associated with the different report.
13. If the program has more than one report description entry, every Procedure Division reference to PAGE-COUNTER must be qualified.
14. In the Report Section, an unqualified reference to PAGE-COUNTER is qualified implicitly by the name of the report in whose report description entry the reference is made. Whenever the PAGE-COUNTER of a different report is referenced, PAGE-COUNTER must be qualified explicitly by the report name associated with the different report.
15. On OpenVMS, if the program has more than one file description entry, every reference to RMS-STS, RMS-STV, and RMS-FILENAME must be qualified. <>

## 6.2.2 Subscripts and Indexes

Occurrences of a table are not individually named. You refer to them by using a subscript or index to specify their location relative to the table's beginning. Subscripting is a general operation; indexing is a special form of subscripting.

Unless otherwise specified by the rules for a statement, subscripts and indexes are evaluated once, at the beginning of a statement. If a statement contains rules describing the evaluation of subscripts, those rules also apply to the evaluation of indexes.

Subscripting

Subscripts can appear only in references to individual elements in a list, or table, of like elements that do not have individual data-names. (See the Section 5.3.35 clause in Chapter 5.)

The general format for subscripting is as follows:

All restrictions in the rules for subscripting also apply to indexing (See the following subsection describing Indexing.) The following rules apply to subscripting:

1. A subscript can be represented by any arithmetic expression.
2. In Format 2, argument is an intrinsic function argument that is allowed to be repeated a variable number of times. Note that Format 1 also applies to intrinsic function arguments, but not with ALL subscripts. When ALL is specified as a subscript, the effect is as if each table element associated with that subscript position were specified. (For a list of the intrinsic functions that permit arguments with ALL subscripts, and for more information, see Chapter 7.) Also in Format 2, data-name is the data-name of a numeric integer elementary item.
3. Identifiers in subscript arithmetic expressions must refer to elementary numeric data items.
4. The lowest valid subscript value is 1. This value points to the first element of the table. Subscript values 2, 3, and so on, point to the next consecutive table elements.
5. The highest valid subscript value is the maximum number of occurrences of the item specified in the OCCURS clause.
6. The subscript or set of subscripts that identifies the table element is delimited by a balanced pair of left and right parentheses.
7. Each table element reference must include subscripting. However, the reference cannot include subscripting when it is one of the following:
   - The subject of a SEARCH statement
   - In a REDEFINES clause
   - In the KEY IS phrase of an OCCURS clause
8. The subscript or set of subscripts follows the table element's data-name. The data-name is then called a subscripted data-name or an identifier.
9. The number of subscripts following a table element reference must equal the number of dimensions in the table; that is, there must be a subscript for each OCCURS clause in the hierarchy that contains the table element and one for the table element itself.
10. A data-name can have up to 48 subscripts.
11. Subscripts must appear in the order of successively less inclusive dimensions of the table.
12. An arithmetic expression in a subscript cannot begin with a left parenthesis if the preceding arithmetic expression ends with a data-name.

Note Use the `check` compiler option with the `bounds` keyword for run-time upper- and lower-bound subscript range verification. The default action is not to check. For more information, refer to the COBOL online help file for your particular platform.

In the following examples, references to ITEME require two subscripts. The first subscript refers to the occurrence number of the most inclusive dimension, ITEMD (that contains ITEME).

Example 6-1 Subscripting Example

    WORKING-STORAGE SECTION.
    01  ITEMA PIC 99 COMP VALUE IS 3.
    01  ITEMB PIC 99 COMP VALUE IS 5.
    01  ITEMC VALUE IS "ABCDEFGHIJKLMNOPQRSTUVWX".
        03  ITEMD OCCURS 4 TIMES.
            05  ITEME OCCURS 6 TIMES PIC X.

IDENTIFIER | VALUE
ITEME (4,3) | U
ITEME (ITEMA,ITEMB) | Q
ITEME (ITEMA * 2 - 4, ITEMB - 2) | I
ITEME (ITEMA * ITEMB / 15, (ITEMA + ITEMB) / 4) | B

Indexing

Indexing is a special subscripting procedure. In indexing, you use the INDEXED BY phrase of the OCCURS clause to assign an index-name to each table level. You then refer to a table element using the index-name as a subscript.

The general format for indexing follows:

All the restrictions in the rules for subscripting apply to indexing. (See Subscripting.) The following rules apply only to indexing:

1. You must give index-name an initial value before using it. You can do this in:
   - A SET statement
   - A SEARCH statement with the ALL phrase
   - A PERFORM statement with the VARYING phrase
   Furthermore, only the statements in the previous list can change the value of index-name.
2. Indexing can be either direct or relative. Direct indexing means that the value of index-name or literal-1 is the occurrence number. Relative indexing means that the occurrence number is the value of index-name plus or minus literal-2. literal-2 must be an unsigned integer.

Note Use the `check` compiler option with the `bounds` keyword for run-time upper- and lower-bound index range verification. The default is not to check. For more information, refer to the COBOL online help file for your particular platform.

Example 6_2 is similar to Example 6-1 that illustrates subscripting. However, this example shows the use of index-names in references to the table, initializing indexes with the SET statement, and storing index-name values in index data items.

Example 6-2 Indexing Example

    WORKING-STORAGE SECTION.
    01  ITEMA USAGE IS INDEX.
    01  ITEMB USAGE IS INDEX.
    01  ITEMC VALUE IS "ABCDEFGHIJKLMNOPQRSTUVWX".
        03  ITEMD OCCURS 4 TIMES
            INDEXED BY DX.
            05  ITEME OCCURS 6 TIMES
                INDEXED BY EX PIC X.
    PROCEDURE DIVISION.
    PARA.
            SET DX TO 4.
            SET EX TO 1.
            DISPLAY ITEMD (DX).          (1)
            DISPLAY ITEME (DX, EX).      (2)
            DISPLAY ITEME (DX - 3, EX)   (3)
            SET ITEMA TO DX.
            SET ITEMB TO EX.

This example produces the following results:

1. : STUVWX
2. : S
3. : A

## 6.2.3 Reference Modification

Reference modification defines a subset of a data item by specifying its leftmost character and length.

data-name must refer to a data item whose usage is DISPLAY.

function-name must refer to an alphanumeric function.

The specifications for leftmost-character-position and length must be arithmetic expressions.

Each character of a data item has an ordinal number corresponding to its position. The leftmost position is number 1; successive positions to the right are numbered 2, 3, 4, and so on. If the data-name's data description entry has a SIGN IS SEPARATE clause, the sign position is assigned an ordinal number in the data item.

For a data item defined as numeric, numeric edited, alphanumeric, alphabetic, or alphanumeric edited, reference modification operates as if the data item were redefined as an alphanumeric data item the same size as that referred to by data-name.

Unless otherwise specified by the rules for a statement, reference modification is evaluated only once, at the beginning of a statement. Reference modification is evaluated immediately after subscripting or indexing evaluation. Rules that describe the evaluation of subscripting for the various statements also apply to the evaluation of reference modification.

The components of reference modification define the data item as follows:

- The evaluation of leftmost-character-position specifies the ordinal position of the data item's leftmost character. This position is relative to the leftmost character of the data item referred to by data-name. Evaluation of leftmost-character-position must result in an integer that is not less than 1, or greater than the number of characters in the data item referred to by data-name.
- The evaluation of length specifies the size of the unique data item. The evaluation must result in a positive integer. The sum of leftmost-character-position and length minus the value 1 must not exceed the number of characters in the data item referred to by data-name.
- If there is no length, the data item extends:
  - From and including the character identified by leftmost-character-position of the data item referred to by data-name
  - To and including the rightmost character of the data item referred to by data-name

The resulting unique data item is treated as an elementary item without the JUSTIFIED clause. It has the same class and category as the data item referred to by data-name. However, the categories numeric, numeric edited, and alphanumeric edited are considered category alphanumeric.

Reference modification is valid anywhere an alphanumeric identifier is allowed unless specific rules for a general format prohibit it.

Note Use the `check` compiler option with the `bounds` keyword for run-time upper- and lower-bound reference modification range verification. The default is not to check. For more information, refer to the COBOL online help file for your particular platform.

Examples

    WORKING-STORAGE SECTION.
    01  ITEMA PIC X(15) VALUE IS "ABCDEFGHIJKLMNO".
    01  ITEMB PIC 99 VALUE IS 10.

IDENTIFIER | VALUE
ITEMA (2:3) | BCD
ITEMA (ITEMB:2) | JK
ITEMA (ITEMB / 2:ITEMB - 6) | EFGH
ITEMA (ITEMB:) | JKLMNO

Previous | Next | Contents | Index