#include <DbXml.hpp>

XmlTransaction XmlManager::createTransaction(DB_TXN *toAdopt)
XmlTransaction XmlManager::createTransaction(u_int32_t flags = 0)

The XmlManager::createTransaction method method creates a new XmlTransaction object. If a DB_TXN object is not provided to this method, then a new transaction is begun (a DB_TXN object is instantiated and DbEnv::txn_begin is called).

If transactions were not initialized when this XmlManager object was opened (that is, DB_INIT_TXN was not specified) then this method throws an exception.

• If a DB_TXN handle is passed to this method, the new XmlTransaction is simply another reference for the DB_TXN handle. In this case, if the XmlTransaction object is destroyed or goes out of scope before XmlTransaction::commit or XmlTransaction::abort are called, the state of the underlying transaction is left unchanged. This allows a transaction to be controlled external to its XmlTransaction object. If no DB_TXN is passed, and the XmlTransaction object is destroyed or goes out of scope, the transaction is implicitly aborted.

• The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
  DB_READ_COMMITTED
  • This operation will have degree 2 isolation. This provides for cursor stability but not repeatable reads. Data items which have been previously read by this transaction may be deleted or modified by other transactions before this transaction completes.
  DB_READ_UNCOMMITTED
  • This operation will support degree 1 isolation; that is, read operations may return data that has been modified by other transactions but which has not yet been committed. Silently ignored if the DB_READ_UNCOMMITTED flag was not specified when the underlying container was opened.
  DB_TXN_NOSYNC
  • Do not synchronously flush the log when this transaction commits or prepares. This means the transaction will exhibit the ACI (atomic, consistent, and isolated) properties, but not D (durable); that is, database integrity will be maintained but it is possible that this transaction may be undone during recovery.

    This behavior may be set for a Berkeley DB environment using the UNREF==dbenv_set_flags method. Any value specified to this method overrides that setting.

  DB_TXN_NOWAIT
  • If a lock is unavailable for any Berkeley DB operation performed in the context of this transaction, cause the operation to return DB_LOCK_DEADLOCK or throw an XmlException with DB error code DB_LOCK_DEADLOCK immediately instead of blocking on the lock.
  DB_TXN_SNAPSHOT
  • This transaction will execute with snapshot isolation. For containers with the DB_MULTIVERSION flag set, data values will be read as they are when the transaction begins, without taking read locks. Silently ignored for operations on databases with DB_MULTIVERSION not set on the underlying container (read locks are acquired).

    The error DB_LOCK_DEADLOCK will be returned from update operations if a snapshot transaction attempts to update data which was modified after the snapshot transaction read it.

  DB_TXN_SYNC
  • Synchronously flush the log when this transaction commits or prepares. This means the transaction will exhibit all of the ACID (atomic, consistent, isolated, and durable) properties.

    This behavior is the default for Berkeley DB environments unless the DB_TXN_NOSYNC flag was specified to the UNREF==dbenv_set_flags method. Any value specified to this method overrides that setting.

  
  

The XmlManager::createTransaction method may fail and throw XmlException, encapsulating one of the following non-zero errors:

• Cannot call XmlManager::createTransaction when transactions are not initialized

• XmlManager::createTransaction(DB_TXN*) requires a valid DB_TXN handle