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.62.4" />
9    <link rel="home" 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="previous" 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></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="cursorJavaUsage.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		To use a cursor, you must open it using the <tt class="methodname">Database.openCursor()</tt> 
113		method. When you open a
114		cursor, you can optionally pass it a <tt class="classname">CursorConfig</tt> 
115		object to set cursor properties. 
116        
117        <span>
118                The cursor properties that you can set allows you to
119                control the isolation level that the cursor will obey. See
120                the
121                <i class="citetitle">Berkeley DB Getting Started with Transaction Processing</i> guide for more
122                information.
123        </span>
124	</p>
125        <p>For example:</p>
126        <a id="java_cursor1"></a>
127        <pre class="programlisting">package db.GettingStarted;
128    
129import com.sleepycat.db.Cursor;
130import com.sleepycat.db.Database;
131import com.sleepycat.db.DatabaseException;
132
133import java.io.FileNotFoundException;
134
135...
136Database myDatabase = null;
137Cursor myCursor = null;
138
139try {
140    myDatabase = new Database("myDB", null, null);
141
142    myCursor = myDatabase.openCursor(null, null);
143} catch (FileNotFoundException fnfe) {
144    // Exception handling goes here ...
145} catch (DatabaseException dbe) {
146    // Exception handling goes here ...
147}</pre>
148        <p>
149        To close the cursor, call the <tt class="methodname">Cursor.close()</tt>
150        method. Note that if you close a database that has cursors open in it,
151        then it will throw an exception and close any open cursors for you. 
152        For best results, close your cursors from within a 
153        <tt class="literal">finally</tt> block.
154        
155    </p>
156        <a id="java_cursor2"></a>
157        <pre class="programlisting">package db.GettingStarted;
158    
159import com.sleepycat.db.Cursor;
160import com.sleepycat.db.Database;
161
162...
163try {
164    ...
165} catch ... {
166} finally {
167    try {
168        if (myCursor != null) {
169            myCursor.close();
170        }
171
172        if (myDatabase != null) {
173            myDatabase.close();
174        }
175    } catch(DatabaseException dbe) {
176        System.err.println("Error in close: " + dbe.toString());
177    }
178} </pre>
179      </div>
180    </div>
181    <div class="navfooter">
182      <hr />
183      <table width="100%" summary="Navigation footer">
184        <tr>
185          <td width="40%" align="left"><a accesskey="p" href="dbtJavaUsage.html">Prev</a>��</td>
186          <td width="20%" align="center">
187            <a accesskey="u" href="baseapi.html">Up</a>
188          </td>
189          <td width="40%" align="right">��<a accesskey="n" href="Positioning.html">Next</a></td>
190        </tr>
191        <tr>
192          <td width="40%" align="left" valign="top">Database Usage Example��</td>
193          <td width="20%" align="center">
194            <a accesskey="h" href="index.html">Home</a>
195          </td>
196          <td width="40%" align="right" valign="top">��Getting Records Using the Cursor</td>
197        </tr>
198      </table>
199    </div>
200  </body>
201</html>
202