LOCK( ) Function

  • Article

Attempts to lock one or more records in a table.

LOCK([nWorkArea | cTableAlias]|
 [cRecordNumberList, nWorkArea | cTableAlias])

Return Values

Logical

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 don't 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 can't 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 doesn't 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.

Remarks

LOCK( ) is identical to RLOCK( ).

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( ) doesn't guarantee that the record lock or locks will be successfully placed. A record lock can't be placed on a record already locked by another user or in a table locked by another user. If the record lock or locks can't 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

See Also

CLEAR | CLOSE | FLOCK( ) | RLOCK( ) | SET MULTILOCKS | SET REPROCESS | UNLOCK | USE