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>Chapter 4. Using Cursors</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="index.html" title="Getting Started with Berkeley DB" /> 11 <link rel="previous" href="DbUsage.html" title="Database Usage Example" /> 12 <link rel="next" href="Positioning.html" title="Getting Records Using the Cursor" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter 4. Using Cursors</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="DbUsage.html">Prev</a> </td> 22 <th width="60%" align="center"> </th> 23 <td width="20%" align="right"> <a accesskey="n" href="Positioning.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="chapter" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title"><a id="Cursors"></a>Chapter 4. Using Cursors</h2> 33 </div> 34 </div> 35 <div></div> 36 </div> 37 <div class="toc"> 38 <p> 39 <b>Table of Contents</b> 40 </p> 41 <dl> 42 <dt> 43 <span class="sect1"> 44 <a href="Cursors.html#openCursor">Opening and Closing Cursors</a> 45 </span> 46 </dt> 47 <dt> 48 <span class="sect1"> 49 <a href="Positioning.html">Getting Records Using the Cursor</a> 50 </span> 51 </dt> 52 <dd> 53 <dl> 54 <dt> 55 <span class="sect2"> 56 <a href="Positioning.html#cursorsearch">Searching for Records</a> 57 </span> 58 </dt> 59 <dt> 60 <span class="sect2"> 61 <a href="Positioning.html#getdups">Working with Duplicate Records</a> 62 </span> 63 </dt> 64 </dl> 65 </dd> 66 <dt> 67 <span class="sect1"> 68 <a href="PutEntryWCursor.html">Putting Records Using Cursors</a> 69 </span> 70 </dt> 71 <dt> 72 <span class="sect1"> 73 <a href="DeleteEntryWCursor.html">Deleting Records Using Cursors</a> 74 </span> 75 </dt> 76 <dt> 77 <span class="sect1"> 78 <a href="ReplacingEntryWCursor.html">Replacing Records Using Cursors</a> 79 </span> 80 </dt> 81 <dt> 82 <span class="sect1"> 83 <a href="CoreCursorUsage.html">Cursor Example</a> 84 </span> 85 </dt> 86 </dl> 87 </div> 88 <p> 89 Cursors provide a mechanism by which you can iterate over the records in a 90 database. Using cursors, you can get, put, and delete database records. If 91 a database allows duplicate records, then cursors are 92 93 94 95 <span>the easiest way that you can access anything 96 other than the first record for a given key.</span> 97 </p> 98 <p> 99 This chapter introduces cursors. It explains how to open and close them, how 100 to use them to modify databases, and how to use them with duplicate records. 101 </p> 102 <div class="sect1" lang="en" xml:lang="en"> 103 <div class="titlepage"> 104 <div> 105 <div> 106 <h2 class="title" style="clear: both"><a id="openCursor"></a>Opening and Closing Cursors</h2> 107 </div> 108 </div> 109 <div></div> 110 </div> 111 <p> 112 Cursors are managed using the 113 <span><tt class="classname">DBC</tt> structure.</span> 114 115 To use a cursor, you must open it using the 116 <tt class="methodname">DB->cursor()</tt> 117 118 method. 119 </p> 120 <p>For example:</p> 121 <a id="c_cursor1"></a> 122 <pre class="programlisting">#include <db.h> 123 124... 125 126DB *my_database; 127DBC *cursorp; 128 129/* Database open omitted for clarity */ 130 131/* Get a cursor */ 132my_database->cursor(my_database, NULL, &cursorp, 0); </pre> 133 <p> 134 When you are done with the cursor, you should close it. To close a 135 cursor, call the 136 <tt class="methodname">DBC->close()</tt> 137 138 method. Note that closing your database while cursors are still opened 139 within the scope of the DB handle, especially if those cursors are 140 writing to the database, can have unpredictable results. Always 141 close your cursors before closing your database. 142 </p> 143 <a id="c_cursor2"></a> 144 <pre class="programlisting">#include <db.h> 145 146... 147 148DB *my_database; 149DBC *cursorp; 150 151/* Database and cursor open omitted for clarity */ 152 153if (cursorp != NULL) 154 cursorp->close(cursorp); 155 156if (my_database != NULL) 157 my_database->close(my_database, 0); </pre> 158 </div> 159 </div> 160 <div class="navfooter"> 161 <hr /> 162 <table width="100%" summary="Navigation footer"> 163 <tr> 164 <td width="40%" align="left"><a accesskey="p" href="DbUsage.html">Prev</a> </td> 165 <td width="20%" align="center"> 166 <a accesskey="u" href="index.html">Up</a> 167 </td> 168 <td width="40%" align="right"> <a accesskey="n" href="Positioning.html">Next</a></td> 169 </tr> 170 <tr> 171 <td width="40%" align="left" valign="top">Database Usage Example </td> 172 <td width="20%" align="center"> 173 <a accesskey="h" href="index.html">Home</a> 174 </td> 175 <td width="40%" align="right" valign="top"> Getting Records Using the Cursor</td> 176 </tr> 177 </table> 178 </div> 179 </body> 180</html> 181