-IBerkeley DB: Dbt[P

Dbt





import com.sleepycat.db.*;

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



AThis manual page describes the specific details of the Dbt class,1used to encode keys and data items in a database.



Key/Data Pairs



gStorage and retrieval for the Db access methods are based onkey/data pairs.7Both key and data items are represented by Dbt objects.

HKey and data byte strings may reference strings of essentially unlimitedIlength. See Database limitsfor more information.

EThe Dbt class provides simple access to an underlying data structure,Bwhose elements can be examined or changed using the set_ orGget_ methods. The remainder of the manual page sometimes refersEto these accesses using the underlying name, e.g., simply uleninstead of Dbt.get_ulen and Dbt.set_ulen.

FThe constructors set all elements of the underlying structure to zero.HThe constructor with one argument has the effect of setting all elementsFto zero except for the specified data and size elements.EThe constructor with three arguments has has the additional effect ofEonly using the portion of the array specified by the size and offset.EIn the case where the flags structure element is 0, when beingOprovided a key or data item by the application, the Berkeley DB package expectsFthe data object to be set to a byte array of size bytes.OWhen returning a key/data item to the application, the Berkeley DB package willDstore into the data object a byte array of size bytes.GDuring a get operation, either the DB_DBT_MALLOC or DB_DBT_USERMEM flagmust be specified.

NThe 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 andZDbt.set_data, and may be initialized using oneof the constructors.ENote that the array data is not copied immediately, but only when the Dbt is used.

int offset;
FThe number of bytes offset into the data array to determine the#portion of the array actually used.1This element is accessed using dbt_get_offset anddbt_set_offset.

int size;
$The length of data, in bytes.[This element is accessed using Dbt.get_size andPDbt.set_size, and may be initializedFimplicitly to the length of the data array with the constructor having one argument.

int ulen;
DThe size of the user's buffer (referenced by data), in bytes.ZThis location is not written by the Db methods.

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

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

int dlen;
JThe length of the partial record being read or written by the application, in bytes.1See the DB_DBT_PARTIAL flag for more information.This element is accessed usingwDbt.get_dlen, and Dbt.set_dlen.

int doff;
JThe offset of the partial record being read or written by the application, in bytes.1See the DB_DBT_PARTIAL flag for more information.This element is accessed usingvDbt.get_doff and Dbt.set_doff.

int flags;
\This element is accessed using Dbt.get_flags and:Dbt.set_flags.SThe flags value is specified by logically OR'ing together one or more of thefollowing values:


Db.DB_DBT_MALLOC
CIgnored except when retrieving information from a database, e.g., ajDb.get or Dbc.get call.iThis flag causes Db to allocate memory for the returned key or data itemGand return a byte array containing the data in the data field ofthe key or data Dbt object.

JIf DB_DBT_MALLOC is specified, Berkeley DB allocates a properly sized byteEarray to contain the data. This can be convenient if you know littleBabout the nature of the data, specifically the size of data in the?database. However, if your application makes repeated calls toFretrieve keys or data, you may notice increased garbage collection dueAto this allocation. If you know the maximum size of data you are?retrieving, you might decrease the memory burden and speed yourGapplication by allocating your own byte array and using DB_DBT_USERMEM.@Even if you don't know the maximum size, you can use this optionBand reallocate your array whenever your retrieval API call returnsKa throws a DbException.

@It is an error to specify both DB_DBT_MALLOC and DB_DBT_USERMEM.

Db.DB_DBT_USERMEM
CIgnored except when retrieving information from a database, e.g., ajDb.get or Dbc.get call.EThe data field of the key or data object must reference memory-that is at least ulen bytes in length.HIf the length of the requested item is less than or equal to that numberJof bytes, the item is copied into the memory referenced by the datafield.DOtherwise, the size field is set to the length needed for the1requested item, and the error ENOMEM is returned.

AIf 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 both DB_DBT_MALLOC and DB_DBT_USERMEM.

Db.DB_DBT_PARTIAL
JIgnored except when specified for a data parameter, where this flag causes,the partial retrieval or storage of an item.IIf the calling application is doing a get, the dlen bytes startingEdoff bytes from the beginning of the retrieved data record are0returned as if they comprised the entire record.@If any or all of the specified bytes do not exist in the record,Ethe get is successful and the existing bytes or 0 bytes are returned.

EFor 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,c&and the size field would be set to 15.

tBIf the calling application is doing a put, the dlen bytes starting@doff bytes from the beginning of the specified key's data record7are replaced by the data specified by the data and size objects.:If dlen is smaller than size, the record will grow, and if1dlen is larger than size, the record will shrink.JIf the specified bytes do not exist, the record will be extended using nul2bytes as necessary, and the put call will succeed.

aIt is an error to attempt a partial put using the Db.putl5method in a database that supports duplicate records.(CPartial puts in databases supporting duplicate records must be doneu?using a Dbc method.l?It is an error to attempt a partial put with differing dlen andl:size values in a recno database with fixed-length records.

aEFor example, if the data portion of a retrieved record was 100 bytes,e4and a partial put was done using a Dbt having a dlen8field of 20, a doff field of 85, and a size field of 30,Dthe resulting record would be 115 bytes in length, where the last 30/bytes would be those specified by the put call.v

a
"

aEAlthough Java normally maintains proper alignment of byte arrays, themHset_offset method can be used to specify unaligned addresses. UnalignedIaddress accesses that are not supported by the underlying hardware may ber?reported as an exception, or may stop the running Java program.

Logical Record Numbers

l>In all cases for the recno access method, and when calling thexDb.get and Dbc.get functions with the,DB_SET_RECNO flag specified, the dataIfield of the key must be a four byte array, large enough to store an int."jThe Dbt.set_recno_key_data method can be used to set the value of the array.fAn int is a 32-bit type,(which limits the number ofhClogical records in a recno database, and the maximum logical recordfIwhich may be directly retrieved from a btree database, to 4,294,967,296).hGThe size field of the key should be the size of that type, i.e.,n4.

rGLogical record numbers are 1-based, not 0-based, i.e., the first record>#in the database is record number 1.d  the application, the Berkeley DB package expectsFthe data object to be set to a byte array of size bytes.OWhen returning a key/data item to the application, the Berkeley DB package willDstore into the data object a byte array of size bytes.GDuring a get operation, either the DB_DBT_MALLOC or DB_DBT_USERMEM flagmust be specified.

NThe elements of the structure underlying the Dbt class a