CS_DATAFMT structure

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

srv_bind uses a CS_DATAFMT structure to describe a source or destination program variable.
srv_descfmt uses a CS_DATAFMT structure to describe the client data.
cs_convert requires CS_DATAFMT structures to describe source and destination data.

Most routines use only a subset of the fields in a CS_DATAFMT. For example, srv_bind does not use the name and usertype fields, and srv_descfmt does not use the format field. For information on which fields in the CS_DATAFMT a routine uses, see that routine’s reference page.

A CS_DATAFMT structure is defined as follows:

typedef struct _cs_datafmt

     CS_CHAR       name[CS_MAX_NAME];   /* Name of data.       */

      CS_INT        namelen;             /* Length of name.     */

      CS_INT        datatype;            /* Datatype of data.   */

      CS_INT        format;              /* Format symbols.     */

      CS_INT        maxlength;           /* Max length of data. */

      CS_INT        scale;               /* Scale of data.      */

      CS_INT        precision;           /* Precision of data.  */

      CS_INT        status;              /* Status symbols.     */

/*

       ** The following field is not used in Open Server.

       ** It must be set to 1 or 0.

*/

       CS_INT     count;

/*

       ** These fields are used to support user-defined

       ** datatypes and international datatypes:

*/

       CS_INT    usertype;            /* User-defined type.*/

       CS_LOCALE *locale;             /* Locale information. */

} CS_DATAFMT;

where:

name is the name of the data, that is, the 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 if name is NULL.
datatype is the datatype of the data, which is one of the Open Server datatypes listed in “Types”.

The datatype field is used to describe the Open Server datatype of the data. usertype is only used if the data has an application-defined datatype in addition to an Open Server datatype.

For example, this Adaptive Server command creates the Adaptive Server user-defined type birthday:
```
sp_addtype birthday, datetime
```
and this command creates a table containing a column of the new type:
```
create table birthdays
```
```
(
```
```
          name         varchar(30),
```
```
          happyday     birthday
```
```
 )
```
An Open Server application that supported user-defined datatypes would return this information to the client by setting the CS_DATAFMT datatype field to CS_DATETIME_TYPE and the usertype field to the user-defined ID for the type birthday.

format describes the destination format of character or binary data. format is a bitmask of these symbols, OR’d together. Table 2-7 summarizes the legal values for format

**Table 2-7: Values for format (CS_DATAFMT)**
Symbol	To indicate	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 binary, image, character, or text data
CS_FMT_UNUSED	Neither padding nor null termination is applicable to the datatype.	For all datatypes

maxlength can represent various lengths, depending on which Open Server routine is using the CS_DATAFMT. Table 2-8 describes the various lengths maxlength can represent:

**Table 2-8: Meaning of maxlength (CS_DATAFMT)**
Open Server routine	maxlength is
srv_bind	The length of the bind variable
srv_descfmt	The maximum possible length of the column or parameter being described
cs_convert	The length of the source data and the length of the destination buffer space

scale is the scale of the data. It is used only with decimal or numeric datatypes.

Legal values for scale are from CS_MIN_SCALE to CS_MAX_SCALE. The default scale is CS_DEF_SCALE.

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 precision of the data. It is used only with decimal or numeric datatypes.

Legal values for precision are from CS_MIN_PREC to CS_MAX_PREC. The default precision is CS_DEF_PREC.

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 used to indicate various types of information. Table 2-9 summarizes the types of information that status can contain:

**Table 2-9: Values for status (CS_DATAFMT)**
Symbolic value	To indicate
CS_CANBENULL	The column can contain NULL.
CS_DESCIN	The CS_DATAFMT structure describes a Dynamic SQL input parameter.
CS_DESCOUT	The CS_DATAFMT structure describes a Dynamic SQL output parameter.
CS_HIDDEN	The column is a “hidden” column that has been exposed.
CS_INPUTVALUE	The parameter is an input parameter value for a cursor open command or a non-return RPC parameter.
CS_KEY	The column is a key column.
CS_RETURN	The parameter is a return parameter to an RPC command.
CS_TIMESTAMP	The column is a timestamp column. An application uses timestamp columns when performing browse-mode updates.
CS_UPDATABLE	The column is an updatable cursor column.
CS_UPDATECOL	The parameter is the name of a column in the update clause of a cursor declare command.
CS_VERSION_KEY	The column is part of the version key for the row. Adaptive Server uses version keys for positioning.
CS_NODEFAULT	There is no default specified for the parameter.

count is not used by Server-Library routines. It should always be set to 0 or 1.
usertype is the user-defined datatype, if any, of data returned.
locale is a pointer to a CS_LOCALE structure containing localization information. Set locale to NULL if localization information is not required.