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>dbc put</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB TCL API Reference" /> 10 <link rel="up" href="tclapi.html" title="Chapter��1.�� Berkeley DB Tcl APIs" /> 11 <link rel="prev" href="dbc_get.html" title="dbc get" /> 12 <link rel="next" href="env_close.html" title="env close" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center"><span class="emphasis"><em>dbc</em></span> put</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbc_get.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��1.�� 23 Berkeley DB Tcl APIs 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="env_close.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="dbc_put"></a><span class="emphasis"><em>dbc</em></span> put</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">dbc put 39 [-after] 40 [-before] 41 [-current] 42 [-partial {doff dlen}] 43 data 44 45dbc put 46 [-keyfirst] 47 [-keylast] 48 [-partial {doff dlen}] 49 key data </pre> 50 <p> 51 The <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> 52 command stores the specified key/data pair into the database. One of 53 the following options must be specified: 54 </p> 55 <div class="itemizedlist"> 56 <ul type="disc"> 57 <li> 58 <p> 59 <span class="bold"><strong>-after</strong></span> 60 </p> 61 <p> 62 In the case of the Btree and Hash access methods, insert the data 63 element as a duplicate element of the key to which the cursor refers. 64 The new element appears immediately after the current cursor position. 65 It is an error to specify <span class="bold"><strong>-after</strong></span> if 66 the underlying Btree or Hash database was not created with the 67 <span class="bold"><strong>-dup</strong></span> option. No key argument should 68 be specified. 69 </p> 70 <p> 71 In the case of the Recno access method, it is an error to specify the 72 <span class="bold"><strong>-after</strong></span> option if the underlying Recno 73 database was not created with the <span class="bold"><strong>-renumber</strong></span> option. If the <span class="bold"><strong>-renumber</strong></span> option was specified, a new key is 74 created, all records after the inserted item are automatically 75 renumbered, and the key of the new record is returned in the structure 76 to which the key argument refers. The initial value of the key 77 parameter is ignored. See <span class="bold"><strong>berkdb open</strong></span> 78 for more information. 79 </p> 80 <p> 81 In the case of the Queue access method, it is always an error to 82 specify <span class="bold"><strong>-after</strong></span>. 83 </p> 84 <p> 85 If the current cursor record has already been deleted, and the 86 underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying 87 access method is Btree or Recno, the operation will succeed. 88 </p> 89 </li> 90 <li> 91 <p> 92 <span class="bold"><strong>-before</strong></span> 93 </p> 94 <p> 95 In the case of the Btree and Hash access methods, insert the data 96 element as a duplicate element of the key to which the cursor refers. 97 The new element appears immediately before the current cursor 98 position. It is an error to specify <span class="bold"><strong>-before</strong></span> if the underlying Btree or Hash 99 database was not created with the <span class="bold"><strong>-dup</strong></span> option. No key argument should be 100 specified. 101 </p> 102 <p> 103 In the case of the Recno access method, it is an error to specify 104 <span class="bold"><strong>-before</strong></span> if the underlying Recno 105 database was not created with the <span class="bold"><strong>-before</strong></span> option. If the <span class="bold"><strong>-before</strong></span> option was specified, a new key is 106 created, the current record and all records after it are automatically 107 renumbered, and the key of the new record is returned in the structure 108 to which the key argument refers. The initial value of the key 109 parameter is ignored. See <span class="bold"><strong>berkdb open</strong></span> 110 for more information. 111 </p> 112 <p> 113 In the case of the Queue access method, it is always an error to 114 specify <span class="bold"><strong>-before</strong></span>. 115 </p> 116 <p> 117 If the current cursor record has already been deleted and the 118 underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying 119 access method is Btree or Recno, the operation will succeed. 120 </p> 121 </li> 122 <li> 123 <p> 124 <span class="bold"><strong>-current</strong></span> 125 </p> 126 <p> 127 Overwrite the data of the key/data pair to which the cursor refers 128 with the specified data item. No key argument should be specified. 129 </p> 130 <p> 131 If the <span class="bold"><strong>-dupsort</strong></span> option was specified 132 to <span class="bold"><strong>berkdb open</strong></span> and the data item of 133 the key/data pair to which the cursor refers does not compare equally 134 to the data parameter, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. 135 </p> 136 <p> 137 If the current cursor record has already been deleted and the 138 underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying 139 access method is Btree, Queue, or Recno, the operation will succeed. 140 </p> 141 </li> 142 <li> 143 <p> 144 <span class="bold"><strong>-keyfirst</strong></span> 145 </p> 146 <p> 147 In the case of the Btree and Hash access methods, insert the specified 148 key/data pair into the database. 149 </p> 150 <p> 151 If the key already exists in the database, and the <span class="bold"><strong>-dupsort</strong></span> option was specified to <span class="bold"><strong>berkdb open</strong></span>, the inserted data item is added in 152 its sorted location. If the key already exists in the database, and 153 the <span class="bold"><strong>-dupsort</strong></span> option was not 154 specified, the inserted data item is added as the first of the data 155 items for that key. 156 </p> 157 <p> 158 The <span class="bold"><strong>-keyfirst</strong></span> option may not be 159 specified to the Queue or Recno access methods. 160 </p> 161 </li> 162 <li> 163 <p> 164 <span class="bold"><strong>-keylast</strong></span> 165 </p> 166 <p> 167 In the case of the Btree and Hash access methods, insert the specified 168 key/data pair into the database. 169 </p> 170 <p> 171 If the key already exists in the database, and the <span class="bold"><strong>-dupsort</strong></span> option was specified to <span class="bold"><strong>berkdb open</strong></span>, the inserted data item is added in 172 its sorted location. If the key already exists in the database, and 173 the <span class="bold"><strong>-dupsort</strong></span> option was not 174 specified, the inserted data item is added as the last of the data 175 items for that key. 176 </p> 177 <p> 178 The <span class="bold"><strong>-keylast</strong></span> option may not be 179 specified to the Queue or Recno access methods. 180 </p> 181 </li> 182 <li> 183 <p> 184 <span class="bold"><strong>-partial {doff dlen}</strong></span> 185 </p> 186 <p> 187 The <span class="bold"><strong>dlen</strong></span> bytes starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the specified 188 key's data record are replaced by the data specified by the data and 189 size structure elements. If <span class="bold"><strong>dlen</strong></span> is 190 smaller than the length of the supplied data, the record will grow; if 191 <span class="bold"><strong>dlen</strong></span> is larger than the length of the 192 supplied data, the record will shrink. If the specified bytes do not 193 exist, the record will be extended using nul bytes as necessary, and 194 the <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> call 195 will succeed. 196 </p> 197 <p> 198 It is an error to attempt a partial put using the 199 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> command 200 in a database that supports duplicate records. Partial puts in 201 databases supporting duplicate records must be done using a 202 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> command. 203 </p> 204 <p> 205 It is an error to attempt a partial put with differing <span class="bold"><strong>dlen</strong></span> and supplied data length values in Queue 206 or Recno databases with fixed-length records. 207 </p> 208 </li> 209 </ul> 210 </div> 211 <p> 212 If a key is specified, and if the underlying database is a Queue or 213 Recno database, the given key will be interpreted by Tcl as an 214 integer. For all other database types, the key is interpreted by Tcl 215 as a byte array. 216 </p> 217 <p> 218 If <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> fails 219 for any reason, the state of the cursor will be unchanged. If 220 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> succeeds 221 and an item is inserted into the database, the cursor is always 222 positioned to refer to the newly inserted item. 223 </p> 224 <p> 225 The <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> 226 command returns 0 on success, and in the case of error, a Tcl error is 227 thrown. 228 </p> 229 </div> 230 <div class="navfooter"> 231 <hr /> 232 <table width="100%" summary="Navigation footer"> 233 <tr> 234 <td width="40%" align="left"><a accesskey="p" href="dbc_get.html">Prev</a>��</td> 235 <td width="20%" align="center"> 236 <a accesskey="u" href="tclapi.html">Up</a> 237 </td> 238 <td width="40%" align="right">��<a accesskey="n" href="env_close.html">Next</a></td> 239 </tr> 240 <tr> 241 <td width="40%" align="left" valign="top"><span class="emphasis"><em>dbc</em></span> get��</td> 242 <td width="20%" align="center"> 243 <a accesskey="h" href="index.html">Home</a> 244 </td> 245 <td width="40%" align="right" valign="top">��<span class="emphasis"><em>env</em></span> close</td> 246 </tr> 247 </table> 248 </div> 249 </body> 250</html> 251