BuiltIn Functions › $STRING Function

$STRING Function

$STRING returns an alphanumeric value obtained from the series of parameters by concatenating the values obtained for each parameter.

This function has the following format:

$STRING (parm‑1,...,parm‑n)

parm‑1,...,parm‑n

Defines the items to concatenate (after conversion to alphanumeric expressions, if necessary). An expression must be one of those described follows. If any items contain null values, the concatenated string returns null values. The actions of $STRING vary with the parameter type as follows:

• alphanumeric-field or literal No change.
• flag- Converted to a one‑character value of T or F.
• group- Converted to the concatenation of the result of $STRING on each of the fields in the group. If the group contains an OCCURs, all occurrences are concatenated. Redefined items in the group are ignored.
• numeric field-Converted to alphanumeric representation as follows: if the number is negative, a minus sign is generated, otherwise, no sign representation appears. The integer portion of the number is represented with the display form of the numerals, with leading zeros according to the attributes of the field. The leading zeros, including the units position, are converted to leading blanks.

  Note: You can use the $EDIT function to edit a given field or literal according to a specified pattern. For more information, see the $EDIT Function section.

  If, in this interim result, leading blanks and a minus sign appears, the minus sign is floated to the position adjacent to the first significant digit. If the field has one or more decimal positions, a decimal point is generated, followed by the decimal part with trailing zeros according to the attributes of the field. A byte must be allocated in the field size for an addition or minus sign or a decimal point.

• date field-Converted to the default SCF date pattern (for example, mm/dd/yy). The SET COMMAND SESSION OPTIONS command displays the format.
• numeric literal-Each numeric digit is converted to the corresponding alphanumeric numeral; a plus sign is converted to a blank; a minus sign is retained.
• alphanumeric function- You can nest alphanumeric functions used as parameters of $STRING to three levels. $SPACE, $HIGH, and $LOW are each assumed to be one character long when used as parameters of $STRING.

Note: You must specify each occurrence of fields that are defined as repeating fields (defined with OCCURs) with a subscript.

Examples

$STRING ('ABC', 'DEF')            : result is 'ABCDEF'

Assume G is a group that contains I, J, K.

Assume I is an unsigned numeric field with three digits and two decimal places.

Assume J is a signed numeric field with six digits.

Assume K is an alphanumeric elementary five‑character item.

SET I = 34.5
SET J = ‑123
SET K = 'HELLO'

$STRING (I)      : result is '  34.50'
$STRING (J)      : result is '   ‑123'
$STRING (K)      : result is 'HELLO'
$STRING (I,J)    : result is '  34.50   ‑123'
$STRING (J,K)    : result is '   ‑123HELLO'
$STRING (G)      : result is '  34.50   ‑123HELLO'
$STRING (I,J,K)  : result is '  34.50   ‑123HELLO'

$STRING(G) and $STRING(I,J,K) are equivalent.

$STRING ('*' $SUBSTR('ABCDE' START=2,LENGTH=3) $SPACE K '*')
                 : result is '*BCD HELLO*'