Retrieves the conversion multiplier for converting character data from one character set to another.
CS_RETCODE cs_conv_mult(context, srcloc, destloc, conv_multiplier) CS_CONTEXT *context; CS_LOCALE *srcloc; CS_LOCALE *destloc; CS_INT *conv_multiplier;
A pointer to a CS_CONTEXT structure.
A pointer to the CS_LOCALE structure that describes the source variable’s character set. This parameter cannot be NULL.
A pointer to the CS_LOCALE structure that describes the destination variable’s character set. This parameter cannot be NULL.
A pointer to a CS_INT variable. cs_conv_mult retrieves the conversion multiplier for conversions from the character set indicated by srcloc to the character set indicated by destloc and places it into *conv_multiplier.
cs_conv_mult returns the following values:
Returns |
Indicates |
---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
The most common reason for a cs_conv_mult failure is an invalid parameter.
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);
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.