This module will add a routine onto the error vector (ErrorV) which will test the error number of any errors generated against a list of error numbers. If an error is generated which matches an entry in the list, TrapError will do one of several possible things:
The debug build of this module will output a dump of all errors passing through the error vector to a file.
This file can be specified by setting the system variable <TrapError$File>
. While this variable
is not set, no dump output will be generated. If the file specified already exists, the debug output will be
appended at the end. If a directory exists with the same name as the file specified, no error message or debug
output will be generated.
The debug output consists of lines of the following format (all values are eight-digit hexadecimal):
<Monotonic time of error> <space> <Error number> <space> <Error text> <linefeed>
Word | Meaning |
0 | lowest error number in list - 1 |
1 | highest error number in list + 1 |
2 | error number |
3 | action to take |
4 | value to pass in R12 |
6 | error number |
... | ... |
n | 0 (end of list) |
When the table is empty, word 0 contains &7FFFFFFF and word 1 contains &C0000000. This will allow very quick detection of when an error number should not be checked and thus be passed on.
Every time a number is removed from the table, it is compared against words 0 and 1 (-1). If it matches either (or both), the table will be re-scanned to get the next lowest/highest.
The TrapError module provides a *Command equivalent to each SWI, with the same name and the same parameters. The only difference of note is that all *Commands which would have a flags parameter which should be zero, have that parameter omitted. For example, *TrapError_Off takes no parameters. Use *Help for more information.
TrapError_Off
(SWI &52DC0)
On entry
Errors: "This TrapError SWI must have a flags word of zero" (&816A03)
TrapError_On
(SWI &52DC1)
On entry
Errors:
TrapError_AddError
(SWI &52DC2)
On entry
R0 | Meaning |
0 | Perform an OS_Reset |
1 | Stop the error message from being passed-on |
2 | Replace the error block pointer with another (in R2) |
3..255 | Reserved (do not use) |
> 255 | Issue a CallBack to the address in R0 (bits 0 and 1 used for flags) |
All other codes for R0 are reserved and will return an error. If the error number in R1 is already in the list, the action specified in R0 will replace that already defined.
If R0 contains a value greater than 255, it is assumed to be the address of some routine to be called when an error of the specified type is detected. In this case, bits 0 and 1 of R0 contain flags as follows:
Bits 0,1 | Meaning |
0 | CallBack to code and pass-on the error as normal |
1 | CallBack to code and don't pass-on the error |
2 | Reserved (do not use) |
3 | Reserved (do not use) |
When the error R1 is detected, a CallBack to R0 is issued. The code at R0 will be entered when RiscOS is next idle and threaded out. The processor will be in SVC mode with interrupts disabled. R2 contains the value to be passed in R12 to your code (ie: a private workspace pointer). This register can contain any value and is not checked by TrapError.
Errors:
TrapError_RemoveError
(SWI &52DC3)
On entry
Errors:
TrapError_ResetTable
(SWI &52DC4)
On entry