READV Statement

Reads an attribute value from an item and assign its string value to a specified variable. See also the READVU statement.

Syntax

READV variable FROM {file-var,}item-id, attr# {SETTING setting-var} {LOCKED statement(s)} [THEN statement(s) | ELSE statement(s)]

Syntax Elements

variable The name of a variable to which the value of the attribute is assigned.

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.

attr# The number of the attribute to be read.

If attr# is 0, READV checks that the specified item exists and executes the THEN or ELSE clause as appropriate. variable is returned unchanged.

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 READVU).

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

  • The ELSE clause is executed 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.

Comments

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

Refer to the topic File Input and Output in the Efficiency Guidelines section for important recommendations about efficient and inefficient ways of using READV.

Examples

READV A FROM F, "XYZ", 3 ELSE STOP

Reads the third attribute of item XYZ in the file specified by F and assigns it to variable A.  If XYZ does not exist, the program terminates.

READV X FROM A, "TEST", 5 ELSE
  PRINT ERR
  GOTO 70
  END

Reads the fifth attribute of item TEST (in the file opened and assigned to variable A) and assigns its value to variable X. If TEST does not exist, then the value of ERR is printed and control transfers to statement 70.