Import BSDDB 4.7.25 (as of svn r89086)

docs_src/db/db_set_re_source.so

@@ -0,0 +1,102 @@
+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