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