CREATING VARIABLE-LENGTH TABLES - IBM Mainframe

If you do not know before execution how many occurrences of a table element there are, you need to set up a variable-length table definition. To dothis, use the OCCURS DEPENDING ON (ODO) clause. There are three different cases to consider when using the ODO clause:

  • ODO object is outside of the group item that contains the subject
  • ODO object and subject are contained within the same group item, and that item is a sending field
  • ODO object and subject are contained within the same group item, and that item is a receiving field.

ODO Object Outside the Group

You must ensure that the object of the OCCURS DEPENDING ON clause (which specifies the number of occurrences of the table elements) contains a value that correctly specifies the current number of occurrences of the table elements. Tine following code shows how to define a variable-length table.

ODO Object Outside the Group

Two factors that affect the successful manipulation of variable-length records are the correct calculation of records lengths, and the conformance of the data in the OCCURS...DEPENDING ON object to its picture. If you are using variable-length records in either a READ...INTO or WRITE...FROM statement, in conjunction with an OCCURS...DEPENDING ON statement, make sure that the receiver or intermediate field length is correct. The length of the variable portions of a group item is the product of the object of the DEPENDING ON option and the length of the subject of the OCCURS clause. If the content of the ODO object does not match its PICTURE clause, the program may abend.

ODO Object and Subject Contained in Sending Group Item

The following example illustrates a group item (WS-REC-ONE) whose subordinate items contain an OCCURS clause with the DEPENDING ON option and the object of that DEPENDING ON option.

ODO Object and Subject Contained in Sending Group Item

If you want to move WS-REC-ONE to WS-REC-TWO, the length of WS-REC-ONE is determined immediately prior to the MOVE, using the current value in WS-FIELD-ONE. If the contents of WS-FIELD-ONE do not conform to its PICTURE clause, that is, if WS-FIELD-ONE does not contain an external decimal item, the program will abend. As you can see, you must be sure that in this situation you have the correct value placed in the ODO object (WS-FIELD-ONE) before the MOVE is initiated.

ODO Object and Subject Contained in Receiving Group Item

The following example illustrates a group item (MAIN-AREA) whose subordinate items contain an OCCURS clause with the DEPENDING ON option and the object of that DEPENDING ON option.

ODO Object and Subject Contained in Receiving Group Item

If you want to do a MOVE to WS-REC-TWO, the length of WS-REC-TWO is determined using the maximum number of occurrences. In this example, that would be 5 occurrences of WS-FIELD-FOUR plus WS-FIELD-THREE for a length of 26. In this case, the ODO object (WS-FIELD-THREE) need not be set before referencing WS-REC-TWO as a receiving item. However, if a data item, which is in the same record but is not subordinate to WS-REC-TWO, then the actual length of WS-REC-TWO, followed WS-REC-TWO is used and the ODO object must be set before the reference. In the following example, WS-REC-TWO is followed by WS-REC-THREE.

WS-REC-TWO is followed by WS-REC-THREE.

If you do a MOVE to WS-REC-TWO in this case, the actual length of WS-REC-TWO would be calculated immediately prior to the move using the current value of the ODO object (WS-FIELD-THREE), and a compiler message would be issued letting you know that the actual length, instead of the maximum length, was used. This case requires that you set the value of the ODO object (WS-FIELD-THREE) prior to using the item as a receiving field.

Complex OCCURS DEPENDING ON (ODO)

There are three basic forms of complex ODO permitted by the compiler:

  • A data item described by an OCCURS clause with the DEPENDING ON option is followed by a non-subordinate item. The non-subordinate item is variably located.
  • 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.
  • 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.

If a group item contains both the subject and object of the ODO and it is1 a receiving item, then the maximum length of the item is used. In this situation, it is not necessary to set the value of the ODO object before a reference is made. If the receiving item is followed by a data item which is in the same record but is not subordinate to the receiver, then the actual length is used and a compiler message is issued to inform you that the actual length, not the maximum, will be used in this situation, it is necessary to set the value of the ODO object before any reference to the item.

