QlgTransformUCSData()--Transform UCS Data API

 #include <qlgusr.h>

 int QlgTransformUCSData(int xformtype,
                         char   **inbuf,
                         size_t *inbytesleft,
                         char   **outbuf,
                         size_t *outbytesleft,
                         size_t *outspacereg);

The QlgTransformUCSData() function transforms, through a formula as compared to a mapping, data from one form of Unicode to another. A transformation type identification is used to specify the type of transformation.

Parameters

xformtype

(Input) The type of transformation requested for execution (that is, UCS2-UTF8, UTF8-UCS2). The xformtype parameter must be one of the following values:

1	Transform from UCS-2 to UTF-8.
2	Transform from UTF-8 to UCS-2.

Other transformation types are one of the following allowable values from the table of transformation types. The first three decimal digits represent the from encoding and the last three decimal digits represent the to encoding. For instance, 030042 is a transform from UTF-32 LE(Little Endian) (030) to UTF-16 BE(Big Endian) without a BOM(Byte Order Mark) (042).

Allowable decimal values:

010021, 010022, 010031, 010032, 010041, 010042, 010051, 010052, 010061, 010062, 020021, 020022, 020031, 020032, 020041, 020042, 020051, 020052, 020061, 020062, 030021, 030022, 030031, 030032, 030041, 030042, 030051, 030052, 030061, 030062, 040021, 040022, 040031, 040032, 040041, 040042, 040051, 040052, 040061, 040062, 050021, 050022, 050031, 050032, 050041, 050042, 050051, 050052, 050061, 050062, 060021, 060022, 060031, 060032, 060041, 060042, 060051, 060052, 060061, 060062

Table of transformation types:

Transformation	From:	To: with BOM	To: without BOM
Autodetect	010
UTF-32 BE	020	021	022
UTF-32 LE	030	031	032
UTF-16 BE	040	041	042
UTF-16 LE	050	051	052
UTF-8	060	061	062

inbuf

(Input) A pointer to a variable (pointer) that points to the first character in the input buffer. The variable (pointer) is updated to point to the byte following the last byte successfully used in the transformation. The maximum size of the input buffer is 16773104.

inbytesleft

(Input) A pointer to a variable containing the number of bytes to the end of the input buffer to be transformed. This variable is decremented to reflect the number of bytes still not transformed in the input buffer. The maximum number of bytes that can be transformed is 16773104.

outbuf

(Input) A pointer to a variable (pointer) that points to the first character in the output buffer. This variable (pointer) is updated to point to the byte following the last byte of transformed output data. The maximum size of the output buffer is 16773104.

outbytesleft

(Input) A pointer to a variable containing the number of bytes to the end of the output buffer. This variable is decremented to reflect the number of bytes still available in the output buffer. The maximum number of bytes that can be transformed is 16773104.

outspacereq

(Input) A pointer to a variable containing the size of the output buffer required to transform the remaining portion of the input buffer. This value will not be accurate if a sequence error (EILSEQ) occurs, either independently or following an E2BIG error.

Authorities and Locks

None

Return Value

[E2BIG]

There was insufficient space in the output buffer. As much of the input buffer as can be contained in the output buffer is transformed. The buffer pointers and byte counters reflect the point at which a complete character could not be transformed into the output buffer.

[EBADFUNC]

An invalid transform type request was given on the first parameter, xformtype.

[EFAULT]

The address used for an argument is not correct. In attempting to use an argument in a call, the system detected an address that is not valid. While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EILSEQ]

Data provided on an Unicode input buffer was found with an incorrect encoding as determined by the sequence or ordering of the bytes, or a requested xformtype from type did not match the data of the inbuf. Use inbytesleft to determine where the error occurred in the sequence.

[EINVAL]

An invalid inbytesleft data length was given. More specifically, an uneven number of bytes were provided when transforming from UCS-2.

[ENOMEM]

There was not enough memory to perform the transformation.

[ENOTSUP]

Operation not supported. Automatic detection could not find a BOM. A transformation will not be performed.

Usage Notes:

1. When requesting a BOM tagged output buffer the following BOM values will be generated.
   
   

   BOMS	Hex values
   UTF-32 BE (020)	00 00 FE FF
   UTF-32 LE (030)	FF FE 00 00
   UTF-16 BE (040)	FE FF
   UTF-16 LE (050)	FF FE
   UTF-8 (060)	EF BB BF

   A sample conversion:

   transformation type: 030021

   UTF-32 LE (030) -> UTF-32 BE marked (021)

   x'AB 5F 00 00 7C 8E 00 00' -> x'00 00 FE FF 00 00 5F AB 00 00 8E 7C'

2. Auto detection is available when there is a BOM in the beginning of the inbuf that represents a Unicode type.

Error Messages

None.