Click or drag to resize

Functions.Lock Method

Attempts to lock one or more records in a table.

Namespace:  XSharp.VFP
Assembly:  XSharp.VFP (in XSharp.VFP.dll) Version: 2.17
Request Example View Source


cRecordNumberList (Optional)
Type: Usual
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 X#, you can specify 0 as a record number. Specifying 0 makes it possible for you to attempt to lock the table header.
Note 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.
uArea (Optional)
Type: Usual
Attempts a lock on the current record in a table open in a specific work area. uArea specifies the work area number and 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.

Return Value

Type: Logic
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 X#. 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.
 1Close Databases
 2Open Database (HOME(2) + 'data\testdata')
 4STORE '1,2,3,4' TO gcRecList
 5gcOldExc = Set('EXCLUSIVE')
 7Select 0
 8Use employee  // Open Employee table
 9Select 0
10Use customer  // Open Customer table
11? Lock('1,2,3,4', 'customer')  // Lock 1st 4 records in customer
12? RLock(gcRecList, 'employee')  // Lock 1st 4 records in employee
13UNLock IN customer
14UNLock IN employee
15Set EXCLUSIVE &gcOldExc
See Also