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 CodeDescription
EBADFInvalid file descriptor
EINVALInvalid 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.
ENOLCKThe system is out of lock resources, too many file locks in place.
EDEADLKDeadlock condition
EINTRProcess 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

    MethodDescription
    xbDbf::AutoLockOnTurns autolocking on
    xbDbf::AutoLockOffTurns autolocking off
    xbDbf::ExclusiveLockLock file and indexes in exclusive mode
    xbDbf::ExclusiveUnlockUnlock files and indexes
    xbDbf::LockDatabaseLocks or unlocks a DBF database
    xbNdx::LockIndexLocks or unlocks an xbNdx index
    xbNdx::LockMemoFileLocks 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 CodeDescription
    XB_INVALID_RECORDAn invalid record given
    XB_LOCK_FAILEDThe lock action failed, see errno
    XB_NO_ERRORThe 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 CodeDescription
    XB_LOCK_FAILEDThe lock action failed, see errno
    XB_NO_ERRORThe 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 CodeDescription
    XB_LOCK_FAILEDThe lock action failed, see errno
    XB_NO_ERRORThe lock was successful

    Send me mail - xbase@startech.keller.tx.us

    (c)1997 StarTech