Subscripting

Subscripting is a method of providing table references through the use of subscripts. A subscript is a positive integer whose value specifies the occurrence number of a table element.

Format

Read syntax diagramSkip visual syntax diagramcondition-name-1data-name-1INOFdata-name-2INOFfile-name-1( integer-1ALLdata-name-3 +  - integer-2index-name-1 +  - integer-3 )
condition-name-1
The conditional variable for condition-name-1 must contain an OCCURS clause or must be subordinate to a data description entry that contains an OCCURS clause.
data-name-1
Must contain an OCCURS clause or must be subordinate to a data description entry that contains an OCCURS clause.
data-name-2 , file-name-1
Must name data items or records that contain data-name-1.
integer-1
Can be signed. If signed, it must be positive.
ALL
Shall not be specified if condition-name-1 is specified.

Must be used only when the subscripted identifier is used as an intrinsic function argument or to identify a table in a format 2 SORT statement (table SORT statement).

If ALL is specified, the subscript is all of the possible values of a subscript for the associated table as specified in the rules for the functions for which the subscript ALL is allowed.

data-name-3
Must be a numeric elementary item representing an integer.

data-name-3 can be qualified. data-name-3 cannot be a windowed date field.

index-name-1
Corresponds to a data description entry in the hierarchy of the table being referenced that contains an INDEXED BY phrase that specifies that name.
integer-2 , integer-3
Cannot be signed.

The subscripts, enclosed in parentheses, are written immediately following any qualification for the name of the table element. The number of subscripts in such a reference must equal the number of dimensions in the table whose element is being referenced. That is, there must be a subscript for each OCCURS clause in the hierarchy that contains the data-name including the data-name itself.

When more than one subscript is required, they are written in the order of successively less inclusive dimensions of the data organization. If a multidimensional table is thought of as a series of nested tables and the most inclusive or outermost table in the nest is considered to be the major table with the innermost or least inclusive table being the minor table, the subscripts are written from left to right in the order major, intermediate, and minor.

For example, if TABLE-THREE is defined as:


01  TABLE-THREE.
    05  ELEMENT-ONE OCCURS 3 TIMES.
        10  ELEMENT-TWO OCCURS 3 TIMES.
            15  ELEMENT-THREE OCCURS 2 TIMES    PIC X(8).

a valid subscripted reference to TABLE-THREE is:


ELEMENT-THREE (2 2 1)

Subscripted references can also be reference modified. See the third example under Reference modification examples. A reference to an item must not be subscripted unless the item is a table element or an item or condition-name associated with a table element.

Each table element reference must be subscripted except when such reference appears:

  • In a USE FOR DEBUGGING statement
  • As the subject of a SEARCH statement
  • In a REDEFINES clause
  • In the KEY IS phrase of an OCCURS clause
  • In a format 2 SORT statement (table SORT statement)
  • In a LIKE clause

In a format 2 SORT statement, subscripting may be specified with the rightmost subscript being the word ALL.

The lowest permissible occurrence number represented by a subscript is 1. The highest permissible occurrence number in any particular case is the maximum number of occurrences of the item as specified in the OCCURS clause.

Subscripting using data-names

When a data-name is used to represent a subscript, it can be used to reference items within different tables. These tables need not have elements of the same size. The same data-name can appear as the only subscript with one item and as one of two or more subscripts with another item. A data-name subscript can be qualified; it cannot be subscripted or indexed. For example, valid subscripted references to TABLE-THREE, assuming that SUB1, SUB2, and SUB3 are all items subordinate to SUBSCRIPT-ITEM, include:


ELEMENT-THREE (SUB1 SUB2 SUB3)

ELEMENT-THREE IN TABLE-THREE (SUB1 OF SUBSCRIPT-ITEM,
    SUB2 OF SUBSCRIPT-ITEM, SUB3 OF SUBSCRIPT-ITEM)

Subscripting using index-names (indexing)

Indexing allows such operations as table searching and manipulating specific items. To use indexing, you associate one or more index-names with an item whose data description entry contains an OCCURS clause.

An index associated with an index-name acts as a subscript, and its value corresponds to an occurrence number for the item to which the index-name is associated.

The INDEXED BY phrase, by which the index-name is identified and associated with its table, is an optional part of the OCCURS clause. There is no separate entry to describe the index associated with index-name. At run time, the contents of the index corresponds to an occurrence number for that specific dimension of the table with which the index is associated.

The initial value of an index at run time is undefined, and the index must be initialized before it is used as a subscript. An initial value is assigned to an index with one of the following statements:

  • The PERFORM statement with the VARYING phrase
  • The SEARCH statement with the ALL phrase
  • The SET statement

The use of an integer or data-name as a subscript that references a table element or an item within a table element does not cause the alteration of any index associated with that table.

An index-name can be used to reference any table. However, the element length of the table being referenced and of the table that the index-name is associated with should match. Otherwise, the reference will not be to the same table element in each table, and you might get runtime errors.

Data that is arranged in the form of a table is often searched. The SEARCH statement provides facilities for producing serial and nonserial searches. It is used to search for a table element that satisfies a specific condition and to adjust the value of the associated index to indicate that table element.

To be valid during execution, an index value must correspond to a table element occurrence of neither less than one, nor greater than the highest permissible occurrence number.

For more information about index-names, see Index-name and INDEXED BY phrase.

Relative subscripting

In relative subscripting, the name of a table element is followed by a subscript of the form data-name or index-name followed by the operator + or -, and a positive or unsigned integer literal.

The operators + and - must be preceded and followed by a space. The value of the subscript used is the same as if the index-name or data-name had been set up or down by the value of the integer. The use of relative indexing does not cause the program to alter the value of the index.