Sets up result data to be processed.
CS_RETCODE ct_results(command, result_type); CS_COMMAND *command; CS_INT *result_type;
(I) Handle for this client/server operation. This handle is defined in the associated ct_cmd_alloc call.
(O) Variable containing the result type. ct_results 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-15.
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. |
ct_results 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 canceled. |
The following code fragment demonstrates how ct_results can describe a result row for a language request. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”
/********************************************************************/
/* */
/* Subroutine to process the result */
/* */
/********************************************************************/
void proces_results ()
{
CS_INT rc;
/*------------------------------------------------------------*/
/* Set up the results data */
/*------------------------------------------------------------*/
rc = ct_results (cmd, &results_type);
/*------------------------------------------------------------*/
/* Determine the outcome of the comand execution */
/*------------------------------------------------------------*/
switch (rc)
{
case CS_SUCCEED:
/*--------------------------------------------------------------*/
/* Determine the type of result returned by the current request */
/*--------------------------------------------------------------*/
switch (results_type)
{
/*------------------------------------------------------------*/
/* Process row results */
/*------------------------------------------------------------*/
case CS_ROW_RESULT:
result_row_processing ();
fetch_row_processing ();
break;
/*------------------------------------------------------------*/
/* Process parameter results --- there should be no parameter */
/* to process */
/*------------------------------------------------------------*/
case CS_PARAM_RESULT:
no_more_results = FALSE;
break;
/*------------------------------------------------------------*/
/* process status results --- the stored procedure status */
/* result will not be processed in this example */
/*------------------------------------------------------------*/
case CS_STATUS_RESULT:
no_more_results = FALSE;
break;
/*------------------------------------------------------------*/
/* print an error message if the server encountered an error */
/* while executing the request */
/*------------------------------------------------------------*/
case CS_CMD_FAIL:
no_errors_sw = FALSE ;
strncpy (msgstr,
"CT_RESUL returned CS_CMD-FAIL restype",
msg_size);
error_out (rc);
break;
/*------------------------------------------------------------*/
/* print a message for successful commands that returned no */
/* data( optional ) */
/*------------------------------------------------------------*/
case CS_CMD_SUCCEED:
strncpy (msgstr,
"CT_RESUL returned CS_CMD_SUCCEED restype",
msg_size);
break;
/*------------------------------------------------------------*/
/* print a message for requests that have been processed */
/* successfully( optional ) */
/*------------------------------------------------------------*/
case CS_CMD_DONE:
strncpy (msgstr,
"CT_RESUL returned CS_CMD_DONE restype",
msg_size);
break;
default:
no_more_results = TRUE ;
no_errors_sw = FALSE ;
strncpy (msgstr,
"CT_RESUL returned UNKNOWN restype",
msg_size);
error_out (rc);
break;
} /* end of switch (result_type) */
break; /* case of CS_SUCCEED */
/*------------------------------------------------------------*/
/* print an error message if the CTBRESULTS call failed */
/*------------------------------------------------------------*/
case CS_FAIL:
no_more_results = TRUE ;
no_errors_sw = FALSE ;
strncpy (msgstr, "CT_RESULTS returned CS_FAIL ret_code",
msg_size);
error_out (rc);
break;
/*------------------------------------------------------------*/
/* drop out of the results loop if no more result sets are */
/* available for processing or if the results were cancelled */
/*------------------------------------------------------------*/
case CS_END_RESULTS:
case CS_CANCELLED:
no_more_results = TRUE ;
break;
default:
no_more_results = TRUE ;
no_errors_sw = FALSE ;
strncpy (msgstr, "CT_RESULTS returned unknown ret_code",
msg_size);
error_out (rc);
break;
} /* end of switch (rc) */
} /* end process_results */
ct_results tells the application what kind of results returned and sets up result data for processing. An application calls ct_results after sending a request to the server through ct_send and before binding and retrieving the results of that request (if any) with ct_bind and ct_fetch.
“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
ct_results sets 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 ct_results 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 ct_results fails to return CS_SUCCEED. After the loop, an application can test the ct_results 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.
The result_type argument indicates what type of result data the result set contains.
ct_results sets the result type to CS_CMD_DONE to indicate that the results of a logical command processed completely.
A logical command is defined as any command defined through ct_command, 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 ct_results until it fails to return CS_SUCCEED), call ct_cancel.
A run-time error on a language request that contains 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 ct_results still returns CS_SUCCEED.
To check for run-time errors inside stored procedures or transactions, examine the procedure return status. This value returns 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
| Copyright © 2005. Sybase Inc. All rights reserved. |
|
|
