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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
|
<?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>Reading and Writing Database Records</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="Getting Started with Berkeley DB" />
<link rel="up" href="DBEntry.html" title="Chapter 3. Database Records" />
<link rel="prev" href="DBEntry.html" title="Chapter 3. Database Records" />
<link rel="next" href="DbCXXUsage.html" title="Database Usage Example" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 12.1.6.1</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Reading and Writing Database Records</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="DBEntry.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. Database Records</th>
<td width="20%" align="right"> <a accesskey="n" href="DbCXXUsage.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="usingDbt"></a>Reading and Writing Database Records</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="usingDbt.html#databaseWrite">Writing Records to the Database</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="usingDbt.html#CoreDatabaseRead">Getting Records from the Database</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="usingDbt.html#recordDelete">Deleting Records</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="usingDbt.html#datapersist">Data Persistence</a>
</span>
</dt>
</dl>
</div>
<p>
When reading and writing database records, be aware that there are some
slight differences in behavior depending on whether your database supports duplicate
records. Two or more database records are considered to be duplicates of
one another if they share the same key. The collection of records
sharing the same key are called a <span class="emphasis"><em>duplicates set.</em></span>
<span>
In DB, a given key is stored only once for a single duplicates set.
</span>
</p>
<p>
By default, DB databases do
not support duplicate records. Where duplicate records are supported,
cursors (see below) are <span>typically</span> used
to access all of the records in the duplicates set.
</p>
<p>
DB provides two basic mechanisms for the storage and retrieval of database
key/data pairs:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
The
<code class="methodname">Db::put()</code>
and
<code class="methodname">Db::get()</code>
methods provide the easiest access for all non-duplicate records in the database.
These methods are described in this section.
</p>
</li>
<li>
<p>Cursors provide several methods for putting and getting database
records. Cursors and their database access methods are described in
<a class="xref" href="Cursors.html" title="Chapter 4. Using Cursors">Using Cursors</a>.</p>
</li>
</ul>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="databaseWrite"></a>Writing Records to the Database</h3>
</div>
</div>
</div>
<p>
Records are stored in the database using whatever organization is
required by the access method that you have selected. In some cases (such as
BTree), records are stored in a sort order that you may want to define
(see <a class="xref" href="btree.html#comparators" title="Setting Comparison Functions">Setting Comparison Functions</a> for more information).
</p>
<p>
In any case, the mechanics of putting and getting database records do not
change once you have selected your access method, configured your
sorting routines (if any), and opened your database. From your
code's perspective, a simple database put and get is largely the
same no matter what access method you are using.
</p>
<p>
You use
<code class="methodname">Db::put()</code>
to put, or write, a database record. This method requires you to provide
the record's key and data in the form of a pair of
<span><code class="methodname">Dbt</code> objects.</span>
You can also provide one or more flags that control DB's behavior
for the database write.
</p>
<p>
Of the flags available to this method, <code class="literal">DB_NOOVERWRITE</code>
may be interesting to you. This flag disallows overwriting (replacing)
an existing record in the database. If the provided key already exists
in the database, then this method returns <code class="literal">DB_KEYEXIST</code> even if
the database supports duplicates.
</p>
<p>
For example:
</p>
<a id="cxx_dbt3"></a>
<pre class="programlisting">#include <db_cxx.h>
#include <string.h>
...
char *description = "Grocery bill.";
float money = 122.45;
Db my_database(NULL, 0);
// Database open omitted for clarity
Dbt key(&money, sizeof(float));
Dbt data(description, strlen(description) + 1);
int ret = my_database.put(NULL, &key, &data, DB_NOOVERWRITE);
if (ret == DB_KEYEXIST) {
my_database.err(ret, "Put failed because key %f already exists",
money);
}</pre>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="CoreDatabaseRead"></a>Getting Records from the Database</h3>
</div>
</div>
</div>
<p>
You can use the
<code class="methodname">Db::get()</code>
method to retrieve database records. Note that if your
database supports duplicate records, then by default this method will only
return the first record in a duplicate set. For this reason, if your
database supports duplicates, the common solution is to use a cursor to retrieve
records from it. Cursors are described in <a class="xref" href="Cursors.html" title="Chapter 4. Using Cursors">Using Cursors</a>.
</p>
<p>
(You can also retrieve a set of duplicate records using a bulk get.
To do this, you use the <code class="literal">DB_MULTIPLE</code> flag on the
call to
<span><code class="methodname">Db::get()</code>.</span>
For more information, see the DB Programmer's Reference Guide).
</p>
<p>
By default,
<code class="methodname">Db::get()</code>
returns the first record found whose key matches the key
provide on the call to this method. If your database supports
duplicate records, you can change this behavior slightly by supplying
the <code class="literal">DB_GET_BOTH</code> flag. This flag causes
<code class="methodname">DB::get()</code>
to return the first record that matches the provided key and data.
</p>
<p>
If the specified key and/or data does not exist in the database, this
method returns <code class="literal">DB_NOTFOUND</code>.
</p>
<a id="cxx_dbt4"></a>
<pre class="programlisting">#include <db_cxx.h>
#include <string.h>
...
#define DESCRIPTION_SIZE 199
float money;
char description[DESCRIPTION_SIZE + 1];
Db my_database(NULL, 0);
// Database open omitted for clarity
money = 122.45;
Dbt key, data;
key.set_data(&money);
key.set_size(sizeof(float));
data.set_data(description);
data.set_ulen(DESCRIPTION_SIZE + 1);
data.set_flags(DB_DBT_USERMEM);
my_database.get(NULL, &key, &data, 0);
// Description is set into the memory that we supplied. </pre>
<p>
Note that in this example, the
<code class="literal">data.size</code>
field would be automatically set to the size of the retrieved data.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="recordDelete"></a>Deleting Records</h3>
</div>
</div>
</div>
<p>
You can use the
<code class="methodname">Db::del()</code>
method to delete a record from the database. If your database supports
duplicate records, then all records associated with the provided key are
deleted. To delete just one record from a list of duplicates, use a
cursor. Cursors are described in <a class="xref" href="Cursors.html" title="Chapter 4. Using Cursors">Using Cursors</a>.
</p>
<p>
You can also delete every record in the database by using
<code class="methodname">Db::truncate().</code>
</p>
<p>For example:</p>
<a id="cxx_dbt5"></a>
<pre class="programlisting">#include <db_cxx.h>
...
Db my_database(NULL, 0);
// Database open omitted for clarity
float money = 122.45;
Dbt key(&money, sizeof(float));
my_database.del(NULL, &key, 0);</pre>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="datapersist"></a>Data Persistence</h3>
</div>
</div>
</div>
<p>
When you perform a database modification, your modification is made
in the in-memory cache. This means that your data modifications
are not necessarily flushed to disk, and so your data may not appear
in the database after an application restart.
</p>
<p>
Note that as a normal part of closing a database, its cache is
written to disk. However, in the event of an application or system
failure, there is no guarantee that your databases will close
cleanly. In this event, it is possible for you to lose data. Under
extremely rare circumstances, it is also possible for you to
experience database corruption.
</p>
<p>
Therefore, if you care if your data is durable across system
failures, and to guard against the rare possibility of
database corruption, you should use transactions to protect your
database modifications. Every time you commit a transaction, DB
ensures that the data will not be lost due to application or
system failure. Transaction usage is described in the
<span>
<em class="citetitle">Berkeley DB Getting Started with Transaction Processing</em> guide.
</span>
</p>
<p>
If you do not want to use transactions, then the assumption is that
your data is of a nature that it need not exist the next time your
application starts. You may want this if, for example, you are using
DB to cache data relevant only to the current application
runtime.
</p>
<p>
If, however, you are not using transactions for some reason and you
still want some guarantee that your database modifications are
persistent, then you should periodically
<span>call <code class="methodname">Db::sync()</code>.</span>
Syncs cause any dirty entries in the in-memory cache and the
operating system's file cache to be written to disk. As
such, they are quite expensive and you should use them sparingly.
</p>
<p>
Remember that by default a sync is performed any time a non-transactional
database is closed cleanly. (You can override this behavior by
specifying
<code class="literal">DB_NOSYNC</code>
on the call to
<span><code class="methodname">Db::close()</code>.)</span>
That said, you can manually run a sync by calling
<code class="methodname">Db::sync().</code>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
If your application or system crashes and you are not using
transactions, then you should either discard and recreate your
databases, or verify them. You can verify a database using
<span>Db::verify().</span>
If your databases do not verify cleanly, use the
<span class="command"><strong>db_dump</strong></span> command to salvage as much of the
database as is possible. Use either the <code class="literal">-R</code> or
<code class="literal">-r</code> command line options to control how
aggressive <span class="command"><strong>db_dump</strong></span> should be when salvaging
your databases.
</p>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="DBEntry.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="DBEntry.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="DbCXXUsage.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 3. Database Records </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Database Usage Example</td>
</tr>
</table>
</div>
</body>
</html>
|
