docs/api_tcl/dbc_put.html

<!--$Id: dbc_put.so,v 11.18 2004/12/02 18:21:08 bostic Exp $-->
<!--$Id: m4.tcl,v 11.28 2004/12/16 19:13:05 bostic Exp $-->
<!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB: dbc put</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td>
<b><i>dbc</i> <b>put</b></b>
</td>
<td align=right>
<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></td>
</tr></table>
<hr size=1 noshade>
<tt>
<b><pre>dbc put
	[-after]
	[-before]
	[-current]
	[-partial {doff dlen}]
	data
dbc put
	[-keyfirst]
	[-keylast]
	[-partial {doff dlen}]
	key data
</pre></b>
<b>Description(dbc put)</b>
<p>The <i>dbc</i> <b>put</b> command stores the specified key/data pair into the
database.  One of the following options must be specified:</p>
<br>
<b>-after</b><ul compact><li>In the case of the Btree and Hash access methods, insert the data element
as a duplicate element of the key to which the cursor refers. The new
element appears immediately after the current cursor position. It is an
error to specify <b>-after</b> if the underlying Btree or Hash database
was not created with the <b>-dup</b> option. No key argument should be
specified.
<p>In the case of the Recno access method, it is an error to specify the
<b>-after</b> option if the underlying Recno database was not created
with the <b>-renumber</b> option.  If the <b>-renumber</b> option was
specified, a new key is created, all records after the inserted item
are automatically renumbered, and the key of the new record is returned
in the structure to which the key argument refers. The initial value of
the key parameter is ignored. See <b>berkdb open</b> for more information.</p>
<p>In the case of the Queue access method, it is always an error to specify
<b>-after</b>.</p>
<p>If the current cursor record has already been deleted, and the underlying
access method is Hash, <i>dbc</i> <b>put</b> will throw a Tcl error. If the
underlying access method is Btree or Recno, the operation will succeed.</p></ul>
<b>-before</b><ul compact><li>In the case of the Btree and Hash access methods, insert the data element
as a duplicate element of the key to which the cursor refers. The new
element appears immediately before the current cursor position. It is an
error to specify <b>-before</b> if the underlying Btree or Hash database
was not created with the <b>-dup</b> option. No key argument should be
specified.
<p>In the case of the Recno access method, it is an error to specify
<b>-before</b> if the underlying Recno database was not created with the
<b>-before</b> option.  If the <b>-before</b> option was specified, a
new key is created, the current record and all records after it are
automatically renumbered, and the key of the new record is returned in
the structure to which the key argument refers.  The initial value of the
key parameter is ignored. See <b>berkdb open</b> for more information.</p>
<p>In the case of the Queue access method, it is always an error to specify
<b>-before</b>.</p>
<p>If the current cursor record has already been deleted and the underlying
access method is Hash, <i>dbc</i> <b>put</b> will throw a Tcl error. If the
underlying access method is Btree or Recno, the operation will succeed.</p></ul>
<b>-current</b><ul compact><li>Overwrite the data of the key/data pair to which the cursor refers with
the specified data item.  No key argument should be specified.
<p>If the <b>-dupsort</b> option was specified to <b>berkdb open</b> and the
data item of the key/data pair to which the cursor refers does not
compare equally to the data parameter, <i>dbc</i> <b>put</b> will throw a Tcl
error.</p>
<p>If the current cursor record has already been deleted and the underlying
access method is Hash, <i>dbc</i> <b>put</b> will throw a Tcl error. If the
underlying access method is Btree, Queue, or Recno, the operation will
succeed.</p></ul>
<b>-keyfirst</b><ul compact><li>In the case of the Btree and Hash access methods, insert the specified
key/data pair into the database.
<p>If the key already exists in the database, and the <b>-dupsort</b> option
was specified to <b>berkdb open</b>, the inserted data item is added in its
sorted location.  If the key already exists in the database, and the
<b>-dupsort</b> option was not specified, the inserted data item is added
as the first of the data items for that key.</p>
<p>The <b>-keyfirst</b> option may not be specified to the Queue or Recno
access methods.</p></ul>
<b>-keylast</b><ul compact><li>In the case of the Btree and Hash access methods, insert the specified
key/data pair into the database.
<p>If the key already exists in the database, and the <b>-dupsort</b> option
was specified to <b>berkdb open</b>, the inserted data item is added in its
sorted location.  If the key already exists in the database, and the
<b>-dupsort</b> option was not specified, the inserted data item is added
as the last of the data items for that key.</p>
<p>The <b>-keylast</b> option may not be specified to the Queue or Recno
access methods.</p></ul>
<b>-partial {doff dlen}</b><ul compact><li><p>The <b>dlen</b> bytes starting <b>doff</b> bytes from the beginning
of the specified key's data record are replaced by the data specified
by the data and size structure elements.  If <b>dlen</b> is smaller
than the length of the supplied data, the record will grow; if
<b>dlen</b> is larger than the length of the supplied data, the record
will shrink.  If the specified bytes do not exist, the record will be
extended using nul bytes as necessary, and the <i>dbc</i> <b>put</b> call will succeed.
</p>
<p>It is an error to attempt a partial put using the <i>dbc</i> <b>put</b> command in a database
that supports duplicate records. Partial puts in databases supporting
duplicate records must be done using a <i>dbc</i> <b>put</b> command.</p>
<p>It is an error to attempt a partial put with differing <b>dlen</b> and
supplied data length values in Queue or Recno databases with fixed-length
records.</p></ul>
<br>
<p>If a key is specified, and
if the underlying database is a Queue or Recno database, the given key
will be interpreted by Tcl as an integer.  For all other database types,
the key is interpreted by Tcl as a byte array.</p>
<p>If <i>dbc</i> <b>put</b> fails for any reason, the state of the cursor will be
unchanged. If <i>dbc</i> <b>put</b> succeeds and an item is inserted into the
database, the cursor is always positioned to refer to the newly inserted
item.</p>
<p>The <i>dbc</i> <b>put</b> command returns 0 on success, and in the case of error, a Tcl error
is thrown.</p>
</tt>
<table width="100%"><tr><td><br></td><td align=right>
<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>
</td></tr></table>
<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
</body>
</html>