mirror of
https://github.com/yasuhirokimura/db18
synced 2026-06-08 18:29:23 +00:00
Yasuhiro KIMURA
351 lines
14 KiB
HTML
351 lines
14 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Automatically generated functions</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
|
||
<link rel="up" href="apprec.html" title="Chapter 15. Application Specific Logging and Recovery" />
|
||
<link rel="prev" href="apprec_def.html" title="Defining application-specific log records" />
|
||
<link rel="next" href="apprec_config.html" title="Application configuration" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 18.1.40</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Automatically generated
|
||
functions</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="apprec_def.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 15. Application Specific Logging and
|
||
Recovery </th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="apprec_config.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="apprec_auto"></a>Automatically generated
|
||
functions</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The XXX.src file is processed using the gen_rec.awk script
|
||
included in the dist directory of the Berkeley DB
|
||
distribution. This is an awk script that is executed from with
|
||
the following command line:
|
||
</p>
|
||
<pre class="programlisting">awk -f gen_rec.awk \
|
||
-v source_file=<span class="emphasis"><em>C_FILE</em></span> \
|
||
-v header_file=<span class="emphasis"><em>H_FILE</em></span> \
|
||
-v print_file=<span class="emphasis"><em>P_FILE</em></span> \
|
||
-v template_file=<span class="emphasis"><em>TMP_FILE</em></span> < XXX.src</pre>
|
||
<p>
|
||
where <span class="emphasis"><em>C_FILE</em></span> is the name of the file
|
||
into which to place the automatically generated C code,
|
||
<span class="emphasis"><em>H_FILE</em></span> is the name of the file into
|
||
which to place the automatically generated data structures and
|
||
declarations, <span class="emphasis"><em>P_FILE</em></span> is the name of the
|
||
file into which to place the automatically generated C code
|
||
that prints log records, and <span class="emphasis"><em>TMP_FILE</em></span> is
|
||
the name of the file into which to place a template for the
|
||
recovery routines.
|
||
</p>
|
||
<p>
|
||
Because the gen_rec.awk script uses sources files located
|
||
relative to the Berkeley DB dist directory, it must be run
|
||
from the dist directory. For example, in building the Berkeley
|
||
DB logging and recovery routines for ex_apprec, the following
|
||
script is used to rebuild the automatically generated
|
||
files:
|
||
</p>
|
||
<pre class="programlisting">E=../examples/c/ex_apprec
|
||
|
||
cd ../../dist
|
||
awk -f gen_rec.awk \
|
||
-v source_file=$E/ex_apprec_auto.c \
|
||
-v header_file=$E/ex_apprec_auto.h \
|
||
-v print_file=$E/ex_apprec_autop.c \
|
||
-v template_file=$E/ex_apprec_template < $E/ex_apprec.src</pre>
|
||
<p>
|
||
For each log record description found in the XXX.src file,
|
||
the following structure declarations and #defines will be
|
||
created in the file <span class="emphasis"><em>header_file</em></span>:
|
||
</p>
|
||
<pre class="programlisting">#define DB_PREFIX_RECORD_TYPE /* Integer ID number */
|
||
|
||
typedef struct _PREFIX_RECORD_TYPE_args {
|
||
/*
|
||
* These three fields are generated for every record.
|
||
*/
|
||
u_int32_t type; /* Record type used for dispatch. */
|
||
|
||
/*
|
||
* Transaction handle that identifies the transaction on whose
|
||
* behalf the record is being logged.
|
||
*/
|
||
DB_TXN *txnid;
|
||
|
||
/*
|
||
* The log sequence number returned by the previous call to log_put
|
||
* for this transaction.
|
||
*/
|
||
DB_LSN *prev_lsn;
|
||
|
||
/*
|
||
* The rest of the structure contains one field for each of
|
||
* the entries in the record statement.
|
||
*/
|
||
};</pre>
|
||
<p>
|
||
Thus, the auto-generated ex_apprec_mkdir_args structure
|
||
looks as follows:
|
||
</p>
|
||
<pre class="programlisting">typedef struct _ex_apprec_mkdir_args {
|
||
u_int32_t type;
|
||
DB_TXN *txnid;
|
||
DB_LSN prev_lsn;
|
||
DBT dirname;
|
||
} ex_apprec_mkdir_args;</pre>
|
||
<p>
|
||
The template_file will contain a template for a recovery
|
||
function. The recovery function is called on each record read
|
||
from the log during system recovery, transaction abort, or the
|
||
application of log records on a replication client, and is
|
||
expected to redo or undo the operations described by that
|
||
record. The details of the recovery function will be specific
|
||
to the record being logged and need to be written manually,
|
||
but the template provides a good starting point. (See
|
||
ex_apprec_template and ex_apprec_rec.c for an example of both
|
||
the template produced and the resulting recovery
|
||
function.)
|
||
</p>
|
||
<p>
|
||
The template file should be copied to a source file in the
|
||
application (but not the automatically generated source_file,
|
||
as that will get overwritten each time gen_rec.awk is run) and
|
||
fully developed there. The recovery function takes the
|
||
following parameters:
|
||
</p>
|
||
<div class="blockquote">
|
||
<blockquote class="blockquote">
|
||
<div class="variablelist">
|
||
<dl>
|
||
<dt>
|
||
<span class="term">dbenv</span>
|
||
</dt>
|
||
<dd>
|
||
The environment in which recovery is
|
||
running.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">rec</span>
|
||
</dt>
|
||
<dd>
|
||
The record being recovered.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">lsn</span>
|
||
</dt>
|
||
<dd>
|
||
The log sequence number of the record being
|
||
recovered. The prev_lsn field, automatically
|
||
included in every auto-generated log record,
|
||
should be returned through this argument. The
|
||
prev_lsn field is used to chain log records
|
||
together to allow transaction aborts; because the
|
||
recovery function is the only place that a log
|
||
record gets parsed, the responsibility for
|
||
returning this value lies with the recovery
|
||
function writer.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">op</span>
|
||
</dt>
|
||
<dd>
|
||
A parameter of type db_recops, which
|
||
indicates what operation is being run
|
||
(<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_ABORT" class="olink">DB_TXN_ABORT</a>, <a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_APPLY" class="olink">DB_TXN_APPLY</a>,
|
||
<a href="../api_reference/C/envset_app_dispatch.html#set_app_dispatch_DB_TXN_BACKWARD_ROLL" class="olink">DB_TXN_BACKWARD_ROLL</a>, <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_PRINT" class="olink">DB_TXN_PRINT</a>).
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</blockquote>
|
||
</div>
|
||
<p>
|
||
In addition to the header_file and template_file, a
|
||
source_file is created, containing a log, read, recovery, and
|
||
print function for each record type.
|
||
</p>
|
||
<p>
|
||
The log function marshalls the parameters into a buffer, and
|
||
calls <a href="../api_reference/C/logput.html" class="olink">DB_ENV->log_put()</a> on that buffer returning 0 on success and
|
||
non-zero on failure. The log function takes the following
|
||
parameters:
|
||
</p>
|
||
<div class="blockquote">
|
||
<blockquote class="blockquote">
|
||
<div class="variablelist">
|
||
<dl>
|
||
<dt>
|
||
<span class="term">dbenv</span>
|
||
</dt>
|
||
<dd>The environment in which recovery is
|
||
running.</dd>
|
||
<dt>
|
||
<span class="term">txnid</span>
|
||
</dt>
|
||
<dd>
|
||
The transaction identifier for the
|
||
transaction handle returned by
|
||
<a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a>.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">lsnp</span>
|
||
</dt>
|
||
<dd>
|
||
A pointer to storage for a log sequence
|
||
number into which the log sequence number of the
|
||
new log record will be returned.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">syncflag</span>
|
||
</dt>
|
||
<dd>
|
||
A flag indicating whether the record must be
|
||
written synchronously. Valid values are 0 and
|
||
<a href="../api_reference/C/logput.html#put_DB_FLUSH" class="olink">DB_FLUSH</a>.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">args</span>
|
||
</dt>
|
||
<dd>
|
||
The remaining parameters to the log message
|
||
are the fields described in the XXX.src file, in
|
||
order.
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</blockquote>
|
||
</div>
|
||
<p>
|
||
The read function takes a buffer and unmarshalls its
|
||
contents into a structure of the appropriate type. It returns
|
||
0 on success and non-zero on error. After the fields of the
|
||
structure have been used, the pointer returned from the read
|
||
function should be freed. The read function takes the
|
||
following parameters:
|
||
</p>
|
||
<div class="blockquote">
|
||
<blockquote class="blockquote">
|
||
<div class="variablelist">
|
||
<dl>
|
||
<dt>
|
||
<span class="term">dbenv</span>
|
||
</dt>
|
||
<dd>
|
||
The environment in which recovery is
|
||
running.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">recbuf</span>
|
||
</dt>
|
||
<dd>
|
||
A buffer.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">argp</span>
|
||
</dt>
|
||
<dd>
|
||
A pointer to a structure of the appropriate
|
||
type.
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</blockquote>
|
||
</div>
|
||
<p>
|
||
The print function displays the contents of the record. The
|
||
print function takes the same parameters as the recovery
|
||
function described previously. Although some of the parameters
|
||
are unused by the print function, taking the same parameters
|
||
allows a single dispatch loop to dispatch to a variety of
|
||
functions. The print function takes the following
|
||
parameters:
|
||
</p>
|
||
<div class="blockquote">
|
||
<blockquote class="blockquote">
|
||
<div class="variablelist">
|
||
<dl>
|
||
<dt>
|
||
<span class="term">dbenv</span>
|
||
</dt>
|
||
<dd>
|
||
The environment in which recovery is
|
||
running.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">rec</span>
|
||
</dt>
|
||
<dd>
|
||
The record being recovered.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">lsn</span>
|
||
</dt>
|
||
<dd>
|
||
The log sequence number of the record being
|
||
recovered.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">op</span>
|
||
</dt>
|
||
<dd>
|
||
Unused.
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</blockquote>
|
||
</div>
|
||
<p>
|
||
Finally, the source file will contain a function (named
|
||
XXX_init_print, where XXX is replaced by the prefix) which
|
||
should be added to the initialization part of the standalone
|
||
<a href="../api_reference/C/db_printlog.html" class="olink">db_printlog</a> utility code so that utility can be used to display
|
||
application-specific log records.
|
||
</p>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="apprec_def.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="apprec.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="apprec_config.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Defining application-specific log
|
||
records </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Application configuration</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|