READ

The READ statement reads a record from a previously opened file.

Format

READ var {ENCODING name} FROM file.var, record.id {ON ERROR statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

where

At least one of the THEN and ELSE clauses must be present unless the OPTIONAL.THEN.ELSE setting of the $MODE compiler directive is enabled.

The specified record is read into the named variable.

When reading from a directory file, newlines in the data read from the file are replaced by field marks. This action may be suppressed by using the MARK.MAPPING statement after opening the file.

The optional ENCODING element to this statement sets the character encoding to be used, overriding any encoding set in the VOC F-type record or when the file was opened. This is relevant only to directory files and is ignored for other file types. A null string as the encoding name is equivalent to not having the ENCODING clause at all. To disable the default encoding, the encoding name should be specified as "NULL".

The THEN clause is executed if the READ is successful.

The ELSE clause is executed if the READ fails because no record with the given id is present on the file. If the PICK.READ mode of the $MODE directive is used var will be left unchanged, otherwise it will be set to a null string for a normal file or an empty collection for a data collection file. The STATUS() function will indicate the cause of the error.

The ON ERROR clause is executed for serious fault conditions such as errors in a file's internal control structures. The STATUS() function will return an error number. If no ON ERROR clause is present, an abort would occur.

Example

READ ITEM FROM STOCK, ITEM.ID THEN

  ...processing statements...

END ELSE

  DISPLAY "Record " : ITEM.ID : " not found"

END

This program fragment reads a record from the a file previously opened to file variable STOCK into variable ITEM. If successful, the processing statements are executed. If the record is not found, a message is displayed.