Collaboration diagram for Cursor Navigation Functions:

Functions
RDM_RETCODE	rdm_cursorMoveToAfterLast (RDM_CURSOR cursor)
	Position a cursor to the AfterLast position. More...

RDM_RETCODE	rdm_cursorMoveToBeforeFirst (RDM_CURSOR cursor)
	Position a cursor to the BeforeFirst position. More...

RDM_RETCODE	rdm_cursorMoveToFirst (RDM_CURSOR cursor)
	Position a cursor to the first row in the collection. More...

RDM_RETCODE	rdm_cursorMoveToKey (RDM_CURSOR cursor, RDM_KEY_ID keyId, const void *keyValue, size_t bytesIn)
	Position a cursor based on a key value. More...

RDM_RETCODE	rdm_cursorMoveToLast (RDM_CURSOR cursor)
	Position a cursor to the last row in the collection. More...

RDM_RETCODE	rdm_cursorMoveToNext (RDM_CURSOR cursor)
	Position a cursor to the next row in the collection. More...

RDM_RETCODE	rdm_cursorMoveToPosition (RDM_CURSOR cursor1, RDM_CURSOR cursor2)
	Position a cursor based on the currow row of another cursor. More...

RDM_RETCODE	rdm_cursorMoveToPrevious (RDM_CURSOR cursor)
	Position a cursor to the previous row in the collection. More...

RDM_RETCODE	rdm_cursorMoveToRowId (RDM_CURSOR cursor, RDM_ROWID_T rowid)
	Position a cursor based on a rowid. More...

RDM_RETCODE	rdm_cursorMoveToSearchKey (RDM_CURSOR cursor, RDM_KEY_ID keyId, const RDM_SEARCH_KEY *keyValue)
	Position a cursor based on a key value. More...

Detailed Description

API for navigating a core cursor. All the functions here are located in RDM DB Engine Library. Linker option:

    -lrdmrdm

See RDM Cursor APIs for a more detailed description of a cursor.

Function Documentation

◆ rdm_cursorMoveToAfterLast()

RDM_RETCODE rdm_cursorMoveToAfterLast ( RDM_CURSOR cursor )

#include <rdmcursorapi.h>

Position a cursor to the AfterLast position.

This function will position a cursor to the AfterLast position.

Locking Requirements: If cursor is a set cursor then the owner table associated need a read lock.

Return values

sOKAY	Normal, successful return.
eDBNOTOPEN	Database not open.
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.
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_cursorMoveToBeforeFirst; rdm_cursorMoveToFirst; rdm_cursorMoveToKey; rdm_cursorMoveToLast; rdm_cursorMoveToNext; rdm_cursorMoveToPosition; rdm_cursorMoveToPrevious; rdm_cursorMoveToRowId; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in] cursor The cursor to be positioned

◆ rdm_cursorMoveToBeforeFirst()

RDM_RETCODE rdm_cursorMoveToBeforeFirst ( RDM_CURSOR cursor )

#include <rdmcursorapi.h>

Position a cursor to the BeforeFirst position.

This function will position a cursor to the BeforeFirst position.

Locking Requirements: If cursor is a set cursor then the owner table associated need a read lock.

Return values

sOKAY	Normal, successful return.
eDBNOTOPEN	Database not open.
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.
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_cursorMoveToAfterLast; rdm_cursorMoveToFirst; rdm_cursorMoveToKey; rdm_cursorMoveToLast; rdm_cursorMoveToNext; rdm_cursorMoveToPosition; rdm_cursorMoveToPrevious; rdm_cursorMoveToRowId; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in] cursor The cursor to be positioned

◆ rdm_cursorMoveToFirst()

RDM_RETCODE rdm_cursorMoveToFirst ( RDM_CURSOR cursor )

#include <rdmcursorapi.h>

Position a cursor to the first row in the collection.

This function will position a cursor to the first row in the collection. If there are no rows in the collection then the cursor will be positioned to AfterLast and the function will return sENDOFCURSOR.

