CTBRESULTS

Description

Sets up result data to be processed.

Syntax

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.

Parameters

COMMAND: (I) Handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call.

RETCODE: (O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Return value,” in this section.

RESULT-TYP

(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.

**Table 3-18: Values for RESULT-TYP (CTBRESULTS)**
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.

Returns

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.

Examples

Example 1

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.

Usage

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.

The CTBRESULTS loop

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.

When are the results of a command completely processed?

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.

Canceling results

To cancel remaining results from a request (and eliminate the need to continue calling CTBRESULTS until it fails to return CS-SUCCEED), call CTBCANCEL.

CTBRESULTS and stored procedures

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.