cs_set_convert

Description

Installs or retrieves a user-defined conversion routine.

Syntax

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;

Parameters

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:

Returns	Indicates
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

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-13.
- If the conversion routine returns a value listed in Table 2-13 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-13, then the application receives an “Unknown return code” error message from Client-Library or CS-Library:

**Table 2-13: Return values for a custom conversion routine**
Return value	Indicates
CS_SUCCEED	Successful conversion.
CS_TRUNCATED	The conversion resulted in truncation.
CS_MEM_ERROR	A memory allocation failure has occurred.
CS_EBADXLT	Some characters could not be translated.
CS_ENOXLT	The requested translation is not supported.
CS_EDOMAIN	The source value is outside the domain of legal values for the datatype.
CS_EDIVZERO	Division by 0 is not allowed.
CS_EOVERFLOW	The conversion resulted in overflow.
CS_EUNDERFLOW	The conversion resulted in underflow.
CS_EPRECISION	The conversion resulted in loss of precision.
CS_ESCALE	An illegal scale value was encountered.
CS_ESYNTAX	The conversion resulted in a value which is not syntactically correct for the destination type.
CS_ESTYLE	The conversion operation was stopped due to a style error.

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);