Sets up result data to be processed.
%INCLUDE CTPUBLIC;
DCL 01 COMMAND FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 RESULT_TYP FIXED BIN(31); CALL CTBRESUL (COMMAND, RETCODE, RESULT_TYP);
(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.
(O) Variable containing the result type. CTBRESULTS returns to this variable a symbolic value that indicates the type of result returned by the current request. The result type can be any of the following symbolic values listed in Table 3-18.
Value |
Meaning |
Result produced |
|---|---|---|
CS_ROW_RESULT (4040) |
Regular row results arrived. |
One or more rows of tabular data. |
CS_PARAM_RESULT (4042) |
Return parameter results arrived. |
A single row of return parameters. |
CS_STATUS_RESULT (4043) |
Stored procedure return status results arrived. |
A single row containing a single status. |
CS_CMD_DONE (4046) |
The results of the request processed completely. |
Not applicable. |
CS_CMD_SUCCEED (4047) |
A request that returns no data, such as a language request containing an insert statement, processed successfully. |
No results. |
CS_CMD_FAIL (4048) |
The server encountered an error while executing the request. This value can indicate that the connection failed or was terminated. |
No results. |
CTBRESULTS returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
A result set is available for processing. |
CS_END_RESULTS (-205) |
No more result sets are available for processing. |
CS_FAIL (-2) |
The routine failed. |
CS_CANCELLED (-202) |
Results were cancelled. |
The following code fragment demonstrates how CTBRESULTS is used to describe a result row for a language request. It is taken from the sample program SYCTSAA4 in Appendix A, “Sample Language Application.”
/*------------------------------------------------------------------*/
/* */
/* Subroutine to process the result */
/* */
/*------------------------------------------------------------------*/
PROCESS_RESULTS: PROC ;
/*------------------------------------------------------------*/
/* set up the results data */
/*------------------------------------------------------------*/
CALL CTBRESUL( CSL_CMD_HANDLE,
CSL_RC,
RF_TYPE ) ;
/*------------------------------------------------------------*/
/* determine the outcome of the comand execution */
/*------------------------------------------------------------*/
SELECT( CSL_RC ) ;
WHEN( CS_SUCCEED )
DO ;
/*--------------------------------------------------------------*/
/* determine the type of result returned by the current request */
/*--------------------------------------------------------------*/
SELECT( RF_TYPE ) ;
/*------------------------------------------------------------*/
/* process row results */
/*------------------------------------------------------------*/
WHEN( CS_ROW_RESULT )
DO ;
CALL RESULT_ROW_PROCESSING ;
DO WHILE( ^NO_MORE_ROWS ) ;
CALL FETCH_ROW_PROCESSING ;
END ;
END ;
/*------------------------------------------------------------*/
/* process parameter results --- there should be no parameter */
/* to process */
/*------------------------------------------------------------*/
WHEN( CS_PARAM_RESULT )
DO ;
NO_MORE_ROWS = FALSE ;
END ;
/*------------------------------------------------------------*/
/* process status results --- the stored procedure status */
/* result will not be processed in this example */
/*------------------------------------------------------------*/
WHEN( CS_STATUS_RESULT )
DO ;
NO_MORE_ROWS = FALSE ;
END ;
/*------------------------------------------------------------*/
/* print an error message if the server encountered an error */
/* while executing the request */
/*------------------------------------------------------------*/
WHEN( CS_CMD_FAIL )
DO ;
NO_ERRORS_SW = FALSE ;
MSGSTR =
'CTBRESUL returned CS_CMD-FAIL restype' ;
CALL ERROR_OUT ;
END ;
/*------------------------------------------------------------*/
/* print a message for successful commands that returned no */
/* data( optional ) */
/*------------------------------------------------------------*/
WHEN( CS_CMD_SUCCEED )
DO ;
MSGSTR = 'CTBRESUL returned CS_CMD_SUCCEED restype' ;
END ;
/*------------------------------------------------------------*/
/* print a message for requests that have been processed */
/* successfully( optional ) */
/*------------------------------------------------------------*/
WHEN( CS_CMD_DONE )
DO ;
MSGSTR = 'CTBRESUL returned CS_CMD_DONE restype' ;
END ;
OTHERWISE
DO ;
NO_MORE_RESULTS = TRUE ;
NO_ERRORS_SW = FALSE ;
MSGSTR = 'CTBRESUL returned UNKNOWN restype' ;
CALL ERROR_OUT ;
END ;
END ; /* end of SELECT( RF_TYPE ) */
END ;
/*------------------------------------------------------------*/
/* print an error message if the CTBRESULTS call failed */
/*------------------------------------------------------------*/
WHEN( CS_FAIL )
DO ;
NO_MORE_RESULTS = TRUE ;
NO_ERRORS_SW = FALSE ;
MSGSTR = 'CTBRESUL returned CS_FAIL ret_code' ;
CALL ERROR_OUT ;
END ;
/*------------------------------------------------------------*/
/* drop out of the results loop if no more result sets are */
/* available for processing or if the results were cancelled */
/*------------------------------------------------------------*/
WHEN( CS_END_RESULTS )
DO ;
NO_MORE_RESULTS = TRUE ;
END ;
WHEN( CS_CANCELLED )
DO ;
NO_MORE_RESULTS = TRUE ;
END ;
OTHERWISE
DO ;
NO_MORE_RESULTS = TRUE ;
NO_ERRORS_SW = FALSE ;
MSGSTR =
'CTBRESUL returned unknown ret_code' ;
CALL ERROR_OUT ;
END ;
END ; /* end of SELECT( CSL_RC ) */
RF_TYPE = 0 ;
END PROCESS_RESULTS ;
CTBRESULTS tells the application what kind of results returned and sets up result data for processing. An application calls CTBRESULTS after sending a request to the server through CTBSEND and before binding and retrieving the results of that request (if any) with CTBBIND and CTBFETCH.
“Result data” is an umbrella term for all the types of data that a server can return to an application:
Regular rows
Return parameters
Stored procedure return status
CTBRESULTS is used to set up all of these types of results for processing.
Result data is returned to an application in the form of result sets. A result set includes only a single type of result data. For example, a regular row result set contains only regular rows, and a return parameter result set contains only return parameters.
Because a request can generate multiple result sets, an application must call CTBRESULTS as long as it continues to return CS_SUCCEED, indicating that results are available. The simplest way to do this is in a loop that terminates when CTBRESULTS fails to return CS_SUCCEED. After the loop, an application can test the CTBRESULTS final return code to determine why the loop terminated.
Results are returned to an application in the order in which they are produced. However, this order is not always easy to predict. For example, when an application calls a stored procedure or transaction that in turn calls another stored procedure or transaction, the application might receive a number of row result sets, as well as a return parameter and a return status result set. The order in which these results are returned depends on how the called stored procedure or transaction is written.
For this reason, we recommend that you include a series of IF statements in your application, ending with a statement that handles all types of results that can be received. The RESULT_TYP argument indicates what type of result data the result set contains.
CTBRESULTS sets the result type to CS_CMD_DONE to indicate that the results of a logical command processed completely. A logical command is any command defined through CTBCOMMAND, with the following rules:
Each Transact-SQL select statement inside a stored procedure is a logical command. Other Transact-SQL statements inside stored procedures do not count as logical commands.
Each Transact-SQL statement in a language request is a logical command.
A result type of CS_CMD_SUCCEED or CS_CMD_FAIL is immediately followed by a result type of CS_CMD_DONE.
To cancel remaining results from a request (and eliminate the need to continue calling CTBRESULTS until it fails to return CS_SUCCEED), call CTBCANCEL.
A runtime error on a language request containing an execute statement returns CS_CMD_FAIL. However, a run-time error on a statement inside a stored procedure or transaction does not return CS_CMD_FAIL. For example, if a called stored procedure or transaction contains an insert statement and the user does not have insert permission on the database table, the insert statement fails, but CTBRESULTS still returns CS_SUCCEED.
To check for runtime errors inside stored procedures or transactions, examine the procedure return status. This value is returned as a return status result set immediately following the row and parameter results, if any. If the error generates a server message, the message is also available to the application.
If results are coming from Open ServerConnect, a return status of TDS_DONE_ERROR indicates an error.
Related functions:
Related topics:
