Collaboration diagram for Cursor Association Functions (keyscan):

Functions
RDM_RETCODE	rdm_cursorGetRowsByKeyAtPosition (RDM_CURSOR sourceCursor, RDM_KEY_ID keyId, RDM_CURSOR *pCursor)
	Associate an RDM_CURSOR with a row set based on a key and positioned to the same row as the source cursor. More...

Detailed Description

Core cursor association API for retrieving rows in key order
positioned at a given row.  All the fuctions here are located
in \ref lib_rdm. Linker option:\
 <pre><code>    -l<tt><a href="lib_rdm.html">rdmrdm</a></tt></code></pre>  See \ref cursor for a more detailed
description of a cursor.

Function Documentation

rdm_cursorGetRowsByKeyAtPosition()

RDM_RETCODE rdm_cursorGetRowsByKeyAtPosition	(	RDM_CURSOR	sourceCursor,
RDM_KEY_ID	keyId,
RDM_CURSOR *	pCursor
)

#include <rdmcursorapi.h>

Associate an RDM_CURSOR with a row set based on a key and positioned to the same row as the source cursor.

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 the specified key column is in. The cursor will be positioned to the current row of sourceCursor.

If sourceCursor is not at a row that is a valid row of the specified key an error will be returned and cursor will not be associated.

sourceCursor can be any type of RDM_CURSOR as long as the current row of sourceCursor is a valid row for the specified key.

Cursor Association Rules

If pCursor points to NULL then a new cursor will be allocated and associated with the same RDM_DB as sourceCursor.
If pCursor points to an RDM_CURSOR that has been allocated, but not associated with an RDM_DB then the RDM_CURSOR will be associated with the same RDM_DB as sourceCursor.
If pCursor points to an RDM_CURSOR that is associated with an RDM_DB other than the RDM_DB associated with sourceCursor 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 the sourceCursor

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.
eNOCURRENTROW	The cursor is not positioned to a valid row.
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_cursorGetMemberRows; rdm_cursorGetOwnerRow; rdm_cursorGetRowsAtPosition; rdm_cursorGetRowsInReverseOrder; rdm_cursorGetSelf; rdm_cursorGetSiblingRows; rdm_cursorGetClone; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_cursorLinkRow

Parameters

[in]	sourceCursor	[in] The cursor whose current row will be used for the resulting cursor position
[in]	keyId	[in] The RDM key id
[out]	pCursor	[out] A pointer to an RDM_CURSOR (must be allocated, associated with db, or set to NULL)