Pages Navigation Menu

Using cursors

Using cursors

In this section… Opening and positioning cursors
Read/lock modes

Cursors enable you to filter, traverse over, and lock records or key-value pairs. There are two types of cursor: discriminated and unfiltered (non-discriminated). When you open a discriminated cursor, subsequent cursor operations are limited to records or key-value pairs that are equal to, greater than, or greater than or equal to a specified key (depending on DBReadFlags settings). When you open an unfiltered cursor, subsequent cursor operations apply to the entire database—all records or key-value pairs. Note the following:

  • A cursor represents an open channel to the database, so cursor-based operations are resource intensive.
  • When you open a cursor, you can use the DBReadFlags enumerator to specify one or more read/lock modes, which remain in effect for the lifespan of the cursor. See Read/lock modes below.
  • You can get the key for the current cursor location by using DBCursor.GetKey or DBCursor.GetKeyString.
  • You can get the GRFA for the current cursor location by using DBCursor.GetGRFA. (The RFA is the first six bytes of the value returned by DBCursor.GetGRFA.) For information on GRFAs and RFAs, which can be used to position cursors, see Using GRFAs and RFAs.

Opening and positioning cursors

  1. Open a KitaroDB database using DB.Open[Async]. Note that there’s no need to open a KitaroDB database if you have just created it (see Creating a KitaroDB database).
  2. Open a cursor using one of the following:
    DB.Select[Async] Opens a discriminated cursor at the first match of a specified key, or returns NULL if no match is found.
    DB.Seek[Async] Opens an unfiltered cursor at the first match for a specified key, GRFA, or RFA. If no match is found, the cursor is positioned at the first record.

    By default, the “First match” for these methods is the first record or key-value pair whose key is equal to the key specified in the method call. You can, however, pass a DBReadFlags flag to change this to the first record or key-value pair whose key is greater than the specified key (MatchGreater) or the first record or key-value pair whose key is greater than or equal to the specified key (MatchGTEQ) See Read/lock modes below.

  3. Once you’ve opened a cursor, you can position it using the following:
    DBCursor.MoveFirst[Async] Moves the cursor to the first record or key-value pair.
    DBCursor.MoveLast[Async] Moves the cursor to the last record or key-value pair.
    DBCursor.MoveNext[Async] Moves the cursor to the next record or key-value pair.
    DBCursor.MovePrevious[Async] Moves the cursor to the previous record or key value pair.
    DBCursor.Seek[Async] Repositions the cursor to the first match for a specified key. (Not supported for discriminated cursors.)

Read/lock modes

When you open a cursor, you can optionally use the DBReadFlags enumerator to specify one or more read/lock modes, which remain in effect for the lifespan of the cursor:

AutoLock Locks the record or key-value pair at the current cursor position. The record or key-value pair is automatically unlocked when the cursor is repositioned or when the locked record is updated or deleted. This is the default.
GRFA Uses a GRFA to position the cursor when using DB.Seek[Async].
ManualLock Locks the record or key-value pair at the cursor position. The record can be unlocked only by passing the GRFA or RFA for the record to DBCursor.UnlockGRFA[Async].
MatchGreater Positions the cursor on the first record or key-value pair with a key that is greater than the one passed to DB.Seek[Async] or DB.Select[Async]. With DB.Select[Async], subsequent cursor operations are limited to records or key-value pairs with keys that are greater than the passed key.
MatchGTEQ Positions the cursor on the record or key-value pair whose key matches the key passed to DB.Seek[Async] or DB.Select[Async]. If there is no match, positions the cursor on the first record or key-value pair whose key is greater than the specified key. With DB.Select[Async], subsequent cursor operations are limited to records or key-value pairs with keys that are greater than or equal to the passed key.
NoLock Does not apply locks. This results in a read-only cursor.
RFA Uses an RFA (the first six bytes of a GRFA) to position the cursor when using DB.Seek[Async]. This enables you to use the portion of the GRFA that uniquely identifies a record without accounting for data changes.
WaitOnLock Waits up to one second to apply a lock to the current record or key-value pair before getting an error.