DbEnv::txn_begin |
#include <db_cxx.h>int DbEnv::txn_begin(DbTxn *parent, DbTxn **tid, u_int32_t flags);
The DbEnv::txn_begin method creates a new transaction in the environment and copies a pointer to a DbTxn that uniquely identifies it into the memory to which tid refers. Calling the DbTxn::abort, DbTxn::commit or DbTxn::discard methods will discard the returned handle.
If the parent argument is non-NULL, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level. In the presence of distributed transactions and two-phase commit, only the parental transaction, that is a transaction without a parent specified, should be passed as an argument to DbTxn::prepare.
The flags value must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
This behavior may be set for a Berkeley DB environment using the DbEnv::set_flags interface. Any value specified in this interface overrides that setting.
This behavior is the default for Berkeley DB environments unless the DB_TXN_NOSYNC flag was specified to the DbEnv::set_flags interface. Any value specified in this interface overrides that setting.
Note: A transaction may not span threads; that is, each transaction must begin and end in the same thread, and each transaction may be used only by a single thread.
Note: Cursors may not span transactions; that is, each cursor must be opened and closed within a single transaction.
Note: A parent transaction may not issue any Berkeley DB operations -- except for DbEnv::txn_begin, DbTxn::abort and DbTxn::commit -- while it has active child transactions (child transactions that have not yet been committed or aborted).
The DbEnv::txn_begin method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.
The DbEnv::txn_begin method may fail and throw an exception or return a non-zero error for the following conditions:
The DbEnv::txn_begin method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods. If a catastrophic error has occurred, the DbEnv::txn_begin method may fail and either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail in the same way.