cs_convert

Description

Converts a data value from one datatype, locale, or format to another datatype, locale, or format.

Syntax

CS_RETCODE cs_convert(context, srcfmt, srcdata,
                      destfmt, destdata, resultlen)
 CS_CONTEXT           *context;
 CS_DATAFMT            *srcfmt;
 CS_VOID                   *srcdata;
 CS_DATAFMT           *destfmt;
 CS_VOID                  *destdata;
 CS_INT                     *resultlen;

Parameters

context: A pointer to a CS_CONTEXT structure.

srcfmt

A pointer to a CS_DATAFMT structure describing the source data format. The fields in *srcfmt are used as follows:

Field name	Set it to
datatype	A type constant representing the type of the source data (CS_CHAR_TYPE, CS_BINARY_TYPE, and so on).
maxlength	The length of the data in the srcdata buffer. This value is ignored for fixed-length datatypes or if srcdata* is NULL.
locale	A pointer to a CS_LOCALE structure containing localization values for the source data, or NULL to use localization values from *context.
All other fields	Are ignored.

For general information on the CS_DATAFMT structure, see the “CS_DATAFMT Structure” topics page in the Open Client Client-Library/C Reference Manual.

srcdata

A pointer to the source data. To indicate that the source data represents a null value, pass srcdata as NULL. If srcdata is NULL, cs_convert places the null substitution value for the datatype indicated by destfmt−>datatype in *destdata.

Table 2-14 lists the default null substitution value for each datatype. An application can define custom null substitution values by calling cs_setnull.

destfmt

A pointer to a CS_DATAFMT structure describing the destination data format. The following table lists the fields in *destfmt that are used.

