+---------------------------------+
|              LOCK               |
+---------------------------------+
LOCK([<expN1> | <expC1>]
        | [<expC2>, <expN2> | <expC3>])

-----------------------------------
Attempts to lock database records.
Return value - Logical
-----------------------------------

With the LOCK() function you may attempt to place a lock on a database
record or a set of records.  If the lock or locks are successfully
placed a logical true value (.T.) is returned.  Locked records are
available for both read and write access by the user who placed the
locks -- read-only access to the records is available to all other users
on the network.

Executing the LOCK() function does not guarantee that the attempted
record lock or locks will be successfully placed.  A record lock cannot
be placed on a record already locked by another user, or on a record in
a database locked by another user.

The SET MULTILOCKS command determines whether you may lock multiple
records in a database.  If MULTILOCKS is SET OFF (the default), you may
only lock a single record in a database.  Multiple records in a database
may be locked when MULTILOCKS is SET ON.  See the SET MULTILOCKS command
in this help facility for further information.

You may issue the LOCK() function from within the Command window and
programs.  The LOCK() function is identical to the RLOCK() function.

Single record locking:
----------------------

A single record in a database may be locked when MULTILOCKS is SET OFF.
A record lock is attempted on the current record in the current work
area unless an <alias> of a different work area is included -- then a
lock is attempted on the current record in the specified work area.  If
a record is locked, its lock is released when a different record in the
same database is locked.

To attempt a record lock on the current record in a different work area,
include the database alias or work area letter (work area letters A
through J for the first ten work areas only) or specify the work area
number in <alias>.  If you specify a database alias or work area letter
it must be enclosed in quotes.

If the record is successfully locked a logical true (.T.) is returned.
If the record cannot be locked (the record or file has already been
locked by another user on the network) a logical false (.F.) is
returned.

Multiple record locking:
------------------------

Multiple records may be locked in the currently selected work area or in
another work area when MULTILOCKS is SET ON.

You may lock multiple records in two fashions.  First, you may move the
record pointer to the record you would like to lock and then issue a
LOCK() or RLOCK() command, repeating this for each record.  This allows
you to attempt multiple record locks in the current work area without
specifying an <alias> in LOCK() or RLOCK().

You may also specify a list of the record numbers you would like to lock
in a character expression <expC>.  The record numbers in <expC> must be
separated by commas, and the entire list must be enclosed in single or
double quotation marks.  For example, to attempt record locks on the
first 4 records in a database, <expC> would be "1,2,3,4" or '1,2,3,4'.
Note that <expC> can be a memory variable containing this character
string.

You must always include a work area <alias> if you attempt multiple
record locks with a record number list <expC>.  You may specify the
database alias or work area letter (work area letters A through J for
the first ten work areas only) or specify the work area number in
<alias>.  If you specify a database alias or work area letter it must be
enclosed in quotes.

Multiple record locking is an additive process -- placing additional
record locks does not release locks on other records.

If ALL the records specified in <expC> are successfully locked a logical
true (.T.) is returned.

If even one of the records specified in <expC> cannot be locked, a
logical false (.F.) is returned and none of the records specified in
<expC> will be locked.  However, any existing record locks will remain
in place.

The maximum number of records that may be locked in each work area by
FoxPro is approximately 8,000.  However, the total number of locks that
can be placed is limited by the amount of memory on your file server.
From a performance perspective it is always faster to lock the entire
database rather than locking even a small number of records.

Unlocking records:
------------------

A database record may only be unlocked by the user who placed the lock.
Record locks may be released by issuing the UNLOCK command, closing the
database or QUITting out of FoxPro/LAN.

The UNLOCK command may be used to release record locks in the current
work area (UNLOCK), a specific work area (UNLOCK IN <alias>) or in all
work areas (UNLOCK ALL).  See the UNLOCK command in this help facility
for more information its use and syntax.

Note that toggling MULTILOCKS from ON to OFF or from OFF to ON
implicitly performs an UNLOCK ALL command -- all record locks in all
work areas are released.

Databases may be closed with the USE, CLEAR ALL or CLOSE DATABASE
commands.

The SET REPROCESS command affects how LOCK() returns a value.  With SET
REPROCESS you may keep attempting to lock a record if the initial lock
attempt is unsuccessful.  For more information about how SET REPROCESS
controls record locking attempts, see the SET REPROCESS topic in this
help facility.

Clauses
-------

<expN1> | <expC1>
        Work area number or alias.

<expC2>
        List of one or more record numbers separated by commas.

<expN2> | <expC3>
        Work area number or alias.

+---------------------------------+
|         Program Example         |
+---------------------------------+
SET MULTILOCKS ON
SET REPROCESS TO AUTOMATIC
STORE '1,2,3,4' TO mreclist

CLOSE ALL
SELECT 0
USE customer
SELECT 0
USE states

? LOCK('1,2,3,4', 'customer') && Lock the first 4 records in customer
? RLOCK(mreclist, 'states')   && Lock the first 4 records in states
UNLOCK IN customer
UNLOCK IN states

-----------------------------------

See Also:  CLOSE, FLOCK(), RLOCK(), SET MULTILOCKS, SET REPROCESS, SET
RELATION, UNLOCK, USE

-----------------------------------