mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 09:36:24 +00:00
580 lines
28 KiB
HTML
580 lines
28 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>Chapter 4. The Dbt Handle</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 C++ API Reference" />
|
|||
|
|
<link rel="up" href="index.html" title="Berkeley DB C++ API Reference" />
|
|||
|
|
<link rel="prev" href="dbcset_priority.html" title="Dbc::set_priority()" />
|
|||
|
|
<link rel="next" href="dbmultipleiterator.html" title="DbMultipleIterator" />
|
|||
|
|
</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">Chapter 4.
|
|||
|
|
The Dbt Handle
|
|||
|
|
</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="20%" align="left"><a accesskey="p" href="dbcset_priority.html">Prev</a> </td>
|
|||
|
|
<th width="60%" align="center"> </th>
|
|||
|
|
<td width="20%" align="right"> <a accesskey="n" href="dbmultipleiterator.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
<hr />
|
|||
|
|
</div>
|
|||
|
|
<div class="chapter" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h2 class="title"><a id="dbt"></a>Chapter 4.
|
|||
|
|
The Dbt Handle
|
|||
|
|
</h2>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<pre class="programlisting">#include <db_cxx.h>
|
|||
|
|
|
|||
|
|
class Dbt {
|
|||
|
|
public:
|
|||
|
|
Dbt(void *data, size_t size);
|
|||
|
|
Dbt();
|
|||
|
|
Dbt(const Dbt &);
|
|||
|
|
Dbt &operator = (const Dbt &);
|
|||
|
|
~Dbt();
|
|||
|
|
|
|||
|
|
void *get_data() const;
|
|||
|
|
void set_data(void *);
|
|||
|
|
|
|||
|
|
u_int32_t get_size() const;
|
|||
|
|
void set_size(u_int32_t);
|
|||
|
|
|
|||
|
|
u_int32_t get_ulen() const;
|
|||
|
|
void set_ulen(u_int32_t);
|
|||
|
|
|
|||
|
|
u_int32_t get_dlen() const;
|
|||
|
|
void set_dlen(u_int32_t);
|
|||
|
|
|
|||
|
|
u_int32_t get_doff() const;
|
|||
|
|
void set_doff(u_int32_t);
|
|||
|
|
|
|||
|
|
u_int32_t get_flags() const;
|
|||
|
|
void set_flags(u_int32_t);
|
|||
|
|
|
|||
|
|
DBT *Dbt::get_DBT();
|
|||
|
|
const DBT *Dbt::get_const_DBT() const;
|
|||
|
|
static Dbt *Dbt::get_Dbt(DBT *dbt);
|
|||
|
|
static const Dbt *Dbt::get_const_Dbt(const DBT *dbt);
|
|||
|
|
}; </pre>
|
|||
|
|
<p>
|
|||
|
|
The <code class="classname">Dbt</code> class is used to encode key and data
|
|||
|
|
items in a Berkeley DB database.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Storage and retrieval for the <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> access methods are
|
|||
|
|
based on key/data pairs. Both key and data items are represented by
|
|||
|
|
|
|||
|
|
<span>
|
|||
|
|
<code class="classname">Dbt</code> objects.
|
|||
|
|
</span>
|
|||
|
|
Key and data byte strings may refer to strings of zero length up to strings of essentially
|
|||
|
|
unlimited length. See <a href="../../programmer_reference/am_misc_dbsizes.html" class="olink">Database limits</a> for
|
|||
|
|
more information.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
|
|||
|
|
<span>
|
|||
|
|
In the case when the <span class="bold"><strong>flags</strong></span> structure element is set to
|
|||
|
|
0,
|
|||
|
|
</span>
|
|||
|
|
|
|||
|
|
when the application is providing Berkeley DB a key or data item to store into the database,
|
|||
|
|
Berkeley DB expects the <span class="bold"><strong>data</strong></span>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<span>
|
|||
|
|
object
|
|||
|
|
</span>
|
|||
|
|
|
|||
|
|
to point to a byte string of <span class="bold"><strong>size</strong></span> bytes. When returning a
|
|||
|
|
key/data item to the application, Berkeley DB will store into the <span class="bold"><strong>data</strong></span>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<span>
|
|||
|
|
object
|
|||
|
|
</span>
|
|||
|
|
a pointer to a byte string of <span class="bold"><strong>size</strong></span> bytes,
|
|||
|
|
and the memory to which the pointer refers will be
|
|||
|
|
allocated and managed by Berkeley DB. Note that using the default flags
|
|||
|
|
for returned <code class="classname">Dbt</code>s is only compatible with
|
|||
|
|
single threaded usage of Berkeley DB.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Access to <code class="classname">Dbt</code> objects is not re-entrant. In particular, if multiple
|
|||
|
|
threads simultaneously access the same Dbt object using
|
|||
|
|
<a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> API calls, the results are undefined, and may
|
|||
|
|
result in a crash. One easy way to avoid problems is to use <code class="classname">Dbt</code>
|
|||
|
|
objects that are constructed as stack variables.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Each <code class="classname">Dbt</code> object has an associated <code class="literal">DBT</code> struct,
|
|||
|
|
which is used by the underlying implementation of Berkeley DB and its C-language API. The
|
|||
|
|
<code class="methodname">Dbt::get_DBT()</code> method returns a pointer to this struct. Given a
|
|||
|
|
const <code class="classname">Dbt</code> object, <code class="methodname">Dbt::get_const_DBT()</code>
|
|||
|
|
returns a const pointer to the same struct.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Given a <code class="literal">DBT</code> struct, the <code class="methodname">Dbt::get_Dbt()</code> method
|
|||
|
|
returns the corresponding <code class="classname">Dbt</code> object, if there is one. If the
|
|||
|
|
<code class="literal">DBT</code> object was not associated with a <code class="classname">Dbt</code> (that is,
|
|||
|
|
it was not returned from a call to <code class="methodname">Dbt::get_DBT()</code>), then the
|
|||
|
|
result of <code class="methodname">Dbt::get_Dbt()</code> is undefined. Given a const
|
|||
|
|
<code class="literal">DBT</code> struct, <code class="methodname">Dbt::get_const_Dbt()</code> returns the
|
|||
|
|
associated const <code class="classname">Dbt</code> object, if there is one.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
These methods may be useful for Berkeley DB applications including both C and C++ language
|
|||
|
|
software. It should not be necessary to use these calls in a purely C++ application.
|
|||
|
|
</p>
|
|||
|
|
<div class="itemizedlist">
|
|||
|
|
<ul type="disc">
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::set_data(void *data)</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Set the data array.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The <code class="literal">data</code> parameter is an array
|
|||
|
|
of bytes to be used to set the content for the
|
|||
|
|
<code class="classname">Dbt</code>.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::get_data()</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Return the data array.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::set_size(u_int32_t size)</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Sets the byte size of the data array, in bytes.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::get_size()</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Return the data array size.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::set_ulen(u_int32_t value)</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Set the byte size of the user-specified buffer.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Note that applications can determine the length of a record by setting
|
|||
|
|
the <code class="literal">ulen</code> field to 0 and checking the return value in the
|
|||
|
|
<span class="bold"><strong>size</strong></span> field. See
|
|||
|
|
the <code class="literal">DB_DBT_USERMEM</code> flag for more information.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::get_ulen()</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Return the length in bytes of the user-specified
|
|||
|
|
buffer.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Note that applications can determine the length of a record by setting
|
|||
|
|
the <code class="literal">ulen</code> field to 0 and checking the return value in the
|
|||
|
|
<span class="bold"><strong>size</strong></span> field. See
|
|||
|
|
the <code class="literal">DB_DBT_USERMEM</code> flag for more information.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::set_dlen(u_int32_t dlen)</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
|
|||
|
|
<span>
|
|||
|
|
Set the
|
|||
|
|
</span>
|
|||
|
|
length of the partial record being read or written by the
|
|||
|
|
application, in bytes. See the <code class="literal">DB_DBT_PARTIAL</code>
|
|||
|
|
flag for more information.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::get_dlen()</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Return the length of the partial record, in bytes.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::set_doff(u_int32_t value)</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
|
|||
|
|
<span>
|
|||
|
|
Sets the
|
|||
|
|
</span>
|
|||
|
|
offset of the partial record being read or written by the application,
|
|||
|
|
in bytes. See the <code class="literal">DB_DBT_PARTIAL</code> flag for more information.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::get_doff()</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Return the offset of the partial record, in bytes.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="methodname">Dbt::set_flags(u_int32_t flags)</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Set the object flag value.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 or
|
|||
|
|
by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together
|
|||
|
|
one or more of the following values:
|
|||
|
|
</p>
|
|||
|
|
<span>
|
|||
|
|
<div class="itemizedlist"><ul type="circle"><li><p><a id="dbt_DB_DBT_MALLOC"></a>
|
|||
|
|
<code class="literal">DB_DBT_MALLOC</code>
|
|||
|
|
</p><p>
|
|||
|
|
When this flag is set, Berkeley DB will allocate memory
|
|||
|
|
for the returned key or data item (using
|
|||
|
|
<span class="bold"><strong>malloc</strong></span>(3), or
|
|||
|
|
the user-specified malloc function), and return a
|
|||
|
|
pointer to it in the
|
|||
|
|
<span class="bold"><strong>data</strong></span> field of the key or data
|
|||
|
|
<code class="literal">DBT</code>
|
|||
|
|
structure. Because any allocated memory becomes the
|
|||
|
|
responsibility of the calling application, the caller
|
|||
|
|
must determine whether memory was allocated using the
|
|||
|
|
returned value of the
|
|||
|
|
<span class="bold"><strong>data</strong></span> field.
|
|||
|
|
</p><p>
|
|||
|
|
It is an error to specify more than one of
|
|||
|
|
<code class="literal">DB_DBT_MALLOC</code>,
|
|||
|
|
<code class="literal">DB_DBT_REALLOC</code>, and
|
|||
|
|
<code class="literal">DB_DBT_USERMEM</code>.
|
|||
|
|
</p></li><li><p><a id="dbt_DB_DBT_REALLOC"></a>
|
|||
|
|
<code class="literal">DB_DBT_REALLOC</code>
|
|||
|
|
</p><p>
|
|||
|
|
When this flag is set Berkeley DB will allocate memory
|
|||
|
|
for the returned key or data item (using
|
|||
|
|
<span class="bold"><strong>realloc</strong></span>(3), or
|
|||
|
|
the user-specified realloc function), and return a
|
|||
|
|
pointer to it in the
|
|||
|
|
<span class="bold"><strong>data</strong></span> field of the key or data DBT
|
|||
|
|
structure. Because any allocated memory becomes the
|
|||
|
|
responsibility of the calling application, the caller
|
|||
|
|
must determine whether memory was allocated using the
|
|||
|
|
returned value of the
|
|||
|
|
<span class="bold"><strong>data</strong></span> field.
|
|||
|
|
</p><p>
|
|||
|
|
It is an error to specify more than one of
|
|||
|
|
<code class="literal">DB_DBT_MALLOC</code>,
|
|||
|
|
<code class="literal">DB_DBT_REALLOC</code>, and
|
|||
|
|
<code class="literal">DB_DBT_USERMEM</code>.
|
|||
|
|
</p></li><li><p><a id="dbt_DB_DBT_USERMEM"></a>
|
|||
|
|
<code class="literal">DB_DBT_USERMEM</code>
|
|||
|
|
</p><p>
|
|||
|
|
The <span class="emphasis"><em>data</em></span>
|
|||
|
|
field of the key or data structure must refer
|
|||
|
|
to memory that is at least
|
|||
|
|
<span class="emphasis"><em>ulen</em></span>
|
|||
|
|
bytes in length. If the
|
|||
|
|
length of the requested item is less than or equal to
|
|||
|
|
that number of bytes, the item is copied into the memory
|
|||
|
|
to which the
|
|||
|
|
<span class="emphasis"><em>data</em></span>
|
|||
|
|
field refers. Otherwise, the
|
|||
|
|
<span class="emphasis"><em>size</em></span>
|
|||
|
|
field is set to the length needed for the requested
|
|||
|
|
item, and the error
|
|||
|
|
<code class="literal">DB_BUFFER_SMALL</code> is returned.
|
|||
|
|
</p><p>
|
|||
|
|
It is an error to specify more than one of
|
|||
|
|
<code class="literal">DB_DBT_MALLOC</code>,
|
|||
|
|
<code class="literal">DB_DBT_REALLOC</code>, and
|
|||
|
|
<code class="literal">DB_DBT_USERMEM</code>.
|
|||
|
|
</p></li></ul></div>
|
|||
|
|
|
|||
|
|
<span>
|
|||
|
|
<p>
|
|||
|
|
If <code class="literal">DB_DBT_MALLOC</code> or
|
|||
|
|
<code class="literal">DB_DBT_REALLOC</code> is specified, Berkeley DB
|
|||
|
|
allocates a properly sized byte array to contain the data. This
|
|||
|
|
can be convenient if you know little about the nature of the
|
|||
|
|
data, specifically the size of data in the database. However, if
|
|||
|
|
your application makes repeated calls to retrieve keys or data,
|
|||
|
|
you may notice increased garbage collection due to this
|
|||
|
|
allocation. If you know the maximum size of data you are
|
|||
|
|
retrieving, you might decrease the memory burden and speed your
|
|||
|
|
application by allocating your own byte array and using
|
|||
|
|
<code class="literal">DB_DBT_USERMEM</code>. Even if you don't know the
|
|||
|
|
maximum size, you can use this option and reallocate your array
|
|||
|
|
whenever your retrieval API call returns an
|
|||
|
|
<code class="literal">DB_BUFFER_SMALL</code> error or throws an exception
|
|||
|
|
encapsulating an <code class="literal">DB_BUFFER_SMALL</code>.
|
|||
|
|
</p>
|
|||
|
|
</span>
|
|||
|
|
<div class="itemizedlist"><ul type="circle"><li><p><a id="dbt_DB_DBT_PARTIAL"></a>
|
|||
|
|
<code class="literal">DB_DBT_PARTIAL</code>
|
|||
|
|
</p><p>
|
|||
|
|
Do partial retrieval or storage of an item. If the
|
|||
|
|
calling application is doing a get, the
|
|||
|
|
<span class="bold"><strong>dlen</strong></span> bytes
|
|||
|
|
starting
|
|||
|
|
<span class="bold"><strong>doff</strong></span>
|
|||
|
|
bytes from the beginning of the retrieved
|
|||
|
|
data record are returned as if they comprised the entire
|
|||
|
|
record. If any or all of the specified bytes do not
|
|||
|
|
exist in the record, the get is successful, and any
|
|||
|
|
existing bytes are returned.
|
|||
|
|
</p><p>
|
|||
|
|
For example, if the data portion of a retrieved record
|
|||
|
|
was 100 bytes, and a partial retrieval was done using a
|
|||
|
|
DBT having a
|
|||
|
|
<span class="bold"><strong>dlen</strong></span>
|
|||
|
|
field of 20 and a
|
|||
|
|
<span class="bold"><strong>doff</strong></span>
|
|||
|
|
field of 85,
|
|||
|
|
the get call would succeed, the
|
|||
|
|
<span class="bold"><strong>data</strong></span>
|
|||
|
|
field would refer
|
|||
|
|
to the last 15 bytes of the record, and the
|
|||
|
|
<span class="bold"><strong>size</strong></span>
|
|||
|
|
field would be set to 15.
|
|||
|
|
</p><p>
|
|||
|
|
If the calling application is doing a put, 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
|
|||
|
|
<span class="bold"><strong>data</strong></span>
|
|||
|
|
and
|
|||
|
|
<span class="bold"><strong>size</strong></span>
|
|||
|
|
structure elements. If
|
|||
|
|
<span class="bold"><strong>dlen</strong></span>
|
|||
|
|
is smaller than
|
|||
|
|
<span class="bold"><strong>size</strong></span>
|
|||
|
|
the record will grow; if
|
|||
|
|
<span class="bold"><strong>dlen</strong></span>
|
|||
|
|
is larger than
|
|||
|
|
<span class="bold"><strong>size</strong></span>
|
|||
|
|
the record will shrink. If the
|
|||
|
|
specified bytes do not exist, the record will be
|
|||
|
|
extended using nul bytes as necessary, and the put call
|
|||
|
|
will succeed.
|
|||
|
|
</p><p>
|
|||
|
|
It is an error to attempt a partial put using the
|
|||
|
|
<a class="xref" href="dbput.html" title="Db::put()">Db::put()</a>
|
|||
|
|
method in a database that supports duplicate
|
|||
|
|
records. Partial puts in databases supporting duplicate
|
|||
|
|
records must be done using a
|
|||
|
|
<a class="xref" href="dbcput.html" title="Dbc::put()">Dbc::put()</a>
|
|||
|
|
method.
|
|||
|
|
</p><p>
|
|||
|
|
It is an error to attempt a partial put with differing
|
|||
|
|
<span class="bold"><strong>dlen</strong></span>
|
|||
|
|
and
|
|||
|
|
<span class="bold"><strong>size</strong></span>
|
|||
|
|
values in Queue or Recno databases with
|
|||
|
|
fixed-length records.
|
|||
|
|
</p><p>
|
|||
|
|
For example, if the data portion of a retrieved record
|
|||
|
|
was 100 bytes, and a partial put was done using a DBT
|
|||
|
|
having a
|
|||
|
|
<span class="bold"><strong>dlen</strong></span>
|
|||
|
|
field of 20, a
|
|||
|
|
<span class="bold"><strong>doff</strong></span>
|
|||
|
|
field of 85, and a
|
|||
|
|
<span class="bold"><strong>size</strong></span>
|
|||
|
|
field of 30, the resulting record would be 115
|
|||
|
|
bytes in length, where the last 30 bytes would be those
|
|||
|
|
specified by the put call.
|
|||
|
|
</p><p>
|
|||
|
|
This flag is ignored when used with the
|
|||
|
|
<code class="literal">pkey</code> parameter on
|
|||
|
|
<a class="link" href="dbget.html" title="Db::get()">DB->pget()</a> or
|
|||
|
|
<a class="link" href="dbcget.html" title="Dbc::get()">DBcursor->pget()</a>.
|
|||
|
|
</p></li><li><p><a id="dbt_DB_DBT_APPMALLOC"></a>
|
|||
|
|
<code class="literal">DB_DBT_APPMALLOC</code>
|
|||
|
|
</p><p>
|
|||
|
|
After an application-supplied callback routine passed to
|
|||
|
|
either
|
|||
|
|
<a class="xref" href="dbassociate.html" title="Db::associate()">Db::associate()</a>
|
|||
|
|
or
|
|||
|
|
<a class="xref" href="dbset_append_recno.html" title="Db::set_append_recno()">Db::set_append_recno()</a>
|
|||
|
|
is executed, the
|
|||
|
|
<span class="bold"><strong>data</strong></span>
|
|||
|
|
field of a DBT may refer to memory allocated with
|
|||
|
|
<span class="bold"><strong>malloc</strong></span>(3)
|
|||
|
|
or
|
|||
|
|
<span class="bold"><strong>realloc</strong></span>(3).
|
|||
|
|
In that case,
|
|||
|
|
the callback sets the
|
|||
|
|
<code class="literal">DB_DBT_APPMALLOC</code>
|
|||
|
|
flag in the DBT
|
|||
|
|
so that Berkeley DB will call
|
|||
|
|
<span class="bold"><strong>free</strong></span>(3)
|
|||
|
|
to deallocate the
|
|||
|
|
memory when it is no longer required.
|
|||
|
|
</p></li><li><p><a id="dbt_DB_DBT_MULTIPLE"></a>
|
|||
|
|
<code class="literal">DB_DBT_MULTIPLE</code>
|
|||
|
|
</p><p>
|
|||
|
|
Set in a secondary key creation callback routine passed
|
|||
|
|
to
|
|||
|
|
<a class="xref" href="dbassociate.html" title="Db::associate()">Db::associate()</a>
|
|||
|
|
to indicate that multiple secondary
|
|||
|
|
keys should be associated with the given primary
|
|||
|
|
key/data pair. If set, the
|
|||
|
|
<span class="bold"><strong>size</strong></span>
|
|||
|
|
field indicates the
|
|||
|
|
number of secondary keys and the
|
|||
|
|
<span class="bold"><strong>data</strong></span>
|
|||
|
|
field refers to an
|
|||
|
|
array of that number of DBT structures.
|
|||
|
|
</p><p>
|
|||
|
|
The <code class="literal">DB_DBT_APPMALLOC</code> flag may be set on any of the DBT
|
|||
|
|
structures to indicate that their
|
|||
|
|
<span class="bold"><strong>data</strong></span>
|
|||
|
|
field needs to be
|
|||
|
|
freed.
|
|||
|
|
</p></li><li><p><a id="dbt_DB_DBT_READONLY"></a>
|
|||
|
|
<code class="literal">DB_DBT_READONLY</code>
|
|||
|
|
</p><p>
|
|||
|
|
When this flag is set Berkeley DB will not write
|
|||
|
|
into the DBT. This may be set on key values in
|
|||
|
|
cases where the key is a static string that cannot
|
|||
|
|
be written and Berkeley DB might try to update it
|
|||
|
|
because the application has set a user defined
|
|||
|
|
comparison function.
|
|||
|
|
</p></li></ul></div>
|
|||
|
|
</span>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="sect1" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h2 class="title" style="clear: both"><a id="dbtlist"></a>DBT and Bulk Operations</h2>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="navtable">
|
|||
|
|
<table border="1" width="80%">
|
|||
|
|
<thead>
|
|||
|
|
<tr>
|
|||
|
|
<th>DBT and Bulk Operations</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<a class="xref" href="dbmultipleiterator.html" title="DbMultipleIterator">DbMultipleIterator</a>
|
|||
|
|
</td>
|
|||
|
|
<td>Base class for bulk get retrieval</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<a class="xref" href="dbmultipledataiterator.html" title="DbMultipleDataIterator">DbMultipleDataIterator</a>
|
|||
|
|
</td>
|
|||
|
|
<td>Bulk retrieval iterator for data items</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<a class="xref" href="dbmultiplekeydataiterator.html" title="DbMultipleKeyDataIterator">DbMultipleKeyDataIterator</a>
|
|||
|
|
</td>
|
|||
|
|
<td>Bulk retrieval iterator for key/data pairs</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<a class="xref" href="dbmultiplerecnodataiterator.html" title="DbMultipleRecnoDataIterator">DbMultipleRecnoDataIterator</a>
|
|||
|
|
</td>
|
|||
|
|
<td>Bulk retrieval iterator for record number / data item pairs</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<a class="xref" href="dbmultiplebuilder.html" title="DbMultipleBuilder">DbMultipleBuilder</a>
|
|||
|
|
</td>
|
|||
|
|
<td>Base class for bulk buffer building</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<a class="xref" href="dbmultipledatabuilder.html" title="DbMultipleDataBuilder">DbMultipleDataBuilder</a>
|
|||
|
|
</td>
|
|||
|
|
<td>Bulk buffer builder for data items</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<a class="xref" href="dbmultiplekeydatabuilder.html" title="DbMultipleKeyDataBuilder">DbMultipleKeyDataBuilder</a>
|
|||
|
|
</td>
|
|||
|
|
<td>Bulk buffer builder for key/data pairs</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<a class="xref" href="dbmultiplerecnodatabuilder.html" title="DbMultipleRecnoDataBuilder">DbMultipleRecnoDataBuilder</a>
|
|||
|
|
</td>
|
|||
|
|
<td>Bulk buffer builder for record number / data pairs</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="navfooter">
|
|||
|
|
<hr />
|
|||
|
|
<table width="100%" summary="Navigation footer">
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left"><a accesskey="p" href="dbcset_priority.html">Prev</a> </td>
|
|||
|
|
<td width="20%" align="center"> </td>
|
|||
|
|
<td width="40%" align="right"> <a accesskey="n" href="dbmultipleiterator.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left" valign="top">Dbc::set_priority() </td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="h" href="index.html">Home</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right" valign="top"> DbMultipleIterator</td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|