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 the OCCURS clause.

  • Conformance of the data in the object of the OCCURS DEPENDING ON clause to its PICTURE clause

    If 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).

related concepts  
Complex OCCURS DEPENDING ON

related references  
OCCURS DEPENDING ON clause
(Enterprise COBOL for z/OS® Language Reference)  
Variable-length tables (Enterprise COBOL for z/OS Language Reference)