dbcursorfetch

Description

Fetch a block of rows into the program variables declared by the user in dbcursorbind.

Syntax

RETCODE dbcursorfetch(hc, fetchtype, rownum)
 
DBCURSOR     *hc;
DBINT               fetchtype;
DBINT                rownum;

Parameters

hc: Cursor handle created by dbcursoropen.

fetchtype

Type of fetch chosen. The scroll option in dbcursoropen determines which of these values are legal. Table 2-10 lists the various fetch types.

**Table 2-10: Values for fetchtype (dbcursorfetch)**
Symbolic value	Meaning	Comment
FETCH_FIRST	Fetch the first block of rows.	Although available for all cursor types, this option is especially useful for returning to the beginning of a keyset when you have selected a forward-only scrolling cursor.
FETCH_NEXT	Fetch the next block of rows.	If the result set exceeds the specified keyset size and if FETCH_RANDOM and/or FETCH_RELATIVE have been issued, a FETCH_NEXT can span a keyset boundary. In this case, the fetch that spans a keyset boundary returns a partial buffer, and the next fetch shifts down the keyset and returns the next full set of rows.
FETCH_PREV	Fetch the previous block of rows.	This option is unavailable with forward-only scrolling cursors. If rownum falls within the keyset, the range of rows must stay within the keyset because only the rows within the keyset are returned. This option does not change the keyset to the previous rownum rows in the result set.
FETCH_RANDOM	Fetch a block of rows, starting from the specified row number within the keyset.	This option is valid only within the keyset. The buffer is only partially filled when the range spans the keyset boundary.
FETCH_RELATIVE	Fetch a block of rows, relative to the number of rows indicated in the last fetch.	This option jumps rownum rows from the first row of the last fetch and starts fetching from there. The rows must remain within the keyset. The buffer is only partially filled when the range spans the keyset boundary.
FETCH_LAST	Fetch the last block of rows.	This value is available only with totally keyset-driven cursors.

rownum: The specified row for the buffer to start filling. Use this parameter only with a fetchtype of FETCH_RANDOM or -FETCH_RELATIVE.

Returns

SUCCEED or FAIL.

If the status array contains a status row for every row fetched, SUCCEED is returned. FAIL is returned if at least one of the following is true.

FETCH_RANDOM and FETCH_RELATIVE require a keyset driven cursor.
Forward-only scrolling can use only FETCH_FIRST and FETCH_NEXT.
The server or a connection fails or takes a timeout.
The client is out of memory.
The FETCH_LAST option requires a fully keyset-driven cursor.

Usage

Specify the size of the fetch buffer in dbcursoropen. dbcursorfetch fills the array passed as dbcursoropen’s pstatus parameter with status codes for the fetched rows. See the reference page for dbcursoropen for these codes.
Program variables must first be registered, using dbcursorbind. Then the data can be transferred into the DB-Library buffers. The bound variables must, therefore, be arrays large enough to hold the specified number of rows. The status array contains status code for every row and contains flags for missing rows.
When the range of rows specified by FETCH_NEXT, FETCH_RANDOM, or FETCH_RELATIVE spans a keyset boundary, only the rows remaining in the keyset are returned. In this case, the buffer is only partially filled, and the FETCH_ENDOFKEYSET flag is set as the status of the last row. The following FETCH_NEXT shifts the keyset down.
For more information on cursors, see Appendix A, “Cursors.”