import com.sleepycat.db.*;

public class Dbt extends Object
{
	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

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 zero length up to strings of essentially unlimited length. See Database limits for more information.

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 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.

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 data and size 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 flags structure element is 0, when being provided a key or data item by the application, the Berkeley 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 Berkeley DB package will store into the data object a byte array of size bytes. During a get operation, one of the Db.DB_DBT_MALLOC, Db.DB_DBT_REALLOC or Db.DB_DBT_USERMEM flags must be specified.

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 Dbt.get_data and Dbt.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 Dbt.get_offset and Dbt.set_offset.

int size;

The length of data, in bytes. This element is accessed using Dbt.get_size and Dbt.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 methods.

Note that applications can determine the length of a record by setting the ulen to 0 and checking the return value found in size. See the Db.DB_DBT_USERMEM flag for more information.

This element is accessed using Dbt.get_ulen and Dbt.set_ulen.

int dlen;

The length of the partial record being read or written by the application, in bytes. See the Db.DB_DBT_PARTIAL flag for more information. This element is accessed using Dbt.get_dlen, and Dbt.set_dlen.

int doff;

The offset of the partial record being read or written by the application, in bytes. See the Db.DB_DBT_PARTIAL flag for more information. This element is accessed using Dbt.get_doff and Dbt.set_doff.

int flags;

This element is accessed using Dbt.get_flags and Dbt.set_flags.

The flags value must be set by bitwise inclusively OR'ing together one or more of the following values.

Db.DB_DBT_MALLOC

When this flag is set Berkeley DB will 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.

If Db.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.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 throws a DbMemoryException.

It is an error to specify more than one of Db.DB_DBT_MALLOC, Db.DB_DBT_REALLOC and Db.DB_DBT_USERMEM.

Db.DB_DBT_REALLOC

When this flag is set Berkeley DB will return the data in the data field of the key or data Dbt object, reusing the existing byte array if it is large enough, or allocating a new one of the appropriate size.

It is an error to specify more than one of Db.DB_DBT_MALLOC, Db.DB_DBT_REALLOC and Db.DB_DBT_USERMEM.

Db.DB_DBT_USERMEM

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, the size field is set to the length needed for the requested item, and the error ENOMEM is returned.

If Db.DB_DBT_USERMEM is specified, the data field of the Dbt must be set to an appropriately sized byte array.

It is an error to specify more than one of Db.DB_DBT_MALLOC, Db.DB_DBT_REALLOC and Db.DB_DBT_USERMEM.

If Db.DB_DBT_MALLOC or Db.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.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 throws a DbMemoryException.

Db.DB_DBT_PARTIAL

Do 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 nul 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 Dbc method.

It is an error to attempt a partial put with differing dlen and size values in Queue or Recno databases 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.

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.

Logical Record Numbers

In all cases for the Queue and Recno access methods, and when calling the Db.get and Dbc.get functions with the Db.DB_SET_RECNO flag specified, the data field of the key must be a four byte array, large enough to store an int. The Dbt.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 Queue or 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, i.e., 4.