/usr/share/doc/libxbase64-doc/html/xbc8.htm

<!DOCTYPE HTML PUBLIC>
<HTML>
<TITLE>Xbase DBMS Chapter 8</TITLE>
<BODY BGCOLOR=#FFFFFF>
<H1><p align="center">Record and File Locking</p></H1>
<p align="center">Chapter Updated 2/1/99</p><hr>

<h3>Locking Overview</h3>

Xbase DBMS supports multi-user processing through file and record locks.
Record locking restricts multiple cooperating programs from simultaneously 
accessing the same data and corrupting it. Without record and file locking 
in a multi-user environment, simultaneous access to the data and index files
can cause the files to become inaccurate and unusable.<br><br>

Record locking is on by default in the Xbase DBMS library. To disable it,
comment out the XB_LOCKING_ON option in the <em>options.h</em> file in the 
xbase/src directory.<br><br>

The current Xbase DBMS record locking does not co-exist with other Xbase 
products and there is not yet support for locking in a DOS/Windows environment.
The locking functions do work correctly for a Xbase DBMS only configuration.
Future version of Xbase DBMS will have enhanced locking features for 
co-existing with other Xbase products and also include DOS/Windows support.
<br><br>

The locking methods return either XB_LOCK_FAILED or XB_NO_ERROR.  If they return
XB_LOCK_FAILED the actual reason can be found in the global variable 
<em>errno</em> or function <em>perror()</em> can be executed to view the
results.
<br><br>

The errno field may contain one of the following values if the lock was not
successful.<br><br>
<TABLE BORDER>
<TR VALIGN="BASELINE">
<TR><TH ALIGN="LEFT">Error Code<TD>Description
<TR><TH ALIGN="LEFT">EBADF<TD>Invalid file descriptor
<TR><TH ALIGN="LEFT">EINVAL<TD>Invalid lock information or file does not support locks
<TR><TH ALIGN="LEFT">EACCESS<BR>EAGAIN<TD>Lock can not be set because it is blocked by an existing lock on the file.
<TR><TH ALIGN="LEFT">ENOLCK<TD>The system is out of lock resources, too many file locks in place.
<TR><TH ALIGN="LEFT">EDEADLK<TD>Deadlock condition
<TR><TH ALIGN="LEFT">EINTR<TD>Process was interrupted by a signal while it was waiting
</TABLE>
<br><br>
<h3>Types of Locks</h3>

<li><em>Write or Exclusive Locks</em> provide exclusive access to a 
particular file location. No other process can lock the same location.<br><br>

<li><em>Read or Shared Locks</em> prohibit any process from requesting a write 
lock on a specified part of the file.  Other processes can request 
simultaneous read locks.<br><br><br>

<h3>DBF File Locking Techniques</h3>

Xbase DBMS uses the following protocol for DBF file and record locking:
<br><br>

To lock a record - the first byte of the record is locked.<br>
To lock the file - the header bytes of the file are locked.<br><br>

When a record is being appended to the file, the header bytes are locked.<br>
When a record is being updated, the header bytes and the specific record are
locked.<br><br>
This locking protocol is probably not compatable with other Xbase type products.
However, Xbase can be safely used for multi-user access when it is not 
simultaneously updating DBF or NDX files while other products/programs are.
<br><br><br>

<h3>NDX File Locking Techniques</h3>

Xbase DBMS locks indexes by locking the first 512 bytes 
of the index file.
The entire index is locked because any updates to the index potentially
can modify significant portions of the index tree.
<br><br><br>

<h3>DBT File Locking Techniques</h3>

Xbase DBMS locks memo files by locking the first 4 bytes 
of the memo file. This effectively locks the entire file.  The entire file
is locked because any updates to the free block chain can significantly
change the structure of the file.
<br><br><br>


<h3>AutoLocking Features</h3>

If XB_LOCKING_ON is set in the <em>options.h</em> file, the locking methods 
execute any appropriate locking logic.  If XB_LOCKING_ON is not set in the 
<em>options.h</em> file, all locking methods return XB_NO_ERROR without 
performing any actual record or file locking.  This enables the application
program to always call locking routines regardless of the XB_LOCKING_ON switch
in the <em>options.h</em> file.
<br><br>
By leaving the autolocking features enabled, the application program does
not need to address record, file or index locking.  All locking is handled
automatically by the Xbase routines.  However, if access to the locking 
routines is required, they are available to the applciation programmer.
<br><br>
When the files are automatically locked by the Xbase routines, the database 
file is locked first, then it locks the indexes in alphabetical order.  To 
avoid deadlock conditions, files and record locks should always be done in 
the same order.  When the files are unlocked, then indexes are unlocked
first, then the database is unlocked.
<br><br>
Auto-locking works well in an on-line transaction based environment.
However, it does not function efficiently in batch mode. If you
will be writing programs which process files in a batch mode, disabling 
auto-lock and locking the entire file at the beginning of the process 
and unlocking the file at the end of the process will significantly
reduce process time.  On a 586-200 class machine, a file with 45000 records
can be read thru in a few seconds with the file locked in batch mode. 
In record-lock mode it takes about six minutes with the same processor. 

<br><br>For processing large files, locking the file instead of locking each
record is far more efficient.  This is how you do it.<br><br>

For reading the file in batch mode:<br>
xbDbf.AutoLockOff();<br>
xbDbf.LockDatabase( F_SETLKW, F_RDLCK, 0L );<br><br>      
For updating the file in batch mode:<br>
xbDbf.AutoLockOff();<br>
xbDbf.LockDatabase( F_SETLKW, F_WRLCK, 0L );<br><br>      
<br> 
<hr><br>
<p><img src="xbase.jpg"><br><hr>
</BODY>
</HTML>
libxbase64-doc 3.1.2-4 / usr / share / doc / libxbase64-doc / html / xbc8.htm
