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>Putting Records 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="Cursors.html" title="Chapter 9. Using Cursors" />
11    <link rel="previous" href="Positioning.html" title="Getting Records Using the Cursor" />
12    <link rel="next" href="DeleteEntryWCursor.html" title="Deleting 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">Putting Records Using Cursors</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="Positioning.html">Prev</a> </td>
22          <th width="60%" align="center">Chapter 9. Using Cursors</th>
23          <td width="20%" align="right"> <a accesskey="n" href="DeleteEntryWCursor.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="PutEntryWCursor"></a>Putting Records Using Cursors</h2>
33          </div>
34        </div>
35        <div></div>
36      </div>
37      <p>
38        You can use cursors to put records into the database. DB's behavior
39        when putting records into the database differs depending on the flags
40        that you use when writing the record, on the access method that you are
41        using, and on whether your database supports sorted duplicates.
42    </p>
43      <p>
44        Note that when putting records to the database using a cursor, the
45        cursor is positioned at the record you inserted. 
46    </p>
47      <div class="itemizedlist">
48        <ul type="disc">
49          <li>
50            <p>
51            <tt class="methodname">Cursor.putNoDupData()</tt>
52            
53         </p>
54            <p>
55            If the provided key  already exists 
56            in the database, then this method returns 
57            <tt class="literal">OperationStatus.KEYEXIST</tt>.
58        </p>
59            <p>
60            If the key does not exist, then the order that the record is put into the database 
61            is determined by the 
62                
63                <span>
64                    insertion order in use by the database. If a comparison
65                    function has been provided to the database, the record is
66                    inserted in its sorted location. Otherwise (assuming BTree), 
67                    lexicographical sorting is used, with
68                    shorter items collating before longer items.
69                </span>
70         </p>
71            <p>
72            This flag can only be used for the BTree and Hash access methods,
73            and only if the database has been configured to support sorted
74            duplicate data items (<tt class="literal">DB_DUPSORT</tt> was specified at
75            database creation time).
76        </p>
77            <p>
78            This flag cannot be used with the Queue or Recno access methods.
79        </p>
80            <p>
81            For more information on duplicate records, see
82            <a href="btree.html#duplicateRecords">Allowing Duplicate Records</a>.
83        </p>
84          </li>
85          <li>
86            <p>
87            <tt class="methodname">Cursor.putNoOverwrite()</tt>
88         </p>
89            <p>
90            If the provided key already exists 
91            in the database, then this method returns 
92            .
93        </p>
94            <p>
95            If the key does not exist, then the order that the record is put into the database 
96            is determined by the BTree (key) comparator in use by the database. 
97         </p>
98          </li>
99          <li>
100            <p>
101            <tt class="methodname">Cursor.putKeyFirst()</tt>
102            
103        </p>
104            <p>
105            For databases that do not support duplicates, this method behaves
106                
107                <span>
108                    exactly the same as if a default insertion was performed.
109                </span>
110                If the database supports duplicate records, 
111                    
112                    <span>
113                        and a duplicate sort function has been specified, the
114                        inserted data item is added in its sorted location. If
115                        the key already exists in the database and no duplicate
116                        sort function has been specified, the inserted data item
117                        is added as the first of the data items for that key.
118                    </span>
119        </p>
120          </li>
121          <li>
122            <p>
123            <tt class="methodname">Cursor.putKeyLast()</tt>
124            
125        </p>
126            <p>
127            Behaves exactly as if 
128                 
129                <tt class="methodname">Cursor.putKeyFirst()</tt>
130            was used, except that if the key already exists in the database and no
131            duplicate sort function has been specified, the
132            inserted data item is added as the last of the data
133            items for that key.
134        </p>
135          </li>
136        </ul>
137      </div>
138      <p>For example:</p>
139      <a id="java_cursor7"></a>
140      <pre class="programlisting">package db.GettingStarted;
141    
142import com.sleepycat.db.Cursor;
143import com.sleepycat.db.Database;
144import com.sleepycat.db.DatabaseEntry;
145import com.sleepycat.db.OperationStatus; 
146
147...
148  
149// Create the data to put into the database
150String key1str = "My first string";
151String data1str = "My first data";
152String key2str = "My second string";
153String data2str = "My second data";
154String data3str = "My third data";
155  
156Cursor cursor = null;
157Database myDatabase = null;
158try {
159    ...
160    // Database open omitted for brevity
161    ...
162
163    DatabaseEntry key1 = new DatabaseEntry(key1str.getBytes("UTF-8"));
164    DatabaseEntry data1 = new DatabaseEntry(data1str.getBytes("UTF-8"));
165    DatabaseEntry key2 = new DatabaseEntry(key2str.getBytes("UTF-8"));
166    DatabaseEntry data2 = new DatabaseEntry(data2str.getBytes("UTF-8"));
167    DatabaseEntry data3 = new DatabaseEntry(data3str.getBytes("UTF-8"));
168
169    // Open a cursor using a database handle
170    cursor = myDatabase.openCursor(null, null);
171
172    // Assuming an empty database.
173
174    OperationStatus retVal = cursor.put(key1, data1); // SUCCESS
175    retVal = cursor.put(key2, data2); // SUCCESS
176    retVal = cursor.put(key2, data3); // SUCCESS if dups allowed, 
177                                      // KEYEXIST if not.    
178                                              
179} catch (Exception e) {
180    // Exception handling goes here
181} finally {
182   // Make sure to close the cursor
183   cursor.close();
184}</pre>
185    </div>
186    <div class="navfooter">
187      <hr />
188      <table width="100%" summary="Navigation footer">
189        <tr>
190          <td width="40%" align="left"><a accesskey="p" href="Positioning.html">Prev</a> </td>
191          <td width="20%" align="center">
192            <a accesskey="u" href="Cursors.html">Up</a>
193          </td>
194          <td width="40%" align="right"> <a accesskey="n" href="DeleteEntryWCursor.html">Next</a></td>
195        </tr>
196        <tr>
197          <td width="40%" align="left" valign="top">Getting Records Using the Cursor </td>
198          <td width="20%" align="center">
199            <a accesskey="h" href="index.html">Home</a>
200          </td>
201          <td width="40%" align="right" valign="top"> Deleting Records Using Cursors</td>
202        </tr>
203      </table>
204    </div>
205  </body>
206</html>
207