Cursor Comparison Functions
Collaboration diagram for Cursor Comparison Functions:

Functions

RDM_RETCODE rdm_cursorComparePosition (RDM_CURSOR cursorPrimary, RDM_CURSOR cursorSecondary, RDM_CURSOR_COMPARE *comparison)
compare the position of a cursor relative to another cursor More...
RDM_RETCODE rdm_cursorGetStatus (RDM_CURSOR cursor, RDM_CURSOR_STATUS *position)
Check a cursor for special conditions. More...
RDM_RETCODE rdm_cursorIsAfterLast (RDM_CURSOR cursor, RDM_BOOL_T *isAfterLast)
Check to see if a cursor is positioned after the last row in a collection. More...
RDM_RETCODE rdm_cursorIsBeforeFirst (RDM_CURSOR cursor, RDM_BOOL_T *isBeforeFirst)
Check to see if a cursor is positioned before the first row in a collection. More...

Detailed Description

API for comparing core cursor positions. 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_cursorComparePosition()

RDM_RETCODE rdm_cursorComparePosition ( RDM_CURSOR cursorPrimary,
RDM_CURSOR cursorSecondary,
RDM_CURSOR_COMPARE * comparison
)

#include <rdmcursorapi.h>

compare the position of a cursor relative to another cursor

This function compares the current position of cursorPrimary relative to cursorSecondary.

If the cursor types are not the same the current row of the secondary will be used and then converted to a position in the cursor type of cursorPrimary. If the current row of the secondary is not a valid cursor position in the primary an error will be returned.

This means:

  • If cursorPrimary is a key cursor the comparison will be based on key value.
  • If cursorPrimary is a table scan cursor the comparison will be based on rowid value
  • If cursorPrimary is a set member cursor the comparison will be based on the order in the set chain
  • If cursorPrimary is a singleton cursor the comparison is only valid if cursorSecondary and cursorPrimary are the same row (there is no order for a singleton)
  • If the row at the current position of cursorSecondary is not in the collection of cursorPrimary an error will be returned.
  • There are two distinct types of errors to be returned when the row in cursorSecondary is not found in the collection of cursorPrimary:
    • If row in cursorSecondary can never be in the collection of cursorPrimary based on the schema information (it is a different table or from another database) then eNOTRELATED will be returned.
    • If the row in cursorSecondary could be found in the collection of cursorPrimary but is not (it has a different set owner) then eNOTINCURSOR is returned.
  • In the case where the cursors are related but secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If it is not a meaningful comparison eNOTINCURSOR is returned.
Locking Requirements
None
Return values
sOKAY Normal, successful return.
eNOTINCURSOR The row is not in the cursor.
See also
rdm_cursorMoveToAfterLast
rdm_cursorMoveToBeforeFirst
rdm_cursorMoveToFirst
rdm_cursorMoveToKey
rdm_cursorMoveToLast
rdm_cursorMoveToNext
rdm_cursorMoveToPosition
rdm_cursorMoveToPrevious
rdm_cursorMoveToRowId
rdm_cursorMoveToSearchKey
rdm_cursorMoveToNext
rdm_rdmGetBeforeFirst
rdm_rdmGetAfterLast
Parameters
[in] cursorPrimary The cursor whose current row is being checked relative to cursorSecondary
[in] cursorSecondary The cursor whose current row is being checked against
[in] comparison A pointer to the returned comparison result value
Examples
cursor/printSiblingNamesOnMothersSide.c, and cursor/registerMembers.c.

rdm_cursorGetStatus()

RDM_RETCODE rdm_cursorGetStatus ( RDM_CURSOR cursor,
RDM_CURSOR_STATUS * position
)

#include <rdmcursorapi.h>

Check a cursor for special conditions.

This function will return information about an RDM_CURSOR's position.

As you navigate (using any of the rdm_cursorMove* functions) the cursor will typically be in any of these states: CURSOR_BEFORE_FIRST; CURSOR_AT_ROW; CURSOR_BETWEEN; or, CURSOR_BEFORE_FIRST. Changes to the row through this cursor or any other cursor may put the cursor in some other state.

Locking Requirements
Read lock on the table associated with the cursor
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_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorGetRowStatus
Parameters
[in] cursor The cursor whose position is being checked
[out] position The check position result value
Examples
cursor/changeAdultIdentity.c.

rdm_cursorIsAfterLast()

RDM_RETCODE rdm_cursorIsAfterLast ( RDM_CURSOR cursor,
RDM_BOOL_T * isAfterLast
)

#include <rdmcursorapi.h>

Check to see if a cursor is positioned after the last row in a collection.

This function will set isAfterLast to RDM_TRUE if the cursor is positioned after the last row in the cursor collection.

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_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorMoveToAfterLast
Parameters
[in] cursor The cursor whose position is being checked
[out] isAfterLast A pointer to the returned condition

rdm_cursorIsBeforeFirst()

RDM_RETCODE rdm_cursorIsBeforeFirst ( RDM_CURSOR cursor,
RDM_BOOL_T * isBeforeFirst
)

#include <rdmcursorapi.h>

Check to see if a cursor is positioned before the first row in a collection.

This function will set isBeforeFirst to RDM_TRUE if the cursor is positioned before the first row in the cursor collection.

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_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorMoveToBeforeFirst
Parameters
[in] cursor The cursor whose position is being checked
[out] isBeforeFirst A pointer to the returned condition
Examples
cursor/printAdultsInReverseSortedOrder.c.