Variable-Length Tables
Variable-length tables are specified using Format 2 of the OCCURS clause.
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-'
- 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.
- 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.
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 ExtensionAll data-names used in the OCCURS clause may be qualified; they may not be subscripted or indexed.
- 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.
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