reduce-historical/r38/doc/manual/io.tex

\chapter{File Handling Commands}\index{File handling}

In many applications, it is desirable to load previously prepared {\REDUCE}
files into the system, or to write output on other files. {\REDUCE} offers
four commands for this purpose, namely, {\tt IN}, {\tt OUT}, {\tt SHUT},
{\tt LOAD}, and {\tt LOAD\_PACKAGE}.  The first\ttindex{IN}\ttindex{OUT}
\ttindex{SHUT} three operators are described here; {\tt LOAD} and {\tt
LOAD\_PACKAGE} are discussed in Section~\ref{sec-load}.

\section{IN Command}\ttindex{IN}
This command takes a list of file names as argument and directs the system
to input\index{Input} each file (that should contain {\REDUCE} statements
and commands) into the system.  File names can either be an identifier or
a string.  The explicit format of these will be system dependent and, in
many cases, site dependent.  The explicit instructions for the
implementation being used should therefore be consulted for further
details. For example:
\begin{verbatim}
        in f1,"ggg.rr.s";
\end{verbatim}
will first load file {\tt F1}, then {\tt ggg.rr.s}.  When a semicolon is
used as the terminator of the IN statement, the statements in the file are
echoed on the terminal or written on the current output file.  If \$
\index{Command terminator} is used as the terminator, the input is not
shown.  Echoing of all or part of the input file can be prevented, even if
a semicolon was used, by placing an {\tt off echo;}\ttindex{ECHO} command
in the input file.

Files to be read using {\tt IN} should end with {\tt ;END;}.  Note the two
semicolons!  First of all, this is protection against obscure difficulties
the user will have if there are, by mistake, more {\tt BEGIN}s than
{\tt END}s on the file.  Secondly, it triggers some file control book-keeping
which may improve system efficiency.  If {\tt END} is omitted, an error
message {\tt "End-of-file read"} will occur.

\section{OUT Command}\ttindex{OUT}
This command takes a single file name as argument, and directs output to
that file from then on, until another {\tt OUT} changes the output file,
or {\tt SHUT} closes it.  Output can go to only one file at a time,
although many can be open.  If the file has previously been used for
output during the current job, and not {\tt SHUT},\ttindex{SHUT} the new
output is appended to the end of the file.  Any existing file is erased
before its first use for output in a job, or if it had been {\tt SHUT}
before the new {\tt OUT}.

To output on the terminal without closing the output file, the reserved
file name T (for terminal) may be used.  For example,
{\tt out ofile;} will direct output to the file {\tt OFILE} and
{\tt out t;} will direct output to the user's terminal.

The output sent to the file will be in the same form that it would have on
the terminal.  In particular {\tt x\verb|^|2} would appear on two lines, an
{\tt X} on the lower line and a 2 on the line above.  If the purpose of the
output file is to save results to be read in later, this is not an
appropriate form.  We first must turn off the {\tt NAT} switch that
specifies that output should be in standard mathematical notation.

{\it Example:} To create a file {\tt ABCD} from which it will be possible
to read -- using {\tt IN} -- the value of the expression {\tt XYZ}:
\begin{verbatim}
 off echo$      % needed if your input is from a file.
 off nat$       % output in IN-readable form. Each expression
                % printed will end with a $ .
 out abcd$      % output to new file
 linelength 72$ % for systems with fixed input line length.
 xyz:=xyz;      % will output "XYZ := " followed by the value
                % of XYZ
 write ";end"$  % standard for ending files for IN
 shut abcd$     % save ABCD, return to terminal output
 on nat$                % restore usual output form
\end{verbatim}

\section{SHUT Command}\ttindex{SHUT}
This command takes a list of names of files that have been previously
opened via an {\tt OUT} statement and closes them. Most systems require this
action by the user before he ends the {\REDUCE} job (if not sooner),
otherwise the output may be lost. If a file is shut and a further {\tt OUT}
command issued for the same file, the file is erased before the new output
is written.

If it is the current output file that is shut, output will switch to the
terminal.  Attempts to shut files that have not been opened by {\tt OUT},
or an input file, will lead to errors.