SQLFetchScroll - Fetch from a scrollable cursor
SQLFetchScroll() positions the cursor based on the requested orientation and then retrieves any bound columns.
SQLFetchScroll() can be used to receive the data directly into variables that 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
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.
When using this function to retrieve rows from an SQL procedure result set, only the SQL_FETCH_NEXT orientation is supported.
SQLFetchScroll() supports array fetch, an alternative to the array fetch support provided by SQLExtendedFetch(). See the SQLExtendedFetch() topic for details on array fetch.
- 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.
fOrient | Description |
---|---|
SQL_FETCH_ABSOLUTE | Move to the result set row specified by the fOffset argument. |
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:
|
Return codes
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_NO_DATA_FOUND
Diagnostics
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. |
HY021 | Internal descriptor that is not valid | The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid. |