docs/gsg/C/Cursors.html

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