153 lines
9.2 KiB
HTML
153 lines
9.2 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: Key/Data Pairs</b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_c/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>
|
|
<a name="2"><!--meow--></a>
|
|
<p>Storage and retrieval for the Berkeley DB access methods are based on key/data
|
|
pairs. Both key and data items are represented by the DBT data
|
|
structure. (The name <i>DBT</i> is a mnemonic for <i>data
|
|
base thang</i>, and was used because no one could think of a reasonable
|
|
name that wasn't already in use somewhere else.) 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>
|
|
<blockquote><pre>typedef struct {
|
|
void *data;
|
|
u_int32_t size;
|
|
u_int32_t ulen;
|
|
u_int32_t dlen;
|
|
u_int32_t doff;
|
|
u_int32_t flags;
|
|
} DBT;</pre></blockquote>
|
|
<p>In order to ensure compatibility with future releases of Berkeley DB, all
|
|
fields of the DBT structure that are not explicitly set should be
|
|
initialized to nul bytes before the first time the structure is used.
|
|
Do this by declaring the structure external or static, or by calling
|
|
the C library routine <b>bzero</b>(3) or <b>memset</b>(3).</p>
|
|
<p>By default, the <b>flags</b> structure element is expected to be set
|
|
to 0. In this default case, when the application is providing Berkeley DB a
|
|
key or data item to store into the database, Berkeley DB expects the
|
|
<b>data</b> structure element 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> structure element 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>The elements of the DBT structure are defined as follows:</p>
|
|
<br>
|
|
<b>void *<a name="data">data</a>;</b><ul compact><li>A pointer to a byte string.</ul>
|
|
<b>u_int32_t <a name="size">size</a>;</b><ul compact><li>The length of <b>data</b>, in bytes.</ul>
|
|
<b>u_int32_t <a name="ulen">ulen</a>;</b><ul compact><li>The size of the user's buffer (to which <b>data</b> refers), in bytes.
|
|
This location is not written by the Berkeley DB functions.
|
|
<p>Note that applications can determine the length of a record by setting
|
|
the <b>ulen</b> field to 0 and checking the return value in the
|
|
<b>size</b> field. See the DB_DBT_USERMEM flag for more information.</p></ul>
|
|
<b>u_int32_t <a name="dlen">dlen</a>;</b><ul compact><li>The length of the partial record being read or written by the application,
|
|
in bytes. See the DB_DBT_PARTIAL flag for more information.</ul>
|
|
<b>u_int32_t <a name="doff">doff</a>;</b><ul compact><li>The offset of the partial record being read or written by the application,
|
|
in bytes. See the DB_DBT_PARTIAL flag for more information.</ul>
|
|
<b>u_int32_t flags;</b><ul compact><li>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
|
|
function), and return a pointer to it in the <b>data</b> 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
|
|
<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
|
|
function), and return a pointer to it in the <b>data</b> 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
|
|
<b>data</b> field.
|
|
<p>The difference between DB_DBT_MALLOC and DB_DBT_REALLOC
|
|
is that the latter will call <b>realloc</b>(3) instead of
|
|
<b>malloc</b>(3), so the allocated memory will be grown as necessary
|
|
instead of the application doing repeated free/malloc calls.</p>
|
|
<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 structure 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 to which the <b>data</b> field refers.
|
|
Otherwise, the <b>size</b> field is 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>
|
|
<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> structure elements. 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_c/db_put.html">DB->put</a> function
|
|
in a database that supports duplicate records.
|
|
Partial puts in databases supporting duplicate records must be done
|
|
using a <a href="../api_c/dbc_put.html">DBcursor->put</a> function.</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_c/db_associate.html">DB->associate</a> or <a href="../api_c/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 <a href="../api_c/dbt_class.html#DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a> 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_c/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 <a href="../api_c/dbt_class.html#DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a> 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></ul>
|
|
<br>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_c/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>
|