зеркало из https://github.com/mozilla/gecko-dev.git
280 строки
15 KiB
HTML
280 строки
15 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>Dbt</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>Dbt</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<B>import</B> <B>com.sleepycat.db.*;</B>
|
|
|
|
<B>public</B> <B>Dbt();</B>
|
|
<B>public</B> <B>Dbt(byte[]</B> <B>data);</B>
|
|
<B>public</B> <B>Dbt(byte[]</B> <B>data,</B> <B>int</B> <B>off,</B> <B>int</B> <B>len);</B>
|
|
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>data(byte[]</B> <B>data);</B>
|
|
<B>public</B> <B>byte[]</B> <B>get</B>_<B>data();</B>
|
|
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>offset(int</B> <B>off);</B>
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>offset();</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>size();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>size(int</B> <B>size);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>ulen();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>ulen(int</B> <B>ulen);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>dlen();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>dlen(int</B> <B>dlen);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>doff();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>doff(int</B> <B>doff);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>flags();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>flags(int</B> <B>flags);</B>
|
|
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>recno</B>_<B>key</B>_<B>data(int</B> <B>recno);</B>
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>recno</B>_<B>key</B>_<B>data();</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
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 <B><A HREF="db_intro.html">db_intro(3)</A></B>. This manual page describes the
|
|
specific details of the Dbt class, used to encode keys and
|
|
data items in a database.
|
|
|
|
|
|
</PRE>
|
|
<H2>KEY/DATA PAIRS</H2><PRE>
|
|
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.
|
|
|
|
<B>The</B> <B>access</B> <B>methods</B> <B>provide</B> <B>no</B> <B>guarantees</B> <B>about</B> <B>byte</B> <B>string</B>
|
|
<B>alignment,</B> <B>and</B> <B>applications</B> <B>are</B> <B>responsible</B> <B>for</B>
|
|
<B>maintaining</B> <B>any</B> <B>necessary</B> <B>alignment.</B> 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 <B>or</B>'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 <B><A HREF="Db.j.html">Db.open(3)</A></B> 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 <B><A HREF="Db.j.html">Db.open(3)</A></B>. <B>When</B> <B>multiple</B>
|
|
<B>threads</B> <B>are</B> <B>using</B> <B>the</B> <B>returned</B> <B>Db</B> <B>handle</B> <B>concurrently,</B>
|
|
<B>either</B> <B>the</B> <B>DB</B>_<B>DBT</B>_<B>MALLOC</B> <B>or</B> <B>DB</B>_<B>DBT</B>_<B>USERMEM</B> <B>flags</B> <B>must</B> <B>be</B>
|
|
<B>specified</B> <B>for</B> <B>any</B> <B>Dbt</B> <B>used</B> <B>for</B> <B>key</B> <B>or</B> <B>data</B> <B>retrieval.</B>
|
|
|
|
<B>For</B> <B>this</B> <B>reason,</B> <B>when</B> <B>using</B> <B>the</B> <B>JAVA</B> <B>DB</B> <B>API,</B> <B>either</B> <B>the</B>
|
|
<B>DB</B>_<B>DBT</B>_<B>MALLOC</B> <B>or</B> <B>DB</B>_<B>DBT</B>_<B>USERMEM</B> <B>flags</B> <B>must</B> <B>be</B> <B>specified</B>
|
|
<B>for</B> <B>any</B> <B>Dbt</B> <B>used</B> <B>for</B> <B>key</B> <B>or</B> <B>data</B> <B>retrieval.</B> 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.
|
|
|
|
|
|
</PRE>
|
|
<H2>LOGICAL RECORD NUMBERS</H2><PRE>
|
|
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.
|
|
|
|
|
|
</PRE>
|
|
<H2>BUGS</H2><PRE>
|
|
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.
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
<B><A HREF="db_archive.html">db_archive(1)</A></B>, <B><A HREF="db_checkpoint.html">db_checkpoint(1)</A></B>, <B><A HREF="db_deadlock.html">db_deadlock(1)</A></B>, <B><A HREF="db_dump.html">db_dump(1)</A></B>,
|
|
<B><A HREF="db_load.html">db_load(1)</A></B>, <B><A HREF="db_recover.html">db_recover(1)</A></B>, <B><A HREF="db_stat.html">db_stat(1)</A></B>, <B><A HREF="db_intro.html">db_intro(3)</A></B>,
|
|
<B><A HREF="db_internal.html">db_internal(3)</A></B>, <B><A HREF="db_thread.html">db_thread(3)</A></B>, <B><A HREF="Db.j.html">Db(3)</A></B>, <B><A HREF="Dbc.j.html">Dbc(3)</A></B>, <B><A HREF="DbEnv.j.html">DbEnv(3)</A></B>,
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B>, <B><A HREF="DbInfo.j.html">DbInfo(3)</A></B>, <B><A HREF="DbLock.j.html">DbLock(3)</A></B>, <B><A HREF="DbLockTab.j.html">DbLockTab(3)</A></B>, <B><A HREF="DbLog.j.html">DbLog(3)</A></B>,
|
|
<B><A HREF="DbLsn.j.html">DbLsn(3)</A></B>, <B><A HREF="DbMpool.j.html">DbMpool(3)</A></B>, <B><A HREF="Dbt.j.html">Dbt(3)</A></B>, <B><A HREF="DbTxn.j.html">DbTxn(3)</A></B>, <B><A HREF="DbTxnMgr.j.html">DbTxnMgr(3)</A></B>
|
|
|
|
</PRE>
|
|
<HR SIZE=1 NOSHADE>
|
|
<ADDRESS>
|
|
Man(1) output converted with
|
|
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
|
|
</ADDRESS>
|
|
</BODY>
|
|
</HTML>
|