Collaboration diagram for Locking and Transaction Start Functions:

Modules
	RaimaDB Transaction APIs

Functions
RDM_RETCODE	rdm_dbEnd (RDM_DB db)
	End a transactional operation. More...

RDM_RETCODE	rdm_dbEndRollback (RDM_DB db)
	End and rollback a transactional operation. More...

RDM_RETCODE	rdm_dbGetLockStatus (RDM_DB db, RDM_TABLE_ID tableId, RDM_LOCK_STATUS *status)
	Get the RDM_DB handle's current lock status of a table. More...

RDM_RETCODE	rdm_dbGetTransactionStatus (RDM_DB db, RDM_TRANS_STATUS *status)
	Get the transaction status for a database handle. More...

RDM_RETCODE	rdm_dbStartRead (RDM_DB db, const RDM_TABLE_ID tableIds, uint32_t numTableIds, RDM_TRANS pTrans)
	Get read locks. More...

RDM_RETCODE	rdm_dbStartSnapshot (RDM_DB db, const RDM_TABLE_ID tableIds, uint32_t numTableIds, RDM_TRANS pTrans)
	Start a snapshot. More...

RDM_RETCODE	rdm_dbStartUpdate (RDM_DB db, const RDM_TABLE_ID writeTableIds, uint32_t numWriteTableIds, const RDM_TABLE_ID readTableIds, uint32_t numReadTableIds, RDM_TRANS *pTrans)
	Get write locks. More...

Detailed Description

Locking and Transaction functions for the core database API. All the functions here are located in RaimaDB DB Engine Library. Linker option:

    -lrdmrdm

Function Documentation

rdm_dbEnd()

RDM_RETCODE rdm_dbEnd ( RDM_DB db )

#include <rdmdbapi.h>

End a transactional operation.

rdm_dbEnd() will commit a transactional operation for the specified database. If any updates have been made to the database then those will be committed and all locks will be freed.

If a snapshot is active then it will be released.

If there are only read locks active they will be freed.

If there are any active transaction handles they will be invalidated and should not be used.

See Transactions and Locking for a more detailed description.

Locking Requirements: None

Return values

sOKAY Normal, successful return.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbEvictRowData; rdm_dbEvictKeyData; rdm_dbEndRollback; rdm_dbPrecommit; rdm_transEnd; rdm_dbClose

Parameters

[in] db A valid RaimaDB database handle

Examples: core01Example_main.c, core02Example_main.c, core03Example_main.c, core04Example_main.c, core05Example_main.c, core06Example_main.c, core07Example_main.c, core08Example_main.c, core09Example_main.c, core10Example_main.c, core11Example_main.c, core12Example_main.c, core13Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core19Example_main.c, core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, core24Example_main.c, core25Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core35Example_main.c, core36Example_main.c, core37Example_main.c, core38Example_main.c, cpp51example_main.cpp, cpp55Example_main.cpp, learn/bookStore_client.c, learn/bookStore_embed.c, learn/bookStore_vxWorks7.c, rtree/deleteZipcode.c, rtree/insertZipcode.c, rtree/retrieveAllZipcode.c, rtree/retrieveContainedZipcode.c, rtree/retrieveExactZipcode.c, rtree/retrieveOverlapZipcode.c, and rtree/updateZipcode.c.

rdm_dbEndRollback()

RDM_RETCODE rdm_dbEndRollback ( RDM_DB db )

#include <rdmdbapi.h>

End and rollback a transactional operation.

rdm_dbEndRollback() will end a transactional operation with a rollback for the specified database.

If any updates have been made to the database then those will be rolled back and all locks will be freed.

If a snapshot is active then it will be released.

If there are only read locks active they will be freed.

If there are any active transaction handles they will be invalidated and should not be used.

If an error has occured while processing the modifications in a transaction (sub or root) that transaction should be rolled back and not committed. Committing a transaction after encountering an error condition from an insert, update, or delete operation can result in database corruption, memory leaks, or undefined behavior.

See Transactions and Locking for a more detailed description.

Locking Requirements: None

Return values

sOKAY	Normal, successful return.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.

See also: rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbStartUpdate; rdm_dbPrecommit; rdm_dbEnd; rdm_dbClose

Parameters

[in] db A valid RaimaDB database handle

Examples: core01Example_main.c, core02Example_main.c, core03Example_main.c, core04Example_main.c, core05Example_main.c, core06Example_main.c, core07Example_main.c, core08Example_main.c, core09Example_main.c, core10Example_main.c, core11Example_main.c, core12Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core19Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core35Example_main.c, core36Example_main.c, core37Example_main.c, core38Example_main.c, cpp55Example_main.cpp, learn/bookStore_client.c, learn/bookStore_embed.c, learn/bookStore_vxWorks7.c, rtree/deleteZipcode.c, rtree/insertZipcode.c, and rtree/updateZipcode.c.