Locking Requirements: Read lock on the table associated with the cursor. If cursor is a set cursor then the owner table associated with that cursor also need a read lock.

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.
sENDOFCURSOR	Reached the end of the cursor collection. No rows in the collection.
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_cursorMoveToAfterLast; rdm_cursorMoveToBeforeFirst; rdm_cursorMoveToKey; rdm_cursorMoveToLast; rdm_cursorMoveToNext; rdm_cursorMoveToPosition; rdm_cursorMoveToPrevious; rdm_cursorMoveToRowId; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in] cursor The cursor to be positioned

Examples: c-core/01_helloworld_c/core01Example_main.c, c-core/02_core/core02Example_main.c, c-core/03_core/core03Example_main.c, c-core/04_core/core04Example_main.c, c-core/05_core/core05Example_main.c, c-core/06_core/core06Example_main.c, c-core/07_core/core07Example_main.c, c-core/08_core/core08Example_main.c, c-core/09_core/core09Example_main.c, c-core/10_core/core10Example_main.c, c-core/11_core/core11Example_main.c, c-core/12_core/core12Example_main.c, c-core/13_core/core13Example_main.c, c-core/14_core/core14Example_main.c, c-core/15_core/core15Example_main.c, c-core/16_core/core16Example_main.c, c-core/18_core/core18Example_main.c, c-core/19_core/core19Example_main.c, c-core/20_core/core20Example_main.c, c-core/21_core/core21Example_main.c, c-core/22_core/core22Example_main.c, c-core/23_core/core23Example_main.c, c-core/31_core/core31Example_main.c, c-core/32_core/core32Example_main.c, cursor/printAdults.c, cursor/printChildNamesForMother.c, cursor/printChildrenNamesWithUnknownFather.c, cursor/printMembers.c, cursor/printSiblingNamesOnMothersSide.c, cursor/registerVoters.c, rtree/deleteZipcode.c, rtree/retrieveAllZipcode.c, rtree/retrieveContainedZipcode.c, rtree/retrieveExactZipcode.c, rtree/retrieveOverlapZipcode.c, and rtree/updateZipcode.c.

◆ rdm_cursorMoveToKey()

RDM_RETCODE rdm_cursorMoveToKey	(	RDM_CURSOR	cursor,
		RDM_KEY_ID	keyId,
		const void *	keyValue,
		size_t	bytesIn
	)

#include <rdmcursorapi.h>

Position a cursor based on a key value.

This function will position a cursor to the first row in the row set that has the specified key value. The cursor to be positioned can be any type of cursor and does not need to be a key scan cursor based on keyId. Using the partial key allows a subset of the columns in a compound key to be considered in the search.

If there is no exact match then:

If the cursor is a key scan cursor based on the same key as the specified key then the function will return sNOTFOUND and the cursor will be placed in the CURSOR_BETWEEN position. Navigating forward (rdm_cursorMoveToNext()) from that position will position the cursor at the next key value larger than the specified key value. Navigating backward (rdm_cursorMoveToPrevious()) from that position will position the cursor at the next key value smaller than the specified key value (assuming the cursor is not in reverse order).
Otherwise the function will return eNOTINCURSOR and the cursor position will be left unchanged.

The engine validates the size of the buffers prior to accessing them.

If the size of the keyValue.value buffer is smaller than the size required to fully define the key then the remainder of the full buffer will be padded with NULL bytes and the search will be performed using that value.
If the size of the keyValue.value buffer is larger than the size required to fully define the key then the extra bytes will be ignored and the search will be performed using the truncated value.

