MBConvertUnicodeToMB

NLS Function: Converts a Unicode string to a multibyte-character string from the current codepage.

Module: USE DFNLS

Syntax

result = MBConvertUnicodeToMB (unicodestr, mbstr [, flags ])

unicodestr
(Input) INTEGER(2). Array of integers holding the Unicode string to be translated.

mbstr
(Output) Character*(*). Translation of Unicode string into multibyte character string from the current codepage.

flags
(Optional; input) INTEGER(4). If specified, argument to modify the string conversion. If flags is omitted, no extra checking of the conversion takes place. Available values (defined in DFNLS.F90) are:

• NLS$CompositeCheck - Convert composite characters to precomposed.
• NLS$SepChars - Generate separate characters.
• NLS$DiscardDns - Discard nonspacing characters.
• NLS$DefaultChars - Replace exceptions with default character.

The last three flags (NLS$SepChars, NLS$DiscardDns, and NLS$DefaultChars) are mutually exclusive and can be used only if NLS$CompositeCheck is set, in which case one (and only one) of them is combined with NLS$CompositeCheck using an inclusive OR (IOR or OR). These flags determine what translation to make when there is no precomposed mapping for a base character/nonspace character combination in the Unicode wide character string. The default (IOR(NLS$CompositeCheck, NLS$SepChars)) is to generate separate characters.

Results:

The result is of type INTEGER(4). If no error occurs, returns the number of bytes written to mbstr (bytes are counted, not characters), or the number of bytes required to hold the output string if mbstr has zero length. If mbstr is longer than the translation, it is blank-padded. If mbstr is zero length, the function returns the number of bytes required to hold the translation and nothing is written to mbstr.

If an error occurs, one of the following negative values is returned:

• NLS$ErrorInsufficentBuffer - The mbstr argument is too small, but not zero length so that the needed number of bytes is returned.
• NLS$ErrorInvalidFlags - The flags argument has an illegal value.

Compatibility

CONSOLE STANDARD GRAPHICS QUICKWIN GRAPHICS WINDOWS DLL LIB

See Also: MBConvertMBToUnicode