The Cursor base class. More...

#include "cpp-cursor.h"

Public Member Functions
	Cursor (void) throw ()
	Cursor Default Constructor. More...

	Cursor (const Cursor &cursor) throw ()
	Cursor Copy Constructor. More...

Cursor &	operator= (const Cursor &cursor) throw ()
	Cursor assignment operator. More...

	~Cursor ()
	Cursor Destructor. More...

RDM_TABLE_ID	GetTableId (void) const
	Get the id for the table the cursor is based on. More...

RDM_RETCODE	GetReturnCode (void) const
	Get the current info status value. More...

uint64_t	GetCount (void) const
	Get a count of the number of rows contained in a cursor collection. More...

RDM_LOCK_STATUS	GetLockStatus (void) const
	Get a current lock status of the table a cursor is based on. More...

Cursor	DeleteRow (void) const
	Delete the row at the current cursor position. More...

Cursor	UnlinkAndDeleteRow (void) const
	Disconnect and Delete the row at the current cursor position. More...

const Cursor &	MoveToFirst (void) const
	Navigate to the first row in the Cursor collection. More...

const Cursor &	MoveToNext (void) const
	Navigate to the next row in the Cursor collection. More...

const Cursor &	MoveToPrev (void) const
	Navigate to the previous row in the Cursor collection. More...

const Cursor &	MoveToLast (void) const
	Navigate to the last row in the Cursor collection. More...

const Cursor &	operator++ (void) const
	Prefix increment operator. More...

const Cursor &	operator-- (void) const
	Prefix decrement operator. More...

Cursor	GetRows (void) const
	Obtain a Cursor for the current table ordered by rowId. More...

Cursor	GetSelf (void) const
	Obtain a singleton Cursor for the source cursor's current row. More...

Cursor	GetClone (void) const
	Clone a cursor. More...

bool	IsBeforeFirst (void) const
	Check to see if the Cursor in the the BeforeFirst position. More...

void	MoveToBeforeFirst (void) const
	Position the cursor to BeforeFirst. More...

bool	IsAfterLast (void) const
	Check to see if the Cursor in the the AfterLast position. More...

void	MoveToAfterLast (void) const
	Position the cursor to AfterLast. More...

RDM_CURSOR_STATUS	GetStatus (void) const
	Check to see where the cursor is positioned. More...

bool	IsBefore (const Cursor &cursor) const
	Check to see if passed in cursor is positioned before the source cursor's current position. More...

bool	IsBeforeAt (const Cursor &cursor) const
	Check to see if passed in cursor is positioned before or at the source cursor's current position. More...

bool	IsAt (const Cursor &cursor) const
	Check to see if passed in cursor is positioned at the same row as the source cursor. More...

bool	IsAfterAt (const Cursor &cursor) const
	Check to see if passed in cursor is positioned after or at the source cursor's current position. More...

bool	IsAfter (const Cursor &cursor) const
	Check to see if passed in cursor is positioned after the source cursor's current position. More...

bool	IsNotAt (const Cursor &cursor) const
	Check to see if passed in cursor is positioned to a different row than the source cursor. More...

bool	operator< (const Cursor &cursor) const
	Less than operator. More...

bool	operator<= (const Cursor &cursor) const
	Less than or equal to operator. More...

bool	operator== (const Cursor &cursor) const
	Equal to operator. More...

bool	operator>= (const Cursor &cursor) const
	Greater than or equal to operator. More...

bool	operator> (const Cursor &cursor) const
	Greater than operator. More...

bool	operator!= (const Cursor &cursor) const
	Not equal to operator. More...

Db	GetDb (void)
	Get the Db object associated with the Cursor. More...

RDM_ROWID_T	GetRowId () const
	Get the rowid of Cursor's current row. More...

void	GetRowStatus (RDM_ROW_STATUS_INFO &rowStat) const
	Get the row status information of a status cursor. More...

