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