protocol

Create a protocol of a session

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

protocol(filename | n, <InputOnly | OutputOnly>)
protocol()

Description

protocol(file) starts a protocol of the current MuPAD® terminal session.

protocol() stops the protocol.

protocol writes a protocol of input commands and corresponding MuPAD output of a terminal session to a text file.

When used from the MuPAD Notebook app, protocol is disabled and raises an error.

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 the filename ends in ".gz", MuPAD will write a gzip-compressed text file.

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 Microsoft® Windows® systems and on Mac OS X systems, the "working directory" is the folder where MuPAD is installed. On UNIX® systems, it is the current working directory in which MuPAD was started; when started from a menu or desktop item, this is typically the user's home directory.

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 if it has been opened by protocol. 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.

Environment Interactions

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."

Examples

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():
fclose(n):

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():

Example 3

The protocol file is opened directly by protocol. Only output is protocolled:

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

The file now has the following content:


     a
  2, -
     b

         1/2           1/2
  {[x = 2   ], [x = - 2   ]}

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

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

OutputOnly

Only output is protocolled

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

Return Values

Void object of type DOM_NULL.

See Also

MuPAD Functions

Was this topic helpful?