DbTxn::discard()

#include <db_cxx.h>
 
int
DbTxn::discard(u_int32_t flags);

The DbTxn::discard() method frees up all the per-process resources associated with the specified DbTxn handle, neither committing nor aborting the transaction. This call may be used only after calls to DbEnv::txn_recover() when there are multiple global transaction managers recovering transactions in a single Berkeley DB environment. Any transactions returned by DbEnv::txn_recover() that are not handled by the current global transaction manager should be discarded using DbTxn::discard().

All open cursors in the transaction are closed and the first cursor close error, if any, is returned.

The DbTxn::discard() 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 errors values that this method returns include the error values of Dbc::close() and the following:

DbDeadlockException or DB_LOCK_DEADLOCK

A transactional database environment operation was selected to resolve a deadlock.

DbDeadlockException is thrown if your Berkeley DB API is configured to throw exceptions. Otherwise, DB_LOCK_DEADLOCK is returned.

DbLockNotGrantedException or DB_LOCK_NOTGRANTED

A Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable to grant a lock in the allowed time.

DbLockNotGrantedException is thrown if your Berkeley DB API is configured to throw exceptions. Otherwise, DB_LOCK_NOTGRANTED is returned.

EINVAL

If the cursor is already closed; or if an invalid flag value or parameter was specified.

After DbTxn::discard() has been called, regardless of its return, the DbTxn handle may not be accessed again.

Parameters

flags

The flags parameter is currently unused, and must be set to 0.

Errors

The DbTxn::discard() method may fail and throw a DbException exception, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

EINVAL

If the transaction handle does not refer to a transaction that was recovered into a prepared but not yet completed state; or if an invalid flag value or parameter was specified.

Class

DbEnv, DbTxn

See Also

Transaction Subsystem and Related Methods