cwbNL_CreateConverterEx

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 @@xe1s@@, or retrieved from the default iSeries™ system when needed. There may have been some problem communicating with the default iSeries 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:

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