#include <db_cxx.h>

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

int
Db::stat_print(u_int32_t flags);

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.

• The flags parameter must be set to 0 or one of the following values:
  DB_FAST_STAT
  • 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.
  DB_READ_COMMITTED
  • 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.
  DB_READ_UNCOMMITTED
  • Database items read during a transactional call will have degree 1 isolation, including modified but not yet committed data. Silently ignored if the DB_READ_UNCOMMITTED flag was not specified when the underlying database was opened.
  
  

• If the operation is part of an application-specified transaction, the txnid parameter is a transaction handle returned from DbEnv::txn_begin; if the operation is part of a Berkeley DB Concurrent Data Store group, the txnid parameter is a handle returned from DbEnv::cdsgroup_begin; otherwise NULL. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

Statistical structures are stored 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 standard C library 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.

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 may not be called before the Db::open method is called.

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.

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:

• Magic number that identifies the file as a Hash file. Returned if DB_FAST_STAT is set.

• The version of the Hash database. Returned if DB_FAST_STAT is set.

• 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.

• 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.

• The number of pages in the database. Returned if DB_FAST_STAT is set.

• The underlying database page (and bucket) size, in bytes. Returned if DB_FAST_STAT is set.

• The desired fill factor (number of items per bucket) specified at database-creation time. Returned if DB_FAST_STAT is set.

• The number of hash buckets. Returned if DB_FAST_STAT is set.

• The number of pages on the free list.

• The number of bytes free on bucket pages.

• The number of big key/data pages.

• The number of bytes free on big item pages.

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

• The number of bytes free on overflow pages.

• The number of duplicate pages.

• The number of bytes free on duplicate pages.

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:

• Magic number that identifies the file as a Btree database. Returned if DB_FAST_STAT is set.

• The version of the Btree database. Returned if DB_FAST_STAT is set.

• 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 DB_RECNUM), 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 number of records in the database. If the database was configured with mutable record numbers (see DB_RENUMBER), 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.

  Returned if DB_FAST_STAT is set.

• 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.

  For the Recno Access Method, the number of records in the database. If the database was configured with mutable record numbers (see DB_RENUMBER), 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.

  Returned if DB_FAST_STAT is set.

• The number of pages in the database. Returned if DB_FAST_STAT is set.

• The underlying database page size, in bytes. Returned if DB_FAST_STAT is set.

• The minimum keys per page. Returned if DB_FAST_STAT is set.

• The length of fixed-length records. Returned if DB_FAST_STAT is set.

• The padding byte value for fixed-length records. Returned if DB_FAST_STAT is set.

• Number of levels in the database.

• Number of database internal pages.

• Number of database leaf pages.

• Number of database duplicate pages.

• Number of database overflow pages.

• Number of empty database pages.

• Number of pages on the free list.

• Number of bytes free in database internal pages.

• Number of bytes free in database leaf pages.

• Number of bytes free in database duplicate pages.

• Number of bytes free in database overflow pages.

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:

• Magic number that identifies the file as a Queue file. Returned if DB_FAST_STAT is set.

• The version of the Queue file type. Returned if DB_FAST_STAT is set.

• 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.

• 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.

• Underlying database page size, in bytes. Returned if DB_FAST_STAT is set.

• Underlying database extent size, in pages. Returned if DB_FAST_STAT is set.

• Number of pages in the database.

• The length of the records. Returned if DB_FAST_STAT is set.

• The padding byte value for the records. Returned if DB_FAST_STAT is set.

• Number of bytes free in database pages.

• First undeleted record in the database. Returned if DB_FAST_STAT is set.

• Next available record number. Returned if DB_FAST_STAT is set.

The Db::stat method may fail and throw DbException, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

• The database handle has been invalidated because a replication election unrolled a committed transaction.

• The operation was blocked by client/master synchronization.

• An invalid flag value or parameter was specified.

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 DbEnv::set_msgfile method for more information), or passed to an application callback function (see the DbEnv::set_msgcall method for more information).

The Db::stat_print method may not be called before the Db::open method is called.

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.

• The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
  DB_FAST_STAT
  • 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.
  DB_STAT_ALL
  • Display all available information.