Products Support Documentation Download
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 fuctions 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
sOKAYNormal, successful return.
eNOTINCURSORThe 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]cursorPrimaryThe cursor whose current row is being checked relative to cursorSecondary
[in]cursorSecondaryThe cursor whose current row is being checked against
[in]comparisonA pointer to the returned comparison result value

◆ 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
sOKAYNormal, successful return.
eNOSTARTREADA read operation was attempted when no rdm_dbStartSnapshot(), rdm_dbStartRead(), or rdm_dbStartUpdate() is active.
eNOTLOCKEDAttempt to access a table for reading or update without proper locks.
eDBNOTOPENDatabase not open.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorGetRowStatus
Parameters
[in]cursorThe cursor whose position is being checked
[out]positionThe check position result value

◆ 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
sOKAYNormal, successful return.
eDBNOTOPENDatabase not open.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorMoveToAfterLast
Parameters
[in]cursorThe cursor whose position is being checked
[out]isAfterLastA 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
sOKAYNormal, successful return.
eDBNOTOPENDatabase not open.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorMoveToBeforeFirst
Parameters
[in]cursorThe cursor whose position is being checked
[out]isBeforeFirstA pointer to the returned condition