ureadline() function

A file on the host system is represented as an unformatted string of bytes without internal delimiters or markers. READ and WRITE commands provide sequential access to files by advancing a pointer within the file. Subsequent READ or WRITE commands advance this internal pointer from the current position in the file. The user may specify the exact location within a file to be read by positioning the file pointer at the preferred location before executing the command.

Format

UREADLINE var FROM FileHandle {UNTIL delimiter} THEN statement(s) ELSE statement(s)

Description

The ureadline() function reads the file currently opened to the file variable, FileHandle. It starts at the current file pointer position and reads up to (but not including) the delimiter, or until an EOF mark is reached. The delimiter can be any single character. If not specified, the character line-feed (0x0a) is used. The resulting string value is assigned to the var variable. If an error occurs, the ELSE clause executes and the uerror() command returns the appropriate error code. The file pointer is advanced by the number of bytes read.

Note: The file must be opened to be read.

If the ureadline command is used before opening the file for reading, an error results. The ELSE clause executes, the var is not changed, and the uerror() command returns the appropriate error code.
If any data is successfully read, then the THEN clause is taken. The var contains the data read and the value returned by the uerror() command is the number of bytes read.
If no data is successfully read due to an EOF being encountered immediately, the ELSE clause is taken. The var is set to NULL and the uerror() command returns the Windows error message 38: (ERROR_HANDLE_EOF).
If errors other than EOF occur during the ureadline command, the ELSE clause is taken, the var contains the data read up to the error, and the uerror() command returns an appropriate error code.

Example(s)

For example, the following statement generates the behavior as shown in the table.

UREADLINE var FROM filehandle UNTIL ';' THEN/ELSE clause

The Host File Contents column describes the content of the host file for the example.
EOF indicates the actual End of File.
The var column is the value returned.
The THEN/ELSE column indicates which of the THEN or ELSE clauses is taken.
The UERROR() column indicates what the value returned by an immediate call to theuerror() function would return.

Table 1:
Host File Contents	var	THEN/ELSE	UERROR( )
EOF	""	ELSE	38
";EOF"	"" ""	THEN ELSE	0 38
";;EOF"	"" "" ""	THEN THEN ELSE	0 0 38
"ABCEOF"	"ABC" ""	THEN ELSE	3 38
"ABC;EOF"	"ABC" ""	THEN ELSE	3 38
"ABC;;EOF"	"ABC" "" ""	THEN THEN ELSE	3 0 38
"ABC;XYZEOF"	"ABC" "XYZ" ""	THEN THEN ELSE	3 3 38
"ABC;XYZ;;EOF"	ABC" "XYZ" ""	THEN THEN ELSE	3 3 38
";ABC;;XYZ;;EOF"	"" "ABC" "" "XYZ" "" ""	THEN THEN THEN THEN THEN ELSE	0 3 0 3 0 38

The following example prints the first line (delimited by a line-feed) of the \books\chap5.txt file. A null string is returned if the file pointer is positioned at the end of the file.

FILENAME="c:\books\chap5.txt"
LF = CHAR(10)
UOPEN FILENAME FOR READ TO FILEDES ELSE
   PRINT "Unable to open ":FILENAME
   STOP
END
UREADLINE VAR1 FROM FILEDES UNTIL LF ELSE GOTO   EOJ:
END
PRINT VAR1

ureadline() function

Format

Description

Example(s)

See also