+I*Berkeley DB: DbTxnMgr::open[P

DbTxnMgr::open





#include <db_cxx.h>

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





Description

The DbTxnMgr::openWmethod copies a pointer, to the "transaction region" identified by the directoryBdir, into the memory location referenced by regionp.

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

KThe flags and mode arguments specify how files will be opened,and/or created if they do not already exist.SThe flags value is specified by logically OR'ing together one or more of thefollowing values:

[

DB_CREATE
Create any underlying files, as necessary. If the files do not alreadyBexist 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 befree-threaded.R

DB_TXN_NOSYNC
On transaction commit, do not synchronously flush the log.HThis means that transactions exhibit the ACI (atomicity, consistency andGisolation) properties, but not D (durability), i.e., database integrityBwill be maintained but it is possible that some number of the mostHrecently committed transactions may be undone during recovery instead of being redone.

FThe number of transactions that are potentially at risk is governed bylhow often the log is checkpointed (see db_checkpoint for moreCinformation) 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 describedHin chmod(2)) and modified by the process' umask value at the time$of creation (see umask(2)))).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

'The transaction subsystem is configuredEbased on the dbenv argument. It is expected that applicationsiwill use a single DbEnv object as the argument to all of thessubsystems in the Berkeley DB package. The fields of the DbEnv object+used by DbTxnMgr::open are described below.pReferences to the DbEnv object are maintained by Berkeley DB, so itDis necessary that the object and memory it references be valid untilthe object is destroyed.mAny of the DbEnv fields that are not explicitly set will defaultto appropriate values.

oThe 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;
y
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.yThe lg_info field contains a return value from the DbLog::open method.4Logging is required for transaction environments,7and 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.AIf 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.FThis bounds the size of backing files and is used to derive limits for)the size of the lock region and logfiles.HWhen 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.

Wint DbTxnMgr::recover(DbLog *logp, Dbt *DbLog::rec, DbLsn *lsnp, int redo, void *info);r
A method that is called by DbTxn::abort during transaction abort.!This method takes five arguments:
g

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

DbLog::rec
A log record.=

lsnp
A pointer to a log sequence number (DB_LSN *).K

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

DB_TXN_BACKWARD_ROLL
The log is being read backward to determine which transactions have beenJcommitted and which transactions were not (and should therefore be abortedduring recovery).c

DB_TXN_FORWARD_ROLL
The log is being played forward, any transaction ids encountered that1have not been entered into the list referenced byinfo should be ignored.d

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

DB_TXN_REDO
Redo the operation described by the log record.E

DB_TXN_UNDO
Undo the operation described by the log record.
Z

info
An opaque pointer used to reference the list of transaction IDs encounteredduring recovery.


PIf tx_recover is NULL, the default is that only Berkeley DB access methodDoperations 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



V

DB_HOME
If the dbenv argument to DbTxnMgr::open was initialized usingiDbEnv::appinit the environment variable DB_HOME mayBbe used as the path of the database home for the interpretation ofthe dir argument.


[

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




Errors

UIf a fatal error occurs in Berkeley DB, the DbTxnMgr::open method may fail and eitherIreturn DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,Gat which point all subsequent database calls will also fail in the sameFway. Methods marked as returning errno will, by default, throwHan exception that encapsulates the error information. The default error\behavior can be changed, see DbException.

The DbTxnMgr::open&method may fail and throw an exceptionKfor any of the errors specified for the following Berkeley DB and C librarya functions: abort(3),i close(3),e>DbEnv::version, fcntl(3),p fflush(3), fprintf(3),efree(3), fstat(3),e fsync(3),A getenv(3), getpid(3), getuid(3), isdigit(3),t lseek(3),w malloc(3), memcpy(3), memset(3),mmap(3), munmap(3),open(3),pstat_getdynamic(3),read(3), shmat(3),i shmctl(3), shmdt(3),dsigfillset(3),sigprocmask(3),/stat(3), strerror(3), strlen(3), sysconf(3),atime(3),BDbTxnMgr::unlink, unlink(3), vfprintf(3), vsnprintf(3), and, write(3).D

*In addition, the DbTxnMgr::openr&method may fail and throw an exceptionor return errnofor the following conditions:i

R

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

EINVAL
An invalid flag value or parameter was specified.

hFThe DB_THREAD flag was specified and spinlocks are not implemented forthis architecture.

/$The dbenv parameter was NULL.



/

Class

8DbTxnMgr

a

See Also

o@DbTxnMgr::begin,JDbTxnMgr::checkpoint,@DbTxnMgr::close,DbTxnMgr::open,t=DbTxnMgr::stataandhBDbTxnMgr::unlink.
idaingle address space, i.e., to befree-threaded.R

DB_TXN_NOSYNC
On transaction commit, do not synchronously flush the log.HThis means that transactions exhibit the ACI (atomicity, consistency andGisolation) properties, but not D (durability), i.e., database integrityBwill be maintained but it is possible that some number of the mostHrecently committ