ifx_gl_cv_outbuflen - calculates an approximation of the number of bytes for codeset conversion

SYNOPSIS


#include <ifxgls.h>
int ifx_gl_cv_outbuflen(char *dstcodeset, char *srccodeset, int srcbytes);

DESCRIPTION

This function calculates either exactly the number of bytes that will be required by a destination buffer of codeset converted multi-byte characters or a close over-approximation of the number. The argument srcbytes is the number of bytes in the buffer of multi-byte characters to be codeset converted.

The codesets, srccodeset and dstcodeset, may be locale specifiers (for example, "de_de.8859-1" or "ja_jp.ujis") or code set names found in the file $INFORMIXDIR/gls/cmX/registry (for example, "8859-1" or "ujis"). The macro, IFX_GL_PROC_CS, may be passed as srccodeset or dstcodeset to specify the code set of the current processing locale. Depending on the context, the value of IFX_GL_PROC_CS is based on either the client's environment, or the database which the server is currently accessing.

If the value returned by this function is not equal to srcbytes, then codeset conversion of multi-byte characters cannot be done in-place. A separate multi-byte destination buffer must be allocated. However, if the value returned by this function is exactly equal to srcbytes, then multi-byte codeset conversion can be done in-place.

RETURN VALUES

If a buffer of one or more multi-byte characters contains srcbytes bytes, then this function returns the number of bytes required to store the those multi-byte characters after they have been codeset converted. -1 is returned if an error occurs.

ERRORS

If an error has occurred, this function returns -1 and sets ifx_gl_lc_errno() to one of the following,
[IFX_GL_FILEERR]
Retrieving the conversion information for the specified codesets failed. This may be due to invalid codeset names, a missing registry file, a missing codeset conversion object file or one with an incorrect format, or a lack of memory for the codeset conversion object.

APPLICATION USAGE

To determine the length of a codeset conversion output buffer from an input buffer, you can use the following:
  int dstbytes;
  gl_mchar_t *dstmbs;
  conv_state_t state;

  dstbytes = ifx_gl_cv_outbuflen("ujis", "sjis", srcbytes);
  dstmbs = (gl_mchar_t *) malloc(dstbytes);

  state.first_frag = 1;
  state.last_frag = 1;
  if (ifx_gl_cv_mconv(state, &dstmbs, &dstbytes, "ujis"
                             &srcmbs, &srcbytes, "sjis") == -1 )

SEE ALSO

ifx_gl_conv_needed() ifx_gl_cv_mconv() ifx_gl_cv_sb2sb_table() IFX_GL_PROC_CS

ACKNOWLEDGEMENT

Portions of this description were derived from the X/Open CAE Specification: "System Interfaces and Headers, Issue 4"; X/Open Document Number: C202; ISBN: 1-872630-47-2; Published by X/Open Company Ltd., U.K.