Use the OCCURS clause in the Data Division entry to define a table. The OCCURS clause eliminates the need for separate entries for repeated data items; it also supplies the information necessary for the use of subscripts or indexes. Give the table a group name, then define a subordinate item (the table element) that is to be repeated n times:


While the table element has a collective name, the individual occurrences do not have unique data-names. To refer to them, specify the data-name of the table element, together with the occurrence number of the desired item within the element. The occurring number is called a subscript, and the technique of supplying the occurrence number of individual table elements is called subscripting. A related technique, called subscripting using index-names (indexing) is also available for table references.

A subscript indicates the position of an entry- If You had a one-dimensional table called YEAR-TABLE that contained the 12 months (January through December), the subscript for January would be 1. An index is a symbol used to locate an item in a table. An index differs from a subscript in that an index is a value to be added to the address of a table to locate an item (the displacement from the beginning of the table).

One-Dimensional Table

To create a one-dimensional table, use one OCCURS clause. For example:

One-Dimensional Table

WS-ONEDIM-TABLE is the group item that contains the table. WS-EMP-TABLE names the table element of a one-dimensional table that occurs 10 times.

Two-Dimensional Table

To create tables of more than one dimension, use nested OCCURS clauses. That is, create a table of tables. To create a two-dimensional table, define a one-dimensional table within each occurrence of another one-dimensional table. For example:

Two-Dimensional Table

Two-Dimensional TableWS-TWODIM-TABLE is the name of a two-dimensional table. WS-EMP-TABLE-ROW is an element of a one-dimensional table that occurs 10 times. WS-EMP-TABLE-COL is an element of a two-dimensional table that occurs 5 times within each occurrence of WS-EMP-TABLE-ROW.

Three-Dimensional Table

To create a three-dimensional table, define a one-dimensional table within each occurrence of another one-dimensional table, which is itself contained within each occurrence of another one-dimensional table. For example:

Three-Dimensional Table

For all the tables, the table element definition (which includes the OCCURS clause) is subordinate to the group item that contains the table. Remember that the OCCURS clause cannot appear in a level-01 description. Tables of up to seven dimensions can be defined using this same method.

Referring to an Item in a Table

The items in a table are placed as consecutive entries in storage. The following figure shows the storage layout for the three-dimensional table WS-THREEDIM-TABLE that is defined below

Referring to an Item in a Table

Referring to an Item in a Table

You could define the table items as separate, consecutive entries in the Data Division, but this practice has disadvantages. First, the code does not clearly show the unity of the items. Second, you cannot take advantage of subscripting and Indexing for easy reference to the table elements. In general, when your program refers to a specific table element or to any item associated with a specific table element, the reference must indicate the occurrence of the table element.

Three-Dimensional Table Layout

Three-Dimensional Table Layout

For a one-dimensional table, the occurrence number of the desired element (the row number) gives the complete information. For tables of more than one dimension, an element for each dimension must be supplied. In the three-dimensional table defined above, for example, a reference to WS-EMP-TABLE-COL must supply the occurrence number for WS-EMP-TABLE-PAGE, WS-EMP-TABLE-ROW and WS-EMP-TABLE-COL.

Subscripting, subscripting using index-names (indexing), or a combination of both, can be used to supply the necessary references.


A subscript is an integer that represents an occurrence number of a table-element within a table. The lowest possible subscript value is 1, which points to the first occurrence of the table-element. In a one-dimensional table, the subscript corresponds to the row number. In a two-dimensional table, the two subscripts correspond to the column and row numbers. In a three-dimensional table, the three subscripts correspond to the depth, column, and row numbers.

You can use a literal subscript or a data-name for a variable subscript. A literal subscript must be an integer and must have a value of 1 or greater. For example, valid literal subscript references to WS-THREED1M-TABLE are:

  • TABLE-COLUMN (2, 2,1)
  • TABLE-COLUMN (4 2 1) - The spaces are required for subscripting

In the table reference TABLE-COLUMN (4, 2, 1), the first value (4) refers to the fourth occurrence within WS-EMP-TABLE-PAGE, the second value (2) refers to the second occurrence within WS-EMP-TABLE-ROW, and the third value (1) refers to the first occurrence within WS-EMP-TABLE-COLUMN.

