1<!--$Id: re_source.so,v 10.16 2003/10/18 19:15:55 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Flat-text backing files</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></b></td> 14<td align=right><a href="/am_conf/extentsize.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/am_conf/renumber.html"><img src="/images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Flat-text backing files</b></p> 17<p>It is possible to back any Recno database (either fixed or variable 18length) with a flat-text source file. This provides fast read (and 19potentially write) access to databases that are normally created and 20stored as flat-text files. The backing source file may be specified by 21calling the <a href="/api_c/db_set_re_source.html">DB->set_re_source</a> method.</p> 22<p>The backing source file will be read to initialize the database. In the 23case of variable length records, the records are assumed to be separated 24as described for the <a href="/api_c/db_set_re_delim.html">DB->set_re_delim</a> method. For example, standard 25UNIX byte stream files can be interpreted as a sequence of variable 26length records separated by ASCII newline characters. This is the 27default.</p> 28<p>When cached data would normally be written back to the underlying 29database file (for example, when the <a href="/api_c/db_close.html">DB->close</a> or 30<a href="/api_c/db_sync.html">DB->sync</a> methods are called), the in-memory copy of the database will 31be written back to the backing source file.</p> 32<p>The backing source file must already exist (but may be zero-length) when 33<a href="/api_c/db_open.html">DB->open</a> is called. By default, the backing source file is read 34lazily, that is, records are not read from the backing source file until 35they are requested by the application. If multiple processes (not 36threads) are accessing a Recno database concurrently and either 37inserting or deleting records, the backing source file must be read in 38its entirety before more than a single process accesses the database, 39and only that process should specify the backing source file as part of 40the <a href="/api_c/db_open.html">DB->open</a> call. This can be accomplished by calling the 41<a href="/api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="/api_c/db_set_flags.html#DB_SNAPSHOT">DB_SNAPSHOT</a> flag.</p> 42<p>Reading and writing the backing source file cannot be transactionally 43protected because it involves filesystem operations that are not part of 44the Berkeley DB transaction methodology. For this reason, if a temporary 45database is used to hold the records (a NULL was specified as the file 46argument to <a href="/api_c/db_open.html">DB->open</a>), <b>it is possible to lose the 47contents of the backing source file if the system crashes at the right 48instant</b>. If a permanent file is used to hold the database (a filename 49was specified as the file argument to <a href="/api_c/db_open.html">DB->open</a>), normal database 50recovery on that file can be used to prevent information loss. It is 51still possible that the contents of the backing source file itself will 52be corrupted or lost if the system crashes.</p> 53<p>For all of the above reasons, the backing source file is generally used 54to specify databases that are read-only for Berkeley DB applications, and that 55are either generated on the fly by software tools, or modified using a 56different mechanism such as a text editor.</p> 57<table width="100%"><tr><td><br></td><td align=right><a href="/am_conf/extentsize.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/am_conf/renumber.html"><img src="/images/next.gif" alt="Next"></a> 58</td></tr></table> 59<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 60</body> 61</html> 62