MBConvertMBToUnicode

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

Module: USE DFNLS

Syntax

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

mbstr
(Input) Character*(*). Multibyte codepage string to be converted.

unicodestr
(Output) INTEGER(2). Array of integers that is the translation of the input string into Unicode.

flags
(Optional; input) INTEGER(4). If specified, modifies the string conversion. If flags is omitted, the value NLS$Precomposed is used. Available values (defined in DFNLS.F90) are:

• NLS$Precomposed - Use precomposed characters always. (default)
• NLS$Composite - Use composite wide characters always.
• NLS$UseGlyphChars - Use glyph characters instead of control characters.
• NLS$ErrorOnInvalidChars - Returns -1 if an invalid input character is encountered.

The flags NLS$Precomposed and NLS$Composite are mutually exclusive. You can combine NLS$UseGlyphChars with either NLS$Precomposed or NLS$Composite using an inclusive OR (IOR or OR).

Results:

The result is of type INTEGER(4). If no error occurs, returns the number of bytes written to unicodestr (bytes are counted, not characters), or the number of bytes required to hold the output string if unicodestr has zero size. If the unicodestr array is bigger than needed to hold the translation, the extra elements are set to space characters. If unicodestr has zero size, the function returns the number of bytes required to hold the translation and nothing is written to unicodestr.

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

• NLS$ErrorInsufficentBuffer - The unicodestr argument is too small, but not zero size so that the needed number of bytes would be returned.
• NLS$ErrorInvalidFlags - The flags argument has an illegal value.
• NLS$ErrorInvalidCharacter - A character with no Unicode translation was encountered in mbstr. This error can occur only if the NLS$InvalidCharsError flag was used in flags.

By default, or if flags is set to NLS$Precomposed, the function MBConvertMBToUnicode attempts to translate the multibyte codepage string to a precomposed Unicode string. If a precomposed form does not exist, the function attempts to translate the codepage string to a composite form.

Compatibility

CONSOLE STANDARD GRAPHICS QUICKWIN GRAPHICS WINDOWS DLL LIB

See Also: MBConvertUnicodeToMB