1<!--$Id: def.so,v 10.9 2007/12/15 01:18:15 alanb 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: Defining application-specific log records</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/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../apprec/auto.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Defining application-specific log records</b></p> 16<p>By convention, log records are described in files named <b>XXX.src</b>, 17where "XXX" is typically a descriptive name for a subsystem or other 18logical group of logging functions. These files contain interface 19definition language descriptions for each type of log record that is 20used by the subsystem.</p> 21<p>All blank lines and lines beginning with a hash ("#") character in 22the XXX.src files are ignored.</p> 23<p>The first non-comment line in the file should begin with the keyword 24PREFIX, followed by a string that will be prepended to every generated 25function name. Frequently, the PREFIX is either identical or similar 26to the name of the <b>XXX.src</b> file. For example, the Berkeley DB 27application-specific recovery example uses the file 28<b>ex_apprec.src</b>, which begins with the following PREFIX line:</p> 29<blockquote><pre>PREFIX ex_apprec</pre></blockquote> 30<p>Following the PREFIX line are the include files required by the 31automatically generated functions. The include files should be listed 32in order, prefixed by the keyword INCLUDE. For example, the Berkeley DB 33application-specific recovery example lists the following include 34files:</p> 35<blockquote><pre>INCLUDE #include "ex_apprec.h"</pre></blockquote> 36<p>The rest of the XXX.src file consists of log record descriptions. Each 37log record description begins with one of the following lines:</p> 38<blockquote><pre>BEGIN <i>RECORD_NAME</i> <i>DB_VERSION_NUMBER</i> <i>RECORD_NUMBER</i></pre></blockquote> 39<blockquote><pre>BEGIN_COMPAT <i>RECORD_NAME</i> <i>DB_VERSION_NUMBER</i> <i>RECORD_NUMBER</i></pre></blockquote> 40<p>and ends with the line:</p> 41<blockquote><pre>END</pre></blockquote> 42<p>The <i>BEGIN</i> line should be used for most record types.</p> 43<p>The <i>BEGIN_COMPAT</i> is used for log record compatibility to facilitate 44online upgrades of replication groups. Records created with this keyword will 45produce reading and printing routines, but no logging routines. The recovery 46routines are retrieved from older releases, so no recovery templates will be 47generated for these records.</p> 48<p>The <i>DB_VERSION_NUMBER</i> variable should be replaced with the 49current major and minor version of Berkeley DB, with all punctuation removed. 50For example, Berkeley DB version 4.2 should be 42, version 4.5 should be 45.</p> 51<p>The <i>RECORD_NAME</i> variable should be replaced with a record 52name for this log record. The <i>RECORD_NUMBER</i> variable should 53be replaced with a record number.</p> 54<p>The combination of PREFIX name and <i>RECORD_NAME</i>, and the 55<i>RECORD_NUMBER</i> must be unique for the application, that is, 56values for application-specific and Berkeley DB log records may not overlap. 57Further, because record numbers are stored in log files, which are 58usually portable across application and Berkeley DB releases, any change to 59the record numbers or log record format or should be handled as 60described in the <a href="../../ref/upgrade/process.html">Upgrading Berkeley DB 61installations</a> section on log format changes. The record number space 62below 10,000 is reserved for Berkeley DB itself; applications should choose 63record number values equal to or greater than 10,000.</p> 64<p>Between the BEGIN and END keywords there should be one optional 65<i>DUPLICATE</i> line and one line for each 66data item logged as part of this log record.</p> 67<p>The <i>DUPLICATE</i> line is of the form:</p> 68<blockquote><pre>DUPLICATE <i>RECORD_NAME</i> <i>DB_VERSION_NUMBER</i> <i>RECORD_NUMBER</i></pre></blockquote> 69<p>The <i>DUPLICATE</i> specifier should be used when creating a record 70that requires its own record number but can use the argument structure, 71reading and printing routines from another record. In this case, we will 72create a new log record type, but use the enclosing log record type for 73the argument structure and the log reading and printing routines.</p> 74<p>The format of lines for each data item logged is as follows:</p> 75<blockquote><pre>ARG | DBT | POINTER <i>variable_name</i> <i>variable_type</i> <i>printf_format</i></pre></blockquote> 76<p>The keyword ARG indicates that the argument is a simple parameter of 77the type specified. For example, a file ID might be logged as:</p> 78<blockquote><pre>ARG fileID int d</pre></blockquote> 79<p>The keyword DBT indicates that the argument is a Berkeley DB DBT structure, 80containing a length and pointer to a byte string. The keyword POINTER 81indicates that the argument is a pointer to the data type specified (of 82course the data type, not the pointer, is what is logged).</p> 83<p>The <i>variable_name</i> is the field name within the structure that 84will be used to refer to this item. The <i>variable_type</i> is 85the C-language type of the variable, and the printf format is the 86C-language format string, without the leading percent ("%") character, 87that should be used to display the contents of the field (for example, 88"s" for string, "d" for signed integral type, "u" for unsigned integral 89type, "ld" for signed long integral type, "lu" for long unsigned 90integral type, and so on).</p> 91<p>For example, ex_apprec.src defines a single log record type, used to 92log a directory name that has been stored in a DBT:</p> 93<blockquote><pre>BEGIN mkdir 10000 94DBT dirname DBT s 95END</pre></blockquote> 96<p>As the name suggests, this example of an application-defined log record 97will be used to log the creation of a directory. There are many more 98examples of XXX.src files in the Berkeley DB distribution. For example, the 99file btree/btree.src contains the definitions for the log records 100supported by the Berkeley DB Btree access method.</p> 101<table width="100%"><tr><td><br></td><td align=right><a href="../apprec/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../apprec/auto.html"><img src="../../images/next.gif" alt="Next"></a> 102</td></tr></table> 103<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 104</body> 105</html> 106