xHarbour Reference Documentation > Function Reference

FLock()

Applies a file lock to an open, shared database.

Syntax

FLock() --> lSuccess

Return

The function returns .T. (true) when the entire file open in a work area is successfully locked, otherwise .F. (false).

Description

The function FLock() is used when a database open in SHARED mode in a work area must be protected entirely from concurrent updates by other applications in a multi-user scenario. As long as an application has obtained a file lock with FLock(), other applications can read records from the file, but are excluded from updating any record in the file with new data. Therefore, file locks should be used with special care and should be released as soon as possible with DbUnlock().

Before a file lock is placed, it is recommended to consider whether or not the same protection could be achieved with one or multiple record locks. They are created with the Rlock() or DbRLock() functions and are by far less restrictive for network operations.

Certain database updates, however, require an application to obtain a file lock, otherwise a safe operation is not guaranteed to complete. As a general rule, database operations that involve many records require a file lock, while those updating only one or few records can be achieved using record locks.

Commands requiring an FLock()

Command	Protection
APPEND FROM	FLock() or USE...EXCLUSIVE
DELETE (multiple records)	FLock() or USE...EXCLUSIVE
RECALL (multiple records)	FLock() or USE...EXCLUSIVE
REPLACE (multiple records)	FLock() or USE...EXCLUSIVE
UPDATE ON	FLock() or USE...EXCLUSIVE

FLock() attempts to lock the database once only. If this attempt fails, the function returns .F. (false). Common reasons for failure are that another application has currently obtained a record lock or a file lock on the same database file.

Info

See also:	DbRLock(), DbUnlock(), DbUnlockAll(), DbUseArea(), NetFileLock(), RLock(), SET EXCLUSIVE, UNLOCK, USE
Category:	Database functions , Network functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// This example uses FLock() to delete many records at once.

   PROCEDURE Main

      USE Customer SHARED NEW

      IF FLock()
         DELETE FOR Year(Date())-Year(Cust->LastDate) > 5
         DbCommit()
         DbUnlock()
      ELSE
         ? "Error: unable to lock file."
      ENDIF

      USE
   RETURN