──┬─ STRING ──┬─ ( ────────────────────────────────────────────────────►
├─ STRING4 ─┤
├─ STRING7 ─┤
└─ STRING8 ─┘
►─┬─<pointer expression>── , ──<arithmetic expression>─────┬─ ) ───────┤
└─<arithmetic expression>── , ─┬─<arithmetic expression>─┤
└─ * ─────────────────────┘The STRING function returns a string value. The function STRING4 returns a hexadecimal string, the function STRING7 returns an ASCII string, and the function STRING8 returns an EBCDIC string. The function STRING returns a string of the default character type. For more information on the default character type, see Default Character Type.
If the first parameter to the STRING function is a pointer expression, the STRING function converts the string of characters designated by the pointer expression into a string. The number of characters converted is indicated by the value of the arithmetic expression rounded to an integer, if necessary. If this rounded value is less than 0, a compile-time or run-time error occurs. If the rounded value is 0, the null string is returned.
When the first parameter is a pointer expression, the pointer expression and the character type of the STRING function differs from that of the pointer expression. The character referenced by the pointer expression must be the beginning of a valid character when the character type is changed to that of the STRING function. For example, if a hex pointer is being converted to an EBCDIC string, the 4-bit pointer must be referencing an even-numbered hex character within the word.
If the first parameter to the STRING function is an arithmetic expression, the STRING function returns a string consisting of a decimal representation of the value of that arithmetic expression. If the second parameter is also an arithmetic expression, then the value of this expression, rounded to an integer, specifies the length of the resulting string. If the value of the second arithmetic expression is less than 0, a compile-time or run-time error occurs. If this value is equal to 0, the null string is returned. If the second parameter is an asterisk (*), the resulting string is exactly long enough to represent the value of the arithmetic expression with no blanks. If the value of the first arithmetic expression is 0 and the second parameter is an asterisk, the resulting string is one character long.
When the STRING function is to return an ASCII or EBCDIC string and the first parameter is an arithmetic expression, its value is converted into the most efficient form, depending on the length specified by the second parameter. If both parameters are arithmetic expressions and the rounded value of the second parameter is greater than the minimum number of characters needed to represent the first parameter, leading blanks are inserted in the resulting string. If both parameters are arithmetic expressions and the rounded value of the second parameter is less than the number of characters needed to represent the first parameter, then a string of all asterisks is returned. A TRY expression is not allowed as a parameter to the STRING function.
For the function STRING4, when the first parameter is an arithmetic expression, only the integer portion of the value of this expression is converted. If both parameters to STRING4 are arithmetic expressions and the rounded value N of the second parameter is less than the number of characters needed to represent the first parameter, then the rightmost N digits of the converted value of the first parameter are returned. If both parameters to STRING4 are arithmetic expressions and the rounded value of the second parameter is greater than the number of characters needed to represent the converted value of the first parameter, then leading zeros are inserted into the resulting string.
Examples of the STRING Function
STRING(P,20) STRING(POINTER(A),N-3) STRING(256,*) = 8"256" STRING(-335.25,8) = 8" -335.25" STRING(4.78@-2,5) = 8".0478" STRING(555000,1) = 8"*" STRING(456.789,7) = 8"456.789" STRING4(123.456,8) = 4"00000123" STRING4(12345678,4) = 4"5678"
