Support for variable-length arrays

A variable-length array is defined in a COBOL copybook by an OCCURS DEPENDING ON (ODO) clause, and in a PL/I copybook by a dimension attribute where the lower or upper bounds (or both) are defined by REFER options, or when a PL/I string data type has a REFER variable for the declared length, for example, CHAR(expr REFER name).

The following considerations apply when using a template that contains variable-length arrays:

A record structure can contain multiple variable-length arrays; however, the fields that define the size of the arrays (the ODO or REFER “objects”) must all appear in the record prior to the first variable-length array item, or, in the case of PL/I REFER length, prior to the first string declared with a REFER length.
If any of the following are true:
- (COBOL copybook only.) The object is out of the range specified by the ODO clause.
- The actual record length does not match the calculated length of a record with the number of array items specified by the object.
- (PL/I copybook only.) The record length does not match the calculated length of a record based on both string length REFERs and number of dimension extents calculated from the lower and upper bound REFERS for each dimension of an array.
  When editing the data set, the prefix area contains the description =LGTH, indicating that the record was not selected because of invalid length. (To show these records, rather than hiding them with other “not selected” records, select the Length error option on the Edit/Browse Options (option 0.8) panel.)
In SNGL or TABL display format:
- You can change the length of a record by changing the value of an object field. This is an exception to the rule that the length of a record cannot be altered in an Edit session, without using ZOOM.
- When you change the value of an object field, then the number of items in the array expands or contracts automatically.
  New items are inserted at the end of the current array (and before any fields that follow the array); numeric items are initialized to zero and alphanumeric items are initialized to blanks.
  
  Similarly, items are deleted from the end of the array, and any fields subsequent to the end of the array are not affected.
  
  For PL/I, the number of items in an array is determined by subtracting the lower bound of the dimension attribute from the upper bound and then adding one. If any REFER variables (fields) are specified as a lower or upper bound of an array dimension, then changing the value of any REFER object field inserts or deletes array items accordingly. For the TABL Format, if the new number of array items exceeds the current number of TABL columns for the array, File Manager expands the number of columns in the display and adds new column headings. Similarly, if a PL/I string length REFER is changed, the column width in TABL for each variable using that REFER is changed.
- (COBOL copybook only.) File Manager does not allow you to change the object field to a value outside the range specified by the ODO clause (File Manager supports an ODO lower value of 0.)
- (COBOL copybook only.) Inserting a new record results in a record with the minimum number of array items specified by the ODO definition. For example, given the following ODO clause:
```
ODO-ONE OCCURS 0 TO 10 TIMES DEPENDING ON ODO-CNTRL-ONE.
```
  then, when you insert a new record, the ODO-CNTRL-ONE field is initialized to zero, and there are no ODO-ONE array items in the new record.
  
  Given the following ODO clause:
```
ODO-ONE OCCURS 5 TO 7 TIMES DEPENDING ON ODO-CNTRL-ONE.
```
  then ODO-CNTRL-ONE is initialized to 5, and there are five ODO-ONE array items in the new record.
- (PL/I copybook only.) Inserting a new record using a template that contains REFER specifications results in one element for each array dimension. Upper and lower bound REFER values are set to one.
In CHAR, HEX or LHEX display format, changing the value of an object field does not change the record length. In these display formats, changing the value of an object field can result in a mismatch between the object field value and the calculated length of the record with that many array items.
If you select Expose (do not group) records of types: Length error on the Edit/Browse Options (option 0.8) panel then, in Edit (option 2), such records appear with an =LGTH indicator in their prefix area.