rdm_dbGetLockStatus()

RDM_RETCODE rdm_dbGetLockStatus	(	RDM_DB	db,
		RDM_TABLE_ID	tableId,
		RDM_LOCK_STATUS *	status
	)

#include <rdmdbapi.h>

Get the RDM_DB handle's current lock status of a table.

This function returns the current lock status of the specified table. If the specified RDM_DB handle does not have a lock on the table, then the status will be RDM_LOCK_FREE regardless of whether any other sessions have the table locked. This function allows the user to know if the specified RDM_DB handle (db) has access to the table.

Note: This function cannot be used to determine if another RDM_DB handle (e.g., another session) has the specified table locked.

RDM_LOCK_STATUS values that can be returned in status are:

Status	Description
RDM_LOCK_FREE	The table is not locked
RDM_LOCK_READ	The table is locked for reads
RDM_LOCK_WRITE	The table is locked for updates
RDM_LOCK_SNAPSHOT	The table has an active snapshot
RDM_LOCK_CATALOG	The database has the catalog write locked

Locking Requirements: None

Return values

sOKAY	Normal, successful return.
eDBNOTOPEN	Database not open.

See also: rdm_dbStartUpdate; rdm_dbStartRead; rdm_dbStartSnapshot; rdm_cursorGetLockStatus; rdm_dbGetTransactionStatus; rdm_dbEnd; rdm_transEnd

Parameters

[in]	db	A valid RaimaDB database handle
[in]	tableId	The table identifier
[out]	status	The current lock status for the specified table

rdm_dbGetTransactionStatus()

RDM_RETCODE rdm_dbGetTransactionStatus	(	RDM_DB	db,
		RDM_TRANS_STATUS *	status
	)

#include <rdmdbapi.h>

Get the transaction status for a database handle.

This function returns the current transaction status of the database handle.

RDM_TRANS_STATUS values that can be returned in status are:

Status	Description
RDM_TRANS_READ	A read transaction is active
RDM_TRANS_UPDATE	An update transaction is active
RDM_TRANS_SNAPSHOT	A snapshot is active
RDM_TRANS_NONE	There is no transaction active

Locking Requirements: None

Return values

sOKAY	Normal, successful return.
eDBNOTOPEN	Database not open.

See also: rdm_dbOpen; rdm_dbGetLockStatus; rdm_cursorGetLockStatus; rdm_dbGetTransactionStatus; rdm_dbStartUpdate; rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbGetRows; rdm_dbEnd; rdm_transEnd

Parameters

[in]	db	A valid RaimaDB database handle
[out]	status	The current transaction status for the database handle

rdm_dbStartRead()

RDM_RETCODE rdm_dbStartRead	(	RDM_DB	db,
		const RDM_TABLE_ID *	tableIds,
		uint32_t	numTableIds,
		RDM_TRANS *	pTrans
	)

#include <rdmdbapi.h>

Get read locks.

This function will obtain 'read' locks on the specified tables. The numTableIds parameter will specify how many table locks are being requested. The tableIds parameter is an array of the identifiers for the tables to lock. The pTrans parameter can optionally retrieve a handle which will allow rdm_transEnd() to commit or rdm_transEndRollback() to rollback a transaction to a particular point. In the case of read locks they can be freed inside the bounds of an update transaction. If you do not wish read locks to be freed inside of an update transaction then you should request the read locks when starting the update transaction with rdm_dbStartUpdate().

Note: It is illegal to request locks if there is a database snapshot active for the current user.; You can lock all tables by using the special RDM_LOCK_ALL tableIds pointer.

You can stack calls to rdm_dbStartRead() and rdm_dbStartUpdate(). Doing so will create transaction marks (if a transaction handle pTrans parameter is provided) and potentially request additional locks. An update transaction will not be committed (or aborted) until the root update transaction has been committed/rolled back. This can be done by calling rdm_transEnd() or rdm_transEndRollback() with the root RDM_TRANS handle.

If you stack calls to rdm_dbStartRead() or rdm_dbStartUpdate() and get a transaction handle (pTrans) the transaction handle you receive will be invalidated if a transaction handle that was obtained prior is involved in a call to rdm_transEnd(), rdm_transEndRollback() or rdm_transRollback(). In addition, a call to rdm_dbEnd() or rdm_dbEndRollback() will invalidate any existing transaction handles. The results of using an invalid transaction handle are undefined.

