Fetches result data.
COPY CTPUBLIC.
01 COMMAND PIC S9(9) COMP SYNC. 01 RETCODE PIC S9(9) COMP SYNC. 01 TYP PIC S9(9) COMP SYNC. 01 OFFSET PIC S9(9) COMP SYNC. 01 OPTION PIC S9(9) COMP SYNC. 01 ROWS-READ PIC S9(9) COMP SYNC.
CALL 'CTBFETCH' USING COMMAND RETCODE TYP OFFSET OPTION ROWS-READ.
(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.
(I) This argument is currently unused and should be passed as CS-UNUSED in order to ensure compatibility with future versions of Client-Library.
(I) This argument is currently unused and should be passed as CS-UNUSED in order to ensure compatibility with future versions of Client-Library.
(I) This argument is currently unused and should be passed as CS-UNUSED in order to ensure compatibility with future versions of Client-Library.
(I) Variable where the number of result rows is returned. This variable is of type integer. CTBFETCH sets ROWS-READ to the number of rows read by the CTBFETCH call. This argument is required.
CTBFETCH returns one of the following values listed in Table 3-12.
Value |
Meaning |
|---|---|
CS-SUCCEED (-1) |
The routine completed successfully. CTBFETCH places the total number of rows read in ROWS-READ. |
CS-FAIL (-2) |
The routine failed. CTBFETCH places the number of rows fetched before the failure occurred in ROWS-READ. A common reason for a CTBFETCH failure is that a program variable specified through CTBBIND is too small to hold a fetched data item. |
CS-CANCELLED (-202) |
The operation was canceled. CTBFETCH places the number of rows fetched before the cancel occurred in ROWS-READ. |
CS-ROW-FAIL (-203) |
A recoverable error occurred while fetching a row. Recoverable errors include memory allocation failures and conversion errors that occur while copying row values to program variables. An application can continue calling CTBFETCH to continue retrieving rows, or can call CTBCANCEL to cancel the remaining results. CTBFETCH places the number of rows fetched before the error occurred in ROWS-READ, then continues by fetching the row after the error. |
CS-END-DATA (-204) |
No more rows are available in this result set. (Note that this is also a successful completion. |
TDS-INVALID-PARAMETER (-4) |
One of the CTBFETCH arguments contains an illegal value. The most likely cause of this code is assigning a value other than CS-UNUSED to one of more of the reserved arguments, TYP, OFFSET, and OPTION. |
TDS-WRONG-STATE (-6) |
Program is in the wrong communication state to issue this call. It is in Send state instead of Receive state. |
The following example shows a typical use of CTBFETCH. It is taken from the sample program SYCTSAA5 in Appendix A, “Sample Language Requests.”
*========================================================
*== ==
*== Subroutine to fetch row processing ==
*== ==
*========================================================
FETCH-ROW-PROCESSING.
CALL 'CTBFETCH' USING CSL-CMD-HANDLE,
CSL-RC,
CS-UNUSED,
CS-UNUSED,
CS-UNUSED,
FF-ROWS-READ.
EVALUATE CSL-RC
WHEN CS-SUCCEED
MOVE 'Y' TO SW-FETCH
MOVE CS-VARCHAR-TYPE TO DF-DATATYPE
MOVE LENGTH OF CF-COL-FIRSTNME-TXT
TO DF-MAXLENGTH
MOVE CS-CHAR-TYPE TO DF2-DATATYPE
MOVE LENGTH OF CF-COL-FIRSTNME-CHAR
TO DF2-MAXLENGTH
CALL 'CSBCONVE' USING CSL-CTX-HANDLE,
CSL-RC,
DATAFMT,
CF-COL-FIRSTNME,
DATAFMT2,
CF-COL-FIRSTNME-CHAR,
CF-COL-LEN
IF CSL-RC NOT EQUAL CS-SUCCEED
THEN
MOVE SPACES TO MSGSTR
STRING 'CSBCONVERT CS-VARCHAR-TYPE failed'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
PERFORM ALL-DONE
END-IF
COMPUTE FF-ROW-NUM = FF-ROW-NUM + 1
**************************************
* save ROW RESULTS for later display *
**************************************
MOVE CF-COL-FIRSTNME-CHAR TO
OR-COL-FIRSTNME-CHAR
MOVE DATA-SMALLINT TO
OR-COL-EDUCLVL
IF FF-ROW-NUM > MAX-SCREEN-ROWS
THEN
STRING 'Please press return to continue.'
DELIMITED BY SIZE INTO MSG1O
MOVE SPACES TO MSG-TEXT-2
PERFORM DISP-DATA
PERFORM CLEAR-SCREEN-DATA
VARYING FF-ROW-NUM FROM 1 BY 1
UNTIL FF-ROW-NUM > MAX-SCREEN-ROWS
MOVE LOW-VALUES TO A5PANELO
COMPUTE PAGE-CNT = PAGE-CNT + 1
MOVE 1 TO FF-ROW-NUM
**------------------------------------------------------------
** Setup column headings
**------------------------------------------------------------
MOVE 'FirstName EducLvl' TO
RSLTNO(FF-ROW-NUM)
COMPUTE FF-ROW-NUM = FF-ROW-NUM + 1
MOVE '=========== =======' TO
RSLTNO(FF-ROW-NUM)
COMPUTE FF-ROW-NUM = FF-ROW-NUM + 1
END-IF
MOVE OUTPUT-ROW-STR TO RSLTNO(FF-ROW-NUM)
MOVE SPACES TO CF-COL-FIRSTNME-TXT
WHEN CS-END-DATA
MOVE SPACES TO MSG1O
MOVE 'N' TO SW-FETCH
MOVE 'Press Clear To Exit'
TO MSG-TEXT-2
STRING 'All rows processing completed!'
DELIMITED BY SIZE INTO MSG1O
PERFORM DISP-DATA
WHEN CS-FAIL
MOVE 'N' TO SW-FETCH
MOVE SPACES TO MSGSTR
STRING 'CTBFETCH returned CS-FAIL ret-code'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
WHEN CS-ROW-FAIL
MOVE 'N' TO SW-FETCH
MOVE SPACES TO MSGSTR
STRING 'CTBFETCH returned CS-ROW-FAIL ret-code'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
WHEN CS-CANCELLED
MOVE 'N' TO SW-FETCH
MOVE MF-CANCELED TO MSG1O
PERFORM PRINT-MSG
WHEN OTHER
MOVE 'N' TO SW-FETCH
MOVE SPACES TO MSGSTR
STRING 'CTBFETCH returned UNKNOWN ret-code'
DELIMITED BY SIZE INTO MSGSTR
PERFORM PRINT-MSG
END-EVALUATE.
FETCH-ROW-PROCESSING-EXIT.
EXIT.
CTBFETCH fetches result data. “Result data” is an umbrella term for the various types of data that a server can return to an application. These types of data include:
Regular rows.
Return parameters, including both message parameters and RPC return parameters.
Stored procedure status results.
CTBFETCH is used to fetch all of these types of data.
Conceptually, result data is returned to an application in the form of one or more rows that make up a “result set.”
Regular row result sets can contain more than one row. For example, a regular row result set might contain a hundred rows. If array binding is specified for the data items in a regular row result set, then multiple rows can be fetched with a single call to CTBFETCH. The number of rows fetched are returned in the ROWS-READ argument.
Return parameters and status results, however, only contain a single row. For this reason, even if array binding is specified, only a single row of data is fetched.
CTBRESULTS specifies the type of result available in the RESULT-TYP variable. CTBRESULTS must indicate a result type of CS-ROW-RESULT, CS-PARAM-RESULT, or CS-STATUS-RESULT before an application calls CTBFETCH.
After calling CTBRESULTS, an application can do one of the following:
Process the result set by binding the result items and fetching the data, using CTBFETCH (optionally preceded by CTBDESCRIBE and CTBBIND).
Discard the result set, using CTBCANCEL.
If an application does not cancel a result set, it must completely process the result set by repeatedly calling CTBFETCH as long as CTBFETCH continues to indicate that rows are available.
The simplest way to do this is in a loop that terminates when CTBFETCH fails to return either CS-SUCCEED or CS-ROW-FAIL. After the loop terminates, an application can check the CTBFETCH final return code to find out what caused the termination.
Regular rows can be fetched from the server one row at a time, or several rows at once.
When fetching multiple rows, the number of rows to be fetched is indicated by the FMT-COUNT field in the DATAFMT structures used to bind the data items in the result set. Note that the FMT-COUNT field must have the same value for all CTBBIND calls for a result set.
If FMT-COUNT is 0 or 1, CTBFETCH fetches one row.
A return parameter result set contains either stored procedure return parameters or message parameters.
A return parameter result set consists of a single row with a number of columns equal to the number of return parameters.
A stored procedure return status result set consists of a single row with a single column, containing the status.
Related functions
Related documentation
Mainframe Connect Client Option and Server Option Messages and Codes
