path: root/src/hyper/pages/ug16.ht

% Copyright The Numerical Algorithms Group Limited 1992-94. All rights reserved.
% !! DO NOT MODIFY THIS FILE BY HAND !! Created by ht.awk.
\texht{\setcounter{chapter}{0}}{} % Appendix A

\newcommand{\lanb}{{\tt [}}
\newcommand{\ranb}{{\tt ]}}
\newcommand{\vertline}{\texht{$|$}{{\tt |}}}

%
\newcommand{\ugSysCmdTitle}{\Language{} System Commands}
\newcommand{\ugSysCmdNumber}{B.}
%
% =====================================================================
\begin{page}{ugSysCmdPage}{B. \Language{} System Commands}
% =====================================================================
\beginscroll

\texht{\bgroup\baselineskip 10pt\ixpt{}\def\Isize{\SIsize}}{}

This chapter describes system commands, the command-line
facilities used to control the \Language{} environment.
The first section is an introduction and discusses the common
syntax of the commands available.

\table{
  { \downlink{\menuitemstyle{A.1. Introduction}}{ugSysCmdOverviewPage} }
  { \downlink{\menuitemstyle{A.2. )abbreviation}}{ugSysCmdabbreviationPage} }
  { \downlink{\menuitemstyle{A.3. )boot}}{ugSysCmdbootPage} }
  { \downlink{\menuitemstyle{A.4. )cd}}{ugSysCmdcdPage} }
  { \downlink{\menuitemstyle{A.5. )close}}{ugSysCmdclosePage} }
  { \downlink{\menuitemstyle{A.6. )clear}}{ugSysCmdclearPage} }
  { \downlink{\menuitemstyle{A.7. )compile}}{ugSysCmdcompilePage} }
  { \downlink{\menuitemstyle{A.8. )display}}{ugSysCmddisplayPage} }
  { \downlink{\menuitemstyle{A.9. )edit}}{ugSysCmdeditPage} }
  { \downlink{\menuitemstyle{A.10. )fin}}{ugSysCmdfinPage} }
  { \downlink{\menuitemstyle{A.11. )frame}}{ugSysCmdframePage} }
  { \downlink{\menuitemstyle{A.12. )help}}{ugSysCmdhelpPage} }
  { \downlink{\menuitemstyle{A.13. )history}}{ugSysCmdhistoryPage} }
  { \downlink{\menuitemstyle{A.14. )library}}{ugSysCmdlibraryPage} }
  { \downlink{\menuitemstyle{A.15. )lisp}}{ugSysCmdlispPage} }
  { \downlink{\menuitemstyle{A.16. )load}}{ugSysCmdloadPage} }
  { \downlink{\menuitemstyle{A.17. )ltrace}}{ugSysCmdltracePage} }
  { \downlink{\menuitemstyle{A.18. )pquit}}{ugSysCmdpquitPage} }
  { \downlink{\menuitemstyle{A.19. )quit}}{ugSysCmdquitPage} }
  { \downlink{\menuitemstyle{A.20. )read}}{ugSysCmdreadPage} }
  { \downlink{\menuitemstyle{A.21. )set}}{ugSysCmdsetPage} }
  { \downlink{\menuitemstyle{A.22. )show}}{ugSysCmdshowPage} }
  { \downlink{\menuitemstyle{A.23. )spool}}{ugSysCmdspoolPage} }
  { \downlink{\menuitemstyle{A.24. )synonym}}{ugSysCmdsynonymPage} }
  { \downlink{\menuitemstyle{A.25. )system}}{ugSysCmdsystemPage} }
  { \downlink{\menuitemstyle{A.26. )trace}}{ugSysCmdtracePage} }
  { \downlink{\menuitemstyle{A.27. )undo}}{ugSysCmdundoPage} }
  { \downlink{\menuitemstyle{A.28. )what}}{ugSysCmdwhatPage} }
}
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdOverviewTitle}{Introduction}
\newcommand{\ugSysCmdOverviewNumber}{B.1.}
%
% =====================================================================
\begin{page}{ugSysCmdOverviewPage}{B.1. Introduction}
% =====================================================================
\beginscroll

System commands are used to perform \Language{} environment
management.
Among the commands are those that display what has been defined or
computed, set up multiple logical \Language{} environments
(frames), clear definitions, read files of expressions and
commands, show what functions are available, and terminate
\Language{}.

Some commands are restricted: the commands
%-% \HDsyscmdindex{set userlevel interpreter}{ugSysCmdOverviewPage}{B.1.}{Introduction}
%-% \HDsyscmdindex{set userlevel compiler}{ugSysCmdOverviewPage}{B.1.}{Introduction}
%-% \HDsyscmdindex{set userlevel development}{ugSysCmdOverviewPage}{B.1.}{Introduction}
\begin{verbatim}
)set userlevel interpreter
)set userlevel compiler
)set userlevel development
\end{verbatim}
set the user-access level to the three possible choices.
All commands are available at {\tt development} level and the fewest
are available at {\tt interpreter} level.
The default user-level is {\tt interpreter}.
%-% \HDindex{user-level}{ugSysCmdOverviewPage}{B.1.}{Introduction}
In addition to the \spadcmd{)set} command (discussed in \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in Section \ugSysCmdsetNumber\ignore{ugSysCmdset})
you can use the \HyperName{} settings facility to change the {\it user-level.}
\texht{}{Click on \lispmemolink{Settings}{(|htSystemVariables|)}
here to immediately go to the settings facility.}

Each command listing begins with one or more syntax pattern descriptions
plus examples of related commands.
The syntax descriptions are intended to be easy to read and do not
necessarily represent the most compact way of specifying all
possible arguments and options; the descriptions may occasionally
be redundant.

All system commands begin with a right parenthesis which should be in
the first available column of the input line (that is, immediately
after the input prompt, if any).
System commands may be issued directly to \Language{} or be
included in {\bf .input} files.
%-% \HDindex{file!input}{ugSysCmdOverviewPage}{B.1.}{Introduction}

A system command {\it argument} is a word that directly
follows the command name and is not followed or preceded by a
right parenthesis.
A system command {\it option} follows the system command and
is directly preceded by a right parenthesis.
Options may have arguments: they directly follow the option.
This example may make it easier to remember what is an option and
what is an argument:

\centerline{{{\tt )syscmd {\it arg1 arg2} )opt1 {\it opt1arg1 opt1arg2} )opt2 {\it opt2arg1} ...}}}

In the system command descriptions, optional arguments and options are
enclosed in brackets (``\lanb'' and ``\ranb'').
If an argument or option name is in italics, it is
meant to be a variable and must have some actual value substituted
for it when the system command call is made.
For example, the syntax pattern description

\noindent
{\tt )read} {\it fileName} {\tt \lanb{})quietly\ranb{}}

\noindent
would imply that you must provide an actual file name for
{\it fileName} but need not use the {\tt )quietly} option.
Thus
\begin{verbatim}
)read matrix.input
\end{verbatim}
is a valid instance of the above pattern.

System command names and options may be abbreviated and may be in
upper or lower case.
The case of actual arguments may be significant, depending on the
particular situation (such as in file names).
System command names and options may be abbreviated to the minimum
number of starting letters so that the name or option is unique.
Thus
\begin{verbatim}
)s Integer
\end{verbatim}
is not a valid abbreviation for the {\tt )set} command,
because both {\tt )set} and {\tt )show}
begin with the letter ``s''.
Typically, two or three letters are sufficient for disambiguating names.
In our descriptions of the commands, we have used no abbreviations for
either command names or options.

In some syntax descriptions we use a vertical line ``\vertline''
to indicate that you must specify one of the listed choices.
For example, in
\begin{verbatim}
)set output fortran on | off
\end{verbatim}
only {\tt on} and {\tt off} are acceptable words for following
{\tt boot}.
We also sometimes use ``...'' to indicate that additional arguments
or options of the listed form are allowed.
Finally, in the syntax descriptions we may also list the syntax of
related commands.

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdabbreviationTitle}{)abbreviation}
\newcommand{\ugSysCmdabbreviationNumber}{B.2.}
%
% =====================================================================
\begin{page}{ugSysCmdabbreviationPage}{B.2. )abbreviation}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{abbreviation}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation}


\par\noindent{\bf User Level Required:} compiler

\par\noindent{\bf Command Syntax:}
\begin{items}
\item {\tt )abbreviation query  \lanb{}{\it nameOrAbbrev}\ranb{}}
\item {\tt )abbreviation category  {\it abbrev  fullname} \lanb{})quiet\ranb{}}
\item {\tt )abbreviation domain  {\it abbrev  fullname}   \lanb{})quiet\ranb{}}
\item {\tt )abbreviation package  {\it abbrev  fullname}  \lanb{})quiet\ranb{}}
\item {\tt )abbreviation remove  {\it nameOrAbbrev}}
\end{items}

\par\noindent{\bf Command Description:}

This command is used to query, set and remove abbreviations for category,
domain and package constructors.
Every constructor must have a unique abbreviation.
This abbreviation is part of the name of the subdirectory
under which the components of the compiled constructor are
stored.
%% BEGIN OBSOLETE
%% END OBSOLETE
Furthermore, by issuing this command you
let the system know what file to load automatically if you use a new
constructor.
Abbreviations must start with a letter and then be followed by
up to seven letters or digits.
Any letters appearing in the abbreviation must be in uppercase.

When used with the {\tt query} argument,
%-% \HDsyscmdindex{abbreviation query}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation}
this command may be used to list the name
associated with a  particular abbreviation or the  abbreviation for a
constructor.
If no abbreviation or name is given, the names and corresponding
abbreviations for {\it all} constructors are listed.

The following shows the abbreviation for the constructor \spadtype{List}:
\begin{verbatim}
)abbreviation query List
\end{verbatim}
The following shows the constructor name corresponding to the
abbreviation \spadtype{NNI}:
\begin{verbatim}
)abbreviation query NNI
\end{verbatim}
The following lists all constructor names and their abbreviations.
\begin{verbatim}
)abbreviation query
\end{verbatim}

To add an abbreviation for a constructor, use this command with
{\tt category}, {\tt domain} or {\tt package}.
%-% \HDsyscmdindex{abbreviation package}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation}
%-% \HDsyscmdindex{abbreviation domain}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation}
%-% \HDsyscmdindex{abbreviation category}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation}
The following add abbreviations to the system for a
category, domain and package, respectively:
\begin{verbatim}
)abbreviation domain   SET Set
)abbreviation category COMPCAT  ComplexCategory
)abbreviation package  LIST2MAP ListToMap
\end{verbatim}
If the {\tt )quiet} option is used,
no output is displayed from this command.
You would normally only define an abbreviation in a library source file.
If this command is issued for a constructor that has already been loaded, the
constructor will be reloaded next time it is referenced.  In particular, you
can use this command to force the automatic reloading of constructors.

