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, ...);