-IBerkeley DB: Dbt[P

Dbt





#include <db_cxx.h>

void *Dbt::get_data() const;void Dbt::set_data(void *);

u_int32_t Dbt::get_size() const;void Dbt::set_size(u_int32_t);

u_int32_t Dbt::get_ulen() const;void Dbt::set_ulen(u_int32_t);

u_int32_t Dbt::get_dlen() const;void Dbt::set_dlen(u_int32_t);

u_int32_t Dbt::get_doff() const;void Dbt::set_doff(u_int32_t);

!u_int32_t Dbt::get_flags() const;void Dbt::set_flags(u_int32_t);

"Dbt::Dbt(void *data, size_t size); Dbt::Dbt(); Dbt::~Dbt();Dbt::Dbt(const Dbt &);#Dbt::Dbt &operator = (const Dbt &);





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



fStorage 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.IThe constructor with two arguments has the effect of setting all elementsFto zero except for the specified data and size elements.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 point to a byte string of size bytes.OWhen returning a key/data item to the application, the Berkeley DB package will?store into the data object a pointer to a byte string ofsize bytes.

NThe elements of the structure underlying the Dbt class are defined as follows:



void *data;
A pointer to a byte string.[This element is accessed using Dbt::get_data andZDbt::set_data, and may be initialized using oneof the constructors.

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.

u_int32_t size;
$The length of data, in bytes.[This element is accessed using Dbt::get_size andPDbt::set_size, and may be initialized)using the constructor with two arguments.

u_int32_t ulen;
DThe size of the user's buffer (referenced by data), in bytes.YThis 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.

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

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

u_int32_t 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_DBT_MALLOC
CIgnored except when retrieving information from a database, e.g., ajDb::get or Dbc::get call.hThis flag causes Db to allocate memory for the returned key or data item<(using malloc(3) or the user-specified malloc method)>and return a pointer to it in the data field of the keyor data Dbt object.KThe allocated memory becomes the responsibility of the calling application.

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

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.

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

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

BIf 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 sizeobjects.: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::put5method in a database that supports duplicate records.CPartial 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 a recno database with fixed-length records.

EFor example, if the data portion of a retrieved record was 100 bytes,)4and 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.r

t
k

%Retrieved key/data permanence:eMWhen using the non-cursor Berkeley DB calls to retrieve key/data items (e.g.,tfDb::get), the memory referenced by the pointer stored into the>Dbt is only valid until the next call to Berkeley DB using theDb handle returned by Db::open. (This includeshany use of the returned Db handle, including by anotherEthread of control within the process. For this reason, when multiplesAthreads are using the returned DB handle concurrently, either the)IDB_DBT_MALLOC or DB_DBT_USERMEM flag must be specified for any non-cursor_FDbt used for key or data retrieval.) When using the cursor Berkeley DBfcalls to retrieve key/data items (e.g., Dbc::get), the memory>referenced by the pointer into the Dbt is only valid until thednext call to Berkeley DB using the Dbc handle returned by6Db::cursor.

n/OThe Berkeley DB access methods provide no guarantees about key/data byte string Galignment, and applications are responsible for arranging any necessarygHalignment. The DB_DBT_MALLOC and DB_DBT_USERMEM flags may be used to6store returned items in memory of arbitrary alignment.

Logical Record Numbers

r>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 data?field of the key must be a pointer to a memory location of typeaNdb_recno_t, as typedef'd in the #include <db_cxx.h> include file.$This type is a 32-bit unsigned type,(which limits the number ofcClogical records in a recno database, and the maximum logical recordrIwhich may be directly retrieved from a btree database, to 4,294,967,296).sGThe size field of the key should be the size of that type, i.e.,k9in the C programming language, sizeof(db_recno_t). 

tGLogical record numbers are 1-based, not 0-based, i.e., the first record.#in the database is record number 1.hce package will?store into the data object a pointer to a byte string ofsize bytes.

NThe elements of the structure underlying the Dbt class are defined as follows:



void *data;
A pointer to a byte string.[This element is accessed using Dbt::get_data andZDbt::set_data, and may be