m4_comment([$Id: db_set_re_source.so,v 10.42 2004/09/28 15:04:19 bostic Exp $])

define(M4PAGELOCAL, [dbh_set_re_source, dbh_get_re_source])
include(m4/m4.seealso)

m4_pf_header(m4_ref(dbh_set_re_source),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_re_source(DB *db, char *source);
m4_blank
int
DB-__GT__get_re_source(DB *db, const char **sourcep);

])
ifelse(M4API, CXX_API, [dnl
int
Db::set_re_source(char *source);
m4_blank
int
Db::get_re_source(const char **sourcep);

]))

m4_p([dnl
Set the underlying source file for the Recno access method.  The purpose
of the m4_arg(source) value is to provide fast access and modification
to databases that are normally stored as flat text files.])

m4_p([dnl
The m4_arg(source) parameter specifies an underlying flat text database
file that is read to initialize a transient record number index.  In
the case of variable length records, the records are separated, as
specified by m4_ref(dbh_set_re_delim).  For example, standard UNIX byte
stream files can be interpreted as a sequence of variable length records
separated by m4_htmlquote(newline) characters.])

m4_p([dnl
In addition, when cached data would normally be written back to the
underlying database file (for example, the m4_ref(dbh_close) or
m4_ref(dbh_sync) methods are called), the in-memory copy of the database
will be written back to the m4_arg(source) file.])

m4_p([dnl
By default, the backing source file is read lazily; that is, records
are not read from the file until they are requested by the application.
m4_bold([dnl
If multiple processes (not threads) are accessing a Recno database
concurrently, and are either inserting or deleting records, the backing
source file must be read in its entirety before more than a single
process accesses the database, and only that process should specify the
backing source file as part of the m4_ref(dbh_open) call.  See the
m4_ref(DB_SNAPSHOT) flag for more information.])])

m4_p([dnl
m4_bold([dnl
Reading and writing the backing source file specified by m4_arg(source)
cannot be transaction-protected because it involves filesystem
operations that are not part of the Db transaction methodology.]) For
this reason, if a temporary database is used to hold the records, it is
possible to lose the contents of the m4_arg(source) file, for
example, if the system crashes at the right instant.  If a file is used
to hold the database, normal database recovery on that file can be used
to prevent information loss, although it is still possible that the
contents of m4_arg(source) will be lost if the system crashes.])

m4_p([dnl
The m4_arg(source) file must already exist (but may be zero-length) when
m4_ref(dbh_open) is called.])

m4_p([dnl
It is not an error to specify a read-only m4_arg(source) file when
creating a database, nor is it an error to modify the resulting database.
However, any attempt to write the changes to the backing source file using
either the m4_ref(dbh_sync) or m4_refT(dbh_close)s will fail, of course.
Specify the m4_ref(DB_NOSYNC) flag to the m4_refT(dbh_close) to stop it
from attempting to write the changes to the backing file; instead, they
will be silently discarded.])

m4_p([dnl
For all of the previous reasons, the m4_arg(source) field is generally
used to specify databases that are read-only for m4_db applications;
and that are either generated on the fly by software tools or modified
using a different mechanism -- for example, a text editor.])

m4_scope_dbh(dbh_set_re_source)

m4_when_dbopen(dbh_set_re_source, corrupt)

m4_return(dbh_set_re_source, std)

m4_parambegin
m4_param_utf8(source, [dnl
The backing flat text database file for a Recno database.])
m4_paramend

m4_err(dbh_set_re_source,
einval, [the method was called after m4_ref(dbh_open) was called])

m4_pf_getter(dbh_get_re_source, source file, sourcep,, reference)

m4_seealso(Db)
m4_page_footer