Rules for Variable-Length Character, Graphic, and UCS-2 Formats
Rules for Variable-Length Character, Graphic, and UCS-2 Formats
The following rules apply when defining variable-length fields:
-
The declared length of the field can be from 1 to 16773100 single-byte characters and from 1 to 8386550 double-byte graphic or UCS-2 characters.
-
The current length may be any value from 0 to the maximum declared length for the field.
-
The field may be initialized using keyword INZ. The initial value is the exact value specified and the initial length of the field is the length of the initial value. The field is padded with blanks for initialization, but the blanks are not included in the length.
-
Variable-length fields which have different-sized length prefixes are fully compatible except when passed as reference parameters.
-
When a prototyped parameter is defined as variable-length (with the VARYING, VARCHAR, VARGRAPH or VARUCS2 keyword), and without either the CONST or VALUE keyword, the passed parameters must have the same size of length prefix as the prototyped parameter. This rule applies even if OPTIONS(*VARSIZE) is specified.
-
In all cases except subfields defined using positional notation, the length (specified by the LEN keyword or the length entry in positions 33-39 on the definition specifications) contains the maximum length of the field in characters; this length does not include the 2- or 4-byte length prefix.
-
For subfields defined using positional notation, the size specified by the From and To positions includes the 2- or 4-byte length prefix. As a result, the number of bytes that you specify using the positional notation must be two or four bytes longer than the number of bytes required to hold the data. If you specify VARYING(2), you add two bytes to the bytes required for the data; if you specify VARYING(4), you add four bytes. If you specify VARYING without a parameter, you add two bytes if the length is 65535 or less, and you add four bytes if the length is greater than 65535. For alphanumeric subfields, sizes from 3 to 65537 represent lengths of 1 to 65535; for UCS-2 and Graphic subfields, sizes from 5 to 131072 represent lengths of 1 to 65535.
Note: A more convenient way to specify variable-length subfields is to use length notation, and to use the POS keyword in a free-form definition or the OVERLAY keyword in a fixed-form definition to specify the position of the subfield within the data structure.
-
The keyword VARYING cannot be specified for a data structure.
-
For variable-length prerun-time arrays, the initialization data in the file is stored in variable format, including the length prefix.
-
Since prerun-time array data is read from a file and files have a maximum record length of 32766, variable-length prerun-time arrays have a maximum size of 32764 single-byte characters, or 16382 double-byte graphic or UCS-2 characters.
-
A variable-length array or table may be defined with compile-time data. The trailing blanks in the field of data are not significant. The length of the data is the position of the last non-blank character in the field. This is different from prerun-time initialization since the length prefix cannot be stored in compile-time data.
-
*LIKE DEFINE cannot be used to define a field like a variable-length field.
The following is an example of defining variable-length character fields:
Figure 1. Defining Variable-Length Character and UCS-2 Fields
*.. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... *
DName+++++++++++ETDsFrom+++To/L+++IDc.Functions++++++++++++++++++++++++++++
* Standalone fields:
D var5 S 5A VARYING
D var10 S 10A VARYING INZ('0123456789')
D largefld_a S 32767A VARYING
D max_len_a S A VARYING LEN(16773100)
DCL-S free_form_10A VARCHAR(10);
* Prerun-time array:
D arr1 S 100A VARYING FROMFILE(dataf)
* Data structure subfields:
D ds1 DS
* Subfield defined with length notation:
D sf1_5 5A VARYING
D sf2_10 10A VARYING INZ('0123456789')
* Subfield defined using positional notation: A(5)VAR
D sf4_5 101 107A VARYING
* Subfields showing internal representation of varying:
D sf7_25 100A VARYING
D sf7_len 5I 0 OVERLAY(sf7_25:1)
D sf7_data 100A OVERLAY(sf7_25:3)
* Free-form varying subfields:
sf8_10 VARCHAR(10);
sf9_13 VARCHAR(13 : 4);
* Procedure prototype
D Replace PR 32765A VARYING
D String 32765A CONST VARYING OPTIONS(*VARSIZE)
D FromStr 32765A CONST VARYING OPTIONS(*VARSIZE)
D ToStr 32765A CONST VARYING OPTIONS(*VARSIZE)
D StartPos 5U 0 VALUE
D Replaced 5U 0 OPTIONS(*OMIT)The following is an example of defining variable-length graphic and UCS-2 fields:
Figure 2. Defining Variable-Length Graphic and UCS-2 Fields
* .. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+...
DName+++++++++++ETDsFrom+++To/L+++IDc.Functions++++++++++++++++
*-------------------------------------------------------------
* Graphic fields
*-------------------------------------------------------------
* Standalone fields:
D GRA20 S 20G VARYING
D MAX_LEN_G S 8386550G VARYING
DCL-S free_form_10G VARGRAPH(10);
* Prerun-time array:
D ARR1 S 100G VARYING FROMFILE(DATAF)
* Data structure subfields:
D DS1 DS
* Subfield defined with length notation:
D SF3_20 20G VARYING
* Subfield defined using positional notation: G(10)VAR
D SF6_10 11 32G VARYING
*-------------------------------------------------------------
* UCS-2 fields
*-------------------------------------------------------------
D MAX_LEN_C S 8386550C VARYING
DCL-S free_form_10C VARUCS2(10);
D FLD1 S 5C INZ(%UCS2('ABCDE')) VARYING
D FLD2 S 2C INZ(U'01230123') VARYING
D FLD3 S 2C INZ(*HIVAL) VARYING
D DS_C DS
D SF3_20_C 20C VARYING
* Subfield defined using positional notation: C(10)VAR
D SF_110_C 11 32C VARYING