cs_set_convert

CS_RETCODE cs_set_convert(context, action, srctype,
               desttype, func)
 
 CS_CONTEXT      *context;
 CS_INT                 action;
 CS_INT                 srctype;
 CS_INT                 desttype;
 CS_CONV_FUNC  *func;

context

A pointer to a CS_CONTEXT structure. A CS_CONTEXT structure defines a Client-Library application context.

action

One of the following symbolic values:

Value of action	cs_set_convert
CS_SET	Installs a conversion routine.
CS_GET	Retrieves the current conversion routine of this type.
CS_CLEAR	Clears the current conversion routine by replacing it with CS-Library’s default conversion routine of this type.

srctype

The datatype of the source data for the conversion.

desttype

The datatype of the destination data.

func

A pointer to a CS_CONV_FUNC variable, which is a pointer to a custom conversion function. “Defining a custom conversion routine” describes the prototype for a custom conversion function.

If a conversion routine is being installed, *func points to the conversion routine that you wish to install.

If a conversion routine is being retrieved, cs_set_convert sets *func to point to the currently installed conversion routine.

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 conversion routine”.

Returns

cs_set_convert returns:

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

Usage

• An application can install custom conversion routines to convert data between:

  • Standard Open Client or Open Server datatypes

  • Standard and user-defined datatypes

  • User-defined datatypes

• Once a custom routine is installed for a particular conversion, the client/server libraries call the custom routine transparently whenever a conversion of the specified type is required.

• A Client-Library or Server-Library application creates a user-defined datatype by declaring it:

  typedef CS_SMALLINT          EMPLOYEE_ID;
  

  Because the Open Client routines ct_bind and cs_convert use integer symbolic constants to identify datatypes, it is often convenient for an application to declare a type constant for a user-defined type. User-defined types must be defined as greater than or equal to CS_USERTYPE:

  #define EMPLOYEE_ID_TYPE     CS_USERTYPE + 1;
  

  To enable conversion between a user-defined type and standard CS-Library datatypes, an application can call cs_set_convert to install user-defined conversion routines for the new type.

• To clear a custom conversion routine, an application can call cs_set_convert with action as CS_CLEAR and func as NULL. cs_set_convert replaces the custom routine with CS-Library’s default conversion routine of the appropriate type, if any.

• An application can call cs_setnull to define null substitution values for a user-defined type.

Defining a custom conversion routine

• A custom 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. If the conversion is successful, the custom routine should set *destlen to the number of bytes placed in *destdata.

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

• The following table lists the legal return values for a custom conversion routine. CS-Library will raise a CS-Library error if any value other than CS_SUCCEED is returned. Other values should be returned to indicate error conditions, as described in Table 2-14.

  • If the conversion routine returns a value listed in Table 2-14 other than CS_SUCCEED, then the application receives a Client-Library or C S underscore -Library message that corresponds to the indicated error condition.

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

Installing a custom conversion routine

The following code demonstrates calling cs_set_convert to install a custom conversion routine, MyConvert, which converts from CS_CHAR to the user defined type indicated by MY_USER_TYPE. The code assumes that MyConvert is a a custom conversion routine that has been defined correctly. (See “Defining a custom conversion routine”.) The program variable myfunc is used to pass the address of the conversion routine.

#define MY_USER_TYPE (CS_USER_TYPE + 2)

CS_CONV_FUNC p_conv_func;

p_conv_func = MyConvert;

 if (cs_set_convert(context, CS_SET, CS_CHAR_TYPE, MY_USER_TYPE,

     &p_conv_func) != CS_SUCCEED)

 {

     fprintf(stdout, "cs_set_convert(MY_USER_TYPE) failed!\n");

     (CS_VOID)ct_exit(context, CS_FORCE_EXIT);

     (CS_VOID)cs_ctx_drop(context);

     exit(1);

 }

See also

cs_convert, cs_manage_convert, cs_setnull, ct_bind

---

Copyright © 2008. Sybase Inc. All rights reserved.

View this document as PDF