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)