Collaboration diagram for Cursor Association Functions (keyscan):

Functions
RDM_RETCODE	rdm_dbGetRowsByKey (RDM_DB db, RDM_KEY_ID keyId, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with a row set based on a key. More...

RDM_RETCODE	rdm_dbGetRowsByKeyAtKey (RDM_DB db, RDM_KEY_ID keyId, const void keyValue, size_t len, RDM_CURSOR pCursor)
	Associate an RDM_CURSOR with a row set that is ordered by key value and is initially positioned at the specified key value. More...

RDM_RETCODE	rdm_dbGetRowsByKeyAtSearchKey (RDM_DB db, RDM_KEY_ID keyId, const RDM_SEARCH_KEY keyValue, RDM_CURSOR pCursor)
	Associate an RDM_CURSOR with a row set that is ordered by key value and is initially positioned at the specified key value. More...

RDM_RETCODE	rdm_dbGetRowsByKeyInKeyRange (RDM_DB db, RDM_KEY_ID keyId, const void startValue, size_t bytesInStartValue, const void endValue, size_t bytesInEndValue, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with rows in a specified key range. More...

RDM_RETCODE	rdm_dbGetRowsByKeyInRangeKeyRange (RDM_DB db, RDM_KEY_ID keyId, const RDM_RANGE_KEY startValue, const RDM_RANGE_KEY endValue, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with rows in a specified key range. More...

RDM_RETCODE	rdm_dbGetRowsByKeyInRtreeKeyRange (RDM_DB db, RDM_KEY_ID keyId, const RDM_RTREE_KEY keyValue, RDM_CURSOR pCursor)
	Associate an RDM_CURSOR with a row set based on a R-tree. More...

RDM_RETCODE	rdm_dbGetRowsByKeyInSearchKeyRange (RDM_DB db, RDM_KEY_ID keyId, const RDM_SEARCH_KEY startValue, const RDM_SEARCH_KEY endValue, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with rows in a specified key range. More...

Detailed Description

Cursor association API for retrieving rows in key order. 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_dbGetRowsByKey()

RDM_RETCODE rdm_dbGetRowsByKey	(	RDM_DB	db,
		RDM_KEY_ID	keyId,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with a row set based on a key.

This function associates the RDM_CURSOR pointed to by pCursor with a row set ordered by the specified key. The row set will contain all of the rows for the table of the key specified. The RDM_CURSOR will be initially positioned in the BeforeFirst position.

Cursor Association Rules

If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
eINVCURSORID	Invalid cursor id.
eINVKEYID	Invalid key id.
eISRTREE	The key specified is an rtree index.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	keyId	The RDM key id
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: c-core/05_core/core05Example_main.c, c-core/06_core/core06Example_main.c, c-core/08_core/core08Example_main.c, c-core/09_core/core09Example_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/22_core/core22Example_main.c, c-core/23_core/core23Example_main.c, and cursor/printAdultsInReverseSortedOrder.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_dbGetRowsByKeyAtKey()

RDM_RETCODE rdm_dbGetRowsByKeyAtKey	(	RDM_DB	db,
		RDM_KEY_ID	keyId,
		const void *	keyValue,
		size_t	len,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with a row set that is ordered by key value and is initially positioned at the specified key value.

This function associates a row set ordered by the specified key with the RDM_CURSOR pointed to by pCursor. The row set contains all of the rows for the table that the specified key is in.

The RDM_CURSOR will be initially positioned at the first row that matches the specified key value. If there is not an exact match then the RDM_CURSOR will be placed in the CURSOR_BETWEEN position. Navigating forward (rdm_cursorMoveToNext()) from that position will position the RDM_CURSOR at the next key value larger than the specified key value. Navigating backward (rdm_cursorMoveToPrevious()) from that position will position the RDM_CURSOR at the next key value smaller than the specified key value.

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

If the size of the keyValue 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 buffer is larger than the size required to fully the key then the extra bytes will be ignored and the search will be performed using the truncated value.

Cursor Association Rules

If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements: Read lock on the table associated with keyId.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found. Success, but no exact key value match, the cursor position is set to CURSOR_BETWEEN.
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.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
eINVCURSORID	Invalid cursor id.
eINVKEYID	Invalid key id.
eISRTREE	The key specified is an rtree index.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	keyId	The RDM key id
[in]	keyValue	The key value used to position the cursor
[in]	len	The length of the key value buffer
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: c-core/06_core/core06Example_main.c, c-core/07_core/core07Example_main.c, c-core/10_core/core10Example_main.c, c-core/17_core/core17Example_main.c, c-core/28_core/core28Example_main.c, c-core/29_core/core29Example_main.c, c-core/30_core/core30Example_main.c, c-core/31_core/core31Example_main.c, c-core/33_core/core33Example_main.c, cursor/adoptChild.c, and cursor/initialize_get_find_TheKing.c.

◆ rdm_dbGetRowsByKeyAtSearchKey()

RDM_RETCODE rdm_dbGetRowsByKeyAtSearchKey	(	RDM_DB	db,
		RDM_KEY_ID	keyId,
		const RDM_SEARCH_KEY *	keyValue,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with a row set that is ordered by key value and is initially positioned at the specified key value.

This function associates a row set ordered by the specified key with the RDM_CURSOR pointed to by pCursor. The row set contains all of the rows for the table that the specified key is in.

The RDM_CURSOR will be initially positioned at the first row that matches the specified key value. If there is not an exact match then the RDM_CURSOR will be placed in the CURSOR_BETWEEN position. Navigating forward (rdm_cursorMoveToNext()) from that position will position the RDM_CURSOR at the next key value larger than the specified key value. Navigating backward (rdm_cursorMoveToPrevious()) from that position will position the RDM_CURSOR at the next key value smaller than the specified key value.

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

If the size of the keyValue 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 buffer is larger than the size required to fully the key then the extra bytes will be ignored and the search will be performed using the truncated value.

Cursor Association Rules

If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements: Read lock on the table associated with keyId.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found. Success, but no exact key value match, the cursor position is set to CURSOR_BETWEEN.
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.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
eINVCURSORID	Invalid cursor id.
eINVKEYID	Invalid key id.
eISRTREE	The key specified is an rtree index.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	keyId	The RDM key id
[in]	keyValue	The key value used to position the cursor
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

◆ rdm_dbGetRowsByKeyInKeyRange()

RDM_RETCODE rdm_dbGetRowsByKeyInKeyRange	(	RDM_DB	db,
		RDM_KEY_ID	keyId,
		const void *	startValue,
		size_t	bytesInStartValue,
		const void *	endValue,
		size_t	bytesInEndValue,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with rows in a specified key range.

This function associates the RDM_CURSOR pointed to by pCursor with a row set ordered by the specified key. The row set contains all of the rows for the table that have a key value that is in the range specified by the start and end values. If the specified start value is NULL then the start of the range will be the first index value. If the end value is NULL then the end of the range will be the last index value. Specifying a start value of NULL and an end value of NULL is equivalent to rdm_dbGetRowsByKey().

For a key that allows duplicate values it can be useful to specify the same value for the start and the end range. For example, the foreign side of a primary foreign key relationship can be retrieved by specifying the primary key value as the start and end value of a key on the foreign table that references the primary key of the primary table. If the index is unique then specifying the same start and end value will result in at most one row in the cursor collection.

The cursor will be initially positioned to the BeforeFirst location.

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

If the value of bytesInStartValue or bytesInEnd is zero, the size of startValue or endValue is assumed to be large enough to fully define the key.
If the value of bytesInStartValue or bytesInEnd is non-zero, the value must be large enough to fully define the key. Otherwise, an error is returned.
If the size of the buffer is larger than the size required to fully the key then the extra bytes will be ignored and the search will be performed using the truncated value.

Cursor Association Rules

If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found. Success, but no exact key value match, the cursor position is set to CURSOR_BETWEEN.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
eINVCURSORID	Invalid cursor id.
eINVKEYID	Invalid key id.
eISRTREE	The key specified is an rtree index.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	keyId	The RDM key id
[in]	startValue	The value for the start of the range
[in]	bytesInStartValue	the size of startValue in bytes
[in]	endValue	The value for the end of the range
[in]	bytesInEndValue	the size of endValue in bytes
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

◆ rdm_dbGetRowsByKeyInRangeKeyRange()

RDM_RETCODE rdm_dbGetRowsByKeyInRangeKeyRange	(	RDM_DB	db,
		RDM_KEY_ID	keyId,
		const RDM_RANGE_KEY *	startValue,
		const RDM_RANGE_KEY *	endValue,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with rows in a specified key range.

This function associates the RDM_CURSOR pointed to by pCursor with a row set ordered by the specified key. The row set contains all of the rows for the table that have a key value that is in the range specified by the start and end values. If the specified start value is NULL then the start of the range will be the first index value stored in the database. If the end value is NULL then the end of the range will be the last index value stored in the database. Specifying a start value of NULL and an end value of NULL is equivalent to rdm_dbGetRowsByKey().

For a key that allows duplicate values it can be useful to specify the same value for the start and the end range. For example, the foreign side of a primary foreign key relationship can be retrieved by specifying the primary key value as the start and end value of a key on the foreign table that references the primary key of the primary table. If the index is unique then specifying the same start and end value will result in at most one row in the cursor collection.

The range can either be 'inclusive' or 'exclusive'. If the range field in the RDM_RANGE_KEY is set to RDM_RANGE_OPEN keys that match the value will be included in the result set. If the range field in RDM_RANGE_KEY is RDM_RANGE_CLOSED then keys that match the value will not be included in the result set.

The cursor will be initially positioned to the BeforeFirst location.

Cursor Association Rules

If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found. Success, but no exact key value match, the cursor position is set to CURSOR_BETWEEN.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
eINVCURSORID	Invalid cursor id.
eINVKEYID	Invalid key id.
eISRTREE	The key specified is an rtree index.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	keyId	The RDM key id
[in]	startValue	The value for the start of the range
[in]	endValue	The value for the end of the range
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: rtree/deleteZipcode.c.

◆ rdm_dbGetRowsByKeyInRtreeKeyRange()

RDM_RETCODE rdm_dbGetRowsByKeyInRtreeKeyRange	(	RDM_DB	db,
		RDM_KEY_ID	keyId,
		const RDM_RTREE_KEY *	keyValue,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with a row set based on a R-tree.

This function associates the RDM_CURSOR pointed to by pCursor with a row set based on the the specified R-tree index. The row set will contain all of the rows for the table of the key specified that match the search criteria. The RDM_CURSOR will be initially positioned in the BeforeFirst position.

Cursor Association Rules

If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found. Success, but no exact key value match, the cursor position is set to CURSOR_BETWEEN.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
eINVCURSORID	Invalid cursor id.
eINVKEYID	Invalid key id.
eNOTRTREE	The key specified is not an rtree index.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	keyId	The RDM key id
[in]	keyValue	The key value used to position the cursor
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: rtree/retrieveAllZipcode.c, rtree/retrieveContainedZipcode.c, rtree/retrieveExactZipcode.c, rtree/retrieveOverlapZipcode.c, and rtree/updateZipcode.c.

◆ rdm_dbGetRowsByKeyInSearchKeyRange()

RDM_RETCODE rdm_dbGetRowsByKeyInSearchKeyRange	(	RDM_DB	db,
		RDM_KEY_ID	keyId,
		const RDM_SEARCH_KEY *	startValue,
		const RDM_SEARCH_KEY *	endValue,
		RDM_CURSOR *	pCursor
	)

#include <rdmdbapi.h>

Associate an RDM_CURSOR with rows in a specified key range.

This function associates the RDM_CURSOR pointed to by pCursor with a row set ordered by the specified key. The row set contains all of the rows for the table that have a key value that is in the range specified by the start and end values. If the specified start value is NULL then the start of the range will be the first index value. If the end value is NULL then the end of the range will be the last index value. Specifying a start value of NULL and an end value of NULL is equivalent to rdm_dbGetRowsByKey().

For a key that allows duplicate values it can be useful to specify the same value for the start and the end range. For example, the foreign side of a primary foreign key relationship can be retrieved by specifying the primary key value as the start and end value of a key on the foreign table that references the primary key of the primary table. If the index is unique then specifying the same start and end value will result in at most one row in the cursor collection.

The cursor will be initially positioned to the BeforeFirst location.

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

If the size of the startValue or endValue 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 buffer is larger than the size required to fully the key then the extra bytes will be ignored and the search will be performed using the truncated value.

Cursor Association Rules

If pCursor points to an RDM_CURSOR with a value of NULL then a new cursor will be allocated and associated with db.
If pCursor points to an RDM_CURSOR that has been allocated, it is associated with db but may not yet be associated with a set of rows.
If pCursor points to a RDM_CURSOR that is associated with an RDM_DB other than db then an error will be returned.
If pCursor points to a RDM_CURSOR that has been previously used and held a set of rows from a different table then memory may need to be reallocated to handle the new set of rows. If you are interacting with more than one set of tables it can be more efficient to use multiple RDM_CURSOR than to share a single RDM_CURSOR.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
sNOTFOUND	Requested item not found. Success, but no exact key value match, the cursor position is set to CURSOR_BETWEEN.
eCURSORDB	Cursor is associated with a different database.
eDBNOTOPEN	Database not open.
eINVCURSORID	Invalid cursor id.
eINVKEYID	Invalid key id.
eISRTREE	The key specified is an rtree index.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

Parameters

[in]	db	A valid RDM database handle
[in]	keyId	The RDM key id
[in]	startValue	The value for the start of the range
[in]	endValue	The value for the end of the range
[out]	pCursor	A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)

Examples: c-core/16_core/core16Example_main.c.