$CHAR and %List Structures

$CHAR and %List Structures

Because a %List structure (%Library.ListOpens in a new tab) 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:

• $CHAR(1) returns an empty list: $lb().

• $CHAR(1,1) returns a two-element empty list: $lb(,).

• $CHAR(2,1), $CHAR(2,2), or $CHAR(2,12) returns a list containing the empty string: $lb("").

• $CHAR(2,4) returns $lb(0).

• $CHAR(2,5) returns $lb(-1).

• $CHAR(2,8) or $CHAR(2,9) returns $lb($double(0)).

$CHAR combinations that involve more than two characters and result in a single-element list have the following syntax:

$CHAR(count,flag,string)

count is the total number of characters. For example, $CHAR(5,1,65,66,67) or $CHAR(5,1)_"ABC".

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.

• flag=1, flag=12, and flag=13 return the literal string value as the list element.

• flag=2 is only valid if count is an even number. It returns a list element containing one or more wide Unicode characters derived from string, often one or more Chinese characters.

• flag=4 returns the positive ASCII numeric code for the character(s) as the list element. flag=4 cannot be used when count>10.

• flag=5 returns a negative integer ASCII numeric code for the character(s) as the list element. flag=5 cannot be used when count>10.

• flag=6 returns a positive integer derived from string as the list element:

  • $CHAR(3,6,n) always returns $lb(0).

  • $CHAR(count,6,string) when count > 3 returns a (usually) large positive integer derived from the ASCII numeric value. The number of trailing zeros corresponds to the ASCII value of the first character in string, the leading numeric value to the ASCII value of the second character in string. For example, $CHAR(4,6,0,7) returns $lb(7); $CHAR(4,6,3,7) returns $lb(7000).

  flag=6 cannot be used when count>11.

• flag=7 returns a negative integer derived from string as the list element:

  • $CHAR(3,7,n) returns a negative number with the number of zeros corresponding to the value of n: 0 = –1, 1 = –10, 2= –100, 3 = –1000, etc.

  • $CHAR(count,7,string) when count > 3 returns a (usually) large negative integer. The number of trailing zeros corresponds to the ASCII value of the first character in string.

  flag=7 cannot be used when count>11.

• flag=8 returns $DOUBLE(x) where x is a small number. flag=8 cannot be used when count>6.

• flag=9 returns $DOUBLE(x) where x is a large number. flag=9 cannot be used when count>10.

string is a numeric or string of count – 2 characters. For example, a string of three characters can be represented as either $CHAR(5,flag,65,66,67) or $CHAR(5,flag)_"ABC". The string value becomes the list element, its value represented as specified by flag.

For further details, refer to $LISTBUILD and $LISTVALID.