cwbNL_CreateConverterEx
Use the cwbNL_CreateConverterEx command.
Purpose
Create a cwbNL_Converter to be used on subsequent calls to cwbNL_Convert().
Syntax
unsigned int CWB_ENTRY cwbNL_CreateConverterEx(
unsigned long sourceCodePage,
unsigned long targetCodePage,
cwbNL_Converter *theConverter,
cwbSV_ErrHandle errorHandle,
unsigned long shiftInShiftOutStatus,
unsigned long padLength,
char *pad);
Parameters
- unsigned long sourceCodePage - input
- Code page of the source data.
- unsigned long targetCodePage - input
- Code page to which the data should be converted.
- cwbNL_Converter * theConverter - output
- The newly created converter.
- cwbSV_ErrHandle errorHandle - output
- Handle to an error object. Any returned messages will be written to this object. It is created with the cwbSV_CreateErrHandle API. The messages may be retrieved with the cwbSV_GetErrText API. If the parameter is set to zero, no messages will be retrievable.
- unsigned long shiftInShiftOutStatus - input
- Indicates whether the shift-in and shift-out bytes are part of the input or output data. 0 - False, no shift-in and shift-out bytes are part of the data string. 1 - True, shift-in and shift-out characters are part of the data string.
- unsigned long padLength - input
- Length of pad characters. 0 - No pad characters for this conversion request 1 - 1 byte of pad character. This is valid only if the target code page is either SBCS or DBCS code page 2 - 2 bytes of pad characters. This is valid only if the code page is not a single-byte code page.
- char * pad - input
- The character or characters for padding.
Return Codes
The following list shows common return values.
- CWB_OK
- Successful completion.
- CWB_INVALID_HANDLE
- Invalid handle.
- CWB_INVALID_POINTER
- NULL passed on output parameter.
- CWBNL_ERR_CNV_UNSUPPORTED
- An error occurred while attempting to convert the characters. No conversion was done. The most common reason is that a conversion table is missing. Conversion tables are either installed with the product, or retrieved from the default system when needed. There may have been some problem communicating with the default system.
- CWBNL_ERR_CNV_ERR_STATUS
- This return code is used to indicate that while the requested conversion is supported, and the conversion completed, there were some characters that did not convert properly. Either the source buffer contained null characters, or the characters do not exist in the target code page. Applications can choose to ignore this return code or treat it as a warning.
- CWBNL_ERR_CNV_INVALID_SISO_STATUS
- Invalid SISO parameter.
- CWBNL_ERR_CNV_INVALID_PAD_LENGTH
- Invalid Pad Length parameter.
- CWB_NOT_ENOUGH_MEMORY
- Insufficient memory.
Usage
The following values may be specified on the sourceCodePage and the targetCodePage parameters:
Value | Meaning |
---|---|
CWBNL_CP_UNICODE_F200 | UCS2 Version 1.1 UNICODE |
CWBNL_CP_UNICODE | UCS2 Current Version UNICODE |
CWBNL_CP_AS400 | IBM® i host code page |
CWBNL_CP_CLIENT_OEM | OEM client code page |
CWBNL_CP_CLIENT_ANSI | ANSI client code page |
CWBNL_CP_CLIENT_UNICODE | UNICODE client code page |
CWBNL_CP_UTF8 | UCS transformation form, 8–bit format |
CWBNL_CP_CLIENT | Generic client code page. Default is CWBNL_CP_CLIENT_OEM. CWBNL_CP_CLIENT is set to CWBNL_CP_CLIENT_ANSI when CWB_ANSI is defined, to CWBNL_CP_CLIENT_UNICODE when CWB_UNICODE is defined and to CWBNL_CP_CLIENT_OEM when CWB_OEM is defined. |
CWBNL_CP_UTF16BE | UTF-16 (Big-Endian) |
CWBNL_CP_UTF16LE | UTF-16 (Little-Endian) |
CWBNL_CP_UTF16 | CWBNL_CP_UTF16BE or CWBNL_CP_UTF16LE, depending on the platform |
CWBNL_CP_UTF32BE | UTF-32 (Big-Endian) |
CWBNL_CP_UTF32LE | UTF-34 (Little-Endian) |
CWBNL_CP_UTF32 | CWBNL_CP_UTF32BE or CWBNL_CP_UTF32LE, depending on the platform |
Instead of calling cwbNL_ConvertCodePagesEx multiple times with the same code pages:
- cwbNL_ConvertCodePagesEx(850, 500, ...);
- cwbNL_ConvertCodePagesEx(850, 500, ...);
- cwbNL_ConvertCodePagesEx(850, 500, ...);
It is more efficient to create a converter and use it multiple times:
- cwbNL_CreateConverterEx(850, 500, &conv, ...);
- cwbNL_Convert(conv, ...);
- cwbNL_Convert(conv, ...);
- cwbNL_Convert(conv, ...);
- cwbNL_DeleteConverter(conv, ...);