1<!--$Id: txn_recover.so,v 10.28 2007/05/30 17:24:41 margo Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: DbEnv::txn_recover</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>DbEnv::txn_recover</b> 14</td> 15<td align=right> 16<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db_cxx.h> 23<p> 24int 25DbEnv::txn_recover(DB_PREPLIST preplist[], 26 long count, long *retp, u_int32_t flags); 27</pre></b> 28<hr size=1 noshade> 29<b>Description: DbEnv::txn_recover</b> 30<p>Database environment recovery restores transactions that were prepared, 31but not yet resolved at the time of the system shut down or crash, to 32their state prior to the shut down or crash, including any locks 33previously held. The DbEnv::txn_recover method returns a list of those 34prepared transactions.</p> 35<p>The DbEnv::txn_recover method should only be called after the environment has 36been recovered.</p> 37<p>Multiple threads of control may call DbEnv::txn_recover, but only one 38thread of control may resolve each returned transaction, that is, only 39one thread of control may call <a href="../api_cxx/txn_commit.html">DbTxn::commit</a> or <a href="../api_cxx/txn_abort.html">DbTxn::abort</a> 40on each returned transaction. Callers of DbEnv::txn_recover must call 41<a href="../api_cxx/txn_discard.html">DbTxn::discard</a> to discard each transaction they do not resolve.</p> 42<p>On return from DbEnv::txn_recover, the <b>preplist</b> parameter will 43be filled in with a list of transactions that must be resolved by the 44application (committed, aborted or discarded). The <b>preplist</b> 45parameter is a structure of type DB_PREPLIST; the following DB_PREPLIST 46fields will be filled in:</p> 47<br> 48<b>DB_TXN * txn;</b><ul compact><li>The transaction handle for the transaction.</ul> 49<b>u_int8_t gid[DB_XIDDATASIZE];</b><ul compact><li>The global transaction ID for the transaction. The global transaction 50ID is the one specified when the transaction was prepared. The 51application is responsible for ensuring uniqueness among global 52transaction IDs.</ul> 53<br> 54<p>The DbEnv::txn_recover method 55either returns a non-zero error value 56or throws an exception that encapsulates a non-zero error value on 57failure, and returns 0 on success. 58</p> 59<b>Parameters</b> <br> 60 <b>count</b><ul compact><li>The <b>count</b> parameter specifies the number of available entries 61in the passed-in <b>preplist</b> array. The <b>retp</b> parameter 62returns the number of entries DbEnv::txn_recover has filled in, in the 63array.</ul> 64 <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to one of the following values: 65<br> 66<b><a name="DB_FIRST">DB_FIRST</a></b><ul compact><li>Begin returning a list of prepared, but not yet resolved transactions. 67Specifying this flag begins a new pass over all prepared, but not yet 68completed transactions, regardless of whether they have already been returned 69in previous calls to DbEnv::txn_recover. 70Calls to DbEnv::txn_recover from different threads of control should not 71be intermixed in the same environment.</ul> 72<b><a name="DB_NEXT">DB_NEXT</a></b><ul compact><li>Continue returning a list of prepared, but not yet resolved transactions, 73starting where the last call to DbEnv::txn_recover left off.</ul> 74<br></ul> 75 <b>preplist</b><ul compact><li>The <b>preplist</b> parameter references memory into which 76 the list of transactions to be resolved by the application is copied.</ul> 77<br> 78<hr size=1 noshade> 79<br><b>Class</b> 80<a href="../api_cxx/env_class.html">DbEnv</a>, <a href="../api_cxx/txn_class.html">DbTxn</a> 81<br><b>See Also</b> 82<a href="../api_cxx/txn_list.html">Transaction Subsystem and Related Methods</a> 83</tt> 84<table width="100%"><tr><td><br></td><td align=right> 85<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 86</td></tr></table> 87<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 88</body> 89</html> 90
