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 with the VARYING 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 OVERLAY keyword 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:

*.. 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 max_len_a       S          32767A   VARYING
 * 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)
 * 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:

* .. 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          16383G   VARYING
 * 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          16383C   VARYING
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