103 lines
3.8 KiB
Plaintext
103 lines
3.8 KiB
Plaintext
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
|