#include <db_cxx.h>

static int
DbTxnMgr::open(const char *dir,
    u_int32_t flags, int mode, DbEnv *dbenv, DbTxnMgr **regionp);

Description

The dir pathname argument is interpreted as described in Berkeley DB File Naming.

The flags and mode arguments specify how files will be opened and/or created if they do not already exist. The flags value is specified by logically 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 m4_reg(DbTxnMgr) handle returned by DbTxnMgr::open 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 for more information) 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 Berkeley DB.

The transaction subsystem is configured based on the dbenv argument. It is expected that applications will use a single DbEnv object as the argument to all of the subsystems in the Berkeley DB package. The fields of the DbEnv object used by DbTxnMgr::open are described below. References to the DbEnv object are maintained by Berkeley DB, so it is necessary that the 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::appinit.

DbLog *lg_info;

The logging region that is being used for this transaction environment. The lg_info field contains a return value from the DbLog::open method. 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 DbLockTab::open method. 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 (DB_LSN *).

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 tx_recover is NULL, the default is that only Berkeley DB access method operations are transaction protected, and the default recover method will be used.

The DbTxnMgr::open method either returns errno or throws an exception that encapsulates an errno on failure, and 0 on success.

Environment Variables

DB_HOME

If the dbenv argument to DbTxnMgr::open was initialized using DbEnv::appinit the environment variable DB_HOME may be used as the path of the database home for the interpretation of the dir argument.

TMPDIR

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

Errors

The DbTxnMgr::open method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: abort(3), close(3), DbEnv::version, fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), getenv(3), getpid(3), getuid(3), isdigit(3), lseek(3), malloc(3), memcpy(3), memset(3), mmap(3), munmap(3), open(3), pstat_getdynamic(3), read(3), shmat(3), shmctl(3), shmdt(3), sigfillset(3), sigprocmask(3), stat(3), strerror(3), strlen(3), sysconf(3), time(3), DbTxnMgr::unlink, unlink(3), vfprintf(3), vsnprintf(3), and write(3).

In addition, the DbTxnMgr::open method may fail and throw an exception or return errno for the following conditions:

EAGAIN

The shared memory region was locked and (repeatedly) unavailable.

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.

Class

See Also