Properties that support variable-length records

When you declare a record part, you can include properties that support the use of variable-length records. You can use variable-length serial records for accessing sequential files, variable-length serial or indexed records for accessing VSAM files, and variable-length MQ records for accessing MQSeries message queues.

Variable-length records with the lengthItem property

The lengthItem property, if present, identifies an item that is used when:

Your code reads a record from a file or queue. The length item receives the number of bytes read into the variable-length record.
Your code writes a record. The length item specifies the number of bytes to add to the file or queue.

The length item can be any of the following:

A structure item in the same record
A structure item in a record that is global to the program or is local to the function that accesses the record (the length item may be qualified with a record variable declared in the program or function)
A data item that is global to the program or is local to the function that accesses the record

The length item has these characteristics:

Has a primitive type of BIN, DECIMAL, INT, NUM, or SMALLINT
Contains no decimal place
Allows for 9 digits at most

An example of a variable-length record part with the lengthItem property is as follows:

  Record mySerialRecordPart1 type serialRecord
    {
      fileName = "myFile",
      lengthItem = myOtherField
    }
    10 myField01 BIN(4);   // 2 bytes long
    10 myField02 NUM(3);   // 3 bytes long
    10 myField03 CHAR(20); // 20 bytes long
  end

When writing a record, the value of the length item must fall between item boundaries, unless the item is a character item. For example, a record of type mySerialRecordPart1 can have the length item, myOtherField, set to 2, 5, 6, 7, ... , 24 , 25. A record with myOtherField set to 2 only contains a value for myField01; a record with myOtherField set to 5 contains values for myField01 and myField02; a record with myOtherField set to 6 through 24 also contains part of myField03.

Variable-length records with the numElementsItem property

The NumElementsItem property, if present, identifies an item that is used when your code adds to or updates the file or queue. The variable-length record must have an array as the last, top-level structure item. The value in the number of elements item represents the actual number of array elements that are written. The value can range from 0 to the maximum, which is the occurs value specified in the declaration of the last, top-level structure item in the record.

The number of bytes written is equal to the sum of the following:

The number of bytes in the fixed-length part of the record.
The value of the number of elements item multiplied by the number of bytes in each element of the ending array.

The number of elements item has these characteristics:

Has a primitive type of BIN, DECIMAL, INT, NUM, SMALLINT
Contains no decimal place
Allows for 9 digits at most

An example of a variable-length record part with the numElementsItem property is as follows:

  Record mySerialRecordPart2 type serialRecord
    {
      fileName = "myFile",
      numElementsItem = myField02
    }
    10 myField01 BIN(4);   // 2 bytes long
    10 myField02 NUM(3);   // 3 bytes long
    10 myField03 CHAR(20)[3]; // 60 bytes long
       20 mySubField01 CHAR(10);
       20 mySubField02 CHAR(10);
  end

Writing a record of type mySerialRecordPart2 with the number of elements item myField02 set to 2 results in a variable-length record with myField01, myField02, and two occurrences of myField03 being written to the file or queue.

The number of elements item must be an item in the fixed-length part of the variable-length record. Use an unqualified reference to name the number of elements item. For example, use myField02 rather than myRecord.myField02.

The number of elements item has no effect when you are reading a record from the file.

Variable-length records with both lengthItem and numElementsItem properties

If both the lengthItem and the numElementsItem properties are specified for a variable-length record, the length of the record is calculated using the number of elements item. The calculated length is moved to the record length item before the record is written to the file.

Variable-length records passed on a call or transfer

If variable-length records are passed on a call, these statements apply:

Space is reserved for the maximum length specified for the record
If the value of the callLink element, property type, is remoteCall or ejbCall, the length item (if any) must be inside the record; for details, see callLink element

Similarly, if variable-length records are passed on a transfer, space is reserved for the maximum length specified for the record.

Related reference
callLink element
MQ record properties