void	MoveToRowId (const RDM_ROWID_T rowId) const
	Position a cursor to a particular row by database address. More...

void	AddMember (const Cursor &member) const
	Add a new member to a set cursor. More...

void	RemoveMember (void) const
	Remove the current row from a set cursor. More...

Cursor &	Release (void)

Static Public Member Functions
static RDM_TABLE_ID	NoMoreTables (void) throw ()
	Mark the end of an array of table ids. More...

static Cursor	GetBeforeFirst (void) throw ()
	Obtain the static BeforeFirst Cursor. More...

static Cursor	GetAfterLast (void) throw ()
	Obtain the static AfterLast Cursor. More...

Friends
class	Db

Detailed Description

The Cursor base class.

This Cursor class provides the base cursor implementation.

This is a class with very little overhead - a single pointer - that is a 'smart pointer' (i.e. will automatically get destroyed when the last reference is removed).

Constructor & Destructor Documentation

Cursor() [1/2]

RDM_CPP::Cursor::Cursor	(	void	)
throw	(
	)

Cursor Default Constructor.

The default constructor, copy constructor, assignment operator, and destructor implement a smart pointer for the Cursor interface and it's generated subclasses. The number of references to the underlying implementation object will be maintained. When the number of references to an implementation object is down to zero the object will be released.

The default constructor will initialize the number of references to the underlying implementation object to one.

Cursor() [2/2]

RDM_CPP::Cursor::Cursor	(	const Cursor &	cursor	)
throw	(
	)

Cursor Copy Constructor.

The default constructor, copy constructor, assignment operator, and destructor implement a smart pointer for the Cursor interface and it's generated subclasses. The number of references to the underlying implementation object will be maintained. When the number of references to an implementation object is down to zero the object will be released.

The copy constructor will increment the number of references to the underlying implementation object by one.

~Cursor()

RDM_CPP::Cursor::~Cursor ( )

Cursor Destructor.

The default constructor, copy constructor, assignment operator, and destructor implement a smart pointer for the Cursor interface and it's generated subclasses. The number of references to the underlying implementation object will be maintained. When the number of references to an implementation object is down to zero the object will be released.

The destructor will decrement the number of references to the underlying implementation object by one.

Member Function Documentation

AddMember()

void RDM_CPP::Cursor::AddMember ( const Cursor & member ) const

Add a new member to a set cursor.

This method will add a new member row to a set cursor. The passed in cursor must be positioned to a row that is a valid member of the set the source cursor is based on. The current row of the passed in cursor will be added as a member of the set the source cursor is based on and will be associated to the current owner row of the source cursor.

An exception will be thrown if the source cursor is not a set cursor or if the member cursor is not positioned to a valid member row.

Locking Requirements: An Update transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOCURRENTROW, eNOTLOCKED, eNOSTARTUPDATE)

Parameters

member A cursor positioned to a row that is a valid member for the set the source Cursor is based on

DeleteRow()

Cursor RDM_CPP::Cursor::DeleteRow ( void ) const

Delete the row at the current cursor position.

This method removes the current row of cursor from the database.

After the row has been removed the cursor will no longer have a current row as it has been removed from the database. However it will maintain a virtual position which be the position between the rows neighboring the row that was deleted. The neighboring rows are dependent upon on the type of the source cursor.

Returns: The Cursor you are using

Locking Requirements: An Update transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOCURRENTROW, eNOSTARTUPDATE, eNOTLOCKED)

GetAfterLast()

static Cursor RDM_CPP::Cursor::GetAfterLast	(	void	)
throw	(
	)

static

Obtain the static AfterLast Cursor.

The AfterLast cursor can be used in the comparison methods. The AfterLast cursor is positioned at the AfterLast position and it's position can not be changed.

Returns: A singleton Cursor at the AfterLast position

Locking Requirements: None

GetBeforeFirst()

