2
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
4
<!--See the file LICENSE for redistribution information.-->
7
<title>Berkeley DB: Db.stat</title>
8
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
12
<a name="2"><!--meow--></a>
13
<table width="100%"><tr valign=top>
18
<a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
23
import com.sleepycat.db.*;
25
public Object stat(int flags)
29
<p>The Db.stat method creates a statistical structure and
30
fills it with statistics for the database.
31
<p>The <b>flags</b> value must be set to 0 or
32
one of the following values:
34
<p><dt><a name="Db.DB_FAST_STAT">Db.DB_FAST_STAT</a><dd>Return only the values which do not require traversal of the database.
35
Fields returned when this flag is set are noted with an asterisk (*)
37
<p>Among other things, this flag makes it possible for applications to
38
request key and record counts without incurring the performance penalty
39
of traversing the entire database. If the underlying database is of
40
type Recno, or of type Btree and the database was created with the
41
<a href="../api_java/db_set_flags.html#DB_RECNUM">Db.DB_RECNUM</a> flag, the count of keys will be exact. Otherwise,
42
the count of keys will be the value saved the last time the database
43
was traversed, or 0 if no count of keys has ever been made. If the
44
underlying database is of type Recno, the count of data items will be
45
exact, otherwise, the count of data items will be the value saved the
46
last time the database was traversed, or 0 if no count of data items
49
<p>If the Db.DB_FAST_STAT flag has not been specified, the
50
Db.stat method will access some of or all the pages in the database,
51
incurring a severe performance penalty as well as possibly flushing the
52
underlying buffer pool.
53
<p>In the presence of multiple threads or processes accessing an active
54
database, the information returned by Db.stat may be out-of-date.
55
<p>If the database was not opened read-only and the Db.DB_FAST_STAT
56
flag was not specified, the cached key and record numbers will be
57
updated after the statistical information has been gathered.
58
<p>The Db.stat method cannot be transaction-protected. For this reason,
59
it should be called in a thread of control that has no open cursors or
61
<p>The Db.stat method throws an exception that encapsulates a non-zero error value on
63
<h3>Hash Statistics</h3>
64
<p>In the case of a Hash database,
65
the statistics are returned in an instance of DbHashStat. The data
66
fields are available from DbHashStat:
68
<p><dt>public int hash_magic*<dd>Magic number that identifies the file as a Hash file.
69
<dt>public int hash_version*<dd>The version of the Hash database.
70
<dt>public int hash_nkeys*<dd>The number of unique keys in the database. If Db.DB_FAST_STAT was
71
specified the count will be the last saved value unless it has never
72
been calculated, in which case it will be 0.
73
<dt>public int hash_ndata*<dd>The number of key/data pairs in the database. If Db.DB_FAST_STAT
74
was specified the count will be the last saved value unless it has never
75
been calculated, in which case it will be 0.
76
<dt>public int hash_pagesize*<dd>The underlying Hash database page (and bucket) size, in bytes.
77
<dt>public int hash_ffactor*<dd>The desired fill factor (number of items per bucket) specified at
78
database-creation time.
79
<dt>public int hash_buckets*<dd>The number of hash buckets.
80
<dt>public int hash_free<dd>The number of pages on the free list.
81
<dt>public int hash_bfree<dd>The number of bytes free on bucket pages.
82
<dt>public int hash_bigpages<dd>The number of big key/data pages.
83
<dt>public int hash_big_bfree<dd>The number of bytes free on big item pages.
84
<dt>public int hash_overflows<dd>The number of overflow pages (overflow pages are pages that contain items
85
that did not fit in the main bucket page).
86
<dt>public int hash_ovfl_free<dd>The number of bytes free on overflow pages.
87
<dt>public int hash_dup<dd>The number of duplicate pages.
88
<dt>public int hash_dup_free<dd>The number of bytes free on duplicate pages.
90
<h3>Btree and Recno Statistics</h3>
91
<p>In the case of a Btree or Recno database,
92
the statistics are returned in an instance of DbBtreeStat. The data
93
fields are available from DbBtreeStat:
95
<p><dt>public int bt_magic*<dd>Magic number that identifies the file as a Btree database.
96
<dt>public int bt_version*<dd>The version of the Btree database.
97
<dt>public int bt_nkeys*<dd>For the Btree Access Method, the number of unique keys in the database.
98
If Db.DB_FAST_STAT was specified and the database was created with
99
the <a href="../api_java/db_set_flags.html#DB_RECNUM">Db.DB_RECNUM</a> flag, the count will be exact, otherwise, the
100
count will be the last saved value unless it has never been calculated,
101
in which case it will be 0.
102
<p>For the Recno Access Method, the exact number of records in the
104
<dt>public int bt_ndata*<dd>For the Btree Access Method, the number of key/data pairs in the
105
database. If Db.DB_FAST_STAT was specified the count will be the
106
last saved value unless it has never been calculated, in which case it
108
<p>For the Recno Access Method, the exact number of records in the
109
database. If the database has been configured to not renumber records
110
during deletion, the count of records will only reflect undeleted
112
<dt>public int bt_pagesize*<dd>Underlying database page size, in bytes.
113
<dt>public int bt_minkey*<dd>The minimum keys per page.
114
<dt>public int bt_re_len*<dd>The length of fixed-length records.
115
<dt>public int bt_re_pad*<dd>The padding byte value for fixed-length records.
116
<dt>public int bt_levels<dd>Number of levels in the database.
117
<dt>public int bt_int_pg<dd>Number of database internal pages.
118
<dt>public int bt_leaf_pg<dd>Number of database leaf pages.
119
<dt>public int bt_dup_pg<dd>Number of database duplicate pages.
120
<dt>public int bt_over_pg<dd>Number of database overflow pages.
121
<dt>public int bt_free<dd>Number of pages on the free list.
122
<dt>public int bt_int_pgfree<dd>Number of bytes free in database internal pages.
123
<dt>public int bt_leaf_pgfree<dd>Number of bytes free in database leaf pages.
124
<dt>public int bt_dup_pgfree<dd>Number of bytes free in database duplicate pages.
125
<dt>public int bt_over_pgfree<dd>Number of bytes free in database overflow pages.
127
<h3>Queue Statistics</h3>
128
<p>In the case of a Queue database,
129
the statistics are returned in an instance of DbQueueStat. The data
130
fields are available from DbQueueStat:
132
<p><dt>public int qs_magic*<dd>Magic number that identifies the file as a Queue file.
133
<dt>public int qs_version*<dd>The version of the Queue file type.
134
<dt>public int qs_nkeys*<dd>The number of records in the database. If Db.DB_FAST_STAT was
135
specified the count will be the last saved value unless it has never
136
been calculated, in which case it will be 0.
137
<dt>public int qs_ndata*<dd>The number of records in the database. If Db.DB_FAST_STAT was
138
specified the count will be the last saved value unless it has never
139
been calculated, in which case it will be 0.
140
<dt>public int qs_pagesize*<dd>Underlying database page size, in bytes.
141
<dt>public int qs_extentsize*<dd>Underlying database extent size, in pages.
142
<dt>public int qs_pages<dd>Number of pages in the database.
143
<dt>public int qs_re_len*<dd>The length of the records.
144
<dt>public int qs_re_pad*<dd>The padding byte value for the records.
145
<dt>public int qs_pgfree<dd>Number of bytes free in database pages.
146
<dt>public int qs_first_recno*<dd>First undeleted record in the database.
147
<dt>public int qs_cur_recno*<dd>Next available record number.
149
<p>The Db.stat method throws an exception that encapsulates a non-zero error value on
152
<p>The Db.stat method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods.
153
If a catastrophic error has occurred, the Db.stat method may fail and
154
throw a <a href="../api_java/runrec_class.html">DbRunRecoveryException</a>,
155
in which case all subsequent Berkeley DB calls will fail in the same way.
157
<a href="../api_java/db_class.html">Db</a>
159
<a href="../api_java/db_list.html">Databases and Related Methods</a>
161
<table width="100%"><tr><td><br></td><td align=right>
162
<a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
164
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>