← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/api_cxx/db_set_re_source.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdb/docs/api_cxx/db_set_re_source.html
1
 
<!--$Id$-->
2
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB: Db::set_re_source</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<a name="2"><!--meow--></a>
13
 
<table width="100%"><tr valign=top>
14
 
<td>
15
 
<h1>Db::set_re_source</h1>
16
 
</td>
17
 
<td align=right>
18
 
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
19
 
</td></tr></table>
20
 
<hr size=1 noshade>
21
 
<tt>
22
 
<h3><pre>
23
 
#include &lt;db_cxx.h&gt;
24
 
<p>
25
 
int
26
 
Db::set_re_source(char *re_source);
27
 
</pre></h3>
28
 
<h1>Description</h1>
29
 
<p>Set the underlying source file for the Recno access method.  The purpose
30
 
of the <b>re_source</b> value is to provide fast access and modification
31
 
to databases that are normally stored as flat text files.
32
 
<p>If the <b>re_source</b> field is set, it specifies an underlying flat
33
 
text database file that is read to initialize a transient record number
34
 
index.  In the case of variable length records, the records are
35
 
separated, as specified by <a href="../api_cxx/db_set_re_delim.html">Db::set_re_delim</a>.  For example,
36
 
standard UNIX byte stream files can be interpreted as a sequence of
37
 
variable length records separated by &lt;newline&gt; characters.
38
 
<p>In addition, when cached data would normally be written back to the
39
 
underlying database file (for example, the <a href="../api_cxx/db_close.html">Db::close</a> or
40
 
<a href="../api_cxx/db_sync.html">Db::sync</a> methods are called), the in-memory copy of the database
41
 
will be written back to the <b>re_source</b> file.
42
 
<p>By default, the backing source file is read lazily; that is, records
43
 
are not read from the file until they are requested by the application.
44
 
<b>If multiple processes (not threads) are accessing a Recno database
45
 
concurrently, and are either inserting or deleting records, the backing
46
 
source file must be read in its entirety before more than a single
47
 
process accesses the database, and only that process should specify the
48
 
backing source file as part of the <a href="../api_cxx/db_open.html">Db::open</a> call.  See the
49
 
<a href="../api_cxx/db_set_flags.html#DB_SNAPSHOT">DB_SNAPSHOT</a> flag for more information.</b>
50
 
<p><b>Reading and writing the backing source file specified by <b>re_source</b>
51
 
cannot be transaction-protected because it involves filesystem
52
 
operations that are not part of the Db transaction methodology.</b> For
53
 
this reason, if a temporary database is used to hold the records, it is
54
 
possible to lose the contents of the <b>re_source</b> file, for
55
 
example, if the system crashes at the right instant.  If a file is used
56
 
to hold the database, normal database recovery on that file can be used
57
 
to prevent information loss, although it is still possible that the
58
 
contents of <b>re_source</b> will be lost if the system crashes.
59
 
<p>The <b>re_source</b> file must already exist (but may be zero-length) when
60
 
<a href="../api_cxx/db_open.html">Db::open</a> is called.
61
 
<p>It is not an error to specify a read-only <b>re_source</b> file when
62
 
creating a database, nor is it an error to modify the resulting database.
63
 
However, any attempt to write the changes to the backing source file using
64
 
either the <a href="../api_cxx/db_sync.html">Db::sync</a> or <a href="../api_cxx/db_close.html">Db::close</a> methods will fail, of course.
65
 
Specify the <a href="../api_cxx/db_close.html#DB_NOSYNC">DB_NOSYNC</a> flag to the <a href="../api_cxx/db_close.html">Db::close</a> method to stop it
66
 
from attempting to write the changes to the backing file; instead, they
67
 
will be silently discarded.
68
 
<p>For all of the previous reasons, the <b>re_source</b> field is generally
69
 
used to specify databases that are read-only for Berkeley DB applications;
70
 
and that are either generated on the fly by software tools or modified
71
 
using a different mechanism -- for example, a text editor.
72
 
<p>The Db::set_re_source method configures operations performed using the specified
73
 
<a href="../api_cxx/db_class.html">Db</a> handle, not all operations performed on the underlying
74
 
database.
75
 
<p>The Db::set_re_source interface may not be called after the <a href="../api_cxx/db_open.html">Db::open</a>
76
 
interface is called.
77
 
If the database already exists when
78
 
<a href="../api_cxx/db_open.html">Db::open</a> is called, the information specified to Db::set_re_source must
79
 
be the same as that historically used to create the database or
80
 
corruption can occur.
81
 
<p>The Db::set_re_source method either returns a non-zero error value or throws an exception that
82
 
encapsulates a non-zero error value on failure, and returns 0 on success.
83
 
<h1>Errors</h1>
84
 
<p>The Db::set_re_source method may fail and throw an exception or return a non-zero error for the following conditions:
85
 
<p><dl compact>
86
 
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
87
 
<p>Called after <a href="../api_cxx/db_open.html">Db::open</a> was called.
88
 
</dl>
89
 
<p>The Db::set_re_source method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods.
90
 
If a catastrophic error has occurred, the Db::set_re_source method may fail and
91
 
either return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> or throw a
92
 
<a href="../api_cxx/runrec_class.html">DbRunRecoveryException</a>,
93
 
in which case all subsequent Berkeley DB calls will fail in the same way.
94
 
<h1>Class</h1>
95
 
<a href="../api_cxx/db_class.html">Db</a>
96
 
<h1>See Also</h1>
97
 
<a href="../api_cxx/db_list.html">Databases and Related Methods</a>
98
 
</tt>
99
 
<table width="100%"><tr><td><br></td><td align=right>
100
 
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
101
 
</td></tr></table>
102
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
103
 
</body>
104
 
</html>