4.3BSD/usr/doc/ps2/07.fp/manCh4.rno

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)manCh4.rno	6.1 (Berkeley) 4/29/86
.\"
.NS 1 "System Commands"
.pp
System commands start with a right parenthesis and they are followed
by the command-name and possibly one or more arguments.  All this information
\fImust be typed on a single line\fP, and any number of spaces or tabs
may be used to separate the components.
.sp 4p
.NS 2 "Load"
.pp
Redirect the standard input to the file named by the command's
argument.
If the file doesn't exist then FP appends '.fp' to the file-name and retries
the open (error if the file doesn't exist).
This command allows the user to read in FP function definitions
from a file.
The user can also read in applications, but such operation is
of little utility since none of the input is echoed at the terminal.
Normally, FP returns control to the user on an end-of-file. 
It will also do so whenever it does a \s-2FRANZ\s+2 reset, e.g.,
whenever the user issues a break, or whenever the system encounters
a non-terminating application.
.sp 4p
.NS 2 "Save"
.pp
Output the source text for all user-defined functions to the file named
by the argument.
.sp
.NS 2 "Csave and Fsave"
.pp
These commands output the lisp code for all the user-defined
functions, including the original source-code, to the file named
by the argument.  Csave pretty prints the code,
Fsave does not.  Unless the user wishes to examine
the code, he should use 'fsave'; it is about
ten times faster than 'csave', and the resulting file
will be about three times smaller.
.pp
These commands are intended to be used with the liszt compiler and
the 'cload' command, as explained below.
.sp
.NS 2 "Cload"
.pp
This command loads or fasls in  the file shown by the argument.
First, FP appends a '.o' to the file-name, and attempts a
load.  Failing that, it tries to load the file named by
the argument.  If the user outputs his function definitions
using fsave or csave, and then compiles them using liszt,
then he may fasl in the compiled code and speed up the execution of
his defined functions by a factor of 5 to 10.
.sp
.NS 2 "Pfn"
.pp
Print the source text(s) (at the terminal) for the
user-defined function(s) named by the argument(s) (error if the function
doesn't exist).
.sp
.NS 2 "Delete"
.pp
Delete the user-defined function(s)
named by the argument (error if the function doesn't exist).
.sp
.NS 2 "Fns"
.pp
List the names of all user-defined functions in alphabetical order.
Traced functions are labeled  by a trailing '@'
(see \(sc 4.7 for sample output).
.sp
.NS 2 "Stats"
.pp
The \*(lqstats\*(rq command has several options
that help the user manage the collection of
dynamic statistics for
functions\**
.(f
\** Measurement of user-defined functions is done with
the aid of the trace package, discussed in \(sc 4.9.
.)f
and functional forms.
Option names follow the keyword \*(lqstats\*(rq,
e.g., \*(lq)stats reset\*(rq.
.pp
The statistic package records the frequency of usage for each function and
functional form; also the size\**
.(f
\** \*(lqSize\*(rq is the top-level length of the argument,
for most functions.  Exceptions are: \fIapndl, distl\fP (top-level length
of the second element), \fIapndr, distr\fP (top-level length of the first
element), and \fItranspose\fP (top level length of each top level
element).
.)f
of all the arguments
for all functions and functional expressions.
These two measures allow the
user to derive the average argument size per call.
For functional
forms the package tallies the frequency of each functional argument.
Construction has an additional statistic that tells the number of
functional arguments involved in the construction.
.pp
Statistics are gathered whenever the mode is on, except for
applications
that \*(lqbottom out\*(rq (\*(IE return bottom \- ?).
Statistic collection
slows the system down by $times 2~$ to $~times 4$.
The following
printout illustrates the use of the statistic package (user input
is emboldened):
.(b
.sp
.hl
.sp
.nf
	\fB)stats on\fP

Stats collection turned on.

	\fB+:<3 4>\fP
7
	\fB!* @ iota :3\fP
6
	\fB)stats print\fP

plus:	times	1

times:	times	2

iota:	times	1

insert:	times	1	size	3

			Functional Args
		Name			Times
		times			1


compos:	times	1	size	1

			Functional Args
		Name			Times
		insert			1
		iota				1
.fi
.sp 4p
.hl
.sp 4p
.)b
.NS 3 "On"
.pp
Enable statistics collection.
.sp 4p
.NS 3 "Off"
.pp
Disable statistics collection.  The user may
selectively collect statistics
using the on and off commands.
.sp 4p
.NS 3 "Print"
.pp
Print the dynamic statistics at the terminal, or, output them to
a file.  The latter option requires an additional argument,
\*(EG \*(lq)stats print fooBar\*(rq prints
the stats to the file \*(lqfooBar\*(rq.
.sp 4p
.NS 3 "Reset"
.pp
Reset the dynamic statistics counters.
To prevent accidental loss of collected statistics, the system
will query the user if he tries to reset the counters without first 
outputting the data (the system will also query the user if he tries
to log out without outputting the data).
.sp 4p
.NS 2 "Trace"
.pp
Enable or disable
the tracing and the dynamic measurement of the user 
defined functions named by the argument(s).
The first argument tells whether to turn tracing off or on and
the others give the name of the functions affected.
The tracing and untracing commands are independent of the dynamic statistics
commands.
This command is cumulative \*(EG
\&')trace\ on\ f1', followed by ')trace\ on\ f2' is equivalent
to ')trace\ on\ f1\ f2'.
.pp
FP tracer output is similar to the \s-2FRANZ\s+2 tracer output: function
entries and exits, call level, the functional argument
(remember that FP functions
have only one argument!), and the result, are printed at the terminal:
.(b
.sp
.hl
.sp 4p
.nf
	)pfn fact

{fact\ (eq0\ ->\ %1\ ;\ *\ @\ [id,\ fact\ @\ s1])}
	)fns

eq0	fact	s1           

	)trace on fact
	)fns

eq0	fact@	s1           

	fact : 2

1 >Enter> fact [2]
|2 >Enter> fact [1]
| 3 >Enter> fact [0]
| 3 <EXIT<\ \ fact\ \ 1
|2 <EXIT<\ \ fact\ \ 1
1 <EXIT<\ \ fact\ \ 2

2
.fi
.sp 4p
.hl
.sp 4p
.)b
.NS 2 "Timer"
.pp
FP provides a simple timing facility to time top-level applications.
The command \*(lq)timer on\*(rq puts the system in timing mode,
\*(lq)timer off\*(rq turns the mode off (the mode is initially off).
While in timing mode, the system reports
CPU time, garbage collection time, and elapsed time,
in seconds.   The timing output follows the printout of the result of
the application.
.NS 2 "Script"
.pp
Open or close a script file. 
The first argument gives the option, the second the optional script file-name.
The \*(lqopen\*(rq option causes a new script-file to be opened and any
currently open script file to be closed.
If the file
cannot be opened, FP sends and error message and, if a
script file was already opened, it remains open.
The command \*(rq)script close\*(rq closes an open script file.
The user may elect to append script output to the script-file
with the append mode.
.NS 2 "Help"
.pp
Print a short summary of all the system commands:
.(b
.sp
.TS
center;
l l.
\ \ \ \ \ \ )help	\&
Commands are:	\&
\&	\&
.T&
l12 l.
load <file>	Redirect input from <file>
save <file>	Save defined fns in <file>
pfn <fn1> ...	Print source text of <fn1> ...
delete <fn1> ...	Delete <fn1> ...
fns	List all functions
stats on/off/reset/print [file]	Collect and print dynamic stats
trace on/off <fn1> ...	Start/Stop exec trace of <fn1> ...
timer on/of	Turn timer on/off
script open/close/append	Open or close a script-file
lisp	Exit to the lisp system (return with '^D')
debug on/off	Turn debugger output on/off
csave <file>	Output Lisp code for all user-defined fns
cload <file>	Load Lisp code from a file (may be compiled)
fsave <file>	Same as csave except without pretty-printing
.TE
.sp
.)b
.NS 2 "Special System Functions"
.pp
There are two system functions that
are not generally meant to be used by average users.
.NS 3 "Lisp"
.pp
This exits to the lisp system.
Use "^D" to return to FP.
.NS 3 "Debug"
.pp
Turns the  'debug' flag on or off.  The command \*(lq)debug on\*(rq
turns the flag on, \*(lq)debug off\*(rq  turns the flag off.
The main purpose of the command is to print out the parse tree.
.bp
.sx 1