Graphic String Data (DBCS Support)

A GRAPHIC string is a sequence of DBCS characters (double-byte characters). The number of DBCS characters in a graphic string or sequence is called the length of the graphic string or sequence. In Open PL/I, the maximum length of a graphic string value is 16383 DBCS characters.

A graphic string of zero length is called a null graphic string.

A graphic string variable or graphic string valued function is declared with the following attributes:

GRAPHIC(n)

or

GRAPHIC(n) VARYING

or

CHARACTER(n) VARYINGZ

or

GRAPHIC(n) VARYING BIGENDIAN

where n is an integer valued expression that specifies the maximum length of all graphic string values that can be held by the variable or returned by the function. G can be used as a synonym for GRAPHIC.

The VARYING (VAR) attribute causes the string variable or function to hold or return values of varying lengths. Internally, the length of the varying string is recorded along with the value. Varying strings are not padded to assume their maximum length, n. The representation of a varying string variable in storage is such that any string up to n graphic characters may be held by the variable, and the length of the current string is retained as part of the value. By default, the length field is always stored according the native architecture of the machine for fixed binary (15) data items. If the BIGENDIAN attribute is supplied, the length field is stored in Big Endian format.

The VARYINGZ (VARZ) attribute causes the string variable or function to hold or return values of varying lengths. Internally, the varyingz graphic strings are a stored as a sequence of characters terminated by a ‘0000’x byte, and are not padded to assume their maximum length, n. The representation of a varying string variable in storage is such that any string up to n double-byte characters may be held by the variable.

Without the VARYING attribute, graphic string variable or function always holds or returns values of length n . An assignment to a non-varying string always extends short values with DBCS blanks on the right to make them n graphic characters long.

Assignments of a string of more than n graphic characters to either a VARYING or a non-varying string variable cause only the leftmost n graphic characters to be assigned and excess characters to be truncated.

Graphic string values are compared from left to right using the binary values of the DBCS byte-pairs. Graphic strings of unequal length are compared by effectively extending the shorter string with DBCS blanks on the right.

Non-varying graphic string variables always occupy exactly n*2 bytes of storage. As elements of arrays or members of a structure, they begin on the next available byte and are not aligned on word or other storage address boundaries. This permits an array of non-varying characters to be stored and accessed as if it were a single wide string.

Varying graphic string variables always occupy (n*2)+2 bytes of storage. The first 2 bytes contain an integer L (0 <= L <= n) that specifies the length of the wide string value currently stored in the variable. The string text occupies the first L*2 bytes of the storage following the 2-byte length field. The value of the last n-L byte-pairs of the variable is undefined. The value L can be accessed using the LENGTH built-in function.

Varyingz graphic string variables always occupy n+1 double-bytes of storage. The current length L of a varyingz string is determined by the position of the first '0000'x double-byte, where L = index(string, '0000'Gx) - 1. The string text occupies the first L double-bytes of the storage following the '0000'x double-byte terminator. The value of the last n-L double-bytes of the variable is undefined. The value L can be accessed using the LENGTH built-in function. An array of varyingz graphic strings cannot be accessed as if it were a single character string.

See the Open PL/I User's Guide for specific alignment of graphic varying strings.

Dcl gstr graphic (12) init(‘82678285828C828C828F81408276828F8292828C82848144'Gx) ; 

Dcl gstr graphic(12) init ('Hello World.');