How Cursors Work
Cursors enable an application to process, one at a time, the result rows returned by a select statement. The following SQL statements are used in processing data with a cursor:
update (cursor)
Updates the current row.
delete (cursor)
Deletes the current row.
If a cursor is opened as updatable (the default), the application can update or delete the row referenced by the cursor. If the cursor is opened as read-only, the application can read the data but cannot update or delete it.
When an application calls IIapi_query() to open a cursor, it provides the name of the cursor as a parameter in subsequent calls to IIapi_setDescriptor() and IIapi_putParms(). Cursor name is the character string, unique within the application, that represents the cursor.
When the application calls IIapi_query() to update or delete data with a cursor, it provides the cursor ID as a parameter in subsequent calls to IIapi_setDescriptor() and IIapi_putParms(). Cursor ID is the statement handle returned by IIapi_query() when the cursor is opened.
Scrollable Cursors
The application requests a scrollable cursor by setting the IIAPI_QF_SCROLL flag when opening the cursor using IIapi_query() with query type IIAPI_QT_OPEN. A scrollable cursor can be positioned prior to calling IIapi_getColumns() using either IIapi_scroll() or IIapi_position(). IIapi_getColumns() then returns rows starting with the row specified by IIapi_scroll() or IIapi_position(). If IIapi_getColumns() is not preceded by an explicit scroll/position request, the rows following the current cursor position are returned.
Order of Function Calls Used to Manipulate Data with a Cursor
To use a cursor, the application:
1. Opens the cursor with IIapi_query().
2. Provides cursor name and parameter descriptions and values with IIapi_setDescriptor() and IIapi_putParms().
3. Requests a description of the data being returned from the server with IIapi_getDescriptor().
The application may call IIapi_getQueryInfo() to obtain the status of the open cursor request.
4. Optionally positions the cursor with IIapi_scroll() and IIapi_position().
5. Requests the data with calls to IIapi_getColumns() until the function returns with a status of “no more data.”
The application may call IIapi_getQueryInfo() after each call to IIapi_getColumns() to obtain the status of the fetch request.
If the application is deleting or updating information with a cursor, it specifies the cursor delete or update statement for the row where the cursor is positioned. The statement handle returned from the open statement should be used as a cursor ID value for the delete or update statement.
6. Closes the SQL statement and releases the statement handle with IIapi_close(). This automatically closes the cursor.
Last modified date: 01/30/2023