1<!--$Id: auto.so,v 10.6 2008/01/19 14:12:58 bostic 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: Automatically generated functions</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/def.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/apprec/config.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Automatically generated functions</b></p> 16<p>The XXX.src file is processed using the gen_rec.awk script included in 17the dist directory of the Berkeley DB distribution. This is an awk script 18that is executed from with the following command line:</p> 19<blockquote><pre>awk -f gen_rec.awk \ 20 -v source_file=<i>C_FILE</i> \ 21 -v header_file=<i>H_FILE</i> \ 22 -v print_file=<i>P_FILE</i> \ 23 -v template_file=<i>TMP_FILE</i> < XXX.src</pre></blockquote> 24<p>where <i>C_FILE</i> is the name of the file into which to place the 25automatically generated C code, <i>H_FILE</i> is the name of the 26file into which to place the automatically generated data structures 27and declarations, <i>P_FILE</i> is the name of the file into which to 28place the automatically generated C code that prints log records, 29and <i>TMP_FILE</i> is the name of the file into 30which to place a template for the recovery routines.</p> 31<p>Because the gen_rec.awk script uses sources files located relative to 32the Berkeley DB dist directory, it must be run from the dist directory. For 33example, in building the Berkeley DB logging and recovery routines for 34ex_apprec, the following script is used to rebuild the automatically 35generated files:</p> 36<blockquote><pre>E=/examples_c/ex_apprec 37<p> 38cd /dist 39awk -f gen_rec.awk \ 40 -v source_file=$E/ex_apprec_auto.c \ 41 -v header_file=$E/ex_apprec_auto.h \ 42 -v print_file=$E/ex_apprec_autop.c \ 43 -v template_file=$E/ex_apprec_template < $E/ex_apprec.src</pre></blockquote> 44<p>For each log record description found in the XXX.src file, the following 45structure declarations and #defines will be created in the file 46<i>header_file</i>:</p> 47<blockquote><pre>#define DB_PREFIX_RECORD_TYPE /* Integer ID number */ 48<p> 49typedef struct _PREFIX_RECORD_TYPE_args { 50 /* 51 * These three fields are generated for every record. 52 */ 53 u_int32_t type; /* Record type used for dispatch. */ 54<p> 55 /* 56 * Transaction handle that identifies the transaction on whose 57 * behalf the record is being logged. 58 */ 59 DB_TXN *txnid; 60<p> 61 /* 62 * The log sequence number returned by the previous call to log_put 63 * for this transaction. 64 */ 65 DB_LSN *prev_lsn; 66<p> 67 /* 68 * The rest of the structure contains one field for each of 69 * the entries in the record statement. 70 */ 71};</pre></blockquote> 72<p>Thus, the auto-generated ex_apprec_mkdir_args structure looks as follows:</p> 73<blockquote><pre>typedef struct _ex_apprec_mkdir_args { 74 u_int32_t type; 75 DB_TXN *txnid; 76 DB_LSN prev_lsn; 77 DBT dirname; 78} ex_apprec_mkdir_args;</pre></blockquote> 79<p>The template_file will contain a template for a recovery function. The 80recovery function is called on each record read from the log during 81system recovery, transaction abort, or the application of log records 82on a replication client, and is expected to redo or undo the operations 83described by that record. The details of the recovery function will be 84specific to the record being logged and need to be written manually, but 85the template provides a good starting point. (See ex_apprec_template 86and ex_apprec_rec.c for an example of both the template produced and the 87resulting recovery function.)</p> 88<p>The template file should be copied to a source file in the application 89(but not the automatically generated source_file, as that will get 90overwritten each time gen_rec.awk is run) and fully developed there. 91The recovery function takes the following parameters:</p> 92<blockquote><br> 93<b>dbenv</b><ul compact><li>The environment in which recovery is running.</ul> 94<b>rec</b><ul compact><li>The record being recovered.</ul> 95<b>lsn</b><ul compact><li>The log sequence number of the record being recovered. The 96prev_lsn field, automatically included in every auto-generated log 97record, should be returned through this argument. The prev_lsn field 98is used to chain log records together to allow transaction aborts; 99because the recovery function is the only place that a log record gets 100parsed, the responsibility for returning this value lies with the 101recovery function writer.</ul> 102<b>op</b><ul compact><li>A parameter of type db_recops, which indicates what operation is being 103run (<a href="/api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a>, <a href="/api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a>, <a href="/api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a>, 104<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_PRINT">DB_TXN_PRINT</a>).</ul> 105<br></blockquote> 106<p>In addition to the header_file and template_file, a source_file is 107created, containing a log, read, recovery, and print function for each 108record type.</p> 109<p>The log function marshalls the parameters into a buffer, and calls 110<a href="/api_c/log_put.html">DB_ENV->log_put</a> on that buffer returning 0 on success and non-zero on 111failure. The log function takes the following parameters:</p> 112<blockquote><br> 113<b>dbenv</b><ul compact><li>The environment in which recovery is running.</ul> 114<b>txnid</b><ul compact><li>The transaction identifier for the transaction handle returned by 115<a href="/api_c/txn_begin.html">DB_ENV->txn_begin</a>.</ul> 116<b>lsnp</b><ul compact><li>A pointer to storage for a log sequence number into which the log 117sequence number of the new log record will be returned.</ul> 118<b>syncflag</b><ul compact><li>A flag indicating whether the record must be written synchronously. 119Valid values are 0 and <a href="/api_c/log_put.html#DB_FLUSH">DB_FLUSH</a>.</ul> 120<b>args</b><ul compact><li>The remaining parameters to the log message are the fields described 121in the XXX.src file, in order.</ul> 122<br></blockquote> 123<p>The read function takes a buffer and unmarshalls its contents into a 124structure of the appropriate type. It returns 0 on success and non-zero 125on error. After the fields of the structure have been used, the pointer 126returned from the read function should be freed. The read function 127takes the following parameters:</p> 128<blockquote><br> 129<b>dbenv</b><ul compact><li>The environment in which recovery is running.</ul> 130<b>recbuf</b><ul compact><li>A buffer.</ul> 131<b>argp</b><ul compact><li>A pointer to a structure of the appropriate type.</ul> 132<br></blockquote> 133<p>The print function displays the contents of the record. The print 134function takes the same parameters as the recovery function described 135previously. Although some of the parameters are unused by the print 136function, taking the same parameters allows a single dispatch loop to 137dispatch to a variety of functions. The print function takes the 138following parameters:</p> 139<blockquote><br> 140<b>dbenv</b><ul compact><li>The environment in which recovery is running.</ul> 141<b>rec</b><ul compact><li>The record being recovered.</ul> 142<b>lsn</b><ul compact><li>The log sequence number of the record being recovered.</ul> 143<b>op</b><ul compact><li>Unused.</ul> 144<br></blockquote> 145<p>Finally, the source file will contain a function (named XXX_init_print, 146where XXX is replaced by the prefix) which should be added to the 147initialization part of the standalone <a href="/utility/db_printlog.html">db_printlog</a> utility code 148so that utility can be used to display application-specific log records.</p> 149<table width="100%"><tr><td><br></td><td align=right><a href="/apprec/def.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/apprec/config.html"><img src="/images/next.gif" alt="Next"></a> 150</td></tr></table> 151<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 152</body> 153</html> 154
