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_cxx.h> 39 40int 41Db::del(DbTxn *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 61 <span> 62 method either returns a non-zero error value or throws an 63 exception that encapsulates a non-zero error value on 64 failure, and returns 0 on success. 65 </span> 66 </span> 67 </p> 68 <div class="sect2" lang="en" xml:lang="en"> 69 <div class="titlepage"> 70 <div> 71 <div> 72 <h3 class="title"><a id="id1632214"></a>Parameters</h3> 73 </div> 74 </div> 75 </div> 76 <div class="sect3" lang="en" xml:lang="en"> 77 <div class="titlepage"> 78 <div> 79 <div> 80 <h4 class="title"><a id="id1632915"></a>flags</h4> 81 </div> 82 </div> 83 </div> 84 <p> 85 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 86 or one of the following values: 87 </p> 88 <div class="itemizedlist"> 89 <ul type="disc"> 90 <li> 91 <p><a id="dbput_DB_CONSUME"></a> 92 <code class="literal">DB_CONSUME</code> 93 </p> 94 <p> 95 If the database is of type DB_QUEUE then this flag may be set to force the head of the queue 96 to move to the first non-deleted item in the queue. Normally this is only done if the 97 deleted item is exactly at the head when deleted. 98 </p> 99 </li> 100 <li> 101 <p><a id="del_DB_MULTIPLE"></a> 102 <code class="literal">DB_MULTIPLE</code> 103 </p> 104 <p> 105 Delete multiple data items using keys from the buffer to which the 106 <span class="bold"><strong>key</strong></span> parameter refers. 107 </p> 108 <p> 109 To delete records in bulk by key with the btree or hash access methods, construct a 110 bulk buffer in the <span class="bold"><strong>key</strong></span> 111 <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> using 112 <a class="xref" href="dbmultipledatabuilder.html" title="DbMultipleDataBuilder">DbMultipleDataBuilder</a>. 113 To delete records in bulk by record number, construct a bulk buffer in the 114 <span class="bold"><strong>key</strong></span> 115 <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> using 116 <a class="xref" href="dbmultiplerecnodatabuilder.html" title="DbMultipleRecnoDataBuilder">DbMultipleRecnoDataBuilder</a> 117 with a data size of zero. 118 </p> 119 <p> 120 A successful bulk delete operation is logically equivalent to a loop through each 121 key/data pair, performing a <a class="xref" href="dbdel.html" title="Db::del()">Db::del()</a> for each one. 122 </p> 123 <p> 124 See the <a class="xref" href="dbt.html#dbtlist" title="DBT and Bulk Operations">DBT and Bulk Operations</a> for more information on 125 working with bulk updates. 126 </p> 127 <p> 128 The <code class="literal">DB_MULTIPLE</code> flag may only be used alone. 129 </p> 130 </li> 131 <li> 132 <p><a id="del_DB_MULTIPLE_KEY"></a> 133 <code class="literal">DB_MULTIPLE_KEY</code> 134 </p> 135 <p> 136 Delete multiple data items using keys and data from the buffer to which the 137 <span class="bold"><strong>key</strong></span> parameter refers. 138 </p> 139 <p> 140 To delete records in bulk with the btree or hash access methods, construct a bulk 141 buffer in the <span class="bold"><strong>key</strong></span> 142 <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> using 143 <a class="xref" href="dbmultiplekeydatabuilder.html" title="DbMultipleKeyDataBuilder">DbMultipleKeyDataBuilder</a>. 144 To delete records in bulk with the recno or hash access methods, construct a bulk 145 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="dbmultiplerecnodatabuilder.html" title="DbMultipleRecnoDataBuilder">DbMultipleRecnoDataBuilder</a>. 148 </p> 149 <p> 150 See the <a class="xref" href="dbt.html#dbtlist" title="DBT and Bulk Operations">DBT and Bulk Operations</a> for more information on 151 working with bulk updates. 152 </p> 153 <p> 154 The <code class="literal">DB_MULTIPLE_KEY</code> flag may only be used alone. 155 </p> 156 </li> 157 </ul> 158 </div> 159 </div> 160 <div class="sect3" lang="en" xml:lang="en"> 161 <div class="titlepage"> 162 <div> 163 <div> 164 <h4 class="title"><a id="id1633193"></a>key</h4> 165 </div> 166 </div> 167 </div> 168 <p> 169 The key <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> operated on. 170 </p> 171 </div> 172 <div class="sect3" lang="en" xml:lang="en"> 173 <div class="titlepage"> 174 <div> 175 <div> 176 <h4 class="title"><a id="id1633277"></a>txnid</h4> 177 </div> 178 </div> 179 </div> 180 <p> 181 If the operation is part of an application-specified transaction, the 182 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 183 handle returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>; 184 if the operation is part of a Berkeley DB Concurrent Data Store group, the 185 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 186 from <a class="xref" href="envcdsgroup_begin.html" title="DbEnv::cdsgroup_begin()">DbEnv::cdsgroup_begin()</a>; 187 otherwise NULL. If no transaction handle is specified, but the 188 operation occurs in a transactional database, the operation will be 189 implicitly transaction protected. 190 </p> 191 </div> 192 </div> 193 <div class="sect2" lang="en" xml:lang="en"> 194 <div class="titlepage"> 195 <div> 196 <div> 197 <h3 class="title"><a id="id1632500"></a>Errors</h3> 198 </div> 199 </div> 200 </div> 201 <p> 202 The <code class="methodname">Db::del()</code> <span> 203 204 <span> 205 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 206 exception, encapsulating one of the following non-zero errors, or return one 207 of the following non-zero errors: 208 </span> 209 </span> 210 </p> 211 <div class="sect3" lang="en" xml:lang="en"> 212 <div class="titlepage"> 213 <div> 214 <div> 215 <h4 class="title"><a id="id1633360"></a>DB_FOREIGN_CONFLICT</h4> 216 </div> 217 </div> 218 </div> 219 <p> 220 A <a class="link" href="dbassociate_foreign.html" title="Db::associate_foreign()">foreign key constraint violation</a> 221 has occurred. This can be caused by one of two things: 222 </p> 223 <div class="orderedlist"> 224 <ol type="1"> 225 <li> 226 <p> 227 An attempt was made to add a record to a 228 constrained database, and the key used for that 229 record does not exist in the foreign key 230 database. 231 </p> 232 </li> 233 <li> 234 <p> 235 <a class="link" href="dbassociate_foreign.html#associate_foreign_DB_FOREIGN_ABORT">DB_FOREIGN_ABORT</a> 236 was declared for a foreign key database, and then 237 subsequently a record was deleted from the 238 foreign key database without first removing it 239 from the constrained secondary database. 240 </p> 241 </li> 242 </ol> 243 </div> 244 </div> 245 <div class="sect3" lang="en" xml:lang="en"> 246 <div class="titlepage"> 247 <div> 248 <div> 249 <h4 class="title"><a id="id1633001"></a><span>DbDeadlockException or </span>DB_LOCK_DEADLOCK</h4> 250 </div> 251 </div> 252 </div> 253 <p> 254 A transactional database environment operation was selected to resolve 255 a deadlock. 256 </p> 257 <p> 258 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 259 your Berkeley DB API is configured to throw exceptions. 260 Otherwise, <code class="literal">DB_LOCK_DEADLOCK</code> is returned. 261 </p> 262 </div> 263 <div class="sect3" lang="en" xml:lang="en"> 264 <div class="titlepage"> 265 <div> 266 <div> 267 <h4 class="title"><a id="id1633256"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4> 268 </div> 269 </div> 270 </div> 271 <p> 272 A Berkeley DB Concurrent Data Store database environment configured 273 for lock timeouts was unable to grant a lock in the allowed time. 274 </p> 275 <p> 276 <a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if 277 your Berkeley DB API is configured to throw exceptions. 278 Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned. 279 </p> 280 </div> 281 <div class="sect3" lang="en" xml:lang="en"> 282 <div class="titlepage"> 283 <div> 284 <div> 285 <h4 class="title"><a id="id1633442"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4> 286 </div> 287 </div> 288 </div> 289 <p> 290 When a client synchronizes with the master, it is possible for committed 291 transactions to be rolled back. This invalidates all the database and cursor 292 handles opened in the replication environment. Once this occurs, an attempt to use 293 such a handle will 294 <span> 295 throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if 296 your application is configured to throw exceptions), or 297 </span> 298 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 299 The application will need to discard the handle and open a new one in order to 300 continue processing. 301 </p> 302 </div> 303 <div class="sect3" lang="en" xml:lang="en"> 304 <div class="titlepage"> 305 <div> 306 <div> 307 <h4 class="title"><a id="id1633538"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4> 308 </div> 309 </div> 310 </div> 311 <p> 312 The operation was blocked by client/master synchronization. 313 </p> 314 <p> 315 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 316 your Berkeley DB API is configured to throw exceptions. 317 Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned. 318 </p> 319 </div> 320 <div class="sect3" lang="en" xml:lang="en"> 321 <div class="titlepage"> 322 <div> 323 <div> 324 <h4 class="title"><a id="id1633363"></a>DB_SECONDARY_BAD</h4> 325 </div> 326 </div> 327 </div> 328 <p> 329 A secondary index references a nonexistent primary key. 330 </p> 331 </div> 332 <div class="sect3" lang="en" xml:lang="en"> 333 <div class="titlepage"> 334 <div> 335 <div> 336 <h4 class="title"><a id="id1633057"></a>EACCES</h4> 337 </div> 338 </div> 339 </div> 340 <p> 341 An attempt was made to modify a read-only database. 342 </p> 343 </div> 344 <div class="sect3" lang="en" xml:lang="en"> 345 <div class="titlepage"> 346 <div> 347 <div> 348 <h4 class="title"><a id="id1633534"></a>EINVAL</h4> 349 </div> 350 </div> 351 </div> 352 <p> 353 An invalid flag value or parameter was specified. 354 </p> 355 </div> 356 </div> 357 <div class="sect2" lang="en" xml:lang="en"> 358 <div class="titlepage"> 359 <div> 360 <div> 361 <h3 class="title"><a id="id1633215"></a>Class</h3> 362 </div> 363 </div> 364 </div> 365 <p> 366 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 367 </p> 368 </div> 369 <div class="sect2" lang="en" xml:lang="en"> 370 <div class="titlepage"> 371 <div> 372 <div> 373 <h3 class="title"><a id="id1632981"></a>See Also</h3> 374 </div> 375 </div> 376 </div> 377 <p> 378 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 379 </p> 380 </div> 381 </div> 382 <div class="navfooter"> 383 <hr /> 384 <table width="100%" summary="Navigation footer"> 385 <tr> 386 <td width="40%" align="left"><a accesskey="p" href="dbcompact.html">Prev</a> </td> 387 <td width="20%" align="center"> 388 <a accesskey="u" href="db.html">Up</a> 389 </td> 390 <td width="40%" align="right"> <a accesskey="n" href="dberr.html">Next</a></td> 391 </tr> 392 <tr> 393 <td width="40%" align="left" valign="top">Db::compact() </td> 394 <td width="20%" align="center"> 395 <a accesskey="h" href="index.html">Home</a> 396 </td> 397 <td width="40%" align="right" valign="top"> Db::err()</td> 398 </tr> 399 </table> 400 </div> 401 </body> 402</html> 403