#include <db_cxx.h>

int
Db::stat(void *sp, u_int32_t flags);

Description

The Db::stat method creates a statistical structure and copies a pointer to it into user-specified memory locations. Specifically, if sp is non-NULL, a pointer to the statistics for the database are copied into the memory location to which it refers.

Statistical structures are created in allocated memory. If application-specific allocation routines have been declared (see DbEnv::set_alloc for more information), they are used to allocate the memory; otherwise, the library function malloc(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.

The flags value must be set to 0 or one of the following values:

DB_CACHED_COUNTS

Return a cached count of the keys and records in a database. The DB_CACHED_COUNTS flag has been deprecated in favor of the DB_FAST_STAT flag. Please update your applications.

DB_FAST_STAT

Return only the values which do not require traversal of the database. Fields returned when this flag is set are noted with an asterisk (*) below.

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. If the underlying database is of type Recno, or of type Btree and the database was created with the DB_RECNUM flag, the count of keys will be exact. Otherwise, the count of keys will be the value saved the last time the database was traversed, or 0 if no count of keys has ever been made. If the underlying database is of type Recno, the count of data items will be exact, otherwise, the count of data items will be the value saved the last time the database was traversed, or 0 if no count of data items has ever been done.

DB_RECORDCOUNT

Return a count of the records in a Btree or Recno Access Method database. The DB_RECORDCOUNT flag has been deprecated in favor of the DB_FAST_STAT flag. Please update your applications.

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.

In the presence of multiple threads or processes accessing an active database, the information returned by Db::stat may be out-of-date.

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.

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.

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.

Hash Statistics

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:

u_int32_t hash_magic*

Magic number that identifies the file as a Hash file.

u_int32_t hash_version*

The version of the Hash database.

u_int32_t hash_nkeys*

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.

u_int32_t hash_ndata*

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.

u_int32_t hash_pagesize*

The underlying Hash database page (and bucket) size, in bytes.

u_int32_t hash_nelem*

The estimated size of the hash table specified at database-creation time.

u_int32_t hash_ffactor*

The desired fill factor (number of items per bucket) specified at database-creation time.

u_int32_t hash_buckets*

The number of hash buckets.

u_int32_t hash_free

The number of pages on the free list.

u_int32_t hash_bfree

The number of bytes free on bucket pages.

u_int32_t hash_bigpages

The number of big key/data pages.

u_int32_t hash_big_bfree

The number of bytes free on big item pages.

u_int32_t hash_overflows

The number of overflow pages (overflow pages are pages that contain items that did not fit in the main bucket page).

u_int32_t hash_ovfl_free

The number of bytes free on overflow pages.

u_int32_t hash_dup

The number of duplicate pages.

u_int32_t hash_dup_free

The number of bytes free on duplicate pages.

Btree and Recno Statistics

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:

u_int32_t bt_magic*

Magic number that identifies the file as a Btree database.

u_int32_t bt_version*

The version of the Btree database.

u_int32_t bt_nkeys*

For the Btree Access Method, the number of unique keys in the database. If DB_FAST_STAT was specified and the database was created with the DB_RECNUM flag, 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.

For the Recno Access Method, the exact number of records in the database.

u_int32_t bt_ndata*

For the Btree Access Method, 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.

For the Recno Access Method, the exact number of records in the database. If the database has been configured to not renumber records during deletion, the count of records will only reflect undeleted records.

u_int32_t bt_pagesize*

Underlying database page size, in bytes.

u_int32_t bt_minkey*

The minimum keys per page.

u_int32_t bt_re_len*

The length of fixed-length records.

u_int32_t bt_re_pad*

The padding byte value for fixed-length records.

u_int32_t bt_levels

Number of levels in the database.

u_int32_t bt_int_pg

Number of database internal pages.

u_int32_t bt_leaf_pg

Number of database leaf pages.

u_int32_t bt_dup_pg

Number of database duplicate pages.

u_int32_t bt_over_pg

Number of database overflow pages.

u_int32_t bt_free

Number of pages on the free list.

u_int32_t bt_int_pgfree

Number of bytes free in database internal pages.

u_int32_t bt_leaf_pgfree

Number of bytes free in database leaf pages.

u_int32_t bt_dup_pgfree

Number of bytes free in database duplicate pages.

u_int32_t bt_over_pgfree

Number of bytes free in database overflow pages.

Queue Statistics

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:

u_int32_t qs_magic*

Magic number that identifies the file as a Queue file.

u_int32_t qs_version*

The version of the Queue file type.

u_int32_t qs_nkeys*

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.

u_int32_t qs_ndata*

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.

u_int32_t qs_pagesize*

Underlying database page size, in bytes.

u_int32_t qs_extentsize*

Underlying database extent size, in pages.

u_int32_t qs_pages

Number of pages in the database.

u_int32_t qs_re_len*

The length of the records.

u_int32_t qs_re_pad*

The padding byte value for the records.

u_int32_t qs_pgfree

Number of bytes free in database pages.

u_int32_t qs_start

Start offset.

u_int32_t qs_first_recno*

First undeleted record in the database.

u_int32_t qs_cur_recno*

Last allocated record number in the database.

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.

Errors

The Db::stat method may fail and throw an exception or return a non-zero error 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 either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail in the same way.

Class

See Also