Return a description of result data.
CS_RETCODE ct_describe(cmd, item, datafmt) CS_COMMAND *cmd; CS_INT item; CS_DATAFMT *datafmt;
A pointer to the CS_COMMAND structure managing a client/server operation.
An integer representing the result item of interest.
When retrieving a column description, item is the column’s column number. The first column in a select-list is column number 1, the second is number 2, and so forth.
When retrieving a compute column description, item is the column number of the compute column. Compute columns are returned in the order in which they are listed in the compute clause. The first column returned is number 1.
When retrieving a return parameter description, item is the parameter number of the parameter. The first parameter returned by a stored procedure is number 1. Stored procedure return parameters are returned in the same order as the parameters were originally specified in the stored procedure’s create procedure statement. This is not necessarily the same order as specified in the RPC command that invoked the stored procedure. In determining what number to pass as item do not count non-return parameters. For example, if the second parameter in a stored procedure is the only return parameter, pass item as 1.
When retrieving a stored procedure return status description, item must be 1, as there can be only a single status in a return status result set.
When retrieving format information, item takes a column or compute column number.
An application cannot call ct_describe after ct_results indicates
a result set of type CS_MSG_RESULT. This is because
a result type of CS_MSG_RESULT has no data items
associated with it. Parameters associated with a message are returned
as a CS_PARAM_RESULT result set. Likewise, an
application cannot call ct_describe after ct_results sets
its *result_type parameter
to CS_CMD_DONE, CS_CMD_SUCCEED,
or CS_CMD_FAIL to indicate command status information.
A pointer to a CS_DATAFMT structure. ct_describe fills *datafmt with a description of the result data item referenced by item.
ct_describe fills in the following fields in the CS_DATAFMT:
Field name |
Types of result items |
Value of field after ct_describe call |
|---|---|---|
name |
Regular columns, column formats, and return parameters. |
The null-terminated name of the data item, if any. A NULL name is indicated by a namelen of 0. |
namelen |
Regular columns, column formats, and return parameters. |
The actual length of the name, not including the null terminator. 0 to indicate a NULL name. |
datatype |
Regular columns, column formats, return parameters, return status, compute columns, and compute column formats. |
A type constant (CS_xxx_TYPE) representing the datatype of the item. All type constants listed in “Types” are valid, except CS_VARCHAR_TYPE and CS_VARBINARY_TYPE. A return status has a datatype of CS_INT_TYPE. A compute column’s datatype depends on the type of the underlying column and the aggregate operator that created the column. |
format |
Not used. |
|
maxlength |
Regular columns, column formats, and return parameters. |
The maximum possible length of the data for the column or parameter. |
scale |
Regular columns, column formats, return parameters, compute columns, or compute column formats of type numeric or decimal. |
The maximum number of digits to the right of the decimal point in the result data item. |
precision |
Regular columns, column formats, return parameters, compute columns, or compute column formats of type numeric or decimal. |
The maximum number of decimal digits that can be represented in the result data item. |
status |
Regular columns and column formats. |
A bitmask of the following values:
|
count |
Regular columns, column formats, return parameters, return status, compute columns, and compute column formats. |
count represents the number of rows copied to program variables per ct_fetch call. ct_describe sets count to 1 to provide a default value in case an application uses ct_describe’s return CS_DATAFMT as ct_bind’s input CS_DATAFMT. |
usertype |
Regular columns, column formats, and return parameters. |
The Adaptive Server user-defined datatype of the column or parameter, if any. usertype is set in addition to (not instead of) datatype. |
locale |
Regular columns, column formats, return parameters, return status, compute columns, and compute column formats. |
A pointer to a CS_LOCALE structure that contains locale information for the data. This pointer can be NULL. |
When ct_describe is called, it fills *datafmt with information about the column or parameter being described. The status field of *datafmt is a bitmask of the following values:
CS_CANBENULL to indicate that the column can contain NULL values.
CS_HIDDEN to indicate that the column is a “hidden” column that has been exposed.
CS_IDENTITY to indicate that the column is an identity column.
CS_KEY to indicate that the column is part of the key for a table.
CS_VERSION_KEY to indicate that the column is part of the version key for the row.
CS_TIMESTAMP to indicate that the column is a timestamp column.
CS_UPDATABLE to indicate that the column is an updatable cursor column.
CS_UPDATECOL to indicate that the column is in the update clause of a cursor declare command.
CS_RETURN to indicate that the column is a return parameter of an RPC command.
ct_describe returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
CS_BUSY |
An asynchronous operation is already pending for this connection. See “Asynchronous programming”. |
ct_describe returns CS_FAIL if item does not represent a valid result data item.
/* ex_fetch_data()*/
CS_RETCODE CS_PUBLIC
ex_fetch_data(cmd)
CS_COMMAND *cmd;
{
CS_RETCODE retcode;
CS_INT num_cols;
CS_INT i;
CS_INT j;
CS_INT row_count = 0;
CS_DATAFMT *datafmt;
EX_COLUMN_DATA *coldata;
/*
** Determine the number of columns in this result
** set
*/
...CODE DELETED...
for (i = 0; i < num_cols; i++)
{
/*
** Get the column description. ct_describe()
** fills the datafmt parameter with a
** description of the column.
*/
retcode = ct_describe(cmd, (i + 1),
&datafmt[i]);
if (retcode != CS_SUCCEED)
{
ex_error("ex_fetch_data: ct_describe()
failed");
break;
}
/* Now bind columns */
...CODE DELETED.....
}
/* Now fetch rows */
...CODE DELETED.....
return retcode;
}
This code excerpt is from the exutils.c example program.
An application can use ct_describe to retrieve a description of a regular result column, a return parameter, a stored procedure return status number, or a compute column.
An application can also use ct_describe to retrieve format information. Client-Library indicates that format information is available by setting ct_results’ *result_type to CS_ROWFMT_RESULT or CS_COMPUTEFMT_RESULT.
An application cannot call ct_describe after ct_results sets its *result_type parameter to CS_MSG_RESULT, CS_CMD_SUCCEED, CS_CMD_DONE, or CS_CMD_FAIL. This is because, in these cases, there are no result items to describe.
An application can call ct_res_info to find out how many result items are present in the current result set.
An application generally needs to call ct_describe to describe a result data item before it binds the result item to a program variable using ct_bind.
See “CS_DATAFMT structure” for a description.
See “Results” for a description of result types.
