cs_conv_mult

Description

Retrieves the conversion multiplier for converting character data from one character set to another.

Syntax

CS_RETCODE cs_conv_mult(context, 
                         srcloc, 
                         destloc, 
                         conv_multiplier)
 CS_CONTEXT      *context;
 CS_LOCALE         *srcloc;
 CS_LOCALE         *destloc;
 CS_INT                  *conv_multiplier;

Parameters

Returns

cs_conv_mult returns the following values:

The most common reason for a cs_conv_mult failure is an invalid parameter.

Examples

Example 1

The following code fragment retrieves the conversion multiplier for conversions from the iso_1 character set to the eucjis character set:

#define EXIT_ON_FAIL(context, ret, msg) \

{ if (ret != CS_SUCCEED) \

    { \

      fprintf(stdout,"Fatal error(%ld): %s\n",(long)ret,msg); \

      if (context != (CS_CONTEXT *)NULL) \

      { (CS_VOID)ct_exit(context, CS_FORCE_EXIT); \

        (CS_VOID)cs_ctx_drop(context); } \

      exit(-1); \

    } }

** usa_locale uses the iso_1 character set.

*/

ret = cs_loc_alloc(context, &usa_locale);

EXIT_ON_FAIL(context, ret, "cs_loc_alloc(usa) failed.");

ret = cs_locale(context, CS_SET, usa_locale,

                CS_SYB_CHARSET, "iso_1", CS_NULLTERM, NULL);

EXIT_ON_FAIL(context, ret, "cs_locale(usa, CHARSET) failed.");

/*

 ** japan_locale uses eucjis.

 */

 ret = cs_loc_alloc(context, &japan_locale);

 EXIT_ON_FAIL(context, ret, "cs_loc_alloc(japan) failed.");

ret = cs_locale(context, CS_SET, japan_locale,

                 CS_SYB_CHARSET, "eucjis", CS_NULLTERM, NULL);

 EXIT_ON_FAIL(context, ret, "cs_locale(japan, CHARSET) failed.");

/*

 ** Get the conversion multiplier for iso_1 to eucjis conversions.

 */

 ret = cs_conv_mult(context, 

                    usa_locale, japan_locale, &conv_mult);

 EXIT_ON_FAIL(context, ret, "cs_conv_mult(usa, japan) failed.");

fprintf(stdout, 

         "Conversion multiplier for iso_1 to eucjis is %ld.\n",

         (long)conv_mult);

Usage

• cs_conv_mult retrieves the conversion multiplier for converting character data from one character set to another.

• The conversion multiplier allows an application to size the destination data space for conversion of character data into a different character set.

• When converted to another character set, character strings can grow or shrink in length, and applications need to make sure that the destination data space is large enough for the result. With a multi-byte character set destination, 1-byte in the source can convert to several bytes in the destination.

• Inconvertible characters are substituted with single-byte “?”, 2-byte “??” or 3-byte “0xefbfbd” characters.

• A conversion multiplier equals the largest number of bytes in the destination that can replace 1 source byte.

• When converting a character string to a different character set, the application uses the conversion multiplier to size the destination data space, as follows:

  bytes_needed = conv_mult 
                * srclen 
                * CS_SIZEOF(CS_BYTE) 
                + NTB
  

  where:

  • bytes_needed is the necessary length, in bytes, of the destination data space.

  • conv_mult is the conversion multiplier value.

  • srclen is the length, in bytes, of the source string.

  • NTB is 1 if null termination is requested and 0 otherwise.

• See the Open Client and Open Server International Developers Guide.

See also