Cursor Association Functions (other)
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
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_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 [in] The cursor to clone
[out] pCursor [out] A pointer to an RDM_CURSOR (must be allocated, associated with the same db as sourceCursor, or set to NULL)

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