VARYING, VARYING4, VARYINGZ, and NONVARYING attributes

The VARYING, VARYING4, and VARYINGZ attributes specify that a variable can have a length varying from 0 to the declared maximum length. NONVARYING specifies that a variable always has a length equal to the declared length. VAR, VAR4, VARZ, and NONVAR can be used as abbreviations for the VARYING, VARYING4, VARYINGZ, and NONVARYING attributes respectively.

The storage allocated for VARYING strings includes an additional 2 bytes that holds the current length of the string. As the current value is in the units of the string type, so the current length value for a BIT VARYING string is the current number of bits in the string, and the value for a UCHAR VARYING string is the current number of UTF-8 characters in the string.

The storage allocated for VARYING4 strings includes an additional 4 bytes that holds the current length of the string. As the current value is in the units of the string type, so the current length value for a BIT VARYING string is the current number of bits in the string, and the value for a UCHAR VARYING string is the current number of UTF-8 characters in the string.

The storage allocated for a VARYINGZ CHARACTER string is 1 byte longer than the declared length. The current length of the string is equal to the number of bytes before the first '00'x in the storage allocated to it.

The storage allocated for a VARYINGZ GRAPHIC string is 2 bytes more than 2 times its declared length. The current length of the string is equal to half the number of bytes before the first '0000'gx in the storage allocated to it.

The storage allocated for a VARYINGZ UCHAR string is 1 byte more than 4 times its declared length. The current length of the string is equal to the number of UTF-8 characters before the first '00'ux in the storage allocated to the string.

The storage allocated for a VARYINGZ WIDECHAR string is 2 bytes more than 2 times its declared length. The current length of the string is equal to half the number of bytes before the first '0000'wx in the storage allocated to it.

The VARYINGZ attribute is not allowed with BIT strings.

VARYING4 variables are not supported:

in the PASSWORD suboption of the ENVIRONMENT attribute for a FILE
in the KEYTO option of a record I/O statement
as the subject of a LOCATE statement
as the subject of the FROM or INTO clause of a record I/O statement

In the following DECLARE statements, both User and Zuser represent varying-length character data with a maximum length of 15. However, unlike User, Zuser is null-terminated. The storage allocated is 17 bytes for User and 16 bytes for Zuser.

  declare User character (15) varying;
  declare Zuser character (15) varyingz;

The length for User and Zuser at any time is the length of the data item assigned to it at that time. You can determine the declared and the current length by using the MAXLENGTH and LENGTH built-in functions, respectively.

The null terminator held in a VARYINGZ string is not used in comparisons or assignments, other than to determine the length of the string. Consequently, although the strings in the following declarations have the same internal hex representation, they do not compare as being equal:

  declare A char(4) nonvarying init( ('abc' ∥ '00'x) );
  declare B char(3) varyingz   init( 'abc' );

To the contrary, Z and C in this example do compare as equal:

  dcl Z char(3) nonvarying init('abc');
  dcl C char(3) varyingz init('abc');

The VARYING, VARYING4, and VARYINGZ strings can be passed and received as parameters with * length. They can be passed without a descriptor if they have the NONASSIGNABLE attribute.