Cursor Association Functions (setscan)
Collaboration diagram for Cursor Association Functions (setscan):

Functions

RDM_RETCODE rdm_cursorGetMemberRows (RDM_CURSOR ownerCursor, RDM_REF_ID refId, RDM_CURSOR *pCursor)
Associate an RDM_CURSOR with members. More...
RDM_RETCODE rdm_cursorGetOwnerRow (RDM_CURSOR memberCursor, RDM_REF_ID refId, RDM_CURSOR *pCursor)
Associate an RDM_CURSOR with a set owner. More...
RDM_RETCODE rdm_cursorGetSiblingRows (RDM_CURSOR memberCursor, RDM_REF_ID refId, RDM_CURSOR *pCursor)
Associate an RDM_CURSOR with siblings. More...
RDM_RETCODE rdm_cursorGetSiblingRowsAtPosition (RDM_CURSOR memberCursor, RDM_REF_ID refId, RDM_CURSOR *pCursor)
Associate an RDM_CURSOR with siblings. More...

Detailed Description

Core cursor association API for retrieving rows in a set.  All
the fuctions here are located in \ref lib_rdm. Linker option:\
 <pre><code>    -l<tt><a href="lib_rdm.html">rdmrdm</a></tt></code></pre>  See \ref
cursor for a more detailed description of a cursor.

Function Documentation

rdm_cursorGetMemberRows()

RDM_RETCODE rdm_cursorGetMemberRows ( RDM_CURSOR ownerCursor,
RDM_REF_ID refId,
RDM_CURSOR * pCursor
)

#include <rdmcursorapi.h>

Associate an RDM_CURSOR with members.

This function associates the RDM_CURSOR pointed to by pCursor with a set of rows containing all the members related to the current row of ownerCursor for the set identified by refId. The resulting cursor will be positioned at BeforeFirst.

If ownerCursor is not positioned to a row that is in a table that is a valid owner of the set identified by refId an error will be returned and the RDM_CURSOR will not be associated.

ownerCursor can be any type of cursor as long as the current row of ownerCursor is a valid owner of the set identified by refId.

Cursor Association Rules
  • If pCursor points to NULL then a new cursor will be allocated and associated with the same RDM_DB as ownerCursor.
  • If pCursor points to an RDM_CURSOR that has been allocated, but not associated with an RDM_DB then the RDM_CURSOR will be associated with the same RDM_DB as ownerCursor.
  • If pCursor points to an RDM_CURSOR that is associated with an RDM_DB other than the RDM_DB associated with ownerCursor 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 member table and the owner table (ownerCursor) associated with the set refId
Return values
sOKAY Normal, successful return.
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.
eDBNOTOPEN Database not open.
eNOCURRENTROW The cursor is not positioned to a valid row.
eOWNERDELETED The owner row for a set cursor has been deleted.
eSINGLETONDELETED The row for a singleton cursor has been deleted.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetOwnerRow
rdm_cursorGetRowsAtPosition
rdm_cursorGetRowsByKeyAtPosition
rdm_cursorGetRowsInReverseOrder
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorGetSiblingRowsAtPosition
rdm_cursorGetClone
rdm_cursorMoveToNext
rdm_cursorReadRow
rdm_cursorUpdateRow
rdm_cursorDeleteRow
rdm_cursorLinkRow
Parameters
[in] ownerCursor [in] The cursor for the owner row
[in] refId [in] The set identifier for the requesting set of members
[out] pCursor [out] A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

rdm_cursorGetOwnerRow()

RDM_RETCODE rdm_cursorGetOwnerRow ( RDM_CURSOR memberCursor,
RDM_REF_ID refId,
RDM_CURSOR * pCursor
)

#include <rdmcursorapi.h>

Associate an RDM_CURSOR with a set owner.

This function associates the RDM_CURSOR pointed to by pCursor with the set owner of current row of memberCursor for the set identified by refId. The cursor will be positioned at this row. If the sourceCursor is not positioned to a valid member of the set identified by refId an error will be returned and the RDM_CURSOR will not be associated.

Cursor Association Rules
  • If pCursor points to NULL then a new cursor will be allocated and associated with the same RDM_DB as memberCursor.
  • If pCursor points to an RDM_CURSOR that has been allocated, but not associated with an RDM_DB then the RDM_CURSOR will be associated with the same RDM_DB as memberCursor.
  • If pCursor points to an RDM_CURSOR that is associated with an RDM_DB other than the RDM_DB associated with memberCursor 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 member table (memberCursor) and the owner table associated with the set refId
