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 49 <code class="methodname">Dbc::put()</code> 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="cxx_cursor7"></a> 133 <pre class="programlisting">#include <db_cxx.h> 134#include <string.h> 135 136... 137 138char *key1str = "My first string"; 139char *data1str = "My first data"; 140char *key2str = "A second string"; 141char *data2str = "My second data"; 142char *data3str = "My third data"; 143 144 145Db my_database(NULL, 0); 146Dbc *cursorp; 147 148try { 149 // Set up our DBTs 150 Dbt key1(key1str, strlen(key1str) + 1); 151 Dbt data1(data1str, strlen(data1str) + 1); 152 153 Dbt key2(key2str, strlen(key2str) + 1); 154 Dbt data2(data2str, strlen(data2str) + 1); 155 Dbt data3(data3str, strlen(data3str) + 1); 156 157 // Database open omitted 158 159 // Get the cursor 160 my_database.cursor(NULL, &cursorp, 0); 161 162 // Assuming an empty database, this first put places 163 // "My first string"/"My first data" in the first 164 // position in the database 165 int ret = cursorp->put(&key1, &data1, DB_KEYFIRST); 166 167 // This put places "A second string"/"My second data" in the 168 // the database according to its key sorts against the key 169 // used for the currently existing database record. Most likely 170 // this record would appear first in the database. 171 ret = cursorp->put(&key2, &data2, 172 DB_KEYFIRST); /* Added according to sort order */ 173 174 // If duplicates are not allowed, the currently existing record that 175 // uses "key2" is overwritten with the data provided on this put. 176 // That is, the record "A second string"/"My second data" becomes 177 // "A second string"/"My third data" 178 // 179 // If duplicates are allowed, then "My third data" is placed in the 180 // duplicates list according to how it sorts against "My second data". 181 ret = cursorp->put(&key2, &data3, 182 DB_KEYFIRST); // If duplicates are not allowed, record 183 // is overwritten with new data. Otherwise, 184 // the record is added to the beginning of 185 // the duplicates list. 186} catch(DbException &e) { 187 my_database.err(e.get_errno(), "Error!"); 188} catch(std::exception &e) { 189 my_database.errx("Error! %s", e.what()); 190} 191 192// Cursors must be closed 193if (cursorp != NULL) 194 cursorp->close(); 195 196my_database.close(0);</pre> 197 </div> 198 <div class="navfooter"> 199 <hr /> 200 <table width="100%" summary="Navigation footer"> 201 <tr> 202 <td width="40%" align="left"><a accesskey="p" href="Positioning.html">Prev</a>��</td> 203 <td width="20%" align="center"> 204 <a accesskey="u" href="Cursors.html">Up</a> 205 </td> 206 <td width="40%" align="right">��<a accesskey="n" href="DeleteEntryWCursor.html">Next</a></td> 207 </tr> 208 <tr> 209 <td width="40%" align="left" valign="top">Getting Records Using the Cursor��</td> 210 <td width="20%" align="center"> 211 <a accesskey="h" href="index.html">Home</a> 212 </td> 213 <td width="40%" align="right" valign="top">��Deleting Records Using Cursors</td> 214 </tr> 215 </table> 216 </div> 217 </body> 218</html> 219