ug_ch6.htm

db.* (pronounced dee-be star) is an advanced, high performance, small footprint embedded database fo

series of <b>d_reclock</b> and <b>d_setlock</b> calls to avoid
deadlock.*</font></p>
</td>
</tr>
<tr>
<td width="23%" valign="top">
<p><b><font size="2">transaction body</font></b></p>
</td>
<td width="77%" valign="top">
<p><font size="2">Here, a series of function calls to modify the
database are made. If modified pages fill the cache (called a
transaction overflow), then extra cache space is created by writing
modified pages to the log file.</font></p>
</td>
</tr>
<tr>
<td width="23%" valign="top">
<p><b><font size="2">d_trend</font></b></p>
</td>
<td width="77%" valign="top">
<p><font size="2">During this call, the commit is made to the
database. At any point after the <b>d_trbegin</b> and before the
<b>d_trend</b>, updates can be thrown away and locks released by
issuing a <b>d_trabort</b> call. During a <b>d_trend</b>, the
following sequence occurs:</font></p>
<p>1. Modified database pages are written to the transaction log
file<br>
(if transaction logging is enabled).<br>
2. Lock manager is informed of the commit.*<br>
3. The name of the log file is added to the TAF.<br>
4. Changed pages are written to the database from cache. If an
overflow occurred earlier, then changed pages contained only in the
log file are read from it and written to the database.<br>
5. The log file name is deleted from the TAF.<br>
6. Lock manager is informed of the end of the transaction.*<br>
7. All unkept and non-exclusive file locks are freed.</p>
</td>
</tr>
</table>
<font size="1"><br>
<br></font>
<blockquote style="MARGIN-RIGHT: 0px">
<blockquote style="MARGIN-RIGHT: 0px">
<p><font size="1">* This step occurs in a multi-user environment
only.</font></p>
</blockquote>
</blockquote>
<p><font size="2">One log file is maintained for each user. This
file is used within a transaction for storing modified database
pages after the page buffers (cache) have been filled. Thus, there
is effectively no limit to the number of changes that can be made
within a transaction. When the transaction ends, all modified pages
are first written to this file (whether or not an overflow
occurred). The database is then updated.</font></p>
<p>If a transaction is aborted, the modified pages in the page
buffers are cleared.</p>
<p>An indexing technique has been developed to provide fast access
to the changed database pages that are stored in the log file after
a cache overflow has occurred. It utilizes a separate cache for the
management of all database pages on the log file. The size of this
index cache (that is, the number of page buffers) is specified as
an argument to function <b>d_setpages</b> as follows:</p>
<pre>
<font color="#0000FF">d_setpages(dbpgs, ixpgs, task)</font>
</pre>
<p><font size="2">where <i>dbpgs</i> is an integer specifying the
number of pages to be used for the standard database cache and
<i>ixpgs</i> is an integer specifying the number of pages to be
used for the overflow index cache. Both arguments are required on
any call to <b>d_setpages</b>.</font></p>
<p>If your application is prone to large transaction overflows, you
will want a fairly large index cache (for example, 17 pages).
Usually, however, a small number of index pages is all that is
necessary (for example, five pages, the default).</p>
<h2><a name="Recovery" id="Recovery"></a>6.5 Database Recovery</h2>
<p><font size="2">If a program crashes while a transaction is
active (after the <b>d_trbegin</b> but before a transaction end or
<b>d_trend</b> has been issued), the database is guaranteed to be
consistent since it has not been written to. Only the changes made
since the beginning of the transaction are lost. If the program
fails while the modified pages are being written to the log file
(step 1 in section 6.4, above), the same situation exists. However,
after the changes have been written to the log file, if the program
fails while the database is being updated, recovery is possible. If
the program fails while committing the database from the log file,
recovery is required.</font></p>
<h3><a name="External" id="External"></a>6.5.1 External
Recovery</h3>
<p><font size="2">In a system with only one active user (one-user
mode, or multi-user mode with only one active user), recovery is
facilitated by the TAF. If this one user crashes after the log file
name has been written to the TAF (step 3 in section 6.4, above),
but before it has been removed (step 5), then the assumption is
made that the database needs recovering. The TAF is checked the
next time a database is opened. If one or more log file names are
present in the TAF, they are all recovered by the first application
to use this TAF during the <b>d_open</b> call.</font></p>
<h3><a name="Automatic" id="Automatic"></a>6.5.2 Automatic
Recovery</h3>
<p><font size="2">In multi-user shared mode, automatic recovery is
accomplished through cooperation between the transaction processing
functions and the lock manager. The lock manager, which runs as an
independent process, is given the name of the log file when the
update is initiated (referred to as the transaction commit point,
step 2 in section 6.4, above) and is notified when the update is
complete (step 6). The recovery automatically occurs when the lock
manager determines that a process performing a transaction commit
has abnormally terminated. When failed processes that were not
doing a transaction commit are detected by the lock manager, the
lock manager simply releases the locks held by the failed
process.</font></p>
<p>The recovery will occur automatically when the lock manager
receives an open or lock request from another active process using
the same TAF. The lock manager will transfer responsibility for the
completion of the failed transaction to the process requesting the
open or lock. The read locks held by the failed process are freed,
but write locks are held until the transaction has recovered.</p>
<p>Upon successful completion of the commit, the lock manager is
informed and the log file name is removed from the TAF. If both the
committing process and the lock manager fail, all
<b><i>db.*</i></b> processes on the system should be shut down.
When the lock manager is restarted, the first database process to
open a database will check the TAF and perform an external recovery
on any listed transaction log files. The lock manager will delay
all other database processes for the database families using that
TAF until the recovery is complete.</p>
<p>Both the log file and the TAF need to be accessible by all
database tasks. Moreover, all the log files for the users of each
TAF need to be in the same physical directory. The path and names
of these files can be established through use of functions
<b>d_dblog</b> and <b>d_dbtaf</b>, or through environment variables
DBLOG and DBTAF, or with the <b>db.star.ini</b> file (see section
6.2, above). All users of all databases need to have read/write
access to all database files. It is possible for an application
using one database to do recovery for a completely different
database, but only when both databases are using the same TAF. It
is recommended that each database family use a different TAF.</p>
<p>Whenever <b><i>db.*</i></b> initiates a recovery operation, the
error reporter is called with the message "recovery about to
occur." The purpose of this function is simply to inform the user
that a recovery is about to take place. You will probably wish to
tailor the error reporting for your particular application
requirements through <b>d_set_dberr</b>. S_RECOVERY is probably one
of the return codes that you will want to "ignore" in your error
reporter.</p>
<h2><a name="Logging" id="Logging"></a>6.6 Archive Logging</h2>
<p><font size="2">A system-wide transaction archive log can be
supported through user-defined functions, which can be called
automatically by the <b><i>db.*</i></b> runtime system. In the rare
event that automatic recovery is not possible, the transaction
identifier for the incomplete transaction will be known by the lock
manager, and a user-initiated database restore can be performed.
This would involve reloading the database from the last complete
backup and using a utility to reapply the changes recorded on the
archive log, up to but not including the last
transaction.</font></p>
<p><font size="2">Module <b>trlog.c</b> contains complete
information, along with the skeletal function declarations
necessary for implementing archive logging.</font></p>
<p><font size="2">The user-defined functions are needed because of
the diversity of devices that could be used for storing the archive
data (for example, cartridge tapes, floppies, files, nine-track
tapes, write-once laser disks, etc.). Access to these devices
cannot be accommodated through any standard techniques.</font></p>
<p><font size="2">However, the performance cost incurred by
maintaining an archive log, in addition to automatic transaction
logging, would almost always be much greater than the benefits of
the additional level of recoverability. Keeping regular backups of
the database files is the best method for protecting the database
beyond the automatic recovery capability previously
described.</font></p>
<p>&nbsp;<a href="UG_Ch7.htm">Next Page</a></p>
</body>
</html>