static Cursor RDM_CPP::Cursor::GetBeforeFirst	(	void	)
throw	(
	)

static

Obtain the static BeforeFirst Cursor.

The BeforeFirst cursor can be used in the comparison methods. The BeforeFirst cursor is positioned at the BeforeFirst position and it's position can not be changed.

Returns: A singleton Cursor at the BeforeFirst position

Locking Requirements: None

GetClone()

Cursor RDM_CPP::Cursor::GetClone ( void ) const

inline

Clone a cursor.

This method crates a cursor as a clone of the source cursor. The resulting cursor will be of the same type, contain the same rows, and will have the same position and current row as the source cursor.

This is method will be intentionally hidden by the generated class derived for a specific database.

Returns: A Cursor that is an exact clone of the source cursor

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP)

 {
return this->_GetClone ();
 };

GetCount()

uint64_t RDM_CPP::Cursor::GetCount ( void ) const

Get a count of the number of rows contained in a cursor collection.

Returns: The number of rows contained in the cursor collection

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eNOTLOCKED)

GetDb()

Db RDM_CPP::Cursor::GetDb ( void )

Get the Db object associated with the Cursor.

Each active cursor is associated with a Db object. This method allows a user to get a reference to the Db object associated with the source Cursor.

Returns: The Db object associated with this Cursor

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP)

GetLockStatus()

RDM_LOCK_STATUS RDM_CPP::Cursor::GetLockStatus ( void ) const

Get a current lock status of the table a cursor is based on.

This method returns the current lock status for the table the cursor is based on. The lock status on specifies if the cursor currently has access to the table, it does not check if the table is locked by other sessions.

Returns: A RDM_LOCK_STATUS value

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP)

GetReturnCode()

RDM_RETCODE RDM_CPP::Cursor::GetReturnCode ( void ) const

Get the current info status value.

The Cursor object does not throw exceptions for status codes. This function allows you to get the return code from the last method call. If the previous method call did not throw and exception this will either be sOKAY or a status code value. If the previous method call did throw an exception this will be the error code related to that exception.

Returns: A RDM_RETCODE value

GetRowId()

RDM_ROWID_T RDM_CPP::Cursor::GetRowId ( ) const

Get the rowid of Cursor's current row.

This method returns the database address of the current row for the Cursor.

If the cursor is not at a valid row a rdm_exception will be thrown.

Returns: The database address of the row

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOCURRENTROW, eNOMEMORY, eNOTLOCKED)

GetRows()

Cursor RDM_CPP::Cursor::GetRows ( void ) const

Obtain a Cursor for the current table ordered by rowId.

Create a new TableScan Cursor of rows of the same type as the current row of the source cursor. Position the new cursor to the same row as the source cursor is positioned to.

Returns: A Cursor positioned to the same row the Cursor is positioned to

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eNOMEMORY)

GetRowStatus()

void RDM_CPP::Cursor::GetRowStatus ( RDM_ROW_STATUS_INFO & rowStat ) const

Get the row status information of a status cursor.

This retrieves returns the RDM_ROW_STATUS_INFO for a status cursor. A status cursor can be retrieved from a bulk insert operation.

If the cursor is not at a valid entry a rdm_exception will be thrown.

Locking Requirements: None

Exceptions

rdm_exception (eINVCURSOROP, eNOCURRENTROW)

GetSelf()

Cursor RDM_CPP::Cursor::GetSelf ( void ) const

inline

Obtain a singleton Cursor for the source cursor's current row.

Create a new singleton cursor positioned to the same row as the source cursor.

If the source cursor is not at a valid row then a /ref rdm_exception will be thrown.

Returns: A singleton Cursor positioned at the row the source Cursor is positioned to

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eNOMEMORY, eOWNERDELETED, eSINGLETONDELETED, eNOCURRENTROW)

 {
return this->_GetSelf ();
 };

GetStatus()

RDM_CURSOR_STATUS RDM_CPP::Cursor::GetStatus ( void ) const

