The mvBASIC command clause, UREADLINE, reads data from a previously opened file on the host system. 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 from by positioning the file pointer before executing the command.
Format
|
UREADLINE var FROM FileHandle {UNTIL delimiter} THEN statement(s) ELSE statement(s) |
Description
UREADLINE reads the file currently opened to the file variable, FileHandle, starting at the current file pointer position up to but not including the delimiter or until an EOF mark is reached. The delimiter can be any single character and if not specified, the character line-feed (0x0a) is used. The resulting string value is assigned to the variable var. If an error occurs, the ELSE clause executes and UERROR() 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 UERROR() 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 UERROR() 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 UERROR() returns the Windows error message 38 (ERROR_HANDLE_EOF).
If errors other than EOF occur during a UREADLINE the ELSE clause is taken, the var contains the data read up to the error and the UERROR() returns an appropriate error code.
For example, the statement below generates the behavior as shown in the table. The File Contents describes the content of the host file for the example. EOF indicates the actual End of File, var is the value returned. THEN/ELSE indicates which of the THEN or ELSE clauses is taken and UERROR() indicates what the value returned by an immediate call to the UERROR() function would return.
|
UREADLINE var FROM filehandle UNTIL ';' THEN/ELSE clause |
|
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 |
This example prints the first line (delimited by a line-feed) of the file \books\chap5.txt. 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 |
See Also