DbTxnMgr(3db)

NAME

DbTxnMgr - Db transaction management

SYNOPSIS

#include <db2/db_cxx.h>
static int
DbTxnMgr::open(const char *dir,
u_int32_t flags, int mode, DbEnv *dbenv, DbTxnMgr **regionp);
int
DbTxnMgr::begin(DbTxn *pid, DbTxn **tid);
int
DbTxnMgr::checkpoint(u_int32_t kbyte, u_int32_t min) const;
int
DbTxnMgr::close();
static int
DbTxnMgr::unlink(const char *dir, int force, DbEnv *dbenv);
int
DbTxnMgr::stat(DB_TXN_STAT **statp, void *(*db_malloc)(size_t));

DESCRIPTION

The DB library is a family of classes that provides a modular programming interface to transactions and record-oriented file access. The library includes support for transactions, locking, logging and file page caching, as well as various indexed access methods. Many of the classes (e.g., the file page caching class) are useful independent of the other DB classes, although some classes are explicitly based on other classes (e.g., transactions and logging). For a general description of the DB package, see db_intro(3).

This manual page describes the specific details of the Db transaction support. The DbTxnMgr class is used in conjunction with DbTxn(3) to provide transaction semantics. Full transaction support is provided by a collection of modules that provide interfaces to the services required for transaction processing. These services are recovery (see DbLog(3)), concurrency control (see DbLock(3) and DbLockTab(3)), and the management of shared data (see DbMpool(3) and DbMpoolFile(3)). Transaction semantics can be applied to the access methods described in Db(3) through method call parameters.

The model intended for transactional use (and that is used by the access methods) is that write-ahead logging is provided by DbLog(3) to record both before- and after-image logging. Locking follows a two-phase protocol (i.e., all locks are released at transaction commit).

DbTxnMgr::open The DbTxnMgr::open method copies a pointer, to the transaction region identified by the directory dir, into the memory location referenced by regionp.

If the dbenv argument to DbTxnMgr::open was initialized using DbEnv::appinit, dir is interpreted as described by DbEnv(3).

Otherwise, if dir is not NULL, it is interpreted relative to the current working directory of the process. If dir is NULL, the following environment variables are checked in order: ``TMPDIR'', ``TEMP'', and ``TMP''. If one of them is set, transaction region files are created relative to the directory it specifies. If none of them are set, the first possible one of the following directories is used: /var/tmp, /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.

All files associated with the transaction region are created in this directory. This directory must already exist when DbTxnMgr::open is called. If the transaction region already exists, the process must have permission to read and write the existing files. If the transaction region does not already exist, it is optionally created and initialized.

The flags and mode arguments specify how files will be opened and/or created when they don't already exist. The flags value is specified by or'ing together one or more of the following values:

DB_CREATE: Create any underlying files, as necessary. If the files do not already exist and the DB_CREATE flag is not specified, the call will fail.

DB_THREAD: Cause the DbTxnMgr handle returned by the DbTxnMgr::open method to be useable by multiple threads within a single address space, i.e., to be ``free-threaded''.

DB_TXN_NOSYNC

On transaction commit, do not synchronously flush the log. This means that transactions exhibit the ACI (atomicity, consistency and isolation) properties, but not D (durability), i.e., database integrity will be maintained but it is possible that some number of the most recently committed transactions may be undone during recovery instead of being redone.

The number of transactions that are potentially at risk is governed by how often the log is checkpointed (see db_checkpoint(1)) and how many log updates can fit on a single log page.

All files created by the transaction subsystem are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)). The group ownership of created files is based on the system and directory defaults, and is not further specified by DB.

The transaction subsystem is configured based on which set methods have been used. It is expected that applications will use a single DbEnv object as the argument to all of the subsystems in the DB package. The fields of the DbEnv object used by DbTxnMgr::open are described below. As references to the DbEnv object may be maintained by DbTxnMgr::open, it is necessary that the DbEnv object and memory it references be valid until the object is destroyed. Any of the DbEnv fields that are not explicitly set will default to appropriate values.

