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 functions here are located in RaimaDB DB Engine Library. Linker option:

    -lrdmrdm

See 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	The cursor for the owner row
[in]	refId	The set identifier for the requesting set of members
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: core03Example_main.c, core04Example_main.c, core06Example_main.c, core07Example_main.c, core31Example_main.c, cursor/printChildNamesForMother.c, cursor/printOurCommonChildrenNames.c, and cursor/registerVoters.c.

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	The cursor for the member
[in]	refId	The set identifier for the requesting owner
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: core07Example_main.c, core10Example_main.c, and cursor/printParentNames.c.

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	The source cursor for the member row
[in]	refId	The set identifier for the requested set of siblings
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: core10Example_main.c, and cursor/printSiblingNamesOnMothersSide.c.

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	The source cursor for the member row
[in]	refId	The set identifier for the requested set of siblings
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: cursor/printSiblingNamesOnMothersSide.c.