Table 3-17: Fields in the *srcfmt* structure for **cs_convert**
Field	When used	Value represents
name	Not used (CS_FMT_UNUSED).	Not applicable.
namelen	Not used (CS_FMT_UNUSED).	Not applicable.
type	For all datatype conversions.	The datatype of the source data. cs_convert converts this datatype to the datatype specified for the destination variable (dest_type).
format	Not used (CS_FMT_UNUSED).	Not applicable.
maxlen	When converting non-fixed-length source datatypes to any destination type. src_maxlen is ignored when converting fixed-length types.	The length of the source variable, in bytes. If srcdata is an array, src_maxlen is the length of an element in the array. When converting character or binary datatypes, src_maxlen must describe the total length of the source variable, including any space required for special terminating bytes, with this exception: when converting a VARYCHAR-type source such as the DB2 VARCHAR, src_maxlen does not include the length of the “LL” length specification. In case of Sybase-numeric, Sybase-decimal or packed decimal this value is the actual length.
scale	Only when converting to or from numeric, Sybase-decimal, or packed-decimal	Number of digits that follow the decimal point in the source data. src_scale must be less than or equal to src_precis and cannot be greater than 31.
precis	Only when converting to or from packed- decimal, numeric and Sybase-decimal datatypes.	The total number of digits in the source data. src_precis must be greater than or equal to src_scale and cannot be less than 1 or greater than 31.
status	Not used (CS_FMT_UNUSED).	Not applicable.
count	Not used (CS_FMT_UNUSED).	Not applicable.
usertype	Not used (CS_FMT_UNUSED).	Not applicable.
locale	Not used (CS_FMT_UNUSED).	Not applicable.

**Table 3-18: Fields in the *datafmt* structure for cs_convert**
Field	When used	Value represents
name	Not used (CS_FMT_UNUSED).	Not applicable.
namelen	Not used (CS_FMT_UNUSED).	Not applicable.
type	For all datatype conversions.	The datatype of the destination variable. cs_convert converts the datatype specified for the source data (srctype) to this datatype.
format	Not used (CS_FMT_UNUSED).	Not applicable.
maxlen	When converting all source datatypes to non-fixed-length datatypes. dest_maxlen is ignored when converting to fixed-length datatypes.	The length of the destination variable, in bytes. If destdata is an array, dest_maxlen is the length of an element in the array. When converting character or binary datatypes, dest_maxlen must describe the total length of the destination variable, including any space required for special terminating bytes, with this exception: when converting to a VARYCHAR-type destination such as the DB2 VARCHAR, dest_maxlen does not include the length of the “LL” length specification. dest_maxlen = 35 when converting to numeric or Sybase-decimal.
scale	Only when converting to or from numeric, Sybase-decimal, or packed decimal datatypes.	Number of digits that follow the decimal point in the destination variable. dest_scale must be less than or equal to dest_precis and cannot be greater than 31. Use the same value as in src_scale.
precis	Only when converting to or from numeric, Sybase-decimal, or packed decimal datatypes.	The total number of digits in the destination data. dest_precis must be greater than or equal to dest_scale and cannot be less than 1 or greater than 31. Use the same value as in src_precis
status	Not used (CS_FMT_UNUSED).	Not applicable.
count	Not used (CS_FMT_UNUSED).	Not applicable.
usertype	Not used (CS_FMT_UNUSED).	Not applicable.
locale	Not used (CS_FMT_UNUSED).	Not applicable.

cs_convert

Description

Converts a data value from one datatype to another.

Syntax

CS_RETCODE cs_convert(context, srcfmt, srcdata,	 destfmt, destdata, outlen);
CS_CONTEXT     *context;
CS_DATAFMT     *srcfmt;
CS_BYTE        *srcdata;
CS_DATAFMT     *destfmt;
CS_BYTE        *destdata;
CS_INT         *outlen;

Parameters

context: (I) A context structure. The context structure is defined in the program call cs_ctx_alloc.

srcfmt: (I) A structure that describes the variable(s) that contain the source data. cs_convert ignores srcfmt fields that it does not use.

Table 3-17 lists the fields in the srcfmt structure and indicates whether and how they are used by cs_convert. For a general discussion of this structure, see “DATAFMT structure”.

Table 3-17: Fields in the srcfmt structure for cs_convert
Field

