1<!--$Id: db_put.so,v 11.14 2004/12/16 19:13:05 bostic Exp $--> 2<!--$Id: m4.tcl,v 11.28 2004/12/16 19:13:05 bostic Exp $--> 3<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 4<!--See the file LICENSE for redistribution information.--> 5<html> 6<head> 7<title>Berkeley DB: db put</title> 8<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 9<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 10</head> 11<body bgcolor=white> 12<table width="100%"><tr valign=top> 13<td> 14<b><i>db</i> <b>put</b></b> 15</td> 16<td align=right> 17<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a> 18<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 19</tr></table> 20<hr size=1 noshade> 21<tt> 22<b><pre>db put 23 -append 24 [-partial {doff dlen}] 25 [-txn txnid] 26 data 27db put 28 [-nooverwrite] 29 [-partial {doff dlen}] 30 [-txn txnid] 31 key data 32</pre></b> 33<b>Description(db put)</b> 34<p>The <i>db</i> <b>put</b> command stores the specified key/data pair into the 35database.</p> 36<p>The options are as follows:</p> 37<br> 38<b>-append</b><ul compact><li>Append the data item to the end of the database. For the <b>-append</b> 39option to be specified, the underlying database must be a Queue or Recno 40database. The record number allocated to the record is returned on 41success.</ul> 42<b>-nooverwrite</b><ul compact><li>Enter the new key/data pair only if the key does not already appear in 43the database.</ul> 44<b>-partial {doff dlen}</b><ul compact><li><p>The <b>dlen</b> bytes starting <b>doff</b> bytes from the beginning 45of the specified key's data record are replaced by the data specified 46by the data and size structure elements. If <b>dlen</b> is smaller 47than the length of the supplied data, the record will grow; if 48<b>dlen</b> is larger than the length of the supplied data, the record 49will shrink. If the specified bytes do not exist, the record will be 50extended using nul bytes as necessary, and the <i>db</i> <b>put</b> call will succeed. 51<p>It is an error to attempt a partial put using the <i>db</i> <b>put</b> command in a database 52that supports duplicate records. Partial puts in databases supporting 53duplicate records must be done using a <i>dbc</i> <b>put</b> command.</p> 54<p>It is an error to attempt a partial put with differing <b>dlen</b> and 55supplied data length values in Queue or Recno databases with fixed-length 56records.</p></ul> 57<b>-txn txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 58<b>txnid</b> parameter is a transaction handle returned from 59<i>env</i> <b>txn</b>. If no transaction handle is specified, but the 60operation occurs in a transactional 61database, 62the operation will be implicitly transaction protected.</ul> 63<br> 64<p>The <i>db</i> <b>put</b> command returns either 0 or a record number for success 65(the record number is returned if the <b>-append</b> option was specified). 66If an error occurs, a Berkeley DB error message is returned or a Tcl error is 67thrown.</p> 68<p>If the underlying database is a Queue or Recno database, then the given 69key will be interpreted by Tcl as an integer. For all other database 70types, the key is interpreted by Tcl as a byte array.</p> 71</tt> 72<table width="100%"><tr><td><br></td><td align=right> 73<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 74</td></tr></table> 75<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 76</body> 77</html> 78