CBL_STRING_CONVERT

Converts a string from one character encoding to another.

Syntax:

call "CBL_STRING_CONVERT" using by reference in-string
                                by value in-length
                                by value in-encoding
                                by reference out-string
                                by reference out-length
                                by value out-encoding
                                by value flags
                                by reference reserved
                                returning status-code.

Parameters:

in-string
Picture: pic x(n)
in-length
Picture: pic x(4) comp-5
in-encoding
Picture: pic x(4) comp-5
out-string
Picture: pic x(n)
out-length
Picture: pic x(4) comp-x
out-encoding
Picture: pic x(4) comp-5
flags
Picture: pic x(4) comp-5
reserved
Picture: pic x(4) comp-x
status-code
See Library Routines - Key

On Entry:

in-string
The source string to convert.
in-length
The length of the source string.
in-encoding
The encoding type of the source string. Must be one of:
Value Encoding
0 UTF-8
1 UTF-16 (native)
2 UTF-16 (portable)
3 ASCII/MBCS characters (ANSI characters (Windows) or current locale (UNIX))
4 EBCDIC character (CHARSET"EBCDIC" encoding)
5 ASCII/MBCS characters (OEM characters (Windows) or current locale (UNIX))
6 [4] Base641 ASCII
7 [4] Base64 EBCDIC
8 [4] Base64 BINARY
out-length
Maximum buffer length available for the converted string.
If the value is zero on entry, the call returns the size of the buffer required for the conversion only, and does not perform the actual conversion.
out-encoding
The encoding type of the converted string. Must be one of:
Value Encoding
0 UTF-8
1 UTF-16 (native)
2 UTF-16 (portable)
3 ASCII/MBCS characters (ANSI characters (Windows) or current locale (UNIX))
4 EBCDIC character (CHARSET"EBCDIC" encoding)
5 ASCII/MBCS characters (OEM characters (Windows) or current locale (UNIX))
6 [4] Base64 ASCII
Note: Only permitted if the in-encoding is BASE64 BINARY.
7 [4] Base64 EBCDIC
Note: Only permitted if the in-encoding is BASE64 BINARY.
8 [4] Base64 BINARY
Note: Only permitted if the in-encoding is BASE64 ASCII or BASE64 EBCDIC.
flags
Reserved - must be set to zero.
reserved
Must be set to zero.

On Exit:

out-string
The converted string. If out-string is not large enough to contain the converted data, an error occurs.
If any character in in-string does not have an equivalent character in the output encoding, then it will be converted to a system dependent replacement character
Note: This should only possibly occur when converting from a UTF encoding to an ASCII or EBCDIC character.
out-length
The actual buffer length of out-string (the converted string).
status-code
The result of the conversion. Will be one of:
Value Result
0 success
1 target buffer too small
2 out of memory
3 unsupported conversion