зеркало из https://github.com/mozilla/gecko-dev.git
433 строки
22 KiB
HTML
433 строки
22 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>DbInfo</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>DbInfo</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>DbInfo();</B>
|
|
<B>public</B> <B>DbInfo(DbInfo</B> <B>that);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>lorder();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>lorder(int</B> <B>lorder);</B>
|
|
|
|
<B>public</B> <B>long</B> <B>get</B>_<B>cachesize();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>cachesize(long</B> <B>cachesize);</B>
|
|
|
|
<B>public</B> <B>long</B> <B>get</B>_<B>pagesize();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>pagesize(long</B> <B>pagesize);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>bt</B>_<B>minkey();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>bt</B>_<B>minkey(int</B> <B>bt</B>_<B>minkey);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>h</B>_<B>ffactor();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>h</B>_<B>ffactor(int</B> <B>h</B>_<B>ffactor);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>h</B>_<B>nelem();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>h</B>_<B>nelem(int</B> <B>h</B>_<B>nelem);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>re</B>_<B>pad();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>re</B>_<B>pad(int</B> <B>re</B>_<B>pad);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>re</B>_<B>delim();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>re</B>_<B>delim(int</B> <B>re</B>_<B>delim);</B>
|
|
|
|
<B>public</B> <B>int</B> <B>get</B>_<B>re</B>_<B>len();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>re</B>_<B>len(int</B> <B>re</B>_<B>len);</B>
|
|
|
|
<B>public</B> <B>String</B> <B>get</B>_<B>re</B>_<B>source();</B>
|
|
<B>public</B> <B>void</B> <B>set</B>_<B>re</B>_<B>source(String</B> <B>re</B>_<B>source);</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>
|
|
|
|
|
|
</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 DbInfo class. A DbInfo
|
|
object is used in conjunction with the Db.open method (see
|
|
<B><A HREF="Db.j.html">Db(3)</A></B>) to specify particular configuration options for the
|
|
open. The DbInfo 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 refers to these accesses using the
|
|
underlying name, e.g., cachesize instead of get_cachesize
|
|
and set_cachesize. The default constructor sets all
|
|
elements of the underlying structure to zero. Some of the
|
|
fields are specific to a type of file format (one of
|
|
btree, hashed and recno) and are thus named with an
|
|
underscore separated string, ``bt'', ``h'' and ``re'',
|
|
respectively. For example, the method set_bt_minkey sets
|
|
the underlying bt_minkey field, and this field is only
|
|
used when opening a btree file.
|
|
|
|
The fields that are common to all access methods are
|
|
listed here; those specific to an individual access method
|
|
are described below.
|
|
|
|
If possible, defaults appropriate for the system are used
|
|
for the DbInfo fields if dbinfo is null or any fields of
|
|
the DbInfo object are not explicitly set. The following
|
|
DbInfo fields may be initialized before calling Db.open:
|
|
|
|
long cachesize;
|
|
A suggested maximum size of the memory pool cache, in
|
|
bytes. If cachesize is not explicitly set, an
|
|
appropriate default is used. It is an error to
|
|
specify both the mp_info field and a non-zero
|
|
db_cachesize.
|
|
|
|
<B>Note,</B> <B>the</B> <B>minimum</B> <B>number</B> <B>of</B> <B>pages</B> <B>in</B> <B>the</B> <B>cache</B> <B>should</B>
|
|
<B>be</B> <B>no</B> <B>less</B> <B>than</B> <B>10,</B> <B>and</B> <B>the</B> <B>access</B> <B>methods</B> <B>will</B> <B>fail</B>
|
|
<B>if</B> <B>an</B> <B>insufficiently</B> <B>large</B> <B>cache</B> <B>is</B> <B>specified.</B> In
|
|
addition, for applications that exhibit strong
|
|
locality in their data access patterns, increasing
|
|
the size of the cache can significantly improve
|
|
application performance.
|
|
|
|
int lorder;
|
|
The byte order for integers in the stored database
|
|
metadata. The number should represent the order as
|
|
an integer, for example, big endian order is the
|
|
number 4,321, and little endian order is the number
|
|
1,234. If lorder is not explicitly set, the host
|
|
order of the machine where the Db library was
|
|
compiled is used.
|
|
|
|
The value of lorder is ignored except when databases
|
|
are being created. If a database already exists, the
|
|
byte order it uses is determined when the file is
|
|
read.
|
|
|
|
<B>The</B> <B>access</B> <B>methods</B> <B>provide</B> <B>no</B> <B>guarantees</B> <B>about</B> <B>the</B>
|
|
<B>byte</B> <B>ordering</B> <B>of</B> <B>the</B> <B>application</B> <B>data</B> <B>stored</B> <B>in</B> <B>the</B>
|
|
<B>database,</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>ordering.</B>
|
|
|
|
long pagesize;
|
|
The size of the pages used to hold items in the
|
|
database, in bytes. The minimum page size is 512
|
|
bytes and the maximum page size is 64K bytes. If
|
|
pagesize is not explicitly set, a page size is
|
|
selected based on the underlying filesystem I/O block
|
|
size. The selected size has a lower limit of 512
|
|
bytes and an upper limit of 16K bytes.
|
|
|
|
|
|
</PRE>
|
|
<H2>BTREE</H2><PRE>
|
|
The btree data structure is a sorted, balanced tree
|
|
structure storing associated key/data pairs. Searches,
|
|
insertions, and deletions in the btree will all complete
|
|
in O (lg base N) where base is the average number of keys
|
|
per page. Often, inserting ordered data into btrees
|
|
results in pages that are half-full. This implementation
|
|
has been modified to make ordered (or inverse ordered)
|
|
insertion the best case, resulting in nearly perfect page
|
|
space utilization.
|
|
|
|
Space freed by deleting key/data pairs from the database
|
|
is never reclaimed from the filesystem, although it is
|
|
reused where possible. This means that the btree storage
|
|
structure is grow-only. If sufficiently many keys are
|
|
deleted from a tree that shrinking the underlying database
|
|
file is desirable, this can be accomplished by creating a
|
|
new tree from a scan of the existing one.
|
|
|
|
The following additional fields and flags may be
|
|
initialized in the DbInfo object before calling Db.open,
|
|
when using the btree access method:
|
|
|
|
int bt_minkey;
|
|
The minimum number of keys that will be stored on any
|
|
single page. This value is used to determine which
|
|
keys will be stored on overflow pages, i.e. if a key
|
|
or data item is larger than the pagesize divided by
|
|
the bt_minkey value, it will be stored on overflow
|
|
pages instead of in the page itself. The bt_minkey
|
|
value specified must be at least 2; if bt_minkey is
|
|
not explicitly set, a value of 2 is used.
|
|
|
|
unsigned long flags;
|
|
The following additional flags may be specified:
|
|
|
|
DB_DUP
|
|
Permit duplicate keys in the tree, i.e.
|
|
insertion when the key of the key/data pair
|
|
being inserted already exists in the tree will
|
|
be successful. The ordering of duplicates in
|
|
the tree is determined by the order of
|
|
insertion, unless the ordering is otherwise
|
|
specified by use of a cursor (see <B><A HREF="Dbc.j.html">Dbc(3)</A></B> for
|
|
more information.) It is an error to specify
|
|
both DB_DUP and DB_RECNUM.
|
|
|
|
Db.DB_RECNUM
|
|
Support retrieval from btrees using record
|
|
numbers. For more information, see the
|
|
DB_GET_RECNO flag to the db.get method (below),
|
|
and the cursor Dbc.get method (in <B><A HREF="Dbc.j.html">Dbc(3)</A></B>).
|
|
|
|
Logical record numbers in btrees are mutable in
|
|
the face of record insertion or deletion. See
|
|
the DB_RENUMBER flag in the RECNO section below
|
|
for further discussion.
|
|
|
|
Maintaining record counts within a btree
|
|
introduces a serious point of contention, namely
|
|
the page locations where the record counts are
|
|
stored. In addition, the entire tree must be
|
|
locked during both insertions and deletions,
|
|
effectively single-threading the tree for those
|
|
operations. Specifying DB_RECNUM can result in
|
|
serious performance degradation for some
|
|
applications and data sets.
|
|
|
|
It is an error to specify both DB_DUP and
|
|
DB_RECNUM.
|
|
|
|
|
|
</PRE>
|
|
<H2>HASH</H2><PRE>
|
|
The hash data structure is an extensible, dynamic hashing
|
|
scheme. Backward compatible interfaces to the functions
|
|
described in <B>dbm(3)</B>, <B>ndbm(3)</B> and <B>hsearch(3)</B> are provided,
|
|
however these interfaces are not compatible with previous
|
|
file formats.
|
|
|
|
The following additional fields and flags may be
|
|
initialized in the DbInfo object before calling Db.open,
|
|
when using the hash access method:
|
|
|
|
int h_ffactor;
|
|
The desired density within the hash table. It is an
|
|
approximation of the number of keys allowed to
|
|
accumulate in any one bucket, determining when the
|
|
hash table grows or shrinks. The default value is 0,
|
|
indicating that the fill factor will be selected
|
|
dynamically as pages are filled.
|
|
|
|
int h_nelem;
|
|
An estimate of the final size of the hash table. If
|
|
not set or set too low, hash tables will expand
|
|
gracefully as keys are entered, although a slight
|
|
performance degradation may be noticed. The default
|
|
value is 1.
|
|
|
|
unsigned long flags;
|
|
The following additional flags may be specified by
|
|
<B>or</B>'ing together one or more of the following values:
|
|
|
|
DB_DUP
|
|
Permit duplicate keys in the tree, i.e.
|
|
insertion when the key of the key/data pair
|
|
being inserted already exists in the tree will
|
|
be successful. The ordering of duplicates in
|
|
the tree is determined by the order of
|
|
insertion, unless the ordering is otherwise
|
|
specified by use of a cursor (see <B><A HREF="Dbc.j.html">Dbc(3)</A></B> for
|
|
more information.)
|
|
|
|
|
|
</PRE>
|
|
<H2>RECNO</H2><PRE>
|
|
The recno access method provides support for fixed and
|
|
variable length records, optionally backed by a flat text
|
|
(byte stream) file. Both fixed and variable length
|
|
records are accessed by their logical record number.
|
|
|
|
It is valid to create a record whose record number is more
|
|
than one greater than the last record currently in the
|
|
database. For example, the creation of record number 8,
|
|
when records 6 and 7 do not yet exist, is not an error.
|
|
However, any attempt to retrieve such records (e.g.,
|
|
records 6 and 7) will return DB_KEYEMPTY.
|
|
|
|
Deleting a record will not, by default, renumber records
|
|
following the deleted record (see DB_RENUMBER below for
|
|
more information). Any attempt to retrieve deleted
|
|
records will return DB_KEYEMPTY.
|
|
|
|
The following additional fields and flags may be
|
|
initialized in the DbInfo object before calling Db.open,
|
|
when using the recno access method:
|
|
|
|
int re_delim;
|
|
For variable length records, if the re_source file is
|
|
specified and the DB_DELIMITER flag is set, the
|
|
delimiting byte used to mark the end of a record in
|
|
the source file. If the re_source file is specified
|
|
and the DB_DELIMITER flag is not set, <newline>
|
|
characters (i.e. ``\n'', 0x0a) are interpreted as
|
|
end-of-record markers.
|
|
|
|
int re_len;
|
|
The length of a fixed-length record.
|
|
|
|
int re_pad;
|
|
For fixed length records, if the DB_PAD flag is set,
|
|
the pad character for short records. If the DB_PAD
|
|
flag is not explicitly set, <space> characters (i.e.,
|
|
0x20) are used for padding.
|
|
|
|
String re_source;
|
|
The purpose of the re_source field is to provide fast
|
|
access and modification to databases that are
|
|
normally stored as flat text files.
|
|
|
|
If the re_source field is explicitly set, it
|
|
specifies an underlying flat text database file that
|
|
is read to initialize a transient record number
|
|
index. In the case of variable length records, the
|
|
records are separated by the byte value re_delim.
|
|
For example, standard UNIX byte stream files can be
|
|
interpreted as a sequence of variable length records
|
|
separated by <newline> characters.
|
|
|
|
In addition, when cached data would normally be
|
|
written back to the underlying database file (e.g.,
|
|
the close or sync methods are called), the in-memory
|
|
copy of the database will be written back to the
|
|
re_source file.
|
|
|
|
By default, the backing source file is read lazily,
|
|
i.e., records are not read from the file until they
|
|
are requested by the application. <B>If</B> <B>multiple</B>
|
|
<B>processes</B> <B>(not</B> <B>threads)</B> <B>are</B> <B>accessing</B> <B>a</B> <B>recno</B>
|
|
<B>database</B> <B>concurrently</B> <B>and</B> <B>either</B> <B>inserting</B> <B>or</B>
|
|
<B>deleting</B> <B>records,</B> <B>the</B> <B>backing</B> <B>source</B> <B>file</B> <B>must</B> <B>be</B>
|
|
<B>read</B> <B>in</B> <B>its</B> <B>entirety</B> <B>before</B> <B>more</B> <B>than</B> <B>a</B> <B>single</B>
|
|
<B>process</B> <B>accesses</B> <B>the</B> <B>database,</B> <B>and</B> <B>only</B> <B>that</B> <B>process</B>
|
|
<B>should</B> <B>specify</B> <B>the</B> <B>backing</B> <B>source</B> <B>file</B> <B>as</B> <B>part</B> <B>of</B> <B>the</B>
|
|
Db.open call. See the DB_SNAPSHOT flag below for
|
|
more information.
|
|
|
|
<B>Reading</B> <B>and</B> <B>writing</B> <B>the</B> <B>backing</B> <B>source</B> <B>file</B> <B>specified</B>
|
|
<B>by</B> <B>re</B>_<B>source</B> <B>cannot</B> <B>be</B> <B>transactionally</B> <B>protected</B>
|
|
<B>because</B> <B>it</B> <B>involves</B> <B>filesystem</B> <B>operations</B> <B>that</B> <B>are</B>
|
|
<B>not</B> <B>part</B> <B>of</B> <B>the</B> <B>Db</B> <B>transaction</B> <B>methodology.</B> For this
|
|
reason, if a temporary database is used to hold the
|
|
records, i.e., a null was specified as the file
|
|
argument to Db.open, it is possible to lose the
|
|
contents of the re_source file, e.g., if the system
|
|
crashes at the right instant. If a file is used to
|
|
hold the database, i.e., a file name was specified as
|
|
the file argument to Db.open, normal database
|
|
recovery on that file can be used to prevent
|
|
information loss, although it is still possible that
|
|
the contents of re_source will be lost if the system
|
|
crashes.
|
|
|
|
The re_source file must already exist (but may be
|
|
zero-length) when Db.open is called.
|
|
|
|
For all of the above reasons, the re_source field is
|
|
generally used to specify databases that are read-
|
|
only for Db applications, and that are either
|
|
generated on the fly by software tools, or modified
|
|
using a different mechanism, e.g., a text editor.
|
|
|
|
unsigned long flags;
|
|
The following additional flags may be specified by
|
|
<B>or</B>'ing together one or more of the following values:
|
|
|
|
Db.DB_DELIMITER
|
|
The re_delim field is set.
|
|
|
|
Db.DB_FIXEDLEN
|
|
The records are fixed-length, not byte
|
|
delimited. The re_len value specifies the
|
|
length of the record, and the re_pad value is
|
|
used as the pad character.
|
|
|
|
Any records added to the database that are less
|
|
than re_len bytes long are automatically padded.
|
|
Any attempt to insert records into the database
|
|
that are greater than re_len bytes long will
|
|
cause the call to fail immediately and return an
|
|
error.
|
|
|
|
Db.DB_PAD
|
|
The re_pad field is set.
|
|
|
|
Db.DB_RENUMBER
|
|
Specifying the DB_RENUMBER flag causes the
|
|
logical record numbers to be mutable, and change
|
|
as records are added to and deleted from the
|
|
database. For example, the deletion of record
|
|
number 4 causes records numbered 5 and greater
|
|
to be renumbered downward by 1. If a cursor was
|
|
positioned to record number 4 before the
|
|
deletion, it will reference the new record
|
|
number 4, if any such record exists, after the
|
|
deletion. If a cursor was positioned after
|
|
record number 4 before the deletion, it will be
|
|
shifted downward 1 logical record, continuing to
|
|
reference the same record as it did before.
|
|
|
|
Using the Dbc.put or put interfaces to create
|
|
new records will cause the creation of multiple
|
|
records if the record number is more than one
|
|
greater than the largest record currently in the
|
|
database. For example, creating record 28, when
|
|
record 25 was previously the last record in the
|
|
database, will create records 26 and 27 as well
|
|
as 28. Attempts to retrieve records that were
|
|
created in this manner will result in an error
|
|
return of DB_KEYEMPTY.
|
|
|
|
If a created record is not at the end of the
|
|
database, all records following the new record
|
|
will be automatically renumbered upward by 1.
|
|
For example, the creation of a new record
|
|
numbered 8 causes records numbered 8 and greater
|
|
to be renumbered upward by 1. If a cursor was
|
|
positioned to record number 8 or greater before
|
|
the insertion, it will be shifted upward 1
|
|
logical record, continuing to reference the same
|
|
record as it did before.
|
|
|
|
For these reasons, concurrent access to a recno
|
|
database with the DB_RENUMBER flag specified may
|
|
be largely meaningless, although it is
|
|
supported.
|
|
|
|
Db.DB_SNAPSHOT
|
|
This flag specifies that any specified re_source
|
|
file be read in its entirety when Db.open is
|
|
called. If this flag is not specified, the
|
|
re_source file may be read lazily.
|
|
|
|
|
|
</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>
|