# Dbt

           import com.sleepycat.db.*;

           public Dbt();
           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

           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 be set to a byte array
           of size bytes.  When returning  a  key/data  item  to  the
           application,  the  DB  package  will  store  into the data
           object a a byte array of size bytes.

           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.

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

           int size;
                The length  of  data,  in  bytes.   This  element  is
                accessed  using  get_size  and  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
                functions.   See  the  DB_DBT_USERMEM  flag  for more
                information.  This element is accessed using get_ulen
                and set_ulen.

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

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

           int 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.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  and  return  a  byte
                     array  containing  the data in the data field of
                     the key or data Dbt object.  It is an  error  to
                     specify both DB_DBT_MALLOC and DB_DBT_USERMEM.

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

           For  this  reason,  when using the JAVA DB API, either the
           DB_DBT_MALLOC or DB_DBT_USERMEM flags  must  be  specified
           for   any   Dbt  used  for  key  or  data  retrieval.   If
           DB_DBT_USERMEM is specified, the data  field  of  the  Dbt
           must be set to an appropriately sized byte array.

           If  DB_DBT_MALLOC  is  specified,  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.

## 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 four
           byte  array,  large  enough  to   store   an   int.    The
           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 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., 4.

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