Variable-length Fields

You can bring a variable-length field into your program if you specify *VARCHAR on the CVTOPT parameter of the CRTCBLMOD or CRTBNDCBL commands, or the VARCHAR option of the PROCESS statement. When *VARCHAR is specified, your ILE COBOL program will convert a variable-length field from an externally described file into an ILE COBOL group item.

An example of such a group item is: 
      06  ITEM1.
          49  ITEM1-LENGTH     PIC S9(4) COMP-4.
          49  ITEM1-DATA       PIC X(n).

where n represents the maximum length of the variable-length field. Within the program, the PIC S9(4) COMP-4 is treated like any other declaration of this type, and the PIC X(n) is treated as standard alphanumeric.

When *VARCHAR is not specified, variable-length fields are ignored and declared as FILLER fields in ILE COBOL programs. If *NOVARCHAR is specified, the item is declared as follows: 
  06  FILLER     PIC x(n+2).

For syntax information, see the CVTOPT parameter under CVTOPT Parameter.

Your program can perform any valid character operations on the generated data portion; however, because of the structure of the field, the length portion must be valid binary data. This data is not valid if it is negative, or greater than the maximum field length.

If the first two bytes of the field do not contain a valid binary number, an error will occur if you try to WRITE or REWRITE a record containing the field, and file status 90 is returned.

The following conditions apply when you specify variable-length fields:
  • If a variable-length field is encountered when a Format 2 COPY statement is used in the Data Division, it is declared in an ILE COBOL program as a fixed-length character field.
  • For single-byte character fields, the length of the declared ILE COBOL field is the number of single-byte characters in the DDS field plus 2 bytes.
  • For DBCS-graphic data fields, the length of the declared ILE COBOL field is two times the number of DBCS-graphic characters in the DDS field plus 2 bytes. For more information on graphic data types, see DBCS-Graphic Fields. The two extra bytes in the ILE COBOL field contain a binary number that represents the current length of the variable-length field.  Figure 1 shows the ILE COBOL field length of variable-length fields.
    Figure 1. ILE COBOL Field Length of a Variable-Length Field
    2 + n for single-byte fields; 2 + 2n for double-byte fields
  • Your ILE COBOL program can perform any valid character manipulation operations on the declared fixed-length field. However, because of the structure of the field, the first two bytes of the field must contain valid binary data (invalid current field-length data is less than 0, or greater than the DDS field length). An error occurs for an input or output operation if the first two bytes of the field contain invalid field-length data; file status 90 is returned.
  • If you do not specify *VARCHAR, you can encounter problems performing WRITE operations on variable-length fields, because you cannot assign a value to FILLER. The two-byte field may have a value (for example X'4040') which gives a length beyond the range allowed for the field. This causes an I/O error.
  • Variable length fields can not be used in a SORT/MERGE key as a variable length field. If the variable length field is used in a SORT/MERGE key, then the entire structure is compared as an alphanumeric data item.

To see an example of a program using variable-length fields, refer to Examples of Using Variable-length DBCS-graphic Fields.