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��9.��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="baseapi.html" title="Part��II.��Programming with the Base API" />
11    <link rel="prev" href="dbtJavaUsage.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��9.��Using Cursors</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="dbtJavaUsage.html">Prev</a>��</td>
22          <th width="60%" align="center">Part��II.��Programming with the Base API</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��9.��Using Cursors</h2>
33          </div>
34        </div>
35      </div>
36      <div class="toc">
37        <p>
38          <b>Table of Contents</b>
39        </p>
40        <dl>
41          <dt>
42            <span class="sect1">
43              <a href="Cursors.html#openCursor">Opening and Closing Cursors</a>
44            </span>
45          </dt>
46          <dt>
47            <span class="sect1">
48              <a href="Positioning.html">Getting Records Using the Cursor</a>
49            </span>
50          </dt>
51          <dd>
52            <dl>
53              <dt>
54                <span class="sect2">
55                  <a href="Positioning.html#cursorsearch">Searching for Records</a>
56                </span>
57              </dt>
58              <dt>
59                <span class="sect2">
60                  <a href="Positioning.html#getdups">Working with Duplicate Records</a>
61                </span>
62              </dt>
63            </dl>
64          </dd>
65          <dt>
66            <span class="sect1">
67              <a href="PutEntryWCursor.html">Putting Records Using Cursors</a>
68            </span>
69          </dt>
70          <dt>
71            <span class="sect1">
72              <a href="DeleteEntryWCursor.html">Deleting Records Using Cursors</a>
73            </span>
74          </dt>
75          <dt>
76            <span class="sect1">
77              <a href="ReplacingEntryWCursor.html">Replacing Records Using Cursors</a>
78            </span>
79          </dt>
80          <dt>
81            <span class="sect1">
82              <a href="cursorJavaUsage.html">Cursor Example</a>
83            </span>
84          </dt>
85        </dl>
86      </div>
87      <p>
88	Cursors provide a mechanism by which you can iterate over the records in a
89	database. Using cursors, you can get, put, and delete database records.  If
90	a database allows duplicate records, then cursors are 
91    
92    
93
94    <span>the easiest way that you can access anything
95    other than the first record for a given key.</span>
96  </p>
97      <p>
98	This chapter introduces cursors. It explains how to open and close them, how
99	to use them to modify databases, and how to use them with duplicate records.
100  </p>
101      <div class="sect1" lang="en" xml:lang="en">
102        <div class="titlepage">
103          <div>
104            <div>
105              <h2 class="title" style="clear: both"><a id="openCursor"></a>Opening and Closing Cursors</h2>
106            </div>
107          </div>
108        </div>
109        <p>
110		To use a cursor, you must open it using the <code class="methodname">Database.openCursor()</code> 
111		method. When you open a
112		cursor, you can optionally pass it a <code class="classname">CursorConfig</code> 
113		object to set cursor properties. 
114        
115        <span>
116                The cursor properties that you can set allows you to
117                control the isolation level that the cursor will obey. See
118                the
119                <em class="citetitle">Berkeley DB Getting Started with Transaction Processing</em> guide for more
120                information.
121        </span>
122	</p>
123        <p>For example:</p>
124        <a id="java_cursor1"></a>
125        <pre class="programlisting">package db.GettingStarted;
126    
127import com.sleepycat.db.Cursor;
128import com.sleepycat.db.Database;
129import com.sleepycat.db.DatabaseException;
130
131import java.io.FileNotFoundException;
132
133...
134Database myDatabase = null;
135Cursor myCursor = null;
136
137try {
138    myDatabase = new Database("myDB", null, null);
139
140    myCursor = myDatabase.openCursor(null, null);
141} catch (FileNotFoundException fnfe) {
142    // Exception handling goes here ...
143} catch (DatabaseException dbe) {
144    // Exception handling goes here ...
145}</pre>
146        <p>
147        To close the cursor, call the <code class="methodname">Cursor.close()</code>
148        method. Note that if you close a database that has cursors open in it,
149        then it will throw an exception and close any open cursors for you. 
150        For best results, close your cursors from within a 
151        <code class="literal">finally</code> block.
152        
153    </p>
154        <a id="java_cursor2"></a>
155        <pre class="programlisting">package db.GettingStarted;
156    
157import com.sleepycat.db.Cursor;
158import com.sleepycat.db.Database;
159
160...
161try {
162    ...
163} catch ... {
164} finally {
165    try {
166        if (myCursor != null) {
167            myCursor.close();
168        }
169
170        if (myDatabase != null) {
171            myDatabase.close();
172        }
173    } catch(DatabaseException dbe) {
174        System.err.println("Error in close: " + dbe.toString());
175    }
176} </pre>
177      </div>
178    </div>
179    <div class="navfooter">
180      <hr />
181      <table width="100%" summary="Navigation footer">
182        <tr>
183          <td width="40%" align="left"><a accesskey="p" href="dbtJavaUsage.html">Prev</a>��</td>
184          <td width="20%" align="center">
185            <a accesskey="u" href="baseapi.html">Up</a>
186          </td>
187          <td width="40%" align="right">��<a accesskey="n" href="Positioning.html">Next</a></td>
188        </tr>
189        <tr>
190          <td width="40%" align="left" valign="top">Database Usage Example��</td>
191          <td width="20%" align="center">
192            <a accesskey="h" href="index.html">Home</a>
193          </td>
194          <td width="40%" align="right" valign="top">��Getting Records Using the Cursor</td>
195        </tr>
196      </table>
197    </div>
198  </body>
199</html>
200