INDEXED BY and SET

INDEXED BY gives a table a second way of naming an entry: an index, which the compiler keeps beside the table and moves with SET. A subscript is a number the program owns and the compiler reads; an index belongs to the table and the runtime knows it.

An index is a name

The clause goes after the OCCURS on the entry that repeats, and the name it introduces is used in the parentheses where a subscript would go:

IDENTIFICATION DIVISION. PROGRAM-ID. IDXTEST. DATA DIVISION. WORKING-STORAGE SECTION. 01 CODES-T. 05 CODE-E PIC X(3) OCCURS 5 TIMES INDEXED BY IDX. 01 N-F PIC 9 VALUE 2. PROCEDURE DIVISION. MOVE "A10" TO CODE-E(1). MOVE "B20" TO CODE-E(2). MOVE "C30" TO CODE-E(3). MOVE "D40" TO CODE-E(4). MOVE "E50" TO CODE-E(5). SET IDX TO 3. DISPLAY "at three [" CODE-E(IDX) "]". DISPLAY "index prints " IDX. SET IDX UP BY 2. DISPLAY "up by two [" CODE-E(IDX) "]". SET IDX DOWN BY 1. DISPLAY "down by one [" CODE-E(IDX) "]". SET IDX TO N-F. DISPLAY "from field [" CODE-E(IDX) "]". STOP RUN.

cobc -x -free -Wall -o idx idx.cob
./idx

at three [C30]
index prints +000000003
up by two [E50]
down by one [D40]
from field [B20]

DISPLAY of the index itself printed +000000003: an occurrence number in a signed field of the compiler's own choosing. A program that shows an index to a user is showing the runtime representation of it, not a value it declared.

SET TO, UP BY and DOWN BY

SET is the statement that moves an index, and it has three forms: to a value, up by a value and down by a value. The value may be a literal or a numeric field, which is the last line of the run: SET IDX TO N-F moved the index to the second entry because the field holds 2.

The three forms are not interchangeable with a MOVE. The standard defines SET for an index, and this compiler also accepts a MOVE to and from one, which is an extension a program should not rely on: the index is not a PIC 9 field even when it prints like one.

A loop that moves the index

A loop over the table sets the index before the first pass and moves it after the body:

IDENTIFICATION DIVISION. PROGRAM-ID. IDXLOOP. DATA DIVISION. WORKING-STORAGE SECTION. 01 NUMS-T. 05 NUM-E PIC 9(3) OCCURS 4 TIMES INDEXED BY IDX. 01 TOTAL-F PIC 9(5) VALUE 0. PROCEDURE DIVISION. MOVE 10 TO NUM-E(1). MOVE 20 TO NUM-E(2). MOVE 30 TO NUM-E(3). MOVE 40 TO NUM-E(4). SET IDX TO 1. PERFORM UNTIL IDX > 4 ADD NUM-E(IDX) TO TOTAL-F SET IDX UP BY 1 END-PERFORM. DISPLAY "total " TOTAL-F. STOP RUN.

cobc -x -free -Wall -o idxloop idxloop.cob
./idxloop

total 00100

The condition IDX > 4 compares the index with a number, which is allowed. The clause PERFORM VARYING IDX FROM 1 BY 1 UNTIL IDX > 4 also works and does the same thing with one less statement, and the compiler applies the SET rules to the index in that clause.

An index against a subscript

For a table in working storage the two are close: both name an entry, both number from one, both let the program walk the table. The difference is what happens when the table is searched and when it is passed. An index is the only thing SEARCH moves, so a table searched with the verb needs one; and an index belongs to the table, so a program that passes a table to a subprogram passes its index with it, which a numeric subscript cannot do.

The next lesson uses an index for the first time in a SEARCH, which is the statement this clause exists for. The lesson on SEARCH ALL adds the sorted table that a binary search needs.

Exercises

  1. Set the index to 1 and move it down by 1. What does the next read of the table do, and what does a -debug build report?
  2. Write the same loop with PERFORM VARYING IDX FROM 1 and compare the two programs.
  3. Move a value of 9 into the field the last SET uses and run the program. Which entry does it try to read?
  4. Give the table two indexes with INDEXED BY IDX-A IDX-B and use one for the loop and the other for a single entry.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does INDEXED BY add to an OCCURS entry?

    Answer

    A name the program moves with SET and uses as a subscript

    The clause declares an index, which names an occurrence and is moved by SET.

  2. Which statement moves an index?

    Answer

    SET, with TO, UP BY or DOWN BY

    The standard defines SET for an index; this compiler also accepts MOVE, which the page calls an extension.

  3. What does DISPLAY of an index print?

    Answer

    The occurrence number in a signed field of the compiler choosing

    The run printed +000000003 for an index set to the third entry.

  4. Why does SEARCH need an index rather than a numeric subscript?

    Answer

    SEARCH moves the index itself as it walks the table

    The verb changes the index as part of the search, so the table has to have one.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-T. 05 E-F PIC X(2) OCCURS 3 TIMES INDEXED BY I. PROCEDURE DIVISION. MOVE "AA" TO E-F(1). MOVE "BB" TO E-F(2). MOVE "CC" TO E-F(3). SET I TO 2. DISPLAY "[" E-F(I) "]". STOP RUN.

    Answer

    [BB]

    The index names the second entry, so the display reads BB.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-T. 05 E-F PIC 9(2) OCCURS 4 TIMES INDEXED BY I. 01 S-F PIC 9(3) VALUE 0. PROCEDURE DIVISION. MOVE 1 TO E-F(1). MOVE 2 TO E-F(2). MOVE 3 TO E-F(3). MOVE 4 TO E-F(4). SET I TO 1. PERFORM UNTIL I IS GREATER THAN 4 ADD E-F(I) TO S-F SET I UP BY 1 END-PERFORM. DISPLAY S-F. STOP RUN.

    Answer

    010

    The loop adds 1, 2, 3 and 4, which is ten.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-T. 05 E-F PIC 9(2) OCCURS 4 TIMES INDEXED BY I. PROCEDURE DIVISION. MOVE 10 TO E-F(1). MOVE 20 TO E-F(2). MOVE 30 TO E-F(3). MOVE 40 TO E-F(4). SET I TO 1. SET I UP BY 2. DISPLAY E-F(I). STOP RUN.

    Answer

    30

    Starting at one and moving up by two lands on the third entry.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-T. 05 E-F PIC 9(2) OCCURS 4 TIMES INDEXED BY I. PROCEDURE DIVISION. MOVE 10 TO E-F(1). MOVE 20 TO E-F(2). MOVE 30 TO E-F(3). MOVE 40 TO E-F(4). SET I TO 4. SET I DOWN BY 1. DISPLAY E-F(I). STOP RUN.

    Answer

    30

    From the fourth entry one step down is the third, which holds 30.

  9. A table is searched with SEARCH but declared without INDEXED BY. What does the compiler say?

    Answer

    That the entry is not indexed, which is the message 'E-F' not indexed

    SEARCH moves an index, so an OCCURS without INDEXED BY has nothing for it to move.

  10. Why is an index not the same as a PIC 9 field?

    Answer

    It belongs to the table and the runtime keeps it, while the field is the program data

    SET and SEARCH maintain the index as table metadata, and passing the table passes its index with it.

The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev