← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/ref/apprec/auto.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

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