Check to see where the cursor is positioned.

This function will return information about special conditions for a cursor's position. See RDM_CURSOR_STATUS for possible cursor status definitions.

As you navigate (using MoveToNext(), MoveToPrev(), MoveToFirst(), MoveToLast(), MoveToBeforeFirst(), MoveToAfterLast(), or any of the Find* functions), use InsertRow(), or create a cursor using any of the Db class Get methods the cursor will be in any of these states CURSOR_AT_ROW, CURSOR_BETWEEN, or CURSOR_BEFORE_FIRST. Changes to the row through this cursor or any other cursor may put the cursor in some other state. Clone will make an exact copy with the exact same state, position, and current row.

Returns: A RDM_CURSOR_STATUS value

Locking Requirements: None.

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

GetTableId()

RDM_TABLE_ID RDM_CPP::Cursor::GetTableId ( void ) const

Get the id for the table the cursor is based on.

Returns: The table identifier

IsAfter()

bool RDM_CPP::Cursor::IsAfter ( const Cursor & cursor ) const

Check to see if passed in cursor is positioned after the source cursor's current position.

This method compares the current position of source cursor relative to secondary (passed in) cursor and will return TRUE if the position for the primary cursor is after the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondar cursor is positioned after the source cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

Referenced by operator>().

Here is the caller graph for this function:

IsAfterAt()

bool RDM_CPP::Cursor::IsAfterAt ( const Cursor & cursor ) const

Check to see if passed in cursor is positioned after or at the source cursor's current position.

This method compares the current position of source cursor relative to secondary (passed in) cursor and will return TRUE if the position for the primary cursor is at or after the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor is positioned after or at the source cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

Referenced by operator>=().

Here is the caller graph for this function:

IsAfterLast()

bool RDM_CPP::Cursor::IsAfterLast ( void ) const

Check to see if the Cursor in the the AfterLast position.

Return values

true	If the current cursor position is after the last row in the collection
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED)

IsAt()

bool RDM_CPP::Cursor::IsAt ( const Cursor & cursor ) const

Check to see if passed in cursor is positioned at the same row as the source cursor.

This method compares the current position of source cursor relative to secondary (passed in) cursor and will return TRUE if the position for the primary cursor is at the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor is positioned to the same row as the source cursor
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

Referenced by operator==().

Here is the caller graph for this function:

IsBefore()

bool RDM_CPP::Cursor::IsBefore ( const Cursor & cursor ) const

Check to see if passed in cursor is positioned before the source cursor's current position.

This method compares the current position of source cursor relative to secondary (passed in) cursor and will return TRUE if the position for the primary cursor is before the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor's position is before the source cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

Referenced by operator<().

Here is the caller graph for this function:

IsBeforeAt()

bool RDM_CPP::Cursor::IsBeforeAt ( const Cursor & cursor ) const

Check to see if passed in cursor is positioned before or at the source cursor's current position.

This method compares the current position of source cursor relative to secondary (passed in) cursor and will return TRUE if the position for the primary cursor is before or at the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor's position is before or at the source cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

Referenced by operator<=().

Here is the caller graph for this function:

IsBeforeFirst()

bool RDM_CPP::Cursor::IsBeforeFirst ( void ) const

Check to see if the Cursor in the the BeforeFirst position.

Return values

true	If the current cursor position is before the first row in the collection
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED)

IsNotAt()

bool RDM_CPP::Cursor::IsNotAt ( const Cursor & cursor ) const

Check to see if passed in cursor is positioned to a different row than the source cursor.

This method compares the current position of source cursor relative to secondary (passed in) cursor and will return TRUE if the position for the primary cursor is not at the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor is positioned to a different row than the source cursor.
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

Referenced by operator!=().

Here is the caller graph for this function:

MoveToAfterLast()

void RDM_CPP::Cursor::MoveToAfterLast ( void ) const

