Variable-Length Tables

Variable-length tables are specified using Format 2 of the OCCURS clause.

Read syntax diagramSkip visual syntax diagram
OCCURS Clause - Format 2 - Variable-Length Tables

>>-OCCURS--integer-1--TO--integer-2--+-------+--DEPENDING--+----+-->
                                     '-TIMES-'             '-ON-'   

>--data-name-1-------------------------------------------------->

   .------------------------------------------------------.   
   V                                                      |   
>----+--------------------------------------------------+-+----->
     |                                  .-------------. |     
     |                                  V             | |     
     '-+-ASCENDING--+--+-----+--+----+----data-name-2-+-'     
       '-DESCENDING-'  '-KEY-'  '-IS-'                        

>--+-----------------------------------+-----------------------><
   |                  .--------------. |   
   |                  V              | |   
   '-INDEXED--+----+----index-name-1-+-'   
              '-BY-'                       

The length of the subject item is fixed; it is only the number of repetitions of the subject item that is variable.
integer-1
The minimum number of occurrences.

The value of integer-1 must be greater than or equal to zero; it must also be less than the value of integer-2.

integer-2
The maximum number of occurrences.
data-name-1
Specifies the object of the OCCURS DEPENDING ON clause; that is, the (integer) data item whose current value represents the current number of occurrences of the subject item. The contents of items whose occurrence numbers exceed the value of the object are unpredictable.

The object of the OCCURS DEPENDING ON clause must not occupy any storage position within the range of any table (that is, any storage position from the first character position in the table through the last character position in the table).

The object of the OCCURS DEPENDING ON clause may not be variably located; the object cannot follow an item that contains an OCCURS DEPENDING ON clause.

At the time that the group item (or any data item that contains a subordinate OCCURS DEPENDING ON item or that follows but is not subordinate to the OCCURS DEPENDING ON item) is referenced, the value of the object of the OCCURS DEPENDING ON clause must fall within the range integer-1 through integer-2. This rule does not apply when the group being referenced is used in a CALL BY REFERENCE statement, provided that the group is not variably-located.

If the OCCURS clause is specified in a data description entry included in a record description entry containing the EXTERNAL clause, data-name-1 must reference a data item possessing the EXTERNAL attribute which is described in the same Data Division.

If the data description entry is subordinate to one containing the GLOBAL clause, data-name-1 must be a global name and must reference a data item which is described in the same Data Division.

When a group item containing a subordinate OCCURS DEPENDING ON item is referred to, the part of the table area used in the operation is determined as follows:
  • If the object is outside the group, only that part of the table area that is specified by the object at the start of the operation will be used.
  • If the object 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 object at the start of the operation will be used in the operation.
  • If the object is included in the same group and the group data item is referenced as a receiving item, the maximum length of the group item will be used in the operation.

When reference modification is applied to a group item containing a variable-length table, reference modification creates a unique data item from the referenced data item. The length of this referenced data item is determined by first applying the previous rules. Subsequently, the rules for reference modification are applied to determine the length of the unique data item.

If a group item containing a variable-length table is used as an argument in the CALL statement USING phrase, the size of the storage for that parameter from the called program's point of view depends on how the argument is passed. If it is passed BY REFERENCE, the maximum size is described by the data description of the argument in the calling program. If it is passed BY CONTENT, the group item is considered as a sending item.

If the group item is followed by a non-subordinate item, the actual length (rather than the maximum length) will be used. At the time the subject of entry is referenced (or any data item subordinate or superordinate to the subject of entry is referenced), the object of the OCCURS DEPENDING ON clause must fall within the range integer-1 through integer-2.

The subject of an OCCURS clause is the data-name of the data item containing the OCCURS clause. The subject of an OCCURS clause may be subordinate to a type-name. Except for the OCCURS clause itself, data description clauses used with the subject apply to each occurrence of the item described.

Subscripting or indexing is required whenever the subject is used in a statement other than SEARCH or USE FOR DEBUGGING, unless it is the object of a REDEFINES clause. In this case, the subject refers to one occurrence within a table element.

Subscripting and indexing are not allowed when the subject is used in a SEARCH or USE FOR DEBUGGING statement, or when it is the object of a REDEFINES clause. In this case, the subject represents an entire table element.

Note that the previous two restrictions do not apply to the LENGTH OF special register.

In one record description entry, any entry that contains an OCCURS DEPENDING ON clause may be followed only by items subordinate to it, or by a level-66 item.

The OCCURS DEPENDING ON clause may not be specified as subordinate to another OCCURS clause.

IBM Extension
IBM Extension

The following constitute complex OCCURS DEPENDING ON:

  • Subordinate items can contain OCCURS DEPENDING ON clauses.
  • Entries containing an OCCURS DEPENDING ON clause can be followed by non-subordinate items. Non-subordinate items, however, cannot be the object of an OCCURS DEPENDING ON clause.
  • The location of any subordinate or non-subordinate item, following an item containing an OCCURS DEPENDING ON clause, is affected by the value of the OCCURS DEPENDING ON object.
  • Entries subordinate to the subject of an OCCURS DEPENDING ON clause can contain OCCURS DEPENDING ON clauses.
  • When implicit redefinition is used in a File Description (FD) entry, subordinate level items can contain OCCURS DEPENDING ON clauses.
  • The INDEXED BY phrase can be specified for a table that has a subordinate item that contains an OCCURS DEPENDING ON clause.

For more information on complex OCCURS DEPENDING ON, see Appendix H. Complex OCCURS DEPENDING ON.

End of IBM Extension
End of IBM Extension

All data-names used in the OCCURS clause may be qualified; they may not be subscripted or indexed.

The OCCURS or OCCURS DEPENDING ON clause cannot be specified in a data description entry that:
  • Has a level number of 01, 66, 77, or 88.
  • Describes a redefined data item. (However, a redefined item can be subordinate to an item containing an OCCURS clause.) See REDEFINES Clause.
The ASCENDING/DESCENDING KEY and INDEXED BY clauses are described under Fixed-Length Tables.
Note: If you use the OCCURS DEPENDING ON clause, the table must contain no more than 16 711 568 occurrences, the length of a table element must be no more than 16 711 568 bytes, and the length of the whole table must be no more than 16 711 568 bytes.
IBM Extension
IBM Extension

Complex OCCURS DEPENDING ON is supported as an extension to the COBOL 85 Standard. The basic forms of complex ODO permitted by the compiler are:

  • A data item described by an OCCURS clause with the DEPENDING ON option is followed by a non-subordinate element or group (variably-located item).
  • A data item described by an OCCURS clause with the DEPENDING ON option is followed by a non-subordinate data item described by an OCCURS clause with the DEPENDING ON option (variably-located table).
  • A data item described by an OCCURS clause with the DEPENDING ON option is nested within another data item described by an OCCURS clause with the DEPENDING ON option (table with variable-length elements).
  • Index-name for a table with variable-length elements.

Complex ODO is tricky to use and can make maintaining your code more difficult. If you choose to use it in order to save disk space, follow the guidelines in Appendix H. Complex OCCURS DEPENDING ON.

End of IBM Extension
End of IBM Extension