Cursor Navigation Functions
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 cursor 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

Referenced by RDM::DB::read_row< table_id >::reset().

Here is the caller graph for this function:

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
core01Example_main.c, core02Example_main.c, core03Example_main.c, core04Example_main.c, core05Example_main.c, core06Example_main.c, core07Example_main.c, core08Example_main.c, core09Example_main.c, core10Example_main.c, core11Example_main.c, core12Example_main.c, core13Example_main.c, core15Example_main.c, core16Example_main.c, core18Example_main.c, core19Example_main.c, core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, core31Example_main.c, core32Example_main.c, core35Example_main.c, core36Example_main.c, core38Example_main.c, cpp70Example_main.cpp, cursor/printAdults.c, cursor/printChildNamesForMother.c, cursor/printChildrenNamesWithUnknownFather.c, cursor/printMembers.c, cursor/printSiblingNamesOnMothersSide.c, cursor/registerVoters.c, learn/bookStore_client.c, learn/bookStore_embed.c, learn/bookStore_vxWorks7.c, rtree/deleteZipcode.c, rtree/retrieveAllZipcode.c, rtree/retrieveContainedZipcode.c, rtree/retrieveExactZipcode.c, rtree/retrieveOverlapZipcode.c, and rtree/updateZipcode.c.

Referenced by RDM::DB::read_row< table_id >::fetch_first().

Here is the caller graph for this function:

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
core17Example_main.c, core33Example_main.c, cpp55Example_main.cpp, and cursor/registerVoters.c.

Referenced by RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_range(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_stats(), and RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, 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
core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, cursor/printAdultsInReverseSortedOrder.c, and cursor/registerMembers.c.

Referenced by RDM::DB::read_row< table_id >::fetch_last(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_range(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_stats(), and RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, 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
core02Example_main.c, core03Example_main.c, core04Example_main.c, core05Example_main.c, core06Example_main.c, core07Example_main.c, core08Example_main.c, core09Example_main.c, core10Example_main.c, core11Example_main.c, core12Example_main.c, core13Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core35Example_main.c, core38Example_main.c, cpp50Example_main.cpp, cpp55Example_main.cpp, cpp70Example_main.cpp, 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, learn/bookStore_client.c, learn/bookStore_embed.c, learn/bookStore_vxWorks7.c, rtree/deleteZipcode.c, rtree/retrieveAllZipcode.c, rtree/retrieveContainedZipcode.c, rtree/retrieveExactZipcode.c, and rtree/retrieveOverlapZipcode.c.

Referenced by RDM::DB::read_row< table_id >::fetch_next(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_range(), RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, NEXT >::put_stats(), and RDM::TIME_SERIES::restore_aggregate< TIME_STAMP_KEY_T, SOURCE_TIME_STAMP_KEY, AGGREGATE_TIME_STAMP_KEY, 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
cpp50Example_main.cpp, and 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
core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, cursor/printAdultsInReverseSortedOrder.c, cursor/printANumberOfAdultsArroundRecord.c, cursor/printANumberOfAdultsArroundRecordInSortedOrder.c, and cursor/registerMembers.c.

Referenced by RDM::DB::read_row< table_id >::fetch_prev().

Here is the caller graph for this function:

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
cpp50Example_main.cpp, and 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