1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
<?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 14. 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 11.2.5.3</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 14.
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
<p></p>
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>
|
