IIapi_position() Function--Position Cursor and Initiate Row Retrieval
The IIapi_position() function positions a cursor and requests some number of rows to be retrieved. The data associated with the requested rows can be retrieved with IIapi_getColumns(), while the status of the cursor position request can be determined with IIapi_getQueryInfo().
The position of the cursor is specified by a reference point and an offset from the reference point. The reference point can be the beginning of the result set, the current cursor position, or the end of the result set. A 0 offset corresponds to the reference point. Positive offsets reference positions that follow the reference point, while negative offsets reference positions that precede the reference point.
The number of rows to be retrieved can also be specified. A row count of 0 positions the cursor to the requested position without retrieving any rows. A row count of 1 retrieves the target row (if it exists) and leaves the cursor positioned on the target row. A row count greater than 1 retrieves a block of rows and leave the cursor on the last row/position accessed.
A 0 row count should be specified when the requested position is not associated with a row (references IIAPI_POS_BEGIN or IIAPI_POS_END with an offset of 0). A request for 0 rows should be followed by a call to IIapi_getQueryInfo(). IIapi_getColumns() returns a status of IIAPI_ST_NO_DATA if preceded by a position request with a row count of 0.
A request for 1 or more rows should be followed by calling IIapi_getColumns() for the same number of rows. This ensures that the operation started by IIapi_position() is completed by the single call to IIapi_getColumns(). It is possible, by carefully observing certain guidelines, to retrieve the rows requested using multiple calls to IIapi_getColumns(). After the requested rows have been retrieved, the status of the position request can be determined using IIapi_getQueryInfo(). If IIapi_getQueryInfo() is called before all the requested rows have been retrieved, the remaining rows are discarded.
This function has the following syntax:
II_VOID IIapi_position( IIAPI_POSPARM *posParm );
typedef struct _IIAPI_POSPARM
{
IIAPI_GENPARM po_genParm;
II_PTR po_stmtHandle;
II_UINT2 po_reference;
II_INT4 po_offset;
II_INT2 po_rowCount;
} IIAPI_POSPARM;
This function has the following parameters:
po_genParm
Type: input and delayed output
po_stmtHandle
Type: input
Specifies the statement handle identifying the query/cursor.
po_reference
Type: input
Specifies the reference point from which the target position is calculated. Its value is one of the following:
IIAPI_POS_BEGIN
Beginning of the result set. Offset 0 corresponds to the initial position of the cursor (before the first row). Rows in the result set are at positive offsets from this reference point with the first row at offset 1.
IIAPI_POS_CURRENT
Current position of the cursor. Offset 0 corresponds to the current cursor position. Rows that precede the current cursor position are at negative offsets from this reference point with the prior row at offset -1. Rows that follow the current cursor position are at positive offsets from this reference point with the next row at offset 1.
IIAPI_POS_END
End of the result set. Offset 0 corresponds to the final position of a forward-only cursor (after the last row). Rows in the result set are at negative offsets from this reference point with the last row at offset -1.
po_offset
Type: input
Specifies the row offset of the target position from the reference point.
po_rowCount
Type: input
Specifies the number of rows to be retrieved. May be 0 to position cursor without retrieving rows.