**Table 3-20: Fields in the SRCFMT structure for CSBCONVERT**
Field	When used	Value represents
SRC_NAME	Not used (CS_FMT_UNUSED).	Not applicable.
SRC_NAMELEN	Not used (CS_FMT_UNUSED).	Not applicable.
SRC_TYPE	For all datatype conversions.	The datatype of the source data. CSBCONVERT converts this datatype to the datatype specified for the destination variable (DEST_TYPE).
SRC_FORMAT	Not used (CS_FMT_UNUSED).	Not applicable.
SRC_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.
SRC_SCALE	Only when converting to or from numeric, Sybase-decimal, or packed decimal datatypes.	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.
SRC_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.
SRC_STATUS	Not used (CS_FMT_UNUSED).	Not applicable.
SRC_COUNT	Not used (CS_FMT_UNUSED).	Not applicable.
SRC_UTYPE	Not used (CS_FMT_UNUSED).	Not applicable.
SRC_LOCALE	Not used (CS_FMT_UNUSED).	Not applicable.

**Table 3-21: Fields in the DATAFMT structure for CSBCONVERT**
Field	When used	Value represents
DEST_NAME	Not used (CS_FMT_UNUSED).	Not applicable.
DEST_NAMELEN	Not used (CS_FMT_UNUSED).	Not applicable.
DEST_TYPE	For all datatype conversions.	The datatype of the destination variable. CSBCONVERT converts the datatype specified for the source data (SRCTYPE) to this datatype.
DEST_FORMAT	Not used (CS_FMT_UNUSED).	Not applicable.
DEST_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.
DEST_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.
DEST_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.
DEST_STATUS	Not used (CS_FMT_UNUSED).	Not applicable.
DEST_COUNT	Not used (CS_FMT_UNUSED).	Not applicable.
DEST_UTYPE	Not used (CS_FMT_UNUSED).	Not applicable.
DEST_LOCALE	Not used (CS_FMT_UNUSED).	Not applicable.

CSBCONVERT

Description

Converts a data value from one datatype to another.

Syntax

%INCLUDE CTPUBLIC;

DCL
      01 CONTEXT          FIXED BIN(31) INIT(0);
      01 RETCODE          FIXED BIN(31); INIT(0);          
      01 SRCFMT,
      		05 SRC_NAME             CHAR(132),
      		05 SRC_NAMELEN          FIXED BIN(31),
      		05 SRC_TYPE             FIXED BIN(31),
      		05 SRC_FORMAT           FIXED BIN(31),
      		05 SRC_MAXLEN           FIXED BIN(31),
      		05 SRC_SCALE            FIXED BIN(31),
      		05 SRC_PRECIS           FIXED BIN(31),
      		05 SRC_STATUS           FIXED BIN(31),
      		05 SRC_COUNT            FIXED BIN(31),
      		05 SRC_UTYPE            FIXED BIN(31),
      		05 SRC_LOCALE           FIXED BIN(31);
      01 SRCDATA      type;
      01 DESTFMT, 
      		05 DEST_NAME            CHAR(132),
      		05 DEST_NAMELEN         FIXED BIN(31),
      		05 DEST_TYPE            FIXED BIN(31),
      		05 DEST_FORMAT          FIXED BIN(31),
      		05 DEST_MAXLEN          FIXED BIN(31),
      		05 DEST_SCALE           FIXED BIN(31),
      		05 DEST_PRECIS          FIXED BIN(31),
      		05 DEST_STATUS          FIXED BIN(31),
      		05 DEST_COUNT           FIXED BIN(31),
      		05 DEST_UTYPE           FIXED BIN(31),
      		05 DEST_LOCALE          FIXED BIN(31);
      01 DESTDATA     type;
      01 OUTLEN       FIXED BIN(31);
 
     CALL CSBCONVE (CONTEXT, RETCODE, SRCFMT, SRCDATA,
      DESTFMT, DESTDATA, OUTLEN);

Parameters

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

