Developer Guide and Reference

ID 767251
Date 10/31/2024
Public
Document Table of Contents

MBConvertUnicodeToMB

NLS Function: Converts a Unicode string to a multibyte-character string from the current codepage. This routine is only available for Windows.

Module

USE IFNLS

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

unicodestr

(Input) INTEGER(2). Is an array of integers holding the Unicode string to be translated.

mbstr

(Output) Character*(*). Is a translation of Unicode string into multibyte character string from the current codepage.

flags

(Input; optional) INTEGER(4). If specified, is an argument to modify the string conversion. If flags is omitted, no extra checking of the conversion takes place. Available values (defined in IFNLS.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 last three 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 type is INTEGER(4). If no error occurs, it 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$ErrorInsufficientBuffer - The mbstr argument is too small, but not zero length so the needed number of bytes is returned.

  • NLS$ErrorInvalidFlags - The flags argument has an illegal value.