@V7 54 2 -5
@L3 COUK1247
80
@V9 0
@YCHAPTER 7 - MUSS USER MANUAL
@G@RCHAPTER 7 - ERROR SIGNALLING AND RECOVERY@G
@V10 1 9 108
@T% 10
@BThis chapter describes the facilities available to the programmer
for signalling, detecting and acting upon error and other
exception conditions. Detailed information on the error codes and error
messages produced by the system is given in Appendix 2.
@S27.1 ERROR DETECTION AND SIGNALLING.
@BAn error condition indicates the failure of some piece of hardware
or software to carry out the task it has been called upon to do.
Usually, the program requesting the operation will require to be informed
of this failure, in order either to effect a local recovery action or to
inform @Gits@G caller in turn that an error has occurred. Thus a general
mechanism is needed whereby a called program (or a hardware operation)
may inform its caller of the existence and nature of any errors which
may arise.
@BThere are two possible approaches to the problem of signalling
detected errors to a calling program. One is to set an error code into
a status variable, which may subsequently be inspected by the caller, and
then to return to the caller. Alternatively the caller may be "trapped" -
i.e. forced into an error handling procedure which it has previously
nominated to deal with the condition. Obviously, each method has
its advantages: the former is often easier to use, particularly for
errors which are expected to occur (e.g. a user mis-typing a parameter);
on the other hand, the trapping method is potentially more efficient
since it eliminates the need to check the status after each action which
might cause an error.
@BMUSS provides for both of these methods, and allows the programmer to
select which is to be used for particular classes of error.
@S27.2 CLASSIFICATION OF ERRORS.
@BFor convenience of recovery, errors are grouped into a number
of error classes, and the recovery action may be specified separately
for each error class. Within the classes, individual errors are identified
by an error code; a complete list is given in Appendix 2.
@BThe basic system distinguishes sixteen different error classes
numbered 0 - 15. The first ten of these are system defined; classes 10-15 are
available for use by applications software. The ten system-defined error classes
 are:@
