ct_describe

Description

Return a description of result data.

Syntax

CS_RETCODE ct_describe(cmd, item, datafmt)
 
 CS_COMMAND   *cmd;
 CS_INT                 item;
 CS_DATAFMT      *datafmt;

Parameters

cmd

A pointer to the CS_COMMAND structure managing a client/server operation.

item

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.

NoteAn 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.

datafmt

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:

Table 3-18: Fields in the CS_DATAFMT structure as set by ct_describe

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 “Datatypes support” 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 (in bytes) 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:

  • 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. For information about hidden columns, see “Hidden keys”.

  • CS_IDENTITY to indicate that the column is an identity column.

  • CS_KEY to indicate the column is part of the key for a table.

  • CS_VERSION_KEY to indicate the column is part of the version key for the row.

  • CS_TIMESTAMP to indicate 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 the cursor declare commandC.

  • CS_RETURN to indicate that the column is a return parameter of an RPC command.

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.

Returns

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.

Examples

Example 1

        /* 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 sample program.

Usage

See also

ct_bind, ct_fetch, ct_res_info, ct_results, “Results”