READSEQ Statement

Reads a line of data from a file opened for sequential access.

Syntax

READSEQ line-var{:} FROM seqfile-var {SETTING setting-var} {ON ERROR statement(s)} [ THEN statement(s) | ELSE statement(s) ]

WHILE READSEQ line-var{:} FROM seqfile-var {SETTING setting-var} {ON ERROR statement(s)} DO

Syntax Elements

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

: Reads a block of data instead of a line (similar to the READBLK statement). The block size must be specified when the file or item is opened with the OPENSEQ statement.

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

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
	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

The delimiter used depends on the environment:

In a UNIX file, lines are delimited by line feed characters.
In a Windows file, lines are delimited by line feed/carriage return.
In a Reality item, lines are delimited by attribute marks.

The line delimiter is not included in the returned data.

When used as the condition in a WHILE statement, the READSEQ 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 line from the end of the file.

Example

OPENSEQ "/usr/pauls/qa4" TO SF1 THEN
    LOOP WHILE READSEQ LINE FROM SF1 DO
        PRINT LINE
    REPEAT
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 loops reading lines from the file and displaying them, until the end of the file. Finally, the file is closed.