Fetches result data.
CS_RETCODE ct_fetch(command, type, offset, option,
rows_read);
CS_COMMAND *command;
CS_INT type;
CS_INT offset;
CS_INT option;
CS_INT *rows_read;
(I) Handle for this client/server operation. This command handle must already be allocated with ct_cmd_alloc.
(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. ct_fetch sets rows_read to the number of rows read by the ct_fetch call. This argument is required.
ct_fetch returns one of the following values listed in Table 3-8.
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. ct_fetch places the total number of rows read in rows_read. |
CS_FAIL (-2) |
The routine failed. ct_fetch places the number of rows fetched before the failure occurred in rows_read. A common reason for a ct_fetch failure is that a program variable specified through ct_bind is too small to hold a fetched data item. |
CS_CANCELLED (-202) |
The operation was canceled. ct_fetch 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 ct_fetch to continue retrieving rows, or can call ct_cancel to cancel the remaining results. ct_fetch 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 ct_fetch arguments contains an illegal value. The most likely cause of this code is assigning a value other than CS_UNUSED to one or more of the reserved arguments, type, 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 ct_fetch. It is taken from the SYCTSAA6 sample program in Appendix A, “Sample Language Application.”
/********************************************************************/
/* */
/* Subroutine to fetch row processing */
/* */
/********************************************************************/
void fetch_row_processing ()
{
CS_INT rows_read;
CS_INT rc;
CS_INT col_len;
CS_INT max_screen_rows = 10;
CS_SMALLINT nomore_rows = 0;
CS_DATAFMT datafmt;
CS_DATAFMT datafmt2;
struct {
char first[12];
char space2[2];
char edlevel[4];
} output_row;
while (nomore_rows == FALSE)
{
strcpy(col_firstnme.str, " ");
memset (&output_row, ' ', sizeof(output_row));
rc = ct_fetch (cmd, (long) CS_UNUSED,
(long) CS_UNUSED,
(long) CS_UNUSED,
&rows_read);
switch (rc)
{
case CS_SUCCEED:
nomore_rows = FALSE ;
datafmt.datatype = CS_VARCHAR_TYPE;
datafmt.maxlength = sizeof(col_firstnme);
datafmt2.datatype = CS_CHAR_TYPE;
datafmt2.maxlength = 12;
/*------------------------------------------------------------*/
/* convert the first column from VARCHAR to CHAR for display */
/*------------------------------------------------------------*/
if (cs_convert(context, datafmt, col_firstnme, datafmt2,
&output_row.first, &col_len) !=CS_SUCCEED)
{
strncpy (msgstr,
"CS_CONVERT CS_CHAR_TYPE failed", msg_size);
no_errors_sw = FALSE ;
error_out(rc);
}
/*------------------------------------------------------------*/
/* save ROW RESULTS for later display */
/*------------------------------------------------------------*/
cvtleft = 4; /* Digits to the left */
cvtright = 0; /* Digits to the right */
SYCVTD(col_edlevel, output_row.edlevel,
cvtleft, cvtright, cvtwork, cvtdbl, CS_TRUE);
if (row_num > max_screen_rows)
{
strncpy (msgtext1, "Please press return to
continue!",text_size);
memset (msgtext2, ' ', text_size);
disp_data ();
/* re-init output lines */
for (row_num = 0; row_num < 14; ++row_num)
memset (RS[row_num].rsltno, ' ', text_size);
row_num = 1;
page_cnt = page_cnt + 1 ;
/*------------------------------------------------------------*/
/* Setup column headings */
/*------------------------------------------------------------*/
strncpy (RS[row_num].rsltno, "FirstName EducLvl",
text_size);
row_num += 1;
strncpy (RS[row_num].rsltno, "========== =======",
text_size);
row_num += 1;
} /* if row_num > 10 */
row_num += 1;
memcpy (RS[row_num].rsltno, &output_row,
sizeof(output_row));
break; /* end of CS_SUCCEED */
case CS_END_DATA:
nomore_rows = TRUE ;
strncpy (msgtext1, "All rows processing completed!",
text_size);
strncpy (msgtext2, "Press Clear To Exit", text_size);
disp_data ();
break; /* end of CS_END_DATA */
case CS_FAIL:
nomore_rows = TRUE ;
no_errors_sw = FALSE ;
strncpy (msgstr, "CT_FETCH returned CS_FAIL ret_code");
error_out(rc);
break; /* end of CS_FAIL */
case CS_ROW_FAIL:
nomore_rows = TRUE ;
no_errors_sw = FALSE ;
strncpy (msgstr, "CT_FETCH returned CS_ROW_FAIL
ret_code");
error_out(rc);
break; /* end of CS_ROW_FAIL */
case CS_CANCELLED:
nomore_rows = TRUE ;
no_errors_sw = FALSE ;
strncpy (msgstr, "CT_FETCH returned CS_CANCELLED
ret_code");
error_out(rc);
break; /* end of CS_CANCELLED */
default:
nomore_rows = TRUE ;
no_errors_sw = FALSE ;
strncpy (msgstr, "CT_FETCH returned Unknown ret_code");
error_out(rc);
break; /* end of OTHERWISE */
} /* end of switch (rc) */
} /* end of while nomore_rows false */
} /* end fetch_row_processing */
ct_fetch 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.
ct_fetch 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 ct_fetch. The number of rows fetched is 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.
ct_results specifies the type of result available in the result_type variable. ct_results must indicate a result type of CS_ROW_RESULT, CS_PARAM_RESULT, or CS_STATUS_RESULT before an application calls ct_fetch.
After calling ct_results, an application can:
Process the result set by binding the result items and fetching the data, using ct_fetch (optionally preceded by ct_describe and ct_bind), or
Discard the result set, using ct_cancel.
If an application does not cancel a result set, it must completely process the result set by repeatedly calling ct_fetch as long as ct_fetch continues to indicates that rows are available.
The simplest way to do this is in a loop that terminates when ct_fetch fails to return either CS_SUCCEED or CS_ROW_FAIL. After the loop terminates, an application can check the ct_fetch 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 count field in the datafmt structures used to bind the data items in the result set. Note that the count field must have the same value for all ct_bind calls for a result set.
If count is 0 or 1, ct_fetch 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
