Products Support Documentation Download
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 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_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
sOKAYNormal, successful return.
eDBNOTOPENDatabase not open.
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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]cursorThe 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
sOKAYNormal, successful return.
eDBNOTOPENDatabase not open.
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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]cursorThe 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
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.
sENDOFCURSORReached the end of the cursor collection. No rows in the collection.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe 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]cursorThe cursor to be positioned
Examples:
tutorials/HelloWorld/hello_worldTutorial_main.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
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe row for a singleton cursor has been deleted.
sNOTFOUNDRequested item not found. Did not find an exact match, but positioned cursor between keys.
eNOTINCURSORThe 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]cursorThe cursor to be positioned
[in]keyIdThe key id
[in]keyValueThe key value to position to
[in]bytesInThe length of keyValue in bytes

◆ 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
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe row for a singleton cursor has been deleted.
sENDOFCURSORReached 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]cursorThe cursor to be positioned

◆ 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
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe row for a singleton cursor has been deleted.
sENDOFCURSORReached the end of the cursor collection. Reached the end of the collection.
eINVITERATIONInvalid 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]cursorThe cursor to be positioned

◆ 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
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe row for a singleton cursor has been deleted.
sNOTFOUNDRequested item not found. Did not find an exact match, but positioned cursor between records.
eNOTINCURSORThe 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]cursor1The cursor to be positioned
[in]cursor2The cursor whose current row cursor1 will be positioned to

◆ 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
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe row for a singleton cursor has been deleted.
sENDOFCURSORReached the end of the cursor collection. Reached the end of the collection.
eINVITERATIONInvalid 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]cursorThe cursor to be positioned

◆ 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
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe row for a singleton cursor has been deleted.
eNOTINCURSORThe row is not in the cursor.
sNOTFOUNDRequested 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]cursorThe cursor to be positioned
[in]rowidThe rowid to position the cursor to

◆ 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
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.
eOWNERDELETEDThe owner row for a set cursor has been deleted.
eSINGLETONDELETEDThe row for a singleton cursor has been deleted.
sNOTFOUNDRequested item not found. Did not find an exact match, but positioned cursor between keys.
eNOTINCURSORThe 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]cursorThe cursor to be positioned
[in]keyIdThe key id
[in]keyValueThe key value to position to