Returns a description of result data.
CS_RETCODE ct_describe(command, item_num, datafmt); CS_COMMAND *command; CS_INT item_num; CS_DATAFMT *datafmt;
(I) Handle for this client/server operation. This handle is defined in the associated ct_cmd_alloc call.
(I) Ordinal number of the column, parameter, or status being returned. This value is an integer.
When describing a column, item_num is the column number. For example, the first column in the select list of a SQL select statement is column number 1, the second is column number 2, and so forth.
When describing a return parameter, item_num is the ordinal rank of the parameter. The first parameter returned by a procedure or transaction is number 1. Adaptive Server Enterprise stored procedure return parameters are returned in the order originally specified in the create procedure statement for the stored procedure. This is not necessarily the same order as specified in the RPC that invoked the stored procedure or transaction.
In determining what number to assign to item_num, do not count non-return parameters. For example, if the second parameter in a stored procedure or transaction is the only return parameter, its item_num is 1.
When describing a stored procedure return status, item_num must be 1, as there can be only a single status in a return status result set.
To clear all bindings, assign item_num a value of CS_UNUSED.
(O) A structure that contains a description of the result data item referenced by item_num. This structure is also used by ct_bind, ct_param and cs_convert and is explained in the Topics chapter, under “DATAFMT structure”.
WARNING! You must initialize DATAFMT to zeroes. Failure to do so causes addressing exceptions.
The DATAFMT structure contains the following fields listed in Table 3-5.
When this field |
Is used with these result items |
ct_describe sets the field to |
|---|---|---|
name |
Regular columns, return parameters |
The null-terminated name of the data item, if any. To indicate a name does not exist, set namelen to 0. |
namelen |
Regular columns, return parameters |
The actual length, in bytes, of name, not including the null terminator. A zero value here indicates no name. |
datatype |
Regular columns, return parameters, return status |
The datatype of the data item. All items listed in “DATAFMT structure” are valid. A return status always has a datatype of CS_INT. |
format |
Not used (CS_FMT_UNUSED) |
Not applicable. |
maxlength |
Regular columns, return parameters |
The maximum possible length, of the data for the column or parameter being described. |
scale |
Regular columns and return parameters with a datatype of packed decimal (CS_PACKED370), or Sybase-decimal/numeric |
The number of digits to the right of the decimal point. |
precision |
Regular columns and return parameters whose datatype is packed decimal (CS_PACKED370), or Sybase-decimal/numeric |
The total number of decimal digits in the result data item. |
status |
Regular columns only |
One or more of the following symbolic values, added together:
|
count |
Regular columns, return parameters, return status |
The number of rows copied to destination variables per ct_fetch call. ct_describe initializes count as 1 to provide a default value in case an application uses the ct_describe return datafmt structure as the ct_bind input datafmt structure. This value is always 1 for return parameters and status results. |
usertype |
Regular columns, return parameters |
The user-defined datatype of the column or parameter, if any. usertype is set in addition to (not instead of) DATATYPE.
|
locale |
Reserved for future use (CS_FORMAT_UNUSED) |
Reserved for future use. |
ct_describe returns one of the following values listed in Table 3-6.
Value |
Meaning |
|---|---|
CS-SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. ct_describe returns CS_FAIL if item_num does not represent a valid result data item. |
TDS_CANCEL_RECEIVED (-12) |
Operation canceled. The remote partner issued a cancel. The current operation failed. |
TDS_CONNECTION_TERMINATED (-4997) |
The connection is not active. |
TDS_NO_COMPUTES_ALLOWED (-60) |
Compute results are not supported. |
TDS_RESULTS_CANCELED (-49) |
A cancel was sent to purge results. |
TDS_WRONG_STATE (-6) |
Program is in the wrong communication state to issue this call. |
The following code fragment demonstrates the use of ct_describe. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
This field is used for datatypes defined at the server,
not for Open Client user-defined datatypes.
/********************************************************************/
/* */
/* Subroutine to process result rows */
/* */
/********************************************************************/
void result_row_processing ()
{
CS_INT rc;
CS_INT col_len;
CS_INT &&numcol;
CS_INT parm_cnt;
char msg1[40] = "The maximum number of connections is ";
char msg2[25] = "The number of columns is ";
char wrk_str [4];
char period = '.';
/*------------------------------------------------------------*/
/* We need to bind the data to program variables. We don't */
/* care about the indicator variable so we'll pass NULL for */
/* that parameter in OC_BIND(). */
/*------------------------------------------------------------*/
rc = ct_res_info(cmd,CS_NUMDATA,&&numcol,
sizeof(&numcol),&col_len);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_RES_INFO failed", msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* display the number of connections */
/*------------------------------------------------------------*/
row_num = row_num + 1;
strncpy (RS[row_num].rsltno, msg1, msg_size);
cvtleft = 4; /* Digits to the left */
cvtright = 0; /* Digits to the right */
SYCVTD(maxconnect, wrk_str,
cvtleft, cvtright, cvtwork, cvtdbl, CS_TRUE);
strncat (RS[row_num].rsltno, wrk_str, 4);
row_num = row_num + 2;
/*------------------------------------------------------------*/
/* display the number of columns */
/*------------------------------------------------------------*/
strncpy (RS[row_num].rsltno, msg2, sizeof(msg2));
cvtleft = 4; /* Digits to the left */
cvtright = 0; /* Digits to the right */
SYCVTD(&numcol, wrk_str,
cvtleft, cvtright, cvtwork, cvtdbl, CS_TRUE);
strncat (RS[row_num].rsltno, wrk_str, 4);
row_num = row_num + 2;
if (&numcol != 2)
{
strncpy (msgstr, "CT_RES_INFO returned wrong # of parms",
msg_size);
no_errors_sw = FALSE ;
error_out (rc);
}
/*------------------------------------------------------------*/
/* Setup column headings */
/*------------------------------------------------------------*/
strncpy (RS[row_num].rsltno,
"FirstName EducLvl", text_size);
row_num = row_num + 1;
strncpy (RS[row_num].rsltno,
"========== =======", text_size);
for (parm_cnt = 1; parm_cnt <= &numcol; ++parm_cnt)
bind_columns (parm_cnt);
} /* end result_row_processing */
/********************************************************************/
/* */
/* Subroutine to bind each data */
/* */
/********************************************************************/
void bind_columns (parm_cnt)
CS_INT parm_cnt;
{
CS_INT rc;
CS_INT col_len;
CS_DATAFMT datafmt;
rc= ct_describe(cmd, parm_cnt, &dtafmt);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_DESCRIBE failed", msg_size);
no_errors_sw = FALSE ;
error_out(rc);
}
/*------------------------------------------------------------*/
/* We need TO bind the data TO program variables. We don't */
/* care about the indicator variable so we'll pass NULL for */
/* that PARAMeter in OC_BIND(). */
/*------------------------------------------------------------*/
/*------------------------------------------------------------*/
/* rows per fetch */
/*------------------------------------------------------------*/
switch (datafmt.datatype)
{
/*------------------------------------------------------------*/
/* bind the first column, FIRSTNME defined as VARCHAR(12) */
/*------------------------------------------------------------*/
case CS_VARCHAR_TYPE:
rc= ct_bind(cmd, parm_cnt, &dtafmt, &col_firstnme,
&col_len, CS_NULL);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_BIND CS_VARCHAR_TYPE failed",
msg_size);
no_errors_sw = FALSE ;
error_out(rc);
}
break;
/*------------------------------------------------------------*/
/* bind the second column, EDLEVEL defined as SMALLINT */
/*------------------------------------------------------------*/
case CS_SMALLINT_TYPE:
rc= ct_bind(cmd, parm_cnt, &dtafmt, &col_edlevel,
&col_len, CS_NULL);
if (rc != CS_SUCCEED)
{
strncpy (msgstr, "CT_BIND CS_SMALLINT_TYPE failed",
msg_size);
no_errors_sw = FALSE ;
error_out(rc);
}
break;
default:
break;
} /* end of switch (datatype) */
} /* end bind_columns */
ct_describe returns a complete description of a result data item in the current result set. Result data items include regular result columns, return parameters, and stored procedure return status values.
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 after it establishes a connection and sends a request, and before it binds the result item to a program variable using ct_bind.
ct_describe also indicates when the client issues a cancel.
Related functions
Related topics