To remove an abbreviation, the {\tt remove} argument is used.
%-% \HDsyscmdindex{abbreviation remove}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation}
This is usually
only used to correct a previous command that set an abbreviation for a
constructor name.
If, in fact, the abbreviation does exist, you are prompted
for confirmation of the removal request.
Either of the following commands
will remove the abbreviation \spadtype{VECTOR2} and the
constructor name \spadtype{VectorFunctions2} from the system:
\begin{verbatim}
)abbreviation remove VECTOR2
)abbreviation remove VectorFunctions2
\end{verbatim}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdbootTitle}{)boot}
\newcommand{\ugSysCmdbootNumber}{B.3.}
%
% =====================================================================
\begin{page}{ugSysCmdbootPage}{B.3. )boot}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{boot}{ugSysCmdbootPage}{B.3.}{)boot}


\par\noindent{\bf User Level Required:} development

\par\noindent{\bf Command Syntax:}
\begin{items}
\item {\tt )boot} {\it bootExpression}
\end{items}

\par\noindent{\bf Command Description:}

This command is used by \Language{} system developers to execute
expressions written in the BOOT language.
For example,
\begin{verbatim}
)boot times3(x) == 3*x
\end{verbatim}
creates and compiles the \Lisp{} function ``times3''
obtained by translating the BOOT code.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber
\downlink{``\ugSysCmdlispTitle''}{ugSysCmdlispPage} in section \ugSysCmdlispNumber
\downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber
\downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdcdTitle}{)cd}
\newcommand{\ugSysCmdcdNumber}{B.4.}
%
% =====================================================================
\begin{page}{ugSysCmdcdPage}{B.4. )cd}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{cd}{ugSysCmdcdPage}{B.4.}{)cd}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item {\tt )cd} {\it directory}
\end{items}

\par\noindent{\bf Command Description:}

This command sets the \Language{} working current directory.
The current directory is used for looking for
input files (for {\tt )read}),
\Language{} library source files (for {\tt )compile}),
saved history environment files (for {\tt )history )restore}),
compiled \Language{} library files (for \spadcmd{)library}), and
files to edit (for {\tt )edit}).
It is also used for writing
spool files (via {\tt )spool}),
writing history input files (via {\tt )history )write}) and
history environment files (via {\tt )history )save}),and
compiled \Language{} library files (via {\tt )compile}).
%-% \HDsyscmdindex{read}{ugSysCmdcdPage}{B.4.}{)cd}
%-% \HDsyscmdindex{compile}{ugSysCmdcdPage}{B.4.}{)cd}
%-% \HDsyscmdindex{history )restore}{ugSysCmdcdPage}{B.4.}{)cd}
%-% \HDsyscmdindex{edit}{ugSysCmdcdPage}{B.4.}{)cd}
%-% \HDsyscmdindex{spool}{ugSysCmdcdPage}{B.4.}{)cd}
%-% \HDsyscmdindex{history )write}{ugSysCmdcdPage}{B.4.}{)cd}
%-% \HDsyscmdindex{history )save}{ugSysCmdcdPage}{B.4.}{)cd}

If issued with no argument, this command sets the \Language{}
current directory to your home directory.
If an argument is used, it must be a valid directory name.
Except for the ``{\tt )}'' at the beginning of the command,
this has the same syntax as the operating system {\tt cd} command.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber
\downlink{``\ugSysCmdeditTitle''}{ugSysCmdeditPage} in section \ugSysCmdeditNumber
\downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber
\downlink{``\ugSysCmdlibraryTitle''}{ugSysCmdlibraryPage} in section \ugSysCmdlibraryNumber
\downlink{``\ugSysCmdreadTitle''}{ugSysCmdreadPage} in section \ugSysCmdreadNumber
\downlink{``\ugSysCmdspoolTitle''}{ugSysCmdspoolPage} in section \ugSysCmdspoolNumber

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdcloseTitle}{)close}
\newcommand{\ugSysCmdcloseNumber}{B.5.}
%
% =====================================================================
\begin{page}{ugSysCmdclosePage}{B.5. )close}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{close}{ugSysCmdclosePage}{B.5.}{)close}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )close}
\item{\tt )close )quietly}
\end{items}
\par\noindent{\bf Command Description:}

This command is used to close down interpreter client processes.
Such processes are started by \HyperName{} to run \Language{} examples
when you click on their text. When you have finished examining or modifying the
example and you do not want the extra window around anymore, issue
\begin{verbatim}
)close
\end{verbatim}
to the \Language{} prompt in the window.

If you try to close down the last remaining interpreter client
process, \Language{} will offer to close down the entire \Language{}
session and return you to the operating system by displaying something
like
\begin{verbatim}
   This is the last AXIOM session. Do you want to kill AXIOM?
\end{verbatim}
Type "y" (followed by the Return key) if this is what you had in mind.
Type "n" (followed by the Return key) to cancel the command.

You can use the {\tt )quietly} option to force \Language{} to
close down the interpreter client process without closing down
the entire \Language{} session.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber
\downlink{``\ugSysCmdpquitTitle''}{ugSysCmdpquitPage} in section \ugSysCmdpquitNumber



\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdclearTitle}{)clear}
\newcommand{\ugSysCmdclearNumber}{B.6.}
%
% =====================================================================
\begin{page}{ugSysCmdclearPage}{B.6. )clear}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{clear}{ugSysCmdclearPage}{B.6.}{)clear}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )clear all}
\item{\tt )clear completely}
\item{\tt )clear properties all}
\item{\tt )clear properties}  {\it obj1 \lanb{}obj2 ...\ranb{}}
\item{\tt )clear value      all}
\item{\tt )clear value}     {\it obj1 \lanb{}obj2 ...\ranb{}}
\item{\tt )clear mode       all}
\item{\tt )clear mode}      {\it obj1 \lanb{}obj2 ...\ranb{}}
\end{items}
\par\noindent{\bf Command Description:}

This command is used to remove function and variable declarations, definitions
and values  from the workspace.
To  empty the entire workspace  and reset the
step counter to 1, issue
\begin{verbatim}
)clear all
\end{verbatim}
To remove everything in the workspace but not reset the step counter, issue
\begin{verbatim}
)clear properties all
\end{verbatim}
To remove everything about the object {\tt x}, issue
\begin{verbatim}
)clear properties x
\end{verbatim}
To remove everything about the objects {\tt x, y} and {\tt f}, issue
\begin{verbatim}
)clear properties x y f
\end{verbatim}

The word {\tt properties} may be abbreviated to the single letter
``{\tt p}''.
\begin{verbatim}
)clear p all
)clear p x
)clear p x y f
\end{verbatim}
All definitions of functions and values of variables may be removed by either
\begin{verbatim}
)clear value all
)clear v all
\end{verbatim}
This retains whatever declarations the objects had.  To remove definitions and
values for the specific objects {\tt x, y} and {\tt f}, issue
\begin{verbatim}
)clear value x y f
)clear v x y f
\end{verbatim}
To remove  the declarations  of everything while  leaving the  definitions and
values, issue
\begin{verbatim}
)clear mode  all
)clear m all
\end{verbatim}
To remove declarations for the specific objects {\tt x, y} and {\tt f}, issue
\begin{verbatim}
)clear mode x y f
)clear m x y f
\end{verbatim}
The {\tt )display names} and {\tt )display properties} commands  may be used
to see what is currently in the workspace.

The command
\begin{verbatim}
)clear completely
\end{verbatim}
does everything that {\tt )clear all} does, and also clears the internal
system function and constructor caches.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmddisplayTitle''}{ugSysCmddisplayPage} in section \ugSysCmddisplayNumber
\downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber
\downlink{``\ugSysCmdundoTitle''}{ugSysCmdundoPage} in section \ugSysCmdundoNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdcompileTitle}{)compile}
\newcommand{\ugSysCmdcompileNumber}{B.7.}
%
% =====================================================================
\begin{page}{ugSysCmdcompilePage}{B.7. )compile}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{compile}{ugSysCmdcompilePage}{B.7.}{)compile}


\par\noindent{\bf User Level Required:} compiler

\par\noindent{\bf Command Syntax:}

\begin{items}
\item {\tt )compile}
\item {\tt )compile {\it fileName}}
\item {\tt )compile {\it fileName}.as}
\item {\tt )compile {\it directory/fileName}.as}
\item {\tt )compile {\it fileName}.ao}
\item {\tt )compile {\it directory/fileName}.ao}
\item {\tt )compile {\it fileName}.al}
\item {\tt )compile {\it directory/fileName}.al}
\item {\tt )compile {\it fileName}.lsp}
\item {\tt )compile {\it directory/fileName}.lsp}
\item {\tt )compile {\it fileName}.spad}
\item {\tt )compile {\it directory/fileName}.spad}
\item {\tt )compile {\it fileName} )new}
\item {\tt )compile {\it fileName} )old}
\item {\tt )compile {\it fileName} )translate}
\item {\tt )compile {\it fileName} )quiet}
\item {\tt )compile {\it fileName} )noquiet}
\item {\tt )compile {\it fileName} )moreargs}
\item {\tt )compile {\it fileName} )onlyargs}
\item {\tt )compile {\it fileName} )break}
\item {\tt )compile {\it fileName} )nobreak}
\item {\tt )compile {\it fileName} )library}
\item {\tt )compile {\it fileName} )nolibrary}
\item {\tt )compile {\it fileName} )vartrace}
\item {\tt )compile {\it fileName} )constructor} {\it nameOrAbbrev}
\end{items}

\par\noindent{\bf Command Description:}

You use this command to invoke the new \Language{} library compiler or
the old \Language{} system compiler.
The {\tt )compile} system command is actually a combination of
\Language{} processing and a call to the \axiomxl{} compiler.
It is performing double-duty, acting as a front-end to
both the \axiomxl{} compiler and the old \Language{} system
compiler.
(The old \Language{} system compiler was written in Lisp and was
an integral part of the \Language{} environment.
The \axiomxl{} compiler is written in C and executed by the operating system
when called from within \Language{}.)

