DbTxnMgr



NAME

       DbTxnMgr - Db transaction management


SYNOPSIS

       #include <db_cxx.h>

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

       int
       DbTxnMgr::begin(DbTxn *pid, DbTxn **tid);

       int
       DbTxnMgr::checkpoint(int kbyte, int 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 mod-
       ular programming interface to transactions and record-ori-
       ented  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 pack-
       age, see db_intro(3).

       This manual page describes the specific details of the  Db
       transaction  support.   The DbTxnMgr class is used in con-
       junction 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 DbM-
       pool(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 pro-
       vided 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).
       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  cre-
       ated in this directory.  This directory must already exist
       when 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  DbTxn-
            Mgr::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
       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 trans-
            action 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 trans-
            action 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  transac-
            tion environment.

       unsigned int 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 trans-
            action 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  fol-
                 lowing 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 trans-

                 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  transac-
       tion 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 pointer.
       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 con-
       currently, only  a  single  thread  may  call  the  DbTxn-
       Mgr::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
       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  transac-
       tion  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_recovery(1) or the
       DB_RECOVER 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 direc-
       tory 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  envi-
       ronment.

       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  mem-
       ory  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 writ-
       ten but that  DbMpool::sync  (3)  (see  DbMpool  (3))  was
       unable  to  write  immediately.   In this case, the DbTxn-
       Mgr::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 loca-
       tions.

       Statistical structures are created  in  allocated  memory.
       If  db_malloc  is  non-NULL,  it is called to allocate the

       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.
       DB_TXN_ACTIVE *st_txnarray;
            A  pointer  to  an  array of st_nactive DB_TXN_ACTIVE
            structures, describing the currently active  transac-
            tions.   The  following  fields  of the DB_TXN_ACTIVE
            structure (typedef'd in <db_cxx.h>)  will  be  filled
            in:


            u_int32_t txnid;
                 The   transaction   ID  as  returned  by  DbTxn-
                 Mgr::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 initial-
            ized  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  DbTxn-
            Mgr::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

       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 condi-
       tions:

       [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  DbExcep-
       tion(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  condi-
       tions:

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

       The DbTxnMgr::checkpoint method may fail and throw a DbEx-
       ception(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 DbExcep-
       tion(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 DbExcep-
       tion(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),
       The DbTxnMgr::stat method may fail and  throw  a  DbExcep-
       tion(3)  or  return  errno for any of the errors specified
       for the following DB and library functions: fcntl(2), and
       malloc(3).


SEE ALSO

       LIBTP:  Portable,  Modular  Transactions  for  UNIX, Margo
       Seltzer, Michael Olson, USENIX proceedings, Winter 1992.


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_jump(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)