ct_fetch

Description

Fetch result data.

Syntax

CS_RETCODE ct_fetch(cmd, type, offset, option,
           rows_read)
 
 CS_COMMAND *cmd;
 CS_INT                type;
 CS_INT                offset;
 CS_INT                option;
 CS_INT                 *rows_read;

Parameters

cmd

A pointer to the CS_COMMAND structure managing a client/server operation.

type

This parameter is currently unused and must be passed as CS_UNUSED to ensure compatibility with future versions of Client-Library.

offset

This parameter is currently unused and must be passed as CS_UNUSED to ensure compatibility with future versions of Client-Library.

option

This parameter is currently unused and must be passed as CS_UNUSED to ensure compatibility with future versions of Client-Library.

rows_read

A pointer to an integer variable. ct_fetch sets rows_read to the number of rows read by the ct_fetch call.

rows_read is an optional parameter intended for use by applications using array binding.

In asynchronous mode, *rows_read is not set until ct_fetch completes.

Returns

ct_fetch returns the following values:

Table 3-42: ct_fetch return values

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

ct_fetch places the number of rows read in *rows_read.

The application must continue to call ct_fetch, as the result data is not yet completely fetched.

CS_END_DATA

All rows of the current result set have been fetched.

The application should call ct_results to get the next result set.

CS_ROW_FAIL

A recoverable error occurred while fetching a row. The application must continue calling ct_fetch to keep retrieving rows, or can call ct_cancel to cancel the remaining results.

When using array binding, CS_ROW_FAIL indicates a partial result is available in the bound arrays. ct_fetch sets *row_count to indicate the number of rows transferred (including the row containing the error) and transfers no rows after that row. The next call to ct_fetch will read rows starting with the row after the one where the error occurred.

Recoverable errors include memory allocation failures and conversion errors (such as overflowing the destination buffer) that occur while copying row values to program variables. In the case of buffer-overflow errors, ct_fetch sets the corresponding *indicator variable(s) to a value greater than 0. Indicator variables must have been specified in the application’s calls to ct_bind.

CS_FAIL

The routine failed.

ct_fetch places the number of rows fetched in *rows_read. This number includes the failed row.

Unless the routine failed due to application error (for example, bad parameters), additional result rows are not available.

If ct_fetch returns CS_FAIL, an application must call ct_cancel with type as CS_CANCEL_ALL before using the affected command structure to send another command.

If ct_cancel returns CS_FAIL, the application must call ct_close(CS_FORCE_CLOSE) to force the connection closed.

CS_CANCELED

The current result set and any additional result sets have been canceled. Data is no longer available.

ct_fetch places the number of rows fetched before the cancel occurred in *rows_read.

CS_PENDING

Asynchronous network I/O is in effect. See “Asynchronous programming”.

CS_BUSY

An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

A common reason for a ct_fetch failure is that a program variable specified through ct_bind is not large enough for a fetched data item.

Examples

Example 1

        /* ex_fetch_data()*/
        CS_RETCODE CS_PUBLIC
         ex_fetch_data(cmd)
         CS_COMMAND  *cmd;
         {
             CS_RETCODE    retcode;
             CS_INT        num_cols;
             CS_INT        i;
             CS_INT        j;
             CS_INT        row_count = 0;
             CS_INT         rows_read;
            /*
             ** Determine the number of columns in this 
             ** result set.
             */
             ...CODE DELETED.....
            /* Get column descriptions and bind columns */
             ...CODE DELETED.....
            /*
             ** Fetch the rows.  Loop while ct_fetch() returns
             ** CS_SUCCEED or CS_ROW_FAIL
             */
             while (((retcode = ct_fetch(cmd, CS_UNUSED,
                 CS_UNUSED, CS_UNUSED,&rows_read)) ==
                 CS_SUCCEED) || (retcode == CS_ROW_FAIL))
             {
                 /*
                 ** Increment our row count by the number of
                 ** rows just fetched.
                 */
                 row_count = row_count + rows_read;
                /* Check if we hit a recoverable error */
                 if (retcode == CS_ROW_FAIL)
                 {
                     fprintf(stdout, "Error on row %d.\n",
                         row_count);
                 }
                /*
                 ** We have a row.  Loop through the columns
                 ** displaying the column values.
                 */
                 for (i = 0; i < num_cols; i++)
                 { 
                     ...CODE DELETED.....
                 } 
                 fprintf(stdout, "\n");
             }
            /* Free allocated space */
             ...CODE DELETED.....
            /*
             ** We're done processing rows.  Let's check the 
             ** final return value of ct_fetch().
             */
             switch ((int)retcode)
             {
                 case CS_END_DATA:
                     /* Everything went fine */
                     fprintf(stdout, "All done processing
                         rows.\n");
                     retcode = CS_SUCCEED;
                     break;
                case CS_FAIL:
                     /* Something terrible happened */
                     ex_error("ex_fetch_data: ct_fetch()
                         failed");
                     return retcode;
                     break;
                default:
                     /* We got an unexpected return value */
                     ex_error("ex_fetch_data: ct_fetch() \ 
                         returned an unexpected retcode");
                     return retcode;
                     break;
            }
            return retcode;
 }

This code excerpt is from the exutils.c example program.

Usage


Fetching regular rows and cursor rows


Fetching return parameters


Fetching a return status


Fetching compute rows

See also

ct_bind, ct_describe, ct_get_data, ct_results, “Results”