OCCURS: a fixed table
A table in COBOL is a field with OCCURS, and a table is the same bytes as the fields it replaces: there is no header, no length and no object. That is why a table can be moved, written and read as one block, and why the language cannot tell a good subscript from a bad one.
OCCURS n TIMES
The clause goes on the entry that repeats and names how many copies there are. The entry is used with a subscript in parentheses, and the copies are numbered from one:
IDENTIFICATION DIVISION.
PROGRAM-ID. TABLE.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 AMOUNTS-T.
05 AMOUNT-E PIC 9(4) OCCURS 5 TIMES.
01 I-F PIC 9 VALUE 0.
01 TOTAL-F PIC 9(6) VALUE 0.
01 AVG-F PIC 9(4).
PROCEDURE DIVISION.
MOVE 120 TO AMOUNT-E(1).
MOVE 80 TO AMOUNT-E(2).
MOVE 250 TO AMOUNT-E(3).
MOVE 40 TO AMOUNT-E(4).
MOVE 110 TO AMOUNT-E(5).
PERFORM VARYING I-F FROM 1 BY 1 UNTIL I-F > 5
DISPLAY "amount " I-F " = " AMOUNT-E(I-F)
ADD AMOUNT-E(I-F) TO TOTAL-F
END-PERFORM.
COMPUTE AVG-F = TOTAL-F / 5.
DISPLAY "total " TOTAL-F " average " AVG-F.
DISPLAY "table bytes " LENGTH OF AMOUNTS-T.
STOP RUN.
cobc -x -free -Wall -o table table.cob
./table
amount 1 = 0120
amount 2 = 0080
amount 3 = 0250
amount 4 = 0040
amount 5 = 0110
total 000600 average 0120
table bytes 20
A subscript, from one
The first entry is AMOUNT-E(1) and the last is (5). A subscript may be a literal, a numeric field or an arithmetic expression in parentheses, and it is evaluated before the entry is used. In the loop the subscript is I-F, which the PERFORM VARYING moves from 1 to 5.
There is no entry zero. A program that fills a table from a file usually keeps a separate count of how many entries it has written, because the table itself is always five entries long and the unused ones stay at whatever the last run left there.
The bytes the table takes
LENGTH OF AMOUNTS-T is 20: five entries of four digits each, with no padding and no separator. The group that holds the table is the same 20 bytes, so a MOVE AMOUNTS-T TO OUT-REC copies the whole table in one statement, and a file written from it is a block of twenty bytes.
That is why a table belongs in a file layout more often than a series of separate fields: it is already the shape of the record. The next lessons add the variable length with OCCURS DEPENDING ON, an index of its own with INDEXED BY, and the searches that use them.
A subscript outside the table
A loop written with a wrong limit reads past the end of the table, and the plain build says nothing: the bytes after the table are read as if they were entry four of a table of three.
IDENTIFICATION DIVISION.
PROGRAM-ID. OUTSIDE.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 VALUES-T.
05 VALUE-E PIC 9(2) OCCURS 3 TIMES.
01 I-F PIC 9 VALUE 0.
PROCEDURE DIVISION.
MOVE 11 TO VALUE-E(1).
MOVE 22 TO VALUE-E(2).
MOVE 33 TO VALUE-E(3).
PERFORM VARYING I-F FROM 1 BY 1 UNTIL I-F > 4
DISPLAY "entry " I-F " = " VALUE-E(I-F)
END-PERFORM.
STOP RUN.
cobc -x -free -Wall -o outside outside.cob
./outside | cat -v
entry 1 = 11
entry 2 = 22
entry 3 = 33
entry 4 = ^@^@
cat -v shows the two bytes the program read as ^@^@: they are not digits, and DISPLAY wrote them anyway. The run exited with status zero. A program built with -debug checks the subscript and stops with a message instead:
cobc -x -free -Wall -debug -o outsidedbg outside.cob
./outsidedbg
entry 1 = 11
entry 2 = 22
entry 3 = 33
libcob: outside.cob:15: error: subscript of 'VALUE-E' out of bounds: 4
note: maximum subscript for 'VALUE-E': 3
Last statement of "OUTSIDE" was DISPLAY at line 15 of outside.cob
ENTRY OUTSIDE at outside.cob:11
Started by ./outsidedbg
The check costs a build flag and a slower run, and it turns a wrong subscript into a message with the field, the value and the line. The lesson on debug builds covers the rest of what -debug checks; for a program that walks tables, the flag belongs in every test run.
Exercises
- Change the table to OCCURS 10 TIMES and print LENGTH OF it. How many bytes does each entry take now?
- Fill the five amounts with a PERFORM VARYING that computes each value from the subscript. What is the total now?
- Add a sixth amount to the table and print the entry five times. Which entries change?
- Build the out-of-range program without -debug and with it, and compare what a user of each sees.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is the first subscript of an OCCURS table?
Answer
One
The entries are numbered from one to the number of OCCURS copies.
-
What does LENGTH OF return for a group of five PIC 9(4) entries?
Answer
20 bytes
Five entries of four bytes each are twenty bytes with no padding.
-
What happens when a plain build reads a subscript past the end of a table?
Answer
It reads the bytes after the table and reports nothing
The run printed ^@^@ and exited with status zero, because nothing checks the subscript without -debug.
-
What does building with -debug add?
Answer
Run-time checks such as the subscript bounds, with a message that names the field
The checked run printed the field name, the value and the line number before it stopped.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-T. 05 E-F PIC 9(2) OCCURS 3 TIMES. 01 I-F PIC 9 VALUE 0. PROCEDURE DIVISION. MOVE 5 TO E-F(1). MOVE 6 TO E-F(2). MOVE 7 TO E-F(3). PERFORM VARYING I-F FROM 1 BY 1 UNTIL I-F IS GREATER THAN 3 DISPLAY E-F(I-F) END-PERFORM. STOP RUN.Answer
05 / 06 / 07
Each entry is two digits wide, and the loop prints them in order from one.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-T. 05 N-F PIC 9(3) OCCURS 4 TIMES. 01 I-F PIC 9 VALUE 0. 01 S-F PIC 9(5) VALUE 0. PROCEDURE DIVISION. PERFORM VARYING I-F FROM 1 BY 1 UNTIL I-F IS GREATER THAN 4 MOVE I-F TO N-F(I-F) ADD N-F(I-F) TO S-F END-PERFORM. DISPLAY S-F. STOP RUN.Answer
00010
The entries hold 1, 2, 3 and 4, and their sum is ten.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-T. 05 E-F PIC X(2) OCCURS 3 TIMES. PROCEDURE DIVISION. MOVE "AB" TO E-F(2). DISPLAY "[" E-F(1) "][" E-F(2) "][" E-F(3) "]". STOP RUN.Answer
[ ][AB][ ]
Only the second entry was filled, and the other two keep their spaces.
-
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 0. 01 C-F PIC 9 VALUE 0. PROCEDURE DIVISION. MOVE 9 TO E-F(1). MOVE 8 TO E-F(2). MOVE 7 TO E-F(3). PERFORM VARYING I-F FROM 3 BY -1 UNTIL I-F IS LESS THAN 1 ADD 1 TO C-F END-PERFORM. DISPLAY C-F " [" E-F(1) "]". STOP RUN.Answer
3 [09]
The loop counts down through three subscripts, and the display reads the first entry, which is untouched by the loop.
-
A table of four entries is filled from a file and the program prints five entries. What does a plain build do?
Answer
It prints one entry of bytes that were never part of the table
Only -debug checks the bounds; the plain build reads whatever follows the table.
-
Why can a whole table be moved with one MOVE?
Answer
The table is a block of bytes with no header or separators
LENGTH OF the group is the twenty bytes of its entries, so a group move copies exactly them.
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