# Dbt

           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

           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 point to a byte string
           of size bytes.  When returning  a  key/data  item  to  the
           application,  the  DB  package  will  store  into the data
           object a pointer to a  byte  string  of  size  bytes.   By
           default,  the  memory referenced by this stored pointer is
           only valid until the next call to the DB package using the
           Db handle returned by Db::open.

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

           The 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 get_data and set_data, and may  be  initialized
                using one of the constructors.

           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.

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

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

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

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

           u_int32_t 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_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 (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.  The 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
                     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_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.

## 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 pointer to a memory location of
           type  db_recno_t,  as  typedef'd in the <db_cxx.h> include
           file.  This type is a 32-bit unsigned 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.,

           in the C programming language, ``sizeof(db_recno_t)''.

           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), DbMpoolFile(3), Dbt(3), DbTxn(3),
           DbTxnMgr(3)