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