260 lines
9.9 KiB
Plaintext
260 lines
9.9 KiB
Plaintext
m4_comment([$Id: db_stat.so,v 10.95 2007/10/24 16:06:06 bostic Exp $])
|
|
|
|
define(M4PAGELOCAL, [dbh_stat, dbh_stat_print, DB_FAST_STAT])
|
|
include(m4/m4.seealso)
|
|
|
|
m4_pf_header(m4_ref(dbh_stat),
|
|
ifelse(M4API, C_API, [dnl
|
|
int
|
|
DB-__GT__stat(DB *db, DB_TXN *txnid, void *sp, u_int32_t flags);
|
|
m4_blank
|
|
int
|
|
DB-__GT__stat_print(DB *db, u_int32_t flags);
|
|
])
|
|
ifelse(M4API, CXX_API, [dnl
|
|
int
|
|
Db::stat(DbTxn *txnid, void *sp, u_int32_t flags);
|
|
m4_blank
|
|
int
|
|
Db::stat_print(u_int32_t flags);
|
|
]))
|
|
|
|
m4_p([dnl
|
|
The m4_refT(dbh_stat) creates a statistical structure and copies a
|
|
pointer to it into user-specified memory locations. Specifically, if
|
|
m4_arg(sp) is non-NULL, a pointer to the statistics for the database are
|
|
copied into the memory location to which it refers.])
|
|
|
|
m4_parambegin
|
|
m4_param(flags, [dnl
|
|
m4_sf_zmust(1)
|
|
|
|
m4_tagbegin
|
|
m4_tag(m4_idef(DB_FAST_STAT), [dnl
|
|
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.])
|
|
|
|
m4_tag(m4_idef(DB_READ_COMMITTED), [dnl
|
|
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.])
|
|
|
|
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
|
|
Database items read during a transactional call will have degree 1
|
|
isolation, including modified but not yet committed data. Silently
|
|
ignored if the m4_ref(DB_READ_UNCOMMITTED) flag was not specified when
|
|
the underlying database was opened.]) m4_tagend])
|
|
|
|
m4_param_txn(dbh_stat)
|
|
m4_paramend
|
|
|
|
m4_alloc([Statistical structures])
|
|
|
|
m4_p([dnl
|
|
If the m4_ref(DB_FAST_STAT) flag has not been specified, the
|
|
m4_refT(dbh_stat) 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.])
|
|
|
|
m4_p([dnl
|
|
In the presence of multiple threads or processes accessing an active
|
|
database, the information returned by m4_ref(dbh_stat) may be out-of-date.])
|
|
|
|
m4_p([dnl
|
|
If the database was not opened read-only and the m4_ref(DB_FAST_STAT)
|
|
flag was not specified, the cached key and record numbers will be
|
|
updated after the statistical information has been gathered.])
|
|
|
|
m4_when(dbh_stat, before, dbh_open)
|
|
|
|
m4_return(dbh_stat, std)
|
|
|
|
m4_section([Hash Statistics])
|
|
m4_p([dnl
|
|
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:])
|
|
|
|
m4_tagbegin
|
|
m4_field(u_int32_t, hash_magic,
|
|
[Magic number that identifies the file as a Hash file. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, hash_version,
|
|
[The version of the Hash database. Returned if m4_ref(DB_FAST_STAT) is
|
|
set.])
|
|
m4_field(u_int32_t, hash_nkeys,
|
|
[The number of unique keys in the database. If m4_ref(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
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, hash_ndata,
|
|
[The number of key/data pairs in the database. If m4_ref(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
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, hash_pagecnt,
|
|
[The number of pages in the database. Returned if m4_ref(DB_FAST_STAT)
|
|
is set.])
|
|
m4_field(u_int32_t, hash_pagesize,
|
|
[The underlying database page (and bucket) size, in bytes. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, hash_ffactor,
|
|
[The desired fill factor (number of items per bucket) specified at
|
|
database-creation time. Returned if m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, hash_buckets,
|
|
[The number of hash buckets. Returned if m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, hash_free,
|
|
[The number of pages on the free list.])
|
|
m4_field(u_int32_t, hash_bfree,
|
|
[The number of bytes free on bucket pages.])
|
|
m4_field(u_int32_t, hash_bigpages,
|
|
[The number of big key/data pages.])
|
|
m4_field(u_int32_t, hash_big_bfree,
|
|
[The number of bytes free on big item pages.])
|
|
m4_field(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).])
|
|
m4_field(u_int32_t, hash_ovfl_free,
|
|
[The number of bytes free on overflow pages.])
|
|
m4_field(u_int32_t, hash_dup,
|
|
[The number of duplicate pages.])
|
|
m4_field(u_int32_t, hash_dup_free,
|
|
[The number of bytes free on duplicate pages.])
|
|
m4_tagend
|
|
|
|
m4_section([Btree and Recno Statistics])
|
|
m4_p([dnl
|
|
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:])
|
|
|
|
m4_tagbegin
|
|
m4_field(u_int32_t, bt_magic,
|
|
[Magic number that identifies the file as a Btree database. Returned
|
|
if m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, bt_version,
|
|
[The version of the Btree database. Returned if m4_ref(DB_FAST_STAT)
|
|
is set.])
|
|
m4_field(u_int32_t, bt_nkeys,
|
|
[For the Btree Access Method, the number of keys in the database. If
|
|
the m4_ref(DB_FAST_STAT) flag is not specified or the database was
|
|
configured to support record numbers (see m4_ref(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.
|
|
m4_p([dnl
|
|
For the Recno Access Method, the number of records in the database. If
|
|
the database was configured with mutable record numbers (see
|
|
m4_ref(DB_RENUMBER)), the count will be exact. Otherwise, if the
|
|
m4_ref(DB_FAST_STAT) flag is specified the count will be exact but will
|
|
include deleted and implicitly created records; if the
|
|
m4_ref(DB_FAST_STAT) flag is not specified, the count will be exact and
|
|
will not include deleted or implicitly created records.])
|
|
m4_p([dnl
|
|
Returned if m4_ref(DB_FAST_STAT) is set.])])
|
|
m4_field(u_int32_t, bt_ndata, [dnl
|
|
For the Btree Access Method, the number of key/data pairs in the
|
|
database. If the m4_ref(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.
|
|
m4_p([dnl
|
|
For the Recno Access Method, the number of records in the database. If
|
|
the database was configured with mutable record numbers (see
|
|
m4_ref(DB_RENUMBER)), the count will be exact. Otherwise, if the
|
|
m4_ref(DB_FAST_STAT) flag is specified the count will be exact but will
|
|
include deleted and implicitly created records; if the
|
|
m4_ref(DB_FAST_STAT) flag is not specified, the count will be exact and
|
|
will not include deleted or implicitly created records.])
|
|
m4_p([dnl
|
|
Returned if m4_ref(DB_FAST_STAT) is set.])])
|
|
m4_field(u_int32_t, bt_pagecnt,
|
|
[The number of pages in the database. Returned if m4_ref(DB_FAST_STAT)
|
|
is set.])
|
|
m4_field(u_int32_t, bt_pagesize,
|
|
[The underlying database page size, in bytes. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, bt_minkey,
|
|
[The minimum keys per page. Returned if m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, bt_re_len,
|
|
[The length of fixed-length records. Returned if m4_ref(DB_FAST_STAT)
|
|
is set.])
|
|
m4_field(u_int32_t, bt_re_pad,
|
|
[The padding byte value for fixed-length records. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, bt_levels,
|
|
[Number of levels in the database.])
|
|
m4_field(u_int32_t, bt_int_pg,
|
|
[Number of database internal pages.])
|
|
m4_field(u_int32_t, bt_leaf_pg,
|
|
[Number of database leaf pages.])
|
|
m4_field(u_int32_t, bt_dup_pg,
|
|
[Number of database duplicate pages.])
|
|
m4_field(u_int32_t, bt_over_pg,
|
|
[Number of database overflow pages.])
|
|
m4_field(u_int32_t, bt_empty_pg,
|
|
[Number of empty database pages.])
|
|
m4_field(u_int32_t, bt_free,
|
|
[Number of pages on the free list.])
|
|
m4_field(u_int32_t, bt_int_pgfree,
|
|
[Number of bytes free in database internal pages.])
|
|
m4_field(u_int32_t, bt_leaf_pgfree,
|
|
[Number of bytes free in database leaf pages.])
|
|
m4_field(u_int32_t, bt_dup_pgfree,
|
|
[Number of bytes free in database duplicate pages.])
|
|
m4_field(u_int32_t, bt_over_pgfree,
|
|
[Number of bytes free in database overflow pages.])
|
|
m4_tagend
|
|
|
|
m4_section([Queue Statistics])
|
|
m4_p([dnl
|
|
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:])
|
|
|
|
m4_tagbegin
|
|
m4_field(u_int32_t, qs_magic,
|
|
[Magic number that identifies the file as a Queue file. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, qs_version,
|
|
[The version of the Queue file type. Returned if m4_ref(DB_FAST_STAT)
|
|
is set.])
|
|
m4_field(u_int32_t, qs_nkeys,
|
|
[The number of records in the database. If m4_ref(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
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, qs_ndata,
|
|
[The number of records in the database. If m4_ref(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
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, qs_pagesize,
|
|
[Underlying database page size, in bytes. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, qs_extentsize,
|
|
[Underlying database extent size, in pages. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, qs_pages,
|
|
[Number of pages in the database.])
|
|
m4_field(u_int32_t, qs_re_len,
|
|
[The length of the records. Returned if m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, qs_re_pad,
|
|
[The padding byte value for the records. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, qs_pgfree,
|
|
[Number of bytes free in database pages.])
|
|
m4_field(u_int32_t, qs_first_recno,
|
|
[First undeleted record in the database. Returned if
|
|
m4_ref(DB_FAST_STAT) is set.])
|
|
m4_field(u_int32_t, qs_cur_recno,
|
|
[Next available record number. Returned if m4_ref(DB_FAST_STAT) is set.])
|
|
m4_tagend
|
|
|
|
m4_err(dbh_stat, rephandle, replockout, einval)
|
|
|
|
m4_stat_print(dbh_stat_print, database, dbh_stat)
|
|
|
|
m4_seealso(Db)
|
|
m4_page_footer
|