291 lines
14 KiB
HTML
291 lines
14 KiB
HTML
<!--$Id: dbt_class.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--$Id: dbt_class.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: Dbt</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>Dbt</b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_cxx/api_core.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>
|
|
#include <db_cxx.h>
|
|
<p>
|
|
class Dbt {
|
|
public:
|
|
Dbt(void *data, size_t size);
|
|
Dbt();
|
|
Dbt(const Dbt &);
|
|
Dbt &operator = (const Dbt &);
|
|
~Dbt();
|
|
<p>
|
|
void *get_data() const;
|
|
void set_data(void *);
|
|
<p>
|
|
u_int32_t get_size() const;
|
|
void set_size(u_int32_t);
|
|
<p>
|
|
u_int32_t get_ulen() const;
|
|
void set_ulen(u_int32_t);
|
|
<p>
|
|
u_int32_t get_dlen() const;
|
|
void set_dlen(u_int32_t);
|
|
<p>
|
|
u_int32_t get_doff() const;
|
|
void set_doff(u_int32_t);
|
|
<p>
|
|
u_int32_t get_flags() const;
|
|
void set_flags(u_int32_t);
|
|
<p>
|
|
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></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt</b>
|
|
<p>This information describes the specific details of the Dbt class,
|
|
used to encode keys and data items in a database.</p>
|
|
<a name="2"><!--meow--></a>
|
|
<b>Key/Data Pairs</b>
|
|
<p>Storage and retrieval for the <a href="../api_cxx/db_class.html">Db</a> access methods are based on
|
|
key/data pairs. Both key and data items are represented by Dbt
|
|
objects. Key and data byte strings may refer to strings of zero length
|
|
up to strings of essentially unlimited length. See
|
|
<a href="../ref/am_misc/dbsizes.html">Database limits</a> for more
|
|
information.</p>
|
|
<p>The Dbt class provides simple access to an underlying data
|
|
structure, whose elements can be examined or changed using the usual
|
|
<b>set</b> or <b>get</b> methods. Dbt can be subclassed,
|
|
providing a way to associate with it additional data or references to
|
|
other structures.</p>
|
|
<p>The constructors set all elements of the underlying structure to zero.
|
|
The constructor with two parameters has the effect of setting all elements
|
|
to zero except for the <b>data</b> and <b>size</b> elements.</p>
|
|
<p>In the case in which the <b>flags</b> structure element is set to 0, when
|
|
the application is providing Berkeley DB a key or data item to store into the
|
|
database, Berkeley DB expects the <b>data</b> object to point to a byte
|
|
string of <b>size</b> bytes. When returning a key/data item to the
|
|
application, Berkeley DB will store into the <b>data</b> object a pointer to
|
|
a byte string of <b>size</b> bytes, and the memory to which the pointer
|
|
refers will be allocated and managed by Berkeley DB.</p>
|
|
<p>Access to Dbt objects is not re-entrant. In particular, if
|
|
multiple threads simultaneously access the same Dbt object using
|
|
<a href="../api_cxx/db_class.html">Db</a> API calls, the results are undefined, and may result in a
|
|
crash. One easy way to avoid problems is to use Dbt objects
|
|
that are constructed as stack variables.</p>
|
|
<p>Each Dbt object has an associated DBT struct, which is used by
|
|
the underlying implementation of Berkeley DB and its C-language API. The
|
|
Dbt::get_DBT method returns a pointer to this struct. Given a const
|
|
Dbt object, Dbt::get_const_DBT returns a const pointer to the
|
|
same struct.</p>
|
|
<p>Given a DBT struct, the Dbt::get_Dbt method returns the corresponding
|
|
Dbt object, if there is one. If the DBT object was not
|
|
associated with a Dbt (that is, it was not returned from a call
|
|
to Dbt::get_DBT), then the result of Dbt::get_Dbt is undefined. Given
|
|
a const DBT struct, Dbt::get_const_Dbt returns the associated const
|
|
Dbt 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>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::set_data</b>
|
|
<p>Set the data array.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>data</b><ul compact><li>The <b>data</b> parameter is an array of bytes to be used to set the
|
|
content for the Dbt.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::get_data</b>
|
|
<p>Return the data array.</p>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::set_recno_key_data</b>
|
|
<p>Initialize the data array from a logical record number. Recno database
|
|
records are ordered by integer keys starting at 1. When the
|
|
Dbt::set_recno_key_data method is called, the data, size and offset
|
|
fields in the Dbt are implicitly set to hold a byte array
|
|
representation of the integer key.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>recno</b><ul compact><li>The <b>recno</b> parameter logical record number used to initialize the
|
|
data array.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::get_recno_key_data</b>
|
|
<p>Return an object from the data array, expecting that data to be a
|
|
logical record number.</p>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::set_offset</b>
|
|
<p>Set the byte offset into the data array.</p>
|
|
<p>The number of bytes offset into the <b>data</b> array determine the
|
|
portion of the array actually used. This element is accessed using
|
|
Dbt::get_offset and Dbt::set_offset.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>offset</b><ul compact><li>The <b>offset</b> parameter is the byte offset into the data array.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::get_offset</b>
|
|
<p>Return the byte offset into the data array.</p>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::set_size</b>
|
|
<p>Set the byte size of the data array.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>size</b><ul compact><li>The <b>size</b> parameter is the size of the data array in bytes.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::get_size</b>
|
|
<p>Return the data array size.</p>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::set_ulen</b>
|
|
<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 <b>ulen</b> to 0 and checking the return value found in <b>size</b>.
|
|
See the DB_DBT_USERMEM flag for more information.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>ulen</b><ul compact><li>The <b>ulen</b> parameter the size of the data array in bytes.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::get_ulen</b>
|
|
<p>Return the length in bytes of the user-specified buffer.</p>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::set_dlen</b>
|
|
<p>Set the byte length of the partial record being read or written by the
|
|
application, in bytes. See the DB_DBT_PARTIAL flag for more
|
|
information.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>dlen</b><ul compact><li>The <b>dlen</b> parameter is the length of the partial record in bytes.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::get_dlen</b>
|
|
<p>Return the length of the partial record, in bytes.</p>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::set_doff</b>
|
|
<p>Set the offset of the partial record being read or written by the
|
|
application, in bytes. See the DB_DBT_PARTIAL flag for more
|
|
information.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>doff</b><ul compact><li>The <b>doff</b> parameter is the offset of the partial record.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::get_doff</b>
|
|
<p>Return the offset of the partial record, in bytes.</p>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::set_flags</b>
|
|
<p>Set the object flag value.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter is Dbt flag value.</ul>
|
|
The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one
|
|
or more of the following values:
|
|
<br>
|
|
<b><a name="DB_DBT_MALLOC">DB_DBT_MALLOC</a></b><ul compact><li>When this flag is set, Berkeley DB will allocate memory for the returned key
|
|
or data item (using <b>malloc</b>(3) or the user-specified malloc
|
|
method), and return a pointer to it in the <b>data</b> field of the key
|
|
or data Dbt object. 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
|
|
<b>data</b> field.
|
|
<p>It is an error to specify more than one of DB_DBT_MALLOC,
|
|
DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul>
|
|
<b><a name="DB_DBT_REALLOC">DB_DBT_REALLOC</a></b><ul compact><li>When this flag is set Berkeley DB will allocate memory for the returned key
|
|
or data item (using <b>realloc</b>(3) or the user-specified realloc
|
|
method), and return a pointer to it in the <b>data</b> field of the key
|
|
or data Dbt object. 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
|
|
<b>data</b> field.
|
|
<p>It is an error to specify more than one of DB_DBT_MALLOC,
|
|
DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul>
|
|
<a name="3"><!--meow--></a>
|
|
<b><a name="DB_DBT_USERMEM">DB_DBT_USERMEM</a></b><ul compact><li>The <b>data</b> field of the key or data object must refer to memory
|
|
that is at least <b>ulen</b> 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 referred to by the <b>data</b> field.
|
|
Otherwise, the <b>size</b> fields of both the key and data Dbt
|
|
objects are set to the length needed for the requested item, and the
|
|
error DB_BUFFER_SMALL is returned.
|
|
<p>It is an error to specify more than one of DB_DBT_MALLOC,
|
|
DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul>
|
|
<br>
|
|
<p>If DB_DBT_MALLOC or DB_DBT_REALLOC 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
|
|
DB_DBT_USERMEM. 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 DB_BUFFER_SMALL error or throws an exception
|
|
encapsulating an DB_BUFFER_SMALL.</p>
|
|
<br>
|
|
<b><a name="DB_DBT_PARTIAL">DB_DBT_PARTIAL</a></b><ul compact><li>Do partial retrieval or storage of an item. If the calling application
|
|
is doing a get, the <b>dlen</b> bytes starting <b>doff</b> 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>For example, if the data portion of a retrieved record was 100 bytes,
|
|
and a partial retrieval was done using a Dbt having a <b>dlen</b>
|
|
field of 20 and a <b>doff</b> field of 85, the get call would succeed,
|
|
the <b>data</b> field would refer to the last 15 bytes of the record,
|
|
and the <b>size</b> field would be set to 15.</p>
|
|
<p>If the calling application is doing a put, 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 <b>data</b> and <b>size</b>
|
|
objects.
|
|
If <b>dlen</b> is smaller than <b>size</b>, the record will grow; if
|
|
<b>dlen</b> is larger than <b>size</b>, 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 href="../api_cxx/db_put.html">Db::put</a>
|
|
method in a database that supports duplicate records.
|
|
Partial puts in databases supporting duplicate records must be done
|
|
using a <a href="../api_cxx/dbc_class.html">Dbc</a> method.</p>
|
|
<p>It is an error to attempt a partial put with differing <b>dlen</b> and
|
|
<b>size</b> 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 <b>dlen</b>
|
|
field of 20, a <b>doff</b> field of 85, and a <b>size</b> 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></ul>
|
|
<b><a name="DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a></b><ul compact><li>After an application-supplied callback routine passed to either
|
|
<a href="../api_cxx/db_associate.html">Db::associate</a> or <a href="../api_cxx/db_set_append_recno.html">Db::set_append_recno</a> is executed, the
|
|
<b>data</b> field of a Dbt may refer to memory allocated with
|
|
<b>malloc</b>(3) or <b>realloc</b>(3). In that case, the
|
|
callback sets the DB_DBT_APPMALLOC flag in the Dbt so
|
|
that Berkeley DB will call <b>free</b>(3) to deallocate the memory when it
|
|
is no longer required.</ul>
|
|
<b><a name="DB_DBT_MULTIPLE">DB_DBT_MULTIPLE</a></b><ul compact><li>Set in a secondary key creation callback routine passed to
|
|
<a href="../api_cxx/db_associate.html">Db::associate</a> to indicate that multiple secondary keys should be
|
|
associated with the given primary key/data pair. If set, the
|
|
<b>size</b> field indicates the number of secondary keys and the
|
|
<b>data</b> field refers to an array of that number of Dbt
|
|
structures.
|
|
<p>The DB_DBT_APPMALLOC flag may be set on any of the Dbt
|
|
structures to indicate that their <b>data</b> field needs to be
|
|
freed.</p></ul>
|
|
<br>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Dbt::get_flags</b>
|
|
<p>Return the object flag value.</p>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_cxx/api_core.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>
|