# ureadline() function

The ureadline() function 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 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.

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

## 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/)
- [uread command](https://d3codex.com/pickbasic-flashbasic/uread-command/)
- [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/ureadline-function/ - part of the D3Codex reference.