Locking Requirements: Read lock on the table associated with the cursor. If cursor is a set cursor then the owner table associated also need a read lock.

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.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.
sNOTFOUND	Requested item not found. Did not find an exact match, but positioned cursor between keys.
eNOTINCURSOR	The row is not in the cursor.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToAfterLast; rdm_cursorMoveToBeforeFirst; rdm_cursorMoveToFirst; rdm_cursorMoveToLast; rdm_cursorMoveToNext; rdm_cursorMoveToPosition; rdm_cursorMoveToPrevious; rdm_cursorMoveToRowId; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in]	cursor	The cursor to be positioned
[in]	keyId	The key id
[in]	keyValue	The key value to position to
[in]	bytesIn	The length of keyValue in bytes

Examples: c-core/17_core/core17Example_main.c, c-core/33_core/core33Example_main.c, and cursor/registerVoters.c.

Referenced by RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_range(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_stat(), and RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_value().

Here is the caller graph for this function:

◆ rdm_cursorMoveToLast()

RDM_RETCODE rdm_cursorMoveToLast ( RDM_CURSOR cursor )

#include <rdmcursorapi.h>

Position a cursor to the last row in the collection.

This function will position a cursor to the last row in the collection. If there are no rows in the collection then the cursor will be positioned to BeforeFirst and the function will return sENDOFCURSOR.

Locking Requirements: Read lock on the table associated with the cursor. If cursor is a set cursor then the owner table associated also need a read lock.

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.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.
sENDOFCURSOR	Reached the end of the cursor collection. No rows in the collection.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToAfterLast; rdm_cursorMoveToBeforeFirst; rdm_cursorMoveToFirst; rdm_cursorMoveToKey; rdm_cursorMoveToNext; rdm_cursorMoveToPosition; rdm_cursorMoveToPrevious; rdm_cursorMoveToRowId; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in] cursor The cursor to be positioned

Examples: c-core/20_core/core20Example_main.c, c-core/21_core/core21Example_main.c, c-core/22_core/core22Example_main.c, c-core/23_core/core23Example_main.c, cursor/printAdultsInReverseSortedOrder.c, and cursor/registerMembers.c.

Referenced by RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_range(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_stat(), and RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_value().

Here is the caller graph for this function:

◆ rdm_cursorMoveToNext()

RDM_RETCODE rdm_cursorMoveToNext ( RDM_CURSOR cursor )

#include <rdmcursorapi.h>

Position a cursor to the next row in the collection.

This function will position a cursor to the next row in the collection.

If cursor was positioned to the last row in the collection then the cursor will be positioned to AfterLast and the function will return the status sENDOFCURSOR.

If cursor was positioned to AfterLast then the function will return the error eINVITERATION.

Locking Requirements: Read lock on the table associated with the cursor. If cursor is a set cursor then the owner table associated also need a read lock.

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.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.
sENDOFCURSOR	Reached the end of the cursor collection. Reached the end of the collection.
eINVITERATION	Invalid attempt to move cursor before 'BeforeFirst' or past 'AfterLast'.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToAfterLast; rdm_cursorMoveToBeforeFirst; rdm_cursorMoveToFirst; rdm_cursorMoveToKey; rdm_cursorMoveToLast; rdm_cursorMoveToPosition; rdm_cursorMoveToPrevious; rdm_cursorMoveToRowId; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in] cursor The cursor to be positioned

Examples: c-core/02_core/core02Example_main.c, c-core/03_core/core03Example_main.c, c-core/04_core/core04Example_main.c, c-core/05_core/core05Example_main.c, c-core/06_core/core06Example_main.c, c-core/07_core/core07Example_main.c, c-core/08_core/core08Example_main.c, c-core/09_core/core09Example_main.c, c-core/10_core/core10Example_main.c, c-core/11_core/core11Example_main.c, c-core/12_core/core12Example_main.c, c-core/13_core/core13Example_main.c, c-core/14_core/core14Example_main.c, c-core/15_core/core15Example_main.c, c-core/16_core/core16Example_main.c, c-core/17_core/core17Example_main.c, c-core/18_core/core18Example_main.c, c-core/20_core/core20Example_main.c, c-core/21_core/core21Example_main.c, c-core/22_core/core22Example_main.c, c-core/23_core/core23Example_main.c, c-core/31_core/core31Example_main.c, c-core/32_core/core32Example_main.c, c-core/33_core/core33Example_main.c, cursor/printAdults.c, cursor/printANumberOfAdultsArroundRecord.c, cursor/printANumberOfAdultsArroundRecordInSortedOrder.c, cursor/printChildNamesForMother.c, cursor/printChildrenNamesWithUnknownFather.c, cursor/printMembers.c, cursor/printOurCommonChildrenNames.c, cursor/printSiblingNamesOnMothersSide.c, cursor/registerMembers.c, cursor/registerVoters.c, rtree/deleteZipcode.c, rtree/retrieveAllZipcode.c, rtree/retrieveContainedZipcode.c, rtree/retrieveExactZipcode.c, and rtree/retrieveOverlapZipcode.c.

