IIapi_scroll() Function—Scroll (Position) Cursor and Initiate Row Retrieval
The IIapi_scroll() function permits a cursor to be scrolled through a result set. The requested rows can be retrieved with IIapi_getColumns(), while the status of the scroll request can be determined with IIapi_getQueryInfo().
The scrolling operation is specified by a fetch orientation. In most cases, the fetch orientation specifies a specific row/position. In the case of absolute and relative orientations, an offset is used to determine the row/position relative to the start or end of the result set, or the current cursor position.
For fetch orientations other than IIAPI_SCROLL_BEFORE and IIAPI_SCROLL_AFTER, IIapi_scroll() requests a single row to be retrieved. These requests should be followed by a call to IIapi_getColumns(). After calling IIapi_getColumns(), IIapi_getQueryInfo() can be called to determine the status of the scroll request. If IIapi_getQueryInfo() is called without calling IIapi_getColumns(), the requested row data is discarded.
For fetch orientations IIAPI_SCROLL_BEFORE and IIAPI_SCROLL_AFTER, IIapi_scroll() does not request a row to be retrieved; the cursor is simply positioned to the requested position. These requests should be followed by a call to IIapi_getQueryInfo(). If one of these requests is followed by a call to IIapi_getColumns(), a status of IIAPI_ST_NO_DATA is returned.
This function has the following syntax:
II_VOID IIapi_scroll( IIAPI_SCROLLPARM *scrollParm );
typedef struct _IIAPI_SCROLLPARM
{
IIAPI_GENPARM sl_genParm;
II_PTR sl_stmtHandle;
II_UINT2 sl_orientation;
II_INT4 sl_offset;
} IIAPI_SCROLLPARM;
This function has the following parameters:
sl_genParm
Type: input and delayed output
sl_stmtHandle
Type: input
Specifies the statement handle identifying the query/cursor.
sl_orientation
Type: input
Specifies the scrolling operation to be performed. Its value is one of the following:
IIAPI_SCROLL_BEFORE
Positions the cursor at the start of the result set (before the first row, initial position of a cursor).
IIAPI_SCROLL_FIRST
Positions the cursor at the first row of the result set.
IIAPI_SCROLL_PRIOR
Positions the cursor at the preceding row of the result set.
IIAPI_SCROLL_CURRENT
Positions the cursor at the current position in the result set. Retrieves the current row without moving the cursor.
IIAPI_SCROLL_NEXT
Positions the cursor at the following row of the result set.
IIAPI_SCROLL_LAST
Positions the cursor at the last row of the result set.
IIAPI_SCROLL_AFTER
Positions the cursor at the end of the result set (after last row, final position of a non-scrollable cursor).
IIAPI_SCROLL_ABSOLUTE
Positions the cursor at a specific row of the result set. The position is determined by the value of sl_offset. An offset of 0 specifies the beginning of the result set (same as IIAPI_SCROLL_BEFORE). A positive offset specifies the row position from the start of the result set with 1 being the first row. A negative offset specifies the row position from the end of the result set with -1 being the last row.
IIAPI_SCROLL_RELATIVE
Positions the cursor relative to the current cursor position. The position is determined by the value of sl_offset. An offset of 0 specifies the current position in the result set (same as IIAPI_SCROLL_CURRENT). A positive offset specifies the row positions following the current cursor position with 1 being the next row. A negative offset specifies the row positions preceding the current cursor position with -1 being the prior row.
sl_offset
Type: input
Specifies the row offset of the target position when sl_orientation is IIAPI_SCROLL_ABSOLUTE or IIAPI_SCROLL_RELATIVE. Ignored for other values of sl_orientation.