The following fields in the DbEnv object may be initialized, using the appropriate set method, before calling DbTxnMgr::open:

void *(*db_errcall)(char *db_errpfx, char *buffer);

FILE *db_errfile;

const char *db_errpfx;

class ostream *db_error_stream;

int db_verbose;: The error fields of the DbEnv behave as described for DbEnv(3).

DbLog *lg_info;: The logging region that is being used for this transaction environment. The lg_info field contains a return value from the method DbLog::open. Logging is required for transaction environments, and it is an error to not specify a logging region.

DbLockTab *lk_info;: The locking region that is being used for this transaction environment. The lk_info field contains a return value from the method DbLockTab::open. If lk_info is NULL, no locking is done in this transaction environment.

u_int32_t tx_max;: The maximum number of simultaneous transactions that are supported. This bounds the size of backing files and is used to derive limits for the size of the lock region and logfiles. When there are more than tx_max concurrent transactions, calls to DbTxnMgr::begin may cause backing files to grow. If tx_max is 0, a default value is used.

int DbTxnMgr::recover(DbLog *logp, Dbt *DbLog::rec,

DbLsn *lsnp, int redo, void *info);
A method that is called by DbTxn::abort during transaction abort. This method takes five arguments:

logp: A pointer to the transaction log (DbLog *).

DbLog::rec: A log record.

lsnp: A pointer to a log sequence number (DbLsn *).

redo

An integer value that is set to one of the following values:

DB_TXN_BACKWARD_ROLL: The log is being read backward to determine which transactions have been committed and which transactions were not (and should therefore be aborted during recovery).

DB_TXN_FORWARD_ROLL: The log is being played forward, any transaction ids encountered that have not been entered into the list referenced by info should be ignored.

DB_TXN_OPENFILES: The log is being read to open all the files required to perform recovery.

DB_TXN_REDO: Redo the operation described by the log record.

DB_TXN_UNDO: Undo the operation described by the log record.

info: An opaque pointer used to reference the list of transaction IDs encountered during recovery.

: If recover is NULL, the default is that only Db access method operations are transaction protected, and the default recover method will be used.

The DbTxnMgr::open method throws a DbException(3) or returns the value of errno on failure and 0 on success.

DbTxnMgr::begin The DbTxnMgr::begin method creates a new transaction in the transaction manager, copying a pointer to a DbTxn that uniquely identifies it into the memory referenced by tid. If the pid argument is non-NULL, the new transaction is a nested transaction with the transaction indicated by pid as its parent.

Transactions may not span threads, i.e., each transaction must begin and end in the same thread, and each transaction may only be used by a single thread.

The DbTxnMgr::begin method throws a DbException(3) or returns the value of errno on failure and 0 on success.

DbTxnMgr::close The DbTxnMgr::close method detaches a process from the transaction environment specified by the DbTxnMgr object. All mapped regions are unmapped and any allocated resources are freed. Any uncommitted transactions are aborted.

In addition, if the dir argument to DbTxnMgr::open was NULL and dbenv was not initialized using DbEnv::appinit, all files created for this shared region will be removed, as if DbTxnMgr::unlink were called.

When multiple threads are using the DbTxnMgr handle concurrently, only a single thread may call the DbTxnMgr::close method.

The DbTxnMgr::close method throws a DbException(3) or returns the value of errno on failure and 0 on success.

DbTxnMgr::unlink The DbTxnMgr::unlink method destroys the transaction region identified by the directory dir, removing all files used to implement the transaction region. (The directory dir is not removed.) If there are processes that have called DbTxnMgr::open without calling DbTxnMgr::close (i.e., there are processes currently using the transaction region), DbTxnMgr::unlink will fail without further action, unless the force flag is set, in which case DbTxnMgr::unlink will attempt to remove the transaction region files regardless of any processes still using the transaction region.

