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:<P> <OL> <LI>Call OS_Reset to reboot the machine <LI>Claim the error so it doesn't get passed-on <LI>Branch to some code routine </OL> This depends on the action specified for each error number. The default action can be altered after an error number has been added to the list. The default state of the module is <B>on</B>. The default table (list) of error numbers to trap is <B>empty</B>.<P> <H3>Debugging</H3> <P> 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 <CODE><TrapError$File></CODE>. 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.<P> The debug output consists of lines of the following format (all values are eight-digit hexadecimal):<P> <PRE><Monotonic time of error> <space> <Error number> <space> <Error text> <linefeed></PRE><P> <HR> <H3>Table format</H3> <P> <TABLE ALIGN='center' BGCOLOR='#f3F3F3' BORDER='1' COLS='2' WIDTH='80%'> <TR BGCOLOR='#c0C0C0'><TD> <I>Word</I> <TD> Meaning <TR><TD> 0 <TD> lowest error number in list - 1 <TR><TD> 1 <TD> highest error number in list + 1 <TR><TD> 2 <TD> error number <TR><TD> 3 <TD> action to take <TR><TD> 4 <TD> value to pass in R12 <TR><TD> 6 <TD> error number <TR><TD> ... <TD> ... <TR><TD> n <TD> 0 (end of list) </TABLE> <P> 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.<P> 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.<P> <HR> <H3>Overview of TrapError *Commands</H3> <P> 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.<P> <HR> <H3>Overview of TrapError SWI calls</H3> <!-- SWI &52DC0 "TrapError_Off" --> <P ALIGN='RIGHT'> <BIG>TrapError_Off</BIG><BR> <BIG>(SWI &52DC0)</BIG> <P ALIGN='LEFT'> <B>On entry</B> <UL> R0 = flags (<I>should be zero</I>) </UL> <B>On exit</B> <UL> None </UL> Remove TrapError from the Error Vector. No errors will pass through the TrapError filtering code after this SWI call, until TrapError_On is called. If TrapError is already off, no action is taken.<P> Errors: "This TrapError SWI must have a flags word of zero" (&816A03)<P> <!-- SWI &52DC1 "TrapError_On" --> <HR> <P ALIGN='RIGHT'> <BIG>TrapError_On</BIG><BR> <BIG>(SWI &52DC1)</BIG> <P ALIGN='LEFT'> <B>On entry</B> <UL> R0 = flags (<I>should be zero</I>) </UL> <B>On exit</B> <UL> None </UL> Add TrapError to the Error Vector. After this call, any errors which occur will pass through the TrapError filtering routine.<P> Errors: <UL> "This TrapError SWI must have a flags word of zero" (&816A03) </UL> <!-- SWI &52DC2 "TrapError_AddError" --> <HR> <P ALIGN='RIGHT'> <BIG>TrapError_AddError</BIG><BR> <BIG>(SWI &52DC2)</BIG> <P ALIGN='LEFT'> <B>On entry</B> <UL> R0 = flags word contains the action to take <UL> 0 ... reboot when detected<BR> 1 ... ignore when detected (ie: don't pass on)<BR> 2 ... replace the error block pointer with another<BR> Values 3 to 255 are <B>reserved</B><BR> Values greater than 255 are assumed to be an address of code to branch to </UL> R1 = error number to add<BR> R2 = value to pass in R12 to code (if R0 > 255) or pointer to replacement error block (if R0 = 2) </UL> <B>On exit</B> <UL> R0 ~ R2 preserved </UL> Add an error number to a table of error numbers which TrapError will trap. If TrapError is on and an error is generated with the code specified in R1, TrapError will do one of the following, depending on the value in R0:<P> <TABLE ALIGN='center' BGCOLOR='#f3F3F3' BORDER='1' COLS='2' WIDTH='80%'> <TR BGCOLOR='#c0C0C0'><TD><I>R0</I> <TD><I>Meaning</I> <TR><TD>0 <TD>Perform an OS_Reset <TR><TD>1 <TD>Stop the error message from being passed-on <TR><TD>2 <TD>Replace the error block pointer with another (in R2) <TR><TD>3..255 <TD>Reserved (do not use) <TR><TD>> 255 <TD>Issue a CallBack to the address in R0 (bits 0 and 1 used for flags) </TABLE> <P> 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.<P> 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:<P> <TABLE ALIGN='center' BGCOLOR='#f3F3F3' BORDER='1' COLS='2' WIDTH='80%'> <TR BGCOLOR='#c0C0C0'><TD><I>Bits 0,1</I> <TD><I>Meaning</I> <TR><TD>0 <TD>CallBack to code and pass-on the error as normal <TR><TD>1 <TD>CallBack to code and don't pass-on the error <TR><TD>2 <TD>Reserved (do not use) <TR><TD>3 <TD>Reserved (do not use) </TABLE> <P> 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.<P> Errors: <UL> "This is not an error number which can be trapped by TrapError" (&816A00)<BR> "This action code is not supported by this version of TrapError" (&816A01)<BR> "TrapError can only trap up to 125 error numbers" (&816A02) </UL> <!-- SWI &52DC3 "TrapError_RemoveError" --> <HR> <P ALIGN='RIGHT'> <BIG>TrapError_RemoveError</BIG><BR> <BIG>(SWI &52DC3)</BIG> <P ALIGN='LEFT'> <B>On entry</B> <UL> R0 = flags word (<I>should be zero</I>)<BR> R1 = error number to remove </UL> <B>On exit</B> <UL> R0 ~ R1 preserved </UL> Remove an error number from the table of those to trap. If this number is not found in the table, or the table is empty, no action will be taken.<P> Errors: <UL> "This TrapError SWI must have a flags word of zero" (&816A03) </UL> <!-- SWI &52DC4 "TrapError_ResetTable" --> <HR> <P ALIGN='RIGHT'> <BIG>TrapError_ResetTable</BIG><BR> <BIG>(SWI &52DC4)</BIG> <P ALIGN='LEFT'> <B>On entry</B> <UL> None </UL> <B>On exit</B> <UL> None </UL> Reinitialise the table to the same state as when the module started. The state of TrapError will remain unchanged by this call.