OCCURS Clause

General Format

OCCURS table-size TIMES

Syntax Rules

table-size is an integer that specifies the number of occurrences of the screen entry.
An OCCURS clause may not be specified for a screen entry that has a level-number of 01.
An OCCURS clause may be subordinate to a group item with an OCCURS clause to create a two-dimensional table. An OCCURS clause may not be nested more than two deep (three dimensional or greater tables are not allowed).
If an OCCURS clause applies to a screen output or update field, then one OCCURS clause specifying the same number of occurrences, or no OCCURS clause at all, must apply to the source item. This OCCURS clause must not include the DEPENDING phrase.
If an OCCURS clause applies to a screen input or update field, then one OCCURS clause specifying the same number of occurrences must apply to the receiving item. This OCCURS clause must not include the DEPENDING phrase.
If a COLOR clause is specified for a screen description entry that contains or is subordinate to an OCCURS clause, that COLOR clause may reference a table of numeric data items. The number of occurrences in the color table must match the number of occurrences in the screen entry.

General Rules

The general rules that apply to an OCCURS clause specified for a data item in the File, Working-Storage, or Linkage sections also apply to an OCCURS Clause.
Each screen entry affected by an OCCURS clause is repeated table-size times.
If line or column numbers are given to screen items in a table, at least one of these numbers should specify relative positioning. If absolute positioning is used, then every occurrence of the screen item will appear in the same place.
If the screen item is an output or an update field, and no OCCURS clauses apply to the sending item, then a DISPLAY verb causes the sending item to be moved to every occurrence of the screen item.
If the screen item is an output or an update field with an OCCURS clause applying to the sending item, then a DISPLAY verb causes each occurrence of the sending item to be moved to the corresponding occurrence of the screen item.
If the screen item is an input or an update field, then an ACCEPT verb causes each occurrence of the screen item to be moved to the corresponding occurrence of the receiving item.

If a COLOR clause that references a table is specified, each occurrence of the table specifies the color for the corresponding occurrence of the screen item. For example:

DATA DIVISION.
WORKING-STORAGE SECTION.

01  DATA-TABLE.
    03  DATA-ELEMENT OCCURS 5 TIMES PIC X(5).

01  COLOR-TABLE.
    03  COLOR-ELEMENT OCCURS 5 TIMES PIC 9(5).

SCREEN SECTION.

01  SCREEN-1.
    03  OCCURS 5 TIMES, USING DATA-ELEMENT 
        COLOR COLOR-ELEMENT.

Examples

Example: Table on One Line

This program accepts a simple table on one line:

IDENTIFICATION DIVISION.
PROGRAM-ID. OCCURS-SAMPLE-1.
DATA DIVISION.
WORKING-STORAGE SECTION.

01  TABLE-1.
    03  TABLE-ITEM OCCURS 5 TIMES     PIC X(5).

SCREEN SECTION.

01  SCREEN-1.
    03  "TABLE ITEMS:".
    03  OCCURS 5 TIMES USING TABLE-ITEM, COLUMN + 2.

PROCEDURE DIVISION.

MAIN-LOGIC.

   DISPLAY WINDOW ERASE.
   DISPLAY SCREEN-1.
   ACCEPT SCREEN-1.
   STOP RUN.

Example: Two-element Table

This program accepts a two-element table, each pair on its own line:

IDENTIFICATION DIVISION.
PROGRAM-ID. OCCURS-SAMPLE-2.

DATA DIVISION.
WORKING-STORAGE SECTION.

01  TABLE-1.
    03  TABLE-GROUP OCCURS 5 TIMES.
        05  ITEM-1    PIC X(5).
        05  ITEM-2    PIC 9(5).

SCREEN SECTION.

01  SCREEN-1.
    03  "TEXT  NUMBER".
    03  OCCURS 5 TIMES.
        05  USING ITEM-1, LINE + 1.
        05  USING ITEM-2, COLUMN + 2.

PROCEDURE DIVISION.
MAIN-LOGIC.
   DISPLAY WINDOW ERASE.
   DISPLAY SCREEN-1.
   ACCEPT SCREEN-1.
   STOP RUN.

Example with Output

You don't have to use a table data-item when you're doing output:

SCREEN SECTION.
01  LINES-SCREEN.
    03  "-" OCCURS 10 TIMES.

This would cause ---------- to be displayed. This is an example of rule 4, where no OCCURS clause applies to the source item.