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_NAME]; /* 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 “Types”.
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 new 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:
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. The following table lists the meanings of maxlength:
Open Client routine |
Value of maxlength |
---|---|
The length of the bind variable. |
|
The maximum possible length of the column or parameter being described. |
|
The maximum possible length of the column or parameter being described. |
|
The maximum possible length of the column or parameter being described. |
|
The maximum desired length of return parameter data. |
|
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. The following table lists the values that can make up status:
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 “Types”.
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.