Cursor Association Functions (rowscan)

Cursor association API for retrieving rows in rowid order. All the fuctions here are located in RDM DB Engine Library. Linker option: More...

Collaboration diagram for Cursor Association Functions (rowscan):

Functions

RDM_RETCODE rdm_dbGetRows (RDM_DB db, RDM_TABLE_ID tableId, RDM_CURSOR *pCursor)
Associate an RDM_CURSOR with rows based on a table id. More...
RDM_RETCODE rdm_dbGetRowsAtRowId (RDM_DB db, RDM_TABLE_ID tableId, RDM_ROWID_T rowId, RDM_CURSOR *pCursor)
Associate an RDM_CURSOR with rows based on a tableId and and rowId. More...

Detailed Description

Cursor association API for retrieving rows in rowid order. All the fuctions here are located in RDM DB Engine Library. Linker option:

    -lrdmrdm

See RDM Cursor APIs for a more detailed description of a cursor.

Function Documentation

rdm_dbGetRows()

RDM_RETCODE rdm_dbGetRows ( RDM_DB db,
RDM_TABLE_ID tableId,
RDM_CURSOR * pCursor
)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with rows based on a table id.

This function associates the RDM_CURSOR pointed to by pCursor with a set of rows in rowid order. The cursor will contain all of the rows for the table specified by tableId. The cursor will be initially positioned in the BeforeFirst position.

Cursor Association Rules
  • If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
  • If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
  • If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
  • If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.
Locking Requirements
None
Return values
sOKAY Normal, successful return.
eCURSORDB Cursor is associated with a different database.
eDBNOTOPEN Database not open.
eINVCURSORID Invalid cursor id.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRowsAtRowId
rdm_dbGetRowsByKey
rdm_cursorGetRowsAtPosition
rdm_cursorGetMemberRows
rdm_cursorGetOwnerRow
rdm_cursorGetRowsInReverseOrder
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorGetClone
rdm_cursorMoveToNext
rdm_cursorReadRow
rdm_cursorUpdateRow
rdm_cursorDeleteRow
rdm_cursorLinkRow
Parameters
[in] db [in] A valid RDM database handle
[in] tableId [in] The table id for the row set
[out] pCursor [out] A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

rdm_dbGetRowsAtRowId()

RDM_RETCODE rdm_dbGetRowsAtRowId ( RDM_DB db,
RDM_TABLE_ID tableId,
RDM_ROWID_T rowId,
RDM_CURSOR * pCursor
)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with rows based on a tableId and and rowId.

This function associates the RDM_CURSOR pointed to by pCursor with a row set ordered by rowid. The row set contains all of the rows for the specified table and will initially be positioned to the row specified by the rowid value.

If rowid is not a valid rowid for the specified table an error will be returned and no rows will be associated with the cursor.

If rowid is a valid rowid for the specified table but there is no row at that exact position then the function will return sNOTFOUND and the cursor will be placed in the CURSOR_BETWEEN position. Navigating forward (rdm_cursorMoveToNext()) from that position will position the cursor at the next rowid larger than the specified rowid. Navigating backward (rdm_cursorMoveToPrevious()) from that position will position the cursor at the next rowid smaller than the specified rowid.

Cursor Association Rules
  • If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
  • If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
  • If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
  • If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.
Locking Requirements
Read lock on the table tableId.
Return values
sOKAY Normal, successful return.
sNOTFOUND Requested item not found. Success, but no row with the specified rowid, the cursor position is set to CURSOR_BETWEEN.
eDBNOTOPEN Database not open.
sNOTFOUND Requested item not found.
eNOSTARTREAD A read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKED Attempt to access a table for reading or update without proper locks.
eCURSORDB Cursor is associated with a different database.
eINVROWIDVAL Invalid rowid value.
ePRECOMMITTED A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_dbGetRowsByKey
rdm_cursorGetRowsAtPosition
rdm_cursorGetMemberRows
rdm_cursorGetOwnerRow
rdm_cursorGetRowsInReverseOrder
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorGetClone
rdm_cursorMoveToNext
rdm_cursorReadRow
rdm_cursorUpdateRow
rdm_cursorDeleteRow
rdm_cursorLinkRow
Parameters
[in] db [in] A valid RDM database handle
[in] tableId [in] The table identifier for the set of rows
[in] rowId [in] The rowid to position the cursor at
[out] pCursor [out] A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)