<?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 class="navheader">
<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></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></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>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
main-release
>
by-pkgid
>
a00abf5f94bf470fd4cc9e10b2d135e0
>
files
>
514
