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
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<! "@(#)class.so 10.12 (Sleepycat) 11/21/98">
<!Copyright 1997, 1998 by Sleepycat Software, Inc. All rights reserved.>
<html>
<body bgcolor=white>
<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,btr
ee,hash,hashing,transaction,transactions,locking,logging,access method,access me
thods,java,C,C++">
</head>
<h1>Dbt</h1>
<hr size=1 noshade>
<tt>
<h3>
<pre>
import com.sleepycat.db.*;
<p>
public Dbt(byte data);
public Dbt(byte data, int off, int len);
<p>
public void set_data(byte data);
public byte get_data();
<p>
public void set_offset(int off);
public int get_offset();
<p>
public int get_size();
public void set_size(int size);
<p>
public int get_ulen();
public void set_ulen(int ulen);
<p>
public int get_dlen();
public void set_dlen(int dlen);
<p>
public int get_doff();
public void set_doff(int doff);
<p>
public int get_flags();
public void set_flags(int flags);
<p>
public void set_recno_key_data(int recno);
public int get_recno_key_data();
</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.
<p>
<h1>Key/Data Pairs</h1>
<p>
Storage and retrieval for the <a href="../../api_java/Db/class.html">Db</a> access methods are based on
key/data pairs.
Both key and data items are represented by Dbt objects.
<p>
Key and data byte strings may reference strings of essentially unlimited
length. See <a href="../../ref/program/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, e.g., simply <b>ulen</b>
instead of <a href="../../api_java/Dbt/class.html">Dbt.get_ulen</a> and <a href="../../api_java/Dbt/class.html">Dbt.set_ulen</a>.
<p>
The constructors set all elements of the underlying structure to zero.
The constructor with one argument has the effect of setting all elements
to zero except for the specified <b>data</b> and <b>size</b> elements.
The constructor with three arguments has has the additional effect of
only using the portion of the array specified by the size and offset.
In the case where the <b>flags</b> structure element is 0, when being
provided a key or data item by the application, the Berkeley DB package expects
the <b>data</b> object to be set to a byte array of <b>size</b> bytes.
When returning a key/data item to the application, the Berkeley DB package will
store into the <b>data</b> object a byte array of <b>size</b> bytes.
During a get operation, either the DB_DBT_MALLOC or DB_DBT_USERMEM flag
must be specified.
<p>
The elements of the structure underlying the Dbt class are defined as follows:
<dl compact>
<a name="data">
<p><dt>byte[] data;<dd>
A byte array containing the data.
This element is accessed using <a href="../../api_java/Dbt/class.html">Dbt.get_data</a> and
<a href="../../api_java/Dbt/class.html">Dbt.set_data</a>, and may be initialized using one
of the constructors.
Note that the array data is not copied immediately, but only when the
Dbt is used.
<p><dt>int offset;<dd>
The number of bytes offset into the <b>data</b> array to determine the
portion of the array actually used.
This element is accessed using dbt_get_offset and
dbt_set_offset.
<p><dt>int size;<dd>
The length of <b>data</b>, in bytes.
This element is accessed using <a href="../../api_java/Dbt/class.html">Dbt.get_size</a> and
<a href="../../api_java/Dbt/class.html">Dbt.set_size</a>, and may be initialized
implicitly to the length of the data array with the constructor having
one argument.
<p><dt>int ulen;<dd>
The size of the user's buffer (referenced by <b>data</b>), in bytes.
This location is not written by the <a href="../../api_java/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
<a href="../../api_java/Dbt/class.html">Dbt.get_ulen</a> and <a href="../../api_java/Dbt/class.html">Dbt.set_ulen</a>.
<p><dt>int 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
<a href="../../api_java/Dbt/class.html">Dbt.get_dlen</a>, and <a href="../../api_java/Dbt/class.html">Dbt.set_dlen</a>.
<p><dt>int 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
<a href="../../api_java/Dbt/class.html">Dbt.get_doff</a> and <a href="../../api_java/Dbt/class.html">Dbt.set_doff</a>.
<p><dt>int flags;<dd>
This element is accessed using <a href="../../api_java/Dbt/class.html">Dbt.get_flags</a> and
<a href="../../api_java/Dbt/class.html">Dbt.set_flags</a>.
The flags value is specified by logically <b>OR</b>'ing together one or more of the
following values:
<dl compact>
<a name="DB_DBT_MALLOC">
<p><dt>Db.DB_DBT_MALLOC<dd>
Ignored except when retrieving information from a database, e.g., a
<a href="../../api_java/Db/get.html">Db.get</a> or <a href="../../api_java/Dbc/get.html">Dbc.get</a> call.
This flag causes <a href="../../api_java/Db/class.html">Db</a> to allocate memory for the returned key or
data item
and return a byte array containing the data in the <b>data</b> field of
the key or data Dbt object.
<p>
If DB_DBT_MALLOC 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
a throws a <a href="../../api_java/DbException/class.html">DbException</a>.
<p>
It is an error to specify both DB_DBT_MALLOC and DB_DBT_USERMEM.
<a name="DB_DBT_USERMEM">
<p><dt>Db.DB_DBT_USERMEM<dd>
Ignored except when retrieving information from a database, e.g., a
<a href="../../api_java/Db/get.html">Db.get</a> or <a href="../../api_java/Dbc/get.html">Dbc.get</a> call.
The <b>data</b> field of the key or data object must reference 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 referenced 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>
If DB_DBT_USERMEM is specified, the data field of the Dbt must be
set to an appropriately sized byte array.
<p>
It is an error to specify both DB_DBT_MALLOC and DB_DBT_USERMEM.
<a name="DB_DBT_PARTIAL">
<p><dt>Db.DB_DBT_PARTIAL<dd>
Ignored except when specified for a data parameter, where this flag causes
the 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 the existing bytes or 0 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 dlen
field of 20 and a doff field of 85, the get call would succeed,
the data field would reference the last 15 bytes of the record,
and the size field would be set to 15.
<p>
If the calling application is doing a put, the dlen bytes starting
doff bytes from the beginning of the specified key's data record
are replaced by the data specified by the data and size
objects.
If dlen is smaller than size, the record will grow, and if
dlen is larger than size, 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_java/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_java/Dbc/class.html">Dbc</a> method.
It is an error to attempt a partial put with differing dlen and
size values in a recno database 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 dlen
field of 20, a doff field of 85, and a size 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>
Although Java normally maintains proper alignment of byte arrays, the
set_offset method can be used to specify unaligned addresses. Unaligned
address accesses that are not supported by the underlying hardware may be
reported as an exception, or may stop the running Java program.
<h1>Logical Record Numbers</h1>
In all cases for the recno access method, and when calling the
<a href="../../api_java/Db/get.html">Db.get</a> and <a href="../../api_java/Dbc/get.html">Dbc.get</a> functions with the
DB_SET_RECNO flag specified, the <b>data</b>
field of the key must be a four byte array, large enough to store an int.
The <a href="../../api_java/Dbt/class.html">Dbt.set_recno_key_data</a> method can be used to set the value
of the array.
An int is a 32-bit type,
(which limits the number of
logical records in a recno database, and the maximum logical record
which may be directly retrieved from a btree database, to 4,294,967,296).
The <b>size</b> field of the key should be the size of that type, i.e.,
4.
<p>
Logical record numbers are 1-based, not 0-based, i.e., the first record
in the database is record number 1.
</tt>
</body>
</html>
|