Position the cursor to AfterLast.

Position the cursor to the special AfterLast position.

Navigating to the previous position from this special position will position the cursor to the last row in the cursor collection. Navigating forward will throw a /ref rdm_exception with the eINVITERATION error code.

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED)

MoveToBeforeFirst()

void RDM_CPP::Cursor::MoveToBeforeFirst ( void ) const

Position the cursor to BeforeFirst.

Position the cursor to the special BeforeFirst position.

Navigating to the previous position from this special position will position the cursor to the last row in the cursor collection. Navigating forward will throw a /ref rdm_exception with the eINVITERATION error code.

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED)

MoveToFirst()

const Cursor& RDM_CPP::Cursor::MoveToFirst ( void ) const

inline

Navigate to the first row in the Cursor collection.

This method 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.

There is a type specific version of this method in all generated subclasses.

Returns: The Cursor you are using

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTLOCKED)

 {
return this->_MoveToFirst ();
 };

MoveToLast()

const Cursor& RDM_CPP::Cursor::MoveToLast ( void ) const

inline

Navigate to the last row in the Cursor collection.

This method 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.

There is a type specific version of this method in all generated subclasses.

Returns: The Cursor you are using

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTLOCKED)

 {
return this->_MoveToLast ();
 };

MoveToNext()

const Cursor& RDM_CPP::Cursor::MoveToNext ( void ) const

inline

Navigate to the next row in the Cursor collection.

This method will position a cursor to the next row in the collection.

If the cursor was positioned to the last row in the collection then the cursor will be positioned to AfterLast.

If cursor was positioned to AfterLast then the function will throw a /ref rdm_exception with the eINVITERATION error code.

There is a type specific version of this method in all generated subclasses.

Returns: The Cursor you are using

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTLOCKED)

 {
return this->_MoveToNext ();
 };

Referenced by operator++().

Here is the caller graph for this function:

MoveToPrev()

const Cursor& RDM_CPP::Cursor::MoveToPrev ( void ) const

inline

Navigate to the previous row in the Cursor collection.

This method will position a cursor to the previous row in the collection.

If the cursor was positioned to the first row in the collection then the cursor will be positioned to BeforeFirst.

If the cursor was positioned to BeforeFirst then the function will throw /ref rdm_exception with the eINVITERATION error code.

Returns: The Cursor you are using

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTLOCKED)

 {
return this->_MoveToPrev ();
 };

Referenced by operator--().

Here is the caller graph for this function:

MoveToRowId()

void RDM_CPP::Cursor::MoveToRowId ( const RDM_ROWID_T rowId ) const

Position a cursor to a particular row by database address.

This method will position a cursor to the row at database address specified by rowid. The cursor can be any type of cursor and does not need to be a row scan cursor.

If there is no exact match found then:

If the cursor is a row scan cursor and rowid is in the file that row is stored in then the function will return sNOTFOUND and the cursor will be placed in the CURSOR_BETWEEN position. Navigating forward (next) from that position will position the cursor at the next rowid larger than the specified rowid. Navigating backward (prev) from that position will position the cursor at the next rowid smaller than the specified rowid.
Otherwise the function will throw a /ref rdm_exception with the eNOTINCURSOR error code and the cursor position will be left unchanged.

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] rowId The id of the row the Cursor is to be positioned to

NoMoreTables()

static RDM_TABLE_ID RDM_CPP::Cursor::NoMoreTables	(	void	)
throw	(
	)

inlinestatic

Mark the end of an array of table ids.

Use this when setting up an array of table ids passed in to StartRead() or StartUpdate().

See also: Transactions and Locking

Locking Requirements: None

Returns: A table id end marker

 {
return (RDM_TABLE_ID) 0;
 }

operator!=()

bool RDM_CPP::Cursor::operator!= ( const Cursor & cursor ) const

inline

Not equal to operator.

