mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 01:26:25 +00:00
253 lines
13 KiB
HTML
253 lines
13 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>dbc put</title>
|
||
<link rel="stylesheet" href="apiReference.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB TCL API Reference" />
|
||
<link rel="up" href="tclapi.html" title="Chapter 1. Berkeley DB Tcl APIs" />
|
||
<link rel="prev" href="dbc_get.html" title="dbc get" />
|
||
<link rel="next" href="env_close.html" title="env close" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.2</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center"><span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>dbc</em></span> put</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="dbc_get.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 1.
|
||
Berkeley DB Tcl APIs
|
||
</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="env_close.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="dbc_put"></a><span class="emphasis"><em>dbc</em></span> put</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<pre class="programlisting">dbc put
|
||
[-after]
|
||
[-before]
|
||
[-current]
|
||
[-partial {doff dlen}]
|
||
data
|
||
|
||
dbc put
|
||
[-keyfirst]
|
||
[-keylast]
|
||
[-partial {doff dlen}]
|
||
key data </pre>
|
||
<p>
|
||
The <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span>
|
||
command stores the specified key/data pair into the database. One of
|
||
the following options must be specified:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-after</strong></span>
|
||
</p>
|
||
<p>
|
||
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 <span class="bold"><strong>-after</strong></span> if
|
||
the underlying Btree or Hash database was not created with the
|
||
<span class="bold"><strong>-dup</strong></span> option. No key argument should
|
||
be specified.
|
||
</p>
|
||
<p>
|
||
In the case of the Recno access method, it is an error to specify the
|
||
<span class="bold"><strong>-after</strong></span> option if the underlying Recno
|
||
database was not created with the <span class="bold"><strong>-renumber</strong></span> option. If the <span class="bold"><strong>-renumber</strong></span> 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 <span class="bold"><strong>berkdb open</strong></span>
|
||
for more information.
|
||
</p>
|
||
<p>
|
||
In the case of the Queue access method, it is always an error to
|
||
specify <span class="bold"><strong>-after</strong></span>.
|
||
</p>
|
||
<p>
|
||
If the current cursor record has already been deleted, and the
|
||
underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying
|
||
access method is Btree or Recno, the operation will succeed.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-before</strong></span>
|
||
</p>
|
||
<p>
|
||
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 <span class="bold"><strong>-before</strong></span> if the underlying Btree or Hash
|
||
database was not created with the <span class="bold"><strong>-dup</strong></span> option. No key argument should be
|
||
specified.
|
||
</p>
|
||
<p>
|
||
In the case of the Recno access method, it is an error to specify
|
||
<span class="bold"><strong>-before</strong></span> if the underlying Recno
|
||
database was not created with the <span class="bold"><strong>-before</strong></span> option. If the <span class="bold"><strong>-before</strong></span> 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 <span class="bold"><strong>berkdb open</strong></span>
|
||
for more information.
|
||
</p>
|
||
<p>
|
||
In the case of the Queue access method, it is always an error to
|
||
specify <span class="bold"><strong>-before</strong></span>.
|
||
</p>
|
||
<p>
|
||
If the current cursor record has already been deleted and the
|
||
underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying
|
||
access method is Btree or Recno, the operation will succeed.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-current</strong></span>
|
||
</p>
|
||
<p>
|
||
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>
|
||
<p>
|
||
If the <span class="bold"><strong>-dupsort</strong></span> option was specified
|
||
to <span class="bold"><strong>berkdb open</strong></span> and the data item of
|
||
the key/data pair to which the cursor refers does not compare equally
|
||
to the data parameter, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error.
|
||
</p>
|
||
<p>
|
||
If the current cursor record has already been deleted and the
|
||
underlying access method is Hash, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> will throw a Tcl error. If the underlying
|
||
access method is Btree, Queue, or Recno, the operation will succeed.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-keyfirst</strong></span>
|
||
</p>
|
||
<p>
|
||
In the case of the Btree and Hash access methods, insert the specified
|
||
key/data pair into the database.
|
||
</p>
|
||
<p>
|
||
If the key already exists in the database, and the <span class="bold"><strong>-dupsort</strong></span> option was specified to <span class="bold"><strong>berkdb open</strong></span>, the inserted data item is added in
|
||
its sorted location. If the key already exists in the database, and
|
||
the <span class="bold"><strong>-dupsort</strong></span> option was not
|
||
specified, the inserted data item is added as the first of the data
|
||
items for that key.
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>-keyfirst</strong></span> option may not be
|
||
specified to the Queue or Recno access methods.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-keylast</strong></span>
|
||
</p>
|
||
<p>
|
||
In the case of the Btree and Hash access methods, insert the specified
|
||
key/data pair into the database.
|
||
</p>
|
||
<p>
|
||
If the key already exists in the database, and the <span class="bold"><strong>-dupsort</strong></span> option was specified to <span class="bold"><strong>berkdb open</strong></span>, the inserted data item is added in
|
||
its sorted location. If the key already exists in the database, and
|
||
the <span class="bold"><strong>-dupsort</strong></span> option was not
|
||
specified, the inserted data item is added as the last of the data
|
||
items for that key.
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>-keylast</strong></span> option may not be
|
||
specified to the Queue or Recno access methods.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-partial {doff dlen}</strong></span>
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>dlen</strong></span> bytes starting <span class="bold"><strong>doff</strong></span> 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 <span class="bold"><strong>dlen</strong></span> is
|
||
smaller than the length of the supplied data, the record will grow; if
|
||
<span class="bold"><strong>dlen</strong></span> 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 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> call
|
||
will succeed.
|
||
</p>
|
||
<p>
|
||
It is an error to attempt a partial put using the
|
||
<span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> command
|
||
in a database that supports duplicate records. Partial puts in
|
||
databases supporting duplicate records must be done using a
|
||
<span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> command.
|
||
</p>
|
||
<p>
|
||
It is an error to attempt a partial put with differing <span class="bold"><strong>dlen</strong></span> and supplied data length values in Queue
|
||
or Recno databases with fixed-length records.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<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 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> fails
|
||
for any reason, the state of the cursor will be unchanged. If
|
||
<span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span> succeeds
|
||
and an item is inserted into the database, the cursor is always
|
||
positioned to refer to the newly inserted item.
|
||
</p>
|
||
<p>
|
||
The <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span>
|
||
command returns 0 on success, and in the case of error, a Tcl error is
|
||
thrown.
|
||
</p>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="dbc_get.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="tclapi.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="env_close.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top"><span class="emphasis"><em>dbc</em></span> get </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> <span class="emphasis"><em>env</em></span> close</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|