When used

Value represents

name

Not used (CS_FMT_UNUSED).

Not applicable.

namelen

Not used (CS_FMT_UNUSED).

Not applicable.

type

For all datatype conversions.

The datatype of the source data.

cs_convert converts this datatype to the datatype specified for the destination variable (dest_type).

format

Not used (CS_FMT_UNUSED).

Not applicable.

maxlen

When converting non-fixed-length source datatypes to any destination type.

src_maxlen is ignored when converting fixed-length types.

The length of the source variable, in bytes. If srcdata is an array, src_maxlen is the length of an element in the array.

When converting character or binary datatypes, src_maxlen must describe the total length of the source variable, including any space required for special terminating bytes, with this exception: when converting a VARYCHAR-type source such as the DB2 VARCHAR, src_maxlen does not include the length of the “LL” length specification.

In case of Sybase-numeric, Sybase-decimal or packed decimal this value is the actual length.

scale

Only when converting to or from numeric, Sybase-decimal, or packed-decimal

Number of digits that follow the decimal point in the source data.

src_scale must be less than or equal to src_precis and cannot be greater than 31.

precis

Only when converting to or from packed- decimal, numeric and Sybase-decimal datatypes.

The total number of digits in the source data.

src_precis must be greater than or equal to src_scale and cannot be less than 1 or greater than 31.

status

Not used (CS_FMT_UNUSED).

Not applicable.

count

Not used (CS_FMT_UNUSED).

Not applicable.

usertype

Not used (CS_FMT_UNUSED).

Not applicable.

locale

Not used (CS_FMT_UNUSED).

Not applicable.

srcdata: (I) Name of the source variable that contains the data to be converted. This is the variable described in the srcfmt structure.

destfmt: (I) A structure that contains a description of the variable(s) that contain destination (converted) data. cs_convert ignores destfmt fields that it does not use.

Table 3-18 lists the fields in the destfmt structure and indicates whether and how they are used by cs_convert. For a general discussion of this structure, see “DATAFMT structure”.

Table 3-18: Fields in the datafmt structure for cs_convert
Field

When used

Value represents

name

Not used (CS_FMT_UNUSED).

Not applicable.

namelen

Not used (CS_FMT_UNUSED).

Not applicable.

type

For all datatype conversions.

The datatype of the destination variable.

cs_convert converts the datatype specified for the source data (srctype) to this datatype.

format

Not used (CS_FMT_UNUSED).

Not applicable.

maxlen

When converting all source datatypes to non-fixed-length datatypes.

dest_maxlen is ignored when converting to fixed-length datatypes.

The length of the destination variable, in bytes. If destdata is an array, dest_maxlen is the length of an element in the array.

When converting character or binary datatypes, dest_maxlen must describe the total length of the destination variable, including any space required for special terminating bytes, with this exception: when converting to a VARYCHAR-type destination such as the DB2 VARCHAR, dest_maxlen does not include the length of the “LL” length specification.

dest_maxlen = 35 when converting to numeric or Sybase-decimal.

scale

Only when converting to or from numeric, Sybase-decimal, or packed decimal datatypes.

Number of digits that follow the decimal point in the destination variable.

dest_scale must be less than or equal to dest_precis and cannot be greater than 31. Use the same value as in src_scale.

precis

Only when converting to or from numeric, Sybase-decimal, or packed decimal datatypes.

The total number of digits in the destination data.

dest_precis must be greater than or equal to dest_scale and cannot be less than 1 or greater than 31. Use the same value as in src_precis

status

Not used (CS_FMT_UNUSED).

Not applicable.

count

Not used (CS_FMT_UNUSED).

Not applicable.

usertype

Not used (CS_FMT_UNUSED).

Not applicable.

locale

Not used (CS_FMT_UNUSED).

Not applicable.

destdata: (O) Name of the variable that contains the converted data. This is the variable described in the destdata structure.

outlen: (O) Actual length, in bytes, of the data placed in destdata. If the conversion fails, cs_convert sets outlen to CS_UNUSED.

Returns

cs_convert returns one of the following values listed in Table 3-19.

