← Back to branch summary

~ubuntu-branches/ubuntu/precise/rpm/precise-proposed

« back to all changes in this revision

Viewing changes to db/docs/api_c/db_set_re_source.html

  • Committer: Bazaar Package Importer
  • Author(s): Michael Vogt
  • Date: 2009-06-25 18:57:20 UTC
  • mfrom: (1.1.5 upstream) (4.1.2 sid)
  • Revision ID: james.westby@ubuntu.com-20090625185720-617sjskgtgmf09vf
Tags: 4.7.0-7ubuntu1
* Merge from debian unstable, remaining changes:
  - change build depends from libdwarf-dev -> libdw-dev
    (libdwarf-dev is in universe)

Show diffs side-by-side

added added

removed removed

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