The ifx_gl_cv_mconv() function

The ifx_gl_cv_mconv() function converts characters from one code set to another.

Syntax

#include <ifxgls.h>
...
int ifx_gl_cv_mconv(state, dst, dst_bytesleft, dst_codeset, src, src_bytesleft,
    src_codeset)
       conv_state_t *state;
       gl_mchar_t **dst;
       int *dst_bytesleft;
       char *dst_codeset;
       gl_mchar_t **src;
       int *src_bytesleft;
       char *src_codeset;

state: Points to a conv_state_t structure. For more information, see Convert fragmented strings.
dst: Points to a pointer to the first character in the destination buffer. If dst is NULL, the function updates *src, *src_bytesleft, and *dst_bytesleft, but the converted data is not written to *dst.
dst_bytesleft: Points to the maximum number of bytes to write to *dst.
dst_codeset: A pointer to the name of the destination (target) code set.
src: Points to a pointer to the first character in the source buffer.
src_bytesleft: Points to the number of bytes in *src to convert. If src_bytesleft is NULL, the function converts data until it reaches a null character in the source buffer.
src_codeset: A pointer to the name of the source code


Valid in client application	Valid in DataBlade® UDR
Yes	Yes

Usage

The ifx_gl_cv_mconv() function converts the string of multibyte characters in *src to the same characters, but encoded in another code set, and stores the result in the buffer that *dst references. The ifx_gl_cv_mconv() function updates the following arguments:

The function updates src to point to the byte that follows the last source character successfully converted.
The function updates the integer that src_bytesleft references to the number of bytes in *src that have not been converted. After a successful conversion, src_bytesleft points to 0.
The function updates dst to point to the first character of the code-set-converted text.
The function updates the integer that dst_bytesleft references to the number of bytes still available in *dst.

Specify code sets

The code sets, src_codeset and dst_codeset, can be any of the following items:

Locale names
Code-set names
The IFX_GL_PROC_CS macro

For more information, see Specify code-set names.

Calculate the size of the destination buffer

The number of bytes written to *dst might be more or fewer than the number of bytes read from *src. You can determine the number of bytes that will be written to *dst in one of the following ways:

The function ifx_gl_cv_outbuflen() calculates an estimate based on the *src_bytesleft value.
The following expression is the maximum number of bytes that will be written to *dst for any value of *src in any locale:
```
(*srcbytesleft) * IFX_GL_MB_MAX
```

Of these options, the last method is the fastest. The ifx_gl_cv_outbuflen() function is the slowest but the most precise.

Convert fragmented strings

The state argument is a pointer to a conv_state_t structure. You must allocate a conv_state_t structure and set the first_frag and last_frag fields of the conv_state_t structure to tell the ifx_gl_cv_mconv() function whether the string to be converted is a fragment.

The following table lists the different fragments of a string and the corresponding values to which you must set these two conv_state_t fields.


String fragment	Value of first_frag field	Value of last_frag field
String is the first of n fragments.	1	0
String is one of the 2nd, ..., nth-1 fragments.	0	0
String is the last (nth) fragment.	0	1
String is not fragmented; it is a complete string.	1	1

Important: The conv_state_t structure contains other fields that are for internal use only. HCL Informix® does not guarantee that these other internal fields of conv_state_t will not change in future releases. Therefore, to create portable code, set only the first_frag and last_frag fields of the conv_state_t structure.

Locale information

For more information on the use of the conv_state_t structure, see Preserve state information.

Return values

0: The code-set conversion was successful, and the *src, *src_bytesleft, *dst, and *dst_bytesleft arguments have been updated. If the entire source buffer is converted, the *srcbytesleft value is 0.
-1: The function was not successful, and the error number is set to indicate the cause. See the Errors section. If the source conversion is stopped due to an error, the *srcbytesleft value is greater than 0.

Errors

If an error occurred, this function returns -1 and sets the ifx_gl_lc_errno() error number to one of the following values.

IFX_GL_FILEERR: Retrieving the conversion information for the specified code sets failed. This failure might be due to invalid code-set names, a missing registry file, a missing code-set-conversion object file or one with an incorrect format, or insufficient memory for the code-set-conversion object.
IFX_GL_EILSEQ: The *src value contains an invalid character. Conversion stops after both the last successfully converted source and destination character.
IFX_GL_EINVAL: The function cannot determine whether the last character of *src is a valid character or the end of shift sequence because it would need to read more than *src_bytesleft bytes from *src. Conversion stops after the last successfully converted source and destination character.
IFX_GL_E2BIG: Not enough space is available in the destination buffer. Conversion stops after both the last successfully converted source and destination character.