HP OpenVMS Systems Documentation

HP COBOL
Reference Manual

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

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.

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

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.

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.

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.

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.