Creating variable-length tables (DEPENDING ON)
If you do not know before
run time how many times a table
element occurs, define a variable-length table. To do so, use the OCCURS
DEPENDING ON
(ODO) clause.
X OCCURS 1 TO 10 TIMES DEPENDING ON Y
In the example
above, X
is called the ODO subject,
and Y
is called the ODO object.
You can also specify unbounded tables and groups, see Variable-length tables for details.
Two factors affect the successful manipulation of variable-length records:
- Correct calculation of record lengths
The length of the variable portions of a group item is the product of the object of the
DEPENDING ON
phrase and the length of the subject of theOCCURS
clause. - Conformance of the data in the object of the
OCCURS DEPENDING ON
clause to itsPICTURE
clauseIf the content of the ODO object does not match its
PICTURE
clause, the program could terminate abnormally. You must ensure that the ODO object correctly specifies the current number of occurrences of table elements.
The following example shows a group item
(REC-1
) that contains both the subject and object
of the OCCURS DEPENDING ON
clause. The way the length
of the group item is determined depends on whether it is sending or
receiving data.
WORKING-STORAGE SECTION.
01 MAIN-AREA.
03 REC-1.
05 FIELD-1 PIC 9.
05 FIELD-2 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-1 PIC X(05).
01 REC-2.
03 REC-2-DATA PIC X(50).
If you want to move REC-1
(the
sending item in this case) to REC-2
, the length of REC-1
is
determined immediately before the move, using the current value in FIELD-1
.
If the content of FIELD-1
conforms to its PICTURE
clause
(that is, if FIELD-1
contains a zoned decimal
item), the move can proceed based on the actual length of REC-1
.
Otherwise, the result is unpredictable. You must ensure that the ODO
object has the correct value before you initiate the move.
When
you do a move to REC-1
(the receiving item in this
case), the length of REC-1
is determined using the
maximum number of occurrences. In this example, five occurrences of FIELD-2
,
plus FIELD-1
, yields a length of 26 bytes. In this
case, you do not need to set the ODO object (FIELD-1
)
before referencing REC-1
as a receiving item. However,
the sending field's ODO object (not shown) must be set to a valid
numeric value between 1 and 5 for the ODO object of the receiving
field to be validly set by the move.
However,
if you do a move to REC-1
(again the receiving item)
where REC-1
is followed by a variably located group
(a type of complex ODO), the actual length of REC-1
is
calculated immediately before the move, using the current value of
the ODO object (FIELD-1
). In the following example, REC-1
and REC-2
are
in the same record, but REC-2
is not subordinate
to REC-1
and is therefore variably located:
01 MAIN-AREA
03 REC-1.
05 FIELD-1 PIC 9.
05 FIELD-3 PIC 9.
05 FIELD-2 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-1 PIC X(05).
03 REC-2.
05 FIELD-4 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-3 PIC X(05).
The compiler issues a message that lets you know that the actual length was used. This case requires that you set the value of the ODO object before using the group item as a receiving field.
The following example
shows how to define a variable-length table when the ODO object (LOCATION-TABLE-LENGTH
below)
is outside the group:
DATA DIVISION.
FILE SECTION.
FD LOCATION-FILE
RECORDING MODE F
BLOCK 0 RECORDS
RECORD 80 CHARACTERS
LABEL RECORD STANDARD.
01 LOCATION-RECORD.
05 LOC-CODE PIC XX.
05 LOC-DESCRIPTION PIC X(20).
05 FILLER PIC X(58).
WORKING-STORAGE SECTION.
01 FLAGS.
05 LOCATION-EOF-FLAG PIC X(5) VALUE SPACE.
88 LOCATION-EOF VALUE "FALSE".
01 MISC-VALUES.
05 LOCATION-TABLE-LENGTH PIC 9(3) VALUE ZERO.
05 LOCATION-TABLE-MAX PIC 9(3) VALUE 100.
*****************************************************************
*** L O C A T I O N T A B L E ***
*** FILE CONTAINS LOCATION CODES. ***
*****************************************************************
01 LOCATION-TABLE.
05 LOCATION-CODE OCCURS 1 TO 100 TIMES
DEPENDING ON LOCATION-TABLE-LENGTH PIC X(80).
Assigning values to a variable-length table
Loading a variable-length table
Preventing overlay when adding elements to a variable table
Finding the length of data items
OCCURS DEPENDING ON clause
(Enterprise COBOL for z/OS® Language Reference)
Variable-length tables (Enterprise COBOL for z/OS Language Reference)