Referenced by RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_range(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_stat(), and RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, AGGREGATE_T, NEXT >::put_value().

Here is the caller graph for this function:

◆ rdm_cursorMoveToPosition()

RDM_RETCODE rdm_cursorMoveToPosition	(	RDM_CURSOR	cursor1,
		RDM_CURSOR	cursor2
	)

#include <rdmcursorapi.h>

Position a cursor based on the currow row of another cursor.

This function will position a cursor to the current row of another cursor. If the row is not in the row set an error (eNOTINCURSOR) will be returned and the cursor position will be left unchanged.

Note: If the exact cursor position and not the current row is wanted (the two cursors have to be of the same type) one would need to use rdm_cursorGetClone() instead.

Locking Requirements: Read lock on the table associated with the cursor. If cursor is a set cursor then the owner table associated also need a read lock.

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.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.
sNOTFOUND	Requested item not found. Did not find an exact match, but positioned cursor between records.
eNOTINCURSOR	The row is not in the cursor.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToAfterLast; rdm_cursorMoveToBeforeFirst; rdm_cursorMoveToFirst; rdm_cursorMoveToKey; rdm_cursorMoveToLast; rdm_cursorMoveToNext; rdm_cursorMoveToPrevious; rdm_cursorMoveToRowId; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in]	cursor1	The cursor to be positioned
[in]	cursor2	The cursor whose current row cursor1 will be positioned to

Examples: cursor/printOurCommonChildrenNames.c.

◆ rdm_cursorMoveToPrevious()

RDM_RETCODE rdm_cursorMoveToPrevious ( RDM_CURSOR cursor )

#include <rdmcursorapi.h>

Position a cursor to the previous row in the collection.

This function will position a cursor to the previous row in the collection.

If cursor was positioned to the first row in the collection then the cursor will be positioned to BeforeFirst and the function will return the status sENDOFCURSOR.

If cursor was positioned to BeforeFirst then the function will return the error eINVITERATION.

Locking Requirements: Read lock on the table associated with the cursor. If cursor is a set cursor then the owner table associated also need a read lock.

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.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.
sENDOFCURSOR	Reached the end of the cursor collection. Reached the end of the collection.
eINVITERATION	Invalid attempt to move cursor before 'BeforeFirst' or past 'AfterLast'.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToAfterLast; rdm_cursorMoveToBeforeFirst; rdm_cursorMoveToFirst; rdm_cursorMoveToKey; rdm_cursorMoveToLast; rdm_cursorMoveToNext; rdm_cursorMoveToPosition; rdm_cursorMoveToRowId; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in] cursor The cursor to be positioned

Examples: c-core/20_core/core20Example_main.c, c-core/21_core/core21Example_main.c, c-core/22_core/core22Example_main.c, c-core/23_core/core23Example_main.c, cursor/printAdultsInReverseSortedOrder.c, cursor/printANumberOfAdultsArroundRecord.c, cursor/printANumberOfAdultsArroundRecordInSortedOrder.c, and cursor/registerMembers.c.

◆ rdm_cursorMoveToRowId()

