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]	Base64¹ 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