If a subscript is represented by a literal and the subscripted item is of fixed length, then the compiler resolves the location of the subscripted data item within the table at compile time.

The data-name used as a variable subscript must be described as an elementary numeric integer data item. A valid, variable subscript reference to WS-TWODIM-TABLE-2 (assuming that SUB1 and SUB2 are data-names containing positive integer values within the range of the table) would be: WS-EMP-TABLE-COLUMN (SUB1 SUB2)

If a subscript is represented by a data-name, the code generated for the program resolves the location at run time. The most efficient format for data used as a variable subscript is COMPUTATIONAL (COMP) with a PICTURE size of less than five digits.

In relative subscripting, the subscript can be incremented or decremented by a specified integer amount. Relative subscripting is valid with either literal or variable subscripts. For example, WS-EMP-TABLE-COLUMN (SUB1 -1, SUB2 + 3) indicates that the value in data-name SUB1 is to be decremented by one, and the value in data-name SUB2 is to be incremented by three.

Subscripting Using index-Names (indexing)

You can also refer to table elements by using an index. An index |s a displacement from the start of the table, based on the length of the table element. Use the index in SET, SEARCH, SEARCH ALL, PERFORM VARYING, or relational condition statements. An index-name must be initialized through a SET, PERFORM VARYING, or SEARCH ALL statement before it is used in a table reference. The compiler determines the index of an entry based on the following formula:

I = L * (S-1) where 'I* is the index value, 'L' is the length of a table entry and '$' is the subscript (occurrence number) of an entry.

You define the index-name for a table in the INDEXED BY clause of the" OCCURS clause in the table definition. To be valid during execution, an index value must correspond to a table element occurrence of not less than 1 nor greater than the highest permissible occurrence number. This restriction applies to both direct and relative indexing.

In direct indexing, the index-name is in the form of a displacement. The value contained in the index is then calculated as the occurrence number minus 1, multiplied by the length of the individual table entry. For example:


For the fifth occurrence of TABLE-ITEM, the binary value contained in INX-A is (5 -1) * 8 = 32.

In relative indexing, the index-name is followed by a space, followed by a + or a -, followed by another space, followed by an unsigned numeric literal. The literal is considered to be an occurrence number, and is converted to an index value before being added to or subtracted from the index-name. For example, if you specify indexing for THREEDIM-TABLE as follows:

Subscripting Using index-Names (indexing)

Then a relative indexing reference to: TABLE-ROW (INX-A + 1, INX-B + 2, INX-C - 1) causes the following computation of the displacement: (contents of INX-A) + (256 * 1) + (contents of INX-B) + (64 * 2) + (contents of INX-C) - (8*1) That is,

  • Each occurrence of TABLE-DEPTH is 256 characters in length.
  • Each occurrence of TABLE-COLUMN is 64 characters in length.
  • Each occurrence of TABLE-ROW is 8 characters in length.

One or more index references (direct or relative) can be specified together with literal subscripts. To compare two different occurrences of a table element, use a direct indexing reference together with a relative indexing reference, or use subscripting, which is easier to read in your code.

An index can be shared among different tables. That is, you can use the index defined with one table to index another table if both table descriptions are identical. To be identical, the tables must have the same number of occurrences, as well as occurrences of the same length.

You can use index data items to store index values. You can use the SET statement to assign to an index the value that you stored in the index data item. The index data item holds the physical displacement value.

You define an index data item with the USAGE IS INDEX clause.

For example, when you read records to load a variable-length table, you can store the index value of the last record in a data item defined as USAGE IS INDEX. Then, when you use the table index to look through or process the variable-length table, you can test for the end of the table by comparing the current index value with the index value of the last record you stored in the index data item.

Because you are comparing a physical displacement, you can use index data items only in SEARCH and SET statements or for comparisons with indexes or other index data items. You cannot use index data items as subscripts or indexes. Subscripting and Indexing Restrictions The following are the subscripting and indexing restrictions:

  • A data-name must not be subscripted or indexed when it is being used as a subscript or qualifier.
  • An index can be modified only by a PERFORM, SEARCH, or SET statement.
  • When a literal is used in a subscript, it must be a positive or unsigned integer.
  • When a literal is used in relative indexing or relative subscripting, it must be an unsigned integer.

All rights reserved © 2020 Wisdom IT Services India Pvt. Ltd Protection Status

IBM Mainframe Topics