READBLK

The READBLK statement reads a given number of bytes from the current file position in a record previously opened using OPENSEQ.

Format

READBLK var {ENCODING name} FROM file.var, bytes

{ON ERROR statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

where

var	is the name of a variable to receive the data read from the file.

file.var

is the file variable associated with the file.

bytes

evaluates to the number of bytes to be read.

statement(s)

are statements to be executed depending on the outcome of the READBLK 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 READBLK statement reads up to bytes bytes from the file. If at least one byte is available, the data is returned in var and the THEN clause is executed.

The ELSE clause is executed if the READBLK fails. The STATUS() function will indicate the cause of the error. For example, attempting to read when at the end of the file will return ER$EOF.

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.

The optional ENCODING clause sets the character encoding to be used, overriding any encoding set in the VOC F-type record or when the file was opened. 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".

Note that READBLK is a byte level operation and returns a string in which each character will represent one byte from the file and hence is always in the range char(0) to char(255). When used with the ENCODING clause, the bytes value is the number of bytes to be read, not the character count in the decoded data.

If file.var refers to a serial port opened using OPENSEQ, the READBLK statement reads up to bytes bytes of data from the port but does not wait if there is less than the requested number of bytes available.

Example

READBLK VAR FROM SEQ.F, 100 THEN

...processing statements...

END ELSE

DISPLAY "Data block not read"

END

This program fragment reads 100 bytes from the a file previously opened to file variable SEQ.F into variable VAR.