Sets up result data to be processed.
COPY CTPUBLIC.
01 COMMAND PIC S9(9) COMP SYNC. 01 RETCODE PIC S9(9) COMP SYNC. 01 RESULT-TYP PIC S9(9) COMP SYNC.
CALL 'CTBRESUL' USING 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 “Return value,” 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 2-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 can describe a result row for a language request. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”
*========================================================
*== ==
*== Subroutine to process result ==
*== ==
*========================================================
RESULTS-PROCESSING.
***************************
* SET UP THE RESULTS DATA *
***************************
CALL 'CTBRESUL' USING CSL-CMD-HANDLE
CSL-RC
RESTYPE.
**************************************************
* DETERMINE THE OUTCOME OF THE COMMAND EXECUTION *
**************************************************
EVALUATE CSL-RC
WHEN CS-SUCCEED
****************************************************************
* DETERMINE THE TYPE OF RESULT RETURNED BY THE CURRENT REQUEST *
****************************************************************
EVALUATE RESTYPE
***********************
* PROCESS ROW RESULTS *
***********************
WHEN CS-ROW-RESULT
MOVE LOW-VALUES TO A5PANELO
PERFORM RESULT-ROW-PROCESSING
MOVE 'Y' TO SW-FETCH
PERFORM FETCH-ROW-PROCESSING UNTIL NO-MORE-ROWS
*************************************************************
* PROCESS PARAMETER RESULTS - THERE SHOULD BE NO PARAMETERS *
* TO PROCESS *
*************************************************************
WHEN CS-PARAM-RESULT
MOVE 'Y' TO SW-FETCH
***************************************************************
* PROCESS STATUS RESULTS - THE STORED PROCEDURE STATUS RESULT *
* WILL NOT BE PROCESSED IN THIS EXAMPLE *
***************************************************************
WHEN CS-STATUS-RESULT
MOVE 'Y' TO SW-FETCH
*************************************************************
* PRINT AN ERROR MESSAGE IF THE SERVER ENCOUNTERED AN ERROR *
* WHILE EXECUTING THE REQUEST *
*************************************************************
WHEN CS-CMD-FAIL
STRING
'CTBRESUL returned CS-CMD-FAIL restype'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
*****************************************************************
* PRINT A MESSAGE FOR SUCCESSFUL COMMANDS THAT RETURNED NO DATA *
* (OPTIONAL) *
*****************************************************************
WHEN CS-CMD-SUCCEED
STRING
'CTBRESUL returned CS-CMD-SUCCEED restype'
DELIMITED BY SIZE INTO MSGSTR
*********************************************************
* PRINT A MESSAGE FOR REQUESTS THAT HAVE BEEN PROCESSED *
* SUCCESSFULLY (OPTIONAL) *
*********************************************************
WHEN CS-CMD-DONE
STRING 'CTBRESUL returned CS-CMD-DONE restype'
DELIMITED BY SIZE INTO MSGSTR
WHEN OTHER
STRING 'CTBRESUL returned UNKNOWN restype'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
MOVE 'N' TO SW-RESULTS
END-EVALUATE
********************************************************
* PRINT AN ERROR MESSAGE IF THE CTBRESULTS CALL FAILED *
********************************************************
WHEN CS-FAIL
MOVE 'N' TO SW-RESULTS
STRING 'CTBRESUL returned CS-FAIL ret-code'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
*************************************************************
* 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
MOVE 'N' TO SW-RESULTS
WHEN CS-CANCELLED
MOVE 'N' TO SW-RESULTS
WHEN OTHER
MOVE 'N' TO SW-RESULTS
STRING 'CTBRESUL returned UNKNOWN ret-code'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
END-EVALUATE.
MOVE 0 TO RESTYPE.
RESULTS-PROCESSING-EXIT.
EXIT.
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 run-time 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.
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. |
|
|
