Product Site

8.65. SysToUnicode (Windows only)

Translate a character string in the specified code page to a Windows UTF-16 string. The translated character string is returned in outstem.

This function calls the Windows API MultiByteToWideChar for the conversion. Any requirements or restrictions of this API apply here.

See also SysFromUnicode (Windows only).

Parameters
string

A string that should be translated to UTF-16 characters.
codepage

Specifies the code page from which string should be translated to UTF-16. If omitted, OEMCP, the system's OEM code page is used.

Code pages can be specified by their numeric identifier, like 437 or 1252. A list of these numeric code page identifiers can be found in the Windows App Development documentation, currently at https://learn.microsoft.com/en-us/windows/win32/Intl/code-page-identifiers. Also, one of the following strings can be specified:
ACP

The system default Windows ANSI code page.
CONSOLE

The current Windows console code page.
MACCP

The system Macintosh code page (legacy, not recommended).
OEMCP

The system OEM code page.
SYMBOL

The Symbol code page (legacy, not recommended).
THREAD_ACP

The Windows ANSI code page for the current thread.
UTF7

Translate to UTF-7 (not recommended, use UTF8 instead).
UTF8

Translate to UTF-8.
translateflags

Flags indicating the conversion type. If omitted, PRECOMPOSED is the default. PRECOMPOSED and COMPOSITE are mutually exclusive, otherwise a combination of any of the following flags can be used:
COMPOSITE

Always use decomposed (or composite) characters, that is, a base character and one or more nonspacing characters. For example, in the character è, the e is the base character and the accent grave mark is the nonspacing character.

This flag cannot be used together with PRECOMPOSED.
ERR_INVALID_CHARS

Make the translation fail with return code 1113 if an invalid UTF-16 input character is encountered.
PRECOMPOSED

Always use precomposed characters, that is, characters in which a base character and a nonspacing character have a single character value. This is the default translation option.

This flag cannot be used together with COMPOSITE.
USEGLYPHCHARS

Use glyph characters instead of control characters.
outstem

The name of the stem variable that will contain the converted result. If the conversion was successful the following compound variable is set:
outstem.!TEXT

This variable contains the converted string.

Return codes
0

No error.
Other

A Windows operating system error code, which may be one of the following, but could be others.
87

The parameter is incorrect. Possible reasons are

  • string length is larger than 2 GB

  • codepage number is not a valid Windows code page
1004

Invalid flags. A possible reason is

  • no flags can be specified with code pages 50220/1/2/5/7/9, 57002-57011, 54936, UTF7, or SYMBOL.
1113

No mapping for the Unicode character exists in the target multi-byte code page.