The OCCURS Clause

General Rules

1. The OCCURS clause is used in defining tables and other homogenous sets of repeated data items. Whenever the OCCURS clause is used, the data-name which is the subject of this entry must be either subscripted or indexed whenever it is referred to in a statement other than SEARCH

    , SORT

   or USE FOR DEBUGGING. Further, if the subject of this entry is the name of a group item, then all data-names belonging to the group must be subscripted or indexed whenever they are used as operands, except as the object of a REDEFINES clause. (See the topics Subscripting, Indexing and Identifier in the chapter Concepts of the COBOL Language.)

2. Except for the OCCURS clause itself, all data description clauses associated with an item whose description includes an OCCURS clause apply to each occurrence of the item described.
3. UNBOUNDED can be used to specify an unbounded table (a table with an unbounded maximum number of occurrences), and can be referenced anywhere that a table can be referenced.
4. An unbounded group is a group that contains at least one unbounded table. It can be specified only in the Linkage Section, and must be of type alphanumeric or national.
5. You can reference unbounded groups in COBOL syntax anywhere that an alphanumeric or national group can be referenced, with the following exceptions:
   • You cannot specify unbounded groups as a BY CONTENT argument in a CALL statement.
   • You cannot specify unbounded groups as data-name-2 on the Procedure Division RETURNING phrase.
   • You cannot specify unbounded groups as arguments to intrinsic functions, except as an argument to the LENGTH intrinsic function.
6. Data-name-1 must have a fixed location, and must not follow an item that contains an OCCURS DEPENDING ON clause.
7. The number of occurrences of the subject entry is defined as follows:
   1. In Format 1, the value of integer-2 represents the exact number of occurrences.
   2. In Format 2, the current value of the data item referenced by data-name-1 represents the number of occurrences.

      This format specifies that the subject of this entry has a variable number of occurrences. The value of integer-2 represents the maximum number of occurrences and the value of integer-1 represents the minimum number of occurrences. This does not imply that the length of the subject of the entry is variable, but that the number of occurrences is variable.

      The value of the data item referenced by data-name-1 must fall within the range of integer-1 through integer-2. Reducing the value of this data item makes the contents of data items, whose occurrence numbers now exceed the value of the data item referenced by data-name-1, unpredictable.

8.   When a group item, having subordinate to it an entry that specifies Format 2 of the OCCURS clause, is referenced, the part of the table area used in the operation is determined as follows:
   1. If the data item referenced by data-name-1 is outside the group, only that part of the table area that is specified by the value of the data item referenced by data-name-1 at the start of the operation is used.
   2. If the data item referenced by data-name-1 is included in the same group and the group data item is referenced as a sending item, only that part of the table area that is specified by the value of the data item referenced by data-name-1 at the start of the operation is used in the operation. If the group is a receiving item, the maximum length of the group is used.
9. The KEY IS phrase is used to indicate that the repeated data is arranged in ascending or descending order according to the values contained in data-name-2, data-name-3, and so on. The ascending or descending order is determined according to the rules for comparison of operands (see the topics Comparison of Numeric Operands and Comparison of Nonnumeric Operands in the topic Relation Condition in the chapter Procedure Division). The data-names are listed in their descending order of significance.
10. The type of storage allocated for index-name-1, index-name-2... depends on whether or not the program is recursive (that is, has a Local-Storage Section defined) and whether the REENTRANT Complier directive has been specified.

    The first of the tables below specifies how storage is allocated for non-recursive programs. The second table specifies how storage is allocated for recursive programs.

    Table 1. Storage Allocated for Index-name in Non-Recursive Program

    Index-name Defined in	Index-name Allocated in
    	NOREENTRANT	REENTRANT (1)	REENTRANT (2)
    working storage	working storage	working storage	thread-local
    thread-local	thread-local	thread-local	thread-local
    linkage	working storage	local storage	local storage

    Table 2. Storage Allocated for Index-name in Recursive Program

    Index-name Defined in	Index-name Allocated in
    	NOREENTRANT	REENTRANT (1)	REENTRANT (2)
    working storage	working storage	working storage	thread-local
    thread-local	thread-local	thread-local	thread-local
    local storage	local storage	local storage	local storage
    linkage	local storage	local storage	local storage

11.  An entry with a Format 3 OCCURS clause defines an array that is mapped directly to a .NET native array. In COBOL, the first array element has the subscript one.
12.  If the ANY phrase is specified, a SET statement with either the SIZE phrase or the CONTENT phrase must be executed on the array before an element of the array can be referenced.
13.  A Format 3 OCCURS clause that repeats the option containing ANY and integer-2 defines a rectangular array, one in which all rows and columns have the same size.
14.  Repetition of the Format 3 OCCURS clause defines a jagged array, or an array of arrays in which the various sub-arrays can have different lengths.