Return values
sOKAY Normal, successful return.
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.
eDBNOTOPEN Database not open.
eNOCURRENTROW The cursor is not positioned to a valid row.
eOWNERDELETED The owner row for a set cursor has been deleted.
eSINGLETONDELETED The row for a singleton cursor has been deleted.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetOwnerTableId
rdm_cursorGetOwnerRowId
rdm_cursorGetMemberRows
rdm_cursorGetOwnerRowsOfMembers
rdm_cursorGetRowsAtPosition
rdm_cursorGetRowsByKeyAtPosition
rdm_cursorGetRowsInReverseOrder
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorGetSiblingRowsAtPosition
rdm_cursorGetClone
rdm_cursorMoveToNext
rdm_cursorReadRow
rdm_cursorUpdateRow
rdm_cursorDeleteRow
rdm_cursorLinkRow
Parameters
[in] memberCursor [in] The cursor for the member
[in] refId [in] The set identifier for the requesting owner
[out] pCursor [out] A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

rdm_cursorGetSiblingRows()

RDM_RETCODE rdm_cursorGetSiblingRows ( RDM_CURSOR memberCursor,
RDM_REF_ID refId,
RDM_CURSOR * pCursor
)

#include <rdmcursorapi.h>

Associate an RDM_CURSOR with siblings.

This function associates the RDM_CURSOR pointed to by pCursor with a set of rows containing all the member rows related (as members of the same owner) to the current row of memberCursor for the set identified by refId. The resulting cursor will be positioned at BeforeFirst.

If memberCursor is not at a row that is a valid member of the set identified by refId an error will be returned and the RDM_CURSOR will not be associated.

memberCursor can be any type of RDM_CURSOR as long as it's current row is a valid member of the set identified by refId.

Cursor Association Rules
  • If pCursor points to NULL then a new cursor will be allocated and associated with the same RDM_DB as memberCursor.
  • If pCursor points to an RDM_CURSOR that has been allocated, but not associated with an RDM_DB then the RDM_CURSOR will be associated with the same RDM_DB as memberCursor.
  • If pCursor points to an RDM_CURSOR that is associated with an RDM_DB other than the RDM_DB associated with memberCursor 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 member table associated with the set refId (unless memberCursor is a set cursor associated with refId) and the table owner table associated with the set refId.

Return values
sOKAY Normal, successful return.
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.
eDBNOTOPEN Database not open.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_cursorGetSiblingRowsAtPosition
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetOwnerRow
rdm_cursorGetRowsAtPosition
rdm_cursorGetRowsByKeyAtPosition
rdm_cursorGetRowsInReverseOrder
rdm_cursorGetSelf
rdm_cursorGetClone
rdm_cursorMoveToNext
rdm_cursorReadRow
rdm_cursorUpdateRow
rdm_cursorDeleteRow
rdm_cursorLinkRow
Parameters
[in] memberCursor [in] The source cursor for the member row
[in] refId [in] The set identifier for the requested set of siblings
[out] pCursor [out] A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

rdm_cursorGetSiblingRowsAtPosition()

RDM_RETCODE rdm_cursorGetSiblingRowsAtPosition ( RDM_CURSOR memberCursor,
RDM_REF_ID refId,
RDM_CURSOR * pCursor
)

#include <rdmcursorapi.h>

Associate an RDM_CURSOR with siblings.

This function associates the RDM_CURSOR pointed to by pCursor with a set of rows containing all the member rows related (as members of the same owner) to the current row of memberCursor for the set identified by refId. The resulting cursor will be positioned at the same row as memberCursor

If memberCursor is not at a row that is a valid member of the set identified by refId an error will be returned and the RDM_CURSOR will not be associated.

memberCursor can be any type of RDM_CURSOR as long as it's current row is a valid member of the set identified by refId.

Cursor Association Rules
  • If pCursor points to NULL then a new cursor will be allocated and associated with the same RDM_DB as memberCursor.
  • If pCursor points to an RDM_CURSOR that has been allocated, but not associated with an RDM_DB then the RDM_CURSOR will be associated with the same RDM_DB as memberCursor.
  • If pCursor points to an RDM_CURSOR that is associated with an RDM_DB other than the RDM_DB associated with memberCursor 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 owner table and the member table associated with the set refId.

Return values
sOKAY Normal, successful return.
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.
eDBNOTOPEN Database not open.
eNOCURRENTROW The cursor is not positioned to a valid row.
eOWNERDELETED The owner row for a set cursor has been deleted.
eSINGLETONDELETED The row for a singleton cursor has been deleted.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_cursorGetSiblingRows
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetOwnerRow
rdm_cursorGetRowsAtPosition
rdm_cursorGetRowsByKeyAtPosition
rdm_cursorGetRowsInReverseOrder
rdm_cursorGetSelf
rdm_cursorGetClone
rdm_cursorMoveToNext
rdm_cursorReadRow
rdm_cursorUpdateRow
rdm_cursorDeleteRow
rdm_cursorLinkRow
Parameters
[in] memberCursor [in] The source cursor for the member row
[in] refId [in] The set identifier for the requested set of siblings
[out] pCursor [out] A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)