+.\" 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 5.1 (Berkeley) %G%
+.\"
+.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
projects / unix-history / commitdiff