Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 38 ยท Tables and Arrays

Tables with OCCURS

Learn how COBOL builds arrays with the OCCURS clause - table layout in memory, subscripts, loading and reading tables, PERFORM VARYING, REDEFINES tricks and out-of-range bugs.

COBOL has no int[] or list. What other languages call an array, COBOL calls a table, and you create one by adding the OCCURS clause to a data item. A table is a group of identical entries stored one after another in memory. Tables hold things a business program meets all the time: twelve monthly totals, a list of tax brackets, the lines of an invoice.

This lesson shows how to declare a table, how subscripts select an entry, how to fill and walk a table with PERFORM VARYING, and how to pre-load constant values with REDEFINES. We also look at the classic mistake: a subscript that points outside the table.

Declaring a table

OCCURS n TIMES goes on any item below the 01 level. The item and everything under it is repeated n times:

COBOL
       WORKING-STORAGE SECTION.
       01  SALES-TABLE.
           05  MONTH-SALES   PIC 9(5)V99 OCCURS 12 TIMES.

       01  EMPLOYEE-TABLE.
           05  EMPLOYEE OCCURS 50 TIMES.
               10  EMP-ID     PIC 9(5).
               10  EMP-NAME   PIC X(20).
               10  EMP-SALARY PIC 9(6)V99.

MONTH-SALES is twelve numeric fields in a row, 7 bytes each (the V takes no space), so the table occupies 84 bytes. EMPLOYEE is a group that repeats 50 times, and each repetition has an id, a name and a salary: 33 bytes per entry, 1,650 bytes in all. You cannot put OCCURS on a level 01 or 77 item; wrap it in a group instead.

The number in OCCURS is fixed at compile time. If you need a table whose size changes while the program runs, use OCCURS ... DEPENDING ON, covered in multi-dimensional tables and variable length.

Subscripts

You pick an entry by writing a subscript in parentheses after the name. COBOL counts from 1, not 0:

COBOL
           MOVE 1500.00 TO MONTH-SALES (1)
           MOVE 980.50  TO MONTH-SALES (12)
           ADD MONTH-SALES (1) TO YEAR-TOTAL
           DISPLAY EMP-NAME (3)

A subscript can be a literal, a numeric data name, or a simple expression like I + 1 (written with spaces around the operator). The subscript variable is normally an ordinary numeric item such as 01 I PIC 99. Items declared USAGE INDEX are a faster alternative; they are the subject of indexes and SEARCH.

The next picture shows how a table lies in memory: no gaps, no headers, just entry after entry.

flowchart LR
    A["MONTH-SALES (1)<br/>7 bytes"] --> B["MONTH-SALES (2)<br/>7 bytes"] --> C["..."] --> D["MONTH-SALES (12)<br/>7 bytes"]

The compiler finds entry n at offset (n - 1) x entry-length from the start of the table.

That arithmetic is why table access is quick, and also why a wrong subscript is dangerous: nothing in memory marks where the table ends.

Filling and reading a table

Loops over tables are written with PERFORM VARYING. The program below reads twelve sales figures (hard-coded here to stay short), adds them up and finds the best month:

COBOL
       IDENTIFICATION DIVISION.
       PROGRAM-ID. YEARSUM.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  SALES-TABLE.
           05  MONTH-SALES  PIC 9(5)V99 OCCURS 12 TIMES.
       01  I            PIC 99.
       01  YEAR-TOTAL   PIC 9(7)V99 VALUE ZERO.
       01  BEST-MONTH   PIC 99 VALUE 1.
       PROCEDURE DIVISION.
       MAIN.
           PERFORM VARYING I FROM 1 BY 1 UNTIL I > 12
               COMPUTE MONTH-SALES (I) = 1000 + I * 125
               ADD MONTH-SALES (I) TO YEAR-TOTAL
               IF MONTH-SALES (I) > MONTH-SALES (BEST-MONTH)
                   MOVE I TO BEST-MONTH
               END-IF
           END-PERFORM
           DISPLAY "Year total: " YEAR-TOTAL
           DISPLAY "Best month: " BEST-MONTH
           STOP RUN.

