Modules | Functions
Locking and Transaction Start Functions
RDM C API Reference » RDM Database APIs
Collaboration diagram for Locking and Transaction Start Functions:

Modules
RDM 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_dbPrecommit (RDM_DB db)
Precommit a transactional operation (Two-Phase Commit phase 1) 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 RDM 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_dbEndRollback
rdm_dbPrecommit
rdm_transEnd
rdm_dbClose
Parameters
[in] db A valid RDM 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, core14Example_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, core28Example_main.c, core29Example_main.c, core30Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core34Example_main.c, core35Example_main.c, 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.

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 RDM 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, core14Example_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, 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 RDM 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 RDM database handle
[out] status The current transaction status for the database handle

rdm_dbPrecommit()

RDM_RETCODE rdm_dbPrecommit ( RDM_DB db )

#include <rdmdbapi.h>

Precommit a transactional operation (Two-Phase Commit phase 1)

rdm_dbPrecommit() performs phase one of a two-phase commit. The function prepares to commit a transaction by writing to the database log file all changes made since the latest root transaction for the database was started. Soon after this call, rdm_dbEnd(), rdm_transEnd(), rdm_dbEndRollback() or rdm_transEndRollback() should be called to finally commit or rollback the transaction. The difference between calling rdm_dbPrecommit() prior to rdm_dbEnd() is that all file I/O necessary to prepare the transaction will be done during the precommit, and all rdm_dbEnd() / rdm_transEnd() has left to do is a minimal task, essentially flipping a switch to commit the prepared transaction.

This call does not change the status of locks, so a database should not be held in this state indefinitely.

Locking Requirements
None.
Return values
sOKAY Normal, successful return.
eDBNOTOPEN Database not open.
eNOSTARTUPDATE An update operation was attempted when no rdm_dbStartUpdate() is active.
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

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 RDM 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, core14Example_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, core28Example_main.c, core29Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core35Example_main.c, cpp50Example_main.cpp, cpp55Example_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.

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 RDM database handle
[in] tableIds array of table identifiers
[in] numTableIds The number of elements in tableIds
[out] pTrans optional transaction handle
Examples
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_dbEnd
rdm_dbEndRollback
rdm_transEnd
rdm_transEndRollback
Parameters
[in] db A valid RDM 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, core14Example_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, core28Example_main.c, core29Example_main.c, core30Example_main.c, core31Example_main.c, core32Example_main.c, core33Example_main.c, core34Example_main.c, core35Example_main.c, cpp50Example_main.cpp, 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.