# 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 by positioning the file pointer at the preferred location before executing the command.

 See [ulseek() function](https://d3codex.com/pickbasic-flashbasic/ulseek-function/) for additional information.

## Format

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

## Description

The uread command 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. The *n* variable indicates the number of
 contiguous bytes to be read from the current file pointer position. 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 uread command is used before opening the file for reading, an error results, the ELSE clause executes, and the uerror() command returns the appropriate error code.

- If any data is successfully read, the ELSE clause is not taken. In that case, the uerror() command returns the number of bytes read.

- If an EOF is encountered, the value returned by the uerror() command is less than the requested amount.

- If no EOF is encountered, the value returned by the uerror() command 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 the uerror() command returns the Windows error message 38: ERROR_HANDLE_EOF.

- If errors other than EOF occur during the uread command, the ELSE clause is taken, no data is returned, and the uerror() command returns the appropriate error code.

## Example(s)

```
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 following example prints the first 50 bytes of the \books\chap5.txt
 file. 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. The
 \books\chap6.txt file 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:
```

## See also

- [O/S interoperability commands and functions](https://d3codex.com/pickbasic-flashbasic/os-interoperability-commands/)
- [uclose command](https://d3codex.com/pickbasic-flashbasic/uclose-command/)
- [ucreate command](https://d3codex.com/pickbasic-flashbasic/ucreate-command/)
- [udelete command](https://d3codex.com/pickbasic-flashbasic/udelete-command/)
- [uerror() function](https://d3codex.com/pickbasic-flashbasic/uerror-function/)
- [uexecute command](https://d3codex.com/pickbasic-flashbasic/uexecute-command/)
- [ulock command](https://d3codex.com/pickbasic-flashbasic/ulock-command/)
- [ulseek() function](https://d3codex.com/pickbasic-flashbasic/ulseek-function/)
- [umessage command](https://d3codex.com/pickbasic-flashbasic/umessage-command/)
- [uopen command](https://d3codex.com/pickbasic-flashbasic/uopen-command/)
- [ureadline() function](https://d3codex.com/pickbasic-flashbasic/ureadline-function/)
- [usystem() function](https://d3codex.com/pickbasic-flashbasic/usystem-function/)
- [uwaitfor command](https://d3codex.com/pickbasic-flashbasic/uwaitfor-command/)
- [uwrite command](https://d3codex.com/pickbasic-flashbasic/uwrite-command/)

---
Source: https://d3codex.com/pickbasic-flashbasic/uread-command/ - part of the D3Codex reference.