Berkeley DB: Dbt

Dbt

#include <db_cxx.h> class Dbt { public: Dbt(void *data, size_t size); Dbt(); Dbt(const Dbt &); Dbt &operator = (const Dbt &); ~Dbt(); void *get_data() const; void set_data(void *); u_int32_t get_size() const; void set_size(u_int32_t); u_int32_t get_ulen() const; void set_ulen(u_int32_t); u_int32_t get_dlen() const; void set_dlen(u_int32_t); u_int32_t get_doff() const; void set_doff(u_int32_t); u_int32_t get_flags() const; void set_flags(u_int32_t); DBT *Dbt::get_DBT(); const DBT *Dbt::get_const_DBT() const; static Dbt *Dbt::get_Dbt(DBT *dbt); static const Dbt *Dbt::get_const_Dbt(const DBT *dbt); }; Description: Dbt This information 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 refer to 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 usual set or get methods. 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 two parameters has the effect of setting all elements to zero except for the data and size elements. In the case in which the flags structure element is set to 0, when the application is providing Berkeley DB a key or data item to store into the database, Berkeley DB expects the data object to point to a byte string of size bytes. When returning a key/data item to the application, Berkeley DB will store into the data object a pointer to a byte string of size bytes, and the memory to which the pointer refers will be allocated and managed by Berkeley DB. Access to Dbt objects is not re-entrant. In particular, if multiple threads simultaneously access the same Dbt object using Db API calls, the results are undefined, and may result in a crash. One easy way to avoid problems is to use Dbt objects that are constructed as stack variables. Each Dbt object has an associated DBT struct, which is used by the underlying implementation of Berkeley DB and its C-language API. The Dbt::get_DBT method returns a pointer to this struct. Given a const Dbt object, Dbt::get_const_DBT returns a const pointer to the same struct. Given a DBT struct, the Dbt::get_Dbt method returns the corresponding Dbt object, if there is one. If the DBT object was not associated with a Dbt (that is, it was not returned from a call to Dbt::get_DBT), then the result of Dbt::get_Dbt is undefined. Given a const DBT struct, Dbt::get_const_Dbt returns the associated const Dbt object, if there is one. These methods may be useful for Berkeley DB applications including both C and C++ language software. It should not be necessary to use these calls in a purely C++ application. Description: Dbt::set_data Set the data array. Parameters data The data parameter is an array of bytes to be used to set the content for the Dbt. Description: Dbt::get_data Return the data array. Description: Dbt::set_recno_key_data Initialize the data array from a logical record number. Recno database records are ordered by integer keys starting at 1. When the Dbt::set_recno_key_data method is called, the data, size and offset fields in the Dbt are implicitly set to hold a byte array representation of the integer key. Parameters recno The recno parameter logical record number used to initialize the data array. Description: Dbt::get_recno_key_data Return an object from the data array, expecting that data to be a logical record number. Description: Dbt::set_offset Set the byte offset into the data array. The number of bytes offset into the data array determine the portion of the array actually used. This element is accessed using Dbt::get_offset and Dbt::set_offset. Parameters offset The offset parameter is the byte offset into the data array. Description: Dbt::get_offset Return the byte offset into the data array. Description: Dbt::set_size Set the byte size of the data array. Parameters size The size parameter is the size of the data array in bytes. Description: Dbt::get_size Return the data array size. Description: Dbt::set_ulen Set the byte size of the user-specified buffer. 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_DBT_USERMEM flag for more information. Parameters ulen The ulen parameter the size of the data array in bytes. Description: Dbt::get_ulen Return the length in bytes of the user-specified buffer. Description: Dbt::set_dlen Set the byte length of the partial record being read or written by the application, in bytes. See the DB_DBT_PARTIAL flag for more information. Parameters dlen The dlen parameter is the length of the partial record in bytes. Description: Dbt::get_dlen Return the length of the partial record, in bytes. Description: Dbt::set_doff Set the offset of the partial record being read or written by the application, in bytes. See the DB_DBT_PARTIAL flag for more information. Parameters doff The doff parameter is the offset of the partial record. Description: Dbt::get_doff Return the offset of the partial record, in bytes. Description: Dbt::set_object Set the object flag value. Parameters flags The flags parameter is Dbt flag value. The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values: DB_DBT_MALLOC When this flag is set, Berkeley DB will 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 key or data Dbt object. Because any allocated memory becomes the responsibility of the calling application, the caller must determine whether memory was allocated using the returned value of the data field. It is an error to specify more than one of DB_DBT_MALLOC, DB_DBT_REALLOC, and DB_DBT_USERMEM. DB_DBT_REALLOC When this flag is set Berkeley DB will allocate memory for the returned key or data item (using realloc(3) or the user-specified realloc method), and return a pointer to it in the data field of the key or data Dbt object. Because any allocated memory becomes the responsibility of the calling application, the caller must determine whether memory was allocated using the returned value of the data field. It is an error to specify more than one of DB_DBT_MALLOC, DB_DBT_REALLOC, and DB_DBT_USERMEM. DB_DBT_USERMEM The data field of the key or data object must refer to 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 referred to by the data field. Otherwise, the size field is set to the length needed for the requested item, and the error ENOMEM is returned. It is an error to specify more than one of DB_DBT_MALLOC, DB_DBT_REALLOC, and DB_DBT_USERMEM. If DB_DBT_MALLOC or 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_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 or throws an exception encapsulating an ENOMEM. 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 any existing 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 refer to 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; 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. Description: Dbt::set_object Return the object flag value.