Cursor Information Functions
Collaboration diagram for Cursor Information Functions:

Functions

RDM_RETCODE rdm_cursorGetCount (RDM_CURSOR cursor, uint64_t *count)
Get the row count for a cursor. More...
RDM_RETCODE rdm_cursorGetDatabase (RDM_CURSOR cursor, RDM_DB *pDb)
Get the RDM_DB handle associated with a cursor. More...
RDM_RETCODE rdm_cursorGetMemberCount (RDM_CURSOR cursor, RDM_REF_ID refId, uint64_t *memberCount)
Get the member count for a set owner row. More...
RDM_RETCODE rdm_cursorGetOwnerRowId (RDM_CURSOR cursor, RDM_REF_ID refId, RDM_ROWID_T *rowid)
Get the rowid of a set owner. More...
RDM_RETCODE rdm_cursorGetOwnerTableId (RDM_CURSOR cursor, RDM_REF_ID refId, RDM_TABLE_ID *tableId)
Get the table id for the refId owner for the current row of a cursor. More...
RDM_RETCODE rdm_cursorGetRowId (RDM_CURSOR cursor, RDM_ROWID_T *rowid)
Get the rowid for the current row of the cursor. More...
RDM_RETCODE rdm_cursorGetRowStatus (RDM_CURSOR cursor, RDM_ROW_STATUS_INFO *rowStat)
Get the row status information for a status cursor. More...
RDM_RETCODE rdm_cursorGetTableId (RDM_CURSOR cursor, RDM_TABLE_ID *tableId)
Get the table id for the current row of the cursor. More...
RDM_RETCODE rdm_cursorGetType (RDM_CURSOR cursor, RDM_CURSOR_TYPE *type)
Get the cursor type. More...
RDM_RETCODE rdm_cursorHasMembers (RDM_CURSOR cursor, RDM_REF_ID refId, RDM_BOOL_T *hasMembers)
Check to see if a row has members for the specified set. More...
RDM_RETCODE rdm_cursorHasOwner (RDM_CURSOR cursor, RDM_REF_ID refId, RDM_BOOL_T *hasOwner)
Check to see if a row is a member for the specified set. More...

Detailed Description

API for retrieving information for core cursors. 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_cursorGetCount()

RDM_RETCODE rdm_cursorGetCount ( RDM_CURSOR cursor,
uint64_t * count
)

#include <rdmcursorapi.h>

Get the row count for a cursor.

This function returns the row count for the specified cursor.

A singleton cursor has by definition only one row.

Locking Requirements
Read lock on the table associated with the cursor
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.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
Parameters
[in] cursor The cursor to get the record count of
[out] count A pointer to the returned record count
Examples
core28Example_main.c, core29Example_main.c, cpp55Example_main.cpp, and cursor/registerMembers.c.

rdm_cursorGetDatabase()

RDM_RETCODE rdm_cursorGetDatabase ( RDM_CURSOR cursor,
RDM_DB * pDb
)

#include <rdmcursorapi.h>

Get the RDM_DB handle associated with a cursor.

This function assigns the RDM_DB handle associated with an RDM_CURSOR to the pDb.

Locking Requirements
None
Return values
sOKAY Normal, successful return.
See also
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
Parameters
[in] cursor The cursor to get the database handle for
[out] pDb A pointer to an RDM_DB that will be assigned the db handle associated with cursor

rdm_cursorGetMemberCount()

RDM_RETCODE rdm_cursorGetMemberCount ( RDM_CURSOR cursor,
RDM_REF_ID refId,
uint64_t * memberCount
)

#include <rdmcursorapi.h>

Get the member count for a set owner row.

This function calculates the member count of the set identified by refId for the owner identified by the current row of cursor.

The current row of cursor must be a valid owner of refId.

Locking Requirements
Read lock on the member table and the owner table (cursor) associated with the set refId
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.
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_cursorGetSiblingRows
rdm_cursorGetSelf
rdm_cursorMoveToNext
Parameters
[in] cursor The cursor whose current row we will get the member count of
[in] refId The set identifier for the requesting count
[out] memberCount A pointer to the returned set member count
Examples
cursor/registerVoters.c.

rdm_cursorGetOwnerRowId()

RDM_RETCODE rdm_cursorGetOwnerRowId ( RDM_CURSOR cursor,
RDM_REF_ID refId,
RDM_ROWID_T * rowid
)

#include <rdmcursorapi.h>

Get the rowid of a set owner.

This function retrieves the rowid of the owning row of the refId set for the current record of cursor.

If the current row of cursor is not at a valid member of the set an error will be returned.

Locking Requirements
Read lock on the member table and the owner table associated with the set refId
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.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorGetOwnerRow
rdm_cursorGetOwnerTableId
Parameters
[in] cursor The cursor to get the owner rowid from
[in] refId The set identifier of the set to get the owner rowid of
[out] rowid A pointer to the returned rowid
Examples
cursor/initialize_get_find_TheKing.c.

rdm_cursorGetOwnerTableId()

