## `protocol` -- create a protocol of a MuPAD session

#### Introduction

`protocol(`filename`)` starts a protocol of the current MuPAD session in the file with the name `filename`.

`protocol(`n`)` writes into the file associated with the file descriptor `n`.

`protocol(``)` stops the protocol.

#### Call(s)

`protocol(filename <, InputOnly>)`
`protocol(n <, InputOnly>)`
`protocol()`

#### Parameters

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

#### Options

`InputOnly` | - | only input is protocolled

#### Returns

the void object of type `DOM_NULL`.

#### Side Effects

The function is sensitive to the environment variable `WRITEPATH`. If this variable has a value, then the protocol file is created in the corresponding directory. Otherwise, the file is created in the ``current working directory''.

#### Related Functions

`fclose`, `finput`, `fopen`, `fprint`, `fread`, `ftextinput`, `pathname`, `print`, `read`, `READPATH`, `write`, `WRITEPATH`

#### Details

- `protocol` writes a protocol of input commands and corresponding MuPAD output to a text file.
- The file may be specified directly by its name. This either creates a new file or overwrites an existing file. `protocol` opens and closes the file automatically.

  If `WRITEPATH` does not have a value, `protocol` 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. Further, on the interactive level, MacMuPAD warns the user, if an existing file is about to be overwritten.

  Also absolute path names are processed by `protocol`.

- Alternatively, the file may be specified by a file descriptor `n`. In this case, the file must have been opened via `fopen``(Text, filename, Write)` or `fopen``(Text, filename, Append)`. This returns the file descriptor as an integer `n`. Note that `fopen``(filename)` opens the file in read-only mode. A subsequent `protocol` command to this file causes an error.

  The file is not closed automatically by `protocol(``)` and must be closed by a subsequent call to `fclose`.

- A call of `protocol` without arguments terminates a running protocol and closes the corresponding file. Closing the protocol file with `fclose` also terminates the protocol.
- If a new protocol is started while a protocol is running, then the old one is terminated and the corresponding file is closed.

#### Option: InputOnly

- The protocol file only contains the input lines. All output is omitted.

#### Example 1

We open a text file `test` in write mode with `fopen`:

    >> n := fopen(Text, "test", Write):

A protocol is written into this file:

    >> protocol(n):
       1 + 1, a/b;
       solve(x^2 = 2)
       protocol():

The file now has the following content:

          1 + 1, a/b;

                                          a
                                       2, -
                                          b
          solve(x^2 = 2)

                                   1/2           1/2
                            {[x = 2   ], [x = - 2   ]}
          protocol():

#### Example 2

The protocol file is opened directly by `protocol`. Only input is protocolled:

    >> protocol("test", InputOnly):
       1 + 1; a/b;
       solve(x^2 = 2)
       protocol():

The file now has the following content:

          1 + 1; a/b;
          solve(x^2 = 2)
          protocol():

#### Changes

- The new option InputOnly was introduced.

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