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��4.��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��4.��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      <p>
47        You use 
48            <code class="methodname">DBC-&gt;put()</code>
49            
50            
51        to put (write) records to the database. You can use the following flags
52        with this method:
53    </p>
54      <div class="itemizedlist">
55        <ul type="disc">
56          <li>
57            <p>
58            
59            <code class="literal">DB_NODUPDATA</code>
60         </p>
61            <p>
62            If the provided key  already exists 
63            in the database, then this method returns 
64            <code class="literal">DB_KEYEXIST</code>.
65        </p>
66            <p>
67            If the key does not exist, then the order that the record is put into the database 
68            is determined by the 
69                
70                <span>
71                    insertion order in use by the database. If a comparison
72                    function has been provided to the database, the record is
73                    inserted in its sorted location. Otherwise (assuming BTree), 
74                    lexicographical sorting is used, with
75                    shorter items collating before longer items.
76                </span>
77         </p>
78            <p>
79            This flag can only be used for the BTree and Hash access methods,
80            and only if the database has been configured to support sorted
81            duplicate data items (<code class="literal">DB_DUPSORT</code> was specified at
82            database creation time).
83        </p>
84            <p>
85            This flag cannot be used with the Queue or Recno access methods.
86        </p>
87            <p>
88            For more information on duplicate records, see
89            <a class="xref" href="btree.html#duplicateRecords" title="Allowing Duplicate Records">Allowing Duplicate Records</a>.
90        </p>
91          </li>
92          <li>
93            <p>
94            
95            <code class="literal">DB_KEYFIRST</code>
96        </p>
97            <p>
98            For databases that do not support duplicates, this method behaves
99                
100                <span>
101                    exactly the same as if a default insertion was performed.
102                </span>
103                If the database supports duplicate records, 
104                    
105                    <span>
106                        and a duplicate sort function has been specified, the
107                        inserted data item is added in its sorted location. If
108                        the key already exists in the database and no duplicate
109                        sort function has been specified, the inserted data item
110                        is added as the first of the data items for that key.
111                    </span>
112        </p>
113          </li>
114          <li>
115            <p>
116            
117            <code class="literal">DB_KEYLAST</code>
118        </p>
119            <p>
120            Behaves exactly as if 
121                <code class="literal">DB_KEYFIRST</code> 
122                
123            was used, except that if the key already exists in the database and no
124            duplicate sort function has been specified, the
125            inserted data item is added as the last of the data
126            items for that key.
127        </p>
128          </li>
129        </ul>
130      </div>
131      <p>For example:</p>
132      <a id="c_cursor7"></a>
133      <pre class="programlisting">#include &lt;db.h&gt;
134#include &lt;string.h&gt;
135
136...
137
138DB *dbp;
139DBC *cursorp;
140DBT data1, data2, data3;
141DBT key1, key2;
142char *key1str = "My first string";
143char *data1str = "My first data";
144char *key2str = "A second string";
145char *data2str = "My second data";
146char *data3str = "My third data";
147int ret;
148
149/* Set up our DBTs */
150key1.data = key1str;
151key1.size = strlen(key1str) + 1;
152data1.data = data1str;
153data1.size = strlen(data1str) + 1;
154
155key2.data = key2str;
156key2.size = strlen(key2str) + 1;
157data2.data = data2str;
158data2.size = strlen(data2str) + 1;
159data3.data = data3str;
160data3.size = strlen(data3str) + 1;
161
162/* Database open omitted */
163
164/* Get the cursor */
165dbp-&gt;cursor(dbp, NULL, &amp;cursorp, 0);
166
167/* 
168 * Assuming an empty database, this first put places
169 * "My first string"/"My first data" in the first 
170 * position in the database
171 */
172ret = cursorp-&gt;put(cursorp, &amp;key1, 
173  &amp;data1, DB_KEYFIRST); 
174
175/*
176 * This put places "A second string"/"My second data" in the
177 * the database according to its key sorts against the key 
178 * used for the currently existing database record. Most likely
179 * this record would appear first in the database.
180 */
181ret = cursorp-&gt;put(cursorp, &amp;key2, 
182  &amp;data2, DB_KEYFIRST); /* Added according to sort order */
183
184/*
185 * If duplicates are not allowed, the currently existing record that 
186 * uses "key2" is overwritten with the data provided on this put.
187 * That is, the record "A second string"/"My second data" becomes
188 * "A second string"/"My third data"
189 *
190 * If duplicates are allowed, then "My third data" is placed in the
191 * duplicates list according to how it sorts against "My second data".
192 */
193ret = cursorp-&gt;put(cursorp, &amp;key2, 
194  &amp;data3, DB_KEYFIRST); /* If duplicates are not allowed, record 
195                         * is overwritten with new data. Otherwise, 
196                         * the record is added to the beginning of 
197                         * the duplicates list.
198                         */ </pre>
199    </div>
200    <div class="navfooter">
201      <hr />
202      <table width="100%" summary="Navigation footer">
203        <tr>
204          <td width="40%" align="left"><a accesskey="p" href="Positioning.html">Prev</a>��</td>
205          <td width="20%" align="center">
206            <a accesskey="u" href="Cursors.html">Up</a>
207          </td>
208          <td width="40%" align="right">��<a accesskey="n" href="DeleteEntryWCursor.html">Next</a></td>
209        </tr>
210        <tr>
211          <td width="40%" align="left" valign="top">Getting Records Using the Cursor��</td>
212          <td width="20%" align="center">
213            <a accesskey="h" href="index.html">Home</a>
214          </td>
215          <td width="40%" align="right" valign="top">��Deleting Records Using Cursors</td>
216        </tr>
217      </table>
218    </div>
219  </body>
220</html>
221