1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DB->set_re_source()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C API Reference" /> 10 <link rel="up" href="db.html" title="Chapter��2.�� The DB Handle" /> 11 <link rel="prev" href="dbset_re_pad.html" title="DB->set_re_pad()" /> 12 <link rel="next" href="dbstat.html" title="DB->stat()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->set_re_source()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbset_re_pad.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.�� 23 The DB Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dbstat.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="dbset_re_source"></a>DB->set_re_source()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->set_re_source(DB *db, char *source); </pre> 42 <p> 43 Set the underlying source file for the Recno access method. The 44 purpose of the <span class="bold"><strong>source</strong></span> value is to 45 provide fast access and modification to databases that are normally 46 stored as flat text files. 47 </p> 48 <p> 49 The <span class="bold"><strong>source</strong></span> parameter specifies an 50 underlying flat text database file that is read to initialize a 51 transient record number index. In the case of variable length 52 records, the records are separated, as specified by 53 <a class="xref" href="dbset_re_delim.html" title="DB->set_re_delim()">DB->set_re_delim()</a>. For 54 example, standard UNIX byte stream files can be interpreted as a 55 sequence of variable length records separated by <newline> 56 characters. 57 </p> 58 <p> 59 In addition, when cached data would normally be written back to the 60 underlying database file (for example, the 61 <a class="xref" href="dbclose.html" title="DB->close()">DB->close()</a> or 62 <a class="xref" href="dbsync.html" title="DB->sync()">DB->sync()</a> methods are called), 63 the in-memory copy of the database will be written back to the 64 <span class="bold"><strong>source</strong></span> file. 65 </p> 66 <p> 67 By default, the backing source file is read lazily; that is, records 68 are not read from the file until they are requested by the 69 application. <span class="bold"><strong>If multiple processes (not threads) 70 are accessing a Recno database concurrently, and are either inserting 71 or deleting records, the backing source file must be read in its 72 entirety before more than a single process accesses the database, and 73 only that process should specify the backing source file as part of 74 the <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> call. See the 75 <a class="link" href="dbset_flags.html#dbset_flags_DB_SNAPSHOT">DB_SNAPSHOT</a> flag 76 for more information.</strong></span> 77 </p> 78 <p> 79 <span class="bold"><strong>Reading and writing the backing source file 80 specified by <span class="bold"><strong>source</strong></span> cannot be 81 transaction-protected because it involves filesystem operations that 82 are not part of the Db transaction methodology.</strong></span> For this 83 reason, if a temporary database is used to hold the records, it is 84 possible to lose the contents of the <span class="bold"><strong>source</strong></span> file, for example, if the system crashes 85 at the right instant. If a file is used to hold the database, normal 86 database recovery on that file can be used to prevent information 87 loss, although it is still possible that the contents of <span class="bold"><strong>source</strong></span> will be lost if the system crashes. 88 </p> 89 <p> 90 The <span class="bold"><strong>source</strong></span> file must already exist 91 (but may be zero-length) when <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> is called. 92 </p> 93 <p> 94 It is not an error to specify a read-only <span class="bold"><strong>source</strong></span> file when creating a database, nor is it 95 an error to modify the resulting database. However, any attempt to 96 write the changes to the backing source file using either the 97 <a class="xref" href="dbsync.html" title="DB->sync()">DB->sync()</a> or 98 <a class="xref" href="dbclose.html" title="DB->close()">DB->close()</a> methods will fail, 99 of course. Specify the 100 <a class="link" href="dbclose.html#dbclose_DB_NOSYNC">DB_NOSYNC</a> flag to the 101 <a class="xref" href="dbclose.html" title="DB->close()">DB->close()</a> method to 102 stop it from attempting to write the changes to the backing file; 103 instead, they will be silently discarded. 104 </p> 105 <p> 106 For all of the previous reasons, the <span class="bold"><strong>source</strong></span> field is generally used to specify 107 databases that are read-only for Berkeley DB applications; and that 108 are either generated on the fly by software tools or modified using a 109 different mechanism ��� for example, a text editor. 110 </p> 111 <p> 112 The <code class="methodname">DB->set_re_source()</code> method configures operations performed using 113 the specified <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> handle, 114 not all operations performed on the underlying database. 115 </p> 116 <p> 117 The <code class="methodname">DB->set_re_source()</code> method may not be called after the 118 <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> method is called. If 119 the database already exists when 120 <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> is called, the 121 information specified to <code class="methodname">DB->set_re_source()</code> must be the same as that 122 historically used to create the database or corruption can occur. 123 </p> 124 <p> 125 The <code class="methodname">DB->set_re_source()</code> <span> 126 <span> 127 method returns a non-zero error value on failure and 0 on success. 128 </span> 129 130 </span> 131 </p> 132 <div class="sect2" lang="en" xml:lang="en"> 133 <div class="titlepage"> 134 <div> 135 <div> 136 <h3 class="title"><a id="id1650586"></a>Parameters</h3> 137 </div> 138 </div> 139 </div> 140 <div class="sect3" lang="en" xml:lang="en"> 141 <div class="titlepage"> 142 <div> 143 <div> 144 <h4 class="title"><a id="id1650591"></a>source</h4> 145 </div> 146 </div> 147 </div> 148 <p> 149 The backing flat text database file for a Recno database. 150 </p> 151 <p> 152 When using a Unicode build on Windows (the default), the 153 <span class="bold"><strong>source</strong></span> 154 argument will be interpreted as a UTF-8 string, which is equivalent to 155 ASCII for Latin characters. 156 </p> 157 </div> 158 </div> 159 <div class="sect2" lang="en" xml:lang="en"> 160 <div class="titlepage"> 161 <div> 162 <div> 163 <h3 class="title"><a id="id1650744"></a>Errors</h3> 164 </div> 165 </div> 166 </div> 167 <p> 168 The <code class="methodname">DB->set_re_source()</code> <span> 169 <span> 170 method may fail and return one of the following non-zero errors: 171 </span> 172 173 </span> 174 </p> 175 <div class="sect3" lang="en" xml:lang="en"> 176 <div class="titlepage"> 177 <div> 178 <div> 179 <h4 class="title"><a id="id1650760"></a>EINVAL</h4> 180 </div> 181 </div> 182 </div> 183 <p> 184 If the method was called after <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> 185 was called; or if an invalid flag value or parameter was specified. 186 </p> 187 </div> 188 </div> 189 <div class="sect2" lang="en" xml:lang="en"> 190 <div class="titlepage"> 191 <div> 192 <div> 193 <h3 class="title"><a id="id1650761"></a>Class</h3> 194 </div> 195 </div> 196 </div> 197 <p> 198 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 199 </p> 200 </div> 201 <div class="sect2" lang="en" xml:lang="en"> 202 <div class="titlepage"> 203 <div> 204 <div> 205 <h3 class="title"><a id="id1650576"></a>See Also</h3> 206 </div> 207 </div> 208 </div> 209 <p> 210 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 211 </p> 212 </div> 213 </div> 214 <div class="navfooter"> 215 <hr /> 216 <table width="100%" summary="Navigation footer"> 217 <tr> 218 <td width="40%" align="left"><a accesskey="p" href="dbset_re_pad.html">Prev</a>��</td> 219 <td width="20%" align="center"> 220 <a accesskey="u" href="db.html">Up</a> 221 </td> 222 <td width="40%" align="right">��<a accesskey="n" href="dbstat.html">Next</a></td> 223 </tr> 224 <tr> 225 <td width="40%" align="left" valign="top">DB->set_re_pad()��</td> 226 <td width="20%" align="center"> 227 <a accesskey="h" href="index.html">Home</a> 228 </td> 229 <td width="40%" align="right" valign="top">��DB->stat()</td> 230 </tr> 231 </table> 232 </div> 233 </body> 234</html> 235