m4_comment([$Id: logrec.so,v 10.31 2004/08/05 14:16:56 bostic Exp $])

m4_ref_title(Access Methods,
    Logical record numbers,
    logical @record numbers,
    am_conf/select, am_conf/pagesize)

m4_p([dnl
The m4_db Btree, Queue and Recno access methods can operate on logical
record numbers.  Record numbers are 1-based, not 0-based, that is, the
first record in a database is record number 1.])

m4_p([dnl
In all cases for the Queue and Recno access methods, and when calling
the Btree access method using the m4_ref(dbh_get) and m4_refT(dbc_get)s
with the m4_ref(DB_SET_RECNO) flag specified, the m4_arg(data) field of
the key m4_ref(Dbt) must be a pointer to a memory location of type
m4_arg(db_recno_t), as typedef'd in the standard m4_db include file.
The m4_arg(size) field of the key m4_ref(Dbt) should be the size of that
type (for example, "sizeof(db_recno_t)" in the C programming language).
The m4_arg(db_recno_t) type is a 32-bit unsigned type, which limits the
number of logical records in a Queue or Recno database, and the maximum
logical record which may be directly retrieved from a Btree database,
to 4,294,967,295.])

m4_p([dnl
Record numbers in Recno databases can be configured to run in either
mutable or fixed mode: mutable, where logical record numbers change as
records are deleted or inserted, and fixed, where record numbers never
change regardless of the database operation.  Record numbers in Queue
databases are always fixed, and never change regardless of the database
operation.  Record numbers in Btree databases are always mutable, and
as records are deleted or inserted, the logical record number for other
records in the database can change.  See
m4_link(M4RELDIR/ref/am_conf/renumber, Logically renumbering records)
for more information.])

m4_p([dnl
When appending new data items into Queue databases, record numbers wrap
around.  When the tail of the queue reaches the maximum record number,
the next record appended will be given record number 1.  If the head of
the queue ever catches up to the tail of the queue, m4_db will return
the system error EFBIG.  Record numbers do not wrap around when appending
new data items into Recno databases.])

m4_p([dnl
Configuring Btree databases to support record numbers can severely limit
the throughput of applications with multiple concurrent threads writing
the database, because locations used to store record counts often become
hot spots that many different threads all need to update.  In the case
of a Btree supporting duplicate data items, the logical record number
refers to a key and all of its data items, as duplicate data items are
not individually numbered.])

m4_p([dnl
The following is an example function that reads records from standard
input and stores them into a Recno database.  The function then uses a
cursor to step through the database and display the stored records.])

include(ref/am_conf/logrec.cs)

m4_page_footer