1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Reading and Writing Database Records</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Getting Started with Berkeley DB" /> 10 <link rel="up" href="DBEntry.html" title="Chapter��3.��Database Records" /> 11 <link rel="prev" href="DBEntry.html" title="Chapter��3.��Database Records" /> 12 <link rel="next" href="DbCXXUsage.html" title="Database Usage Example" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Reading and Writing Database Records</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="DBEntry.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��3.��Database Records</th> 23 <td width="20%" align="right">��<a accesskey="n" href="DbCXXUsage.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="usingDbt"></a>Reading and Writing Database Records</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="usingDbt.html#databaseWrite">Writing Records to the Database</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="usingDbt.html#CoreDatabaseRead">Getting Records from the Database</a> 46 </span> 47 </dt> 48 <dt> 49 <span class="sect2"> 50 <a href="usingDbt.html#recordDelete">Deleting Records</a> 51 </span> 52 </dt> 53 <dt> 54 <span class="sect2"> 55 <a href="usingDbt.html#datapersist">Data Persistence</a> 56 </span> 57 </dt> 58 </dl> 59 </div> 60 <p> 61 When reading and writing database records, be aware that there are some 62 slight differences in behavior depending on whether your database supports duplicate 63 records. Two or more database records are considered to be duplicates of 64 one another if they share the same key. The collection of records 65 sharing the same key are called a <span class="emphasis"><em>duplicates set.</em></span> 66 67 <span> 68 In DB, a given key is stored only once for a single duplicates set. 69 </span> 70 </p> 71 <p> 72 By default, DB databases do 73 not support duplicate records. Where duplicate records are supported, 74 cursors (see below) are <span>typically</span> used 75 to access all of the records in the duplicates set. 76 </p> 77 <p> 78 DB provides two basic mechanisms for the storage and retrieval of database 79 key/data pairs: 80 </p> 81 <div class="itemizedlist"> 82 <ul type="disc"> 83 <li> 84 <p> 85 The 86 87 88 <code class="methodname">Db::put()</code> 89 and 90 91 92 <code class="methodname">Db::get()</code> 93 methods provide the easiest access for all non-duplicate records in the database. 94 These methods are described in this section. 95 </p> 96 </li> 97 <li> 98 <p>Cursors provide several methods for putting and getting database 99 records. Cursors and their database access methods are described in 100 <a class="xref" href="Cursors.html" title="Chapter��4.��Using Cursors">Using Cursors</a>.</p> 101 </li> 102 </ul> 103 </div> 104 <div class="sect2" lang="en" xml:lang="en"> 105 <div class="titlepage"> 106 <div> 107 <div> 108 <h3 class="title"><a id="databaseWrite"></a>Writing Records to the Database</h3> 109 </div> 110 </div> 111 </div> 112 <p> 113 Records are stored in the database using whatever organization is 114 required by the access method that you have selected. In some cases (such as 115 BTree), records are stored in a sort order that you may want to define 116 (see <a class="xref" href="btree.html#comparators" title="Setting Comparison Functions">Setting Comparison Functions</a> for more information). 117 </p> 118 <p> 119 In any case, the mechanics of putting and getting database records do not 120 change once you have selected your access method, configured your 121 sorting routines (if any), and opened your database. From your 122 code's perspective, a simple database put and get is largely the 123 same no matter what access method you are using. 124 </p> 125 <p> 126 You use 127 128 <code class="methodname">Db::put()</code> 129 to put, or write, a database record. This method requires you to provide 130 the record's key and data in the form of a pair of 131 132 <span><code class="methodname">Dbt</code> objects.</span> 133 You can also provide one or more flags that control DB's behavior 134 for the database write. 135 </p> 136 <p> 137 Of the flags available to this method, <code class="literal">DB_NOOVERWRITE</code> 138 may be interesting to you. This flag disallows overwriting (replacing) 139 an existing record in the database. If the provided key already exists 140 in the database, then this method returns <code class="literal">DB_KEYEXIST</code> even if 141 the database supports duplicates. 142 </p> 143 <p> 144 For example: 145 </p> 146 <a id="cxx_dbt3"></a> 147 <pre class="programlisting">#include <db_cxx.h> 148#include <string.h> 149 150... 151 152char *description = "Grocery bill."; 153float money = 122.45; 154 155Db my_database(NULL, 0); 156// Database open omitted for clarity 157 158Dbt key(&money, sizeof(float)); 159Dbt data(description, strlen(description) + 1); 160 161int ret = my_database.put(NULL, &key, &data, DB_NOOVERWRITE); 162if (ret == DB_KEYEXIST) { 163 my_database.err(ret, "Put failed because key %f already exists", money); 164}</pre> 165 </div> 166 <div class="sect2" lang="en" xml:lang="en"> 167 <div class="titlepage"> 168 <div> 169 <div> 170 <h3 class="title"><a id="CoreDatabaseRead"></a>Getting Records from the Database</h3> 171 </div> 172 </div> 173 </div> 174 <p> 175 You can use the 176 177 <code class="methodname">Db::get()</code> 178 method to retrieve database records. Note that if your 179 database supports duplicate records, then by default this method will only 180 return the first record in a duplicate set. For this reason, if your 181 database supports duplicates, the common solution is to use a cursor to retrieve 182 records from it. Cursors are described in <a class="xref" href="Cursors.html" title="Chapter��4.��Using Cursors">Using Cursors</a>. 183 </p> 184 <p> 185 (You can also retrieve a set of duplicate records using a bulk get. 186 To do this, you use the <code class="literal">DB_MULTIPLE</code> flag on the 187 call to 188 189 <span><code class="methodname">Db::get()</code>.</span> 190 191 For more information, see the DB Programmer's Reference Guide). 192 </p> 193 <p> 194 By default, 195 196 <code class="methodname">Db::get()</code> 197 returns the first record found whose key matches the key 198 provide on the call to this method. If your database supports 199 duplicate records, you can change this behavior slightly by supplying 200 the <code class="literal">DB_GET_BOTH</code> flag. This flag causes 201 202 <code class="methodname">DB::get()</code> 203 to return the first record that matches the provided key and data. 204 </p> 205 <p> 206 If the specified key and/or data does not exist in the database, this 207 method returns <code class="literal">DB_NOTFOUND</code>. 208 </p> 209 <a id="cxx_dbt4"></a> 210 <pre class="programlisting">#include <db_cxx.h> 211#include <string.h> 212 213... 214 215float money; 216char description[DESCRIPTION_SIZE + 1]; 217 218Db my_database(NULL, 0); 219// Database open omitted for clarity 220 221money = 122.45; 222 223Dbt key, data; 224 225key.set_data(&money); 226key.set_size(sizeof(float)); 227 228data.set_data(description); 229data.set_ulen(DESCRIPTION_SIZE + 1); 230data.set_flags(DB_DBT_USERMEM); 231 232my_database.get(NULL, &key, &data, 0); 233 234// Description is set into the memory that we supplied. </pre> 235 <p> 236 Note that in this example, the 237 <code class="literal">data.size</code> 238 field would be automatically set to the size of the retrieved data. 239 </p> 240 </div> 241 <div class="sect2" lang="en" xml:lang="en"> 242 <div class="titlepage"> 243 <div> 244 <div> 245 <h3 class="title"><a id="recordDelete"></a>Deleting Records</h3> 246 </div> 247 </div> 248 </div> 249 <p> 250 251 You can use the 252 253 254 <code class="methodname">Db::del()</code> 255 method to delete a record from the database. If your database supports 256 duplicate records, then all records associated with the provided key are 257 deleted. To delete just one record from a list of duplicates, use a 258 cursor. Cursors are described in <a class="xref" href="Cursors.html" title="Chapter��4.��Using Cursors">Using Cursors</a>. 259 260 </p> 261 <p> 262 You can also delete every record in the database by using 263 264 265 <code class="methodname">Db::truncate().</code> 266 </p> 267 <p>For example:</p> 268 <a id="cxx_dbt5"></a> 269 <pre class="programlisting">#include <db_cxx.h> 270 271... 272 273Db my_database(NULL, 0); 274// Database open omitted for clarity 275 276float money = 122.45; 277Dbt key(&money, sizeof(float)); 278 279my_database.del(NULL, &key, 0);</pre> 280 </div> 281 <div class="sect2" lang="en" xml:lang="en"> 282 <div class="titlepage"> 283 <div> 284 <div> 285 <h3 class="title"><a id="datapersist"></a>Data Persistence</h3> 286 </div> 287 </div> 288 </div> 289 <p> 290 When you perform a database modification, your modification is made 291 in the in-memory cache. This means that your data modifications 292 are not necessarily flushed to disk, and so your data may not appear 293 in the database after an application restart. 294 </p> 295 <p> 296 Note that as a normal part of closing a database, its cache is 297 written to disk. However, in the event of an application or system 298 failure, there is no guarantee that your databases will close 299 cleanly. In this event, it is possible for you to lose data. Under 300 extremely rare circumstances, it is also possible for you to 301 experience database corruption. 302 </p> 303 <p> 304 Therefore, if you care if your data is durable across system 305 failures, and to guard against the rare possibility of 306 database corruption, you should use transactions to protect your 307 database modifications. Every time you commit a transaction, DB 308 ensures that the data will not be lost due to application or 309 system failure. Transaction usage is described in the 310 311 312 313 314 <span> 315 <em class="citetitle">Berkeley DB Getting Started with Transaction Processing</em> guide. 316 </span> 317 </p> 318 <p> 319 If you do not want to use transactions, then the assumption is that 320 your data is of a nature that it need not exist the next time your 321 application starts. You may want this if, for example, you are using 322 DB to cache data relevant only to the current application 323 runtime. 324 </p> 325 <p> 326 If, however, you are not using transactions for some reason and you 327 still want some guarantee that your database modifications are 328 persistent, then you should periodically 329 330 331 <span>call <code class="methodname">Db::sync()</code>.</span> 332 Syncs cause any dirty entries in the in-memory cache and the 333 operating system's file cache to be written to disk. As 334 such, they are quite expensive and you should use them sparingly. 335 </p> 336 <p> 337 Remember that by default a sync is performed any time a non-transactional 338 database is closed cleanly. (You can override this behavior by 339 specifying 340 <code class="literal">DB_NOSYNC</code> 341 342 on the call to 343 344 <span><code class="methodname">Db::close()</code>.)</span> 345 346 347 That said, you can manually run a sync by calling 348 349 350 <code class="methodname">Db::sync().</code> 351 352 353 </p> 354 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 355 <h3 class="title">Note</h3> 356 <p> 357 If your application or system crashes and you are not using 358 transactions, then you should either discard and recreate your 359 databases, or verify them. You can verify a database using 360 361 <span>Db::verify().</span> 362 363 If your databases do not verify cleanly, use the 364 <span class="command"><strong>db_dump</strong></span> command to salvage as much of the 365 database as is possible. Use either the <code class="literal">-R</code> or 366 <code class="literal">-r</code> command line options to control how 367 aggressive <span class="command"><strong>db_dump</strong></span> should be when salvaging 368 your databases. 369 </p> 370 </div> 371 </div> 372 </div> 373 <div class="navfooter"> 374 <hr /> 375 <table width="100%" summary="Navigation footer"> 376 <tr> 377 <td width="40%" align="left"><a accesskey="p" href="DBEntry.html">Prev</a>��</td> 378 <td width="20%" align="center"> 379 <a accesskey="u" href="DBEntry.html">Up</a> 380 </td> 381 <td width="40%" align="right">��<a accesskey="n" href="DbCXXUsage.html">Next</a></td> 382 </tr> 383 <tr> 384 <td width="40%" align="left" valign="top">Chapter��3.��Database Records��</td> 385 <td width="20%" align="center"> 386 <a accesskey="h" href="index.html">Home</a> 387 </td> 388 <td width="40%" align="right" valign="top">��Database Usage Example</td> 389 </tr> 390 </table> 391 </div> 392 </body> 393</html> 394