SQLFetchScroll - Fetch from a scrollable cursor

Purpose

SQLFetchScroll() positions the cursor based on the requested orientation, then retrieves any bound columns.

SQLFetchScroll() can be used to receive the data directly into variables you specify with SQLBindCol(), or the columns can be received individually after the fetch, by calling SQLGetData(). Data conversion is also performed when SQLFetchScroll() is called, if conversion is indicated when the column is bound.

Syntax

SQLRETURN SQLFetchScroll (SQLHSTMT    hstmt,
                          SQLSMALLINT fOrient,
                          SQLINTEGER  fOffset);

Function arguments

Table 1. SQLFetchScroll arguments
Data type	Argument	Use	Description
SQLHSTMT	hstmt	Input	Statement handle.
SQLSMALLINT	fOrient	Input	Fetch orientation. See Table 2 for possible values.
SQLINTEGER	fOffset	Input	Row offset for relative positioning.

Usage

SQLFetchScroll() can only be called if the most recently processed statement on hstmt is a SELECT.

SQLFetchScroll() acts like SQLFetch(), except the fOrient parameter positions the cursor before any data is retrieved. The cursor must be a scrollable cursor for SQLFetchScroll() to use any orientation other than SQL_FETCH_NEXT. See SQLSetStmtAttr - Set a statement attribute for information about setting the SQL_ATTR_CURSOR_SCROLLABLE attribute.

When using this function to retrieve rows from an SQL procedure result set, only the SQL_FETCH_NEXT orientation is supported.

Start of change SQLFetchScroll() supports array fetch, an alternative to the array fetch support provided by SQLExtendedFetch(). See the SQLExtendedFetch() topic for details on array fetch. End of change

The information returned in the RowCountPtr and RowStatusArray parameters of SQLExtendedFetch() are handled by SQLFetchScroll() as follows:

RowCountPtr: SQLFetchScroll() returns the number of rows fetched in the buffer pointed to by the SQL_ATTR_ROWS_FETCHED_PTR statement attribute.
RowStatusArray: SQLFetchScroll() returns the array of statuses for each row in the buffer pointed to by the SQL_ATTR_ROW_STATUS_PTR statement attribute.

Table 2. Statement attributes
fOrient	Description
SQL_FETCH_FIRST	Move to the first row of the result set.
SQL_FETCH_LAST	Move to the last row of the result set.
SQL_FETCH_NEXT	Move to the row following the current cursor position.
SQL_FETCH_PRIOR	Move to the row preceding the current cursor position.
SQL_FETCH_RELATIVE	If fOffset is: Positive, advance the cursor that number of rows. Negative, back up the cursor that number of rows. Zero, do not move the cursor.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

Diagnostics

Table 3. SQLFetchScroll SQLSTATEs
SQLSTATE	Description	Explanation
01004	Data truncated	The data returned for one or more columns is truncated. String values are right truncated. (SQL_SUCCESS_WITH_INFO is returned if no error occurred.)
HY001	Memory allocation failure	The driver is unable to allocate memory required to support the processing or completion of the function.
HY009	Argument value that is not valid	Orientation that is not valid.
HY010	Function sequence error	The specified hstmt is not in an processed state. The function is called without first calling SQLExecute or SQLExecDirect.
HY013 *	Memory management problem	The driver is unable to access memory required to support the processing or completion of the function.