1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<!--$Id: db_stat.so,v 10.37 2000/10/03 21:55:45 bostic Exp $-->
<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<html>
<head>
<title>Berkeley DB: Db.stat</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
</head>
<body bgcolor=white>
<a name="2"><!--meow--></a>
<table><tr valign=top>
<td>
<h1>Db.stat</h1>
</td>
<td width="1%">
<a href="../api_java/java_index.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
</td></tr></table>
<hr size=1 noshade>
<tt>
<h3><pre>
import com.sleepycat.db.*;
<p>
public Object Db.stat(int flags);
</pre></h3>
<h1>Description</h1>
<p>The Db.stat method creates a statistical structure and
fills it with statistics for the database.
<p>Statistical structures are created in allocated memory. If <b>db_malloc</b> is non-NULL, it
is called to allocate the memory, otherwise, the library function
<b>malloc</b>(3) is used. The function <b>db_malloc</b> must match
the calling conventions of the <b>malloc</b>(3) library routine.
Regardless, the caller is responsible for deallocating the returned
memory. To deallocate returned memory, free the returned memory
reference, references inside the returned memory do not need to be
individually freed.
<p>The <b>flags</b> parameter must be set to 0 or the following value:
<p><dl compact>
<p><dt><a name="Db.DB_CACHED_COUNTS">Db.DB_CACHED_COUNTS</a><dd>Return a cached count of the keys and records in a database. This flag
makes it possible for applications to request an possibly approximate key
and record count without incurring the performance penalty of traversing
the entire database. The statistics information described for the access
method <b>XX_nkeys</b> and <b>XX_ndata</b> fields below is filled in,
but no other information is collected. If the cached information has
never been set, the fields will be returned set to 0.
<p><dt><a name="Db.DB_RECORDCOUNT">Db.DB_RECORDCOUNT</a><dd>Return a count of the records in a Btree or Recno Access Method database.
This flag makes it possible for applications to request a record count
without incurring the performance penalty of traversing the entire
database. The statistics information described for the <b>bt_nkeys</b>
field below is filled in, but no other information is collected.
<p>This option is only available for Recno databases, or Btree databases
where the underlying database was created with the <a href="../api_java/db_set_flags.html#DB_RECNUM">Db.DB_RECNUM</a>
flag.
</dl>
<p>The Db.stat method may access all of the pages in the database,
incurring a severe performance penalty as well as possibly flushing the
underlying buffer pool.
<p>In the presence of multiple threads or processes accessing an active
database, the information returned by Db.stat may be out-of-date.
<p>If the database was not opened readonly and the Db.DB_CACHED_COUNTS
flag was not specified, the cached key and record numbers will be updated
after the statistical information has been gathered.
<p>The Db.stat method cannot be transaction protected. For this reason,
it should be called in a thread of control that has no open cursors or
active transactions.
<p>The Db.stat method throws an exception that encapsulates a non-zero error value on
failure.
<h3>Hash Statistics</h3>
<p>In the case of a Hash database,
the statistics are returned in an instance of DbHashStat. The data
fields are available from DbHashStat:
<p><dl compact>
<p><dt>public int hash_magic;<dd>Magic number that identifies the file as a Hash file.
<dt>public int hash_version;<dd>The version of the Hash database.
<dt>public int hash_nkeys;<dd>The number of unique keys in the database.
<dt>public int hash_ndata;<dd>The number of key/data pairs in the database.]
<dt>public int hash_pagesize;<dd>The underlying Hash database page (and bucket) size.
<dt>public int hash_nelem;<dd>The estimated size of the hash table specified at database creation time.
<dt>public int hash_ffactor;<dd>The desired fill factor (number of items per bucket) specified at database
creation time.
<dt>public int hash_buckets;<dd>The number of hash buckets.
<dt>public int hash_free;<dd>The number of pages on the free list.
<dt>public int hash_bfree;<dd>The number of bytes free on bucket pages.
<dt>public int hash_bigpages;<dd>The number of big key/data pages.
<dt>public int hash_big_bfree;<dd>The number of bytes free on big item pages.
<dt>public int hash_overflows;<dd>The number of overflow pages (overflow pages are pages that contain items
that did not fit in the main bucket page).
<dt>public int hash_ovfl_free;<dd>The number of bytes free on overflow pages.
<dt>public int hash_dup;<dd>The number of duplicate pages.
<dt>public int hash_dup_free;<dd>The number of bytes free on duplicate pages.
</dl>
<h3>Btree and Recno Statistics</h3>
<p>In the case of a Btree or Recno database,
the statistics are returned in an instance of DbBtreeStat. The data
fields are available from DbBtreeStat:
<p><dl compact>
<p><dt>public int bt_magic;<dd>Magic number that identifies the file as a Btree database.
<dt>public int bt_version;<dd>The version of the Btree database.
<dt>public int bt_nkeys;<dd>For the Btree Access Method, the number of unique keys in the database.
<p>For the Recno Access Method, the number of records in the database.
<dt>public int bt_ndata;<dd>For the Btree Access Method, the number of key/data pairs in the database.
<p>For the Recno Access Method, the number of records in the database. If
the database has been configured to not re-number records during
deletion, the number of records will only reflect undeleted records.
<dt>public int bt_pagesize;<dd>Underlying database page size.
<dt>public int bt_minkey;<dd>The minimum keys per page.
<dt>public int bt_re_len;<dd>The length of fixed-length records.
<dt>public int bt_re_pad;<dd>The padding byte value for fixed-length records.
<dt>public int bt_levels;<dd>Number of levels in the database.
<dt>public int bt_int_pg;<dd>Number of database internal pages.
<dt>public int bt_leaf_pg;<dd>Number of database leaf pages.
<dt>public int bt_dup_pg;<dd>Number of database duplicate pages.
<dt>public int bt_over_pg;<dd>Number of database overflow pages.
<dt>public int bt_free;<dd>Number of pages on the free list.
<dt>public int bt_int_pgfree;<dd>Number of bytes free in database internal pages.
<dt>public int bt_leaf_pgfree;<dd>Number of bytes free in database leaf pages.
<dt>public int bt_dup_pgfree;<dd>Number of bytes free in database duplicate pages.
<dt>public int bt_over_pgfree;<dd>Number of bytes free in database overflow pages.
</dl>
<h3>Queue Statistics</h3>
<p>In the case of a Queue database,
the statistics are returned in an instance of DbQueueStat. The data
fields are available from DbQueueStat:
<p><dl compact>
<p><dt>public int qs_magic;<dd>Magic number that identifies the file as a Queue file.
<dt>public int qs_version;<dd>The version of the Queue file type.
<dt>public int qs_nkeys;<dd>The number of records in the database.
<dt>public int qs_ndata;<dd>The number of records in the database.
<dt>public int qs_pagesize;<dd>Underlying database page size.
<dt>public int qs_pages;<dd>Number of pages in the database.
<dt>public int qs_re_len;<dd>The length of the records.
<dt>public int qs_re_pad;<dd>The padding byte value for the records.
<dt>public int qs_pgfree;<dd>Number of bytes free in database pages.
<dt>public int qs_start;<dd>Start offset.
<dt>public int qs_first_recno;<dd>First undeleted record in the database.
<dt>public int qs_cur_recno;<dd>Last allocated record number in the database.
</dl>
<p>The Db.stat method throws an exception that encapsulates a non-zero error value on
failure.
<h1>Errors</h1>
<p>The Db.stat method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods.
If a catastrophic error has occurred, the Db.stat method may fail and throw
a <a href="../api_java/runrec_class.html">DbRunRecoveryException</a>, in which case all subsequent Berkeley DB calls
will fail in the same way.
<h3>Class</h3>
<a href="../api_java/db_class.html">Db</a>
<h1>See Also</h1>
<a href="../api_java/db_close.html">Db.close</a>,
<a href="../api_java/db_cursor.html">Db.cursor</a>,
<a href="../api_java/db_del.html">Db.del</a>,
<a href="../api_java/db_fd.html">Db.fd</a>,
<a href="../api_java/db_get.html">Db.get</a>,
<a href="../api_java/db_get_byteswapped.html">Db.get_byteswapped</a>,
<a href="../api_java/db_get_type.html">Db.get_type</a>,
<a href="../api_java/db_join.html">Db.join</a>,
<a href="../api_java/db_key_range.html">Db.key_range</a>,
<a href="../api_java/db_open.html">Db.open</a>,
<a href="../api_java/db_put.html">Db.put</a>,
<a href="../api_java/db_remove.html">Db.remove</a>,
<a href="../api_java/db_set_bt_minkey.html">Db.set_bt_minkey</a>,
<a href="../api_java/db_set_cachesize.html">Db.set_cachesize</a>,
<a href="../api_java/db_set_errcall.html">Db.set_errcall</a>,
<a href="../api_java/db_set_errpfx.html">Db.set_errpfx</a>,
<a href="../api_java/db_set_flags.html">Db.set_flags</a>,
<a href="../api_java/db_set_h_ffactor.html">Db.set_h_ffactor</a>,
<a href="../api_java/db_set_h_nelem.html">Db.set_h_nelem</a>,
<a href="../api_java/db_set_lorder.html">Db.set_lorder</a>,
<a href="../api_java/db_set_pagesize.html">Db.set_pagesize</a>,
<a href="../api_java/db_set_q_extentsize.html">Db.set_q_extentsize</a>,
<a href="../api_java/db_set_re_delim.html">Db.set_re_delim</a>,
<a href="../api_java/db_set_re_len.html">Db.set_re_len</a>,
<a href="../api_java/db_set_re_pad.html">Db.set_re_pad</a>,
<a href="../api_java/db_set_re_source.html">Db.set_re_source</a>,
<a href="../api_java/db_stat.html">Db.stat</a>,
<a href="../api_java/db_sync.html">Db.sync</a>,
<a href="../api_java/db_upgrade.html">Db.upgrade</a>
and
<a href="../api_java/db_verify.html">Db.verify</a>.
</tt>
<table><tr><td><br></td><td width="1%">
<a href="../api_java/java_index.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
</td></tr></table>
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
</body>
</html>
|
