DbTxn



       import com.sleepycat.db.*;

       public void abort()
            throws DbException;

       public void commit()
            throws DbException;

       public int id()
            throws DbException;

       public void prepare()
            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   DbTxn  class  is  used  in
       conjunction  with  DbTxnMgr(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 the one that
       is  used  by  the  access  methods) is write-ahead logging
       provided by DbLog(3) to record  both  before-  and  after-
       images.   Locking  follows  a two-phase protocol, with all
       locks being released at transaction commit.

  DbTxn.prepare
       The DbTxn.prepare method initiates the beginning of a  two
       phase  commit.   In a distributed transaction environment,
       db can be used as a local transaction  manager.   In  this
       case,   the  distributed  transaction  manager  must  send
       prepare messages to each local manager.  The local manager
       must  then  issue a DbTxn.prepare and await its successful
       return before responding to  the  distributed  transaction
       manager.   Only  after the distributed transaction manager
       receives successful responses  from  all  of  its  prepare
       messages should it issue any commit messages.

       The  DbTxn.prepare  method  throws  a  DbException(3) that
       encapsulates an errno on failure.

  DbTxn.commit
       The DbTxn.commit method ends  the  transaction  associated
       with  the  DbTxn.   If  DB_TXN_NOSYNC was not specified, a
       commit log record is written and flushed to disk,  as  are
       all previously written log records.  If the transaction is
       nested, its locks are acquired by the parent  transaction,
       otherwise  its  locks are released.  Any applications that
       require strict two-phase  locking  must  not  release  any
       locks  explicitly,  leaving  them  all  to  be released by
       DbTxn.commit.

       The  DbTxn.commit  method  throws  a  DbException(3)  that
       encapsulates an errno on failure.

  DbTxn.abort
       The  DbTxn.abort  method causes an abnormal termination of
       the transaction.  The log  is  played  backwards  and  any
       necessary  recovery  operations  are initiated through the
       recover method specified to DbTxnMgr.open.  After recovery
       is  completed,  all  locks  held  by  the  transaction are
       acquired by the parent transaction in the case of a nested
       transaction  or  released  in  the  case  of  a non-nested
       transaction.    As   is   the   case   for   DbTxn.commit,
       applications  that require strict two phase locking should
       not explicitly release any locks.

       The  DbTxn.abort  method  throws  a  DbException(3)   that
       encapsulates an errno on failure.

  DbTxn.id
       The  DbTxn.id  method  returns  the  unique transaction id
       associated with the specified transaction.  Locking  calls
       made  on  behalf  of this transaction should use the value
       returned from DbTxn.id as  the  locker  parameter  to  the
       DbLockTab.get or DbLockTab.vec calls.


