## `read` -- search, read, and execute a file

#### Introduction

`read``(filename)` searches for the file `filename` in certain directories, reads and executes it.

`read``(n)` reads and executes the file associated with the file descriptor `n`.

#### Call(s)

`read(filename <, Quiet> <, Plain>)`
`read(n <, Quiet> <, Plain>)`

#### Parameters

`filename` | - | the name of a file: a character string
`n` | - | a file descriptor provided by `fopen`: a positive integer

#### Options

`Plain` | - | makes `read` use its own parser context
`Quiet` | - | suppresses output during execution of `read`

#### Returns

the return value of the last statement of the file.

#### Related Functions

`fclose`, `finput`, `fopen`, `fprint`, `fread`, `ftextinput`, `input`, `LIBPATH`, `loadproc`, `pathname`, `print`, `protocol`, `READPATH`, `textinput`, `write`, `WRITEPATH`

#### Details

- `read``(filename)` searches for the file in various directories:
  - First, the name is interpreted as a relative file name: `filename` is concatenated to each directory given by the environment variable `READPATH`.
  - Then the file name is interpreted as an absolute path name.
  - Then the file name is interpreted relative to the ``working directory''.
  - Last, the file name is concatenated to each directory given by the environment variable `LIBPATH`.
  If a file can be opened with one of this names, then the file is read and executed with `fread`.

- Please note that the ``working directory'', which is used to interpret relative file names, depends on the operating system. On Windows systems, the ``working directory'' is the folder, where MuPAD is installed. On UNIX or Linux systems, it is the directory where MuPAD was started.
- A path separator (```/`'' on UNIX or Linux, ```\`'' on Windows and ```:`'' on the Macintosh) is inserted as neccessary when concatenating a given path and `filename`.
- On the Macintosh, an empty file name may be given. In this case a dialogue box is opened in which the user can choose a file.
- `read``(n)` with a file descriptor `n` as returned by `fopen` is equivalent to the call `fread(n)`.
- See the function `fread` for details about reading and executing the file's content and for a detailed description of the options Plain and Quiet.

#### Example 1

The following example only works under UNIX and Linux; on other operating systems one must change the path names accordingly. First, we use `write` to store values in the file ```testfile.mb`'' in the ```/tmp`'' directory:

    >> a := 3: b := 5: write("/tmp/testfile.mb", a, b):

The following command specifies the file by its absolute path name. After reading the file, the values of `a` and `b` are restored:

    >> delete a, b: read("/tmp/testfile.mb"): a, b

                                       3, 5

Alternatively, we define ```/tmp`'' as the search directory and provide a relative path name. Note that the path separator ```/`'' is inserted by `read`:

    >> delete a, b: READPATH := "/tmp": read("testfile.mb"): a, b

                                       3, 5

We may also use `fopen` to open the file and read its content. Note that `fopen` does not search for the file like `read`, thus we must enter an absolute path name or a name relative to the working directory:

    >> delete a, b:
       n := fopen("/tmp/testfile.mb"): read(n): fclose(n):
       a, b

                                       3, 5

    >> delete a, b, READPATH, n

#### Changes

- The new option Plain was introduced.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000