The command compiles files with file extensions {\it .as, .ao}
and {\it .al} with the
\axiomxl{} compiler and files with file extension {\it .spad} with the
old \Language{} system compiler.
It also can compile files with file extension {\it .lsp}. These
are assumed to be Lisp files genererated by the \axiomxl{}
compiler.
If you omit the file extension, the command looks to see if you
have specified the {\tt )new} or {\tt )old} option.
If you have given one of these options, the corresponding compiler
is used.
Otherwise, the command first looks in the standard system
directories for files with extension {\it .as, .ao} and {\it
.al} and then files with extension {\it .spad}.
The first file found has the appropriate compiler invoked on it.
If the command cannot find a matching file, an error message is
displayed and the command terminates.

The {\tt )translate} option is used to invoke a special version
of the old system compiler that will translate a {\it .spad} file
to a {\it .as} file. That is, the {\it .spad} file will be parsed and
analyzed and a file using the new syntax will be created. By default,
the {\it .as} file is created in the same directory as the
{\it .spad} file. If that directory is not writable, the current
directory is used. If the current directory is not writable, an
error message is given and the command terminates.
Note that {\tt )translate} implies the {\tt )old} option so the
file extension can safely be omitted. If {\tt )translate} is
given, all other options are ignored.
Please be aware that the translation is not necessarily one
hundred percent complete or correct.
You should attempt to compile the output with the \axiomxl{} compiler
and make any necessary corrections.

We now describe the options for the new \axiomxl{} compiler.

The first thing {\tt )compile} does is look for a source code
filename among its arguments.
Thus
\begin{verbatim}
)compile mycode.as
)compile /u/jones/as/mycode.as
)compile mycode
\end{verbatim}
all invoke {\tt )compiler} on the file {\tt
/u/jones/as/mycode.as} if the current \Language{} working
directory is {\tt /u/jones/as.} (Recall that you can set the
working directory via the {\tt )cd} command. If you don't set it
explicitly, it is the directory from which you started
\Language{}.)

This is frequently all you need to compile your file.
This simple command:
\indent{4}
\beginitems
\item[1. ] Invokes the \axiomxl{} compiler and produces Lisp output.
\item[2. ] Calls the Lisp compiler if the \axiomxl{} compilation was
successful.
\item[3. ] Uses the {\tt )library} command to tell \Language{} about
the contents of your compiled file and arrange to have those
contents loaded on demand.
\enditems
\indent{0}

Should you not want the {\tt )library} command automatically
invoked, call {\tt )compile} with the {\tt )nolibrary} option.
For example,
\begin{verbatim}
)compile mycode.as )nolibrary
\end{verbatim}

The general description of \axiomxl{} command line arguments is in
the \axiomxl{} documentation.
The default options used by the {\tt )compile} command can be
viewed and set using the {\tt )set compiler args} \Language{}
system command.
The current defaults are
\begin{verbatim}
-O -Fasy -Fao -Flsp -laxiom -Mno-AXL_W_WillObsolete -DAxiom
\end{verbatim}
These options mean:
\indent{4}
\beginitems
\item[-] {\tt -O}: perform all optimizations,
\item[-] {\tt -Fasy}: generate a {\tt .asy} file,
\item[-] {\tt -Fao}: generate a {\tt .ao} file,
\item[-] {\tt -Flsp}: generate a {\tt .lsp} (Lisp)
file,
%-% \HDindex{Lisp!code generation}{ugSysCmdcompilePage}{B.7.}{)compile}
\item[-] {\tt -laxiom}: use the {\tt axiom} library {\tt libaxiom.al},
\item[-] {\tt -Mno-AXL\_W\_WillObsolete}: do not display messages
about older generated files becoming obsolete, and
\item[-] {\tt -DAxiom}: define the global assertion {\tt Axiom} so that the
\axiomxl{} libraries for generating stand-alone code
are not accidentally used with \Language{}.
\enditems
\indent{0}

To supplement these default arguments, use the {\tt )moreargs} option on
{\tt )compile.}
For example,
\begin{verbatim}
)compile mycode.as )moreargs "-v"
\end{verbatim}
uses the default arguments and appends the {\tt -v} (verbose)
argument flag.
The additional argument specification {\bf must be enclosed in
double quotes.}

To completely replace these default arguments for a particular
use of {\tt )compile}, use the {\tt )onlyargs} option.
For example,
\begin{verbatim}
)compile mycode.as )onlyargs "-v -O"
\end{verbatim}
only uses the {\tt -v} (verbose) and {\tt -O} (optimize)
arguments.
The argument specification {\bf must be enclosed in double quotes.}
In this example, Lisp code is not produced and so the compilation
output will not be available to \Language{}.

To completely replace the default arguments for all calls to {\tt
)compile} within your \Language{} session, use {\tt )set compiler args.}
For example, to use the above arguments for all compilations, issue
\begin{verbatim}
)set compiler args "-v -O"
\end{verbatim}
Make sure you include the necessary {\tt -l} and {\tt -Y}
arguments along with those needed for Lisp file creation.
As above, {\bf the argument specification must be enclosed in double
quotes.}

By default, the {\tt )library} system command {\it exposes} all
domains and categories it processes.
This means that the \Language{} intepreter will consider those
domains and categories when it is trying to resolve a reference
to a function.
Sometimes domains and categories should not be exposed.
For example, a domain may just be used privately by another
domain and may not be meant for top-level use.
The {\tt )library} command should still be used, though, so that
the code will be loaded on demand.
In this case, you should use the {\tt )nolibrary} option on {\tt
)compile} and the {\tt )noexpose} option in the {\tt )library}
command. For example,
\begin{verbatim}
)compile mycode.as )nolibrary
)library mycode )noexpose
\end{verbatim}

Once you have established your own collection of compiled code,
you may find it handy to use the {\tt )dir} option on the
{\tt )library} command.
This causes {\tt )library} to process all compiled code in the
specified directory. For example,
\begin{verbatim}
)library )dir /u/jones/as/quantum
\end{verbatim}
You must give an explicit directory after {\tt )dir}, even if you
want all compiled code in the current working directory
processed, e.g.
\begin{verbatim}
)library )dir .
\end{verbatim}

The {\tt )compile} command works with several file extensions. We saw
above what happens when it is invoked on a file with extension {\tt
.as.} A {\tt .ao} file is a portable binary compiled version of a
{\tt .as} file, and {\tt )compile} simply passes the {\tt .ao} file
onto \axiomxl{}. The generated Lisp file is compiled and {\tt )library}
is automatically called, just as if you had specified a {\tt .as} file.

A {\tt .al} file is an archive file containing {\tt .ao} files. The
archive is created (on Unix systems) with the {\tt ar} program. When
{\tt )compile} is given a {\tt .al} file, it creates a directory whose
name is based on that of the archive. For example, if you issue
\begin{verbatim}
)compile mylib.al
\end{verbatim}
the directory {\tt mylib.axldir} is created. All
members of the archive are unarchived into the
directory and {\tt )compile} is called on each {\tt .ao} file found. It
is your responsibility to remove the directory and its contents, if you
choose to do so.

A {\tt .lsp} file is a Lisp source file, presumably, in our context,
generated by \axiomxl{} when called with the {\tt -Flsp} option. When
{\tt )compile} is used with a {\tt .lsp} file, the Lisp file is
compiled and {\tt )library} is called. You must also have present a
{\tt .asy} generated from the same source file.

The following are descriptions of options for the old system compiler.

You can compile category, domain, and package constructors
contained in files with file extension {\it .spad}.
You can compile individual constructors or every constructor
in a file.

The full filename is remembered between invocations of this command and
{\tt )edit} commands.
The sequence of commands
\begin{verbatim}
)compile matrix.spad
)edit
)compile
\end{verbatim}
will call the compiler, edit, and then call the compiler again
on the file {\bf matrix.spad.}
If you do not specify a {\it directory,} the working current
directory (see \downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in Section \ugSysCmdcdNumber\ignore{ugSysCmdcd})
is searched for the file.
If the file is not found, the standard system directories are searched.

If you do not give any options, all constructors within a file are
compiled.
Each constructor should have an {\tt )abbreviation} command in
the file in which it is defined.
We suggest that you place the {\tt )abbreviation} commands at the
top of the file in the order in which the constructors are
defined.
The list of commands serves as a table of contents for the file.
%-% \HDsyscmdindex{abbreviation}{ugSysCmdcompilePage}{B.7.}{)compile}

The {\tt )library} option causes directories containing the
compiled code for each constructor
to be created in the working current directory.
The name of such a directory consists of the constructor
abbreviation and the {\bf .NRLIB} file extension.
For example, the directory containing the compiled code for
the \axiomType{MATRIX} constructor is called {\bf MATRIX.NRLIB.}
The {\tt )nolibrary} option says that such files should not
be created.
The default is {\tt )library.}
Note that the semantics of {\tt )library} and {\tt )nolibrary}
for the new \axiomxl{} compiler and for the old system compiler are
completely different.

The {\tt )vartrace} option causes the compiler to generate
extra code for the constructor to support conditional tracing of
variable assignments. (see \downlink{``\ugSysCmdtraceTitle''}{ugSysCmdtracePage} in Section \ugSysCmdtraceNumber\ignore{ugSysCmdtrace}). Without
this option, this code is suppressed and one cannot use
the {\tt )vars} option for the trace command.

The {\tt )constructor} option is used to
specify a particular constructor to compile.
All other constructors in the file are ignored.
The constructor name or abbreviation follows {\tt )constructor.}
Thus either
\begin{verbatim}
)compile matrix.spad )constructor RectangularMatrix
\end{verbatim}
or
\begin{verbatim}
)compile matrix.spad )constructor RMATRIX
\end{verbatim}
compiles  the \axiomType{RectangularMatrix} constructor
defined in {\bf matrix.spad.}

The {\tt )break} and {\tt )nobreak} options determine what
the old system compiler does when it encounters an error.
{\tt )break} is the default and it indicates that processing
should stop at the first error.
The value of the {\tt )set break} variable then controls what happens.


%% BEGIN OBSOLTE
%% END OBSOLTE

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdabbreviationTitle''}{ugSysCmdabbreviationPage} in section \ugSysCmdabbreviationNumber
\downlink{``\ugSysCmdeditTitle''}{ugSysCmdeditPage} in section \ugSysCmdeditNumber
\downlink{``\ugSysCmdlibraryTitle''}{ugSysCmdlibraryPage} in section \ugSysCmdlibraryNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmddisplayTitle}{)display}
\newcommand{\ugSysCmddisplayNumber}{B.8.}
%
% =====================================================================
\begin{page}{ugSysCmddisplayPage}{B.8. )display}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{display}{ugSysCmddisplayPage}{B.8.}{)display}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item {\tt )display all}
\item {\tt )display properties}
\item {\tt )display properties all}
\item {\tt )display properties} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}}
\item {\tt )display value all}
\item {\tt )display value} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}}
\item {\tt )display mode all}
\item {\tt )display mode} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}}
\item {\tt )display names}
\item {\tt )display operations} {\it opName}
\end{items}
\par\noindent{\bf Command Description:}

This command is  used to display the contents of  the workspace and
signatures of functions  with a  given  name.\footnote{A
\spadgloss{signature} gives the argument and return types of a
function.}

The command
\begin{verbatim}
)display names
\end{verbatim}
lists the names of all user-defined  objects in the workspace.  This is useful
if you do  not wish to see everything  about the objects and need  only be
reminded of their names.

The commands
\begin{verbatim}
)display all
)display properties
)display properties all
\end{verbatim}
all do  the same thing: show  the values and  types and declared modes  of all
variables in the  workspace.  If you have defined  functions, their signatures
and definitions will also be displayed.

To show all information about a  particular variable or user functions,
for example, something named {\tt d}, issue
\begin{verbatim}
)display properties d
\end{verbatim}
To just show the value (and the type) of {\tt d}, issue
\begin{verbatim}
)display value d
\end{verbatim}
To just show the declared mode of {\tt d}, issue
\begin{verbatim}
)display mode d
\end{verbatim}

All modemaps for a given operation  may be
displayed by using {\tt )display operations}.
A \spadgloss{modemap} is a collection of information about  a particular
reference
to an  operation.  This  includes the  types of the  arguments and  the return
value, the  location of the  implementation and  any conditions on  the types.
The modemap may contain patterns.  The following displays the modemaps for the
operation \spadfunFrom{complex}{ComplexCategory}:
\begin{verbatim}
)d op complex
\end{verbatim}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdclearTitle''}{ugSysCmdclearPage} in section \ugSysCmdclearNumber
\downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber
\downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber
\downlink{``\ugSysCmdshowTitle''}{ugSysCmdshowPage} in section \ugSysCmdshowNumber
\downlink{``\ugSysCmdwhatTitle''}{ugSysCmdwhatPage} in section \ugSysCmdwhatNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdeditTitle}{)edit}
\newcommand{\ugSysCmdeditNumber}{B.9.}
%
% =====================================================================
\begin{page}{ugSysCmdeditPage}{B.9. )edit}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{edit}{ugSysCmdeditPage}{B.9.}{)edit}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )edit} \lanb{}{\it filename}\ranb{}
\end{items}
\par\noindent{\bf Command Description:}

This command is  used to edit files.
It works in conjunction  with the {\tt )read}
and {\tt )compile} commands to remember the name
of the file on which you are working.
By specifying the name fully, you  can edit any file you wish.
Thus
\begin{verbatim}
)edit /u/julius/matrix.input
\end{verbatim}
will place  you in an editor looking at the  file
{\tt /u/julius/matrix.input}.
%-% \HDindex{editing files}{ugSysCmdeditPage}{B.9.}{)edit}
By default, the editor is {\tt vi},
%-% \HDindex{vi}{ugSysCmdeditPage}{B.9.}{)edit}
but if you have an EDITOR shell environment variable defined, that editor
will be used.
When \Language{} is running under the X Window System,
it will try to open a separate {\tt xterm} running your editor if
it thinks one is necessary.
%-% \HDindex{Korn shell}{ugSysCmdeditPage}{B.9.}{)edit}
For example, under the Korn shell, if you issue
\begin{verbatim}
export EDITOR=emacs
\end{verbatim}
then the emacs
%-% \HDindex{emacs}{ugSysCmdeditPage}{B.9.}{)edit}
editor will be used by \spadcmd{)edit}.

If you do not specify a file name, the last file you edited,
read or compiled will be used.
If there is no ``last file'' you will be placed in the editor editing
an empty unnamed file.

It is possible to use the {\tt )system} command to edit a file directly.
For example,
\begin{verbatim}
)system emacs /etc/rc.tcpip
\end{verbatim}
calls {\tt emacs} to edit the file.
%-% \HDindex{emacs}{ugSysCmdeditPage}{B.9.}{)edit}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber
\downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber
\downlink{``\ugSysCmdreadTitle''}{ugSysCmdreadPage} in section \ugSysCmdreadNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdfinTitle}{)fin}
\newcommand{\ugSysCmdfinNumber}{B.10.}
%
% =====================================================================
\begin{page}{ugSysCmdfinPage}{B.10. )fin}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{fin}{ugSysCmdfinPage}{B.10.}{)fin}


\par\noindent{\bf User Level Required:} development

\par\noindent{\bf Command Syntax:}
\begin{items}
\item {\tt )fin}
\end{items}
\par\noindent{\bf Command Description:}

This command is used by \Language{}
developers to leave the \Language{} system and return
to the underlying \Lisp{} system.
To return to \Language{}, issue the
``{\tt (\vertline{}spad\vertline{})}''
function call to \Lisp{}.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdpquitTitle''}{ugSysCmdpquitPage} in section \ugSysCmdpquitNumber
\downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdframeTitle}{)frame}
\newcommand{\ugSysCmdframeNumber}{B.11.}
%
% =====================================================================
\begin{page}{ugSysCmdframePage}{B.11. )frame}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{frame}{ugSysCmdframePage}{B.11.}{)frame}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )frame  new  {\it frameName}}
\item{\tt )frame  drop  {\it \lanb{}frameName\ranb{}}}
\item{\tt )frame  next}
\item{\tt )frame  last}
\item{\tt )frame  names}
\item{\tt )frame  import {\it frameName} {\it \lanb{}objectName1 \lanb{}objectName2 ...\ranb{}\ranb{}}}
\item{\tt )set message frame on \vertline{} off}
\item{\tt )set message prompt frame}
\end{items}

\par\noindent{\bf Command Description:}

A {\it frame} can be thought of as a logical session within the
physical session that you get when you start the system.  You can
have as many frames as you want, within the limits of your computer's
storage, paging space, and so on.
Each frame has its own {\it step number}, {\it environment} and {\it history.}
You can have a variable named {\tt a} in one frame and it will
have nothing to do with anything that might be called {\tt a} in
any other frame.

Some frames are created by the \HyperName{} program and these can
have pretty strange names, since they are generated automatically.
%-% \HDsyscmdindex{frame names}{ugSysCmdframePage}{B.11.}{)frame}
To find out the names
of all frames, issue
\begin{verbatim}
)frame names
\end{verbatim}
It will indicate the name of the current frame.

You create a new frame
%-% \HDsyscmdindex{frame new}{ugSysCmdframePage}{B.11.}{)frame}
``{\bf quark}'' by issuing
\begin{verbatim}
)frame new quark
\end{verbatim}
The history facility can be turned on by issuing either
{\tt )set history on} or {\tt )history )on}.
If the history facility is on and you are saving history information
in a file rather than in the \Language{} environment
then a history file with filename {\bf quark.axh} will
be created as you enter commands.
If you wish to go back to what
you were doing in the
%-% \HDsyscmdindex{frame next}{ugSysCmdframePage}{B.11.}{)frame}
``{\bf initial}'' frame, use
%-% \HDsyscmdindex{frame last}{ugSysCmdframePage}{B.11.}{)frame}
\begin{verbatim}
)frame next
\end{verbatim}
or
\begin{verbatim}
)frame last
\end{verbatim}
to cycle through the ring of available frames to get back to
``{\bf initial}''.

If you want to throw
away a frame (say ``{\bf quark}''), issue
\begin{verbatim}
)frame drop quark
\end{verbatim}
If you omit the name, the current frame is dropped.
%-% \HDsyscmdindex{frame drop}{ugSysCmdframePage}{B.11.}{)frame}

If you do use frames with the history facility on and writing to a file,
you may want to delete some of the older history files.
%-% \HDindex{file!history}{ugSysCmdframePage}{B.11.}{)frame}
These are directories, so you may want to issue a command like
{\tt rm -r quark.axh} to the operating system.

You can bring things from another frame by using
%-% \HDsyscmdindex{frame import}{ugSysCmdframePage}{B.11.}{)frame}
{\tt )frame import}.
For example, to bring the {\tt f} and {\tt g} from the frame ``{\bf quark}''
to the current frame, issue
\begin{verbatim}
)frame import quark f g
\end{verbatim}
If you want everything from the frame ``{\bf quark}'', issue
\begin{verbatim}
)frame import quark
\end{verbatim}
You will be asked to verify that you really want everything.

There are two {\tt )set} flags
%-% \HDsyscmdindex{set message frame}{ugSysCmdframePage}{B.11.}{)frame}
to make it easier to tell where you are.
\begin{verbatim}
)set message frame on | off
\end{verbatim}
will print more messages about frames when it is set on.
By default, it is off.
\begin{verbatim}
)set message prompt frame
\end{verbatim}
will give a prompt
%-% \HDsyscmdindex{set message prompt frame}{ugSysCmdframePage}{B.11.}{)frame}
that looks like
\begin{verbatim}
initial (1) ->
\end{verbatim}
%-% \HDindex{prompt!with frame name}{ugSysCmdframePage}{B.11.}{)frame}
when you start up. In this case, the frame name and step make up the
prompt.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber
\downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdhelpTitle}{)help}
\newcommand{\ugSysCmdhelpNumber}{B.12.}
%
% =====================================================================
\begin{page}{ugSysCmdhelpPage}{B.12. )help}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{help}{ugSysCmdhelpPage}{B.12.}{)help}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )help}
\item{\tt )help} {\it commandName}
\end{items}

\par\noindent{\bf Command Description:}

This command displays help information about system commands.
If you issue
\begin{verbatim}
)help
\end{verbatim}
then this very text will be shown.
You can also give the name or abbreviation of a system command
to display information about it.
For example,
\begin{verbatim}
)help clear
\end{verbatim}
will display the description of the {\tt )clear} system command.

All this material is available in the \Language{} User Guide
and in \HyperName{}.
In \HyperName{}, choose the {\bf Commands} item from the
{\bf Reference} menu.



\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdhistoryTitle}{)history}
\newcommand{\ugSysCmdhistoryNumber}{B.13.}
%
% =====================================================================
\begin{page}{ugSysCmdhistoryPage}{B.13. )history}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{history}{ugSysCmdhistoryPage}{B.13.}{)history}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )history )on}
\item{\tt )history )off}
\item{\tt )history )write} {\it historyInputFileName}
\item{\tt )history )show \lanb{}{\it n}\ranb{} \lanb{}both\ranb{}}
\item{\tt )history )save} {\it savedHistoryName}
\item{\tt )history )restore} \lanb{}{\it savedHistoryName}\ranb{}
\item{\tt )history )reset}
\item{\tt )history )change} {\it n}
\item{\tt )history )memory}
\item{\tt )history )file}
\item{\tt \%}
\item{\tt \%\%({\it n})}
\item{\tt )set history on \vertline{} off}
\end{items}

\par\noindent{\bf Command Description:}

The {\it history} facility within \Language{} allows you to restore your
environment to that of another session and recall previous
computational results.
Additional commands allow you to review previous
input lines and to create an {\bf .input} file of the lines typed to
%-% \HDindex{file!input}{ugSysCmdhistoryPage}{B.13.}{)history}
\Language{}.

\Language{} saves your input and output if the history facility is
turned on (which is the default).
This information is saved if either of
\begin{verbatim}
)set history on
)history )on
\end{verbatim}
has been issued.
Issuing either
\begin{verbatim}
)set history off
)history )off
\end{verbatim}
will discontinue the recording of information.
%-% \HDsyscmdindex{history )on}{ugSysCmdhistoryPage}{B.13.}{)history}
%-% \HDsyscmdindex{set history on}{ugSysCmdhistoryPage}{B.13.}{)history}
%-% \HDsyscmdindex{set history off}{ugSysCmdhistoryPage}{B.13.}{)history}
%-% \HDsyscmdindex{history )off}{ugSysCmdhistoryPage}{B.13.}{)history}

Whether the facility is disabled or not,
the value of \spadSyntax{\%} in \Language{} always
refers to the result of the last computation.
If you have not yet entered anything,
\spadSyntax{\%} evaluates to an object of type
\spadtype{Variable('\%)}.
The function \spadSyntax{\%\%} may be  used to refer
to other previous results if the history facility is enabled.
In that case,
{\tt \%\%(n)} is  the output from step {\tt n} if {\tt n > 0}.
If {\tt n < 0}, the step is computed relative to the current step.
Thus {\tt \%\%(-1)} is also the previous step,
{\tt \%\%(-2)}, is the  step before that, and so on.
If an invalid step number is given, \Language{} will signal an error.

The {\it environment} information can either be saved in a file or entirely in
memory (the default).
Each frame (\downlink{``\ugSysCmdframeTitle''}{ugSysCmdframePage} in Section \ugSysCmdframeNumber\ignore{ugSysCmdframe})
has its own history database.
When it is kept in a file, some of it may also be kept in memory for
efficiency.
When the information is saved in a file, the name of the file is
of the form {\bf FRAME.axh} where ``{\bf FRAME}'' is the name of the
current frame.
The history file is placed in the current working directory
(see \downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in Section \ugSysCmdcdNumber\ignore{ugSysCmdcd}).
Note that these history database files are not text files (in fact,
they are directories themselves), and so are not in human-readable
format.

The options to the {\tt )history} command are as follows:

\indent{0}
\beginitems
\item[{\tt )change} {\it n}]
will set the number of steps that are saved in memory to {\it n}.
This option only has effect when the history data is maintained in a
file.
If you have issued {\tt )history )memory} (or not changed the default)
there is no need to use {\tt )history )change}.
%-% \HDsyscmdindex{history )change}{ugSysCmdhistoryPage}{B.13.}{)history}

\item[{\tt )on}]
will start the recording of information.
If the workspace is not empty, you will be asked to confirm this
request.
If you do so, the workspace will be cleared and history data will begin
being saved.
You can also turn the facility on by issuing {\tt )set history on}.

\item[{\tt )off}]
will stop the recording of information.
The {\tt )history )show} command will not work after issuing this
command.
Note that this command may be issued to save time, as there is some
performance penalty paid for saving the environment data.
You can also turn the facility off by issuing {\tt )set history off}.

\item[{\tt )file}]
indicates that history data should be saved in an external file on disk.

\item[{\tt )memory}]
indicates that all history data should be kept in memory rather than
saved in a file.
Note that if you are computing with very large objects it may not be
practical to kept this data in memory.

\item[{\tt )reset}]
will flush the internal list of the most recent workspace calculations
so that the data structures may be garbage collected by the underlying
\Lisp{} system.
Like {\tt )history )change}, this option only has real effect when
history data is being saved in a file.

\item[{\tt )restore} \lanb{}{\it savedHistoryName}\ranb{}]
completely clears the environment and restores it to a saved session, if
possible.
The {\tt )save} option below allows you to save a session to a file
with a given name. If you had issued
{\tt )history )save jacobi}
the command
{\tt )history )restore jacobi}
would clear the current workspace and load the contents of the named
saved session. If no saved session name is specified, the system looks
for a file called {\bf last.axh}.

\item[{\tt )save} {\it savedHistoryName}]
is used to save  a snapshot of the environment in a file.
This file is placed in the current working directory
(see \downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in Section \ugSysCmdcdNumber\ignore{ugSysCmdcd}).
Use {\tt )history )restore} to restore the environment to the state
preserved in the file.
This option also creates an input file containing all the lines of input
since you created the workspace frame (for example, by starting your
\Language{} session) or last did a \spadcmd{)clear all} or
\spadcmd{)clear completely}.

\item[{\tt )show} \lanb{}{\it n}\ranb{} \lanb{}{\tt both}\ranb{}]
can show previous input lines and output results.
{\tt )show} will display up to twenty of the last input lines
(fewer if you haven't typed in twenty lines).
{\tt )show} {\it n} will display up to {\it n} of the last input lines.
{\tt )show both} will display up to five of the last input lines and
output results.
{\tt )show} {\it n} {\tt both} will display up to {\it n} of the last
input lines and output results.

\item[{\tt )write} {\it historyInputFile}]
creates an {\bf .input} file with the input lines typed since the start
of the session/frame or the last {\tt )clear all} or {\tt )clear
completely}.
If {\it historyInputFileName} does not contain a period (``.'') in the filename,
{\bf .input} is appended to it.
For example,
{\tt )history )write chaos}
and
{\tt )history )write chaos.input}
both write the input lines to a file called {\bf chaos.input} in your
current working directory.
If you issued one or more {\tt )undo} commands,
{\tt )history )write}
eliminates all
input lines backtracked over as a result of {\tt )undo}.
You can edit this file and then use {\tt )read} to have \Language{} process
the contents.
\enditems
\indent{0}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdframeTitle''}{ugSysCmdframePage} in section \ugSysCmdframeNumber
\downlink{``\ugSysCmdreadTitle''}{ugSysCmdreadPage} in section \ugSysCmdreadNumber
\downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber
\downlink{``\ugSysCmdundoTitle''}{ugSysCmdundoPage} in section \ugSysCmdundoNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdlibraryTitle}{)library}
\newcommand{\ugSysCmdlibraryNumber}{B.14.}
%
% =====================================================================
\begin{page}{ugSysCmdlibraryPage}{B.14. )library}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{library}{ugSysCmdlibraryPage}{B.14.}{)library}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )library {\it libName1  \lanb{}libName2 ...\ranb{}}}
\item{\tt )library )dir {\it dirName}}
\item{\tt )library )only {\it objName1  \lanb{}objlib2 ...\ranb{}}}
\item{\tt )library )noexpose}
\end{items}

\par\noindent{\bf Command Description:}

This command replaces the {\tt )load} system command that
was available in \Language{} releases before version 2.0.
The \spadcmd{)library} command makes available to \Language{} the compiled
objects in the libraries listed.

For example, if you {\tt )compile dopler.as} in your home
directory, issue {\tt )library dopler} to have \Language{} look
at the library, determine the category and domain constructors present,
update the internal database with various properties of the
constructors, and arrange for the constructors to be
automatically loaded when needed.
If the {\tt )noexpose} option has not been given, the
constructors will be exposed (that is, available) in the current
frame.

If you compiled a file with the old system compiler, you will
have an {\it NRLIB} present, for example, {\it DOPLER.NRLIB,}
where {\tt DOPLER} is a constructor abbreviation.
The command {\tt )library DOPLER} will then do the analysis and
database updates as above.

To tell the system about all libraries in a directory, use
{\tt )library )dir dirName} where {\tt dirName} is an explicit
directory.
You may specify ``.'' as the directory, which means the current
directory from which you started the system or the one you set
via the \spadcmd{)cd} command. The directory name is required.

You may only want to tell the system about particular
constructors within a library. In this case, use the {\tt )only}
option. The command {\tt )library dopler )only Test1} will only
cause the {\sf Test1} constructor to be analyzed, autoloaded,
etc..

Finally, each constructor in a library  are usually automatically exposed when the
\spadcmd{)library} command is used. Use the {\tt )noexpose}
option if you not want them exposed. At a later time you can use
{\tt )set expose add constructor} to expose any hidden
constructors.

{\bf Note for \Language{} beta testers:} At various times this
command was called {\tt )local} and {\tt )with} before the name
{\tt )library} became the official name.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in section \ugSysCmdcdNumber
\downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber
\downlink{``\ugSysCmdframeTitle''}{ugSysCmdframePage} in section \ugSysCmdframeNumber
\downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdlispTitle}{)lisp}
\newcommand{\ugSysCmdlispNumber}{B.15.}
%
% =====================================================================
\begin{page}{ugSysCmdlispPage}{B.15. )lisp}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{lisp}{ugSysCmdlispPage}{B.15.}{)lisp}


\par\noindent{\bf User Level Required:} development

\par\noindent{\bf Command Syntax:}
\begin{items}
\item {\tt )lisp} {\it\lanb{}lispExpression\ranb{}}
\end{items}

\par\noindent{\bf Command Description:}

This command is used by \Language{} system developers to have single
expressions evaluated by the \Lisp{} system on which
\Language{} is built.
The {\it lispExpression} is read by the \Lisp{} reader and
evaluated.
If this expression is not complete (unbalanced parentheses, say), the reader
will wait until a complete expression is entered.

Since this command is only useful  for evaluating single expressions, the
{\tt )fin}
command may be used to  drop out  of \Language{}  into \Lisp{}.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber
\downlink{``\ugSysCmdbootTitle''}{ugSysCmdbootPage} in section \ugSysCmdbootNumber
\downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber



\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdloadTitle}{)load}
\newcommand{\ugSysCmdloadNumber}{B.16.}
%
% =====================================================================
\begin{page}{ugSysCmdloadPage}{B.16. )load}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{load}{ugSysCmdloadPage}{B.16.}{)load}


\par\noindent{\bf User Level Required:} interpreter

%% BEGIN OBSOLETE
%% END OBSOLETE

\par\noindent{\bf Command Description:}

This command is obsolete. Use \spadcmd{)library} instead.

%% BEGIN OBSOLETE

%
%
%
%

%% END OBSOLETE


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdltraceTitle}{)ltrace}
\newcommand{\ugSysCmdltraceNumber}{B.17.}
%
% =====================================================================
\begin{page}{ugSysCmdltracePage}{B.17. )ltrace}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{ltrace}{ugSysCmdltracePage}{B.17.}{)ltrace}


\par\noindent{\bf User Level Required:} development

\par\noindent{\bf Command Syntax:}

This command has the same arguments as options as the
\spadcmd{)trace} command.

\par\noindent{\bf Command Description:}

This command is used by \Language{} system developers to trace
\Lisp{} or
BOOT functions.
It is not supported for general use.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdbootTitle''}{ugSysCmdbootPage} in section \ugSysCmdbootNumber
\downlink{``\ugSysCmdlispTitle''}{ugSysCmdlispPage} in section \ugSysCmdlispNumber
\downlink{``\ugSysCmdtraceTitle''}{ugSysCmdtracePage} in section \ugSysCmdtraceNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdpquitTitle}{)pquit}
\newcommand{\ugSysCmdpquitNumber}{B.18.}
%
% =====================================================================
\begin{page}{ugSysCmdpquitPage}{B.18. )pquit}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{pquit}{ugSysCmdpquitPage}{B.18.}{)pquit}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )pquit}
\end{items}

\par\noindent{\bf Command Description:}

This command is used to terminate \Language{}  and return to the
operating system.
Other than by redoing all your computations or by
using the {\tt )history )restore}
command to try to restore your working environment,
you cannot return to \Language{} in the same state.

{\tt )pquit} differs from the {\tt )quit} in that it always asks for
confirmation that you want to terminate \Language{} (the ``p'' is for
``protected'').
%-% \HDsyscmdindex{quit}{ugSysCmdpquitPage}{B.18.}{)pquit}
When you enter the {\tt )pquit} command, \Language{} responds
%
\centerline{{Please enter {\bf y} or {\bf yes} if you really want to leave the interactive }}
\centerline{{environment and return to the operating system:}}
%
If you respond with {\tt y} or {\tt yes}, you will see the message
%
\centerline{{You are now leaving the \Language{} interactive environment. }}
\centerline{{Issue the command {\bf axiom} to the operating system to start a new session.}}
%
and \Language{} will terminate and return you to the operating
system (or the environment from which you invoked the system).
If you responded with something other than {\tt y} or {\tt yes}, then
the message
%
\centerline{{You have chosen to remain in the \Language{} interactive environment.}}
%
will be displayed and, indeed, \Language{} would still be running.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber
\downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber
\downlink{``\ugSysCmdcloseTitle''}{ugSysCmdclosePage} in section \ugSysCmdcloseNumber
\downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber
\downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdquitTitle}{)quit}
\newcommand{\ugSysCmdquitNumber}{B.19.}
%
% =====================================================================
\begin{page}{ugSysCmdquitPage}{B.19. )quit}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{quit}{ugSysCmdquitPage}{B.19.}{)quit}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )quit}
\item{\tt )set quit protected \vertline{} unprotected}
\end{items}

\par\noindent{\bf Command Description:}

This command is used to terminate \Language{}  and return to the
operating system.
Other than by redoing all your computations or by
using the {\tt )history )restore}
command to try to restore your working environment,
you cannot return to \Language{} in the same state.

{\tt )quit} differs from the {\tt )pquit} in that it asks for
%-% \HDsyscmdindex{pquit}{ugSysCmdquitPage}{B.19.}{)quit}
confirmation only if the command
\begin{verbatim}
)set quit protected
\end{verbatim}
has been issued.
%-% \HDsyscmdindex{set quit protected}{ugSysCmdquitPage}{B.19.}{)quit}
Otherwise, {\tt )quit} will make \Language{} terminate and return you
to the operating system (or the environment from which you invoked the
system).

The default setting is {\tt )set quit protected} so that {\tt )quit}
and {\tt )pquit} behave in the same way.
If you do issue
\begin{verbatim}
)set quit unprotected
\end{verbatim}
we
%-% \HDsyscmdindex{set quit unprotected}{ugSysCmdquitPage}{B.19.}{)quit}
suggest that you do not (somehow) assign {\tt )quit} to be
executed when you press, say, a function key.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber
\downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber
\downlink{``\ugSysCmdcloseTitle''}{ugSysCmdclosePage} in section \ugSysCmdcloseNumber
\downlink{``\ugSysCmdpquitTitle''}{ugSysCmdpquitPage} in section \ugSysCmdpquitNumber
\downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdreadTitle}{)read}
\newcommand{\ugSysCmdreadNumber}{B.20.}
%
% =====================================================================
\begin{page}{ugSysCmdreadPage}{B.20. )read}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{read}{ugSysCmdreadPage}{B.20.}{)read}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item {\tt )read} {\it \lanb{}fileName\ranb{}}
\item {\tt )read} {\it \lanb{}fileName\ranb{}} \lanb{}{\tt )quiet}\ranb{} \lanb{}{\tt )ifthere}\ranb{}
\end{items}
\par\noindent{\bf Command Description:}

This command is used to read {\bf .input} files into \Language{}.
%-% \HDindex{file!input}{ugSysCmdreadPage}{B.20.}{)read}
The command
\begin{verbatim}
)read matrix.input
\end{verbatim}
will read the contents of the file {\bf matrix.input} into
\Language{}.
The ``.input'' file extension is optional.
See \downlink{``\ugInOutInTitle''}{ugInOutInPage} in Section \ugInOutInNumber\ignore{ugInOutIn} for more information about {\bf .input} files.

This command remembers the previous file you edited, read or compiled.
If you do not specify a file name, the previous file will be read.

The {\tt )ifthere} option checks to see whether the {\bf .input} file
exists.
If it does not, the  {\tt )read} command does nothing.
If you do not use this option and the file does not exist,
you are asked to give the name of an existing {\bf .input} file.

The {\tt )quiet} option suppresses output while the file is being read.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber
\downlink{``\ugSysCmdeditTitle''}{ugSysCmdeditPage} in section \ugSysCmdeditNumber
\downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdsetTitle}{)set}
\newcommand{\ugSysCmdsetNumber}{B.21.}
%
% =====================================================================
\begin{page}{ugSysCmdsetPage}{B.21. )set}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{set}{ugSysCmdsetPage}{B.21.}{)set}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item {\tt )set}
\item {\tt )set} {\it label1 \lanb{}... labelN\ranb{}}
\item {\tt )set} {\it label1 \lanb{}... labelN\ranb{} newValue}
\end{items}
\par\noindent{\bf Command Description:}

The {\tt )set} command is used to view or set system variables that
control what messages are displayed, the type of output desired, the
status of the history facility, the way \Language{} user functions are
cached, and so on.
Since this collection is very large, we will not discuss them here.
Rather, we will show how the facility is used.
We urge you to explore the {\tt )set} options to familiarize yourself
with how you can modify your \Language{} working environment.
There is a \HyperName{} version of this same facility available from the
main \HyperName{} menu.
\texht{}{Click \lispmemolink{here}{(|htSystemVariables|)} to go to it.}

The {\tt )set} command is command-driven with a menu display.
It is tree-structured.
To see all top-level nodes, issue {\tt )set} by itself.
\begin{verbatim}
)set
\end{verbatim}
Variables with values have them displayed near the right margin.
Subtrees of selections have ``{\tt ...}''
displayed in the value field.
For example, there are many kinds of messages, so issue
{\tt )set message} to see the choices.
\begin{verbatim}
)set message
\end{verbatim}
The current setting  for the variable that displays
%-% \HDindex{computation timings!displaying}{ugSysCmdsetPage}{B.21.}{)set}
whether computation times
%-% \HDindex{timings!displaying}{ugSysCmdsetPage}{B.21.}{)set}
are displayed is visible in the menu displayed by the last command.
To see more information, issue
\begin{verbatim}
)set message time
\end{verbatim}
This shows that time printing is on now.
To turn it off, issue
\begin{verbatim}
)set message time off
\end{verbatim}
%-% \HDsyscmdindex{set message time}{ugSysCmdsetPage}{B.21.}{)set}

As noted above, not all settings have so many qualifiers.
For example, to change the {\tt )quit} command to being unprotected
(that is, you will not be prompted for verification), you need only issue
\begin{verbatim}
)set quit unprotected
\end{verbatim}
%-% \HDsyscmdindex{set quit unprotected}{ugSysCmdsetPage}{B.21.}{)set}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdshowTitle}{)show}
\newcommand{\ugSysCmdshowNumber}{B.22.}
%
% =====================================================================
\begin{page}{ugSysCmdshowPage}{B.22. )show}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{show}{ugSysCmdshowPage}{B.22.}{)show}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )show {\it nameOrAbbrev}}
\item{\tt )show {\it nameOrAbbrev} )operations}
\item{\tt )show {\it nameOrAbbrev} )attributes}
\end{items}

\par\noindent{\bf Command Description:}
This command displays information about \Language{}
domain, package and category {\it constructors}.
If no options are given, the {\tt )operations} option is assumed.
For example,
\begin{verbatim}
)show POLY
)show POLY )operations
)show Polynomial
)show Polynomial )operations
\end{verbatim}
each display basic information about the
\spadtype{Polynomial} domain constructor and then provide a
listing of operations.
Since \spadtype{Polynomial} requires a \spadtype{Ring} (for example,
\spadtype{Integer}) as argument, the above commands all refer
to a unspecified ring {\tt R}.
In the list of operations, \spadSyntax{\$} means
\spadtype{Polynomial(R)}.

The basic information displayed includes the {\it signature}
of the constructor (the name and arguments), the constructor
{\it abbreviation}, the {\it exposure status} of the constructor, and the
name of the {\it library source file} for the constructor.

