Edit File - File Manager

Edit File: db_set_re_source.html

<html>
<head>
<title>Berkeley DB: Db::set_re_source</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td>
Db::set_re_source
</td>
<td align=right>
<a href="../../db4-devel-4.7.25/api_cxx/api_core.html"><img src="../../db4-devel-4.7.25/images/api.gif" alt="API"></a>
<a href="../../db4-devel-4.7.25/ref/toc.html"><img src="../../db4-devel-4.7.25/images/ref.gif" alt="Ref"></a></td>
</tr></table>
<hr size=1 noshade>
<tt>
<pre>
#include &lt;db_cxx.h&gt;

int
Db::set_re_source(char *source);

int
Db::get_re_source(const char **sourcep);
</pre>
<hr size=1 noshade>
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 <a href="../../db4-devel-4.7.25/api_cxx/db_set_re_delim.html">Db::set_re_delim</a>. For example, standard UNIX byte
stream files can be interpreted as a sequence of variable length records
separated by &lt;newline&gt; characters.
In addition, when cached data would normally be written back to the
underlying database file (for example, the <a href="../../db4-devel-4.7.25/api_cxx/db_close.html">Db::close</a> or
<a href="../../db4-devel-4.7.25/api_cxx/db_sync.html">Db::sync</a> 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 <a href="../../db4-devel-4.7.25/api_cxx/db_open.html">Db::open</a> call. See the
<a href="../../db4-devel-4.7.25/api_cxx/db_set_flags.html#DB_SNAPSHOT">DB_SNAPSHOT</a> 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
<a href="../../db4-devel-4.7.25/api_cxx/db_open.html">Db::open</a> 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 <a href="../../db4-devel-4.7.25/api_cxx/db_sync.html">Db::sync</a> or <a href="../../db4-devel-4.7.25/api_cxx/db_close.html">Db::close</a> methods will fail, of course.
Specify the <a href="../../db4-devel-4.7.25/api_cxx/db_close.html#DB_NOSYNC">DB_NOSYNC</a> flag to the <a href="../../db4-devel-4.7.25/api_cxx/db_close.html">Db::close</a> 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
<a href="../../db4-devel-4.7.25/api_cxx/db_class.html">Db</a> handle, not all operations performed on the underlying
database.
The Db::set_re_source method may not be called after the <a href="../../db4-devel-4.7.25/api_cxx/db_open.html">Db::open</a> method is called.
If the database already exists when
<a href="../../db4-devel-4.7.25/api_cxx/db_open.html">Db::open</a> 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<ul compact><li>The backing flat text database file for a Recno database.</ul>
When using a Unicode build on Windows (the default), 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
<a href="../../db4-devel-4.7.25/api_cxx/except_class.html">DbException</a>,
encapsulating one of the following non-zero errors, or return one of
the following non-zero errors:
 
EINVAL<ul compact><li>If the method was called after <a href="../../db4-devel-4.7.25/api_cxx/db_open.html">Db::open</a> was called; or if an
invalid flag value or parameter was specified.</ul>
 
<hr size=1 noshade>
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.
<hr size=1 noshade>
 Class
<a href="../../db4-devel-4.7.25/api_cxx/db_class.html">Db</a>
 See Also
<a href="../../db4-devel-4.7.25/api_cxx/db_list.html">Databases and Related Methods</a>
</tt>
<table width="100%"><tr><td> </td><td align=right>
<a href="../../db4-devel-4.7.25/api_cxx/api_core.html"><img src="../../db4-devel-4.7.25/images/api.gif" alt="API"></a><a href="../../db4-devel-4.7.25/ref/toc.html"><img src="../../db4-devel-4.7.25/images/ref.gif" alt="Ref"></a>
</td></tr></table>
Copyright (c) 1996,2008 Oracle. All rights reserved.
</body>
</html>

Back to File Manager