LOCK( ) Function
Attempts to lock one or more records in a table.
LOCK([nWorkArea | cTableAlias]|
[cRecordNumberList, nWorkArea | cTableAlias])
Parameters
nWorkArea| cTableAlias
Attempts a lock on the current record in a table open in a specific work area. nWorkArea specifies the work area number and cTableAlias specifies the table alias. If you do not specify a work area or table alias, LOCK( ) attempts to lock the current record in the table in the current work area.cRecordNumberList
Specifies a list of one or more record numbers which you must include to attempt to lock multiple records. SET MULTILOCKS must be ON and you must include the work area or alias of the table for which you are attempting to place multiple record locks.LOCK( ) attempts to lock all of the records you specify. The record numbers specified with cRecordNumberList are separated by commas. For example, to attempt record locks on the first four records in a table, cRecordNumberList must contain 1,2,3,4.
You can also lock multiple records by moving the record pointer to the record you would like to lock, issuing LOCK( ) or RLOCK( ) and then repeating these steps for each additional record.
In Visual FoxPro, you can specify 0 as a record number. Specifying 0 makes it possible for you to attempt to lock the table header.
Note
Keep the table header locked for as short a time as possible because other users cannot add records to the table when the table header is locked.
Release the table header lock with UNLOCK RECORD 0, UNLOCK or UNLOCK ALL.
If all the records specified in cRecordNumbers are successfully locked, LOCK( ) returns true (.T.). If even one of the records specified with cRecordNumbers cannot be locked, LOCK( ) returns false (.F.) and none of the records are locked. However, any existing record locks remain in place. Multiple record locking is an additive process. Placing additional record locks does not release locks on other records.
The maximum number of records that can be locked in each work area is approximately 8,000. It is always faster to lock the entire table rather than even a small number of records.
Return Value
Logical
Remarks
LOCK( ) is identical to RLOCK( ).
Changes to explicitly locked records aren't saved until the record is unlocked or the record pointer is moved.
If the lock or locks are successfully placed, LOCK( ) returns true (.T.). Locked records are available for both read and write access to the user who placed the locks; they are available for read-only access to all other users on the network.
Executing LOCK( ) does not guarantee that the record lock or locks will be successfully placed. A record lock cannot be placed on a record already locked by another user or in a table locked by another user. If the record lock or locks cannot be placed for any reason, LOCK( ) returns false (.F.).
By default, LOCK( ) makes one attempt to lock a record. Use SET REPROCESS to automatically retry a record lock when the first attempt fails. SET REPROCESS determines the number of lock attempts or the length of time during which lock attempts are made when the initial lock attempt is unsuccessful. For more information, see SET REPROCESS.
SET MULTILOCKS determines whether you can lock multiple records in a table. If SET MULTILOCKS is OFF (the default), you can lock only a single record in a table. When SET MULTILOCKS is ON, you can lock multiple records in a table. For more information, see SET MULTILOCKS.
Unlocking Records A table record can be unlocked only by the user who placed the lock. You can release record locks by issuing UNLOCK, closing the table, or exiting Visual FoxPro.
UNLOCK can be used to release record locks in the current work area, a specific work area, or in all work areas. For more information, see UNLOCK.
Switching SET MULTILOCKS from ON to OFF or from OFF to ON implicitly performs UNLOCK ALL — all record locks in all work areas are released.
Tables can be closed with USE, CLEAR ALL, or CLOSE DATABASES.
For more information about record and file locking and sharing tables on a network, see Programming for Shared Access.
Example
The following example locks and unlocks the first four records in the customer and employee tables.
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
SET REPROCESS TO 3 AUTOMATIC
STORE '1,2,3,4' TO gcRecList
gcOldExc = SET('EXCLUSIVE')
SET EXCLUSIVE OFF
SELECT 0
USE employee && Open Employee table
SELECT 0
USE customer && Open Customer table
? LOCK('1,2,3,4', 'customer') && Lock 1st 4 records in customer
? RLOCK(gcRecList, 'employee') && Lock 1st 4 records in employee
UNLOCK IN customer
UNLOCK IN employee
SET EXCLUSIVE &gcOldExc