NNAAMMEE DbTxnMgr - Db transaction management SSYYNNOOPPSSIISS ##iinncclluuddee <> ssttaattiicc iinntt DDbbTTxxnnMMggrr::::ooppeenn((ccoonnsstt cchhaarr **ddiirr,, uu__iinntt3322__tt ffllaaggss,, iinntt mmooddee,, DDbbEEnnvv **ddbbeennvv,, DDbbTTxxnnMMggrr ****rreeggiioonnpp));; iinntt DDbbTTxxnnMMggrr::::bbeeggiinn((DDbbTTxxnn **ppiidd,, DDbbTTxxnn ****ttiidd));; iinntt DDbbTTxxnnMMggrr::::cchheecckkppooiinntt((uu__iinntt3322__tt kkbbyyttee,, uu__iinntt3322__tt mmiinn)) ccoonnsstt;; iinntt DDbbTTxxnnMMggrr::::cclloossee(());; ssttaattiicc iinntt DDbbTTxxnnMMggrr::::uunnlliinnkk((ccoonnsstt cchhaarr **ddiirr,, iinntt ffoorrccee,, DDbbEEnnvv **ddbbeennvv));; iinntt DDbbTTxxnnMMggrr::::ssttaatt((DDBB__TTXXNN__SSTTAATT ****ssttaattpp,, vvooiidd **((**ddbb__mmaalllloocc))((ssiizzee__tt))));; DDEESSCCRRIIPPTTIIOONN 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 _d_b___i_n_t_r_o(3). This manual page describes the specific details of the Db transaction support. The DbTxnMgr class is used in con- junction with _D_b_T_x_n(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 _D_b_L_o_g(3)), concurrency control (see _D_b_L_o_c_k(3) and _D_b_L_o_c_k_T_a_b(3)), and the management of shared data (see _D_b_M_- _p_o_o_l(3) and _D_b_M_p_o_o_l_F_i_l_e(3)). Transaction semantics can be applied to the access methods described in _D_b(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 _D_b_L_o_g(3) to record both before- and after-image logging. Locking follows a two-phase protocol (i.e., all locks are released at transaction commit). _D_b_T_x_n_M_g_r_:_:_o_p_e_n The _D_b_T_x_n_M_g_r_:_:_o_p_e_n method copies a pointer, to the trans- action region identified by the ddiirreeccttoorryy _d_i_r, into the memory location referenced by _r_e_g_i_o_n_p. If the _d_b_e_n_v argument to _D_b_T_x_n_M_g_r_:_:_o_p_e_n was initialized using _D_b_E_n_v_:_:_a_p_p_i_n_i_t, _d_i_r is interpreted as described by _D_b_E_n_v(3). Otherwise, if _d_i_r is not NULL, it is interpreted relative to the current working directory of the process. If _d_i_r 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: _/_v_a_r_/_t_m_p, _/_u_s_r_/_t_m_p, _/_t_e_m_p, _/_t_m_p, _C_:_/_t_e_m_p and _C_:_/_t_m_p. All files associated with the transaction region are cre- ated 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 ini- tialized. The _f_l_a_g_s and _m_o_d_e arguments specify how files will be opened and/or created when they don't already exist. The flags value is specified by oorr'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 _D_b_T_x_n_- _M_g_r_:_:_o_p_e_n 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 _d_b___c_h_e_c_k_p_o_i_n_t(1)) and how many log updates can fit on a single log page. All files created by the transaction subsystem are created with mode _m_o_d_e (as described in _c_h_m_o_d(2)) and modified by the process' umask value at the time of creation (see _u_m_a_s_k(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 _D_b_T_x_n_M_g_r_:_:_o_p_e_n are described below. As references to the DbEnv object may be maintained by _D_b_T_x_n_- _M_g_r_:_:_o_p_e_n, it is necessary that the DbEnv object and mem- ory 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 initial- ized, using the appropriate set method, before calling _D_b_T_x_n_M_g_r_:_:_o_p_e_n: 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 _D_b_E_n_v(3). DbLog *lg_info; The logging region that is being used for this transaction environment. The _l_g___i_n_f_o field contains a return value from the method _D_b_L_o_g_:_:_o_p_e_n. LLooggggiinngg iiss rreeqquuiirreedd ffoorr ttrraannssaaccttiioonn eennvviirroonnmmeennttss,, aanndd iitt iiss aann eerrrroorr ttoo nnoott ssppeecciiffyy aa llooggggiinngg rreeggiioonn.. DbLockTab *lk_info; The locking region that is being used for this transaction environment. The _l_k___i_n_f_o field contains a return value from the method _D_b_L_o_c_k_T_a_b_:_:_o_p_e_n. If _l_k___i_n_f_o is NULL, no locking is done in this transac- tion 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 _t_x___m_a_x concurrent transactions, calls to _D_b_T_x_n_M_g_r_:_:_b_e_g_i_n may cause backing files to grow. If _t_x___m_a_x 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 _D_b_T_x_n_:_:_a_b_o_r_t 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- action ids encountered that have not been entered into the list referenced by _i_n_f_o 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 _r_e_c_o_v_e_r is NULL, the default is that only Db access method operations are transaction protected, and the default recover method will be used. The _D_b_T_x_n_M_g_r_:_:_o_p_e_n method throws a _D_b_E_x_c_e_p_t_i_o_n(3) or returns the value of _e_r_r_n_o on failure and 0 on success. _D_b_T_x_n_M_g_r_:_:_b_e_g_i_n The _D_b_T_x_n_M_g_r_:_:_b_e_g_i_n method creates a new transaction in the transaction manager, copying a pointer to a DbTxn that uniquely identifies it into the memory referenced by _t_i_d. If the _p_i_d argument is non-NULL, the new transaction is a nested transaction with the transaction indicated by _p_i_d 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 _D_b_T_x_n_M_g_r_:_:_b_e_g_i_n method throws a _D_b_E_x_c_e_p_t_i_o_n(3) or returns the value of _e_r_r_n_o on failure and 0 on success. _D_b_T_x_n_M_g_r_:_:_c_l_o_s_e The _D_b_T_x_n_M_g_r_:_:_c_l_o_s_e 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 _d_i_r argument to _D_b_T_x_n_M_g_r_:_:_o_p_e_n was NULL and _d_b_e_n_v was not initialized using _D_b_E_n_v_:_:_a_p_p_i_n_i_t, all files created for this shared region will be removed, as if _D_b_T_x_n_M_g_r_:_:_u_n_l_i_n_k were called. When multiple threads are using the DbTxnMgr handle con- currently, only a single thread may call the _D_b_T_x_n_- _M_g_r_:_:_c_l_o_s_e method. The _D_b_T_x_n_M_g_r_:_:_c_l_o_s_e method throws a _D_b_E_x_c_e_p_t_i_o_n(3) or returns the value of _e_r_r_n_o on failure and 0 on success. _D_b_T_x_n_M_g_r_:_:_u_n_l_i_n_k The _D_b_T_x_n_M_g_r_:_:_u_n_l_i_n_k method destroys the transaction region identified by the directory _d_i_r, removing all files used to implement the transaction region. (The directory _d_i_r is not removed.) If there are processes that have called _D_b_T_x_n_M_g_r_:_:_o_p_e_n without calling _D_b_T_x_n_M_g_r_:_:_c_l_o_s_e (i.e., there are processes currently using the transaction region), _D_b_T_x_n_M_g_r_:_:_u_n_l_i_n_k will fail without further action, unless the force flag is set, in which case _D_b_T_x_n_- _M_g_r_:_:_u_n_l_i_n_k will attempt to remove the transaction region files regardless of any processes still using the transac- tion region. The result of attempting to forcibly destroy the region when a process has the region open is unspecified. Pro- cesses 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 transac- tion region will either fail or attempt to create a new region. On other systems, e.g., WNT, where the _u_n_l_i_n_k(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 _d_b___r_e_c_o_v_e_r(1) or the DB_RECOVER and DB_RECOVER_FATAL flags to _D_b_E_n_v_:_:_a_p_p_i_n_i_t(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 _D_b_T_x_n_M_g_r_:_:_o_p_e_n method, as transaction region files are never created in any directory other than the one speci- fied to _D_b_T_x_n_M_g_r_:_:_o_p_e_n. Note, however, that this has the potential to remove files created by the other DB subsys- tems in this database environment. The _D_b_T_x_n_M_g_r_:_:_u_n_l_i_n_k method throws a _D_b_E_x_c_e_p_t_i_o_n(3) or returns the value of _e_r_r_n_o on failure and 0 on success. _D_b_T_x_n_M_g_r_:_:_c_h_e_c_k_p_o_i_n_t The _D_b_T_x_n_M_g_r_:_:_c_h_e_c_k_p_o_i_n_t method syncs the underlying mem- ory pool, writes a checkpoint record to the log and then flushes the log. If either _k_b_y_t_e or _m_i_n is non-zero, the checkpoint is only done if more than _m_i_n minutes have passed since the last checkpoint, or if more than _k_b_y_t_e kilobytes of log data have been written since the last checkpoint. The _D_b_T_x_n_M_g_r_:_:_c_h_e_c_k_p_o_i_n_t method throws a _D_b_E_x_c_e_p_t_i_o_n(3) or returns the value of _e_r_r_n_o on failure, 0 on success, and DB_INCOMPLETE if there were pages that needed to be writ- ten but that _D_b_M_p_o_o_l_:_:_s_y_n_c _(_3_) (see _D_b_M_p_o_o_l _(_3_)_) was unable to write immediately. In this case, the _D_b_T_x_n_- _M_g_r_:_:_c_h_e_c_k_p_o_i_n_t call should be retried. The _D_b_T_x_n_M_g_r_:_:_c_h_e_c_k_p_o_i_n_t method is based on the C _t_x_n___c_h_e_c_k_p_o_i_n_t function, which is the underlying function used by the _d_b___c_h_e_c_k_p_o_i_n_t(1) utility. See the source code for the _d_b___c_h_e_c_k_p_o_i_n_t utility for an example of using _t_x_n___c_h_e_c_k_p_o_i_n_t in a UNIX environment. _D_b_T_x_n_M_g_r_:_:_s_t_a_t The _D_b_T_x_n_M_g_r_:_:_s_t_a_t method creates a statistical structure and copies pointers to it into user-specified memory locations. Statistical structures are created in allocated memory. If _d_b___m_a_l_l_o_c is non-NULL, it is called to allocate the memory, otherwise, the library function _m_a_l_l_o_c(3) is used. The function _d_b___m_a_l_l_o_c must match the calling conventions of the _m_a_l_l_o_c(3) library routine. Regardless, the caller is responsible for deallocating the returned memory. To deallocate the returned memory, free each returned memory pointer; pointers inside the memory do not need to be individually freed. The transaction region statistics are stored in a struc- ture of type DB_TXN_STAT (typedef'd in ). The following DB_TXN_STAT fields will be filled in: 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 _s_t___p_e_n_d_i_n_g___c_k_p is the same as _s_t___l_a_s_t___c_k_p there is no checkpoint in progress. time_t st_time_ckp; The time the last completed checkpoint finished (as returned by _t_i_m_e(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. u_int32_t ; The number of times that a thread of control was forced to wait before obtaining the region lock. u_int32_t ; The number of times that a thread of control was able to obtain the region lock without waiting. DB_TXN_ACTIVE *st_txnarray; A pointer to an array of _s_t___n_a_c_t_i_v_e DB_TXN_ACTIVE structures, describing the currently active transac- tions. The following fields of the DB_TXN_ACTIVE structure (typedef'd in ) will be filled in: u_int32_t txnid; The transaction ID as returned by _D_b_T_x_n_- _M_g_r_:_:_b_e_g_i_n(3). DbLsn lsn; The LSN of the transaction-begin record. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS The following environment variables affect the execution of _d_b___t_x_n: DB_HOME If the _d_b_e_n_v argument to _D_b_T_x_n_M_g_r_:_:_o_p_e_n was initial- ized using _d_b___a_p_p_i_n_i_t, the environment variable DB_HOME may be used as the path of the database home for the interpretation of the _d_i_r argument to _D_b_T_x_n_- _M_g_r_:_:_o_p_e_n, as described in _d_b___a_p_p_i_n_i_t(3). TMPDIR If the _d_b_e_n_v argument to _D_b_T_x_n_M_g_r_:_:_o_p_e_n was NULL or not initialized using _d_b___a_p_p_i_n_i_t, the environment variable TMPDIR may be used as the directory in which to create the transaction region, as described in the _D_b_T_x_n_M_g_r_:_:_o_p_e_n section above. EERRRROORRSS Methods marked as returning _e_r_r_n_o will, by default, throw an exception that encapsulates the error information. The default error behavior can be changed, see _D_b_E_x_c_e_p_t_i_o_n(3). The _D_b_T_x_n_M_g_r_:_:_o_p_e_n method may fail and throw a _D_b_E_x_c_e_p_- _t_i_o_n(3) or return _e_r_r_n_o 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), str- cpy(3), strdup(3), strerror(3), strlen(3), time(3), unlink(2), and write(2). In addition, the _D_b_T_x_n_M_g_r_:_:_o_p_e_n method may fail and throw a _D_b_E_x_c_e_p_t_i_o_n(3) or return _e_r_r_n_o 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 _d_b_e_n_v parameter was NULL. [EAGAIN] The shared memory region was locked and (repeatedly) unavailable. The _D_b_T_x_n_M_g_r_:_:_b_e_g_i_n method may fail and throw a _D_b_E_x_c_e_p_- _t_i_o_n(3) or return _e_r_r_n_o 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), mem- set(3), mmap(2), munmap(2), strerror(3), and write(2). In addition, the _D_b_T_x_n_M_g_r_:_:_b_e_g_i_n method may fail and throw a _D_b_E_x_c_e_p_t_i_o_n(3) or return _e_r_r_n_o for the following condi- tions: [ENOSPC] The maximum number of concurrent transactions has been reached. The _D_b_T_x_n_M_g_r_:_:_c_h_e_c_k_p_o_i_n_t method may fail and throw a _D_b_E_x_- _c_e_p_t_i_o_n(3) or return _e_r_r_n_o 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), mal- loc(3), memcpy(3), memset(3), strerror(3), and time(3). [EINVAL] An invalid flag value or parameter was specified. The _D_b_T_x_n_M_g_r_:_:_c_l_o_s_e method may fail and throw a _D_b_E_x_c_e_p_- _t_i_o_n(3) or return _e_r_r_n_o 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 _D_b_T_x_n_M_g_r_:_:_u_n_l_i_n_k method may fail and throw a _D_b_E_x_c_e_p_- _t_i_o_n(3) or return _e_r_r_n_o 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), mun- map(2), open(2), sigfillset(3), sigprocmask(2), stat(2), strcpy(3), strdup(3), strerror(3), strlen(3), and unlink(2). In addition, the _D_b_T_x_n_M_g_r_:_:_u_n_l_i_n_k method may fail and throw a _D_b_E_x_c_e_p_t_i_o_n(3) or return _e_r_r_n_o for the following conditions: [EBUSY] The shared memory region was in use and the force flag was not set. The _D_b_T_x_n_M_g_r_:_:_s_t_a_t method may fail and throw a _D_b_E_x_c_e_p_- _t_i_o_n(3) or return _e_r_r_n_o for any of the errors specified for the following DB and library functions: fcntl(2), and malloc(3). SSEEEE AALLSSOO _L_I_B_T_P_: _P_o_r_t_a_b_l_e_, _M_o_d_u_l_a_r _T_r_a_n_s_a_c_t_i_o_n_s _f_o_r _U_N_I_X, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. BBUUGGSS Nested transactions are not yet implemented. _d_b___a_r_c_h_i_v_e(1), _d_b___c_h_e_c_k_p_o_i_n_t(1), _d_b___d_e_a_d_l_o_c_k(1), _d_b___d_u_m_p(1), _d_b___l_o_a_d(1), _d_b___r_e_c_o_v_e_r(1), _d_b___s_t_a_t(1), _d_b___i_n_t_r_o(3), _d_b___i_n_t_e_r_n_a_l(3), _d_b___t_h_r_e_a_d(3), _D_b(3), _D_b_c(3), _D_b_E_n_v(3), _D_b_E_x_c_e_p_t_i_o_n(3), _D_b_I_n_f_o(3), _D_b_L_o_c_k(3), _D_b_L_o_c_k_T_a_b(3), _D_b_L_o_g(3), _D_b_L_s_n(3), _D_b_M_p_o_o_l(3), _D_b_M_p_o_o_l_F_i_l_e(3), _D_b_t(3), _D_b_T_x_n(3), _D_b_T_x_n_M_g_r(3)