.\" -------------------- sec7.t ----------------------
.sh 1 "The Simulator"
.pp
The simulator resides in the SB-Prolog system directory \fIsim\fR.  The following
sections describe various aspects of the simulator.
.sh 2 "Invoking the Simulator"
.pp
The simulator is invoked by the command

.(l
	sbprolog \fIbc_\^file\fR
.)l

where \fIbc_\^file\fR is a byte code file resulting from the compilation of a
Prolog program.  In almost all cases, the user will wish to interact with the
SB-Prolog \fIquery evaluator\fR, in which case \fIbc_\|file\fR will be
\fI$readloop\fR, and the command will be

.(l
	sbprolog \fIPATH\fR/\\\\$\$\readloop
.)l

where \fIPATH\fR is the path to the directory containing the
command interpreter \fI$readloop\fR.  This directory, typically, is the
system directory \fImodlib\fR.
.pp
The command interpreter reads in a query typed in by the user, evaluates it and
prints the answer(s), repeating this until it encounters an end-of-file
(the standard end-of-file character on the system, e.g. ctrl-D), or the user types
in \fIend_\|of_\|file\fR or \fIhalt\fR.
.pp
The user should ensure that the the directory containing the executable file \fIsim\fR
(typically, the system directory \fIsim\fR) is included in the shell variable
\fIpath\fR; if not, the full path to the simulator will have to be specified.
.pp
In general, the simulator may be invoked with a variety of options, as
follows:

.(l
	sbprolog \-\fIoptions\fR \fIbc_\^file\fR
or
	sbprolog \-\fIoption\fR\*<1\*> \-\fIoption\fR\*<2\*> ... \-\fIoption\*<n\*>\fR \fIbc_\^file\fR
.)l

The options recognized by the simulator are described below.
.pp
When called with a byte code file \fIbc_\^file\fR, the simulator begins
execution with the first clause in that file.  The first clause in such a
file, therefore, should be a clause without any arguments in the head
(otherwise, the simulator will attempt to dereference argument pointers
in the head
that are really pointing into deep space, and usually come to a sad end).
If the user is executing a file in this manner rather than using the
command interpreter, he should also be careful to include the undefined
predicate handler `_\|\fI$undefined_\|pred\fR'/1, which is normally defined
in the file \fImodlib/$init_\|sys.P\fR.
.sh 2 "Simulator Options"
.lp
The following is a list of options recognized by the simulator.
.ip \fBT\fR
Generates a trace at entry to each called routine.
.ip \fBd\fR
Produces a disassembled dump of \fIbc_\|file\fR into a file named
`dump.pil' and exits.
.ip \fBn\fR
Adds machine addresses when producing trace and dump.
.ip \fBs\fR
Maintains information for the builtin \fIstatistics\fR/0.  Default: off.
.ip \fBm\fR\ \fIsize\fR
Allocates \fIsize\fR words (4 bytes) of space to the local stack and heap
together.  Default: 100000.
.ip \fBp\fR\ \fIsize\fR
Allocates \fIsize\fR words of space to the program area.  Default: 100000.
.ip \fBb\fR\ \fIsize\fR
Allocates \fIsize\fR words of space to the trail stack.  Default: \fIm\fR/5,
where \fIm\fR is the amount of space allocated to the local stack and heap
together.  This parameter, if specified, must follow the -m parameter.
.sp
.lp
As an example, the command
.(l
	sim -s -p 60000 -m 150000 \e$readloop
.)l
starts the simulator executing the command interpreter with 60000 bytes of
program space, 150000 bytes of local and global stack space and (by default)
30000 bytes of trail stack space; the \fIs\fR option also results in
statistics information being maintained.
.sh 2 "Interrupt Handling"
.pp
SB-Prolog provides a facility for exception
handling using user-definable interrupt handlers.  This can be used both
for external interrupts, e.g. those generated from the keyboard by the user
or from signals other processes; or internal traps, e.g. those caused by stack overflows, encountering undefined predicates, etc.
For example, the ``undefined predicate'' interrupt is handled, by default, by the
predicate `\fI_\|$undefined_\|pred\fR'/1, which is defined in the file
\fImodlib/$init_\|sys.P\fR.  The default action on encountering an undefined
predicate is to attempt to dynamically load a file whose name matches that of the
undefined predicate.  However, the user may easily alter this behaviour by
redefining the undefined predicate handler.
.\" -------------------- end of section sec7.t ----------------------