mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 09:36:24 +00:00
254 lines
13 KiB
HTML
254 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>
|