OCCURS DEPENDING ON clause

The OCCURS DEPENDING ON clause specifies variable-length tables.

data-name-1
Identifies the object of the OCCURS DEPENDING ON clause; that is, the 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 undefined.

The object of the OCCURS DEPENDING ON clause (data-name-1) must describe an integer data item.

The object of the OCCURS DEPENDING ON clause must not occupy any storage position within the range of the 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 cannot be variably located; the object cannot follow an item that contains an OCCURS DEPENDING ON clause.

If the OCCURS clause is specified in a data description entry included in a record description entry that contains the EXTERNAL clause, data-name-1, if specified, must reference a data item that possesses the external attribute. data-name-1 must be described in the same DATA DIVISION as the subject of the entry.

If the OCCURS clause is specified in a data description entry subordinate to one that contains the GLOBAL clause, data-name-1, if specified, must be a global name. data-name-1 must be described in the same DATA DIVISION as the subject of the entry.

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

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, if integer-2 is specified (that is, if the table is not UNBOUNDED).

The behavior is undefined if the value of the object is outside of the range integer-1 through integer-2.

When a group item that contains 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 is 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 is 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 is used in the operation.

The following statements are affected by the maximum length rule:

  • ACCEPT identifier (format 1 and 2)
  • CALL ... USING BY REFERENCE identifier
  • INVOKE ... USING BY REFERENCE identifier
  • MOVE ... TO identifier
  • READ ... INTO identifier
  • RELEASE identifier FROM ...
  • RETURN ... INTO identifier
  • REWRITE identifier FROM ...
  • STRING ... INTO identifier
  • UNSTRING ... INTO identifier DELIMITER IN identifier
  • WRITE identifier FROM ...

If a variable-length group item is not followed by a nonsubordinate item, the maximum length of the group is used when it appears as the identifier in CALL ... USING BY REFERENCE identifier. Therefore, the object of the OCCURS DEPENDING ON clause does not need to be set unless the group is variably located.

If the group item is followed by a nonsubordinate item, the actual length, rather than the maximum length, is 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, if integer-2 is specified.

Note:

The maximum length rule does not apply to unbounded groups. For unbounded groups, based on the current run time value of the OCCURS DEPENDING ON objects, the actual length of the group is used for all references to the group. Consequently, before any COBOL statement that references an unbounded group runs, you must set the OCCURS DEPENDING ON objects for that group.

Certain uses of the OCCURS DEPENDING ON clause result in complex OCCURS DEPENDING ON (ODO) items. The following items constitute complex ODO items:

  • A data item described with an OCCURS DEPENDING ON clause that is followed by a nonsubordinate elementary data item, described with or without an OCCURS clause
  • A data item described with an OCCURS DEPENDING ON clause that is followed by a nonsubordinate group item
  • A group item that contains one or more subordinate items described with an OCCURS DEPENDING ON clause
  • A data item described with an OCCURS clause or an OCCURS DEPENDING ON clause that contains a subordinate data item described with an OCCURS DEPENDING ON clause (a table that contains variable-length elements)
  • An index-name associated with a table that contains variable-length elements

The object of an OCCURS DEPENDING ON clause cannot be a nonsubordinate item that follows a complex ODO item.

Any nonsubordinate item that follows an item described with an OCCURS DEPENDING ON clause is a variably located item. That is, its location is affected by the value of the OCCURS DEPENDING ON object.

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 about complex OCCURS DEPENDING ON, see Complex OCCURS DEPENDING ON in the Enterprise COBOL Programming Guide.

The ASCENDING KEY phrase, the DESCENDING KEY phrase, and the INDEXED BY clause are described under Fixed-length tables.