READV

READV

Top  Previous  Next

 

The READV statement reads a specific field from a record of a previously opened file.

 

 

Format

 

READV var {ENCODING name} FROM file.var, record.id, field.expr

{ON ERROR statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

 

where

 

varis the name of a variable to receive the dynamic array read from the file.

 

file.varis the file variable associated with the file.

 

record.idevaluates to the id of the record to be read.

 

field.exprevaluates to the number of the field to be read.

 

statement(s)are statements to be executed depending on the outcome of the READV operation.

 

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 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 specified record is read and the field identified by field.expr is extracted into the named variable. If the field does not exist, var is set to a null string.

 

Note that internally, the file system operates at the record level so READV reads the entire record, extracts the field and discards the rest. If multiple fields are to be extracted, it is always better to read the whole record and use field extraction operations instead of using multiple READV statements.

 

A field.expr value of zero may be used to determine if the record exists. If it does, the THEN clause is taken and var is set to the record id. If the record does not exist, the ELSE clause is taken and var will be set to a null string. The record is not transferred into memory, resulting in a significant performance advantage over use of READ when the record is very large.

 

The THEN clause is executed if the record is read successfully regardless of whether the specified field is present.

 

The ELSE clause is executed if the READV 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. 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.

 

When used with a data collection file, the field.expr must evaluate to zero as records in this file type are not dynamic arrays.

 

 

Example

 

READV ITEM FROM STOCK, ITEM.ID, 3 THEN

...processing statements...

END ELSE

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

END

 

This program fragment reads field 3 of a record from the 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.

 

 
See also:

WRITEV