READ Statement

Reads a file item and assigns its value, as a dynamic array, to a variable.

Syntax

READ dyn-array FROM {file-var,}item-id {SETTING setting-var} {LOCKED statement(s)} [THEN statement(s) | ELSE statement(s)]

Syntax Elements

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

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

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

setting-var The name of a variable that is set to a return value. If the data is read successfully, setting-var is set to 0 and the THEN clause is executed. If an error occurs, setting-var 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, setting-var 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 a LOCKED clause is present, the statement sets a lock on the item (that is, it functions like READU).

  • The THEN clause is executed if the read is successful.

  • The ELSE clause is executed if an error occurs or 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

If the specified file has not been opened prior to the READ statement, the program aborts with an error message.

See Also

READU statement, READV statement, READVU statement.

Examples

READ X1 FROM W,"TEMP" ELSE PRINT "NON-EXISTENT"; STOP

Reads the item named TEMP from the file opened and assigned to file variable W and assigns its string value to variable X1. If TEMP does not exist, the message NON-EXISTENT is displayed and the program is terminated.

A="TEST"
B="1"
READ X FROM C,(A CAT B) ELSE STOP

Reads item TEST1 from file opened and assigned to file variable C and assigns its value to variable X.  Program terminates if TEST1 does not exist.

READ Z FROM "Q1" THEN PRINT X; STOP

Reads item Q1 from the file opened without a file variable and assigns its value to variable Z.  Prints value of X and terminates program if Q1 does not exist.