1<!--$Id: db_del.so,v 10.51 2007/10/24 16:06:06 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: Db::del</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>Db::del</b> 14</td> 15<td align=right> 16<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db_cxx.h> 23<p> 24int 25Db::del(DbTxn *txnid, Dbt *key, u_int32_t flags); 26</pre></b> 27<hr size=1 noshade> 28<b>Description: Db::del</b> 29<p>The Db::del method removes key/data pairs from the database. The 30key/data pair associated with the specified <b>key</b> is discarded from 31the database. In the presence of duplicate key values, all records 32associated with the designated key will be discarded.</p> 33<p>When called on a database that has been made into a secondary index 34using the <a href="../api_cxx/db_associate.html">Db::associate</a> method, the Db::del method deletes the 35key/data pair from the primary database and all secondary indices.</p> 36<p>The Db::del method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if the specified key is not in the database. 37The Db::del method will return <a href="../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a> if the database is a Queue or Recno database and 38the specified key exists, but was never explicitly created by the 39application or was later deleted. 40Unless otherwise specified, the Db::del method 41either returns a non-zero error value 42or throws an exception that encapsulates a non-zero error value on 43failure, and returns 0 on success. 44</p> 45<b>Parameters</b> <br> 46 <b>flags</b><ul compact><li>The <b>flags</b> parameter is currently unused, and must be set to 0.</ul> 47 <b>key</b><ul compact><li>The key <a href="../api_cxx/dbt_class.html">Dbt</a> operated on.</ul> 48 <b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 49<b>txnid</b> parameter is a transaction handle returned from 50<a href="../api_cxx/txn_begin.html">DbEnv::txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the 51<b>txnid</b> parameter is a handle returned from 52<a href="../api_cxx/env_cdsgroup_begin.html">DbEnv::cdsgroup_begin</a>; otherwise NULL. 53If no transaction handle is 54specified, but the 55operation occurs in a transactional 56database, 57the operation will be implicitly transaction protected. 58</ul> 59<br> 60<br><b>Errors</b> 61<p>The Db::del method 62may fail and throw 63<a href="../api_cxx/except_class.html">DbException</a>, 64encapsulating one of the following non-zero errors, or return one of 65the following non-zero errors:</p> 66<br> 67<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election 68unrolled a committed transaction.</ul> 69<br> 70<br> 71<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul> 72<br> 73<br> 74<b>DB_SECONDARY_BAD</b><ul compact><li>A secondary index references a nonexistent primary key.</ul> 75<br> 76<br> 77<b>EACCES</b><ul compact><li>An attempt was made to modify a read-only database.</ul> 78<br> 79<br> 80<b>EINVAL</b><ul compact><li>An 81invalid flag value or parameter was specified.</ul> 82<br> 83<p>If a transactional database environment operation was selected to 84resolve a deadlock, the Db::del method will fail and 85either return <a href="../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> or 86throw a <a href="../api_cxx/deadlock_class.html">DbDeadlockException</a> exception.</p> 87<p>If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable 88to grant a lock in the allowed time, the Db::del method will fail and 89either return <a href="../ref/program/errorret.html#DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a> or 90throw a <a href="../api_cxx/lockng_class.html">DbLockNotGrantedException</a> exception.</p> 91<hr size=1 noshade> 92<br><b>Class</b> 93<a href="../api_cxx/db_class.html">Db</a> 94<br><b>See Also</b> 95<a href="../api_cxx/db_list.html">Databases and Related Methods</a> 96</tt> 97<table width="100%"><tr><td><br></td><td align=right> 98<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 99</td></tr></table> 100<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 101</body> 102</html> 103
