Initialization functions for the core database API. All the fuctions here are located in RDM DB Engine Library. Linker option: More...
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. 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
Initialization functions for the core database API. All the fuctions here are located in RDM DB Engine Library. Linker option:
-lrdmrdmFunction 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.
- 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 [in] A valid RDM database handle
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.
- 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 [in] A valid RDM database handle
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_EXCLUSIVE | The database is opened in exclusive mode |
| 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 [in] A valid RDM database handle [in] tableId [in] The table identifier [out] status [out] 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_INITIALIZE | A database initialization transaction is active |
| RDM_TRANS_SNAPSHOT | A snapshot is active |
| RDM_TRANS_NONE | There is no transaction active |
| RDM_TRANS_UNKNOWN | Unknown transaction status |
- 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 [in] A valid RDM database handle [out] status [out] The current transaction status for the database handle
rdm_dbPrecommit()
| RDM_RETCODE rdm_dbPrecommit | ( | RDM_DB | db | ) |
#include <rdmdbapi.h>
Precommit a transactional operation.
rdm_dbPrecommit() 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 [in] 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.
- 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 [in] A valid RDM database handle [in] tableIds [in] array of table identifiers [in] numTableIds [in] The number of elements in tableIds [out] pTrans [out] An optional transaction handle
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 snapshot 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 visible 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.
- See also
- Transactions and Locking
- 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 [in] A valid RDM database handle [in] tableIds [in] array of table identifiers [in] numTableIds [in] The number of elements in tableIds [out] pTrans [out] optional transaction handle
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 be 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.
- 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 [in] A valid RDM database handle [in] writeTableIds [in] array of table identifiers [in] numWriteTableIds [in] The number of elements in writeTableIds [in] readTableIds [in] array of table identifiers [in] numReadTableIds [in] The number of elements in readTableIds [out] pTrans [out] An optional transaction handle