From daf17154bf13139d9375f48525d19d6aaba08155 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Sat, 2 Aug 2014 08:43:31 +0200 Subject: Imported Upstream version 3.1.2 --- html/xbc18.htm | 261 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100755 html/xbc18.htm (limited to 'html/xbc18.htm') diff --git a/html/xbc18.htm b/html/xbc18.htm new file mode 100755 index 0000000..78d8de6 --- /dev/null +++ b/html/xbc18.htm @@ -0,0 +1,261 @@ + + +Xbase DBMS Chapter 18 + +

Locking Methods

Chapter Updated 2/1/99

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

+ +The errno field may contain one of the following values if the lock was not +successful.

+ + +

Error Code	Description +
EBADF	Invalid file descriptor +
EINVAL	Invalid lock information or file does not support locks +
EACCESS EAGAIN	Lock can not be set because it is blocked by an existing lock on the file. +
ENOLCK	The system is out of lock resources, too many file locks in place. +
EDEADLK	Deadlock condition +
EINTR	Process was interrupted by a signal while it was waiting +

+

+

Types of Locks

+ +

Write or Exclusive Locks provide exclusive access to a +particular file location. No other process can lock the same location.

+ +

Read or Shared Locks prohibit any process from requesting a write +lock on a specified part of the file. Other processes can request +simultaneous read locks.

+ +

DBF File Locking Techniques

+ +Xbase DBMS uses the following protocol for DBF file and record locking: +

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

+ +When a record is being appended to the file, the header bytes are locked.
+When a record is being updated, the header bytes and the specific record are +locked.

+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. +

+ +

NDX File Locking Techniques

+ +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. +

+ +

DBT File Locking Techniques

+ +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. +

+ + +

AutoLocking Features

+ +If XB_LOCKING_ON is set in the options.h file, the locking methods +execute any appropriate locking logic. If XB_LOCKING_ON is not set in the +options.h file, all locking methods return 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 options.h file. +

+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. +

+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. +

+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. + +

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

+ +For reading the file in batch mode:
+xbDbf.AutoLockOff();
+xbDbf.LockDatabase( F_SETLKW, F_RDLCK, 0L );

+For updating the file in batch mode:
+xbDbf.AutoLockOff();
+xbDbf.LockDatabase( F_SETLKW, F_WRLCK, 0L );

+
+

+ +

Method Table

+ + + + +


Method	Description +
xbDbf::AutoLockOn	Turns autolocking on +
xbDbf::AutoLockOff	Turns autolocking off +
xbDbf::ExclusiveLock	Lock file and indexes in exclusive mode +
xbDbf::ExclusiveUnlock	Unlock files and indexes +
xbDbf::LockDatabase	Locks or unlocks a DBF database +
xbNdx::LockIndex	Locks or unlocks an xbNdx index +
xbNdx::LockMemoFile	Locks or unlocks a DBT memo field file +

+ +

Method Descriptions

+ +

Method VOID xbDbf::AutoLockOn( VOID )

+ +This method turns automatic record locking on. Auto record locking is on +by default if XB_LOCKING_ON is set in the options.h file.

+ +

Example Program:

+ +See program loadzips.cpp for an example of +how to use this method. +

+ +

Method VOID xbDbf::AutoLockOff( VOID )

+ +This method turns automatic record locking off. Auto record locking is on +by default if XB_LOCKING_ON is set in the options.h file. +

+Turning auto locking off will result in slightly better execution speeds +but should not be used in multi-user environments when multiple users can +update files simultanteously. If multiple users are accessing a file which +is read only then it is safe to turn off auto-locking for a particular file. +

+Turning autolocking off will disable any index file locking which is +particularly dangerous in a multi-user environment if updates on the files +are permitted. + + +

Example Program:

+ +See program loadzips.cpp for an example of +how to use this method. + +

Method SHORT xbDbf::ExclusiveLock( SHORT WaitOption )

Method SHORT xbDbf::ExclusiveUnlock( VOID )

+ +ExclusiveLock and ExclusiveUnclock will lock the data file, memo file (if applicable) +and any associated indexes in an exclusive mode. They also turn auto-lock +on and off as appropriate.

+ +WaitOption is either:

+

F_SETLK - returns immediately regardless if success or failure
+

F_SETLKW - waits until lock function executes

+ +

Example Program:

+ +See program sample4.cpp for an example of +how to use this method. + +

Method SHORT xbDbf::LockDatabase( SHORT WaitOption, SHORT LockType, LONG LRecNo ) +

+ +This method locks or unlocks an Xbase (.DBF) file which was previously opened.
+
+WaitOption is either:

+

F_SETLK - returns immediately regardless if success or failure
+

F_SETLKW - waits until lock function executes

+ +LockType is one of:

+

F_RDLCK - Perform a Read or Shared Lock
+

F_WRLCK - Perform a Write or Exclusive Lock
+

F_UNLCK - Unlock it

+ +LRecNo is:

+0 - Lock the header section of the file (use this to lock the file)
+1 through n - Lock a particular record

+ + + +

Method Return Codes
Return Code	Description +
XB_INVALID_RECORD	An invalid record given +
XB_LOCK_FAILED	The lock action failed, see errno +
XB_NO_ERROR	The lock was successful +

+ + +

Example Program:

+ +See program loadzips.cpp for an example of +how to use this method. + +

+ +

Method xbShort xbDbf::LockIndex( xbShort WaitOption, xbShort LockType ) +

+ +This method locks or unlocks an Index (.NDX) file which was previously opened.
+
+WaitOption is either:

+

F_SETLK - returns immediately regardless if success or failure
+

F_SETLKW - waits until lock function executes

+ +LockType is one of:

+

F_RDLCK - Perform a Read or Shared Lock
+

F_WRLCK - Perform a Write or Exclusive Lock
+

F_UNLCK - Unlock it

+ + + +

Method Return Codes
Return Code	Description +
XB_LOCK_FAILED	The lock action failed, see errno +
XB_NO_ERROR	The lock was successful +

+ +

Example Program:

+See program loadzips.cpp for an example of +how to use this method. +

+ +

Method xbShort xbDbf::LockMemoFile( xbShort WaitOption, xbShort LockType ) +

+ +This method locks or unlocks a memo (.DBT) file which was previously opened. +It is not necessary for an application to call this method as locking is +handled automatically by other routines.

+ +WaitOption is either:

+

F_SETLK - returns immediately regardless if success or failure
+

F_SETLKW - waits until lock function executes

+ +LockType is one of:

+

F_RDLCK - Perform a Read or Shared Lock
+

F_WRLCK - Perform a Write or Exclusive Lock
+

F_UNLCK - Unlock it

+ + +

Method Return Codes
Return Code	Description +
XB_LOCK_FAILED	The lock action failed, see errno +
XB_NO_ERROR	The lock was successful +

+ + -- cgit v1.2.3