OmniAccess API

Open a Cursor

A cursor defines a working area of the Omnidex environment for a given environment instance. For example, sixty-three rows are qualified using Omnidex indexes and the twenty-fourth row has been fetched. The cursor lets oaselect hold this place so when oafetch is called to retrieve the next row, it retrieves the twenty-fifth row.

To establish a cursor, call oaopencursor. Pass the instance value returned to oaconnect's instance parameter, to oaopencursor's instance parameter.

When a cursor is established, a signed integer value is returned to the cursor parameter. This value is then passed to many OmniAccess routines (like oaselect and oafetch) so that they may reference or modify the current cursor.

Multiple Cursors

By opening multiple cursors, a program can retrieve or update on one cursor without affecting another. This supports simultaneous updates and retrievals on the same table, or simultaneous retrievals of different subsets of rows from the same table.

Cursor numbers are unique across multiple instances. This means a cursor number is not reused between instances. For example, if instance 1 produces cursor 1, no other instance will use the number 1 for its cursor, as long as the original cursor 1 remains open.

Close a Cursor

While multiple cursors support a variety of transactions being performed simultaneously, they each require system resources to be maintained. For example, cursor 1 may be holding a place in a list of 350 rows whose identifiers are stored in memory. To free the system resources associated with a cursor, the cursor should be closed when it is no longer needed.

To close a cursor, call oaclosecursor. Specify the number of the cursor to close by passing it as the cursor parameter to oaclosecursor. Remember, this is the number established for the cursor when it was opened by calling oaopencursor.

All open cursors associated with a particular instance are closed automatically when that instance is closed by a call to oadisconnect.

top