With these figures the sales are 1125, 1250, ... 2500, the total is 002175000 (nine digits with no decimal point, because PIC 9(7)V99 stores an implied point) and the best month is 12. Note the loop condition I > 12: after the last pass I becomes 13, so I must be able to hold 13. A PIC 9 would wrap and loop forever; this is why counters are normally two digits larger than the table needs.

The Python block is a stand-in that mimics the same logic with decimal arithmetic. COBOL itself does not run on this site, so it is labelled as a model of the program above, not the real thing.

Python Stand-in: the YEARSUM loop in Python (decimal, 1-based)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The stand-in prints the total with the point removed to imitate how a numeric display field without an edited picture shows an implied decimal point.

Loading constant values with REDEFINES

VALUE is not allowed together with OCCURS in older COBOL, so a table of constants is traditionally built in two steps: a group with ordinary VALUE clauses, and a second description of the same bytes as a table:

COBOL
       01  MONTH-NAME-VALUES.
           05  FILLER PIC X(9) VALUE "JANUARY".
           05  FILLER PIC X(9) VALUE "FEBRUARY".
           05  FILLER PIC X(9) VALUE "MARCH".
      *    ... nine more months ...
       01  MONTH-NAME-TABLE REDEFINES MONTH-NAME-VALUES.
           05  MONTH-NAME PIC X(9) OCCURS 12 TIMES.

REDEFINES makes MONTH-NAME-TABLE another name for the same storage. After this, DISPLAY MONTH-NAME (3) shows MARCH. COBOL 2002 and later (including GnuCOBOL and Enterprise COBOL) also let you put VALUE on a table item, which then initializes every entry, but the REDEFINES pattern is everywhere in existing code, so you must be able to read it.

Python Stand-in: a month-name lookup table built from fixed-width fields

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

INITIALIZE and whole-table operations

You can clear a whole table in one statement. INITIALIZE SALES-TABLE sets numeric entries to zero and alphanumeric entries to spaces. MOVE ZERO TO SALES-TABLE also works but treats the table as one alphanumeric group, which is unsafe for packed-decimal items. A table entry that is itself a group can be moved as a whole: MOVE EMPLOYEE (2) TO EMPLOYEE (1) copies all three fields.

PERFORM n TIMES and inline PERFORM VARYING are both fine for walking a table. Pick the form that keeps the subscript logic visible.

Out-of-range subscripts

Suppose a loop runs UNTIL I > 13 over a 12-entry table. In MONTH-SALES (13) COBOL reads whatever bytes lie after the table, perhaps the next field. There is no exception by default. Two defenses:

  • Compile with subscript checking. GnuCOBOL has -debug; IBM Enterprise COBOL has SSRANGE. A bad subscript then stops the program with a clear message.
  • Test the subscript yourself before using it, especially when it comes from input: IF IDX >= 1 AND IDX <= 12.

Checking is slower, so production builds sometimes turn it off, which is exactly why you validate data first.

An unchecked bad subscript can overwrite other variables and produce wrong totals long after the bug. When a COBOL program prints strange values, check the table bounds first.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the first valid subscript of a COBOL table?

    COBOL tables are one-based. MONTH-SALES (1) is the first entry.
  2. 2. Where can the OCCURS clause NOT be used?

    OCCURS needs a parent. Wrap the repeated item in a 01 group instead.
  3. 3. A table has OCCURS 12 TIMES and a loop uses I PIC 99 with UNTIL I > 12. Why does this work?

    After the last pass I becomes 13, which fits in two digits, so the test I > 12 becomes true. A one-digit counter could not hold 13 and the loop would never end.
  4. 4. Why is REDEFINES used when building a table of constants?

    A group of FILLER items with VALUE clauses is redefined as a table, so the same bytes can be read by subscript.

Summary

  • A table is created with OCCURS n TIMES below the 01 level; entries sit contiguously in memory.
  • Subscripts start at 1 and are written in parentheses: MONTH-SALES (I).
  • Use PERFORM VARYING to walk a table; make the counter large enough to hold the end value plus one.
  • REDEFINES turns a block of VALUE fields into a table of constants.
  • Subscripts are not checked unless you enable it; validate them or compile with range checking.

Next: Indexes and SEARCH