CS_DATAFMT structure

A CS_DATAFMT structure is used to describe data values and program variables. For example:

ct_bind requires a CS_DATAFMT structure to describe a destination variable.
ct_describe returns a CS_DATAFMT structure to describe a result data item.
ct_param and ct_setparam both require a CS_DATAFMT to describe an input parameter.
cs_convert requires CS_DATAFMT structures to describe source and destination data. cs_convert is documented in the Open Client and Open Server Common Libraries Reference Manual.

Most routines use only a subset of the fields in a CS_DATAFMT. For example, ct_bind does not use the name, status, and usertype fields, and ct_describe does not use the format field. For information on which fields in the CS_DATAFMT a routine uses, see the reference page for the routine.

        typedef struct _cs_datafmt

             CS_CHAR name[CS_MAX_CHAR];  /* Name of data */

             CS_INT  namelen;            /* Length of name */

             CS_INT  datatype;           /* Datatype */

             CS_INT  format;             /* Format symbols */

             CS_INT  maxlength;          /* Data max length */

             CS_INT  scale;              /* Scale of data */

             CS_INT  precision;          /* Data precision */

             CS_INT  status;             /* Status symbols */

/*

             ** The following field indicates the number of

             ** rows to copy, per ct_fetch call, to a bound

             ** program variable. ct_describe sets this field

             ** to a default value of 1. ct_bind is the only

             ** routine that reads this field.

*/

             CS_INT  count;

/*

             ** These fields are used to support Adaptive Server

             ** user-defined datatypes and international

             ** datatypes:

*/

            CS_INT      usertype;   /* Svr user-def’d type */

            CS_LOCALE   *locale;    /* Locale information */

       } CS_DATAFMT;

where:

name is the name of the data. name is often a column or parameter name.

namelen is the length, in bytes, of name. Set namelen to CS_NULLTERM to indicate a null-terminated name. Set namelen to 0 to if name is NULL.

datatype is a type constant representing the datatype of the data. This is either one of the Open Client datatypes or an Open Client user-defined datatype. For information about datatypes, see “Datatypes support”.

Do not confuse the datatype field with the usertype field. datatype is always used to describe the Open Client datatype of the data. usertype is used only if the data has an Adaptive Server user-defined datatype in addition to an Open Client datatype.

For example, the following Adaptive Server command creates the server user-defined type birthday:
```
sp_addtype birthday, datetime
```
and this command creates a table containing a column of the type:
```
create table birthdays
```
```
 (
```
```
     name        varchar(30),
```
```
     happyday    birthday
```
```
 )
```
If a Client-Library application executes a select against this table and calls ct_describe to get a description of the birthday column in the result set, the datatype and usertype fields in the CS_DATAFMT structure are set as follows:

datatype is set to CS_DATETIME_TYPE. usertype is set to the Adaptive Server ID for the type birthday.

format describes the destination format of character or binary data. format is a bitmask of the following symbols, combined with the OR operator:

**Table 2-15: CS_DATAFMT format field values**
Symbol	Meaning	Notes
CS_FMT_NULLTERM	The data should be null-terminated.	For character or text data
CS_FMT_PADBLANK	The data should be padded with blanks to the full length of the destination variable.	For character or text data
CS_FMT_PADNULL	The data should be padded with NULLs to the full length of the destination variable.	For character, text, binary or image data
CS_FMT_UNUSED	No format information is being provided.	For all data types

maxlength represents various lengths, depending on which Open Client routine is using the CS_DATAFMT. Table 2-16 lists the meanings of maxlength:

**Table 2-16: CS_DATAFMT maxlength field values**
Open Client routine	Value of maxlength
ct_bind	The length of the bind variable.
ct_describe	The maximum possible length of the column or parameter being described.
ct_dyndesc	The maximum possible length of the column or parameter being described.
ct_dynsqlda	The maximum possible length of the column or parameter being described.
ct_param	The maximum desired length of return parameter data.
ct_setparam	The maximum desired length of return parameter data. If ct_setparam’s datalen parameter is passed as NULL, maxlength specifies the length of all input values for the parameter.
cs_convert	The length of the source data and the length of the destination buffer space.

scale is the maximum number of digits to the right of the decimal point in the data. scale is used only with decimal or numeric datatypes.

Permitted values for scale are from 0 to 77. The default is 0. CS_MIN_SCALE, CS_MAX_SCALE, and CS_DEF_PREC define the minimum, maximum, and default scale values, respectively.

To indicate that destination data should use the same scale as the source data, set scale to CS_SRC_VALUE.

scale must be less than or equal to precision.

precision is the maximum number of decimal digits that can be represented in the data. precision is used only with decimal or numeric datatypes.

Values for precision are from 1 to 77. The default is 18. CS_MIN_PREC, CS_MAX_PREC, and CS_DEF_PREC define the minimum, maximum, and default precision values, respectively.

To indicate that destination data should use the same precision as the source data, set precision to CS_SRC_VALUE.

precision must be greater than or equal to scale.

status is a bitmask that indicates various types of information. Table 2-17 lists the values that can make up status:

**Table 2-17: CS_DATAFMT status field values**
Symbolic value	Meaning	Legal for
CS_CANBENULL	The column can contain NULL values.	ct_describe, ct_dyndesc, ct_dynsqlda
CS_HIDDEN	The column is a hidden column that has been exposed. See “Hidden keys”.	ct_describe, ct_dyndesc, ct_dynsqlda
CS_IDENTITY	The column is an identity column.	ct_describe, ct_dyndesc, ct_dynsqlda
CS_KEY	The column is a key column. See the reference page for ct_keydata.	ct_describe, ct_dyndesc, ct_dynsqlda
CS_UPDATABLE	The column is an updatable cursor column.	ct_describe, ct_dyndesc, ct_dynsqlda
CS_VERSION_KEY	The column is part of the version key for the row. Adaptive Server uses version keys for positioning cursors. See the reference page for ct_keydata.	ct_describe, ct_dyndesc, ct_dynsqlda
CS_TIMESTAMP	The column is a timestamp column. An application uses timestamp columns when performing browse-mode updates.	ct_describe
CS_UPDATECOL	The parameter is the name of a column in the update clause of a cursor declare command.	ct_param, ct_setparam, ct_dyndesc, ct_dynsqlda
CS_INPUTVALUE	The parameter is an input parameter value for a Client-Library command.	ct_param, ct_setparam, ct_dyndesc, ct_dynsqlda
CS_RETURN	The parameter is a return parameter to an RPC command.	ct_param, ct_setparam, ct_dyndesc, ct_dynsqlda

count is the number of rows to copy to program variables per ct_fetch call. count is used only by ct_bind.

usertype is the server user-defined datatype, if any, of data returned by the server. usertype is used only for server user-defined types, not for Client-Library user-defined types. For a discussion of Client-Library user-defined types, see “Datatypes support”.
locale is a pointer to a CS_LOCALE structure containing localization information. Set locale to NULL if localization information is not required.

Before using a CS_DATAFMT structure, make sure that locale is valid either by setting it to NULL or to the address of a valid CS_LOCALE structure.