The OCCURS Clause

The OCCURS clause eliminates the need for separate entries for repeated data items and supplies information required for the application of subscripts or indices.

General Formats
Format 1
Format 2
Format 3

Directives
  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
Syntax Rules
  1. Where both integer-1 and integer-2 are used, integer-1 must be greater than

    ANS85OSVSor equal to

    zero and integer-2 must be greater than

    OSVSVSC2or equal to

    integer-1.

    OSVSVSC2MFIn Format 2, if "integer-1 TO" is omitted, the default value one is assumed.

  2. The data description of data-name-1 must describe an integer.
  3. Data-name-1, data-name-2, data-name-3, ... can be qualified.
  4. Data-name-2 must be either the name of the entry containing the OCCURS clause or the name of an entry subordinate to the entry containing the OCCURS clause.

    OSVSThis restriction is removed.

  5. Data-name-3, and so on, must be the name of an entry subordinate to the group item which is the subject of this entry.

    OSVSThis restriction is removed.

  6. An INDEXED BY phrase is required if the subject of this entry, or an entry subordinate to this entry, is to be referred to by indexing,

    OSVSVSC2MFunless it is to be indexed by an index defined for another table (see the section Indexing in the chapter Concepts of the COBOL Language)
    .

    The index-name identified by this clause is not defined elsewhere, and not being data, cannot be associated with any data hierarchy.

  7. A data description entry that contains Format 2 of the OCCURS clause should only be followed, within that record description, by data description entries which are subordinate to it.

    OSVSVSC2MFA data description entry that contains Format 2 of the OCCURS clause can be followed, within that record description, by data description entries which are not subordinate to it. When the value of the data item referenced by data-name-1 is changed, the position of data items following, but not subordinate to, the table is changed. The data these items contain can be lost.

    MFIf the NOODOSLIDE Compiler directive is set, all group items containing the table are considered as always having the maximum number of occurrences, irrespective of the value of data-name-1 and therefore the position of the data items following the table is not changed.

  8. The OCCURS clause cannot be specified in a data description entry that:
    1. Has a 66 or 88 level-number
    2. Describes an item whose size is variable. The size of an item is variable if the data description of any subordinate item contains Format 2 of the OCCURS clause.

      OSVSVSC2An OCCURS clause can be specified for a data description subordinate to another item with a Format 2 OCCURS clause.

  9. The OCCURS clause should not be specified in a data description entry at the 01 level or as a 77 level-number.

    MFThis restriction is removed.

  10. In Format 2, the data item defined by data-name-1 must not occupy a character position within the range of the first character position defined by the data description entry containing the OCCURS clause and the last character position defined by the record description entry containing that OCCURS clause.

    OSVSVSC2If the ODOSLIDE Compiler directive is set, data-name-1 must have a fixed location.

  11. If data-name-2 is not the subject of this entry, then:
    1. All of the items identified by the data-names in the KEY IS phrase must be within the group item which is the subject of this entry
    2. Items identified by the data-name in the KEY IS phrase must not contain an OCCURS clause
    3. There must not be any entry that contains an OCCURS clause between the items identified by the data-names in the KEY IS phrase and the subject of this entry.
  12. Index-name-1, index-name-2, ... must be unique words within the source element.

    OSVSIndex-name-1, index-name-2, ... need not be unique and can be qualified by the data-name which is the subject of this entry
    .

  13. OSVSVSC2MFThe OCCURS clause can be specified for external or internal floating-point data items.
  14. ISO2002The KEY clause must not be specified for a data item of class object.
  15. NETThe Format 3 OCCURS clause must be specified in a data description entry at the 01 level.
  16. NETIf the ANY phrase is specifed, it must be specified for all dimensions, whether or not OCCURS is repeated.
  17. NETThe subject of the entry for a Format 3 OCCURS clause must be a .NET native type as specified in the topic .NET Native Types in the section .NET Concepts in the Language Fundamentals chapter.
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

    MF, 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. Data-name-1 must have a fixed location, and must not follow an item that contains an OCCURS DEPENDING ON clause.
  4. 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.

  5. ANS85 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.
  6. 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.
  7. 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.

    Table 1 specifies how storage is allocated for non-recursive programs. Table 2 specifies how storage is allocated for recursive programs.

    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 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
    local storage local storage local storage local storage
    linkage local storage local storage local storage
    Table 2: Storage Allocated for Index-name in Recursive Program
  8. NETAn 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.
  9. NETIf 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.
  10. NETA 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.
  11. NETRepetition 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.