$CHAR returns the character that corresponds to the decimal (base-10) integer value specified by expression. This character can be an 8-bit (ASCII) character, or a 16-bit (Unicode) character. For 8-bit characters, the value in expression must evaluate to a positive integer in the range 0 to 255. For 16-bit characters, specify integers in the range 256 through 65535 (hex FFFF). Values larger than 65535 return an empty string. Values from 65536 (hex 10000) through 1114111 (hex 10FFFF) are used to represent Unicode surrogate pairs; these characters can be returned using $WCHAR. On an 8-bit Caché installation, $CHAR returns the empty string for expression values greater than 255.
You can specify expression as a comma-separated list, in which case $CHAR returns the corresponding character for each expression in the list.
The expression can be an integer value, the name of a variable that contains an integer value, or any valid ObjectScript expression that evaluates to an integer value. To return characters for multiple integer values, specify a comma-separated list of expressions.
You can use the $ZHEX function to specify a character using a hexadecimal character code, rather than a decimal (base-10) character code. In the following example, both $CHAR statements return the Greek letter pi:
When you use $CHAR to write characters with the WRITE command, the output characters reset the positions of the special variables $X and $Y. This is true even for the NULL character (ASCII 0), which is not the same as a null string (""). As a rule, you should use $CHAR with caution when writing nonprinting characters, because such characters may produce unpredictable cursor positioning and screen behavior.
Because a %List structure (%Library.List) is an encoded string using non-printing characters, certain $CHAR values result in a %List structure containing a single element. The $CHAR combinations that return a %List structure are as follows:
flag is an integer specifying how string should be represented. Valid flag values include 1, 2, 4, 5, 6, 7, 8, 9, 12, and 13. These flag interpretations have nothing to do with the usual ASCII interpretation of this non-print character.
You can use signed numeric values for expression. Caché ignores negative numbers and only evaluates positive or unsigned numbers. In the following example, the $CHAR with signed integers returns only the first and third expression, ignoring the second expression, which is a negative integer.
You can use floating point numeric values for expression. Caché ignores the fractional portion of the argument and only considers the integer portion. In the following example, $CHAR ignores the fractional portion of the number and produces the character represented by character code 65, an uppercase A.
On a Unicode installation of Caché, $CHAR supports Unicode characters when represented by decimal (base-10) integers. On an 8-bit installation of Caché, $CHAR returns the empty string for integers greater than 255.
The Unicode value for a character is usually expressed as a 4-digit number in hexadecimal notation, using the digits 0-9 and the letters A-F. However, standard functions in the ObjectScript language generally identify characters according to ASCII codes, which are decimal values, not hexadecimal.
Hence, the $CHAR function supports Unicode encoding by returning a character based on the decimal Unicode value that was input, not the more standard hexadecimal value. You can specify a hexadecimal Unicode value using the $ZHEX function using quotes, as follows $CHAR($ZHEX("hexnum")). You can also use $ZHEX without quotes to convert a decimal number to hexadecimal, as follows: hexnum = $ZHEX(decnum).
$CHAR does not recognize surrogate pairs. Surrogate pairs are used to represent some Chinese characters and to support the Japanese JIS2004 standard. You can use the $WISWIDE function to determine if a string contains a surrogate pair. The $WCHAR function recognizes and correctly parses surrogate pairs. $CHAR and $WCHAR are otherwise identical. However, because $CHAR is generally faster than $WCHAR, $CHAR is preferable for all cases where a surrogate pair is not likely to be encountered.
$WCHAR should not be confused with $ZWCHAR, which always parses characters in pairs.
The $ASCII function is the inverse of $CHAR. You can use it to convert a character to its equivalent numeric value. $ASCII converts all characters, including Unicode characters. In addition, all Caché platforms support the related functions, $ZLCHAR and $ZWCHAR. They are similar to $CHAR, but operate on a word (two bytes) or a long word (four bytes). You can use $ZISWIDE to determine if there are any multibyte (wide) characters in the expression of $CHAR.