The result of attempting to forcibly destroy the region when a process has the region open is unspecified. Processes using a shared memory region maintain an open file descriptor for it. On UNIX systems, the region removal should succeed and processes that have already joined the region should continue to run in the region without change, however processes attempting to join the transaction region will either fail or attempt to create a new region. On other systems, e.g., WNT, where the unlink(2) system call will fail if any process has an open file descriptor for the file, the region removal will fail.

In the case of catastrophic or system failure, database recovery must be performed (see db_recover(1) or the DB_RECOVER and DB_RECOVER_FATAL flags to DbEnv::appinit(3)). Alternatively, if recovery is not required because no database state is maintained across failures, it is possible to clean up a transaction region by removing all of the files in the directory specified to the DbTxnMgr::open method, as transaction region files are never created in any directory other than the one specified to DbTxnMgr::open. Note, however, that this has the potential to remove files created by the other DB subsystems in this database environment.

The DbTxnMgr::unlink method throws a DbException(3) or returns the value of errno on failure and 0 on success.

DbTxnMgr::checkpoint The DbTxnMgr::checkpoint method syncs the underlying memory pool, writes a checkpoint record to the log and then flushes the log.

If either kbyte or min is non-zero, the checkpoint is only done if more than min minutes have passed since the last checkpoint, or if more than kbyte kilobytes of log data have been written since the last checkpoint.

The DbTxnMgr::checkpoint method throws a DbException(3) or returns the value of errno on failure, 0 on success, and DB_INCOMPLETE if there were pages that needed to be written but that DbMpool::sync (3) (see DbMpool (3)) was unable to write immediately. In this case, the DbTxnMgr::checkpoint call should be retried.

The DbTxnMgr::checkpoint method is based on the C txn_checkpoint function, which is the underlying function used by the db_checkpoint(1) utility. See the source code for the db_checkpoint utility for an example of using txn_checkpoint in a UNIX environment.

DbTxnMgr::stat The DbTxnMgr::stat method creates a statistical structure and copies pointers to it into user-specified memory locations.

Statistical structures are created in allocated memory. If db_malloc is non-NULL, it is called to allocate the memory, otherwise, the library function malloc(3) is used. The function db_malloc must match the calling conventions of the malloc(3) library routine. Regardless, the caller is responsible for deallocating the returned memory. To deallocate the returned memory, free each returned memory pointer; pointers inside the memory do not need to be individually freed.

