258 lines
14 KiB
HTML
258 lines
14 KiB
HTML
<!--$Id: db_stat.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<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,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<table width="100%"><tr valign=top>
|
|
<td>
|
|
<b>Db::stat</b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_cxx/api_core.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>
|
|
<b><pre>
|
|
#include <db_cxx.h>
|
|
<p>
|
|
int
|
|
Db::stat(DbTxn *txnid, void *sp, u_int32_t flags);
|
|
<p>
|
|
int
|
|
Db::stat_print(u_int32_t flags);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: Db::stat</b>
|
|
<p>The Db::stat method creates a statistical structure and copies a
|
|
pointer to it into user-specified memory locations. Specifically, if
|
|
<b>sp</b> is non-NULL, a pointer to the statistics for the database are
|
|
copied into the memory location to which it refers.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or
|
|
one of the following values:
|
|
<br>
|
|
<b><a name="DB_FAST_STAT">DB_FAST_STAT</a></b><ul compact><li>Return only the values which do not require traversal of the database.
|
|
Among other things, this flag makes it possible for applications to
|
|
request key and record counts without incurring the performance penalty
|
|
of traversing the entire database.</ul>
|
|
<b><a name="DB_READ_COMMITTED">DB_READ_COMMITTED</a></b><ul compact><li>Database items read during a transactional call will have degree 2
|
|
isolation. This ensures the stability of the data items read during the
|
|
stat operation but permits that data to be modified or deleted by other
|
|
transactions prior to the commit of the specified transaction.</ul>
|
|
<b><a name="DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a></b><ul compact><li>Database items read during a transactional call will have degree 1
|
|
isolation, including modified but not yet committed data. Silently
|
|
ignored if the <a href="../api_cxx/db_open.html#DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> flag was not specified when
|
|
the underlying database was opened.</ul> <br></ul>
|
|
<b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the
|
|
<b>txnid</b> parameter is a transaction handle returned from
|
|
<a href="../api_cxx/txn_begin.html">DbEnv::txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the
|
|
<b>txnid</b> parameter is a handle returned from
|
|
<a href="../api_cxx/env_cdsgroup_begin.html">DbEnv::cdsgroup_begin</a>; otherwise NULL.
|
|
If no transaction handle is
|
|
specified, but the
|
|
operation occurs in a transactional
|
|
database,
|
|
the operation will be implicitly transaction protected.
|
|
</ul>
|
|
<br>
|
|
<p>Statistical structures are stored in allocated memory. If application-specific allocation
|
|
routines have been declared (see <a href="../api_cxx/env_set_alloc.html">DbEnv::set_alloc</a> for more
|
|
information), they are used to allocate the memory; otherwise, the
|
|
standard C library <b>malloc</b>(3) is used. The caller is
|
|
responsible for deallocating the memory. To deallocate the memory, free
|
|
the memory reference; references inside the returned memory need not be
|
|
individually freed.</p>
|
|
<p>If the DB_FAST_STAT flag has not been specified, the
|
|
Db::stat method will access some of or all the pages in the database,
|
|
incurring a severe performance penalty as well as possibly flushing the
|
|
underlying buffer pool.</p>
|
|
<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>
|
|
<p>If the database was not opened read-only and the DB_FAST_STAT
|
|
flag was not specified, the cached key and record numbers will be
|
|
updated after the statistical information has been gathered.</p>
|
|
<p>The Db::stat method may not be called before the <a href="../api_cxx/db_open.html">Db::open</a> method is called.</p>
|
|
<p>The Db::stat method
|
|
either returns a non-zero error value
|
|
or throws an exception that encapsulates a non-zero error value on
|
|
failure, and returns 0 on success.
|
|
</p>
|
|
<b>Hash Statistics</b>
|
|
<p>In the case of a Hash database, the statistics are stored in a structure
|
|
of type DB_HASH_STAT. The following fields will be filled in:</p>
|
|
<br>
|
|
<b>u_int32_t hash_magic;</b><ul compact><li>Magic number that identifies the file as a Hash file. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t hash_version;</b><ul compact><li>The version of the Hash database. Returned if DB_FAST_STAT is
|
|
set.</ul>
|
|
<b>u_int32_t hash_nkeys;</b><ul compact><li>The number of unique keys in the database. If DB_FAST_STAT was
|
|
specified the count will be the last saved value unless it has never
|
|
been calculated, in which case it will be 0. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t hash_ndata;</b><ul compact><li>The number of key/data pairs in the database. If DB_FAST_STAT
|
|
was specified the count will be the last saved value unless it has never
|
|
been calculated, in which case it will be 0. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t hash_pagecnt;</b><ul compact><li>The number of pages in the database. Returned if DB_FAST_STAT
|
|
is set.</ul>
|
|
<b>u_int32_t hash_pagesize;</b><ul compact><li>The underlying database page (and bucket) size, in bytes. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t hash_ffactor;</b><ul compact><li>The desired fill factor (number of items per bucket) specified at
|
|
database-creation time. Returned if DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t hash_buckets;</b><ul compact><li>The number of hash buckets. Returned if DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t hash_free;</b><ul compact><li>The number of pages on the free list.</ul>
|
|
<b>u_int32_t hash_bfree;</b><ul compact><li>The number of bytes free on bucket pages.</ul>
|
|
<b>u_int32_t hash_bigpages;</b><ul compact><li>The number of big key/data pages.</ul>
|
|
<b>u_int32_t hash_big_bfree;</b><ul compact><li>The number of bytes free on big item pages.</ul>
|
|
<b>u_int32_t hash_overflows;</b><ul compact><li>The number of overflow pages (overflow pages are pages that contain items
|
|
that did not fit in the main bucket page).</ul>
|
|
<b>u_int32_t hash_ovfl_free;</b><ul compact><li>The number of bytes free on overflow pages.</ul>
|
|
<b>u_int32_t hash_dup;</b><ul compact><li>The number of duplicate pages.</ul>
|
|
<b>u_int32_t hash_dup_free;</b><ul compact><li>The number of bytes free on duplicate pages.</ul>
|
|
<br>
|
|
<b>Btree and Recno Statistics</b>
|
|
<p>In the case of a Btree or Recno database, the statistics are stored in
|
|
a structure of type DB_BTREE_STAT. The following fields will be filled
|
|
in:</p>
|
|
<br>
|
|
<b>u_int32_t bt_magic;</b><ul compact><li>Magic number that identifies the file as a Btree database. Returned
|
|
if DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t bt_version;</b><ul compact><li>The version of the Btree database. Returned if DB_FAST_STAT
|
|
is set.</ul>
|
|
<b>u_int32_t bt_nkeys;</b><ul compact><li>For the Btree Access Method, the number of keys in the database. If
|
|
the DB_FAST_STAT flag is not specified or the database was
|
|
configured to support record numbers (see <a href="../api_cxx/db_set_flags.html#DB_RECNUM">DB_RECNUM</a>), the count
|
|
will be exact. Otherwise, the count will be the last saved value unless
|
|
it has never been calculated, in which case it will be 0.
|
|
<p>For the Recno Access Method, the number of records in the database. If
|
|
the database was configured with mutable record numbers (see
|
|
<a href="../api_cxx/db_set_flags.html#DB_RENUMBER">DB_RENUMBER</a>), the count will be exact. Otherwise, if the
|
|
DB_FAST_STAT flag is specified the count will be exact but will
|
|
include deleted and implicitly created records; if the
|
|
DB_FAST_STAT flag is not specified, the count will be exact and
|
|
will not include deleted or implicitly created records.</p>
|
|
<p>Returned if DB_FAST_STAT is set.</p></ul>
|
|
<b>u_int32_t bt_ndata;</b><ul compact><li>For the Btree Access Method, the number of key/data pairs in the
|
|
database. If the DB_FAST_STAT flag is not specified, the count
|
|
will be exact. Otherwise, the count will be the last saved value unless
|
|
it has never been calculated, in which case it will be 0.
|
|
<p>For the Recno Access Method, the number of records in the database. If
|
|
the database was configured with mutable record numbers (see
|
|
<a href="../api_cxx/db_set_flags.html#DB_RENUMBER">DB_RENUMBER</a>), the count will be exact. Otherwise, if the
|
|
DB_FAST_STAT flag is specified the count will be exact but will
|
|
include deleted and implicitly created records; if the
|
|
DB_FAST_STAT flag is not specified, the count will be exact and
|
|
will not include deleted or implicitly created records.</p>
|
|
<p>Returned if DB_FAST_STAT is set.</p></ul>
|
|
<b>u_int32_t bt_pagecnt;</b><ul compact><li>The number of pages in the database. Returned if DB_FAST_STAT
|
|
is set.</ul>
|
|
<b>u_int32_t bt_pagesize;</b><ul compact><li>The underlying database page size, in bytes. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t bt_minkey;</b><ul compact><li>The minimum keys per page. Returned if DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t bt_re_len;</b><ul compact><li>The length of fixed-length records. Returned if DB_FAST_STAT
|
|
is set.</ul>
|
|
<b>u_int32_t bt_re_pad;</b><ul compact><li>The padding byte value for fixed-length records. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t bt_levels;</b><ul compact><li>Number of levels in the database.</ul>
|
|
<b>u_int32_t bt_int_pg;</b><ul compact><li>Number of database internal pages.</ul>
|
|
<b>u_int32_t bt_leaf_pg;</b><ul compact><li>Number of database leaf pages.</ul>
|
|
<b>u_int32_t bt_dup_pg;</b><ul compact><li>Number of database duplicate pages.</ul>
|
|
<b>u_int32_t bt_over_pg;</b><ul compact><li>Number of database overflow pages.</ul>
|
|
<b>u_int32_t bt_empty_pg;</b><ul compact><li>Number of empty database pages.</ul>
|
|
<b>u_int32_t bt_free;</b><ul compact><li>Number of pages on the free list.</ul>
|
|
<b>u_int32_t bt_int_pgfree;</b><ul compact><li>Number of bytes free in database internal pages.</ul>
|
|
<b>u_int32_t bt_leaf_pgfree;</b><ul compact><li>Number of bytes free in database leaf pages.</ul>
|
|
<b>u_int32_t bt_dup_pgfree;</b><ul compact><li>Number of bytes free in database duplicate pages.</ul>
|
|
<b>u_int32_t bt_over_pgfree;</b><ul compact><li>Number of bytes free in database overflow pages.</ul>
|
|
<br>
|
|
<b>Queue Statistics</b>
|
|
<p>In the case of a Queue database, the statistics are stored in a
|
|
structure of type DB_QUEUE_STAT. The following fields will be filled
|
|
in:</p>
|
|
<br>
|
|
<b>u_int32_t qs_magic;</b><ul compact><li>Magic number that identifies the file as a Queue file. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t qs_version;</b><ul compact><li>The version of the Queue file type. Returned if DB_FAST_STAT
|
|
is set.</ul>
|
|
<b>u_int32_t qs_nkeys;</b><ul compact><li>The number of records in the database. If DB_FAST_STAT was
|
|
specified the count will be the last saved value unless it has never
|
|
been calculated, in which case it will be 0. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t qs_ndata;</b><ul compact><li>The number of records in the database. If DB_FAST_STAT was
|
|
specified the count will be the last saved value unless it has never
|
|
been calculated, in which case it will be 0. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t qs_pagesize;</b><ul compact><li>Underlying database page size, in bytes. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t qs_extentsize;</b><ul compact><li>Underlying database extent size, in pages. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t qs_pages;</b><ul compact><li>Number of pages in the database.</ul>
|
|
<b>u_int32_t qs_re_len;</b><ul compact><li>The length of the records. Returned if DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t qs_re_pad;</b><ul compact><li>The padding byte value for the records. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t qs_pgfree;</b><ul compact><li>Number of bytes free in database pages.</ul>
|
|
<b>u_int32_t qs_first_recno;</b><ul compact><li>First undeleted record in the database. Returned if
|
|
DB_FAST_STAT is set.</ul>
|
|
<b>u_int32_t qs_cur_recno;</b><ul compact><li>Next available record number. Returned if DB_FAST_STAT is set.</ul>
|
|
<br>
|
|
<br><b>Errors</b>
|
|
<p>The Db::stat method
|
|
may fail and throw
|
|
<a href="../api_cxx/except_class.html">DbException</a>,
|
|
encapsulating one of the following non-zero errors, or return one of
|
|
the following non-zero errors:</p>
|
|
<br>
|
|
<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election
|
|
unrolled a committed transaction.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul>
|
|
<br>
|
|
<br>
|
|
<b>EINVAL</b><ul compact><li>An
|
|
invalid flag value or parameter was specified.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: Db::stat_print</b>
|
|
<p>The Db::stat_print method displays the
|
|
database statistical information, as described for the Db::stat method.
|
|
The information is printed to a specified output channel (see the
|
|
<a href="../api_cxx/env_set_msgfile.html">DbEnv::set_msgfile</a> method for more information), or passed to an
|
|
application callback function (see the <a href="../api_cxx/env_set_msgcall.html">DbEnv::set_msgcall</a> method for
|
|
more information).</p>
|
|
<p>The Db::stat_print method may not be called before the <a href="../api_cxx/db_open.html">Db::open</a> method is called.</p>
|
|
<p>The Db::stat_print method
|
|
either returns a non-zero error value
|
|
or throws an exception that encapsulates a non-zero error value on
|
|
failure, and returns 0 on success.
|
|
</p>
|
|
<b>Parameters</b> <br>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one
|
|
or more of the following values:
|
|
<br>
|
|
<b><a name="DB_FAST_STAT">DB_FAST_STAT</a></b><ul compact><li>Return only the values which do not require traversal of the database.
|
|
Among other things, this flag makes it possible for applications to
|
|
request key and record counts without incurring the performance penalty
|
|
of traversing the entire database.</ul>
|
|
<b><a name="DB_STAT_ALL">DB_STAT_ALL</a></b><ul compact><li>Display all available information.</ul>
|
|
<br></ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<br><b>Class</b>
|
|
<a href="../api_cxx/db_class.html">Db</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_cxx/db_list.html">Databases and Related Methods</a>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_cxx/api_core.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>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|