RETCODE: (O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.

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

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

Table 3-20: Fields in the SRCFMT structure for CSBCONVERT
Field

When used

Value represents

SRC_NAME

Not used (CS_FMT_UNUSED).

Not applicable.

SRC_NAMELEN

Not used (CS_FMT_UNUSED).

Not applicable.

SRC_TYPE

For all datatype conversions.

The datatype of the source data.

CSBCONVERT converts this datatype to the datatype specified for the destination variable (DEST_TYPE).

SRC_FORMAT

Not used (CS_FMT_UNUSED).

Not applicable.

SRC_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.

SRC_SCALE

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

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.

SRC_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.

SRC_STATUS

Not used (CS_FMT_UNUSED).

Not applicable.

SRC_COUNT

Not used (CS_FMT_UNUSED).

Not applicable.

SRC_UTYPE

Not used (CS_FMT_UNUSED).

Not applicable.

SRC_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. CSBCONVERT ignores DESTFMT fields that it does not use.

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

Table 3-21: Fields in the DATAFMT structure for CSBCONVERT
Field

When used

Value represents

DEST_NAME

Not used (CS_FMT_UNUSED).

Not applicable.

DEST_NAMELEN

Not used (CS_FMT_UNUSED).

Not applicable.

DEST_TYPE

For all datatype conversions.

The datatype of the destination variable.

CSBCONVERT converts the datatype specified for the source data (SRCTYPE) to this datatype.

DEST_FORMAT

Not used (CS_FMT_UNUSED).

Not applicable.

DEST_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.

DEST_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.

DEST_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.

DEST_STATUS

Not used (CS_FMT_UNUSED).

Not applicable.

DEST_COUNT

Not used (CS_FMT_UNUSED).

Not applicable.

DEST_UTYPE

Not used (CS_FMT_UNUSED).

Not applicable.

DEST_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, CSBCONVERT sets OUTLEN to CS_UNUSED.

Returns

CSBCONVERT returns one of the following value listed in Table 3-22.

**Table 3-22: CSBCONVERT return values**
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 CSBCONVERT to convert a column in result rows. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”

 /*------------------------------------------------------------------*/
 /*                                                                  */
 /* Subroutine to fetch row processing                               */
 /*                                                                  */
 /*------------------------------------------------------------------*/
 FETCH_ROW_PROCESSING: PROC ;
 
         CALL CTBFETCH( CSL_CMD_HANDLE,
                        CSL_RC,
                        CS_UNUSED,       /* type   */
                        CS_UNUSED,       /* offset */
                        CS_UNUSED,       /* option */
                        FF_ROWS_READ ) ;
 
         SELECT( CSL_RC ) ;
 
           WHEN( CS_SUCCEED )
           DO ;
             NO_MORE_ROWS         = FALSE ;
             CF_COL_FIRSTNME_CHAR = BLANK ;
             DF_DATATYPE          = CS_VARCHAR_TYPE;
             DF_MAXLENGTH         = LENGTH( CF_COL_FIRSTNME ) ;
             DF2_DATATYPE         = CS_CHAR_TYPE;
             DF2_MAXLENGTH        = STG(CF_COL_FIRSTNME_CHAR);
 
             CALL CSBCONVE( CSL_CTX_HANDLE,
                            CSL_RC,
                            DATAFMT,
                            CF_COL_FIRSTNME,
                            DATAFMT2,
                            CF_COL_FIRSTNME_CHAR,
                            CF_COL_LEN);
 
             IF CSL_RC ^= CS_SUCCEED THEN
             DO ;
               MSGSTR       = 'CSCONVERT CS_CHAR_TYPE failed' ;
               NO_ERRORS_SW = FALSE ;
               CALL ERROR_OUT;
               CALL ALL_DONE;
             END ;
 
             FF_ROW_NUM = FF_ROW_NUM + 1 ;

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.
When converting columns, an application must issue a separate CSBCONVERT call for each column to be converted. If several rows of data need converting, the application must issue a separate CSBCONVERT call for every column that needs conversion in each row.

Table 3-23 lists the conversions you can perform with CSBCONVERT.

**Table 3-23: Conversions performed by CSBCONVERT**
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.