Translates a string encoded using the ANSI code page specified by the COBOL_CHARACTER_SET configuration variable to a UTF-8 encoded data item.


C$COBOL-UTF8 using COBOL-item, itemlen
                 [, destination [, destinationlen]]


The source item encoded using the ANSI code page (as specified by the COBOL_CHARACTER_SET configuration variable), to be translated. It must be either a POINTER (set to a valid value) or an alphanumeric data item.
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 (except when the 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.
If specified, is where the translated characters will be moved. If not specified, 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.
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.


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.


Using the following data definitions:

01 my-string-1 pic x(100).
01 my-string-2 pic x(100). 

In the following example, the CALL translates the 5 characters in my-string-1 (ABcde) into UTF-8, and places the result in my-string-2, which is then padded with UTF-8 spaces. The return-code is 5 (characters).

MOVE "ABcde" to my-string-1
CALL "C$COBOL-UTF8" using my-string-1, 5, my-string-2, 50