4.3BSD/usr/contrib/apl/doc/man.7

Compare this file to the similar file:
Show the results in this format: 

.NH 1
What are those funny messages?
.PP
You probably figured that at some
point in this manual you'd
see something about error messages.
Unfortunately,
errors do occur,
and some of \*a's error messages
can really throw you.
Users of other \*a systems have
little advantage over \*a novices in this
area,
for \*u \*a
error messages are,
in general,
nonstandard.
To make matters worse,
\*a's status messages can
be cryptic at times.
Thus,
in this section we'll
explore some of the more common
status and error messages.
.PP
First,
some of \*a's less obvious
and relatively common
abbreviations are:
.DS
asgn		assignment
cat		catenation
crc		circle
dfmt		dyadic format
dibm		dyadic i-beam
exec		execute
fn		function
imm		immediate
iprod		inner product
mdom		monadic domino
menc		monadic encode
miot		monadic iota
oprod		outer product
red		reduction
var		variable
.DE
.PP
There are three major types of
error messages which may be
generated as a result of
an \*a session.
The error message may be
the result of a fatal error
in \*a which has caused \*a
to abort,
the result of some internal
problem in \*a,
or an error produced by
incorrect use of \*a.
.NH 2
Non-fatal Error Messages
.PP
Usually,
\*a can detect serious errors
before they become fatal.
When this occurs,
it will issue an error message
but will not terminate.
You can then take
appropriate action.
Unfortunately,
unlike most \*a
implementations,
\*u \*a
does not report the position on
the line where the error occurred.
However,
a traceback from the function in
which the error occurred is printed.
(See ``The State Indicator''
for more information on function
tracebacks and error recovery.)
.PP
As an example of this type of error,
it is possible to completely
fill up the internal workspace.
Usually \*a will not
attempt to get more
internal workspace memory
if it already has the
maximum permissible amount.
It will then inform you:
.sp
workspace exceeded
.sp
Other possible messages
of a similar nature are:
.DS
directory botch
save botch
elid botch
stack overflow
pop botch
.DE
In general,
if an error message such
as this occurs,
you should save your
internal workspace
in a different file
than you started from
(in case it may
have been ``corrupted''
or otherwise damaged
by the error in \*a),
and then should exit
\*a and restart.
You can then determine
whether or not anything
happened to your workspace,
and can recover any losses
from the original workspace file.
These type of errors generally
occur as the result of some other
error,
such as a function which
calls itself indefinitely
or declaring an array which
is too large for the workspace.
.PP
By far,
majority of non-fatal error messages
produced by \*a are
not serious,
but simply indicate
some error in the
definition or execution
of a function.
These errors fall into
some common types:
.IP "conformability" 20
The variable which you are
passing to a function or
operator does not ``conform''.
That is,
it is not the proper shape
(e.g. array has the wrong number of
dimensions or a scalar
is used instead of an array, etc.)
For example,
trying to add a 2X2
array to a 2-element
vector will produce
this error.
.IP "botch" 20
A ``botch'' can occur for
several reasons.
Attempting to read a
non-existant
element of an array
will produce a
``getdat botch''.
(Storing into a
non-existant variable
or array element will
produce a ``putdat botch''.)
.IP "domain" 20
A domain error means that
somehow the variable passed
to a function or operator
cannot be used.
For example,
attempting to take
the logarithm of
a negative number will
produce a
``log domain''
error message.
.IP "index" 20
A bad index was specified.
A quick example of this
error is to have origin=1
and attempt to access
A[0].
Attempting to concatenate
two arrays along a
non-existant dimension
will produce a
``cat index''
error message.
.IP "syntax" 20
This error message is
probably painfully
familiar \(em
it indicates that
the indicated \*a
expression was not
syntactically correct.
If this error occurs
during the processing
of a function,
the traceback
will show which line
was incorrect.
.IP "rank" 20
This type of error
indicates that the
argument to an operator
or function has
the wrong number of
dimensions.
As an example,
if you attempt to declare
an array with more than
8 dimensions,
you will get a
``max rank''
error message.
.PP
Some other common error
messages do not fall into
any of the above classes.
These include:
.IP "used before set" 20
This message means that a variable
was referenced which had not
yet been defined.
An easy example:
.DS
	y { 2
	z { x + y
x: used before set
.DE
.IP "no fn result" 20
This error occurs when an
attempt is made to use the
returned value of a function
which doesn't return a value.
As an example, if the
function ``xyz'' returns
no value, then the following
sequence will result in an error:
.DS
	z { xyz
no fn result
.DE
.IP "si damage" 20
This error message,
discussed earlier,
usually occurs when
an attempt is made to
edit a function which
is suspended due to
an error.
Type ``)reset'' and
then you may edit
the function.
.IP "can't open file" 20
This error message occurs when
a non-existant file is
used for a ``)load'',
``)read'',
``)save'',
etc.
.IP "not a fn" 20
In most cases,
an attempt to use a function
which has not been defined,
or which has been defined as
a variable,
will result in a ``syntax error.''
There are some special
circumstances
in which this error will slip
past the ordinary error-checking code.
In the event this occurs,
the message ``name: not a fn''
will be printed.
.NH 2
Fatal Error Messages
.PP
In most cases,
when \*a detects that
some irreparable damage
has been done,
it will print an error
message of the form:
.sp
fatal signal: message
.sp
where the ``message'' represents a
type of \*u termination.
The most common one probably is
``segmentation violation'',
which means that \*a needed too
much memory for its
internal workspace
and was aborted in its attempt to
get more than permitted in \*u.
Other possible messages include:
.DS
quit
illegal instruction
trace trap
emt trap
bus error
bad sys call
write no pipe
.DE
Despite the severity of the error,
\*a attempts to dump the workspace
into a file named ``aplws.abort''
in order to facilitate recovery.
This file should be viewed with suspicion.
If another fatal signal occurs while
this dump is being performed,
\*a will abort immediately,
without completely writing the file.
Even if the dump was successful,
the file format may not be internally
consistent since \*a was probably
changing something when it was forced to abort.
It is therefore advised that
you restart \*a and recover
any information you need from this dump file,
writing that information into a new workspace
(see the description of the ``)vsave''
system command in Appendix B).
.I Never
copy ``aplws.abort'' into your original
workspace file without thoroughly
checking it out.
.PP
In some rare cases,
\*a is unable to
print a termination message,
and the system aborts it.
This usually will result in a
message such as:
.sp
Memory fault -- core dumped
.sp
and the operating system
will produce a file named
``core'' in your directory.
This file is probably useless
and you can delete it with:
.sp
$ rm core