1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<!--$Id: dbt_class.html,v 1.1.1.1 2003/11/20 22:14:28 toshok Exp $-->
<!--$Id: dbt_class.html,v 1.1.1.1 2003/11/20 22:14:28 toshok Exp $-->
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
<!--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,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
</head>
<body bgcolor=white>
<a name="2"><!--meow--></a>
<table width="100%"><tr valign=top>
<td>
<h1>Dbt</h1>
</td>
<td align=right>
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
</td></tr></table>
<hr size=1 noshade>
<tt>
<h3><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></h3>
<h1>Description</h1>
<p>This manual page describes the specific details of the Dbt class,
used to encode keys and data items in a database.
<a name="3"><!--meow--></a>
<h3>Key/Data Pairs</h3>
<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>The Dbt class provides simple access to an underlying data
structure, whose elements can be examined or changed using the
<b>set_</b> or <b>get_</b> methods. The remainder of the manual
page sometimes refers to these accesses using the underlying name; for
example, <b>ulen</b> rather than Dbt::get_ulen and
Dbt::set_ulen. Dbt can be subclassed, providing a way
to associate with it additional data or references to other
structures.
<p>The constructors set all elements of the underlying structure to zero.
The constructor with two arguments has the effect of setting all elements
to zero except for the <b>data</b> and <b>size</b> elements.
<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>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>The elements of the structure underlying the Dbt class are defined as follows:
<p><dl compact>
<p><dt>void *<a name="data">data</a>;<dd>A pointer to a byte string.
This element is accessed using Dbt::get_data and
Dbt::set_data, and may be initialized using one
of the constructors.
<p><dt>u_int32_t size;<dd>The length of <b>data</b>, in bytes.
This element is accessed using Dbt::get_size and
Dbt::set_size, and may be initialized
using the constructor with two arguments.
<p><dt>u_int32_t ulen;<dd>The size of the user's buffer (referred to by <b>data</b>), in bytes.
This location is not written by the <a href="../api_cxx/db_class.html">Db</a> methods.
<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>This element is accessed using
Dbt::get_ulen and Dbt::set_ulen.
<p><dt>u_int32_t dlen;<dd>The length of the partial record being read or written by the application,
in bytes.
See the DB_DBT_PARTIAL flag for more information.
This element is accessed using
Dbt::get_dlen, and Dbt::set_dlen.
<p><dt>u_int32_t doff;<dd>The offset of the partial record being read or written by the application,
in bytes.
See the DB_DBT_PARTIAL flag for more information.
This element is accessed using
Dbt::get_doff and Dbt::set_doff.
<p><dt>u_int32_t flags;<dd>This element is accessed using Dbt::get_flags and
Dbt::set_flags.
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
more of the following values:
<p><dl compact>
<p><dt><a name="DB_DBT_MALLOC">DB_DBT_MALLOC</a><dd>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><dt><a name="DB_DBT_REALLOC">DB_DBT_REALLOC</a><dd>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><dt><a name="DB_DBT_USERMEM">DB_DBT_USERMEM</a><dd>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> field is set to the length needed for the
requested item, and the error ENOMEM is returned.
<p>It is an error to specify more than one of DB_DBT_MALLOC,
DB_DBT_REALLOC, and DB_DBT_USERMEM.
</dl>
<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 ENOMEM error or throws an exception encapsulating an ENOMEM.
<p><dl compact>
<p><dt><a name="DB_DBT_PARTIAL">DB_DBT_PARTIAL</a><dd>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>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>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>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>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.
</dl>
</dl>
<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>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>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.
</tt>
<table width="100%"><tr><td><br></td><td align=right>
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
</td></tr></table>
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
</body>
</html>
|