RDM_RETCODE rdm_cursorMoveToRowId	(	RDM_CURSOR	cursor,
		RDM_ROWID_T	rowid
	)

#include <rdmcursorapi.h>

Position a cursor based on a rowid.

This function will position a cursor to the row at specified rowid. The cursor can be any type of cursor and does not need to be a table scan cursor.

If there is no exact match found then:

If the cursor is a table scan cursor then the function will return sNOTFOUND and the cursor will be placed in the CURSOR_BETWEEN position. Navigating forward (rdm_cursorMoveToNext()) from that position will place the cursor at the next valid rowid larger than the specified rowid. Navigating backward (rdm_cursorMoveToPrevious()) from that position will position the cursor at the next rowid smaller than the specified rowid (assuming the cursor is not in reverse order).
Otherwise the function will return eNOTINCURSOR and the cursor position will be left unchanged.

Locking Requirements: Read lock on the table associated with the cursor. If cursor is a set cursor then the owner table associated also need a read lock.

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.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.
eNOTINCURSOR	The row is not in the cursor.
sNOTFOUND	Requested item not found.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToAfterLast; rdm_cursorMoveToBeforeFirst; rdm_cursorMoveToFirst; rdm_cursorMoveToKey; rdm_cursorMoveToLast; rdm_cursorMoveToNext; rdm_cursorMoveToPosition; rdm_cursorMoveToPrevious; rdm_cursorMoveToSearchKey; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in]	cursor	The cursor to be positioned
[in]	rowid	The rowid to position the cursor to

Examples: cursor/initialize_get_find_TheKing.c.

◆ rdm_cursorMoveToSearchKey()

RDM_RETCODE rdm_cursorMoveToSearchKey	(	RDM_CURSOR	cursor,
		RDM_KEY_ID	keyId,
		const RDM_SEARCH_KEY *	keyValue
	)

#include <rdmcursorapi.h>

Position a cursor based on a key value.

This function will position a cursor to the first row in the row set that has the specified key value. The cursor to be positioned can be any type of cursor and does not need to be a key scan cursor based on keyId. Using the partial key allows a subset of the columns in a compound key to be considered in the search.

If there is no exact match then:

If the cursor is a key scan cursor based on the same key as the specified key then the function will return sNOTFOUND and the cursor will be placed in the CURSOR_BETWEEN position. Navigating forward (rdm_cursorMoveToNext()) from that position will position the cursor at the next key value larger than the specified key value. Navigating backward (rdm_cursorMoveToPrevious()) from that position will position the cursor at the next key value smaller than the specified key value (assuming the cursor is not in reverse order).
Otherwise the function will return eNOTINCURSOR and the cursor position will be left unchanged.

The engine validates the size of the buffers prior to accessing them.

If the size of the keyValue.value buffer is smaller than the size required to fully define the key then the remainder of the full buffer will be padded with NULL bytes and the search will be performed using that value.
If the size of the keyValue.value buffer is larger than the size required to fully define the key then the extra bytes will be ignored and the search will be performed using the truncated value.

Locking Requirements: Read lock on the table associated with the cursor. If cursor is a set cursor then the owner table associated also need a read lock.

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.
eOWNERDELETED	The owner row for a set cursor has been deleted.
eSINGLETONDELETED	The row for a singleton cursor has been deleted.
sNOTFOUND	Requested item not found. Did not find an exact match, but positioned cursor between keys.
eNOTINCURSOR	The row is not in the cursor.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToAfterLast; rdm_cursorMoveToBeforeFirst; rdm_cursorMoveToFirst; rdm_cursorMoveToKey; rdm_cursorMoveToLast; rdm_cursorMoveToNext; rdm_cursorMoveToPosition; rdm_cursorMoveToPrevious; rdm_cursorMoveToRowId; rdm_cursorComparePosition; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in]	cursor	The cursor to be positioned
[in]	keyId	The key id
[in]	keyValue	The key value to position to