1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DbEnv::set_app_dispatch()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> 10 <link rel="up" href="env.html" title="Chapter 5. The DbEnv Handle" /> 11 <link rel="prev" href="envset_alloc.html" title="DbEnv::set_alloc()" /> 12 <link rel="next" href="envset_data_dir.html" title="DbEnv::set_data_dir()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::set_app_dispatch()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="envset_alloc.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 5. 23 The DbEnv Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="envset_data_dir.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="envset_app_dispatch"></a>DbEnv::set_app_dispatch()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::set_app_dispatch(int (*tx_recover)(DbEnv *dbenv, 42 Dbt *log_rec, DbLsn *lsn, db_recops op));</pre> 43 <p> 44 Declare a function to be called during transaction abort and recovery 45 to process application-specific log records. 46 </p> 47 <p> 48 The <code class="methodname">DbEnv::set_app_dispatch()</code> method configures operations performed 49 using the specified <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> handle, not all 50 operations performed on the underlying database environment. 51 </p> 52 <p> 53 The <code class="methodname">DbEnv::set_app_dispatch()</code> method may not be called after the 54 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method is 55 called. If the database environment already exists when 56 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> is called, the 57 information specified to <code class="methodname">DbEnv::set_app_dispatch()</code> must be 58 consistent with the existing environment or corruption can occur. 59 </p> 60 <p> 61 The <code class="methodname">DbEnv::set_app_dispatch()</code> method returns a non-zero error value 62 on failure and 0 on success. 63 </p> 64 <div class="sect2" lang="en" xml:lang="en"> 65 <div class="titlepage"> 66 <div> 67 <div> 68 <h3 class="title"><a id="id1669208"></a>Parameters</h3> 69 </div> 70 </div> 71 </div> 72 <div class="sect3" lang="en" xml:lang="en"> 73 <div class="titlepage"> 74 <div> 75 <div> 76 <h4 class="title"><a id="id1669245"></a>tx_recover</h4> 77 </div> 78 </div> 79 </div> 80 <p> 81 The <span class="bold"><strong>tx_recover</strong></span> parameter is the 82 application's abort and recovery function. The function takes four 83 parameters: 84 </p> 85 <div class="itemizedlist"> 86 <ul type="disc"> 87 <li> 88 <p> 89 <code class="literal">dbenv</code> 90 </p> 91 <p> 92 The <span class="bold"><strong>dbenv</strong></span> parameter is the enclosing 93 database environment handle. 94 </p> 95 </li> 96 <li> 97 <p> 98 <code class="literal">log_rec</code> 99 </p> 100 <p> 101 The <span class="bold"><strong>log_rec</strong></span> parameter is a log 102 record. 103 </p> 104 </li> 105 <li> 106 <p> 107 <code class="literal">lsn</code> 108 </p> 109 <p> 110 The <span class="bold"><strong>lsn</strong></span> parameter is a log sequence 111 number. 112 </p> 113 </li> 114 <li> 115 <p> 116 <code class="literal">op</code> 117 </p> 118 <p> 119 The <span class="bold"><strong>op</strong></span> parameter is one of the 120 following values: 121 </p> 122 <div class="itemizedlist"> 123 <ul type="circle"> 124 <li> 125 <p><a id="set_app_dispatch_DB_TXN_BACKWARD_ROLL"></a> 126 <code class="literal">DB_TXN_BACKWARD_ROLL</code> 127 </p> 128 <p> 129 The log is being read backward to determine which transactions have 130 been committed and to abort those operations that were not; undo the 131 operation described by the log record. 132 </p> 133 </li> 134 <li> 135 <p><a id="set_app_dispatch_DB_TXN_FORWARD_ROLL"></a> 136 <code class="literal">DB_TXN_FORWARD_ROLL</code> 137 </p> 138 <p> 139 The log is being played forward; redo the operation described by the 140 log record. 141 </p> 142 </li> 143 <li> 144 <p><a id="set_app_dispatch_DB_TXN_ABORT"></a> 145 <code class="literal">DB_TXN_ABORT</code> 146 </p> 147 <p> 148 The log is being read backward during a transaction abort; undo the 149 operation described by the log record. 150 </p> 151 </li> 152 <li> 153 <p><a id="set_app_dispatch_DB_TXN_APPLY"></a> 154 <code class="literal">DB_TXN_APPLY</code> 155 </p> 156 <p> 157 The log is being applied on a replica site; redo the operation 158 described by the log record. 159 </p> 160 </li> 161 <li> 162 <p><a id="set_app_dispatch_DB_TXN_PRINT"></a> 163 <code class="literal">DB_TXN_PRINT</code> 164 </p> 165 <p> 166 The log is being printed for debugging purposes; print the contents of 167 this log record in the desired format. 168 </p> 169 </li> 170 </ul> 171 </div> 172 <p> 173 The DB_TXN_FORWARD_ROLL and DB_TXN_APPLY operations frequently imply 174 the same actions, redoing changes that appear in the log record, 175 although if a recovery function is to be used on a replication client 176 where reads may be taking place concurrently with the processing of 177 incoming messages, DB_TXN_APPLY operations should also perform 178 appropriate locking. The macro DB_REDO(op) checks that the operation 179 is one of DB_TXN_FORWARD_ROLL or DB_TXN_APPLY, and should be used in 180 the recovery code to refer to the conditions under which operations 181 should be redone. Similarly, the macro DB_UNDO(op) checks if the 182 operation is one of DB_TXN_BACKWARD_ROLL or DB_TXN_ABORT. 183 </p> 184 </li> 185 </ul> 186 </div> 187 <p> 188 The function must return 0 on success and either <span class="bold"><strong>errno</strong></span> 189 or a value outside of the Berkeley DB error name space on failure. 190 </p> 191 </div> 192 </div> 193 <div class="sect2" lang="en" xml:lang="en"> 194 <div class="titlepage"> 195 <div> 196 <div> 197 <h3 class="title"><a id="id1669364"></a>Errors</h3> 198 </div> 199 </div> 200 </div> 201 <p> 202 The <code class="methodname">DbEnv::set_app_dispatch()</code> <span> 203 204 <span> 205 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 206 exception, encapsulating one of the following non-zero errors, or return one 207 of the following non-zero errors: 208 </span> 209 </span> 210 </p> 211 <div class="sect3" lang="en" xml:lang="en"> 212 <div class="titlepage"> 213 <div> 214 <div> 215 <h4 class="title"><a id="id1669098"></a>EINVAL</h4> 216 </div> 217 </div> 218 </div> 219 <p> 220 If the method was called after <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> 221 was called; or if an invalid flag value or parameter was specified. 222 </p> 223 </div> 224 </div> 225 <div class="sect2" lang="en" xml:lang="en"> 226 <div class="titlepage"> 227 <div> 228 <div> 229 <h3 class="title"><a id="id1669380"></a>Class</h3> 230 </div> 231 </div> 232 </div> 233 <p> 234 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>, <a class="link" href="txn.html" title="Chapter 13. The DbTxn Handle">DbTxn</a> 235 </p> 236 </div> 237 <div class="sect2" lang="en" xml:lang="en"> 238 <div class="titlepage"> 239 <div> 240 <div> 241 <h3 class="title"><a id="id1669636"></a>See Also</h3> 242 </div> 243 </div> 244 </div> 245 <p> 246 <a class="xref" href="txn.html#txnlist" title="Transaction Subsystem and Related Methods">Transaction Subsystem and Related Methods</a> 247 </p> 248 </div> 249 </div> 250 <div class="navfooter"> 251 <hr /> 252 <table width="100%" summary="Navigation footer"> 253 <tr> 254 <td width="40%" align="left"><a accesskey="p" href="envset_alloc.html">Prev</a> </td> 255 <td width="20%" align="center"> 256 <a accesskey="u" href="env.html">Up</a> 257 </td> 258 <td width="40%" align="right"> <a accesskey="n" href="envset_data_dir.html">Next</a></td> 259 </tr> 260 <tr> 261 <td width="40%" align="left" valign="top">DbEnv::set_alloc() </td> 262 <td width="20%" align="center"> 263 <a accesskey="h" href="index.html">Home</a> 264 </td> 265 <td width="40%" align="right" valign="top"> DbEnv::set_data_dir()</td> 266 </tr> 267 </table> 268 </div> 269 </body> 270</html> 271