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 105 shows the ILE COBOL field length of variable-length fields.
Figure 105. ILE COBOL Field Length of a Variable-Length Field
- 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.
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.