Function DbRLock() | Xbase++

Locks records for write access when file is open in SHARED mode.

DbRLock( [<xRecordID>] ) --> lSuccess

<xRecordID> is an expression clearly identifying a record. It is predetermined by the file format of the data files. For DBF files, <xRecordID> is a numeric value designating the record number (RecNo()) of the record to lock. If <xRecordID> is missing, all existing record locks in the work area are released and the current record is locked.

The return value of DbRLock() is .T. (true) when the current record or the one designated by <xRecordID> could be locked for write access in a work area open as SHARED. Otherwise, .F. (false) is returned.

The database function DbRLock() locks a record for write access, preventing write access from other work stations. By specifying a record ID <xRecordID> a specific record is locked. The function DbRLock() allows locking multiple records which cannot be done using the function RLock(). If no record ID is specified, DbRLock() behaves like RLock(), meaning that existing record locks are released and the current record is locked.

Record locks are required for multi-user applications in network operation when a user is changing the data in a record. If the data record could be locked, DbRLock() returns the value .T. (true). The record is then available to other users only for read access until the record lock is released with DbRUnlock() or a command like UNLOCK or CLOSE.

A record must be locked with DbRLock() when file operations are executed which modify the record. This includes operations caused by commands like @..GET, RECALL, DELETE or REPLACE and the function FieldPut().

Each call to DbRLock() causes one attempt to lock the record in the work area. If the function is called without the alias operator, the attempt to lock the record occurs in the current work area. If the record could be locked, DbRLock() returns the value .T. (true). The record then remains locked to other users until the lock is released. After a successful lock, other users have only read access to the record.

If links are defined for the specified work area using SET RELATION or DbRelation(), the dependent files may also need to be locked. An automatic lock of all dependent records is not performed by DbRLock().

DbRLock()


// The example shows the locks of several records 
// whose record ID is stored in an array 

PROCEDURE Main 
   LOCAL aRecordID := {1,2,6,7,9}, n 

   USE Customer NEW 

   FOR n:=1 TO 5 
      IF ! DbRLock( aRecordID[ n ] )  // set lock 
         DbRUnlock()                  // a lock was not successful, 
         EXIT                         // release all 
      ENDIF 
   NEXT 

   IF n < 6 
      ? "records could not be locked" 
   ELSE 
      ? "records were locked" 
   ENDIF 

   CLOSE Customer 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function DbRLock() Foundation