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:

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

The following constitute complex OCCURS DEPENDING ON:

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

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:
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

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:

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