Subscripts

A subscript says which copy of an OCCURS entry to use. It is a number from one to the number of copies, and it is the only thing that stands between a program and the memory next to the table. This lesson is about the ways of computing it and the one check that makes the access safe.

A subscript is a position

A subscript can be a literal or a numeric field, and the two are interchangeable. The table below holds five three-letter codes, and a loop compares each entry with a code it is looking for:

IDENTIFICATION DIVISION. PROGRAM-ID. FIND. DATA DIVISION. WORKING-STORAGE SECTION. 01 CODES-T. 05 CODE-E PIC X(3) OCCURS 5 TIMES. 01 I-F PIC 9 VALUE 0. 01 FOUND-I PIC 9 VALUE 0. 01 SEEK-F PIC X(3) VALUE "C30". 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). PERFORM VARYING I-F FROM 1 BY 1 UNTIL I-F > 5 IF CODE-E(I-F) = SEEK-F MOVE I-F TO FOUND-I END-IF END-PERFORM. IF FOUND-I = 0 DISPLAY "code " SEEK-F " not found" ELSE DISPLAY "code " SEEK-F " at entry " FOUND-I END-IF. MOVE "Z99" TO SEEK-F. MOVE 0 TO FOUND-I. PERFORM VARYING I-F FROM 1 BY 1 UNTIL I-F > 5 IF CODE-E(I-F) = SEEK-F MOVE I-F TO FOUND-I END-IF END-PERFORM. IF FOUND-I = 0 DISPLAY "code " SEEK-F " not found" ELSE DISPLAY "code " SEEK-F " at entry " FOUND-I END-IF. STOP RUN.

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

code C30 at entry 3
code Z99 not found

A search by subscript

Three details make this search work, and each of them is a bug in a program that gets it wrong. The found index starts at zero, which cannot be a subscript of the table and therefore means "not found". The loop runs to the number of entries and not one further. And the found index is cleared before the second search, because otherwise a value from the first search stays in it.

The loop does not stop at the first match: it walks the whole table and the last match wins. For a table of unique codes that is harmless, and it costs one pass over five entries. A table of a thousand entries wants the statement SEARCH, which ends at the first match, and the lesson on SEARCH gives it the same table.

A subscript expression

An arithmetic expression in parentheses is a subscript too. It is how a program reads the entry after the current one, which is the shape of a comparison between neighbours:

IDENTIFICATION DIVISION. PROGRAM-ID. EXPR. DATA DIVISION. WORKING-STORAGE SECTION. 01 NOS-T. 05 NO-E PIC 9(3) OCCURS 4 TIMES. 01 I-F PIC 9 VALUE 1. 01 MAX-N PIC 9 VALUE 4. 01 NEXT-N PIC 9(3). PROCEDURE DIVISION. MOVE 10 TO NO-E(1). MOVE 20 TO NO-E(2). MOVE 30 TO NO-E(3). MOVE 40 TO NO-E(4). PERFORM VARYING I-F FROM 1 BY 1 UNTIL I-F > 3 COMPUTE NEXT-N = NO-E(I-F + 1) DISPLAY "entry " I-F " next " NEXT-N END-PERFORM. MOVE 5 TO I-F. IF I-F > MAX-N DISPLAY "subscript " I-F " is outside 1 to " MAX-N ELSE DISPLAY "entry " I-F " is " NO-E(I-F) END-IF. STOP RUN.

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

entry 1 next 020
entry 2 next 030
entry 3 next 040
subscript 5 is outside 1 to 4

The loop stops at three and not at four, because the expression adds one to the subscript and entry five does not exist. The last value the loop should read is NO-E(3 + 1), so the range of the loop is one shorter than the table: the classic off-by-one of a table walk written in any language.

The guard before the access

The second half of the program is what a program does when the number comes from outside: it compares the subscript with the highest entry before it uses it. The comparison printed a message and the table was not read at all.

A guard is not a substitute for the -debug check of the previous lesson: the guard covers the subscripts the writer thought of, and the checked build covers every subscript in the program. The two belong together, the guard in the shipped code and the check in the test run.

The next lesson makes the table itself variable: a count in the data division says how many of its entries are in use, which is what a program needs when the file it reads has a different number of lines every day.

Exercises

  1. Change SEEK-F to a code that appears twice in the table and see which entry the loop reports. Which one would SEARCH report?
  2. Remove the MOVE 0 TO FOUND-I before the second search and use a code that is not in the table. What does the program print, and why?
  3. Change the loop in the expression program to run to four and build with -debug. What does the run report?
  4. Write a guard for a table of ten entries that accepts a subscript of 1 to 10 and prints a message for anything else, including zero.

Questions

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

  1. Which values can a subscript of a five-entry table take?

    Answer

    One to five

    An OCCURS table is numbered from one to the number of entries, and zero is not an entry.

  2. Why does the search start with the found index at zero?

    Answer

    Zero is not a valid subscript, so it means "not found"

    The program tests the index against zero after the loop and prints the not-found message.

  3. What is wrong with a loop that reads NO-E(I-F + 1) for I-F up to the number of entries?

    Answer

    The last pass reads one entry past the end of the table

    The loop of the page stops one earlier for exactly that reason, and the access past the end is what -debug reports.

  4. What does the guard before a table access do?

    Answer

    It compares the subscript with the highest entry before the access

    The program printed the outside message and did not read the table at all.

  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 4 TIMES. 01 I-F PIC 9 VALUE 0. 01 F-I PIC 9 VALUE 0. PROCEDURE DIVISION. MOVE "AA" TO E-F(1). MOVE "BB" TO E-F(2). MOVE "CC" TO E-F(3). MOVE "DD" TO E-F(4). PERFORM VARYING I-F FROM 1 BY 1 UNTIL I-F IS GREATER THAN 4 IF E-F(I-F) = "CC" MOVE I-F TO F-I END-IF END-PERFORM. DISPLAY F-I. STOP RUN.

    Answer

    3

    CC sits in the third entry, which is the position the loop recorded.

  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 3 TIMES. 01 I-F PIC 9 VALUE 1. PROCEDURE DIVISION. MOVE 1 TO E-F(1). MOVE 2 TO E-F(2). MOVE 4 TO E-F(3). COMPUTE E-F(2) = E-F(1) + E-F(3). DISPLAY E-F(2). STOP RUN.

    Answer

    05

    The computed value is 1 plus 4, written into the second entry of the table.

  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 3 TIMES. 01 I-F PIC 9 VALUE 2. PROCEDURE DIVISION. MOVE 10 TO E-F(1). MOVE 20 TO E-F(2). MOVE 30 TO E-F(3). DISPLAY E-F(I-F) " " E-F(I-F + 1). STOP RUN.

    Answer

    20 30

    The field holds 2, so the two displays read the second and 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 3 TIMES. 01 I-F PIC 9 VALUE 4. 01 M-F PIC 9 VALUE 3. PROCEDURE DIVISION. MOVE 1 TO E-F(1). IF I-F IS GREATER THAN M-F DISPLAY "outside" ELSE DISPLAY "inside " E-F(I-F) END-IF. STOP RUN.

    Answer

    outside

    The guard refuses the subscript before the entry is read, so the table is never touched.

  9. A program searches a table of unique keys and keeps scanning after a match. What is the result?

    Answer

    The same answer, at the cost of a full pass over the table

    With unique keys only one entry can match, so the extra passes change nothing but the time.

  10. Why is a guard not a replacement for a -debug build?

    Answer

    The guard covers the cases the writer thought of; the check covers every access

    A subscript computed in a path nobody guarded is still checked by the run-time bounds test.

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