READU Statement

Locks a file item, then reads it and assigns its value, as a dynamic array, to a variable.

Syntax

READU dynArray FROM {fileVar,}itemId {SETTING settingVar} {LOCKED statement(s)} [THEN statement(s) | ELSE statement(s)]

Syntax Elements

dynArray The name of the variable into which the elements of the file item are assigned as a dynamic array.

fileVar The name of a variable containing a file reference (assigned via an OPEN statement). If fileVar is not specified, the internal default file variable is used; that is, the file used is that most recently opened without a file variable.

itemId The name of the item from which the data is to be read.

settingVar The name of a variable that is set to a return value. If the data is read successfully, settingVar is set to 0 and the THEN clause is executed. If an error occurs, settingVar is set to the appropriate error code and the ELSE clause is executed. The error codes and corresponding messages are given in File I/O and IPC Error Codes).

If the item is locked, settingVar is returned unchanged.

statement(s) A sequence of one or more valid DataBasic statements, either separated by semicolons or contained on separate lines and followed by an END statement.

The LOCKED clause (if any) is executed if the item is locked by another process. Use SYSTEM(43) to obtain the number of the port that has locked the item.

If there is no LOCKED clause, READU is suspended until the item becomes unlocked.
The THEN clause is executed (and the item is locked) if the read is successful.
The ELSE clause is executed (and the item is locked) if the item does not exist.

A THEN or an ELSE clause, or both, must be included.

Note

This behaviour can be changed with the NO.IO.ERR compatibility option.

Operation

READU works the same way as the READ statement, except that it locks the item to be read. This prevents an item from simultaneously being updated by two or more processes.

The item is locked even if the item does not exist on file. Thus, when building a new item it can be locked in the database first before it is ever written away.

MultiValue Compatibility

If you call the STATUS function immediately after a READU statement, if a LOCKED clause was specified and has been executed STATUS returns the port number of the process that has locked the item; otherwise STATUS returns zero.

Examples

READU ITEM FROM INV, "S5" ELSE GOSUB 4

Locks item S5, then reads S5 to variable ITEM. If S5 does not exist, control is transferred to subroutine 4.

READU A FROM FILE1,"REC" LOCKED PRINT "LOCKED" ELSE STOP

Attempts to lock item REC in file FILE1 and, if successful, reads it to variable A. If the item cannot be read because it is locked, the message LOCKED is displayed and the program continues; if the item cannot be read for any other reason the program terminates.