RDM_RETCODE rdm_cursorGetOwnerTableId ( RDM_CURSOR cursor,
RDM_REF_ID refId,
RDM_TABLE_ID * tableId
)

#include <rdmcursorapi.h>

Get the table id for the refId owner for the current row of a cursor.

This function returns the table identifier of the refId owner for the row that is in the current position of cursor

If the current row of cursor is not at a valid member of the set an error will be returned.

Locking Requirements
Read lock on member table (cursor) and owner table associated with refId.
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_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorGetOwnerRow
rdm_cursorGetOwnerRowId
rdm_cursorGetTableId
Parameters
[in] cursor The cursor to get the table id for
[in] refId The set identifier
[out] tableId A pointer to the returned table id

rdm_cursorGetRowId()

RDM_RETCODE rdm_cursorGetRowId ( RDM_CURSOR cursor,
RDM_ROWID_T * rowid
)

#include <rdmcursorapi.h>

Get the rowid for the current row of the cursor.

This function retrieves the rowid for the current row of cursor. If the cursor is not at a valid row an error will be returned.

Locking Requirements
Read lock on the table associated with the cursor
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_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorGetOwnerRowId
Parameters
[in] cursor The cursor to get the rowid from
[out] rowid A pointer to the returned rowid value
Examples
cpp50Example_main.cpp, and cursor/initialize_get_find_TheKing.c.

rdm_cursorGetRowStatus()

RDM_RETCODE rdm_cursorGetRowStatus ( RDM_CURSOR cursor,
RDM_ROW_STATUS_INFO * rowStat
)

#include <rdmcursorapi.h>

Get the row status information for a status cursor.

This function retrieves the current row status information for a status cursor. A status cursor can be return from a bulk insert operation.

Locking Requirements
None
Return values
sOKAY Normal, successful return.
eDBNOTOPEN Database not open.
eNOCURRENTROW The cursor is not positioned to a valid row.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorGetStatus
Parameters
[in] cursor The cursor to get the rowid from
[out] rowStat A pointer to the row status value

rdm_cursorGetTableId()

RDM_RETCODE rdm_cursorGetTableId ( RDM_CURSOR cursor,
RDM_TABLE_ID * tableId
)

#include <rdmcursorapi.h>

Get the table id for the current row of the cursor.

This function returns the table identifier of the row that is in the current position of cursor

Locking Requirements
None
Return values
sOKAY Normal, successful return.
eDBNOTOPEN Database not open.
See also
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbStartUpdate
rdm_dbGetRows
rdm_cursorGetMemberRows
rdm_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
rdm_cursorGetOwnerTableId
Parameters
[in] cursor The cursor to get the table id for
[out] tableId A pointer to the returned table id
Examples
cursor/printMembers.c.

rdm_cursorGetType()

RDM_RETCODE rdm_cursorGetType ( RDM_CURSOR cursor,
RDM_CURSOR_TYPE * type
)

#include <rdmcursorapi.h>

Get the cursor type.

This function will return the type of cursor

Locking Requirements
None
Return values
sOKAY Normal, successful return.
See also
rdm_dbGetRows
rdm_dbGetRowsByKey
rdm_cursorGetMemberRows
rdm_cursorGetSelf
Parameters
[in] cursor The cursor to be freed
[out] type The type of the cursor

rdm_cursorHasMembers()

RDM_RETCODE rdm_cursorHasMembers ( RDM_CURSOR cursor,
RDM_REF_ID refId,
RDM_BOOL_T * hasMembers
)

#include <rdmcursorapi.h>

Check to see if a row has members for the specified set.

This function checks to see if current row of cursor is a referenced through the set identified by refId.

The cursor does not need to be a set cursor but its current row must be in a table that is a valid owner of the set identified by refId.

The hasMembers parameter is set to RDM_TRUE if the row has members, otherwise RDM_FALSE.

Locking Requirements
Read lock on the owner and member tables associated with the set refId
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_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
Parameters
[in] cursor The cursor to check set ownership status
[in] refId The set identifier for the request
[in] hasMembers A pointer to the referenced status

rdm_cursorHasOwner()

RDM_RETCODE rdm_cursorHasOwner ( RDM_CURSOR cursor,
RDM_REF_ID refId,
RDM_BOOL_T * hasOwner
)

#include <rdmcursorapi.h>

Check to see if a row is a member for the specified set.

This function checks to see if current row of cursor is an active set member (is linked to an owner) for the set identified by refId.

The cursor does not need to be a set cursor but its current row must be in a table that is a valid member of the set identified by refId.

The hasOwner parameter is set to RDM_TRUE if the record has an active owner, otherwise RDM_FALSE.

Locking Requirements
Read lock on the member table associated with the set refId
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_cursorGetSelf
rdm_cursorGetSiblingRows
rdm_cursorMoveToNext
Parameters
[in] cursor The cursor to check set ownership status
[in] refId The set identifier for the request
[in] hasOwner A pointer to the returned status
Examples
cursor/printChildrenNamesWithUnknownFather.c.