Translates a UTF-8 encoded string to a data item encoded using the ISO-8859-1 code page.
Usage
C$UTF8-885915 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 (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.
- destination
- 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.
- 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. See
Comments below for more information.
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.
ISO 8859-15 is identical to ISO 8859-1 with the exception of the following 8 characters:
- 0xA4 <-> U+20AC
- 0xA6 <-> U+0160
- 0xA8 <-> U+0161
- 0xB4 <-> U+017D
- 0xB8 <-> U+017E
- 0xBC <-> U+0152
- 0xBD <-> U+0153
- 0xBE <-> U+0178
Important: Because the encodings of these characters take more than one byte, the destination string of the C$UTF8-885915 function might
take more space than a C$UTF8-88591 conversion would. For example, the Euro symbol (£) takes three bytes to encode in UTF-8.
To be safe in general, the UTF-8 string should contain three times as many bytes as the input ISO 8859-15 string.
Examples
Using the following data definitions:
01 my-string-1 pic x(100).
In the following example, since
itemlen is 0, the CALL translates all 5 characters (ABcde) into ISO-8859-1, placing the result into
my-string-1.
CALL C$UTF8-885915 using "ABcde", 0, my-string-1.