**Table 3-19: Values returned**
Value	Meaning
CS_SUCCEED (-1)	The routine completed successfully.
CS_FAIL (-2)	The routine failed.
TDS_INVALID_DATAFMT_VALUE (-181)	A srcfmt or destfmt field contains an illegal value—probably an illegal datatype value.
TDS_INVALID_VAR_ADDRESS (-175)	This value cannot be NULL.
TDS_MONEY_CONVERSION_ERROR (-22)	Converting TDSMONEY4 failed, possibly because the TDS version is not 4.2 or above.
TDS_INVALID_DATA_CONVERSION (-172)	This value cannot be NULL.
TDS_INVALID_LENGTH(-173)	Converting TDSMONEY4 failed, possibly because the TDS version is not 4.2 or above.

Examples

Example 1

The following code fragment illustrates the use of cs_convert to convert a column in result rows. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”

  	/********************************************************************/
  	/*                                                                  */
  	/* Subroutine to fetch row processing                               */
  	/*                                                                  */
  	/********************************************************************/
  	void   fetch_row_processing ()
  
  	{
   	CS_INT        rows_read;
   	CS_INT        rc;
   	CS_INT        col_len;
   	CS_INT        max_screen_rows = 10;
   	CS_SMALLINT   nomore_rows    = 0;
   	CS_DATAFMT    datafmt;
   	CS_DATAFMT    datafmt2;
   	struct {
           char  first[12];
           char  space2[2];
           char  edlevel[4];
          } output_row;
  
  
       while (nomore_rows == FALSE)
       {
         strcpy(col_firstnme.str, "            ");
         memset (&output_row, ' ', sizeof(output_row));
  
         rc = ct_fetch (cmd, (long) CS_UNUSED,
                       (long) CS_UNUSED,
                       (long) CS_UNUSED,
                       &rows_read);
  
         switch (rc)
         {
             case  CS_SUCCEED:
                 nomore_rows         = FALSE ;
                 datafmt.datatype     = CS_VARCHAR_TYPE;
                 datafmt.maxlength    = sizeof(col_firstnme);
                 datafmt2.datatype    = CS_CHAR_TYPE;
                 datafmt2.maxlength   = 12;
  
  /*------------------------------------------------------------*/
  /* convert the first column from VARCHAR to CHAR for display  */
  /*------------------------------------------------------------*/
                 if (cs_convert(context, datafmt, col_firstnme, datafmt2,
                                &output_row.first, &col_len) !=
 CS_SUCCEED)
                 {
                    strncpy (msgstr,
                      "CS_CONVERT CS_CHAR_TYPE failed", msg_size);
                    no_errors_sw = FALSE ;
                    error_out(rc);
                 }

Usage

A client application can use this function to convert the datatype of RPC return parameters to the datatype of the target server, and to convert the datatype of a retrieved value to a datatype that can be used by Open ClientConnect. This function converts a single variable each time it executes.
If converting columns, an application must issue a separate cs_convert call for each column to be converted. If several rows of data need converting, the application must issue a separate cs_convert call for every column that needs conversion in each row.
Table 3-20 lists the conversions you can perform with cs_convert.

Table 3-20: Conversions performed by **cs_convert**
Source type	Result type	Notes
CS_VARCHAR	CS_CHAR	Does EBCDIC to ASCII conversion; pads with blanks.
CS_CHAR	CS_VARCHAR
CS_MONEY	CS_CHAR
CS_MONEY	CS_VARCHAR
CS_REAL	CS_FLOAT	Truncates low order digits.
CS_MONEY	CS_FLOAT
CS_PACKED370	CS_FLOAT
CS_FLOAT	CS_REAL	Pads with zeroes.
CS_MONEY	CS_PACKED370
CS_CHAR	CS_PACKED370
CS_VARCHAR	CS_PACKED370
CS_FLOAT	CS_PACKED370
CS_NUMERIC	CS_PACKED370
CS_DECIMAL	CS_PACKED370
CS_NUMERIC	CS_CHAR
CS_DECIMAL	CS_CHAR
CS_DATETIME	CS_CHAR
CS_CHAR	CS_NUMERIC
CS_CHAR	CS_DECIMAL
CS_PACKED370	CS_NUMERIC
CS_PACKED370	CS_DECIMAL
CS_PACKED370	CS_CHAR

WARNING! Converting CS_MONEY or CS_CHAR values to CS_FLOAT can result in a loss of precision. Converting a CS_FLOAT value to a character type can also result in a loss of precision.