A simple use case for reading rows from a table will not use nesting. It will get all of the locks upfront with a single call to rdm_dbStartRead() and free the locks with a call to rdm_dbEnd(). In this simple use case there will be no need to use a transaction handle.

See Transactions and Locking for a more detailed description.

Locking Requirements: None

Return values

sOKAY	Normal, successful return.
eDBNOTOPEN	Database not open.
eUNAVAIL	Requested resource not available.
sSCHEMACHANGE	A schema change was detected but the current operation succeeded.
eSNAPSHOTACTIVE	Snapshot is active.

See also: rdm_dbOpen; rdm_dbGetLockStatus; rdm_cursorGetLockStatus; rdm_dbGetTransactionStatus; rdm_dbStartUpdate; rdm_dbStartSnapshot; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbEnd; rdm_transEnd

Parameters

[in]	db	A valid RaimaDB database handle
[in]	tableIds	array of table identifiers
[in]	numTableIds	The number of elements in tableIds
[out]	pTrans	An optional transaction handle

Examples: core01Example_main.c, core02Example_main.c, core03Example_main.c, core04Example_main.c, core05Example_main.c, core06Example_main.c, core07Example_main.c, core08Example_main.c, core09Example_main.c, core10Example_main.c, core11Example_main.c, core13Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core19Example_main.c, core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core35Example_main.c, core36Example_main.c, core37Example_main.c, core38Example_main.c, cpp50Example_main.cpp, cpp51example_main.cpp, cpp55Example_main.cpp, cpp70Example_main.cpp, learn/bookStore_client.c, learn/bookStore_embed.c, learn/bookStore_vxWorks7.c, rtree/retrieveAllZipcode.c, rtree/retrieveContainedZipcode.c, rtree/retrieveExactZipcode.c, and rtree/retrieveOverlapZipcode.c.

Referenced by RDM::DB::transaction< NEXT >::begin().

Here is the caller graph for this function:

rdm_dbStartSnapshot()

RDM_RETCODE rdm_dbStartSnapshot	(	RDM_DB	db,
		const RDM_TABLE_ID *	tableIds,
		uint32_t	numTableIds,
		RDM_TRANS *	pTrans
	)

#include <rdmdbapi.h>

Start a snapshot.

This function will start a shapshot of the tables referenced in tableIds. A snapshot is a static view of the requested tables at the time the snapshot is created. Any changes made to those tables will not be visibile until the snapshot is released.

The snapshot will remain in effect until a call to rdm_dbEnd() or a call to rdm_transEnd() with the RDM_TRANS handle for the snapshot is made.

Locking Requirements: None

Return values

sOKAY	Normal, successful return.
eDBNOTOPEN	Database not open.
eTRACTIVE	Transaction is active.
sSCHEMACHANGE	A schema change was detected but the current operation succeeded.
eSNAPSHOTACTIVE	Snapshot is active.

See also: rdm_dbOpen; rdm_dbGetLockStatus; rdm_cursorGetLockStatus; rdm_dbGetTransactionStatus; rdm_dbStartRead; rdm_dbStartUpdate; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbEnd; rdm_transEnd

Parameters

[in]	db	A valid RaimaDB database handle
[in]	tableIds	array of table identifiers
[in]	numTableIds	The number of elements in tableIds
[out]	pTrans	optional transaction handle

Examples: core38Example_main.c, cpp50Example_main.cpp, and cpp55Example_main.cpp.

rdm_dbStartUpdate()

RDM_RETCODE rdm_dbStartUpdate	(	RDM_DB	db,
		const RDM_TABLE_ID *	writeTableIds,
		uint32_t	numWriteTableIds,
		const RDM_TABLE_ID *	readTableIds,
		uint32_t	numReadTableIds,
		RDM_TRANS *	pTrans
	)

#include <rdmdbapi.h>

Get write locks.

This function will get 'write' and 'read' locks on the requested tables. The numWriteTableIds parameter will specify how many write table locks are being requested. The writeTableIds parameter is an array of the identifiers for the tables to write lock. The numReadTableIds parameter will specify how many read table locks are being requested. The readTableIds parameter is array of the identifiers for the tables to read lock. The pTrans parameter can optionally retrieve a handle which will allow rdm_transEnd() to commit or rdm_transEndRollback() to rollback a transaction to a particular point. In the case of read locks, they can be freed inside the bounds of an update transaction.

The first call to rdm_dbStartUpdate() will begin a root update transaction.

