Returns a description of result data.
%INCLUDE CTPUBLIC;
DCL 01 COMMAND FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 ITEM_NUM FIXED BIN(31) INIT(1); 01 DATAFMT, 05 FMT_NAME CHAR(132), 05 FMT_NAMELEN FIXED BIN(31), 05 FMT_TYPE FIXED BIN(31), 05 FMT_FORMAT FIXED BIN(31), 05 FMT_MAXLEN FIXED BIN(31), 05 FMT_SCALE FIXED BIN(31), 05 FMT_PRECIS FIXED BIN(31), 05 FMT_STATUS FIXED BIN(31), 05 FMT_COUNT FIXED BIN(31), 05 FMT_UTYPE FIXED BIN(31), 05 FMT_LOCALE FIXED BIN(31); CALL CTBDESCR (COMMAND, RETCODE, ITEM_NUM, DATAFMT);
(I) Handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(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 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, because 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 CTBBIND, CTBPARAM and CSBCONVERT 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-9.
When this field |
Is used with these result items |
CTBDESCRIBE sets the field to |
|---|---|---|
FMT_NAME |
Regular columns, return parameters |
The null-terminated name of the data item, if any. To indicate that there is no name, set FMT_NAMELEN to 0. |
FMT_NAMELEN |
Regular columns, return parameters |
The actual length, in bytes, of FMT_NAME, not including the null terminator. A zero value here indicates no name. |
FMT_TYPE |
Regular columns, return parameters, return status |
The datatype of the data item. All datatypes listed are valid. A return status always has a datatype of CS_INT. |
FMT_FORMAT |
Not used (CS_FMT_UNUSED) |
Not applicable. |
FMT_MAXLEN |
Regular columns, return parameters |
The maximum possible length, in bytes, of the data for the column or parameter being described. |
FMT_SCALE |
Regular columns and return parameters for which the datatype is packed decimal (CS_PACKED370), or Sybase-decimal/numeric |
The number of digits to the right of the decimal point. |
FMT_PRECIS |
Regular columns and return parameters for which the datatype is packed decimal (CS_PACKED370), or Sybase-decimal/numeric |
The total number of decimal digits in the result data item. |
FMT_STATUS |
Regular columns only |
One or more of the following symbolic values, added together:
|
FMT_COUNT |
Regular columns, return parameters, return status |
The number of rows copied to destination variables per CTBFETCH call. CTBDESCRIBE initializes FMT_COUNT as 1 to provide a default value in case an application uses the CTBDESCRIBE return DATAFMT structure as the CTBBIND input DATAFMT structure. This value is always 1 for return parameters and status results. |
FMT_UTYPE |
Regular columns, return parameters |
The user-defined datatype of the column or parameter, if any. FMT_UTYPE is set in addition to (not instead of) DATATYPE.
|
FMT_LOCALE |
Reserved for future use (CS_FORMAT_UNUSED) |
Reserved for future use. |
CTBDESCRIBE returns one of the following values listed in Table 3-10.
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. CTBDESCRIBE 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 CTBDESCRIBE. It is taken from the sample program SYCTSAA4 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 */
/* */
/*------------------------------------------------------------------*/
RESULT_ROW_PROCESSING: PROC ;
/*------------------------------------------------------------*/
/* 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 CTBBIND(). */
/*------------------------------------------------------------*/
CALL CTBRESIN( CSL_CMD_HANDLE,
CSL_RC,
CS_NUMDATA,
RF_NUMDATA,
STG(RF_NUMDATA),
CF_COL_LEN ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBRESINFO failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE;
END ;
FF_ROW_NUM = FF_ROW_NUM + 1;
/*------------------------------------------------------------*/
/* display the number of connections */
/*------------------------------------------------------------*/
OR2_MAXCONNECT = CF_MAXCONNECT ;
RSLTNO(FF_ROW_NUM) = OUTPUT_ROW_STR2 ;
FF_ROW_NUM = FF_ROW_NUM + 2;
/*------------------------------------------------------------*/
/* display the number of columns */
/*------------------------------------------------------------*/
OR4_NUMDATA = RF_NUMDATA ;
RSLTNO(FF_ROW_NUM) = OUTPUT_ROW_STR4 ;
IF RF_NUMDATA ^= 2 THEN
DO ;
MSGSTR = 'CTBRESINFO returned wrong # of parms' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE;
END ;
FF_ROW_NUM = FF_ROW_NUM + 2;
/*------------------------------------------------------------*/
/* Setup column headings */
/*------------------------------------------------------------*/
RSLTNO(FF_ROW_NUM) = 'FirstName EducLvl' ;
FF_ROW_NUM = FF_ROW_NUM + 1;
RSLTNO(FF_ROW_NUM) = '=========== =======' ;
DO PARM_CNT = 1 TO RF_NUMDATA ;
CALL BIND_COLUMNS ;
END ;
END RESULT_ROW_PROCESSING ;
/*------------------------------------------------------------------*/
/* */
/* Subroutine to bind each data */
/* */
/*------------------------------------------------------------------*/
BIND_COLUMNS: PROC ;
CALL CTBDESCR( CSL_CMD_HANDLE,
CSL_RC,
PARM_CNT,
DATAFMT ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBDESCRIBE failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE;
END ;
/*------------------------------------------------------------*/
/* 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 */
/*------------------------------------------------------------*/
DF_COUNT = 1 ;
SELECT( DF_DATATYPE ) ;
/*------------------------------------------------------------*/
/* bind the first column, FIRSTNME defined as VARCHAR(12) */
/*------------------------------------------------------------*/
WHEN( CS_VARCHAR_TYPE )
DO ;
DF_DATATYPE = CS_VARCHAR_TYPE;
DF_FORMAT = CS_FMT_UNUSED;
DF_MAXLENGTH = STG(CF_COL_FIRSTNME) - 2;
DF_COUNT = 1;
CF_COL_NUMBER = 1;
CALL CTBBIND( CSL_CMD_HANDLE,
CSL_RC,
CF_COL_NUMBER,
DATAFMT,
CF_COL_FIRSTNME,
CF_COL_LEN,
CS_PARAM_NOTNULL,
CF_COL_INDICATOR,
CS_PARAM_NULL);
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBBIND CS_VARCHAR_TYPE failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE;
END ;
END ;
/*------------------------------------------------------------*/
/* bind the second column, EDLEVEL defined as SMALLINT */
/*------------------------------------------------------------*/
WHEN( CS_SMALLINT_TYPE )
DO ;
DF_DATATYPE = CS_SMALLINT_TYPE;
DF_FORMAT = CS_FMT_UNUSED;
DF_MAXLENGTH = STG(CF_COL_EDLEVEL);
DF_COUNT = 1;
CF_COL_NUMBER = 2;
CALL CTBBIND( CSL_CMD_HANDLE,
CSL_RC,
CF_COL_NUMBER,
DATAFMT,
CF_COL_EDLEVEL,
CF_COL_LEN,
CS_PARAM_NOTNULL,
CF_COL_INDICATOR,
CS_PARAM_NULL ) ;
IF CSL_RC ^= CS_SUCCEED THEN
DO ;
MSGSTR = 'CTBBIND CS_SMALLINT_TYPE failed' ;
NO_ERRORS_SW = FALSE ;
CALL ERROR_OUT;
CALL ALL_DONE;
END ;
END ;
OTHERWISE ;
END ; /* end of SELECT( DF_DATATYPE ) */
END BIND_COLUMNS ;
CTBDESCRIBE 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 CTBRESINFO to find out how many result items are present in the current result set.
An application generally needs to call CTBDESCRIBE 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 CTBBIND.
Related functions:
Related topics:
