reduce-historical/r38/doc/help/command.tex

\section{General Commands}

\begin{Command}{BYE}
The \name{bye} command ends the REDUCE session, returning control to the
program (e.g., the operating system) that called REDUCE.  When you are at
the top level, the \name{bye} command exits REDUCE. \name{quit} is a
synonym for \name{bye}.

\end{Command}

\begin{Command}{CONT}
The command \name{cont} returns control to an interactive file after a
\nameref{pause} command that has been answered with \name{n}.

\begin{Examples}
\explanation{Suppose you are in the middle of an interactive file.} \\
   & factorize(x**2 + 17*x + 60); \\
   & \{\{X + 12,1\},\{X + 5,1\}\} \\
   pause; &          Cont? (Y or N) \\
n \\
saveas results; \\
factor1 := first results;    &    FACTOR1 := \{X + 12,1\} \\
factor2 := second results;   &    FACTOR2 := \{X + 5,1\} \\
cont;                        &    \explanationo{\em the file resumes}
\end{Examples}

\begin{Comments}
A \nameref{pause} allows you to enter your own REDUCE commands, change
switch values, inquire about results, or other such activities.  When you
wish to resume operation of the interactive file, use \name{cont}.

\end{Comments}
\end{Command}


\begin{Command}{DISPLAY}
\index{history}\index{interactive}
When given a numeric argument \meta{n}, \name{display} prints the \meta{n}
most recent input statements, identified by prompt numbers.  If an empty
pair of parentheses is given, or if \meta{n} is greater than the current
number of statements, all the input statements since the beginning of
the session are printed.
%%%INCONSISTENT??? {\em or}

\begin{Syntax}
\name{display}\(\meta{n}\) {\em or} \name{display}\(\)
\end{Syntax}

\meta{n} should be a positive integer.  However, if it is a real number, the
truncated integer value is used, and if a non-numeric argument is used, all
the input statements are printed.

\begin{Comments}
The statements are displayed in upper case, with lines split at semicolons or
dollar signs, as they are in editing.  If long files have been input during
the session, the \name{display} command is slow to format these for
printing.
\end{Comments}
\end{Command}


\begin{Command}{LOAD\_PACKAGE}
\index{package}
The \name{load\_package} command is used to load REDUCE packages, such as
\name{gentran} that are not automatically loaded by the system.
\begin{Syntax}
\name{load\_package "}\meta{package\_name}\name{"}
\end{Syntax}

%%% We should probably list the names of the packages here.
A package is only loaded once; subsequent calls of \name{load\_package}
for the same package name are ignored.
\end{Command}


\begin{Command}{PAUSE}
\index{interactive}
The \name{pause} command, given in an interactive file, stops operation and
asks if you want to continue or not.

\begin{Examples}
\explanation{An interactive file is running, and at some point you see the
question} \\
				   Cont? (Y or N) \\
\explanation{If you type} \\
y\key{Return}\\
\explanation{the file continues to run until the next pause or the end.} \\
\explanation{If you type } \\
n\key{Return} \\
\explanation{you will get a numbered REDUCE prompt, and be allowed to
enter and execute any REDUCE statements.  If you later wish to continue with
the file, type} \\
cont; \\
\explanation{and the file resumes.}
\end{Examples}

To use \name{pause} in your own interactive files, type

\name{pause;}


in the file wherever you want it.


\begin{Comments}
\name{pause} does not allow you to continue without typing either \name{y}
or \name{n}.  Its use is to slow down scrolling of interactive files, or to
let you change parameters or switch settings for the calculations.

If you have stopped an interactive file at a \name{pause,} and do not wish to
resume the file, type \name{end;}.  This does not end the REDUCE session, but
stops input from the file.  A second \name{end;} ends the REDUCE session.
However, if you have pauses from more than one file stacked up, an \name{end;}
brings you back to the top level, not the file directly above.

A \name{pause} typed from the terminal has no effect.
\end{Comments}
\end{Command}


\begin{Command}{QUIT}
The \name{quit} command ends the REDUCE session, returning control to the
program (e.g., the operating system) that called REDUCE.  When you are at
the top level, the \name{quit} command exits REDUCE. \nameref{bye} is a
synonym for \name{quit}.

\end{Command}


\begin{Operator}{RECLAIM}
\index{memory}
\begin{Comments}
REDUCE's memory is in a storage structure called a heap.  As REDUCE
statements execute, chunks of memory are used up.  When these chunks are no
longer needed, they remain idle.  When the memory is almost full,
the system executes a garbage collection, reclaiming space that is no
longer needed, and putting all the free space at one end.  Depending on
the size of the image REDUCE is using,
garbage collection needs to be done more or less often.  A
larger image means fewer but longer garbage collections.
Regardless of memory size,
if you ask REDUCE to do something ridiculous, like \name{factorial(2000)}, it may
garbage collect many times. 
\end{Comments}
\end{Operator}


\begin{Command}{REDERR}
\index{error handling}
The \name{rederr} command allows you to print an error message from inside
a \nameref{procedure} or a \nameref{block} statement.  
The calculation is gracefully terminated.
\begin{Syntax}
\name{rederr} \meta{message}
\end{Syntax}

\meta{message} is an error message, usually inside double quotation marks
(a \nameref{string}).

\begin{Examples}
\begin{multilineinput}
procedure fac(n);
   if not (fixp(n) and n>=0)
     then  rederr "Choose nonneg. integer only"
    else for i := 0:n-1 product i+1;
\end{multilineinput}     &
fac \\
fac a;                   &
	   ***** Choose nonneg. integer only \\
fac 5;               &  120
\end{Examples}
\begin{Comments}
The above procedure finds the factorial of its argument.
If n is not a positive integer or 0, an error message is returned.

If your procedure is executed in a file, the usual error message is 
printed, followed by \name{Cont? (Y or N)}, just as any other error does from
a file.  Although the procedure is gracefully terminated, any switch settings or
variable assignments you made before the error occurred are not undone.  If you
need to clean up such items before exiting, use a group statement, with the
\name{rederr} command as its last statement.
\end{Comments}
\end{Command}


\begin{Command}{RETRY}
\index{interactive}
The \name{retry} command allows you to retry the latest statement that resulted
in an error message.

\begin{Examples}
matrix a; \\
det a;                      &              ***** Matrix A not set \\
a := mat((1,2),(3,4));      & \begin{multilineoutput}{6cm}
A(1,1) := 1
A(1,2) := 2
A(2,1) := 3
A(2,2) := 4
\end{multilineoutput}\\
retry;                     &               -2
\end{Examples}
\begin{Comments}
\name{retry} remembers only the most recent statement that resulted in an
error message.  It allows you to stop and fix something obvious, then
continue on your way without retyping the original command.
\end{Comments}
\end{Command}


\begin{Command}{SAVEAS}
The \name{saveas} command saves the current workspace under the name of its
argument.
\begin{Syntax}
\name{saveas} \meta{identifier}
\end{Syntax}

\meta{identifier} can be any valid REDUCE identifier.

\begin{Examples}

\explanation{(The numbered prompts are shown below, unlike in most examples)}\\
1: solve(x^2-3);&
\{x=sqrt(3),x= - sqrt(3)\}\\
2: saveas rts(0)\$\\
3: rts(0);&
\{x=sqrt(3),x= - sqrt(3)\}\\
\end{Examples}
\begin{Comments}
\name{saveas} works only for the current workspace, the last algebraic
expression produced by REDUCE.  This allows you to save a result that you
did not assign to an identifier when you originally typed the input.
For access to previous output use \nameref{ws}.
\end{Comments}
\end{Command}


\begin{Command}{SHOWTIME}
\index{time}
The \name{showtime} command prints the elapsed system time since the last
call of this command or since the beginning of the session, if it has not
been called before.


\begin{Examples}
showtime;                    &      Time: 1020 ms \\
factorize(x^4 - 8x^4 + 8x^2 - 136x - 153);
			     &      \{X - 9,X^{2} + 17,X + 1\} \\
showtime;                    &      Time: 920 ms
\end{Examples}
\begin{Comments}
The time printed is either the elapsed cpu time or the elapsed wall clock
time, depending on your system.  \name{showtime} allows you to see the
system time resources REDUCE uses in its calculations.  Your time readings
will of course vary from this example according to the system you use.
\end{Comments}
\end{Command}


\begin{Command}{WRITE}
\index{output}
The \name{write} command explicitly writes its arguments to the output device
(terminal or file).
\begin{Syntax}
\name{write} \meta{item}\{,\meta{item}\}\optional
\end{Syntax}


\meta{item} can be an expression, an assignment or a \nameref{string}
enclosed in double quotation marks (\name{"}).

\begin{Examples}
write a, sin x, "this is a string";       &     ASIN(X)this is a string \\
write a," ",sin x," this is a string";    &      A SIN(X) this is a string \\
if not numberp(a) then write "the symbol ",a;
							&     the symbol A \\
array m(10); \\
for i := 1:5 do write m(i) := 2*i;                      &
\begin{multilineoutput}{6cm}
M(1) := 2
M(2) := 4
M(3) := 6
M(4) := 8
M(5) := 10
\end{multilineoutput}\\
m(4);                                                   &     8
\end{Examples}

\begin{Comments}
The items specified by a single \name{write} statement print on a single line
unless they are too long.  A printed line is always ended with a carriage
return, so the next item printed starts a new line.

When an assignment statement is printed, the assignment is also made.  This
allows you to get feedback on filling slots in an array with a \nameref{for}
 statement, as shown in the last example above.
\end{Comments}
\end{Command}