ILE COBOL Language Reference

Subscripting

Subscripting is a method of providing table references through the use of positive integers. A subscript is a positive integer (or integer data item) whose value specifies the occurrence number of a table element.

Subscripting - Format
 
                         .-------------------------.
                         V                         |
>>-+-condition-name-1-+----+---------------------+-+------------>
   '-data-name-1------'    '-+-IN-+--data-name-2-'
                             '-OF-'
 
>--+---------------------+-------------------------------------->
   '-+-IN-+--file-name-1-'
     '-OF-'
 
      .----------------------------------------.
      V                                        |
>--(----+-integer-1--------------------------+-+--)------------><
        +-ALL--------------------------------+
        +-data-name-3--+------------------+--+
        |              '-+-+-+--integer-2-'  |
        |                '---'               |
        '-index-name-1--+------------------+-'
                        '-+-+-+--integer-3-'
                          '---'
 
 
condition-name-1
Must be subordinate to a data description entry which contains an OCCURS clause.
data-name-1
Must contain an OCCURS clause or must be subordinate to a data description entry which contains an OCCURS clause.
integer-1
Can be signed. If signed, it must be positive.
ALL

Used as a function argument for a function that allows a variable number of arguments. Can be used only when the subscripted identifier is used as a function argument and can not be used when condition-name is specified.
data-name-3
Must be a numeric elementary item representing an integer.

Data-name-3 can be qualified.

index-name-1
Corresponds to a data description entry in the hierarchy of the table being referenced which contains an INDEXED BY phrase specifying the index-name.
integer-2, integer-3
Must be an unsigned integer.

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 containing 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 multi-dimensional 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)

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 a reference appears:

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.

Related Information:

Subscripting Using Integers or Data-Names

When an integer or 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 integer or 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, which identifies the index-name associated with its table, is an optional part of the OCCURS clause. There is no separate entry to describe the index-name since its definition is completely system dependent. Index-names may be seen as compiler generated registers for the use of this program only. They are not data, or part of the data hierarchy, and must be unique in a COBOL program.

Each index name must follow the rules for formation of a user-defined word.

Each index-name refers to a compiler-generated register or storage area.

The initial value of an index at object time is undefined, and the index must be initialized before it is used as a subscript. The initial value of an index is assigned with:

An index-name can only be referenced by a PERFORM, SET, or SEARCH statement, as a parameter in the USING phrase in a CALL statement, or in a relational condition comparison.

The use of an integer or data-name as a subscript referencing 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 only the table to which it is associated by the INDEXED BY phrase.

Data that is arranged in the form of a table is often searched. The SEARCH statement provides facilities for producing serial and non-serial (for example, binary) 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.

Further information on index-names is given in the description of the INDEXED BY phrase of the OCCURS clause. See 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 an unsigned integer literal. The operator + and - must be preceded and followed by a space. If the subscript contains a data-name, the value of the subscript is the same as if the data-name had been set up or down by the value of the integer. If the subscript contains an index-name, the integer is considered to be an occurrence number, and is converted to an index value before being added to or subtracted from the index-name. The use of relative indexing does not cause the object program to alter the value of the index.

The value of an index can be made accessible to an object program by storing the value in an index data-item. Index data-items are described in the program by a data description entry containing a USAGE IS INDEX clause. The index value is moved to the index data-item by the execution of a SET statement.

A valid index value must correspond to a table element occurrence of not less than one, nor greater than the highest permissible occurrence number.

Further information on index-names is given in the description of the INDEXED BY phrase of the OCCURS clause. See INDEXED BY Phrase.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]