Guardian Procedure Calls Reference Manual

shift-to-one-byte
input
STRING .EXT:ref:*
is an optional pointer to a string containing the escape or control string used to indicate a shift
to a one-byte character set in the source text string. This string must always be in HP internal
(not EBCDIC) character format, regardless of the final form of the source string.
This procedure does not contain logic for identifying escape or control strings. The control
strings that are used are either the specified default control strings or user-supplied alternative
control strings. In earlier versions of this procedure, control strings were null delimited. While
null-delimited control strings are still supported, an alternative format that supports control strings
containing null bytes is now also provided. The IBM Kanji character attribute (described
following) is an example of an alternative format.
The alternative format that supports user-supplied control strings containing null bytes must be
expressed as (null flag, count, string), where the first byte is a null flag indicator of the alternative
string form, the second byte contains an integer value representing the length of the control
string, and the third and subsequent bytes represent the value of the control string.
The minimum length for a control string is one byte, and the maximum length is 20 bytes. If
the procedure receives a zero-length control string, the results are undefined.
When the control string values are not user-supplied, the default values used for control strings
expressed in the original null-delimited format are as follows:
[%H0F,null]IBM Kanji
[%H89,null]JEF (Fujitsu) Kanji
[%H18, %H28,%H4A,null]JIS X0208 Kanji
When the control string values are not user-supplied, the default values used for control strings
expressed in the alternative format are as follows:
[null, %H03, %H88, %HA2, %H00]IBM Kanji character attribute
Returned Value
INT
Procedure error code:
Successful completion of the translation.0
Translation truncated due to lack of destination buffer space.-1
Unknown translation requested.-2
Invalid source string length.-3
Invalid character in Kanji-only source string.-4
Control string parameter too long.-5
Required parameter missing.29
Considerations
• All parameters except shift-to-MBCS and shift-to-one-byte are necessary for a
string translation operation.
• In general, translations to external text formats yield text strings of increased length. If less
than this amount of space is allowed, the translation procedure might fail due to insufficient
space in the destination string. To determine the maximum length of the destination string after
820 Guardian Procedure Calls (M)