1<!--$Id: config.so,v 10.5 2007/12/13 03:05:54 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 Reference Guide: Application configuration</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><b><dl><dt>Berkeley DB Reference Guide:<dd>Application Specific Logging and Recovery</dl></b></td> 13<td align=right><a href="/apprec/auto.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/program/appsignals.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Application configuration</b></p> 16<p>The application should include a dispatch function that dispatches to 17appropriate printing and/or recovery functions based on the log record 18type and the operation code. The dispatch function should take the same 19arguments as the recovery function, and should call the appropriate 20recovery and/or printing functions based on the log record type and the 21operation code. For example, the ex_apprec dispatch function is as 22follows:</p> 23<blockquote><pre>int 24apprec_dispatch(dbenv, dbt, lsn, op) 25 DB_ENV *dbenv; 26 DBT *dbt; 27 DB_LSN *lsn; 28 db_recops op; 29{ 30 u_int32_t rectype; 31 /* Pull the record type out of the log record. */ 32 memcpy(&rectype, dbt->data, sizeof(rectype)); 33 switch (rectype) { 34 case DB_ex_apprec_mkdir: 35 return (ex_apprec_mkdir_recover(dbenv, dbt, lsn, op)); 36 default: 37 /* 38 * We've hit an unexpected, allegedly user-defined record 39 * type. 40 */ 41 dbenv->errx(dbenv, "Unexpected log record type encountered"); 42 return (EINVAL); 43 } 44} 45</pre></blockquote> 46<p>Applications use this dispatch function and the automatically generated 47functions as follows:</p> 48<ol> 49<p><li>When the application starts, call the <a href="/api_c/env_set_app_dispatch.html">DB_ENV->set_app_dispatch</a> 50with your dispatch function. 51<p><li>Issue a <a href="/api_c/txn_begin.html">DB_ENV->txn_begin</a> call before any operations you want to be 52transaction-protected. 53<p><li>Before accessing any data, issue the appropriate lock call to lock the 54data (either for reading or writing). 55<p><li>Before modifying any data that is transaction-protected, issue a call 56to the appropriate log function. 57<p><li>Call <a href="/api_c/txn_commit.html">DB_TXN->commit</a> to save all the changes, or call <a href="/api_c/txn_abort.html">DB_TXN->abort</a> 58to cancel all of the modifications. 59</ol> 60<p>The recovery functions are called in the three following cases:</p> 61<ol> 62<p><li>During recovery after application or system failure, with op set to 63<a href="/api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> or <a href="/api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a>. 64<p><li>During transaction abort, with op set to <a href="/api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a>. 65<p><li>On a replicated client to apply updates from the master, with op set to 66<a href="/api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a>. 67</ol> 68<p>For each log record type you declare, you must write the appropriate 69function to undo and redo the modifications. The shell of these 70functions will be generated for you automatically, but you must fill in 71the details.</p> 72<p>Your code must be able to detect whether the described modifications 73have been applied to the data. The function will be called with the 74"op" parameter set to <a href="/api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a> when a transaction that wrote 75the log record aborts, with <a href="/api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> and 76<a href="/api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a> during recovery, and with <a href="/api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a> 77on a replicated client.</p> 78<p>The actions for <a href="/api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a> and <a href="/api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a> 79should generally be the same, and the actions for 80<a href="/api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> and <a href="/api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a> should generally 81be the same. However, if the application is using Berkeley DB replication 82and another thread of control may be performing read operations while 83log records are applied on a replication client, the recovery function 84should perform appropriate locking during <a href="/api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a> 85operations. In this case, the recovery function may encounter deadlocks 86when issuing locking calls. The application should run with the 87deadlock detector, and the recovery function should simply return 88<a href="/ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> if a deadlock is detected and a locking 89operation fails with that error.</p> 90<p>The <a href="/api_c/env_set_app_dispatch.html#DB_TXN_PRINT">DB_TXN_PRINT</a> operation should print the log record, 91typically using the auto-generated print function; it is not used in 92the Berkeley DB library, but may be useful for debugging, as in the 93<a href="/utility/db_printlog.html">db_printlog</a> utility. Applications may safely ignore this 94operation code, they may handle printing from the recovery function, or 95they may dispatch directly to the auto-generated print function.</p> 96<p>One common way to determine whether operations need to be undone or 97redone is the use of log sequence numbers (LSNs). For example, each 98access method database page contains the LSN of the most recent log 99record that describes a modification to the page. When the access 100method changes a page, it writes a log record describing the change and 101including the LSN that was on the page before the change. This LSN is 102referred to as the previous LSN. The recovery functions read the page 103described by a log record, and compare the LSN on the page to the LSN 104they were passed.</p> 105<p>If the page LSN is less than the passed LSN and the operation is an 106undo, no action is necessary (because the modifications have not been 107written to the page). If the page LSN is the same as the previous LSN 108and the operation is a redo, the actions described are reapplied to the 109page. If the page LSN is equal to the passed LSN and the operation is 110an undo, the actions are removed from the page; if the page LSN is 111greater than the passed LSN and the operation is a redo, no further 112action is necessary. If the action is a redo and the LSN on the page 113is less than the previous LSN in the log record, it is an error because 114it could happen only if some previous log record was not processed.</p> 115<p>Examples of other recovery functions can be found in the Berkeley DB library 116recovery functions (found in files named XXX_rec.c) and in the 117application-specific recovery example (specifically, ex_apprec_rec.c).</p> 118<p>Finally, applications need to ensure that any data modifications they 119have made, that were part of a committed transaction, must be written 120to stable storage before calling the <a href="/api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a> method. This is 121to allow the periodic removal of database environment log files.</p> 122<table width="100%"><tr><td><br></td><td align=right><a href="/apprec/auto.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/program/appsignals.html"><img src="/images/next.gif" alt="Next"></a> 123</td></tr></table> 124<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 125</body> 126</html> 127