When that root transaction has been commited or rolled back the transaction will be completed. If a call to rdm_dbStartUpdate() or rdm_dbStartRead() is made while a transaction is already active a a transaction mark point will be created (if the pTrans parameter is specified). It is possible to rollback or commit to a transaction mark point, but changes will not be made a part of the database until the root transaction has been committed.

You can lock all tables by using the special RDM_LOCK_ALL tableIds pointer. You can lock no tables by using the special RDM_LOCK_NONE tableId pointer. You can also use a NULL pointer for the tableIds and a numLocks value of 0 to create a transaction mark point without locking any additional tables.

A shema change require a write lock on the schema which can be obtained by specifying the special RDM_LOCK_SCHEMA tableIds pointer to writeTableIds. This is a shorthand for a list of table identifiers with only TABLE_SCHEMA.

You can stack calls to rdm_dbStartRead() and rdm_dbStartUpdate(). Doing so will create transaction marks and potentially request additional locks. An update transaction will not be committed (or aborted) until the root update transaction has been committed/aborted. This can be done by explicitly ending with the root RDM_TRANS handle or by calling rdm_transEnd() with the root transaction or by calling rdm_dbEnd().

If you stack calls to rdm_dbStartRead() or rdm_dbStartUpdate() and get a transaction handle (pTrans) the transaction handle you receive will be invalidated if a transaction handle that was obtained prior is involved in a call to rdm_transEnd(), rdm_transEndRollback(), or rdm_transRollback(). In addition a call to rdm_dbEnd() or rdm_dbEndRollback() will invalidate any existing transaction handles. The results of using an invalided transaction handle are undefined.

Note: It is illegal to request locks if there is a database snapshot active for the current user.

A simple use case for updating rows from a table will not use nesting. It will get all of the locks upfront with a single call to rdm_dbStartUpdate() and commit the changes with a call to rdm_dbEnd(). In this simple use case there will be no need to use a transaction handle.

See Transactions and Locking for a more detailed description.

Locking Requirements: None.

Return values

sOKAY	Normal, successful return.
ePRECOMMITTED	A precommitted transaction must be committed or rolled back before further operations on this database are allowed.
eSNAPSHOTACTIVE	Snapshot is active.
eREADONLY	Database is read-only and cannot be updated.
eUNAVAIL	Requested resource not available.
sSCHEMACHANGE	A schema change was detected but the current operation succeeded.

See also: rdm_dbOpen; rdm_dbGetLockStatus; rdm_cursorGetLockStatus; rdm_dbGetTransactionStatus; rdm_dbStartRead; rdm_dbStartSnapshot; rdm_dbGetRows; rdm_cursorMoveToNext; rdm_dbInsertRow; rdm_cursorUpdateRow; rdm_cursorDeleteRow; rdm_dbAlterCatalog; rdm_cursorReadRow; rdm_cursorReadBlob; rdm_cursorReadColumn; rdm_cursorReadKey; rdm_dbEvictRowData; rdm_dbEvictKeyData; rdm_dbEnd; rdm_dbEndRollback; rdm_transEnd; rdm_transEndRollback

Parameters

[in]	db	A valid RaimaDB database handle
[in]	writeTableIds	array of table identifiers
[in]	numWriteTableIds	The number of elements in writeTableIds
[in]	readTableIds	array of table identifiers
[in]	numReadTableIds	The number of elements in readTableIds
[out]	pTrans	An optional transaction handle

Examples: core01Example_main.c, core02Example_main.c, core03Example_main.c, core04Example_main.c, core05Example_main.c, core06Example_main.c, core07Example_main.c, core08Example_main.c, core09Example_main.c, core10Example_main.c, core11Example_main.c, core12Example_main.c, core13Example_main.c, core15Example_main.c, core16Example_main.c, core17Example_main.c, core18Example_main.c, core19Example_main.c, core20Example_main.c, core21Example_main.c, core22Example_main.c, core23Example_main.c, core24Example_main.c, core25Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core35Example_main.c, core36Example_main.c, core37Example_main.c, core38Example_main.c, cpp50Example_main.cpp, cpp51example_main.cpp, cpp55Example_main.cpp, cpp70Example_main.cpp, learn/bookStore_client.c, learn/bookStore_embed.c, learn/bookStore_vxWorks7.c, rtree/deleteZipcode.c, rtree/insertZipcode.c, and rtree/updateZipcode.c.

Here is the caller graph for this function:

Modules

Functions

Detailed Description

Function Documentation

rdm_dbEnd()

rdm_dbEndRollback()

rdm_dbGetLockStatus()

rdm_dbGetTransactionStatus()

rdm_dbStartRead()

rdm_dbStartSnapshot()

rdm_dbStartUpdate()