cs_manage_convert

CS_RETCODE cs_manage_convert(context, action,
        srctype, srcname, srcnamelen, 
        desttype, destname, destnamelen,
        conv_multiplier, func)

CS_CONTEXT       *context;
CS_INT                 action;
CS_INT                 srctype;
CS_CHAR             *srcname;
CS_INT                 srcnamelen;
CS_INT                 desttype;
CS_CHAR             *destname;
CS_INT                 destnamelen;
CS_INT                  *conv_multiplier;
CS_CONV_FUNC    *func;

context

A pointer to a CS_CONTEXT structure.

action

One of the following symbolic values:

Value of action	cs_manage_convert
CS_SET	Installs a conversion routine and conversion multiplier for conversions between the indicated datatypes and character-set names.
CS_GET	Retrieves the current conversion routine and conversion multiplier for the indicated datatypes and character-set names.
CS_CLEAR	Clears the current conversion routine by replacing it with CS-Library’s default conversion routine for the indicated datatypes and character-set names.

srctype

The datatype of the source data for the conversion. In the current version, srctype must be CS_CHAR_TYPE.

srcname

The name of the character set associated with srctype. This name must correspond to the name of a subdirectory within the charsets subdirectory of the Sybase installation directory.

srcnamelen

The length, in bytes, of srcname. If srcname is null-terminated, srcnamelen can be passed as CS_NULLTERM.

desttype

The datatype of the destination data. In the current version, desttype must be CS_CHAR_TYPE.

destname

The name of the destination character set. This name must correspond to the name of a subdirectory within the charsets subdirectory of the Sybase installation directory.

destnamelen

The length, in bytes, of destname. If destname is null-terminated, destnamelen can be passed as CS_NULLTERM.

conv_multiplier

The address of a CS_INT variable. When action is CS_SET, pass *conv_multiplier as the conversion multiplier for the indicated character-set conversion. When action is CS_GET, *conv_multiplier receives the conversion multiplier for the indicated character-set conversion. When action is CS_CLEAR, pass conv_multiplier as NULL.

See “Meaning of the conversion multiplier” for a explanation of how applications use this number.

func

The address of a CS_CONV_FUNC variable, which itself is a pointer to a character-set conversion routine. “Defining a custom character set conversion routine” describes the requirements for coding a custom character-set conversion routine.

If a conversion routine is being installed, *func points to the conversion routine to be installed.

If a conversion routine is being retrieved, cs_manage_convert sets *func to point to the currently installed character-set conversion routine for srcname to destname conversions, or to NULL if no custom routine is installed.

If a conversion routine is being cleared, pass *func as NULL.

func represents a pointer to a pointer to a function. There are special requirements for passing this parameter. See the example code fragment under “Installing a custom character set conversion routine”.

Returns

cs_manage_convert returns:

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

Usage

• cs_manage_convert allows an application to install a custom character-set conversion routine that converts data from one character set to another.

Character set conversion

• Client-Library, CS-Library, and Server-Library can all perform character-set conversion. Character-set conversion occurs when an application converts between any two character datatypes and associates different character sets with the source and destination.

  • In CS-Library, cs_convert performs character-set conversion when converting between two character datatypes if the destfmt CS_DATAFMT structure specifies (or defaults to) a different locale than the srcfmt CS_DATAFMT structure.

  • In Client-Library, an application can request character-set conversion for fetched character data by binding the column to a character-datatype variable and passing a pointer to a CS_LOCALE in ct_bind’s datafmt that is different from the connection’s locale (that is, the CS_LOC_PROP connection property).

  • In Server-Library, all character data sent to a client or received from a client is automatically converted between the client thread’s character set and the Open Server character set.

• The character datatypes are CS_CHAR, CS_LONGCHAR, CS_TEXT, CS_UNITEXT, CS_UNICHAR, CS_VARCHAR and CS_XML.

• cs_manage_convert requires an application to pass both srctype and desttype as CS_CHAR_TYPE. However, CS-Library, Client-Library, and Server-Library will call the conversion routine to convert between any two character-based types when the conversion locales specify the character sets associated with the conversion routine.

