# DbTxnMgr

           import com.sleepycat.db.*;

           public static DbTxnMgr open(String dir, int flags, int mode, DbEnv dbenv)
                throws DbException;

           public DbTxn begin(DbTxn pid)
                throws DbException;

           public void checkpoint(int kbyte, int min)
                throws DbException;

           public void close()
                throws DbException;

           public static void unlink(String dir, int force, DbEnv dbenv)
                throws DbException;

           public DbTxnStat stat()
                throws DbException;

## 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  returns  a  transaction  region
           identified by the directory dir.

           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.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.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''.   Threading is assumed in the Java
                API,  so  no  special  flags  are  required,  and  DB
                functions will always behave as if the DB_THREAD flag
                was specified.

           Db.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:

           DbErrcall db_errcall;
           String db_errpfx;
           int db_verbose;
                The error fields of the DbEnv behave as described for
                DbEnv(3).  void *(*db_errcall)(char *db_errpfx,  char
                *buffer);

           FILE *db_errfile;
           const char *db_errpfx;
           int db_verbose;
                The  error  fields  of the DB_ENV behave as described
                for db_appinit(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.

           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.

           The DbTxnMgr.open  method  throws  a  DbException(3)  that
           encapsulates an errno on failure.

      DbTxnMgr.begin
           The DbTxnMgr.begin method creates a new transaction in the
           transaction manager, and returns  a  DbTxn  that  uniquely
           identifies  it.   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) that
           encapsulates an errno on failure.

      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) that
           encapsulates an errno on failure.

      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) that
           encapsulates an errno on failure.

      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)
           that encapsulates an errno on failure,  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  DbTxnStat   object   encapsulating   a
           statistical structure.

           The   transaction   region  statistics  are  stored  in  a
           DbTxnStat object.  The following methods are available  on
           DbTxnStat:

           DbLsn get_st_last_ckp();
                The LSN of the last checkpoint.
           DbLsn get_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.
           int get_st_time_ckp();
                The  time  the last completed checkpoint finished (as
                returned by time(2)).
           int get_st_last_txnid();
                The last transaction ID allocated.
           int get_st_maxtxns();
                The maximum number of active  transactions  supported
                by the region.
           int get_st_naborts();
                The number of transactions that have aborted.
           int get_st_nactive();
                The number of transactions that are currently active.
           int get_st_nbegins();
                The number of transactions that have begun.
           int get_st_ncommits();
                The number of transactions that have committed.
           st_region_wait get_();
                The number of times that  a  thread  of  control  was
                forced to wait before obtaining the region lock.
           st_region_nowait get_();
                The number of times that a thread of control was able
                to obtain the region lock without waiting.

## 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

           The  DbTxnMgr.open   method   may   fail   and   throw   a
           DbException(3)  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) encapsulating an 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) 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) encapsulating an 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) 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)  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)  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) encapsulating an 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) 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_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), Dbt(3), DbTxn(3), DbTxnMgr(3)