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>Getting Records Using the Cursor</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="Cursors.html" title="Chapter��4.��Using Cursors" /> 11 <link rel="prev" href="Cursors.html" title="Chapter��4.��Using Cursors" /> 12 <link rel="next" href="PutEntryWCursor.html" title="Putting Records Using Cursors" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Getting Records Using the Cursor</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="Cursors.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��4.��Using Cursors</th> 23 <td width="20%" align="right">��<a accesskey="n" href="PutEntryWCursor.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="Positioning"></a>Getting Records Using the Cursor</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="Positioning.html#cursorsearch">Searching for Records</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="Positioning.html#getdups">Working with Duplicate Records</a> 46 </span> 47 </dt> 48 </dl> 49 </div> 50 <p> 51 To iterate over database records, from the first record to 52 the last, simply open the cursor and then use the 53 54 <code class="methodname">DBC->get()</code> 55 56 method. 57 <span>Note that you need to supply the 58 <code class="literal">DB_NEXT</code> flag to this method.</span> 59 For example: 60 </p> 61 <a id="c_cursor3"></a> 62 <pre class="programlisting">#include <db.h> 63#include <string.h> 64 65... 66 67DB *my_database; 68DBC *cursorp; 69DBT key, data; 70int ret; 71 72/* Database open omitted for clarity */ 73 74/* Get a cursor */ 75my_database->cursor(my_database, NULL, &cursorp, 0); 76 77/* Initialize our DBTs. */ 78memset(&key, 0, sizeof(DBT)); 79memset(&data, 0, sizeof(DBT)); 80 81/* Iterate over the database, retrieving each record in turn. */ 82while ((ret = cursorp->get(cursorp, &key, &data, DB_NEXT)) == 0) { 83 /* Do interesting things with the DBTs here. */ 84} 85if (ret != DB_NOTFOUND) { 86 /* Error handling goes here */ 87} 88 89/* Cursors must be closed */ 90if (cursorp != NULL) 91 cursorp->close(cursorp); 92 93if (my_database != NULL) 94 my_database->close(my_database, 0);</pre> 95 <p> 96 To iterate over the database from the last record to the first, use 97 <code class="literal">DB_PREV</code> instead of <code class="literal">DB_NEXT</code>: 98 </p> 99 <a id="c_cursor4"></a> 100 <pre class="programlisting">#include <db.h> 101#include <string.h> 102 103... 104 105DB *my_database; 106DBC *cursorp; 107DBT key, data; 108int ret; 109 110/* Database open omitted for clarity */ 111 112/* Get a cursor */ 113my_database->cursor(my_database, NULL, &cursorp, 0); 114 115/* Initialize our DBTs. */ 116memset(&key, 0, sizeof(DBT)); 117memset(&data, 0, sizeof(DBT)); 118 119/* Iterate over the database, retrieving each record in turn. */ 120while ((ret = cursorp->get(cursorp, &key, 121 &data, DB_PREV)) == 0) { 122 /* Do interesting things with the DBTs here. */ 123} 124if (ret != DB_NOTFOUND) { 125 /* Error handling goes here */ 126} 127 128// Cursors must be closed 129if (cursorp != NULL) 130 cursorp->close(cursorp); 131 132if (my_database != NULL) 133 my_database->close(my_database, 0);</pre> 134 <div class="sect2" lang="en" xml:lang="en"> 135 <div class="titlepage"> 136 <div> 137 <div> 138 <h3 class="title"><a id="cursorsearch"></a>Searching for Records</h3> 139 </div> 140 </div> 141 </div> 142 <p> 143 You can use cursors to search for database records. You can search based 144 on just a key, or you can search based on both the key and the data. 145 You can also perform partial matches if your database supports sorted 146 duplicate sets. In all cases, the key and data parameters of these 147 methods are filled with the key and data values of the database record 148 to which the cursor is positioned as a result of the search. 149 </p> 150 <p> 151 Also, if the search fails, then cursor's state is left unchanged 152 and 153 154 <code class="literal">DB_NOTFOUND</code> 155 is returned. 156 157 158 </p> 159 <p> 160 To use a cursor to search for a record, use 161 <span>DBT->get()<code class="methodname"></code>.</span> 162 163 When you use this method, you can provide the following flags: 164 </p> 165 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 166 <h3 class="title">Note</h3> 167 <p> 168 Notice in the following list that the cursor flags use the 169 keyword <code class="literal">SET</code> when the cursor examines just the key 170 portion of the records (in this case, the cursor is set to the 171 record whose key matches the value provided to the cursor). 172 Moreover, when the cursor uses the keyword <code class="literal">GET</code>, 173 then the cursor is positioned to both the key 174 <span class="emphasis"><em>and</em></span> the data values provided to the cursor. 175 </p> 176 <p> 177 Regardless of the keyword you use to get a record with a cursor, the 178 cursor's key and data 179 <span><code class="classname">DBT</code>s</span> 180 181 are filled with the data retrieved from the record to which the 182 cursor is positioned. 183 </p> 184 </div> 185 <div class="itemizedlist"> 186 <ul type="disc"> 187 <li> 188 <p> 189 190 <code class="literal">DB_SET</code> 191 </p> 192 <p> 193 Moves the cursor to the first record in the database with 194 the specified key. 195 </p> 196 </li> 197 <li> 198 <p> 199 200 <code class="literal">DB_SET_RANGE</code> 201 </p> 202 <p> 203 <span>Identical to 204 <code class="literal">DB_SET</code> 205 206 unless you are using the BTree access. In this case, the cursor 207 moves</span> 208 209 210 to the first record in the database whose 211 key is greater than or equal to the specified key. This comparison 212 is determined by the 213 214 <span>comparison function</span> 215 that you provide for the database. If no 216 217 <span>comparison function</span> 218 is provided, then the default 219 220 lexicographical sorting is used. 221 </p> 222 <p> 223 For example, suppose you have database records that use the 224 following 225 226 <span>strings</span> 227 as keys: 228 </p> 229 <pre class="programlisting">Alabama 230Alaska 231Arizona</pre> 232 <p> 233 Then providing a search key of <code class="literal">Alaska</code> moves the 234 cursor to the second key noted above. Providing a key of 235 <code class="literal">Al</code> moves the cursor to the first key (<code class="literal">Alabama</code>), providing 236 a search key of <code class="literal">Alas</code> moves the cursor to the second key 237 (<code class="literal">Alaska</code>), and providing a key of <code class="literal">Ar</code> moves the 238 cursor to the last key (<code class="literal">Arizona</code>). 239 </p> 240 </li> 241 <li> 242 <p> 243 244 <code class="literal">DB_GET_BOTH</code> 245 </p> 246 <p> 247 Moves the cursor to the first record in the database that uses 248 the specified key and data. 249 </p> 250 </li> 251 <li> 252 <p> 253 254 <code class="literal">DB_GET_BOTH_RANGE</code> 255 </p> 256 <p> 257 Moves the cursor to the first record in the database whose key matches the specified 258 key and whose data is 259 greater than or equal to the specified data. If the database supports 260 duplicate records, then on matching the key, the cursor is moved to 261 the duplicate record with the smallest data that is greater than or 262 equal to the specified data. 263 </p> 264 <p> 265 For example, 266 267 <span>suppose your database uses BTree 268 and it has </span> 269 database records that use the following key/data pairs: 270 </p> 271 <pre class="programlisting">Alabama/Athens 272Alabama/Florence 273Alaska/Anchorage 274Alaska/Fairbanks 275Arizona/Avondale 276Arizona/Florence </pre> 277 <p>then providing:</p> 278 <div class="informaltable"> 279 <table border="1" width="80%"> 280 <colgroup> 281 <col /> 282 <col /> 283 <col /> 284 </colgroup> 285 <thead> 286 <tr> 287 <th>a search key of ...</th> 288 <th>and a search data of ...</th> 289 <th>moves the cursor to ...</th> 290 </tr> 291 </thead> 292 <tbody> 293 <tr> 294 <td>Alaska</td> 295 <td>Fa</td> 296 <td>Alaska/Fairbanks</td> 297 </tr> 298 <tr> 299 <td>Arizona</td> 300 <td>Fl</td> 301 <td>Arizona/Florence</td> 302 </tr> 303 <tr> 304 <td>Alaska</td> 305 <td>An</td> 306 <td>Alaska/Anchorage</td> 307 </tr> 308 </tbody> 309 </table> 310 </div> 311 </li> 312 </ul> 313 </div> 314 <p> 315 For example, assuming a database containing sorted duplicate records of 316 U.S. States/U.S Cities key/data pairs (both as 317 318 <span>strings),</span> 319 then the following code fragment can be used to position the cursor 320 to any record in the database and print its key/data values: 321 322 </p> 323 <a id="c_cursor5"></a> 324 <pre class="programlisting">#include <db.h> 325#include <string.h> 326 327... 328 329DBC *cursorp; 330DBT key, data; 331DB *dbp; 332int ret; 333char *search_data = "Fa"; 334char *search_key = "Alaska"; 335 336/* database open omitted for clarity */ 337 338/* Get a cursor */ 339dbp->cursor(dbp, NULL, &cursorp, 0); 340 341/* Set up our DBTs */ 342key.data = search_key; 343key.size = strlen(search_key) + 1; 344data.data = search_data; 345data.size = strlen(search_data) + 1; 346 347/* 348 * Position the cursor to the first record in the database whose 349 * key matches the search key and whose data begins with the 350 * search data. 351 */ 352ret = cursorp->get(cursorp, &key, &data, DB_GET_BOTH_RANGE); 353if (!ret) { 354 /* Do something with the data */ 355} else { 356 /* Error handling goes here */ 357} 358 359/* Close the cursor */ 360if (cursorp != NULL) 361 cursorp->close(cursorp); 362 363/* Close the database */ 364if (dbp != NULL) 365 dbp->close(dbp, 0); </pre> 366 </div> 367 <div class="sect2" lang="en" xml:lang="en"> 368 <div class="titlepage"> 369 <div> 370 <div> 371 <h3 class="title"><a id="getdups"></a>Working with Duplicate Records</h3> 372 </div> 373 </div> 374 </div> 375 <p> 376 A record is a duplicate of another record if the two records share the 377 same key. For duplicate records, only the data portion of the record is unique. 378 </p> 379 <p> 380 Duplicate records are supported only for the BTree or Hash access methods. 381 For information on configuring your database to use duplicate records, 382 see <a class="xref" href="btree.html#duplicateRecords" title="Allowing Duplicate Records">Allowing Duplicate Records</a>. 383 </p> 384 <p> 385 If your database supports duplicate records, then it can potentially 386 contain multiple records that share the same key. 387 388 389 390 <span>By default, normal database 391 get operations will only return the first such record in a set 392 of duplicate records. Typically, subsequent duplicate records are 393 accessed using a cursor. 394 </span> 395 396 The following 397 398 <span><code class="methodname">DBC->get()</code> flags</span> 399 400 are interesting when working with databases that support duplicate records: 401 </p> 402 <div class="itemizedlist"> 403 <ul type="disc"> 404 <li> 405 <p> 406 407 <span> 408 <code class="literal">DB_NEXT</code>, 409 <code class="literal">DB_PREV</code> 410 </span> 411 </p> 412 <p> 413 Shows the next/previous record in the database, regardless of 414 whether it is a duplicate of the current record. For an example of 415 using these methods, see <a class="xref" href="Positioning.html" title="Getting Records Using the Cursor">Getting Records Using the Cursor</a>. 416 </p> 417 </li> 418 <li> 419 <p> 420 421 <code class="literal">DB_GET_BOTH_RANGE</code> 422 </p> 423 <p> 424 Useful for seeking the cursor to a specific record, regardless of 425 whether it is a duplicate record. See <a class="xref" href="Positioning.html#cursorsearch" title="Searching for Records">Searching for Records</a> for more 426 information. 427 </p> 428 </li> 429 <li> 430 <p> 431 432 <span> 433 <code class="literal">DB_NEXT_NODUP</code>, 434 <code class="literal">DB_PREV_NODUP</code> 435 </span> 436 </p> 437 <p> 438 Gets the next/previous non-duplicate record in the database. This 439 allows you to skip over all the duplicates in a set of duplicate 440 records. If you call 441 442 <span> 443 <code class="methodname">DBC->get()</code> 444 445 with <code class="literal">DB_PREV_NODUP</code>, 446 </span> 447 then the cursor is positioned to the last record for the previous 448 key in the database. For example, if you have the following records 449 in your database: 450 </p> 451 <pre class="programlisting">Alabama/Athens 452Alabama/Florence 453Alaska/Anchorage 454Alaska/Fairbanks 455Arizona/Avondale 456Arizona/Florence</pre> 457 <p> 458 and your cursor is positioned to <code class="literal">Alaska/Fairbanks</code>, 459 and you then call 460 461 <span> 462 <code class="methodname">DBC->get()</code> 463 464 with <code class="literal">DB_PREV_NODUP</code>, 465 </span> 466 then the cursor is positioned to Alabama/Florence. Similarly, if 467 you call 468 469 <span> 470 <code class="methodname">DBC->get()</code> 471 472 with <code class="literal">DB_NEXT_NODUP</code>, 473 </span> 474 475 then the cursor is positioned to the first record corresponding to 476 the next key in the database. 477 </p> 478 <p> 479 If there is no next/previous key in the database, then 480 481 <code class="literal">DB_NOTFOUND</code> 482 is returned, and the cursor is left unchanged. 483 </p> 484 </li> 485 <li> 486 <p> 487 488 <code class="literal">DB_NEXT_DUP</code> 489 </p> 490 <p> 491 492 Gets the 493 494 <span>next</span> 495 record that shares the current key. If the 496 cursor is positioned at the last record in the duplicate set and 497 you call 498 499 <span> 500 <code class="methodname">DBC->get()</code> 501 502 with <code class="literal">DB_NEXT_DUP</code>, 503 </span> 504 505 then 506 507 <code class="literal">DB_NOTFOUND</code> 508 is returned and the cursor is left unchanged. 509 510 </p> 511 </li> 512 </ul> 513 </div> 514 <p> 515 For example, the following code fragment positions a cursor to a key 516 517 518 519 <span>and displays it and all its 520 duplicates.</span> 521 522 523 </p> 524 <a id="c_cursor6"></a> 525 <pre class="programlisting">#include <db.h> 526#include <string.h> 527 528... 529 530DB *dbp; 531DBC *cursorp; 532DBT key, data; 533int ret; 534char *search_key = "Al"; 535 536/* database open omitted for clarity */ 537 538/* Get a cursor */ 539dbp->cursor(dbp, NULL, &cursorp, 0); 540 541/* Set up our DBTs */ 542key.data = search_key; 543key.size = strlen(search_key) + 1; 544 545/* 546 * Position the cursor to the first record in the database whose 547 * key and data begin with the correct strings. 548 */ 549ret = cursorp->get(cursorp, &key, &data, DB_SET); 550while (ret != DB_NOTFOUND) { 551 printf("key: %s, data: %s\n", (char *)key.data, (char *)data.data); 552 ret = cursorp->get(cursorp, &key, &data, DB_NEXT_DUP); 553} 554 555/* Close the cursor */ 556if (cursorp != NULL) 557 cursorp->close(cursorp); 558 559/* Close the database */ 560if (dbp != NULL) 561 dbp->close(dbp, 0); </pre> 562 </div> 563 </div> 564 <div class="navfooter"> 565 <hr /> 566 <table width="100%" summary="Navigation footer"> 567 <tr> 568 <td width="40%" align="left"><a accesskey="p" href="Cursors.html">Prev</a>��</td> 569 <td width="20%" align="center"> 570 <a accesskey="u" href="Cursors.html">Up</a> 571 </td> 572 <td width="40%" align="right">��<a accesskey="n" href="PutEntryWCursor.html">Next</a></td> 573 </tr> 574 <tr> 575 <td width="40%" align="left" valign="top">Chapter��4.��Using Cursors��</td> 576 <td width="20%" align="center"> 577 <a accesskey="h" href="index.html">Home</a> 578 </td> 579 <td width="40%" align="right" valign="top">��Putting Records Using Cursors</td> 580 </tr> 581 </table> 582 </div> 583 </body> 584</html> 585