• The most common reason for installing a custom conversion routine is to improve performance by replacing an indirect conversion with a direct conversion.

  A custom character-set conversion routine can improve performance in applications that rely on character-set conversions where CS-Library does not use direct character-set conversion. Indirect character-set conversion converts first to Unicode UTF-8, and then from Unicode UTF-8 to the destination character set. Applications that perform these conversions can improve performance by installing a custom routine that supports direct conversion.

  For example, an Open Server application could install a custom routine to convert between ISO 8859-1 and EUC JIS. This direct conversion may be faster than the indirect conversion (ISO 8859-1 to/from Unicode UTF-8 to/from EUC JIS) that is supplied with Open Server.

• To find out whether a specific character conversion is direct or indirect, look in the source character set’s conversion configuration file. If there is an entry for the destination character set, then the conversion is direct. Character set configuration files are described in the Open Client and Open Server International Developers Guide.

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

Meaning of the conversion multiplier

• Applications must provide cs_manage_convert with a conversion multiplier for conversions between the indicated character sets.

• The value of the conversion multiplier equals the largest number of bytes in the destination result that can replace one source byte when converting between the indicated character sets.

• Applications can retrieve the conversion multiplier for a specific character-set conversion with cs_conv_mult. This number allows the application to determine the destination space needed for a conversion.

Defining a custom character set conversion routine

• A custom character-set conversion routine is defined as follows:

  CS_RETCODE CS_PUBLIC
  

   convfunc(context, srcfmt, srcdata,
  

            destfmt, destdata, destlen)
  

   CS_CONTEXT         *context;
  

   CS_DATAFMT         *srcfmt;
  

   CS_VOID            *srcdata;
  

   CS_DATAFMT         *destfmt;
  

   CS_VOID            *destdata;
  

   CS_INT             *destlen;
  

  where:

  • context is a pointer to a CS_CONTEXT structure.

  • srcfmt is a pointer to a CS_DATAFMT structure describing the source data. srcfmt−>maxlength describes the actual length, in bytes, of the source data.

  • srcdata is a pointer to the source data.

  • destfmt is a pointer to a CS_DATAFMT structure describing the destination data. destfmt−>maxlength describes the actual length, in bytes, of the destination data space.

  • destdata is a pointer to the destination data space.

  destlen is a pointer to an integer. The conversion routine should set *destlen to the number of bytes placed in *destdata. If the routine writes a truncated result, it should set *destlen as the number of bytes written before truncation.

  When converting into a CS_VARCHAR structure, the conversion routine should set both *destlen and the CS_VARCHAR’s len field to the number of bytes written to the CS_VARCHAR’s str field.

• cs_config is the only CS-Library, Client-Library, or Server-Library function that can be called from within a custom conversion routine.

• A custom character-set conversion routine can return any of the values listed in Table 2-11.

  • If the conversion routine returns a value from Table 2-11 other than CS_SUCCEED, then the application receives a Client-Library or CS-Library message that corresponds to the indicated error condition.

  • If the conversion routine returns a value that is not listed in Table 2-11, then the application receives an “Unknown return code” error message from Client-Library or CS-Library.

Installing a custom character set conversion routine

• The following code demonstrates calling cs_manage_convert to install a custom conversion routine. The code is based on the assumption that the installed routine has been defined correctly. (See “Defining a custom character set conversion routine”.) The program variable p_conv_func is used to pass the address of the conversion routine.

  #define MULT_ISO_1_TO_EUCJIS 4
  

   CS_CONV_FUNC p_conv_func;
  

   CS_INT       conv_mult = MULT_ISO_1_TO_EUCJIS;
  

  /*
  

   ** Install the routine charconv_iso_1_TO_eucjis() to convert 
  

   ** character data from iso_1 character set to eucjis character
  

   ** set.
  

   */
  

   p_conv_func = charconv_iso_1_TO_eucjis;
  

   if (cs_manage_convert(context, CS_SET,
  

           CS_CHAR_TYPE, "iso_1", CS_NULLTERM,
  

           CS_CHAR_TYPE, "eucjis", CS_NULLTERM,
  

           &conv_mult, &p_conv_func )
  

       != CS_SUCCEED)
  

   {
  

     fprintf(stdout, "cs_manage_convert() failed!\n");
  

     (CS_VOID)ct_exit(context, CS_FORCE_EXIT);
  

     (CS_VOID)cs_ctx_drop(context);
  

     exit(-1);
  

   }
  

See also

cs_conv_mult, cs_convert, cs_locale, cs_set_convert

---

Copyright © 2012. Sybase Inc. All rights reserved.

View this document as PDF