UREAD Command

The UREAD command 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 subdividers 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. See ULSEEK Function for additional information.

Format

UREAD var FROM FileHandle FOR n THEN statement(s) ELSE statement(s)

Description

UREAD reads the file currently opened to the file variable FileHandle for the number of bytes specified by n or until an EOF mark is reached. n indicates the number of contiguous bytes from the current file pointer position to be read. 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 UREAD command is used before opening the file for reading, an error results, the ELSE clause executes, and UERROR( ) returns the appropriate error code.
If any data is successfully read, the ELSE clause is not taken. In that case, UERROR( ) returns the number of bytes read.
If an EOF is encountered, the value returned by UERROR( ) is less than the requested amount.
If no EOF is encountered, the value returned by UERROR( ) is equal to the requested amount.
If no data is successfully read due to an EOF being encountered immediately, the ELSE clause is taken, no data is returned and UERROR( ) returns the Windows error message 38: ERROR_HANDLE_EOF.
If errors other than EOF occur during a UREAD the ELSE clause is taken, no data is returned, UERROR( ) returns the appropriate error code.

Examples

UOPEN "C:\TEST.TXT" TO HANDLE ELSE STOP

10 UREAD ITEM FROM HANDLE FOR 500 THEN

PRINT UERROR( )

END ELSE

PRINT "ERROR CODE = ": UERROR( )

GOTO EOJ:

END

GOTO 10

If TEST.TXT is 943 bytes the output is:

500

443

ERROR CODE = 38

The next example prints the first 50 bytes of the file \books\chap5.txt. If less than 50 bytes are present, the bytes available are printed. A null string is returned if the file pointer is positioned at the end of the file. Line feed characters embedded in the file are also printed.

FILENAME="c:\books\chap5.txt"

UOPEN FILENAME FOR READ TO FILEDES ELSE

PRINT "Unable to open ":FILENAME

STOP

END

UREAD VAR1 FROM FILEDES FOR 50 ELSE GOTO EOJ:

PRINT VAR1

After execution of the following example, the string TESTDATA2 is equal to TESTDATA1. \books\chap6.txt was created using the UCREATE statement which opened the file for writing only.

TESTDATA1 = "THIS IS TEST DATA"

FILENAME="c:\books\chap6.txt"

UCREATE FILENAME TO FILEDES2 ELSE

PRINT "Unable to create and open ":FILENAME

STOP

END

* Write out DATA and CLOSE

UWRITE TESTDATA1 ON FILEDES2 ELSE

PRINT "Write to ":FILENAME:" failed"

END

UCLOSE FILEDES2 ELSE

PRINT "UCLOSE failed on ":FILENAME

END

UOPEN FILENAME TO FILEDES3 ELSE STOP

UREAD TESTDATA2 FROM FILEDES3 FOR 17 ELSE GO TO EOJ: