Collaboration diagram for RDM Transaction APIs:

Functions

RDM_RETCODE rdm_transEnd (RDM_TRANS trans)
End a transactional operation. More...
RDM_RETCODE rdm_transEndRollback (RDM_TRANS trans)
End a transactional operation with a rollback. More...
RDM_RETCODE rdm_transFree (RDM_TRANS hTrans)
Free a transaction handle. More...
RDM_RETCODE rdm_transPrecommit (RDM_TRANS trans)
Precommit a transactional operation (Two-Phase Commit phase 1) More...
RDM_RETCODE rdm_transRollback (RDM_TRANS hTrans)
Rollback transactional operations. More...

Detailed Description

See Transactions and Locking for a more detailed description.

The core database transaction API. These functions are located in RDM DB Engine Library. Linker option:

    -lrdmrdm

A transaction handle can be instantiated using rdm_dbStartUpdate, rdm_dbStartRead, or rdm_dbStartSnapshot.

Function Documentation

rdm_transEnd()

RDM_RETCODE rdm_transEnd ( RDM_TRANS trans )

#include <rdmtransapi.h>

End a transactional operation.

rdm_transEnd() will process a transaction point. If the transaction point is the root then the transaction will be committed and the changes made a part of the database. If the transaction point is not the root then the transaction point and any subsequent transaction points will be deleted. If a handle to subsequent transaction points was kept it should be discarded as the used of an invalided transaction handle is undefined.

Any read locks that were granted when or after the specified transaction point was created will be freed.

See Transactions and Locking for a more detailed description.

Return values
sOKAY Normal, successful return.
See also
rdm_dbStartUpdate
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbEnd
rdm_transFree
Parameters
[in] trans A valid RDM transaction handle
Examples
core13Example_main.c, core28Example_main.c, core29Example_main.c, core30Example_main.c, and cpp50Example_main.cpp.

rdm_transEndRollback()

RDM_RETCODE rdm_transEndRollback ( RDM_TRANS trans )

#include <rdmtransapi.h>

End a transactional operation with a rollback.

rdm_dbEndRollback() will rollback an update transaction up to the specified transaction point. If the transaction point is the root then the transaction will be aborted and all locks will be freed. If the transaction point is not the root then the transaction point and any subsequent transaction points will be invalidated. If a handle to subsequent transaction points was kept it should be discarded as the used of an invalided transaction handle is undefined.

See Transactions and Locking for a more detailed description.

Return values
sOKAY Normal, successful return.
eNOUPDATE Transaction handle does not refer to an update transaction.
See also
rdm_dbStartUpdate
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_transPrecommit
rdm_transRollback
rdm_dbEndRollback
rdm_transFree
Parameters
[in] trans A valid RDM transaction handle
Examples
cpp50Example_main.cpp.

rdm_transFree()

RDM_RETCODE rdm_transFree ( RDM_TRANS hTrans )

#include <rdmtransapi.h>

Free a transaction handle.

rdm_transFree() will free a hTrans without freeing any of the locks associated with the transaction point. If the specified transaction is a root transaction then the only way to end (commit/rollback) the transaction will be to use the rdm_dbEnd() or rdm_dbEndRollback() APIs. No transaction handle prior or subsequent to hTrans will be affected.

See Transactions and Locking for a more detailed description.

Return values
sOKAY Normal, successful return.
See also
rdm_dbStartUpdate
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_transEnd
rdm_transEndRollback
Parameters
[in] hTrans A valid RDM transaction handle

rdm_transPrecommit()

RDM_RETCODE rdm_transPrecommit ( RDM_TRANS trans )

#include <rdmtransapi.h>

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

rdm_transPrecommit() 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 for the specified transaction. The transaction must be a root transaction for a database and not a transaction mark point. 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_transPrecommit() prior to rdm_dbEnd() or rdm_transEnd() is that all file I/O necessary to prepare the transaction will be done during the precommit, and all rdm_dbEnd() or rdm_transEnd() has left to do is a minimal task, essentially flipping a switch to commit the prepared transaction.

Note
This call does not change the status of locks, so a database should not be held in this state indefinitely.
Return values
sOKAY Normal, successful return.
See also
rdm_dbStartUpdate
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_dbPrecommit
rdm_transEnd
rdm_transEndRollback
Parameters
[in] trans A valid RDM transaction handle

rdm_transRollback()

RDM_RETCODE rdm_transRollback ( RDM_TRANS hTrans )

#include <rdmtransapi.h>

Rollback transactional operations.

rdm_transRollback() will rollback an update transaction up to the specified transaction point. All changes made to the database will be reverted, but any locks granted when the hTrans was started will remain. Locks that were granted to any transactions nested from hTrans will be freed. If a handle to subsequent transaction points was kept it should be discarded as the used of an invalided transaction handle is undefined.

hTrans will remain and updates can continue to be applied to it.

See Transactions and Locking for a more detailed description.

Return values
sOKAY Normal, successful return.
eNOUPDATE Transaction handle does not refer to an update transaction.
See also
rdm_dbStartUpdate
rdm_dbStartRead
rdm_dbStartSnapshot
rdm_transEndRollback
Parameters
[in] hTrans A valid RDM transaction handle