1<!--$Id: db_put.so,v 10.60 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::put</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::put</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::put(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags); 26</pre></b> 27<hr size=1 noshade> 28<b>Description: Db::put</b> 29<p>The Db::put method stores key/data pairs in the database. The default 30behavior of the Db::put function is to enter the new key/data 31pair, replacing any previously existing key if duplicates are disallowed, 32or adding a duplicate data item if duplicates are allowed. If the database 33supports duplicates, the Db::put method adds the new data value at the 34end of the duplicate set. If the database supports sorted duplicates, 35the new data value is inserted at the correct sorted location.</p> 36<p>Unless otherwise specified, the Db::put method 37either returns a non-zero error value 38or throws an exception that encapsulates a non-zero error value on 39failure, and returns 0 on success. 40</p> 41<b>Parameters</b> <br> 42 <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or 43one of the following values: 44<br> 45<b><a name="DB_APPEND">DB_APPEND</a></b><ul compact><li>Append the key/data pair to the end of the database. For the 46DB_APPEND flag to be specified, the underlying database must be 47a Queue or Recno database. The record number allocated to the record is 48returned in the specified <b>key</b>. 49<p>There is a minor behavioral difference between the Recno and Queue access 50methods for the DB_APPEND flag. If a transaction enclosing a 51Db::put operation with the DB_APPEND flag aborts, the 52record number may be decremented (and later reallocated by a subsequent 53DB_APPEND operation) by the Recno access method, but will not be 54decremented or reallocated by the Queue access method.</p></ul> 55<b><a name="DB_NODUPDATA">DB_NODUPDATA</a></b><ul compact><li>In the case of the Btree and Hash access methods, enter the new key/data 56pair only if it does not already appear in the database. 57<p>The DB_NODUPDATA flag may only be specified if the underlying 58database has been configured to support sorted duplicates. The 59DB_NODUPDATA flag may not be specified to the Queue or Recno 60access methods.</p> 61<p>The Db::put method will return <a href="/api_cxx/dbc_put.html#DB_KEYEXIST">DB_KEYEXIST</a> if DB_NODUPDATA is set and the key/data pair already appears 62in the database. 63</p></ul> 64<b><a name="DB_NOOVERWRITE">DB_NOOVERWRITE</a></b><ul compact><li>Enter the new key/data pair only if the key does not already appear in the 65database. The Db::put method call with the DB_NOOVERWRITE flag 66set will fail if the key already exists in the database, even if the database 67supports duplicates. 68<p>The Db::put method will return <a href="/api_cxx/dbc_put.html#DB_KEYEXIST">DB_KEYEXIST</a> if DB_NOOVERWRITE is set and the key already appears in the 69database. 70</p></ul> 71<br></ul> 72 <b>data</b><ul compact><li>The data <a href="/api_cxx/dbt_class.html">Dbt</a> operated on.</ul> 73 <b>key</b><ul compact><li>The key <a href="/api_cxx/dbt_class.html">Dbt</a> operated on.</ul> 74 <b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 75<b>txnid</b> parameter is a transaction handle returned from 76<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 77<b>txnid</b> parameter is a handle returned from 78<a href="/api_cxx/env_cdsgroup_begin.html">DbEnv::cdsgroup_begin</a>; otherwise NULL. 79If no transaction handle is 80specified, but the 81operation occurs in a transactional 82database, 83the operation will be implicitly transaction protected. 84</ul> 85<br> 86<a name="2"><!--meow--></a> 87<a name="3"><!--meow--></a> 88<br><b>Errors</b> 89<p>The Db::put method 90may fail and throw 91<a href="/api_cxx/except_class.html">DbException</a>, 92encapsulating one of the following non-zero errors, or return one of 93the following non-zero errors:</p> 94<br> 95<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election 96unrolled a committed transaction.</ul> 97<br> 98<br> 99<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul> 100<br> 101<br> 102<b>EACCES</b><ul compact><li>An attempt was made to modify a read-only database.</ul> 103<br> 104<br> 105<b>EINVAL</b><ul compact><li>If a record number of 0 was specified; 106an attempt was made to add a record to a fixed-length database that was too 107large to fit; 108an attempt was made to do a partial put; 109an attempt was made to add a record to a secondary index; or if an 110invalid flag value or parameter was specified.</ul> 111<br> 112<br> 113<b>ENOSPC</b><ul compact><li>A btree exceeded the maximum btree depth (255).</ul> 114<br> 115<p>If a transactional database environment operation was selected to 116resolve a deadlock, the Db::put method will fail and 117either return <a href="/ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> or 118throw a <a href="/api_cxx/deadlock_class.html">DbDeadlockException</a> exception.</p> 119<p>If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable 120to grant a lock in the allowed time, the Db::put method will fail and 121either return <a href="/ref/program/errorret.html#DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a> or 122throw a <a href="/api_cxx/lockng_class.html">DbLockNotGrantedException</a> exception.</p> 123<hr size=1 noshade> 124<br><b>Class</b> 125<a href="/api_cxx/db_class.html">Db</a> 126<br><b>See Also</b> 127<a href="/api_cxx/db_list.html">Databases and Related Methods</a> 128</tt> 129<table width="100%"><tr><td><br></td><td align=right> 130<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> 131</td></tr></table> 132<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 133</body> 134</html> 135