Collaboration diagram for Cursor Association Functions (other):

Functions
RDM_RETCODE	rdm_cursorGetClone (RDM_CURSOR sourceCursor, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR as a clone of an existing RDM_CURSOR. More...

RDM_RETCODE	rdm_cursorGetRowsInReverseOrder (RDM_CURSOR sourceCursor, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR as a copy of an existing RDM_CURSOR with the rows in reverse order. More...

RDM_RETCODE	rdm_cursorGetSelf (RDM_CURSOR sourceCursor, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with the current row of the sourceCursor. More...

Detailed Description

Core cursor association API for other functions. All the functions here are located in RDM DB Engine Library. Linker option:

    -lrdmrdm

See cursor for a more detailed description of a cursor.

Function Documentation

rdm_cursorGetClone()

RDM_RETCODE rdm_cursorGetClone	(	RDM_CURSOR	sourceCursor,
		RDM_CURSOR *	pCursor
	)

#include <rdmcursorapi.h>

Associate an RDM_CURSOR as a clone of an existing RDM_CURSOR.

This function associates the RDM_CURSOR pointed to by pCursor as a clone of sourceCursor. The resulting RDM_CURSOR will be of the same type, contain the same row set, and will have the same current row as sourceCursor.

Cursor Association Rules

If pCursor points to NULL then a new cursor will be allocated and associated with the same RDM_DB as sourceCursor.
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 sourceCursor.
If pCursor points to an RDM_CURSOR that is associated with an RDM_DB other than the RDM_DB associated with sourceCursor 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 associated with the sourceCursor

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.
sNOTFOUND	Requested item not found.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorGetMemberRows; rdm_cursorGetOwnerRow; rdm_cursorGetRowsInReverseOrder; rdm_cursorGetSelf; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in]	sourceCursor	The cursor to clone
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with the same db as sourceCursor, or set to NULL)

Examples: cursor/printAdults.c, cursor/printMembers.c, and cursor/registerMembers.c.

rdm_cursorGetRowsInReverseOrder()

RDM_RETCODE rdm_cursorGetRowsInReverseOrder	(	RDM_CURSOR	sourceCursor,
		RDM_CURSOR *	pCursor
	)

#include <rdmcursorapi.h>

Associate an RDM_CURSOR as a copy of an existing RDM_CURSOR with the rows in reverse order.

This function associates the RDM_CURSOR pointed to by pCursor with the same set of rows in sourceCursor, but in the reverse navigation order. The pCursor can point to sourceCursor and in this case you will get sourceCursor back in the reverse order. The resulting cursor will be initially positioned to the BeforeFirst location, which would be the same as AfterLast of the sourceCursor.

Cursor Association Rules

If pCursor points to NULL then a new cursor will be allocated and associated with the same RDM_DB as sourceCursor.
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 sourceCursor.
If pCursor points to an RDM_CURSOR that is associated with an RDM_DB other than the RDM_DB associated with sourceCursor 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.
eDBNOTOPEN	Database not open.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorGetMemberRows; rdm_cursorGetOwnerRow; rdm_cursorGetRowsAtPosition; rdm_cursorGetRowsByKeyAtPosition; rdm_cursorGetSelf; rdm_cursorGetSiblingRows; rdm_cursorGetClone; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in]	sourceCursor	The source cursor to reverse the retrieval order for
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

rdm_cursorGetSelf()

RDM_RETCODE rdm_cursorGetSelf	(	RDM_CURSOR	sourceCursor,
		RDM_CURSOR *	pCursor
	)

#include <rdmcursorapi.h>

Associate an RDM_CURSOR with the current row of the sourceCursor.

This function associates the RDM_CURSOR pointed to by pCursor with the current row of sourceCursor. The new cursor will be a singleton cursor positioned to the current row of sourceCursor.

If the sourceCursor is not at a valid row then 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 sourceCursor.
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 sourceCursor.
If pCursor points to an RDM_CURSOR that is associated with an RDM_DB other than the RDM_DB associated with sourceCursor 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 associated with the sourceCursor

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_cursorGetMemberRows; rdm_cursorGetOwnerRow; rdm_cursorGetRowsAtPosition; rdm_cursorGetRowsByKeyAtPosition; rdm_cursorGetRowsInReverseOrder; rdm_cursorGetSiblingRows; rdm_cursorGetClone; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in]	sourceCursor	The source cursor for the row
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: cursor/initialize_get_find_TheKing.c.