All other cases of ODO objects in a 01-level must be set before any reference is made to a complex ODO item in the 01-level. (Note: An ODO object cannot be variably located.) For instance, in the following example, before WS-EMPLOYEE-NUMBER can be referred to, WS-COUNTER-1 and WS-COUNTER-2 must be set, even though WS-EMPLOYEE-NUMBER does not directly depend on either of the ODO objects for its value. The length of the variable portions of each record is the product of the ODO object and the length of the subject of the OCCURS clause. Any item that meets one of these five criteria is considered to be a 'complex ODO item.' The length is calculated at the time of a reference to one of the following:

  • A group item of variable length
  • A data item following, and not subordinate to, a variable-length table in the same level-01 record (variably located item)
  • A group item following, and not subordinate to, a variable-length table in the same level-01 record (variably located group)
  • An index name for a table that has variable-length elements
  • An element of a table that has variable-length elements

The following example illustrates each of the possible occurrences of a complex ODO item:

each of the possible occurrences of a complex ODO item

Explanation:

  • WS-FIELD-A. - The group item of variable length
  • 10 WS-EMPLOYEE-NUMBER PIC X(5). - The data item following, and not subordinate to, a variable-length table in the same level-01 record (variably located item)
  • 10 WS-TABLE-2 OCCURS 5 TIMES - The group item following, and not subordinate to, a variable-length table in the same level-01 record (variably located group)
  • INDEXED BY INDX. - The index name for a table that has variable-length elements
  • 15 WS-TABLE-ITEM PIC 99. - The element of a table that has variable-length elements

Whenever a reference is made to one of these five items, the length of the data items is computed as:

  • The contents of WS-COUNTER-1 are multiplied by 3 to calculate the length of WS-TABLE-1
  • The contents of WS-COUNTER-2 are multiplied by 2 and added to the length of WS-TABLE-ITEM to calculate the length of WS-TABLE-2
  • The length of WS-FIELD-A is calculated by adding the length of WS-COUNTER-1, WS-COUNTER-2, WS-TABLE-1, WS-EMPLOYEE-NUMBER, and WS-TABLE-2 times 5.

If a data item described by an OCCURS clause with the DEPENDING ON option is followed in the same level-01 record by non-subordinate data items, a change in the value of the ODO object, and a subsequent reference to a complex ODO item during the course of program execution, will have the following effects:

  • The size of any group containing the related OCCURS clause will reflect the new value of the ODO object.
  • Whenever a MOVE to a group containing an ODO object is executed, the MOVE is made based on the current contents of the object of the DEPENDING ON option. The value of the ODO object can change because a MOVE is made to it or to the group in which it is contained. The value of the ODO object can also change because the group in which it is contained is a record area that has been changed by execution of a READ statement.
  • The location of any non-subordinate items following the item described with the OCCURS clause will be affected by the new value of the ODO object. If you want to preserve the contents of these items, use the following procedure: prior to the change in the ODO object, move all non-subordinate items following the variable item to a work area; after the change in the ODO object, move all the items back.

You must be careful when using complex-ODO index names. If you set an index name (like 'INDX' in the previous example) for a table with variable-length entries ('WS-TABLE-2'), and then change the value of the ODO object ('WS-COUNTER-2'), be aware that the offset in your index is no longer valid for the table, since the table has changed. If, at this point, you were to code statements that used your index name, thinking the index name had a valid value for the table, the statements would yield unexpected results. This would apply to coding:

  • A reference (using your index name) to an element of the table
  • A format-1 SET statement of the type SET INTEGER-DATA-ITEM TO INDEX-NAME
  • A format-2 SET statement of the type SET INDEX-NAME UP/DOWN BY INTEGER To avoid making this type of error, you can do the following:
  • Save the value of your index name (in the form of its integer occurrence number) in an integer data-item before changing the ODO object.
  • Immediately after changing the ODO object, restore the value of your index name from the integer data-item.

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM Mainframe Topics