This operator compares the current position of primary (left-most) cursor relative to secondary (right-most) cursor and will return TRUE if the position for the primary cursor is not at the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor's position is not the same as the primary cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

 {
return IsNotAt (cursor);
 }

References IsNotAt().

Here is the call graph for this function:

operator++()

const Cursor& RDM_CPP::Cursor::operator++ ( void ) const

inline

Prefix increment operator.

This method 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.

If cursor was positioned to AfterLast then the method will throw a /ref rdm_exception with the error code eINVITERATION.

Returns: The Cursor you are using (positioned to the next row)

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTLOCKED, eINVITERATION)

 {
return MoveToNext ();
 }

References MoveToNext().

Here is the call graph for this function:

operator--()

const Cursor& RDM_CPP::Cursor::operator-- ( void ) const

inline

Prefix decrement operator.

This method 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.

If cursor was positioned to BeforeFirst then the method will throw a /ref rdm_exception with the error code eINVITERATION.

Returns: The source Cursor you are using (positioned to the previous row)

Locking Requirements: A Snapshot transaction or a Read transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTLOCKED, eINVITERATION)

 {
return MoveToPrev ();
 }

References MoveToPrev().

Here is the call graph for this function:

operator<()

bool RDM_CPP::Cursor::operator< ( const Cursor & cursor ) const

inline

Less than operator.

This operator compares the current position of primary (left-most) cursor relative to secondary (right-most) cursor and will return TRUE if the position for the primary cursor is before the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor's position is before the primary cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED, eNOTINCURSOR)

Parameters

[in] cursor The Cursor to compare against

 {
return IsBefore (cursor);
 }

References IsBefore().

Here is the call graph for this function:

operator<=()

bool RDM_CPP::Cursor::operator<= ( const Cursor & cursor ) const

inline

Less than or equal to operator.

This operator compares the current position of primary (left-most) cursor relative to secondary (right-most) cursor and will return TRUE if the position for the primary cursor is before or at the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor's position is before or at the primary cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

 {
return IsBeforeAt (cursor);
 }

References IsBeforeAt().

Here is the call graph for this function:

operator=()

Cursor& RDM_CPP::Cursor::operator=	(	const Cursor &	cursor	)
throw	(
	)

Cursor assignment operator.

The default constructor, copy constructor, assignment operator, and destructor implement a smart pointer for the Cursor interface and it's generated subclasses. The number of references to the underlying implementation object will be maintained. When the number of references to an implementation object is down to zero the object will be released.

The assignment will increment the number of references to the underlying implementation object by one for the new reference.

operator==()

bool RDM_CPP::Cursor::operator== ( const Cursor & cursor ) const

inline

Equal to operator.

This operator compares the current position of primary (left-most) cursor relative to secondary (right-most) cursor and will return TRUE if the position for the primary cursor is at the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor's position is at the primary cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

 {
return IsAt (cursor);
 }

References IsAt().

Here is the call graph for this function:

operator>()

bool RDM_CPP::Cursor::operator> ( const Cursor & cursor ) const

inline

Greater than operator.

This operator compares the current position of primary (left-most) cursor relative to secondary (right-most) cursor and will return TRUE if the position for the primary cursor is after the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor's position is after the primary cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

 {
return IsAfter (cursor);
 }

References IsAfter().

Here is the call graph for this function:

operator>=()

bool RDM_CPP::Cursor::operator>= ( const Cursor & cursor ) const

inline

Greater than or equal to operator.

This operator compares the current position of primary (left-most) cursor relative to secondary (right-most) cursor and will return TRUE if the position for the primary cursor is after or at the position of the secondary cursor.

If the cursor types are not the same the current row of the secondary cursor will be used and then converted to a position in the cursor type of source cursor. If the current row of the secondary cursor is not a valid cursor position in the source a /ref rdm_exception will be thrown.

This more specifically means:

