READBLK Statement

Reads a block of data from a host file or Reality item that has been opened for sequential access.

Syntax

READBLK data-var FROM seqfile-var {,blocksize} {SETTING setting-var} {ON ERROR statement(s)} [ THEN statement(s) | ELSE statement(s) ]

WHILE READBLK data-var FROM seqfile-var {,blocksize} {SETTING setting-var} {ON ERROR statement(s)} DO

Syntax Elements

data-varThe name of a variable in which the data will be returned.

seqfile-var The name of a variable containing a sequential file reference (assigned via an OPENSEQ statement).

blocksizeThe number of bytes of data to be returned. If omitted, the record size specified in the OPENSEQ statement will be used. If neither is specified, a default size is used (the default size depends on the version of Reality and the platform on which it is running).

setting-varThe name of a variable to which the return status is assigned. See Operation for details of the possible values for this variable.

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.

Operation

The following details circumstances under which the different clauses are executed and the values returned in setting-var:

Clause Executed	Reason	`setting-var`	STATUS() Value
THEN	Data read successfully	0	0
ELSE	Data read successfully, but end of item encountered	0	0
ON ERROR	Item opened, but not for sequential access (not opened with OPENSEQ)	B45	12
	File or item not open	B12	12
	Invalid Block size	2417	205
	General file error	Error number	Error number

Note

If an error occurs but there is no ON ERROR clause, the DataBasic Debugger will be entered with error B53 as well as the setting-var value.
The final column gives the values returned by the STATUS function if this is used instead of a SETTING clause.

Comments

When used as the condition in a WHILE statement, the READBLK statement causes the DO clause to be executed if the read is successful, or the loop to be exited if the end of the file or item is encountered. The THEN and ELSE clauses must be omitted.

Caution

When the ELSE clause is executed or a loop exited because the end of the file or item has been reached, the data-var variable will contain any partial block from the end of the file.

Example

OPENSEQ "/usr/pauls/qa4" TO SF1 THEN
    FOR I = 1 TO 5
        READBLK DATA FROM SF1,20 THEN
            PRINT DATA
        END ELSE
            * If we hit the end of the file, the data is incomplete.
            PRINT "Data corrupt"
            CLOSESEQ SF1
            STOP
        END
    NEXT I
END
CLOSESEQ SF1

This program opens the host file /usr/pauls/qa4 and saves a reference to the open file in variable SF1. If the file exists, the program then reads and displays the first 100 characters from the file, 20 characters at a time. Finally, the file is closed.