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>Application configuration</title> 7 <link rel="stylesheet" href="gettingStarted.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 Programmer's Reference Guide" /> 10 <link rel="up" href="apprec.html" title="Chapter 13. Application Specific Logging and Recovery" /> 11 <link rel="prev" href="apprec_auto.html" title="Automatically generated functions" /> 12 <link rel="next" href="program.html" title="Chapter 14. Programmer Notes" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Application configuration</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="apprec_auto.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 13. 23 Application Specific Logging and Recovery 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="program.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="apprec_config"></a>Application configuration</h2> 35 </div> 36 </div> 37 </div> 38 <p>The application should include a dispatch function that dispatches to 39appropriate printing and/or recovery functions based on the log record 40type and the operation code. The dispatch function should take the same 41arguments as the recovery function, and should call the appropriate 42recovery and/or printing functions based on the log record type and the 43operation code. For example, the ex_apprec dispatch function is as 44follows:</p> 45 <pre class="programlisting">int 46apprec_dispatch(dbenv, dbt, lsn, op) 47 DB_ENV *dbenv; 48 DBT *dbt; 49 DB_LSN *lsn; 50 db_recops op; 51{ 52 u_int32_t rectype; 53 /* Pull the record type out of the log record. */ 54 memcpy(&rectype, dbt->data, sizeof(rectype)); 55 switch (rectype) { 56 case DB_ex_apprec_mkdir: 57 return (ex_apprec_mkdir_recover(dbenv, dbt, lsn, op)); 58 default: 59 /* 60 * We've hit an unexpected, allegedly user-defined record 61 * type. 62 */ 63 dbenv->errx(dbenv, "Unexpected log record type encountered"); 64 return (EINVAL); 65 } 66}</pre> 67 <p>Applications use this dispatch function and the automatically generated 68functions as follows:</p> 69 <div class="orderedlist"> 70 <ol type="1"> 71 <li>When the application starts, call the <a href="../api_reference/C/envset_app_dispatch.html" class="olink">DB_ENV->set_app_dispatch()</a> 72with your dispatch function.</li> 73 <li>Issue a <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> call before any operations you want to be 74transaction-protected.</li> 75 <li>Before accessing any data, issue the appropriate lock call to lock the 76data (either for reading or writing).</li> 77 <li>Before modifying any data that is transaction-protected, issue a call 78to the appropriate log function.</li> 79 <li>Call <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a> 80to cancel all of the modifications.</li> 81 </ol> 82 </div> 83 <p>The recovery functions are called in the three following cases:</p> 84 <div class="orderedlist"> 85 <ol type="1"> 86 <li>During recovery after application or system failure, with op set to 87<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_FORWARD_ROLL" class="olink">DB_TXN_FORWARD_ROLL</a> or <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_BACKWARD_ROLL" class="olink">DB_TXN_BACKWARD_ROLL</a>.</li> 88 <li>During transaction abort, with op set to <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_ABORT" class="olink">DB_TXN_ABORT</a>.</li> 89 <li>On a replicated client to apply updates from the master, with op set to 90<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_APPLY" class="olink">DB_TXN_APPLY</a>.</li> 91 </ol> 92 </div> 93 <p>For each log record type you declare, you must write the appropriate 94function to undo and redo the modifications. The shell of these 95functions will be generated for you automatically, but you must fill in 96the details.</p> 97 <p>Your code must be able to detect whether the described modifications 98have been applied to the data. The function will be called with the 99"op" parameter set to <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_ABORT" class="olink">DB_TXN_ABORT</a> when a transaction that wrote 100the log record aborts, with <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_FORWARD_ROLL" class="olink">DB_TXN_FORWARD_ROLL</a> and 101<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_BACKWARD_ROLL" class="olink">DB_TXN_BACKWARD_ROLL</a> during recovery, and with <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_APPLY" class="olink">DB_TXN_APPLY</a> 102on a replicated client.</p> 103 <p>The actions for <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_ABORT" class="olink">DB_TXN_ABORT</a> and <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_BACKWARD_ROLL" class="olink">DB_TXN_BACKWARD_ROLL</a> 104should generally be the same, and the actions for 105<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_FORWARD_ROLL" class="olink">DB_TXN_FORWARD_ROLL</a> and <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_APPLY" class="olink">DB_TXN_APPLY</a> should generally 106be the same. However, if the application is using Berkeley DB replication 107and another thread of control may be performing read operations while 108log records are applied on a replication client, the recovery function 109should perform appropriate locking during <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_APPLY" class="olink">DB_TXN_APPLY</a> 110operations. In this case, the recovery function may encounter deadlocks 111when issuing locking calls. The application should run with the 112deadlock detector, and the recovery function should simply return 113<a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> if a deadlock is detected and a locking 114operation fails with that error.</p> 115 <p>The <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_PRINT" class="olink">DB_TXN_PRINT</a> operation should print the log record, 116typically using the auto-generated print function; it is not used in 117the Berkeley DB library, but may be useful for debugging, as in the 118<a href="../api_reference/C/db_printlog.html" class="olink">db_printlog utility</a>. Applications may safely ignore this 119operation code, they may handle printing from the recovery function, or 120they may dispatch directly to the auto-generated print function.</p> 121 <p>One common way to determine whether operations need to be undone or 122redone is the use of log sequence numbers (LSNs). For example, each 123access method database page contains the LSN of the most recent log 124record that describes a modification to the page. When the access 125method changes a page, it writes a log record describing the change and 126including the LSN that was on the page before the change. This LSN is 127referred to as the previous LSN. The recovery functions read the page 128described by a log record, and compare the LSN on the page to the LSN 129they were passed.</p> 130 <p>If the page LSN is less than the passed LSN and the operation is an 131undo, no action is necessary (because the modifications have not been 132written to the page). If the page LSN is the same as the previous LSN 133and the operation is a redo, the actions described are reapplied to the 134page. If the page LSN is equal to the passed LSN and the operation is 135an undo, the actions are removed from the page; if the page LSN is 136greater than the passed LSN and the operation is a redo, no further 137action is necessary. If the action is a redo and the LSN on the page 138is less than the previous LSN in the log record, it is an error because 139it could happen only if some previous log record was not processed.</p> 140 <p>Examples of other recovery functions can be found in the Berkeley DB library 141recovery functions (found in files named XXX_rec.c) and in the 142application-specific recovery example (specifically, ex_apprec_rec.c).</p> 143 <p>Finally, applications need to ensure that any data modifications they 144have made, that were part of a committed transaction, must be written 145to stable storage before calling the <a href="../api_reference/C/txncheckpoint.html" class="olink">DB_ENV->txn_checkpoint()</a> method. This is 146to allow the periodic removal of database environment log files.</p> 147 </div> 148 <div class="navfooter"> 149 <hr /> 150 <table width="100%" summary="Navigation footer"> 151 <tr> 152 <td width="40%" align="left"><a accesskey="p" href="apprec_auto.html">Prev</a> </td> 153 <td width="20%" align="center"> 154 <a accesskey="u" href="apprec.html">Up</a> 155 </td> 156 <td width="40%" align="right"> <a accesskey="n" href="program.html">Next</a></td> 157 </tr> 158 <tr> 159 <td width="40%" align="left" valign="top">Automatically generated functions </td> 160 <td width="20%" align="center"> 161 <a accesskey="h" href="index.html">Home</a> 162 </td> 163 <td width="40%" align="right" valign="top"> Chapter 14. 164 Programmer Notes 165 </td> 166 </tr> 167 </table> 168 </div> 169 </body> 170</html> 171