Products Support Documentation Download
Cursor Association Functions (rowscan)
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 cursor 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
sOKAYNormal, successful return.
eCURSORDBCursor is associated with a different database.
eDBNOTOPENDatabase not open.
eINVCURSORIDInvalid cursor id.
ePRECOMMITTEDA 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]dbA valid RDM database handle
[in]tableIdThe table id for the row set
[out]pCursorA pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)
Examples:
tutorials/HelloWorld/hello_worldTutorial_main.c.

◆ 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
sOKAYNormal, successful return.
sNOTFOUNDRequested item not found. Success, but no row with the specified rowid, the cursor position is set to CURSOR_BETWEEN.
eDBNOTOPENDatabase not open.
sNOTFOUNDRequested item not found.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eCURSORDBCursor is associated with a different database.
eINVROWIDVALInvalid rowid value.
ePRECOMMITTEDA 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]dbA valid RDM database handle
[in]tableIdThe table identifier for the set of rows
[in]rowIdThe rowid to position the cursor at
[out]pCursorA pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)