If operation information about a specific domain is wanted,
the full or abbreviated domain name may be used.
For example,
\begin{verbatim}
)show POLY INT
)show POLY INT )operations
)show Polynomial Integer
)show Polynomial Integer )operations
\end{verbatim}
are among  the combinations that will
display the operations exported  by the
domain \spadtype{Polynomial(Integer)} (as opposed to the general
{\it domain constructor} \spadtype{Polynomial}).
Attributes may be listed by using the {\tt )attributes} option.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmddisplayTitle''}{ugSysCmddisplayPage} in section \ugSysCmddisplayNumber
\downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber
\downlink{``\ugSysCmdwhatTitle''}{ugSysCmdwhatPage} in section \ugSysCmdwhatNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdspoolTitle}{)spool}
\newcommand{\ugSysCmdspoolNumber}{B.23.}
%
% =====================================================================
\begin{page}{ugSysCmdspoolPage}{B.23. )spool}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{spool}{ugSysCmdspoolPage}{B.23.}{)spool}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )spool} \lanb{}{\it fileName}\ranb{}
\item{\tt )spool}
\end{items}

\par\noindent{\bf Command Description:}

This command is used to save {\it (spool)} all \Language{} input and output
%-% \HDindex{file!spool}{ugSysCmdspoolPage}{B.23.}{)spool}
into a file, called a {\it spool file.}
You can only have one spool file active at a time.
To start spool, issue this command with a filename. For example,
\begin{verbatim}
)spool integrate.out
\end{verbatim}
To stop spooling, issue {\tt )spool} with no filename.

If the filename is qualified with a directory, then the output will
be placed in that directory.
If no directory information is given, the spool file will be placed in the
%-% \HDindex{directory!for spool files}{ugSysCmdspoolPage}{B.23.}{)spool}
{\it current directory.}
The current directory is the directory from which you started
\Language{} or is the directory you specified using the
{\tt )cd} command.
%-% \HDsyscmdindex{cd}{ugSysCmdspoolPage}{B.23.}{)spool}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in section \ugSysCmdcdNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdsynonymTitle}{)synonym}
\newcommand{\ugSysCmdsynonymNumber}{B.24.}
%
% =====================================================================
\begin{page}{ugSysCmdsynonymPage}{B.24. )synonym}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{synonym}{ugSysCmdsynonymPage}{B.24.}{)synonym}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )synonym}
\item{\tt )synonym} {\it synonym fullCommand}
\item{\tt )what synonyms}
\end{items}

\par\noindent{\bf Command Description:}

This command is used to create short synonyms for system command expressions.
For example, the following synonyms  might simplify commands you often
use.
\begin{verbatim}
)synonym save         history )save
)synonym restore      history )restore
)synonym mail         system mail
)synonym ls           system ls
)synonym fortran      set output fortran
\end{verbatim}
Once defined, synonyms can be
used in place of the longer  command expressions.
Thus
\begin{verbatim}
)fortran on
\end{verbatim}
is the same as the longer
\begin{verbatim}
)set fortran output on
\end{verbatim}
To list all defined synonyms, issue either of
\begin{verbatim}
)synonyms
)what synonyms
\end{verbatim}
To list, say, all synonyms that contain the substring
``{\tt ap}'', issue
\begin{verbatim}
)what synonyms ap
\end{verbatim}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber
\downlink{``\ugSysCmdwhatTitle''}{ugSysCmdwhatPage} in section \ugSysCmdwhatNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdsystemTitle}{)system}
\newcommand{\ugSysCmdsystemNumber}{B.25.}
%
% =====================================================================
\begin{page}{ugSysCmdsystemPage}{B.25. )system}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{system}{ugSysCmdsystemPage}{B.25.}{)system}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )system} {\it cmdExpression}
\end{items}

\par\noindent{\bf Command Description:}

This command may be used to issue commands to the operating system while
remaining in \Language{}.
The {\it cmdExpression} is passed to the operating system for
execution.

To get an operating system shell, issue, for example,
\spadcmd{)system sh}.
When you enter the key combination,
\texht{\fbox{\bf Ctrl}--\fbox{\bf D}}{{\bf Ctrl-D}}
(pressing and holding the
\texht{\fbox{\bf Ctrl}}{{\bf Ctrl}} key and then pressing the
\texht{\fbox{\bf D}}{{\bf D}} key)
the shell will terminate and you will return to \Language{}.
We do not recommend this way of creating a shell because
\Lisp{} may field some interrupts instead of the shell.
If possible, use a shell running in another window.

If you execute programs that misbehave you may not be able to return to
\Language{}.
If this happens, you may have no other choice than to restart
\Language{} and restore the environment via {\tt )history )restore}, if
possible.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdbootTitle''}{ugSysCmdbootPage} in section \ugSysCmdbootNumber
\downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber
\downlink{``\ugSysCmdlispTitle''}{ugSysCmdlispPage} in section \ugSysCmdlispNumber
\downlink{``\ugSysCmdpquitTitle''}{ugSysCmdpquitPage} in section \ugSysCmdpquitNumber
\downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdtraceTitle}{)trace}
\newcommand{\ugSysCmdtraceNumber}{B.26.}
%
% =====================================================================
\begin{page}{ugSysCmdtracePage}{B.26. )trace}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{trace}{ugSysCmdtracePage}{B.26.}{)trace}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )trace}
\item{\tt )trace )off}

\item{\tt )trace} {\it function \lanb{}options\ranb{}}
\item{\tt )trace} {\it constructor \lanb{}options\ranb{}}
\item{\tt )trace} {\it domainOrPackage \lanb{}options\ranb{}}
\end{items}
%
where options can be one or more of
%
\begin{items}
\item{\tt )after} {\it S-expression}
\item{\tt )before} {\it S-expression}
\item{\tt )break after}
\item{\tt )break before}
\item{\tt )cond} {\it S-expression}
\item{\tt )count}
\item{\tt )count} {\it n}
\item{\tt )depth} {\it n}
\item{\tt )local} {\it op1 \lanb{}... opN\ranb{}}
\item{\tt )nonquietly}
\item{\tt )nt}
\item{\tt )off}
\item{\tt )only} {\it listOfDataToDisplay}
\item{\tt )ops}
\item{\tt )ops} {\it op1 \lanb{}... opN \ranb{}}
\item{\tt )restore}
\item{\tt )stats}
\item{\tt )stats reset}
\item{\tt )timer}
\item{\tt )varbreak}
\item{\tt )varbreak} {\it var1 \lanb{}... varN \ranb{}}
\item{\tt )vars}
\item{\tt )vars} {\it var1 \lanb{}... varN \ranb{}}
\item{\tt )within} {\it executingFunction}
\end{items}

\par\noindent{\bf Command Description:}

This command is used to trace the execution of functions that make
up the \Language{} system, functions defined by users,
and functions from the system library.
Almost all options are available for each type of function but
exceptions will be noted below.

To list all functions, constructors, domains and packages that are
traced, simply issue
\begin{verbatim}
)trace
\end{verbatim}
To untrace everything that is traced, issue
\begin{verbatim}
)trace )off
\end{verbatim}
When a function is traced, the default system action is to display
the arguments to the function and the return value when the
function is exited.
Note that if a function is left via an action such as a {\tt THROW}, no
return value will be displayed.
Also, optimization of tail recursion may decrease the number of
times a function is actually invoked and so may cause less trace
information to be displayed.
Other information can be displayed or collected when a function is
traced and this is controlled by the various options.
Most options will be of interest only to \Language{} system
developers.
If a domain or package is traced, the default action is to trace
all functions exported.

Individual interpreter, lisp or boot
functions can be traced by listing their names after
{\tt )trace}.
Any options that are present must follow the functions to be
traced.
\begin{verbatim}
)trace f
\end{verbatim}
traces the function {\tt f}.
To untrace {\tt f}, issue
\begin{verbatim}
)trace f )off
\end{verbatim}
Note that if a function name contains a special character, it will
be necessary to escape the character with an underscore
%
\begin{verbatim}
)trace _/D_,1
\end{verbatim}
%
To trace all domains or packages that are or will be created from a particular
constructor, give the constructor name or abbreviation after
{\tt )trace}.
%
\begin{verbatim}
)trace MATRIX
)trace List Integer
\end{verbatim}
%
The first command traces all domains currently instantiated with
\spadtype{Matrix}.
If additional domains are instantiated with this constructor
(for example, if you have used \spadtype{Matrix(Integer)} and
\spadtype{Matrix(Float)}), they will be automatically traced.
The second command traces \spadtype{List(Integer)}.
It is possible to trace individual functions in a domain or
package.
See the {\tt )ops} option below.

The following are the general options for the {\tt )trace}
command.

%!! system command parser doesn't treat general s-expressions correctly,
%!! I recommand not documenting )after )before and )cond
\indent{0}
\beginitems
%\item[{\tt )after} {\it S-expression}]
%causes the given \Lisp{} {\it S-expression} to be
%executed after exiting the traced function.

%\item[{\tt )before} {\it S-expression}]
%causes the given \Lisp{} {\it S-expression} to be
%executed before entering the traced function.

\item[{\tt )break after}]
causes a \Lisp{} break loop to be entered after
exiting the traced function.

\item[{\tt )break before}]
causes a \Lisp{} break loop to be entered before
entering the traced function.

\item[{\tt )break}]
is the same as \spadcmd{)break before}.

%\item[{\tt )cond} {\it S-expression}]
%causes trace information to be shown only if the given
%\Lisp{} {\it S-expression} evaluates to non-NIL.  For
%example, the following command causes the system function
%{\tt resolveTT} to be traced but to have the information
%displayed only if the value of the variable
%{\tt \$reportBottomUpFlag} is non-NIL.
%\begin{verbatim}
%)trace resolveTT )cond \_\$reportBottomUpFlag}
%\end{verbatim}

\item[{\tt )count}]
causes the system to keep a count of the number of times the
traced function is entered.  The total can be displayed with
{\tt )trace )stats} and cleared with {\tt )trace )stats reset}.

\item[{\tt )count} {\it n}]
causes information about the traced function to be displayed for
the first {\it n} executions.  After the \eth{\it n} execution, the
function is untraced.

\item[{\tt )depth} {\it n}]
causes trace information to be shown for only {\it n} levels of
recursion of the traced function.  The command
\begin{verbatim}
)trace fib )depth 10
\end{verbatim}
will cause the display of only 10 levels of trace information for
the recursive execution of a user function \userfun{fib}.

\item[{\tt )math}]
causes the function arguments and return value to be displayed in the
\Language{} monospace two-dimensional math format.

