Guardian Procedure Calls Reference Manual

Katakana characters also appear within HP Kanji MBCS characters. Furthermore, all byte
values which appear as the first byte of HP Kanji characters might also appear in the second
byte of HP Kanji characters. Similar ambiguous usage of individual byte values occurs in other
supported MBCSs. Proper character identification depends both on value range testing and
context. Because of the multiple identity of individual byte values, it is not safe to attempt to
identify characters selected at random from a text string. Proper character identification requires
analysis of text strings from a starting location with known conditions. Character analysis must
begin on a byte position that is known to be either a one-byte character or the first byte of a
multibyte character.
• To obtain correct results, supply a valid starting point and ensure legitimate access to the text
buffer. Text strings must begin only with a one-byte character or with the first byte of a multibyte
character. Thus, you can call the MBCS_CHAR_ procedure with the testmbcschar parameter
set to the address of the first byte of a text string. Subsequent calls to test other locations within
the text string must be based upon the results of the initial and succeeding calls, with the
testmbcschar pointer being advanced by the size of the character found, following each
call to MBCS_CHAR_. This code sample illustrates the proper use of the MBCS_CHAR_
procedure:
@testmbcschar := @first byte in text string;
WHILE processing mixed text string
DO
BEGIN --text string loop
charsize := number of bytes remaining in text string;
IF MBCS_CHAR_( testmbcschar, charset, charsize )
THEN -- found valid MBCS character
BEGIN -- process and advance pointer
... user-required MBCS character processing here ...
@testmbcschar := @testmbcschar +
$dbl(charsize.<8:15>);
END -- process and advance pointer
ELSE -- found a one-byte character
BEGIN -- process and advance pointer
... user-required one-byte character processing here ...
@testmbcschar := @testmbcschar + 1d;
END; -- process and advance pointer
END; -- text string loop
When calling the MBCS_CHAR_ procedure, you must prevent attempts to read out-of-bounds
data. In the preceding example, the amount of remaining buffer space (number of bytes) is
conveyed by the charinfo parameter on the call; MBCS_CHAR_ does not attempt to access
data beyond this buffer. When this parameter is omitted, the MBCS_CHAR_ procedure operates
upon the assumption that enough bytes may be read to compose one character of the current
MBCS. The caller assumes responsibility for the accuracy of this assumption.
Related Programming Manual
For programming information about the MBCS_CHAR_ procedure, see the Guardian Programmer's
Guide.
788 Guardian Procedure Calls (M)