F-UREAD

Reads an item from a file into a file buffer and locks the specified item.

Syntax

F-UREAD fileBufferNumber itemId
altCmd

F-UR fileBufferNumber itemId
altCmd

Syntax Elements

fileBufferNumber
The number of the file buffer to which the file was assigned that contains the item you want to read. Valid numbers are 1 to 47, but note that 19 and 20 are reserved for system Procs.

fileBufferNumber can be a direct or indirect file buffer reference.

itemId The name of the item to be read and locked.

itemId can be a literal string (not enclosed in quotes), or it can be a direct or indirect reference to a buffer or select register containing the itemId of the item that you want to read and lock.

altCmd A command(s) to be executed if the named item cannot be read. Must be on the line immediately after the command itself.

Operation

The F-UREAD command works exactly like the F-READ command, except that it locks the item so that other processes cannot access it.

Use the F-UREAD command whenever more than one process might be updating the same item simultaneously.

The F-UREAD command is always followed by a command line that is executed if the read fails.

If a process attempts to F-UREAD an item that is locked by another process, execution is suspended until the item becomes unlocked.

The item lock set by F-UREAD command is released when an F-DELETE, F-WRITE or F-FREE command is executed, or when Proc execution terminates.

Note that an item lock is not released by subsequent F-UREAD commands. The lock must be specifically released by an F-DELETE, F-WRITE, or F-FREE command or remain locked until termination of the Proc.

Example

001 PQN
002 T "ENTER FILE NAME ",+
003 IBP:%1
004 IF # %1 X-TCL-
005 F-C 1
006 F-O 1 %1
007 XCANNOT OPEN REQUESTED FILE
008 T "ENTER itemId ",+
009 IBP:%2
010 IF # %2 X-TCL-
011 F-UR 1 %2
012 XREQUESTED ITEM NOT ON FILE
.
.
.
030 F-W 1 %2
.
.

This example opens the requested file to file buffer 1 and reads in the requested item from that file. The item is locked by the F-UREAD command, so that another process that sets a lock cannot update it at the same time. The item remains locked while data is updated, then unlocked by the F-WRITE command on line 30.

See Also

Item Locks.