C$UTF8-UTF16

Usage

C$UTF8-UTF16 using utf-8-item, itemlen
                 [, destination [, destinationlen]]

Parameters

utf-8-item

The UTF-8 encoded source item to be translated. It must be either a POINTER (set to a valid value) or an alphanumeric data item.

itemlen

The number of characters of the source item that you want to translate. If this value is 0, then the size of the source item is used (not valid when source is a POINTER). If this value is -1, the source is assumed to be terminated by a low-value character, and again, the entire source item will be translated.

destination

If given, is where the translated characters will be moved. If not given, the return-code will be the number of characters needed in the destination item to hold the entire source string. This data item can be either a POINTER or an alphanumeric data item. If it is a POINTER, you must set it to a valid value.

destinationlen

The number of characters that can be held in the destination data item. If this parameter is -1, or is not specified, then the length of destination is used.

Comments

The return value is the number of characters moved to the destination data item, or the number that would be needed (when the destination item is missing or NULL).

If fewer characters are placed in the destination than there is room for, the routine will pad the destination with spaces.

Examples

Using the following data definitions:

01 my-string-1 pic x(100).
01 my-string-2 pic x(100).
01 my-pointer pointer.
01 my-len signed-int.
01 alloc-len signed-int. 

In the following example, although the source (my-string-1) is 26 characters, the CALL translates only the first 10 characters into UTF-16. The amount of space required for translation is calculated, allocated, and then translated into that buffer, which is then freed upon completion of the translation.

MOVE "abcdefghijklmnopqrstuvwxyz" to my-string-1.
CALL "C$UTF8-UTF16" using my-string-1, 10.

MOVE return-code to my-len.
MULTIPLY my-len by 2 GIVING alloc-len.  *> UTF-16 uses 2 bytes per character

CALL "M$ALLOC" using alloc-len my-pointer.
CALL "C$UTF8-UTF16" using my-string-1, 10, my-pointer, my-len.
CALL "M$FREE" using my-pointer.