#include <db_cxx.h>

int
Db::set_re_source(char *source);

int
Db::get_re_source(const char **sourcep);

Description: Db::set_re_source

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

The 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 Db::set_re_delim. For example, standard UNIX byte stream files can be interpreted as a sequence of variable length records separated by <newline> characters.

In addition, when cached data would normally be written back to the underlying database file (for example, the Db::close or Db::sync methods are called), the in-memory copy of the database will be written back to the source file.

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. 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 Db::open call. See the DB_SNAPSHOT flag for more information.

Reading and writing the backing source file specified by 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 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 source will be lost if the system crashes.

The source file must already exist (but may be zero-length) when Db::open is called.

It is not an error to specify a read-only 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 Db::sync or Db::close methods will fail, of course. Specify the DB_NOSYNC flag to the Db::close method to stop it from attempting to write the changes to the backing file; instead, they will be silently discarded.

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

The Db::set_re_source method configures operations performed using the specified Db handle, not all operations performed on the underlying database.

The Db::set_re_source method may not be called after the Db::open method is called. If the database already exists when Db::open is called, the information specified to Db::set_re_source must be the same as that historically used to create the database or corruption can occur.

The Db::set_re_source method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Parameters

source

The backing flat text database file for a Recno database.

On Windows, the source argument will be interpreted as a UTF-8 string, which is equivalent to ASCII for Latin characters.

Errors

The Db::set_re_source method may fail and throw DbException, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

EINVAL

If the method was called after Db::open was called; or if an invalid flag value or parameter was specified.

Description: Db::get_re_source

The Db::get_re_source method returns the source file.

The Db::get_re_source method may be called at any time during the life of the application.

Class

See Also