Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 3 Routines

ct_fetch

Usage

Usage

• Result data is an umbrella term for all the types of data that a server can return to an application. The types of data include:

  • Regular rows

  • Cursor rows

  • Return parameters, such as message parameters, stored procedure return parameters, extended error data, and registered procedure notification parameters.

  • Stored procedure status values

  • Compute rows

  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 and cursor row result sets can contain more than one row. For example, a regular row result set might contain a hundred rows.

  If array binding has been specified for the data items in a regular row or cursor row result set, then multiple rows can be fetched with a single call to ct_fetch.

  Asynchronous applications should always specify array binding to fetch multiple rows at a time. This ensures that the application has sufficient time in which to accomplish something before Client-Library calls the application's completion callback routine.

  Return parameter, status number, and compute-row result sets, 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 sets *result_type to indicate the type of result available. ct_results must indicate a result type of CS_ROW_RESULT, CS_CURSOR_RESULT, CS_PARAM_RESULT, CS_STATUS_RESULT, or CS_COMPUTE_RESULT before an application calls ct_fetch.

• After ct_results returns a result_type that indicates fetchable results, an application can:

  • Retrieve the result row(s) by binding the result items and fetching the data. A typical application calls ct_res_info to get the number of data items, ct_describe to get data descriptions, ct_bind to bind result items, ct_fetch to fetch result rows, and ct_get_data, if the result set contains large text or image values.

  • Retrieve result rows using ct_dyndesc or ct_dynsqlda with ct_fetch. Typically, only applications that execute dynamic SQL commands use these routines, but ct_dyndesc or ct_dynsqlda can be used to process fetchable data returned by any command type.

  • Discard the result rows using ct_cancel for non-cursor results and ct_cursor(CS_CURSOR_CLOSE) for cursor results.

• If an application does not cancel a result set, it must completely process the result set by calling ct_fetch as long as ct_fetch continues to indicate 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 use a switch-type statement against ct_fetch's final return code to find out what caused the termination.

  If a result set contains zero rows, an application's first ct_fetch call will return CS_END_DATA.

  An application must call ct_fetch in a loop even if a result set contains only a single row. An application must call ct_fetch until it fails to return either CS_SUCCEED or CS_ROW_FAIL.

• If a conversion error occurs when retrieving a result item, the rest of the items in the row are retrieved. If truncation occurs, the indicator variable, if any, provided in the application's ct_bind call for this item is set to the actual length of the result data.

  ct_fetch returns CS_ROW_FAIL if a conversion or truncation error occurs.

• Regular rows and cursor rows can be fetched one row at a time, or several rows at once.

• An application indicates the number of rows to be fetched per ct_fetch call via the datafmt−>count field in its ct_bind calls that bind result columns to program variables. If datafmt−>count is 0 or 1, each call to ct_fetch fetches one row. If datafmt−>count is greater than one, then array binding is considered to be in effect and each call to ct_fetch fetches datafmt−>count rows. Note that datafmt−>count must have the same value for all ct_bind calls for a result set.

• When fetching multiple rows, if a conversion error occurs on one of the rows, no more rows are retrieved by this ct_fetch call.

• Several types of data can be returned to an application as a parameter result set, including:

  • Stored procedure return parameters

  • Message parameters

• Extended error data and registered procedure notification parameters are also returned as parameter result sets, but since an application does not call ct_results to process these types of data, the application never sees a result type of CS_PARAM_RESULT. Instead, the row of parameters is simply available to be fetched after the application retrieves the CS_COMMAND structure containing the data.

• 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, the status number.

• Compute rows result from the compute clause of a select statement.

• A compute row result set consists of a single row with a number of columns equal to the number of aggregate operators in the compute clause that generated the row.

• Each compute row is considered to be a distinct result set.