Guardian Procedure Calls Reference Manual

On output, if result indicates that buffer[testindex] is part of a multibyte character,
then testindex contains the byte index of the first byte of the multibyte character containing
the tested byte.
charset
input
INT:value
identifies the multibyte character set (MBCS) to be used. If charset is omitted or null, the
MBCS returned from the MBCS_DEFAULTCHARSET_ procedure is used. This procedure does
not examine or validate the character set identification, but simply passes it on to the
MBCS_CHAR_ procedure. All MBCSs supported by the MBCS_CHAR_ procedure are supported
by this procedure.
charinfo
output
INT .EXT:ref:1
indicates the cause of failure of the requested test. This procedure returns file-system error 29
to indicate missing required parameters; other error indications are passed back from the
MBCS_CHAR_ procedure. For returned values and interpretations, see the MBCS_CHAR_
Procedure (page 786). Upon return of an error from the MBCS_CHAR_ procedure, the operation
is aborted and processing is returned to the caller.
Returned Value
INT
Identification of the byte contained in buffer[testindex]:
One-byte character0
First byte of a multibyte character1
Intermediate byte of a multibyte character2
Last byte of a multibyte character3
Considerations
• A simple range check is not adequate to establish positive identification of MBCS byte usages.
The set of second-byte values used by Shift-JIS Kanji characters overlaps the byte value ranges
of ASCII, one-byte Katakana, and the set of byte values used for the first byte of Shift-JIS Kanji
characters. Taken out of context, the second byte of a Shift-JIS character could be mistaken
as an ASCII character, a one-byte Katakana character, or the first byte of a Kanji character.
A combination of relative position and value range analysis is required to correctly establish
usage identity as a one-byte character or as a particular MBCS byte identity. This is the basic
purpose of the MBCS_TESTBYTE_ procedure.
• To obtain proper results from the use of this procedure, the caller must ensure that the string
referenced by the buffer parameter is a properly formed text string. A properly formed text
string meets these criteria:
◦ The first byte (buffer[0]) is either a one-byte character or the first byte of an MBCS
character. It can be assumed that a displayable line of text input from a terminal meets
this requirement. Do not assume that an arbitrarily selected extract from a text string meets
this requirement.
◦ The last byte in a properly formed text string is either a one-byte character or an MBCS
final byte. A line of text typed at a terminal in conversational mode does not necessarily
824 Guardian Procedure Calls (M)