Function
The OCCURS clause is used to define tables. It specifies how many elements a table is to have, i.e. how often a data item is to recur. All elements have the same format. The size of the table may be variable. Furthermore, indices can be supplied.
Format 1 | specifies the exact number of occurrences of a data item. |
Format 2 | specifies a variable number of occurrences of a given data item, ranging between a maximum and a minimum number of occurrences. |
Format 1
OCCURS integer-2 TIMES
[{ASCENDING | DESCENDING} KEY IS {data-name-2}... ] ...
[INDEXED BY {index-1}...]
Format 2
OCCURS [integer-1 TO] integer-2 TIMES DEPENDING ON data-name-1
[{ASCENDING | DESCENDING} KEY IS {data-name-2}... ] ...
[INDEXED BY {index-1}...]
Syntax rules for both formats
The OCCURS clause must not be specified in a data description entry that:
has a level number of 01, 66, 77 or 88, or
describes an item whose size is variable (the size of an item is variable if the data description entry of any item subordinate to it contains an OCCURS clause with the DEPENDING phrase).
data-name-1, data-name-2,... may be qualified with OF or IN (see section "Qualification").
data-name-2 may either be the subject of the OCCURS clause (in which case data-name-2,... must be specified at first), or it must be subordinate to the group item referenced by the OCCURS clause.
If data-name-2 does not match the subject of the OCCURS clause, data-name-2 must not be described with an OCCURS clause. Furthermore, it must not be subordinate to an entry which contains an OCCURS clause.
data-name-2 is subject to the following additional rules:
Up to 12 key fields may be specified for a given table element.
The sum of the lengths of all key fields associated with a table element must not exceed 256 bytes.
The key fields may not be of the class object or pointer.
The OCCURS clause may not be specified together with an IDENTIFIED clause or in an entry which is directly subordinate to an entry with an IDENTIFIED clause.
Syntax rules for format 2
integer-1 must be a positive integer or 0.
When used together, integer-1 must be less than integer-2.
data-name-1 must be defined as an integer numeric data item.
If data-name-1 appears in the same record as the table whose occurrences it controls, it must appear before the variable portion of that record. In other words, the data item defined by data-name-1 must precede the record portion described by the OCCURS clause with the DEPENDING ON phrase.
If the OCCURS clause is specified in a data description entry included in a record description entry containing the EXTERNAL or GLOBAL clause, data-name-1, if specified, must reference a data item possessing the EXTERNAL or GLOBAL attribute which is described in the same Data Division.
A data description entry containing an OCCURS clause with the DEPENDING ON phrase may only be followed, within that record description, by data description entries which are subordinate to it. The COBOL2000 compiler also allows data description entries which are independent of data hierarchy (see general rule 15).
The OCCURS clause may not be specified in the record description of a file with organization XML.
Any entry that contains an OCCURS clause with the DEPENDING ON phrase, or has a subordinate entry with an OCCURS... DEPENDING ON clause, must not contain a REDEFINES clause.
General rules for both formats
integer-2 represents the exact number of occurrences.
Except for the OCCURS clause itself, all data description clauses associated with the item whose description contains that OCCURS clause apply to each occurrence of the item described.
The subject of an OCCURS clause must be indexed or subscribed whenever it is referenced in a statement.
Exception: SEARCH and SORT (Format 2) statement.
If the subject is the name of a group item, then all data-names belonging to the group must be indexed or subscribed whenever they are used as operands.
An indexed or subscribed data-name references one particular table element. When used in a SEARCH and SORT (Format 2) statement, the data-name refers to the entire table.
The ASCENDING/DESCENDING phrase in conjunction with the INDEXED BY phrase is used in the execution of a SEARCH ALL and SORT (Format 2) statement.
Before an index-name may be used as an index, it must be initialized (using a SET, SEARCH ALL or PERFORM statement with VARYING phrase).
The ASCENDING/DESCENDING KEY phrase defines whether the elements in the table are to be arranged in ascending or descending order, according to the values contained in data-name-2. The data-names must be listed in descending order of significance. This order is presupposed in the SEARCH ALL statement (In this case the user is responsible for seeing that the table elements are sorted properly).
The INDEXED BY phrase indicates that indexing may be used to reference the data-name which is the subject of the OCCURS clause, or any entry subordinate to that data-name. The storage allocation and format for such defined indices are automatically defined by the compiler.
Each index contains a binary value that represents a displacement from the beginning of the table, corresponding to an occurrence number. The value is calculated as the occurrence number minus one, multiplied by the length of the entry that is indexed by the index-name (see "Indexing").
If a data item within a table element requires a particular alignment, the compiler ensures that this alignment also applies for every repetition of the table element (see section "Implementor-dependent representation and alignment of data").
General rules for format 2
integer-1 and integer-2 specify the minimum and maximum number of occurrences, respectively. The value of the data item referenced by data-name-1 must range between integer-1 and integer-2.
During an access to the table the current value of data-name-1 must not exceed that of integer-2.
When used in the DEPENDING ON phrase of the OCCURS clause for a data area of variable length, data-name-1 must be supplied with a value before this area is used in a MOVE operation as a sending or receiving item. The same data-name-1 may be used by the sending and receiving items (see Example 7-8).
The DEPENDING ON phrase specifies that the data item described by the OCCURS clause has a variable number of occurrences. The number of occurrences is controlled at object time by the value of data-name-1.
When reference is made to a group item to which an entry with an OCCURS DEPENDING ON clause is subordinate, the part of the table area used in the operation is determined as follows:
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 will be used.
If no other entries are subordinate to the group item and the content of data-name-1 is 0, the group item is a zero-length item.
If only entries which are defined with an OCCURS clause with DEPENDING ON phrase are subordinate to the group item and the content of all data items identified by data-name-1 is 0, the group item is a zero-length item.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 will be used in the operation. If the group is a receiving item, the maximum length of the group will be used.
If, within a record description entry, a data area follows data items with the DEPENDING ON phrase, but is not subordinate to those items, then its position depends on the current values of data-name-1 in the preceding DEPENDING ON phrases.
If the value of data-name-1 is changed (i.e. change of table length), the position of these data areas are shifted accordingly. However, their original contents are not shifted (see Example 7-8).
If the value of data-name-1 is reduced at object time, the contents of the data items with occurrence numbers greater than the new value of data-name-1 are undefined.
Example 7-8
Supplying a value to data-name-1 in OCCURS DEPENDING ON, using a MOVE operation. Given the following data definition:
WORKING-STORAGE SECTION.
01 ITEM-A.
02 COUNTER-A PIC 9.
02 DATA-AVALUE "ABCDEFGHI".
03 CHARACTER-A PIC X OCCURS 1 TO 9
DEPENDING ON COUNTER-A.
01 ITEM-B.
02 COUNTER-B PIC 9.
02 DATA-B.
03 CHARACTER-B PIC X OCCURS 1 TO 9
DEPENDING ON COUNTER-B.
The following MOVE operations are to be performed:
Case a) Sending item longer than receiving item
MOVE 6 TO COUNTER-A,
MOVE 3 TO COUNTER-B,
MOVE ITEM-A TO ITEM-B.
Contents following MOVE operation:
ITEM-A: 6ABCDEF
ITEM-B: 6ABCDEF
MOVE DATA-A TO DATA-B would result in:
ITEM-A: 6ABCDEF
ITEM-B: 3ABC
Case b) Sending item shorter than receiving item (contents of both items as they were before case a)
MOVE 3 TO COUNTER-A,
MOVE 6 TO COUNTER-B,
MOVE ITEM-A TO ITEM-B.
ITEM-A: 3ABC
ITEM-B: 3ABC
MOVE DATA-A TO DATA-B would result in:
ITEM-A: 3ABC
ITEM-B: 6ABC'BLANK''BLANK''BLANK
The MOVE operations proceed according to the rules for alphanumeric moves (see "MOVE statement").
Example 7-9
OCCURS DEPENDING ON data-name-1
Given the following data definition:
WORKING-STORAGE SECTION.
01 DATA-RECORD.
02 TABLE1.
03 LEN PIC 9.
03 TAB-ELEM PIC X OCCURS 1 TO 9
DEPENDING ON LEN.
02 ITEM PIC X.
If the current value of LEN is 9, the following starting position of the items results:
DATA-RECORD | TABLE | LEN | 9 |
ELEM (1) | A | ||
B | |||
ELEM (9) | I | ||
ITEM | J | ||
After MOVE 1 TO LEN
the length of the table and hence the position of ITEM is changed:
DATA-RECORD | TABLE | LEN | 1 |
ELEM (1) | A | ||
ITEM | B | ||
currently unused portion of DATA-RECORD | . . H I J | ||
The data item LEN now has the value 1; the data item ITEM has the value B.