FLOCK(), ISFLOCKED(), ISRLOCKED(), Sys(2011)

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

`FLOCK()`, `ISFLOCKED()`, `ISRLOCKED()`, Sys(2011)

FLOCK() locks all records in a table, preventing any other user from obtaining a lock on the file. Records are still visible for others to view, browse and report on. SYS(2011) can be used to detect the status of the current record, without attempting to actually place a lock on the record. The Is?Locked() functions return a logical rather than SYS(2011)’s localizable string, for easier internationalization.

Usage

lResult = FLOCK( [ nWorkArea | cAlias ] )

Parameter	Value	Meaning
nWorkArea	Integer	Specifies the work area of the table to be locked.
nWorkArea	Omitted	If cAlias is also omitted, the file lock is attempted in the current work area.
cAlias	Character	Specifies the alias of the table to be locked.
cAlias	Omitted	If nWorkArea is also omitted, the file lock is attempted in the current work area.
lResult	.T.	The lock was placed successfully.
lResult	.F.	No lock was placed, either because others have locks on the table, or because there's no table open in the specified area or with the supplied alias.

You can use FLOCK() to ensure that changes to all records will be performed, say, before issuing a REPLACE ALL command. We try to avoid using this command, unless all records must be locked, since it must be manually released with UNLOCK ALL and doesn’t scale well into client-server environments. Instead, we try to use table buffering and multi-locks to lock only those records we want to affect. Use BEGIN TRANSACTION, ROLLBACK and END TRANSACTION to ensure that all or none of the updates are made to the tables.

Example

? FLOCK("Customer")

Usage

cReturn = SYS(2011)
lLock = ISFLOCKED( [ nWorkArea | cAlias ] )
lLock = ISRLOCKED( [ nRecNo, [ nWorkArea | cAlias ]  ])

Parameter	Value	Meaning
cReturn	"Exclusive"	The current table is opened exclusively.
	"Record Unlocked"	The current record is not locked by this workstation.
	"Record Locked"	The current record is locked by this workstation.
	Empty String	There is no table open in the current work area.
nRecno	Integer	The record number whose lock is tested.
lLock	.T.	The file or record is already locked.
lLock	.F.	The file or record is not locked, or, if you specified a work area, no table is open in that work area.

SYS(2011) has confused a number of developers, who think this function tells them whether or not they will be able to lock the record. It doesn’t. This function just reports whether the local FoxPro application has the record locked. In order to determine if someone else has the record or file locked, the application must attempt to lock the record. This function is missing a second, optional parameter, allowing the developer to specify the alias or work area of the record of concern. It is notable by its absence. Like all SYS() Functions, SYS(2011) won’t give you an error if you supply too many parameters, so don’t think that SYS(2011, lcAlias) is actually working on the alias you specify. SYS(2011) returns the localized lock status as text, such as “File Locked,” “Exclusive,” “Record Locked” or “Record Unlocked.” This is almost useless in an application that might run on several different localized runtimes. So, in VFP 5, Microsoft introduced the two IS functions, which return a logical result, regardless of the language in use. Unlike SYS(2011), however, you may not get the whole picture. If a table is open exclusively, ISFLOCKED() reports .T., while ISRLOCKED() reports .F. So, to get the full story on whether a REPLACE can be sure to work, you need to check ISEXCLUSIVE() OR ISFLOCKED() OR ISRLOCKED().

</p>	Even more confusing, the IS functions return .F. if the work area you specify has no table open. If, on the other hand, you supply a bogus alias, you get the error "Alias not found." These functions should consistently do one or the other.

Example

? SYS(2011)
lSafeToSave = ISEXCLUSIVE() OR ISFLOCKED() OR ISRLOCKED()