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 \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_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 [in] The cursor whose current row is being checked relative to cursorSecondary [in] cursorSecondary [in] The cursor whose current row is being checked against [in] comparison [in] A 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
-
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 [in] The cursor whose position is being checked [out] position [out] The 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
-
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 [in] The cursor whose position is being checked [out] isAfterLast [out] 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 [in] The cursor whose position is being checked [out] isBeforeFirst [out] A pointer to the returned condition