RLOCK( ) Function

  • Article

Attempts to lock a table record or records.

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

Return Values

Logical

Parameters

  • nWorkArea | cTableAlias
    Specifies the work area number or table alias for a table open in another work area. If you don't specify a work area or alias, RLOCK( ) attempts to lock the current record in the table in the currently selected work area.

  • cRecordNumberList
    Specifies that RLOCK( ) attempts to lock multiple records. The character expression cRecordNumberList specifies one or more record numbers, separated by commas, that RLOCK( ) attempts to lock. For example, to attempt record locks on the first four records in a table, cRecordNumberList should contain 1, 2, 3, 4.

    To lock multiple records, you must have SET MULTILOCKS on and you must include the work area number (nWorkArea) or alias (cTableAlias) of the table in which you attempt to lock multiple records.

    You can also lock multiple records by moving the record pointer to the record you would like to lock, issuing RLOCK( ) or LOCK( ) and then repeating this process for additional records.

    In Visual FoxPro, you can specify 0 as a record number. Specifying 0 lets you attempt to lock the table header.

    Caution   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 cRecordNumberList are successfully locked, RLOCK( ) returns true (.T.). If one or more of the records specified in cRecordNumberList cannot be locked, RLOCK( ) returns false (.F.) and locks none of the records. In either case, existing record locks remain in place. Multiple record locking is an additive process — placing additional record locks doesn't release existing record locks.

    From a performance perspective, it is always faster to lock the entire table than to lock even a small number of records.

Remarks

RLOCK( ) is identical to LOCK( ).

If the lock or locks are successfully placed, RLOCK( ) returns true (.T.). Locked records are available for both read and write access by the user who placed the locks and for read-only access to all other users on the network.

Executing RLOCK( ) doesn't guarantee that the attempted record lock or locks are 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, RLOCK( ) returns false (.F.).

By default, RLOCK( ) makes one attempt to lock a record. Use SET REPROCESS to automatically retry a record lock when the first attempt fails. SET REPROCESS controls the number of lock attempts or the length of time lock attempts are made when the initial lock attempt is unsuccessful. For more information about SET REPROCESS and table locking, 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. If SET MULTILOCKS is on, you can lock multiple records in a table. For more information, see SET MULTILOCKS.

A table record can be unlocked only by the user who placed the lock. Record locks can be released 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.

To close tables, use 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( ) | LOCK( ) | SET MULTILOCKS | SET RELATION | SET REPROCESS | UNLOCK | USE