**Table 2-2: CS_DATAFMT fields for cs_convert’s *destfmt parameter**
Field Name	Set it to
datatype	A type constant representing the desired destination datatype (CS_CHAR_TYPE, CS_BINARY_TYPE, and so on).
maxlength	The length of the destdata buffer.
locale	A pointer to a CS_LOCALE structure containing localization values for the destination data, or NULL to use localization values from *context.
format	A bit mask of the following symbols: For character and text destinations only, use CS_FMT_NULLTERM to null-terminate the data, or CS_FMT_PADBLANK to pad to the full length of the variable with spaces. For character, binary, text, and image destinations, use CS_FMT_PADNULL to pad to the full length of the variable with nulls. When converting from a character source to a character destination, use CS_FMT_SAFESTR to double any occurrences of the single-quote character (') in the destination. CS_FMT_SAFESTR can be combined with CS_FMT_NULLTERM, CS_FMT_PADBLANK, or CS_FMT_PADNULL. For any type of destination, use CS_FMT_UNUSED if no format information is being provided.
scale	The scale used for the destination variable. If the source data is the same type as the destination, scale can be set to CS_SRC_VALUE to indicate that the destination should pick up its value for scale from the source data. scale must be less than or equal to precision.
precision	The precision used for the destination variable. If the source data is the same type as the destination, precision can be set to CS_SRC_VALUE to indicate that the destination should pick up its value for precision from the source data. precision must be greater than or equal to scale.
All other fields	Are ignored.

For general information on the CS_DATAFMT structure, see the “CS_DATAFMT Structure” topics page in the Open Client Client-Library/C Reference Manual.

destdata: A pointer to the destination buffer space.

resultlen

A pointer to an integer variable. cs_convert sets *resultlen to the length, in bytes, of the data placed in *destdata. If the conversion fails, cs_convert sets *resultlen to CS_UNUSED.

resultlen is an optional parameter and can be passed as NULL.

Datatype Conversion Chart

The chart in Figure 2-1 indicates which datatype conversions are supported by cs_convert. The source datatypes are listed in the leftmost column and the destination datatypes are listed in the top row of the chart. “X” indicates that the conversion is supported; a blank space indicates that the conversion is not supported.

Figure 2-1: Datatype conversion chart

Returns

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

A common reason for a cs_convert failure is that CS-Library does not support the requested conversion.

cs_convert conversion errors will generate CS-Library error messages. For more information about CS-Library error handling, see “Error handling”.

Usage

To determine whether a particular conversion is permitted, use cs_will_convert.
In Client-Library applications, ct_bind sets up automatic, implicit data conversion, which makes it unnecessary for an application to explicitly convert result data that is bound to program variables.
An application can install custom conversion routines by calling cs_set_convert. Once a custom routine for a particular type of conversion is installed, cs_convert or ct_bind call the custom routine whenever a conversion of that type is required.
cs_convert can convert between standard and user-defined datatypes. To enable these types of conversions, an application must install the appropriate custom conversion routines using cs_set_convert.
For more information about CS-Library datatypes, see the “Types” topics page in the Open Client Client-Library/C Reference Manual. For information about Adaptive Server datatypes, see the Adaptive Server Enterprise Reference Manual.

About specific conversions

A conversion to or from binary and image datatypes is a straight byte-copy, except when the conversion involves character or text data. When converting character or text data to binary or image, cs_convert interprets the character or text string as hexadecimal, whether or not the string contains a leading “0x.” There must be a match in the lengths of binary data and fixed length data. If the data lengths do not match, there will be underflow or overflow.
Converting a money, character, or text value to float can result in a loss of precision. Converting a float value to character or text can also result in a loss of precision.
Any length mismatch in the conversion to and from binary and image datatypes cause error underflow or overflow. This may happen, for example, if you are converting one-byte binary data to integer data. Use datatype CS_TINYINT (1 byte integer) to avoid an error.
Converting a float value to money can result in overflow, because the maximum CS_MONEY value is $922,337,203,685,477.5807, and the maximum CS_MONEY4 value is $214,748.3648.
If overflow occurs when converting integer or float data to character or text, the first character of the resulting value will contain an asterisk (*) to indicate the error.
A conversion to bit has the following effect: If the value being converted is not 0, the bit value is set to 1; if the value is 0, the bit value is set to 0.
When converting decimal or numeric data to decimal or numeric data, CS_SRC_VALUE can be used in destfmt−>scale and destfmt−>precision to indicate that the destination data should have the same scale and precision as the source. CS_SRC_VALUE is valid only when the source data is decimal or numeric.

Open Client and Open Server 12.5 support the unichar datatype. For information about this datatype, see Chapter 3, “Using Open Client/Server Datatypes”, in the Open Client Client Library/C Programmer’s Guide.

Converting between character sets

cs_convert performs character set conversion when:
- srctype and desttype both represent character-based types and
- srcfmt−>locale specifies a different character set than destfmt−>locale.
The character-based types are CS_CHAR, CS_LONGCHAR, CS_TEXT, or CS_VARCHAR.
You can program an application to perform character-set conversion by following these steps:
1. Call cs_loc_alloc twice to allocate two CS_LOCALE structures, src_locale and dest_locale, which will be configured to describe the locale of the source data and destination data, respectively.
2. Configure the character set associated with src_locale by calling cs_locale. The call can specify either a locale name or a character set name.
  
  To use a character set name, pass action as CS_SET, type as CS_SYB_CHARSET, and buffer as the name of the character set. Repeat to configure the character set for dest_locale.
  
  To use a locale name, pass action as CS_SET, type as CS_LC_CTYPE, and buffer as a locale name (the character set associated with the locale name will be used). Repeat to configure the character set for dest_locale.
3. (Optional) Call cs_conv_mult to get the conversion multiplier for conversions between src_locale’s character set and dest_locale’s character set. The conversion multiplier can be used to determine whether the result can possibly overflow the destination space.
4. Configure the CS_DATAFMT structures to describe the datatype, length, and format of the source and destination data. Set the locale field in the source CS_DATAFMT structure to src_locale, and set the locale field in the destination CS_DATAFMT structure to dest_locale.
5. Call cs_convert to perform the conversion. This step can be repeated as many times as necessary, using the configured CS_LOCALE and CS_DATAFMT structures.
6. Call cs_loc_drop to deallocate each of src_locale and dest_locale when they are no longer needed.