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)


Man(1) output converted with man2html