FILELOCK statement

Syntax

FILELOCK [ file.variable ] [ , lock.type ] 
[ON ERROR statements] [LOCKED statements]

Description

Use the FILELOCK statement to acquire a lock on an entire file. This prevents other users from updating the file until the program releases it. A FILELOCK statement that does not specify lock.type is equivalent to obtaining an update record lock on every record of the file.

file.variable specifies an open file. If file.variable is not specified, the default file is assumed (for more information on default files, see the OPEN statement). If the file is neither accessible nor open, the program terminates with a run-time error message. If file.variable evaluates to the null value, the FILELOCK statement fails and the program terminates with a run-time error message.

lock.type is an expression that evaluates to one of the following keywords:

SHARED (to request an FS lock)
INTENT (to request an IX lock)
EXCLUSIVE (to request an FX lock)

The ON ERROR Clause

The ON ERROR clause is optional in the FILELOCK statement. The ON ERROR clause lets you specify an alternative for program termination when a fatal error is encountered during processing of the FILELOCK statement.

If a fatal error occurs, and the ON ERROR clause was not specified, or was ignored (as in the case of an active transaction), the following occurs:

An error message appears.
Any uncommitted transactions begun within the current execution environment roll back.
The current program terminates.
Processing continues with the next statement of the previous execution environment, or the program returns to the command prompt.

A fatal error can occur if any of the following occur:

A file is not open.
file.variable is the null value.
A distributed file contains a part file that cannot be accessed.

If the ON ERROR clause is used, the value returned by the STATUS function is the error number. If a FILELOCK statement is used when any portion of a file is locked, the program waits until the file is released.

The LOCKED Clause

The LOCKED clause is optional, but recommended. The LOCKED clause handles a condition caused by a conflicting lock (set by another user) that prevents the FILELOCK statement from processing. The LOCKED clause is executed if one of the following conflicting locks exists:

This requested lock...: Conflicts with...
Shared file lock: Exclusive file lock Intent file lock Update record lock
Intent file lock: Exclusive file lock Intent file lock Shared file lock Update record lock
Exclusive file lock: Exclusive file lock Intent file lock Shared file lock Update record lock Shared record lock

If the FILELOCK statement does not include a LOCKED clause and a conflicting lock exists, the program pauses until the lock is released.

If a LOCKED clause is used, the value returned by the STATUS function is the terminal number of the user who owns the conflicting lock.

Releasing Locks

A shared, intent, or exclusive file lock can be released by a Syntax, RELEASE statement, or STOP statement.

Locks acquired or promoted within a transaction are not released when previous statements are processed.

Examples

OPEN '','SUN.MEMBER' TO DATA ELSE STOP "CAN'T OPEN 
FILE"
FILELOCK DATA LOCKED STOP 'FILE IS ALREADY LOCKED'
FILEUNLOCK DATA
OPEN '','SUN.MEMBER' ELSE STOP "CAN'T OPEN FILE"
FILELOCK LOCKED STOP 'FILE IS ALREADY LOCKED'
PRINT "The file is locked."
FILEUNLOCK

This is the program output:

The file is locked.

The following example acquires an intent file lock:

FILELOCK fvar, "INTENT" LOCKED
   owner = STATUS( )
   PRINT "File already locked by":owner
   STOP
END