The transaction region statistics are stored in a structure of type DB_TXN_STAT (typedef'd in <db2/db_cxx.h>). The following DB_TXN_STAT fields will be filled in:

DbLsn st_last_ckp;: The LSN of the last checkpoint.

DbLsn st_pending_ckp;: The LSN of any checkpoint that is currently in progress. If st_pending_ckp is the same as st_last_ckp there is no checkpoint in progress.

time_t st_time_ckp;: The time the last completed checkpoint finished (as returned by time(2)).

u_int32_t st_last_txnid;: The last transaction ID allocated.

u_int32_t st_maxtxns;: The maximum number of active transactions supported by the region.

u_int32_t st_naborts;: The number of transactions that have aborted.

u_int32_t st_nactive;: The number of transactions that are currently active.

u_int32_t st_nbegins;: The number of transactions that have begun.

u_int32_t st_ncommits;: The number of transactions that have committed.

u_int32_t ;: The number of times that a thread of control was forced to wait before obtaining the region lock.

u_int32_t ;: The number of times that a thread of control was able to obtain the region lock without waiting.

DB_TXN_ACTIVE *st_txnarray;

A pointer to an array of st_nactive DB_TXN_ACTIVE structures, describing the currently active transactions. The following fields of the DB_TXN_ACTIVE structure (typedef'd in <db2/db_cxx.h>) will be filled in:

u_int32_t txnid;: The transaction ID as returned by DbTxnMgr::begin(3).

DbLsn lsn;: The LSN of the transaction-begin record.

ENVIRONMENT VARIABLES

The following environment variables affect the execution of db_txn:

DB_HOME: If the dbenv argument to DbTxnMgr::open was initialized using db_appinit, the environment variable DB_HOME may be used as the path of the database home for the interpretation of the dir argument to DbTxnMgr::open, as described in db_appinit(3).

TMPDIR: If the dbenv argument to DbTxnMgr::open was NULL or not initialized using db_appinit, the environment variable TMPDIR may be used as the directory in which to create the transaction region, as described in the DbTxnMgr::open section above.

ERRORS

Methods marked as returning errno will, by default, throw an exception that encapsulates the error information. The default error behavior can be changed, see DbException(3).

The DbTxnMgr::open method may fail and throw a DbException(3) or return errno for any of the errors specified for the following DB and library functions: DbTxnMgr::unlink(3), close(2), db_version(3), fcntl(2), fflush(3), lseek(2), malloc(3), memcpy(3), memset(3), mmap(2), munmap(2), open(2), sigfillset(3), sigprocmask(2), stat(2), strcpy(3), strdup(3), strerror(3), strlen(3), time(3), unlink(2), and write(2).

In addition, the DbTxnMgr::open method may fail and throw a DbException(3) or return errno for the following conditions:

[EINVAL]

An invalid flag value or parameter was specified.

The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.

The dbenv parameter was NULL.

[EAGAIN]: The shared memory region was locked and (repeatedly) unavailable.

The DbTxnMgr::begin method may fail and throw a DbException(3) or return errno for any of the errors specified for the following DB and library functions: DbLog::put(3), fcntl(2), fflush(3), lseek(2), malloc(3), memcpy(3), memset(3), mmap(2), munmap(2), strerror(3), and write(2).

In addition, the DbTxnMgr::begin method may fail and throw a DbException(3) or return errno for the following conditions:

[ENOSPC]: The maximum number of concurrent transactions has been reached.

The DbTxnMgr::checkpoint method may fail and throw a DbException(3) or return errno for any of the errors specified for the following DB and library functions: DbLog::compare(3), DbLog::put(3), DbMpool::sync(3), fcntl(2), fflush(3), malloc(3), memcpy(3), memset(3), strerror(3), and time(3).

[EINVAL]: An invalid flag value or parameter was specified.

The DbTxnMgr::close method may fail and throw a DbException(3) or return errno for any of the errors specified for the following DB and library functions: DbLog::flush(3), DbTxn::abort(3), close(2), fcntl(2), fflush(3), munmap(2), and strerror(3).

The DbTxnMgr::unlink method may fail and throw a DbException(3) or return errno for any of the errors specified for the following DB and library functions: close(2), fcntl(2), fflush(3), malloc(3), memcpy(3), memset(3), mmap(2), munmap(2), open(2), sigfillset(3), sigprocmask(2), stat(2), strcpy(3), strdup(3), strerror(3), strlen(3), and unlink(2).

In addition, the DbTxnMgr::unlink method may fail and throw a DbException(3) or return errno for the following conditions:

[EBUSY]: The shared memory region was in use and the force flag was not set.

The DbTxnMgr::stat method may fail and throw a DbException(3) or return errno for any of the errors specified for the following DB and library functions: fcntl(2), and malloc(3).

BUGS

Nested transactions are not yet implemented.

db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1), db_load(1), db_recover(1), db_stat(1), db_intro(3), db_internal(3), db_thread(3), Db(3), Dbc(3), DbEnv(3), DbException(3), DbInfo(3), DbLock(3), DbLockTab(3), DbLog(3), DbLsn(3), DbMpool(3), DbMpoolFile(3), Dbt(3), DbTxn(3), DbTxnMgr(3)