TRANSACTIONS

       Creating  transaction  protected applications using the Db
       access methods requires little system  customization.   In
       most   cases,  the  default  parameters  to  the  locking,
       logging, memory  pool,  and  transaction  subsystems  will
       suffice.    Applications   can   use   DbEnv.appinit  (see
       DbEnv(3)) to perform this initialization, or they  may  do
       it explicitly.

       Each  database  operation  (i.e.,  any  call  to  a method
       underlying the handles returned by Db.open  and  Db.cursor
       described  in  Db(3)) is normally performed on behalf of a
       unique locker.  If multiple calls on behalf  of  the  same
       locker are desired, then transactions must be used.

       Once  the  application  has  initialized the Db subsystems
       that it is  using,  it  may  open  the  Db  access  method
       databases.   For applications performing transactions, the
       databases must be opened after  subsystem  initialization,
       and  cannot  be opened as part of a transaction.  Once the
       databases are opened, the application can  group  sets  of
       operations   into   transactions,   by   surrounding   the
       operations   with    the    appropriate    DbTxnMgr.begin,
       DbTxn.commit and DbTxn.abort calls.  Databases accessed by
       a transaction must not be closed during  the  transaction.
       Note, it is not necessary to transaction protect read-only
       transactions, unless those transactions require repeatable
       reads.

       The Db access methods will make the appropriate calls into
       the lock, log and  memory  pool  subsystems  in  order  to
       guarantee  that  transaction  semantics are applied.  When
       the  application  is  ready  to  exit,   all   outstanding
       transactions  should  have  been committed or aborted.  At
       this point, all open Db files should be closed.  Once  the
       Db  database files are closed, the Db subsystems should be
       closed, either explicitly or by  destroying  the  DbEnv(3)
       object.

       It  is  also  possible  to  use  the  locking, logging and
       transaction  subsystems  of  Db  to  provide   transaction
       semantics  to objects other than those described by the Db
       access methods.  In these cases, the application will need
       more  explicit  customization of the subsystems as well as
       the  development  of  appropriate  data-structure-specific
       recovery functions.

       For   example,   consider  an  application  that  provides
       transaction semantics to data stored in plain  UNIX  files
       accessed using the read(2) and write(2) system calls.  The
       operations for which transaction protection is desired are
       bracketed by calls to DbTxnMgr.begin and DbTxn.commit.

       Before  data  are  referenced, the application must make a
       call to the lock manager, DbLock(3), for  a  lock  of  the
       appropriate  type (e.g., read) on the object being locked.
       The object might be a page in the file, a byte, a range of
       bytes, or some key.  It is up to the application to ensure
       that appropriate locks are acquired.  Before  a  write  is
       performed,  the application should acquire a write lock on
       the object, by making an  appropriate  call  to  the  lock
       manager,  DbLock(3).   Then, the application should make a
       call  to  the  log  manager,  DbLog,  to   record   enough
       information to redo the operation in case of failure after
       commit and to undo the operation in  case  of  abort.   As
       discussed  in the DbLog(3) manual page, the application is
       responsible for providing any necessary structure  to  the
       log  record.  For example, the application must understand
       what part of the log record is  an  operation  code,  what
       part identifies the file being modified, what part is redo
       information, and what part is undo information.

       After the log message  is  written,  the  application  may
       issue  the  write  system  call.   After  all requests are
       issued,  the  application  may  call  DbTxn.commit.   When
       DbTxn.commit  returns,  the  caller is guaranteed that all
       necessary log writes have been written to disk.

       At any time, the application may call  DbTxn.abort,  which
       will result in the appropriate calls to the recover method
       to  restore  the  ``database''  to   a   consistent   pre-
       transaction  state.   (The  recover method must be able to
       either re-apply  or  undo  the  update  depending  on  the
       context, for each different type of log record.)

       If the application should crash, the recovery process uses
       the DbLog interface to read the log and call  the  recover
       method to restore the database to a consistent state.

       The  DbTxn.prepare  method provides the core functionality
       to implement distributed transactions,  but  it  does  not
       manage   the   notification   of  distributed  transaction
       managers.   The  caller   is   responsible   for   issuing
       DbTxn.prepare  calls  to  all  sites  participating in the
       transaction.  If all responses are  positive,  the  caller
       can  issue  a  DbTxn.commit.   If any of the responses are
       negative, the  caller  should  issue  a  DbTxn.abort.   In
       general,   the   DbTxn.prepare   call  requires  that  the
       transaction log be flushed to disk.


TRANSACTION ID LIMITS

       The transaction ID space in Berkeley  DB  is  2^31,  or  2
       billion  entries.   It  is possible that some environments
       may need to be aware  of  this  limitation.   Consider  an
       application  performing  600  transactions a second for 15
       hours a day.  The transaction ID space  will  run  out  in
       roughly 66 days:

              2^31 / (600 * 15 * 60 * 60) = 66

       Doing   only   100  transactions  a  second  exhausts  the
       transaction ID space in roughly one year.

       The transaction ID space is reset each  time  recovery  is
       run.   If  you reach the end of your transaction ID space,
       shut down your applications and restart them after running
       recovery  (see  db_recover(1)  for more information).  The
       most   recently   allocated   transaction   ID   is    the
       st_last_txnid   value   in   the   transaction  statistics
       information, and is displayed by the db_stat(1) utility.


ERRORS

       The  DbTxn.prepare   method   may   fail   and   throw   a
       DbException(3)  for  any  of  the errors specified for the
       following DB and library functions: DbLog.flush(3),
       fcntl(2), fflush(3), and strerror(3).

       The   DbTxn.commit   method   may   fail   and   throw   a
       DbException(3) for any of the  errors  specified  for  the
       following DB and library functions: DbLockTab.vec(3),
       DbLog.put(3), fcntl(2), fflush(3), malloc(3), memcpy(3),
       and strerror(3).

       In  addition, the DbTxn.commit method may fail and throw a
       DbException(3) encapsulating an errno  for  the  following
       conditions:

       [EINVAL]
            The transaction was aborted.

       The DbTxn.abort method may fail and throw a DbException(3)
       for any of the errors specified for the following  DB  and
       library functions: DBenv->tx_recover(3), DbLockTab.vec(3),
       DbLog.get(3), fcntl(2), fflush(3), memset(3), and
       strerror(3).

       [EINVAL]
            The transaction was already aborted.


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)


Man(1) output converted with man2html