\item[{\tt )nonquietly}]
causes the display of additional messages when a function is
traced.

\item[{\tt )nt}]
This suppresses all normal trace information.  This option is
useful if the {\tt )count} or {\tt )timer} options are used and
you are interested in the statistics but not the function calling
information.

\item[{\tt )off}]
causes untracing of all or specific functions.  Without an
argument, all functions, constructors, domains and packages are
untraced.  Otherwise, the given functions and other objects
are untraced.  To
immediately retrace the untraced functions, issue {\tt )trace
)restore}.

\item[{\tt )only} {\it listOfDataToDisplay}]
causes only specific trace information to be shown.  The items are
listed by using the following abbreviations:
\indent{0}
\beginitems
\item[a]        display all arguments
\item[v]        display return value
\item[1]        display first argument
\item[2]        display second argument
\item[15]       display the 15th argument, and so on
\enditems
\indent{0}
\enditems
\indent{0}
\indent{0}
\beginitems

\item[{\tt )restore}]
causes the last untraced functions to be retraced.  If additional
options are present, they are added to those previously in effect.

\item[{\tt )stats}]
causes the display of statistics collected by the use of the
{\tt )count} and {\tt )timer} options.

\item[{\tt )stats reset}]
resets to 0 the statistics collected by the use of the
{\tt )count} and {\tt )timer} options.

\item[{\tt )timer}]
causes the system to keep a count of execution times for the
traced function.  The total can be displayed with {\tt )trace
)stats} and cleared with {\tt )trace )stats reset}.

%!! only for lisp, boot, may not work in any case, recommend removing
%\item[{\tt )varbreak}]
%causes a \Lisp{} break loop to be entered after
%the assignment to any variable in the traced function.

\item[{\tt )varbreak} {\it var1 \lanb{}... varN\ranb{}}]
causes a \Lisp{} break loop to be entered after
the assignment to any of the listed variables in the traced
function.

\item[{\tt )vars}]
causes the display of the value of any variable after it is
assigned in the traced function.
Note that library code must
have been compiled (see \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in Section \ugSysCmdcompileNumber\ignore{ugSysCmdcompile})
using the {\tt )vartrace} option in order
to support this option.

\item[{\tt )vars} {\it var1 \lanb{}... varN\ranb{}}]
causes the display of the value of any of the specified variables
after they are assigned in the traced function.
Note that library code must
have been compiled (see \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in Section \ugSysCmdcompileNumber\ignore{ugSysCmdcompile})
using the {\tt )vartrace} option in order
to support this option.

\item[{\tt )within} {\it executingFunction}]
causes the display of trace information only if the traced
function is called when the given {\it executingFunction} is running.
\enditems
\indent{0}

The following are the options for tracing constructors, domains
and packages.

\indent{0}
\beginitems
\item[{\tt )local} {\it \lanb{}op1 \lanb{}... opN\ranb{}\ranb{}}]
causes local functions of the constructor to be traced.  Note that
to untrace an individual local function, you must use the fully
qualified internal name, using the escape character
\spadSyntax{\_} before the semicolon.
\begin{verbatim}
)trace FRAC )local
)trace FRAC_;cancelGcd )off
\end{verbatim}

\item[{\tt )ops} {\it op1 \lanb{}... opN\ranb{}}]
By default, all operations from a domain or package are traced
when the domain or package is traced.  This option allows you to
specify that only particular operations should be traced.  The
command
%
\begin{verbatim}
)trace Integer )ops min max _+ _-
\end{verbatim}
%
traces four operations from the domain \spadtype{Integer}.  Since
{\tt +} and {\tt -} are special
characters, it is necessary
to escape them with an underscore.
\enditems
\indent{0}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdbootTitle''}{ugSysCmdbootPage} in section \ugSysCmdbootNumber
\downlink{``\ugSysCmdlispTitle''}{ugSysCmdlispPage} in section \ugSysCmdlispNumber
\downlink{``\ugSysCmdltraceTitle''}{ugSysCmdltracePage} in section \ugSysCmdltraceNumber

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdundoTitle}{)undo}
\newcommand{\ugSysCmdundoNumber}{B.27.}
%
% =====================================================================
\begin{page}{ugSysCmdundoPage}{B.27. )undo}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{undo}{ugSysCmdundoPage}{B.27.}{)undo}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )undo}
\item{\tt )undo} {\it integer}
\item{\tt )undo} {\it integer \lanb{}option\ranb{}}
\item{\tt )undo} {\tt )redo}
\end{items}
%
where {\it option} is one of
%
\begin{items}
\item{\tt )after}
\item{\tt )before}
\end{items}

\par\noindent{\bf Command Description:}

This command is used to
restore the state of the user environment to an earlier
point in the interactive session.
The argument of an {\tt )undo} is an integer which must designate some
step number in the interactive session.

\begin{verbatim}
)undo n
)undo n )after
\end{verbatim}
These commands return the state of the interactive
environment to that immediately after step {\tt n}.
If {\tt n} is a positive number, then {\tt n} refers to step nummber
{\tt n}. If {\tt n} is a negative number, it refers to the \eth{\tt n}
previous command (that is, undoes the effects of the last \smath{-n}
commands).

A {\tt )clear all} resets the {\tt )undo} facility.
Otherwise, an {\tt )undo} undoes the effect of {\tt )clear} with
options {\tt properties}, {\tt value}, and {\tt mode}, and
that of a previous {\tt undo}.
If any such system commands are given between steps \smath{n} and
\smath{n + 1} (\smath{n > 0}), their effect is undone
for {\tt )undo m} for any \texht{\smath{0 < m \leq n}.}{0 < m <= n}.

The command {\tt )undo} is equivalent to {\tt )undo -1} (it undoes
the effect of the previous user expression).
The command {\tt )undo 0} undoes any of the above system commands
issued since the last user expression.

\begin{verbatim}
)undo n )before
\end{verbatim}
This command returns the state of the interactive
environment to that immediately before step {\tt n}.
Any {\tt )undo} or {\tt )clear} system commands
given before step {\tt n} will not be undone.

\begin{verbatim}
)undo )redo
\end{verbatim}
This command reads the file {\tt redo.input}.
created by the last {\tt )undo} command.
This file consists of all user input lines, excluding those
backtracked over due to a previous {\tt )undo}.

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber
The command {\tt )history )write} will eliminate the ``undone'' command
lines of your program.

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugSysCmdwhatTitle}{)what}
\newcommand{\ugSysCmdwhatNumber}{B.28.}
%
% =====================================================================
\begin{page}{ugSysCmdwhatPage}{B.28. )what}
% =====================================================================
\beginscroll
%-% \HDsyscmdindex{what}{ugSysCmdwhatPage}{B.28.}{)what}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{items}
\item{\tt )what categories} {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what commands  } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what domains   } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what operations} {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what packages  } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what synonym   } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what things    } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )apropos        } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\end{items}

\par\noindent{\bf Command Description:}

This command is used to display lists of things in the system.  The
patterns are all strings and, if present, restrict the contents of the
lists.  Only those items that contain one or more of the strings as
substrings are displayed.  For example,
\begin{verbatim}
)what synonym
\end{verbatim}
displays all command synonyms,
\begin{verbatim}
)what synonym ver
\end{verbatim}
displays all command synonyms containing the substring ``{\tt ver}'',
\begin{verbatim}
)what synonym ver pr
\end{verbatim}
displays all command synonyms
containing the substring  ``{\tt ver}'' or  the substring
``{\tt pr}''.
Output similar to the following will be displayed
\begin{verbatim}
---------------- System Command Synonyms -----------------

user-defined synonyms satisfying patterns:
      ver pr

  )apr ........................... )what things
  )apropos ....................... )what things
  )prompt ........................ )set message prompt
  )version ....................... )lisp *yearweek*
\end{verbatim}

Several other things can be listed with the {\tt )what} command:

\indent{0}
\beginitems
\item[{\tt categories}] displays a list of category constructors.
%-% \HDsyscmdindex{what categories}{ugSysCmdwhatPage}{B.28.}{)what}
\item[{\tt commands}]  displays a list of  system commands available  at your
user-level.
%-% \HDsyscmdindex{what commands}{ugSysCmdwhatPage}{B.28.}{)what}
Your user-level
%-% \HDindex{user-level}{ugSysCmdwhatPage}{B.28.}{)what}
is set via the  {\tt )set userlevel} command.
%-% \HDsyscmdindex{set userlevel}{ugSysCmdwhatPage}{B.28.}{)what}
To get a description of a particular command, such as ``{\tt )what}'', issue
{\tt )help what}.
\item[{\tt domains}]   displays a list of domain constructors.
%-% \HDsyscmdindex{what domains}{ugSysCmdwhatPage}{B.28.}{)what}
\item[{\tt operations}] displays a list of operations in  the system library.
%-% \HDsyscmdindex{what operations}{ugSysCmdwhatPage}{B.28.}{)what}
It  is recommended that you  qualify this command with one or
more patterns, as there are thousands of operations available.  For
example, say you are looking for functions that involve computation of
eigenvalues.  To find their names, try {\tt )what operations eig}.
A rather large list of operations  is loaded into the workspace when
this command  is first issued.  This  list will be deleted  when you
clear the workspace  via {\tt )clear all} or {\tt )clear completely}.
It will be re-created if it is needed again.
\item[{\tt packages}]  displays a list of package constructors.
%-% \HDsyscmdindex{what packages}{ugSysCmdwhatPage}{B.28.}{)what}
\item[{\tt synonym}]  lists system command synonyms.
%-% \HDsyscmdindex{what synonym}{ugSysCmdwhatPage}{B.28.}{)what}
\item[{\tt things}]    displays all  of the  above types for  items containing
%-% \HDsyscmdindex{what things}{ugSysCmdwhatPage}{B.28.}{)what}
the pattern strings as  substrings.
The command synonym  {\tt )apropos} is equivalent to
%-% \HDsyscmdindex{apropos}{ugSysCmdwhatPage}{B.28.}{)what}
{\tt )what things}.
\enditems
\indent{0}

\par\noindent{\bf Also See:}
\downlink{``\ugSysCmddisplayTitle''}{ugSysCmddisplayPage} in section \ugSysCmddisplayNumber
\downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber
\downlink{``\ugSysCmdshowTitle''}{ugSysCmdshowPage} in section \ugSysCmdshowNumber

\texht{\egroup}{}
\endscroll
\autobuttons
\end{page}
%