If the source cursor is a key cursor the comparison will be based on key value.
If the source cursor is a row cursor the comparison will be based the rowId
If the source cursor is a set member cursor the comparison will be based on the order in the set chain
If the source cursor is a singleton cursor the comparison is only valid if the secondary cursor and the source cursor are the same row (there is no order for a singleton)

If the row at the current position of the secondary cursor is not in the collection of the source cursor a /ref rdm_exception will be thrown.

There are two distinct types of errors for the /ref rdm_exception when the row in the secondary cursor is not found in the collection of the source cursor:

If rows in cursor_secondary can never be in the collection of the source cursor based on the schema information (it is a different table or from another database) then eNOTRELATED will be the error code in the /ref rdm_exception.
If the row in the secondary cursor could be found in the collection for the source cursor but is not (it has a different set owner) then eNOTINCURSOR will be the error code in the /ref rdm_exception.

If the secondary cursor is in a special position (BeforeFirst/AfterLast) then the cursors must be of the same type to have a meaningful comparison (both key cursors based on the same key, both set cursors with the same owner, etc.). If that is not the case a /ref rdm_exception with the eNOTINCURSOR error code is thrown.

Return values

true	If the secondary cursor's position is after or at the primary cursor's current position
false	Otherwise

Locking Requirements: None

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOTRELATED)

Parameters

[in] cursor The Cursor to compare against

 {
return IsAfterAt (cursor);
 }

References IsAfterAt().

Here is the call graph for this function:

Release()

Cursor& RDM_CPP::Cursor::Release ( void )

RemoveMember()

void RDM_CPP::Cursor::RemoveMember ( void ) const

Remove the current row from a set cursor.

This function disconnects the current row of the source cursor from the set associated with the cursor. The source cursor must be based on a set (obtained from a call to a GetMember* method).

The source cursor will maintain the original current row and position even though the current row is no longer in the set. Calling next/prev will position the cursor relative to the original position.

Locking Requirements: An Update transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOCURRENTROW, eNOTLOCKED, eNOSTARTUPDATE, eNOTLINKED)

UnlinkAndDeleteRow()

Cursor RDM_CPP::Cursor::UnlinkAndDeleteRow ( void ) const

Disconnect and Delete the row at the current cursor position.

This method disconnects the current row of cursor from all sets and removes it from the database.

After the row has been removed the cursor will no longer have a current row as it has been removed from the database. However it will maintain a virtual position which be the position between the rows neighboring the row that was deleted. The neighboring rows are dependent upon on the type of the source cursor.

Returns: The Cursor you are using

Locking Requirements: An Update transaction with locks on the relevant cursor row(s)

Exceptions

rdm_exception (ePRECOMMITTED, eINVCURSOROP, eOWNERDELETED, eSINGLETONDELETED, eNOCURRENTROW, eNOSTARTUPDATE, eNOTLOCKED)

Friends And Related Function Documentation

Db

friend class Db

friend

The documentation for this class was generated from the following file:

cpp-cursor.h

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Cursor() [1/2]

Cursor() [2/2]

~Cursor()

Member Function Documentation

AddMember()

DeleteRow()

GetAfterLast()

GetBeforeFirst()

GetClone()

GetCount()

GetDb()

GetLockStatus()

GetReturnCode()

GetRowId()

GetRows()

GetRowStatus()

GetSelf()

GetStatus()

GetTableId()

IsAfter()

IsAfterAt()

IsAfterLast()

IsAt()

IsBefore()

IsBeforeAt()

IsBeforeFirst()

IsNotAt()

MoveToAfterLast()

MoveToBeforeFirst()

MoveToFirst()

MoveToLast()

MoveToNext()

MoveToPrev()

MoveToRowId()

NoMoreTables()

operator!=()

operator++()

operator--()

operator<()

operator<=()

operator=()

operator==()

operator>()

operator>=()

Release()

RemoveMember()

UnlinkAndDeleteRow()

Friends And Related Function Documentation

Db