Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (M)
Guardian Procedure Calls Reference Manual—522629-013
9-46
MBCS_TANDEM_TO_EXTERNAL_ Procedure
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 1-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 1 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:
IBM Kanji [%H0F,null]
JEF (Fujitsu) Kanji [%H89,null]
JIS X0208 Kanji [%H18,%H28,%H4A,null]
When the control string values are not user-supplied, the default values used for
control strings expressed in the alternative format is as follows:
IBM Kanji
character attribute [null, %H03, %H88, %HA2, %H00]
Considerations
•
All parameters except shift-to-MBCS and shift-to-one-byte are necessary
for a string translation operation.
•
If any of the optional formal parameters are omitted, the procedure returns, in
maximum-length, the maximum possible length in bytes for the destination data
buffer. In general, translations to external text formats yield text strings of
increased length. The maximum possible finished length for the specified
conditions is returned. If less than this amount of space is allowed, the translation
procedure might fail due to insufficient space in the destination string.