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>DB->del()</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 C API Reference" /> 10 <link rel="up" href="db.html" title="Chapter��2.�� The DB Handle" /> 11 <link rel="prev" href="dbcompact.html" title="DB->compact()" /> 12 <link rel="next" href="dberr.html" title="DB->err()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->del()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbcompact.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.�� 23 The DB Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dberr.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="dbdel"></a>DB->del()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->del(DB *db, DB_TXN *txnid, DBT *key, u_int32_t flags); </pre> 42 <p> 43 The <code class="methodname">DB->del()</code> method removes key/data pairs from the database. The 44 key/data pair associated with the specified <span class="bold"><strong>key</strong></span> is discarded from the database. In the 45 presence of duplicate key values, all records associated with the 46 designated key will be discarded. 47 </p> 48 <p> 49 When called on a database that has been made into a secondary index 50 using the <a class="xref" href="dbassociate.html" title="DB->associate()">DB->associate()</a> method, the 51 <code class="methodname">DB->del()</code> method deletes the key/data pair from the primary database 52 and all secondary indices. 53 </p> 54 <p> 55 The <code class="methodname">DB->del()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if the specified key 56 is not in the database. The <code class="methodname">DB->del()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_KEYEMPTY" class="olink">DB_KEYEMPTY</a> if the database is a 57 Queue or Recno database and the specified key exists, but was never explicitly created by 58 the application or was later deleted. Unless otherwise specified, the 59 <code class="methodname">DB->del()</code> <span> 60 <span> 61 method returns a non-zero error value on failure and 0 on success. 62 </span> 63 64 </span> 65 </p> 66 <div class="sect2" lang="en" xml:lang="en"> 67 <div class="titlepage"> 68 <div> 69 <div> 70 <h3 class="title"><a id="id1632636"></a>Parameters</h3> 71 </div> 72 </div> 73 </div> 74 <div class="sect3" lang="en" xml:lang="en"> 75 <div class="titlepage"> 76 <div> 77 <div> 78 <h4 class="title"><a id="id1633401"></a>flags</h4> 79 </div> 80 </div> 81 </div> 82 <p> 83 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 84 or one of the following values: 85 </p> 86 <div class="itemizedlist"> 87 <ul type="disc"> 88 <li> 89 <p><a id="dbput_DB_CONSUME"></a> 90 <code class="literal">DB_CONSUME</code> 91 </p> 92 <p> 93 If the database is of type DB_QUEUE then this flag may be set to force the head of the queue 94 to move to the first non-deleted item in the queue. Normally this is only done if the 95 deleted item is exactly at the head when deleted. 96 </p> 97 </li> 98 <li> 99 <p><a id="del_DB_MULTIPLE"></a> 100 <code class="literal">DB_MULTIPLE</code> 101 </p> 102 <p> 103 Delete multiple data items using keys from the buffer to which the 104 <span class="bold"><strong>key</strong></span> parameter refers. 105 </p> 106 <p> 107 To delete records in bulk by key with the btree or hash access methods, construct a 108 bulk buffer in the <span class="bold"><strong>key</strong></span> 109 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> using 110 <a class="xref" href="DB_MULTIPLE_WRITE_INIT.html" title="DB_MULTIPLE_WRITE_INIT">DB_MULTIPLE_WRITE_INIT</a> and 111 <a class="xref" href="DB_MULTIPLE_WRITE_NEXT.html" title="DB_MULTIPLE_WRITE_NEXT">DB_MULTIPLE_WRITE_NEXT</a>. To 112 delete records in bulk by record number, construct the 113 <span class="bold"><strong>key</strong></span> <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> using 114 <a class="xref" href="DB_MULTIPLE_RECNO_WRITE_INIT.html" title="DB_MULTIPLE_RECNO_WRITE_INIT">DB_MULTIPLE_RECNO_WRITE_INIT</a> and 115 <a class="xref" href="DB_MULTIPLE_RECNO_WRITE_NEXT.html" title="DB_MULTIPLE_RECNO_WRITE_NEXT">DB_MULTIPLE_RECNO_WRITE_NEXT</a> 116 with a data size of zero. 117 </p> 118 <p> 119 A successful bulk delete operation is logically equivalent to a loop through each 120 key/data pair, performing a <a class="xref" href="dbdel.html" title="DB->del()">DB->del()</a> for each one. 121 </p> 122 <p> 123 See the <a class="xref" href="dbt.html#dbtlist" title="DBT and Bulk Operations">DBT and Bulk Operations</a> for more information on 124 working with bulk updates. 125 </p> 126 <p> 127 The <code class="literal">DB_MULTIPLE</code> flag may only be used alone. 128 </p> 129 </li> 130 <li> 131 <p><a id="del_DB_MULTIPLE_KEY"></a> 132 <code class="literal">DB_MULTIPLE_KEY</code> 133 </p> 134 <p> 135 Delete multiple data items using keys and data from the buffer to which the 136 <span class="bold"><strong>key</strong></span> parameter refers. 137 </p> 138 <p> 139 To delete records in bulk with the btree or hash access methods, construct a bulk 140 buffer in the <span class="bold"><strong>key</strong></span> 141 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> using 142 <a class="xref" href="DB_MULTIPLE_WRITE_INIT.html" title="DB_MULTIPLE_WRITE_INIT">DB_MULTIPLE_WRITE_INIT</a> and 143 <a class="xref" href="DB_MULTIPLE_KEY_WRITE_NEXT.html" title="DB_MULTIPLE_KEY_WRITE_NEXT">DB_MULTIPLE_KEY_WRITE_NEXT</a>. 144 To delete records in bulk with the recno or hash access methods, construct 145 a bulk buffer in the <span class="bold"><strong>key</strong></span> 146 <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> using 147 <a class="xref" href="DB_MULTIPLE_RECNO_WRITE_INIT.html" title="DB_MULTIPLE_RECNO_WRITE_INIT">DB_MULTIPLE_RECNO_WRITE_INIT</a> 148 and <a class="xref" href="DB_MULTIPLE_RECNO_WRITE_NEXT.html" title="DB_MULTIPLE_RECNO_WRITE_NEXT">DB_MULTIPLE_RECNO_WRITE_NEXT</a>. 149 </p> 150 <p> 151 See the <a class="xref" href="dbt.html#dbtlist" title="DBT and Bulk Operations">DBT and Bulk Operations</a> for more information on 152 working with bulk updates. 153 </p> 154 <p> 155 The <code class="literal">DB_MULTIPLE_KEY</code> flag may only be used alone. 156 </p> 157 </li> 158 </ul> 159 </div> 160 </div> 161 <div class="sect3" lang="en" xml:lang="en"> 162 <div class="titlepage"> 163 <div> 164 <div> 165 <h4 class="title"><a id="id1633548"></a>key</h4> 166 </div> 167 </div> 168 </div> 169 <p> 170 The key <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> operated on. 171 </p> 172 </div> 173 <div class="sect3" lang="en" xml:lang="en"> 174 <div class="titlepage"> 175 <div> 176 <div> 177 <h4 class="title"><a id="id1633772"></a>txnid</h4> 178 </div> 179 </div> 180 </div> 181 <p> 182 If the operation is part of an application-specified transaction, the 183 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 184 handle returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; 185 if the operation is part of a Berkeley DB Concurrent Data Store group, the 186 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 187 from <a class="xref" href="envcdsgroup_begin.html" title="DB_ENV->cdsgroup_begin()">DB_ENV->cdsgroup_begin()</a>; 188 otherwise NULL. If no transaction handle is specified, but the 189 operation occurs in a transactional database, the operation will be 190 implicitly transaction protected. 191 </p> 192 </div> 193 </div> 194 <div class="sect2" lang="en" xml:lang="en"> 195 <div class="titlepage"> 196 <div> 197 <div> 198 <h3 class="title"><a id="id1633398"></a>Errors</h3> 199 </div> 200 </div> 201 </div> 202 <p> 203 The <code class="methodname">DB->del()</code> <span> 204 <span> 205 method may fail and return one of the following non-zero errors: 206 </span> 207 208 </span> 209 </p> 210 <div class="sect3" lang="en" xml:lang="en"> 211 <div class="titlepage"> 212 <div> 213 <div> 214 <h4 class="title"><a id="id1633662"></a>DB_FOREIGN_CONFLICT</h4> 215 </div> 216 </div> 217 </div> 218 <p> 219 A <a class="link" href="dbassociate_foreign.html" title="DB->associate_foreign()">foreign key constraint violation</a> 220 has occurred. This can be caused by one of two things: 221 </p> 222 <div class="orderedlist"> 223 <ol type="1"> 224 <li> 225 <p> 226 An attempt was made to add a record to a 227 constrained database, and the key used for that 228 record does not exist in the foreign key 229 database. 230 </p> 231 </li> 232 <li> 233 <p> 234 <a class="link" href="dbassociate_foreign.html#associate_foreign_DB_FOREIGN_ABORT">DB_FOREIGN_ABORT</a> 235 was declared for a foreign key database, and then 236 subsequently a record was deleted from the 237 foreign key database without first removing it 238 from the constrained secondary database. 239 </p> 240 </li> 241 </ol> 242 </div> 243 </div> 244 <div class="sect3" lang="en" xml:lang="en"> 245 <div class="titlepage"> 246 <div> 247 <div> 248 <h4 class="title"><a id="id1633801"></a>DB_LOCK_DEADLOCK</h4> 249 </div> 250 </div> 251 </div> 252 <p> 253 A transactional database environment operation was selected to resolve 254 a deadlock. 255 </p> 256 </div> 257 <div class="sect3" lang="en" xml:lang="en"> 258 <div class="titlepage"> 259 <div> 260 <div> 261 <h4 class="title"><a id="id1633512"></a>DB_LOCK_NOTGRANTED</h4> 262 </div> 263 </div> 264 </div> 265 <p> 266 A Berkeley DB Concurrent Data Store database environment configured 267 for lock timeouts was unable to grant a lock in the allowed time. 268 </p> 269 </div> 270 <div class="sect3" lang="en" xml:lang="en"> 271 <div class="titlepage"> 272 <div> 273 <div> 274 <h4 class="title"><a id="id1634013"></a> DB_REP_HANDLE_DEAD</h4> 275 </div> 276 </div> 277 </div> 278 <p> 279 When a client synchronizes with the master, it is possible for committed 280 transactions to be rolled back. This invalidates all the database and cursor 281 handles opened in the replication environment. Once this occurs, an attempt to use 282 such a handle will 283 284 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 285 The application will need to discard the handle and open a new one in order to 286 continue processing. 287 </p> 288 </div> 289 <div class="sect3" lang="en" xml:lang="en"> 290 <div class="titlepage"> 291 <div> 292 <div> 293 <h4 class="title"><a id="id1633743"></a>DB_REP_LOCKOUT</h4> 294 </div> 295 </div> 296 </div> 297 <p> 298 The operation was blocked by client/master synchronization. 299 </p> 300 </div> 301 <div class="sect3" lang="en" xml:lang="en"> 302 <div class="titlepage"> 303 <div> 304 <div> 305 <h4 class="title"><a id="id1633540"></a>DB_SECONDARY_BAD</h4> 306 </div> 307 </div> 308 </div> 309 <p> 310 A secondary index references a nonexistent primary key. 311 </p> 312 </div> 313 <div class="sect3" lang="en" xml:lang="en"> 314 <div class="titlepage"> 315 <div> 316 <div> 317 <h4 class="title"><a id="id1633536"></a>EACCES</h4> 318 </div> 319 </div> 320 </div> 321 <p> 322 An attempt was made to modify a read-only database. 323 </p> 324 </div> 325 <div class="sect3" lang="en" xml:lang="en"> 326 <div class="titlepage"> 327 <div> 328 <div> 329 <h4 class="title"><a id="id1633560"></a>EINVAL</h4> 330 </div> 331 </div> 332 </div> 333 <p> 334 An invalid flag value or parameter was specified. 335 </p> 336 </div> 337 </div> 338 <div class="sect2" lang="en" xml:lang="en"> 339 <div class="titlepage"> 340 <div> 341 <div> 342 <h3 class="title"><a id="id1633193"></a>Class</h3> 343 </div> 344 </div> 345 </div> 346 <p> 347 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 348 </p> 349 </div> 350 <div class="sect2" lang="en" xml:lang="en"> 351 <div class="titlepage"> 352 <div> 353 <div> 354 <h3 class="title"><a id="id1633555"></a>See Also</h3> 355 </div> 356 </div> 357 </div> 358 <p> 359 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 360 </p> 361 </div> 362 </div> 363 <div class="navfooter"> 364 <hr /> 365 <table width="100%" summary="Navigation footer"> 366 <tr> 367 <td width="40%" align="left"><a accesskey="p" href="dbcompact.html">Prev</a>��</td> 368 <td width="20%" align="center"> 369 <a accesskey="u" href="db.html">Up</a> 370 </td> 371 <td width="40%" align="right">��<a accesskey="n" href="dberr.html">Next</a></td> 372 </tr> 373 <tr> 374 <td width="40%" align="left" valign="top">DB->compact()��</td> 375 <td width="20%" align="center"> 376 <a accesskey="h" href="index.html">Home</a> 377 </td> 378 <td width="40%" align="right" valign="top">��DB->err()</td> 379 </tr> 380 </table> 381 </div> 382 </body> 383</html> 384