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, bool *isAfterLast)
	Check to see if a cursor is positioned after the last row in a collection. More...

RDM_RETCODE	rdm_cursorIsBeforeFirst (RDM_CURSOR cursor, bool *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 RaimaDB 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,
		bool *	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 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,
		bool *	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 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.