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.e
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
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:
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:
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.
