\chapter{Running FORM}
\label{running}

The proper way to invoke the running\index{running \FORM} of \FORM\ depends on 
the operating system that is being used. Here we will consider the 
UNIX\index{UNIX} operating system and its derivatives. The version for 
computers with the Windows operating system use Cygwin\index{Cygwin}, which 
is a UNIX derivative as well and hence it functions similarly. In all cases 
a proper call of \FORM\ is
\begin{verbatim}
     form [options] inputfile
\end{verbatim}
The input file\index{file!input} should have a name that ends in the 
extension \verb:.frm:. It is however not needed to specify this extension. 
If this extension is absent, \FORM\ will add it. Example:
\begin{verbatim}
     form myformprogram
\end{verbatim}
and \FORM{} will look for the file \verb:myformprogram.frm:. 
It is also possible to use the standard input as the input, rather than a file, 
by giving \verb:-: for the \verb:inputfile: (which is currently not supported by \ParFORM{}, though). 
The options are 
separated by blanks and start with a minus sign, followed by one or more 
alphabetic characters. They are:
\begin{description}
\item[-c] Error checking only. Notice that this will not work 
     properly if there are conditionals in the preprocessor phase that 
     depend on results obtained at earlier stages of the program.
\item[-C] Next argument/option is a custom filename for the log file.
\item[-d] Next argument/option is the name of a preprocessor 
     variable that will be defined before the run starts. A specific value can be assigned with the
	 syntax {\tt -d VARIABLENAME=VALUE}. The default value is 1.
\item[-D] Same as -d.
\item[-f] Output goes only to log file.
\item[-F] Output only to log file. Further like -L or -ll.
\item[-h] Wait for some key to be touched before finishing the run.
     Basically only for some old window based systems.
\item[-I] Next argument/option is the path of a directory for 
     include, procedure and subroutine files.
\item[-l] Make a regular log file.
\item[-ll] Make a log file without intermediate statistics.
\item[-L] Same as -ll.
\item[-M] Put the PID (process identifier) in the name of the temporary 
     files. This makes for longer names, but gives a better guarantee of 
     uniqueness. If a file with the created name exists already it will be 
     overwritten. This option is for when several instances of \FORM\ are 
     started at nearly the same time as can happen from minos or make (with 
     the make -j option).
\item[-p] Next argument/option is the path of a directory for 
     input, include, procedure and subroutine files.
\item[-{pipe}] Indicates that \FORM\ is started up as the receiving 
     end of a pipe. Action will be taken to set up the proper communication 
     channels.
\item[-q] Quiet option. Only output expressions are printed.
\item[-R] Recover from a crash. See the checkpoint mechanism in 
     \ref{checkpoints}.
\item[-s] Next argument/option is the path of a directory for a 
     setup file.
\item[-si] Same as -q.
\item[-S] Next argument/option is the name of a setup file.
\item[-t] Next argument/option is the path of a directory for temporary files.
\item[-ts] Next argument/option is the path of a directory for temporary sort 
     files.
\item[-T] Puts\index{totalsize} \FORM\ in a mode in which the maximum 
     totalsize is measured and printed at the end of the program. For more 
     information see the "On TotalSize;" statement~\ref{ontotalsize}.
\item[-v] Only the version will be printed. The program terminates 
     immediately after it.
\item[-w] This should be followed immediately by a number. The 
     number indicates the number of worker threads for \TFORM\@. All other 
     versions of \FORM\ ignore this parameter. It should be noted that \TFORM\ 
     is a different program. For more information, please consult 
     chapter~\ref{parallel}.
\item[-W] Turn on the wall-clock time mode in the statistics. 
     See the `\texttt{On wtimestats}' statement~\ref{substaon}.
\item[-y] Run only the preprocessor and dump its output.
\item[-z] The number following is a timelimit for the program in second.
\item[-Z] Removes the .str file on crash, whatever its contents. Under 
     ordinary circumstances at a crash a .str file will not be removed if 
     it has a nonzero content.
\end{description}

\noindent The log\index{log} file\index{file!log} is a file in which all 
output is collected, even when the output appears on the screen already. 
This makes it possible to follow the progress of the program and have a 
record of everything at the same time. The default name of the log file is 
identical to the name of the program without the extension \verb:.frm: but 
with the extra extension \verb:.log:.
Example:
\begin{center}
\begin{verbatim}
     form -t /LocalDisk/mydir -l myformprogram
\end{verbatim}
\end{center}
\FORM\ will run the program in the file \verb:myformprogram.frm:. Its output 
will both be written to the screen and into the file 
\verb:myformprogram.log:. The temporary files (if any) will be made in the 
directory \verb:/LocalDisk/mydir:. This last feature is very useful, 
because writing temporary files across a network can sometimes slow things 
down considerably.

The second way to pass parameters to \FORM\ during startup is by means of 
environment\index{environment variables} variables, assuming of course that 
the system supports them. The following variables are supported:
\begin{description}
\item[FORMPATH]\index{FORMPATH} The directory in which \FORM\ will look for 
procedures and header files, assuming it cannot find them in the current 
directory.
\item[FORMTMP]\index{FORMTMP} The directory in which \FORM\ will make its 
temporary files\index{file!temporary}.
\item[FORMTMPSORT]\index{FORMTMPSORT} The directory in which \FORM{} will make 
its temporary sort files.
\item[FORMSETUP]\index{FORMSETUP} The full path and name of a setup 
file\index{file!setup}.
\end{description}
It should be noted that when a parameter is specified both in the command 
tail and in the environment the value of the command tail will be used.

The third way to pass parameters at startup is by means of a setup 
file\index{file!setup}. 
One of the first things \FORM\ does is to locate such a startup file. The 
procedure that is being followed for this is:
\begin{itemize}
\item If the command tail specifies a setup file, \FORM\ will use this file, 
ignoring all other indications with respect to the setup file. This assumes 
of course that this file exists. If it does not exist \FORM\ passes on to the 
next option.
\item If the command tail specifies a path for the setup file, \FORM\ will 
try to open the file "form.set" in this directory. If this cannot be done 
(by lack of rights or because the file does not exist) \FORM\ passes on to 
the next option.
\item Next \FORM\ tries to open the file "form.set"\index{form.set} in the 
current directory.\item If all else fails, \FORM\ will look for the 
environment parameter FORMSETUP and use its value as the name of a setup 
file.
\end{itemize}
If all the above attempts fail, \FORM\ will not use a setup file. For more 
information about the setup file one should consult the corresponding 
chapter on page \ref{setup}.
