Dbt
import com.sleepycat.db.*;
public Dbt();
public Dbt(byte[] data);
public Dbt(byte[] data, int off, int len);
public void set_data(byte[] data);
public byte[] get_data();
public void set_offset(int off);
public int get_offset();
public int get_size();
public void set_size(int size);
public int get_ulen();
public void set_ulen(int ulen);
public int get_dlen();
public void set_dlen(int dlen);
public int get_doff();
public void set_doff(int doff);
public int get_flags();
public void set_flags(int flags);
public void set_recno_key_data(int recno);
public int get_recno_key_data();
DESCRIPTION
The DB library is a family of classes that provides a
modular programming interface to transactions and record-
oriented file access. The library includes support for
transactions, locking, logging and file page caching, as
well as various indexed access methods. Many of the
classes (e.g., the file page caching class) are useful
independent of the other DB classes, although some classes
are explicitly based on other classes (e.g., transactions
and logging). For a general description of the DB
package, see db_intro(3). This manual page describes the
specific details of the Dbt class, used to encode keys and
data items in a database.
KEY/DATA PAIRS
Storage and retrieval for the Db access methods are based
on key/data pairs. Both key and data items are
represented by Dbt objects.
Key and data byte strings may reference strings of
essentially unlimited length, although any two keys must
fit into available memory at the same time so that they
may be compared, and any one data item must fit into
available memory so that it may be returned.
The Dbt class provides simple access to an underlying data
structure, whose elements can be examined or changed using
the set_ or get_ methods. The remainder of the manual
page sometimes refers to these accesses using the
underlying name, e.g., simply ulen instead of get_ulen and
set_ulen. 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 specified data and size elements. In the
case where the flags structure element is 0, when being
provided a key or data item by the application, the DB
package expects the data object to be set to a byte array
of size bytes. When returning a key/data item to the
application, the DB package will store into the data
object a a byte array of size bytes.
The access methods provide no guarantees about byte string
alignment, and applications are responsible for
maintaining any necessary alignment. Use the
DB_DBT_USERMEM flag to cause returned items to be placed
in memory of arbitrary alignment.
The elements of the structure underlying the Dbt class are
defined as follows:
byte[] data;
A byte array containing the data. This element is
accessed using get_data and set_data, 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.
int offset;
The number of bytes offset into the data array to
determine the portion of the array actually used.
This element is accessed using get_offset and
set_offset.
int size;
The length of data, in bytes. This element is
accessed using get_size and set_size, and may be
initialized implicitly to the length of the data
array with the constructor having one argument.
int ulen;
The size of the user's buffer (referenced by data),
in bytes. This location is not written by the Db
functions. See the DB_DBT_USERMEM flag for more
information. This element is accessed using get_ulen
and set_ulen.
int dlen;
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 get_dlen and set_dlen.
int doff;
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 get_doff and set_doff.
int flags;
This element is accessed using get_flags and
set_flags. The flags value is specified by or'ing
together one or more of the following values:
Db.DB_DBT_MALLOC
Ignored except when retrieving information from
a database, e.g., a Db.get or Dbc.get call.
This flag causes Db to allocate memory for the
returned key or data item and return a byte
array containing the data in the data field of
the key or data Dbt object. It is an error to
specify both DB_DBT_MALLOC and DB_DBT_USERMEM.
Db.DB_DBT_USERMEM
Ignored except when retrieving information from
a database, e.g., a Db.get or Dbc.get call. The
data field of the key or data object must
reference memory that is at least ulen 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
data field. Otherwise, an error is returned,
the size field is set to the length needed for
the requested item, and the errno variable is
set to ENOMEM. It is an error to specify both
DB_DBT_MALLOC and DB_DBT_USERMEM.
Db.DB_DBT_PARTIAL
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 dlen bytes
starting doff 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.
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.
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.
It is an error to attempt a partial put using
the Db.put method in a database that supports
duplicate records. Partial puts in databases
supporting duplicate records must be done using
a Db.cursor method. It is an error to attempt a
partial put with differing dlen and size values
in a recno database with fixed-length records.
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.
The default algorithm of associating returned key or data
items with the Db handle returned by Db.open(3) will
obviously not work when Db handles are being used
concurrently by multiple threads within a process, i.e,
when DB_THREAD was specified to Db.open(3). When multiple
threads are using the returned Db handle concurrently,
either the DB_DBT_MALLOC or DB_DBT_USERMEM flags must be
specified for any Dbt used for key or data retrieval.
For this reason, when using the JAVA DB API, either the
DB_DBT_MALLOC or DB_DBT_USERMEM flags must be specified
for any Dbt used for key or data retrieval. If
DB_DBT_USERMEM is specified, the data field of the Dbt
must be set to an appropriately sized byte array.
If DB_DBT_MALLOC is specified, 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.
LOGICAL RECORD NUMBERS
In all cases for the recno access method, and when calling
the Db.get and Dbc.get functions with the DB_GET_RECNO
flag specified, the data field of the key must be a four
byte array, large enough to store an int. The
set_recno_key_data 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 size field
of the key should be the size of that type, e.g., 4.
Logical record numbers are 1-based, not 0-based, i.e., the
first record in the database is record number 1.
BUGS
The Db access methods provide no guarantees about byte
string alignment, and applications are responsible for
maintaining any necessary alignment.
The name Dbt is a mnemonic for ``data base thang'', and
was used because noone could think of a reasonable name
that wasn't already in use somewhere else.
SEE ALSO
db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
db_load(1), db_recover(1), db_stat(1), db_intro(3),
db_internal(3), db_thread(3), Db(3), Dbc(3), DbEnv(3),
DbException(3), DbInfo(3), DbLock(3), DbLockTab(3), DbLog(3),
DbLsn(3), DbMpool(3), Dbt(3), DbTxn(3), DbTxnMgr(3)
Man(1) output converted with
man2html