@Q 11
@
@M0 - program fault
@N1 - limit violation
@N2 - timer runout
@N3 - external interrupt
@N4 - organisational command error
@N5 - Input/Output setup errors
@N6 - Input errors
@N7 - Job control command errors
@N8 - Programming language runtime errors
@N9 - System Library errors.
@S37.2.0 Program Faults
@BThis class consists mainly of errors detected by hardware during
instruction execution - for example, arithmetic overflow, access to
illegal store addresses, etc.
@S37.2.1 Resource Limit Violations
@BThese errors are signalled by the system kernel when a process exceeds
one of its stated resource limits - for example, processing time.
@S37.2.2 Timer Interrupts
@BThese are not strictly errors at all, but are handled by the same
trapping mechanism. The process may request to be informed after it has
used a specified amount of processing time (see System Programmers' Manual).
The mechanism is used by the basic system to obtain an "early warning" of
the processing time limit violation, by requesting a timer interrupt
shortly before the actual time limit is exceeded.
@S37.2.3 External Interrupts
@BThese are not strictly errors at all, but are handled by the same
mechanism. An external interrupt is triggered by some other process
(see System Programmers' Manual), usually a device controller, and its main
use is to implement the "break-in" facility for interactive jobs.
@S37.2.4 Organisational Command Errors
@BThe organisational command procedures which form the interface with
the MUSS kernel all signal errors via this error class.
@S37.2.5 Input/Output setup error
@BErrors in the organisation of input/output streams are included
in this error class.
@S37.2.6 Input errors
@BThe errors in this class are those which commonly result
from faulty input, rather than a faulty program - for example, reading
beyond the end of a file, or reading non-numeric data in a context
where numeric data is expected.
@S37.2.7 Job control command errors
@BThis class is reserved for errors detected by the job control command interpre
ter.
@S37.2.8 Programming language runtime errors
@BThis class consists of language dependent errors, such as accessing
outside the bounds of an array or calling an undefined procedure.
To the user they are logically an extension of class 0.
@S37.2.9 System Library Errors
@BAll errors detected by the major user facilities of the basic system
(i.e. those described in this manual, such as EDIT, TEXT, the compilers etc.) fa
ll
into this class.
@S27.3 PROCEDURES FOR ERROR HANDLING.
@
@
1) @JSET.TRAP(I,P)
@BThis procedure nominates P2, which should be a procedure with two
parameters, as the trap procedure to be involved on detecting an error in
class P1.
@
@
2) @JREAD.TRAP(I)P
@BThis procedure returns as its result a reference to the current trap
procedure for errors of class P1.
@
@
3) @JSET.RECOVERY.STATUS(I,I)
@BThis procedure is used to control whether the "trapping" or "status" mechanism
is to be used for errors of class P1. P2 specifies the mechanism to be
used: zero means trapping, 1 means status.
@
@
4) @JREAD.RECOVERY.STATUS(I)I
@BThis procedure returns the current recovery status for error class P1.
@
@
5) @JENTER.TRAP(I,I)
@BThis procedure signals the occurrence of the error with class P1,
code P2. Depending upon the recovery status in force for error class P1,
the error will be signalled either via a trap or via the global
status parameter PW0.
@
@
6) @JRETURN.FROM.TRAP()
@BThis procedure enables a user trap procedure to reset
the process to the state it was in just before the trap
occurred. The process then continues from the reset point.
@S27.4 PROCEDURES FOR FAULT MONITORING.
@
@
1) @JOUT.M(I,I)
@BThis procedure outputs, on the currently selected stream, a suitable
error message for error class P1 code P2.
@
@
2) @JOUT.T(I,I)
@BThis procedure outputs, on the currently selected stream, a standard trap
diagnostic for error class P1 code P2 (i.e. an error message and other
diagnostic information).
@S27.5 NOTES ON THE HANDLING OF ERRORS.
@
@
1)@IError classes 0-3 are implemented within the operating system
kernel, and are @Galways@G handled via the trapping mechanism (SET.RECOVERY.STAT
US)
should not be used).@
@
2)@IError class 4 may be handled by either trapping or status, but most
of the system library procedures assume that the status mechanism will be
used. Thus some library operations may not work correctly if trapping
is activated for error class 4.@
@
3)@ILibrary procedures which alter the trap procedures or the recovery status
should restore their original values prior to exit. Errors which have
been detected may be "passed back" to the caller by restoring the original
trap procedure and status values, and then re-calling ENTER.TRAP.@
@
4)@IIf the "status" form of error recovery is active, then an appropriate
error code is set into the global status variable PW0, and the
ENTER.TRAP procedure returns immediately. Thus, in cases where status
recovery may be in use, calls of ENTER.TRAP should always be followed
immediately by a return to the calling program which may then inspect the
status variable.
@I@BGenerally, use of the status form of recovery is only recommended
in small localised code sequences.@
@
5)@IThe status variable PW0 is encoded as two bytes, the most significant
giving an error class, and the least significant an error code.
@S27.6 HIGH LEVEL LANGUAGE RUN TIME DIAGNOSTICS.
@BAt the start of running a high-level language program the traps
are set to enter the high-level language dump and on-line
debugging facility (MURD). This is a language independent package
for use with the standard MUSS language, MUSL, Pascal and
Fortran 77. The procedure:@
@
@M@JTL.TRAP(I,I)
@
is entered initially with error class P1 and code P2. This prints
the reason for the program failure, the line number of the line
where the failure occurred and the procedure in which it occurred.
@BIf the program is running off-line the procedure@
@
@M@JTL.DUMP()
@
is then entered.
@BThis prints the variables of the current procedure. It then
prints the line number and procedure where the current procedure
was called and the variables of that procedure. This is repeated
until the outermost level of the program is reached.
@BIf the program is running on-line the procedure@
@
@M@JRD.DEBUG()
@
is then entered.
@BThe TL.DEBUG user interface allows users to type@
@Q 4
@
@M(a) run-time diagnostic commands.
@N(b) names of variables to be inspected or changed.
@N(c) MUSS commands.
@SRUN TIME DIAGNOSTIC COMMANDS.
@BThese commands are identified by a single letter.
@BA All : prints names and values of all variables of the
current procedure.
@BN Next : move to next procedure out in the dynamic chain.
@BS Surrounding : move to next procedure/block in the static chain.
@BC Current : move back to the procedure in which the fault occurred.
@BD Dump : the RD.DUMP procedure to give a complete
traceback of variable values.
@X {| }`
@BG {<page>.}<line> Go : restart the program
at the specified line. If page is omitted, the current page is
assumed. Zero indicates the current line.
@BI {<page>.}<line> Insert : a breakpoint is inserted at
the specified line.
@BR {<page>.}<line> Remove : the breakpoint, at the beginning
of the specified line, is removed.
@X {{ }}
@BP Profile : the profiles and stored tracebacks are printed
out.
@BE Enter : to re-enter the program after executing the breakpoint.
@BQ Quit : end run-time diagnostics and revert to job control
command processing.
@BV Variable : move into variable inspecting and changing mode.
@B** Treat the line as an MUSS job control command and execute
that command.
@SVARIABLE INSPECTION AND CHANGING.
@BThe value of a variable (or any of its components) will
be printed out when <variablename> is typed in, followed by any of
the following, indicating the required component.@
@T% 10 30
@
@
%^%to dereference a pointer@
%[] or ()%for all elements of a vector@
%[n] or (n)%for the nth element@
%@@%for all fields of an aggregate type@
%<fieldname>%for one field only.@
%Spaces must be omitted before the character@
%^, [, (, ], ), @@.@
@BTo alter the value of a variable (or component), the
above sequence is followed by /<value>. In the case
of a vector for which only certain elements need altering,
* is typed for each element unaltered.
@B* command letter reverts to diagnostic command mode.
@B** causes the line to be treated as an MUSS job control
command and that command is executed.
@SMUSS COMMANDS.
@BAs indicated above any MUSS command on a line by itself
preceded by ** is interpreted and executed immediately.
@F
