## `finput` -- read MuPAD objects from a file

#### Introduction

`finput(`filename, x`)` reads a MuPAD object from a file and assigns it to the identifier `x`.

`finput(`n, x`)` reads from the file associated with the file descriptor `n`.

#### Call(s)

`finput(filename)`
`finput(filename, x1, x2...)`
`finput(n)`
`finput(n, x1, x2...)`

#### Parameters

`filename` | - | the name of a file: a character string
`n` | - | a file descriptor provided by `fopen`: a positive integer
`x1, x2...` | - | identifiers

#### Returns

the last object that was read from the file.

#### Related Functions

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

#### Details

- `finput` can read MuPAD binary files as well as ASCII text files. `finput` recognizes the format of the file automatically.

  Binary files may be created via `fprint` or `write`. Text files can also be created in a MuPAD session via these functions (using the Text option; see the corresponding help pages for details). Alternatively, text files can be created and edited directly using your favourite text editor. The file must consist of syntactically correct MuPAD objects or statements, separated by semicolons or colons. An object may extend over more than one line.

- `finput(`filename`)` reads the first object in the file and returns it to the MuPAD session.
- `finput(`filename, x1, x2, ...`)` reads the contents of a file object by object. The i-th object is assigned to the identifier x.i. The identifiers are not evaluated while executing `finput`; previously assigned values are overwritten. The objects are not evaluated. Evaluation can be enforced with the function `eval`. Cf. example 2.
- Instead of a file name, also a file descriptor `n` of a file opened via `fopen` can be used. The functionality is as described above. However, there is one difference: With a file name, the file is closed automatically after the data were read. A subsequent call to `finput` starts at the beginning of the file. With a file descriptor, the file remains open (use `fclose` to close the file). The next time data are read from this file, the reading continues at the current position. Consequently, a file descriptor should be used if the individual objects in the file are to be read via several subsequent calls of `finput`. Cf. example 3.
- If the number of identifiers specified in the `finput` call is larger than the number of objects in the file, the exceeding identifiers are not assigned any values. In such a case, `finput` returns the void object of type `DOM_NULL`.
- `finput` interprets the file name as a pathname relative to the ``working directory''.

  Note that the meaning of ``working directory'' 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 current working directory in which MuPAD was started.

  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.

  Also absolute path names are processed by `finput`.

- Expression sequences are not flattened by `finput` and cannot be used to pass several identifiers to `finput`. Cf. example 4.
- `finput` is a function of the system kernel.

#### Example 1

We write the numbers 11, 22, 33 and 44 into a file:

    >> fprint("test", 11, 22, 33, 44):

We read this file with `finput`:

    >> finput("test", x1, x2, x3, x4)

                                        44

    >> x1, x2, x3, x4

                                  11, 22, 33, 44

If we try to read more objects than stored in the file, `finput` returns the void object of type `DOM_NULL`:

    >> finput("test", x1, x2, x3, x4, x5); domtype(%)

                                     DOM_NULL

    >> x1, x2, x3, x4, x5

                                11, 22, 33, 44, x5

    >> delete x1, x2, x3, x4:

#### Example 2

Objects read from a file are not evaluated:

    >> fprint("test", x1): x1 := 23: finput("test")

                                        x1

    >> eval(%)

                                        23

    >> delete x1:

#### Example 3

We read some data from a file using several calls of `finput`. We have to use a file descriptor for reading from the file. The file is opened for reading with `fopen`:

    >> fprint("test", 11, 22, 33, 44): n := fopen("test"):

The file descriptor returned by `fopen` can be passed to `finput` for reading the data:

    >> finput(n, x1, x2): x1, x2

                                      11, 22

    >> finput(n, x3, x4): x3, x4

                                      33, 44

Finally, we close the file and delete the identifiers:

    >> fclose(n): delete n, x1, x2, x3, x4:

Alternatively, the contents of a file can be read into a MuPAD session in the following way:

    >> n := fopen("test"):
       for i from 1 to 4 do
          x.i := finput(n)
       end_for:
       x1, x2, x3, x4

                                  11, 22, 33, 44

    >> fclose(n): delete n, i, x1, x2, x3, x4:

#### Example 4

Expression sequences are not flattened by `finput` and cannot be used to pass identifiers to `finput`:

    >> fprint("test", 11, 22, 33): finput("test", (x1, x2), x3)

          Error: Illegal argument [finput]

The following call does not lead to an error because the identifier `x12` is not evaluated. Consequently, only one object is read from the file and assigned to `x12:`

    >> x12 := x1, x2: finput("test", x12): x1, x2, x12

                                    x1, x2, 11

    >> delete x12:

#### Changes

- no changes

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