Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Operating System Utilities /

Chapter 2 - System Error Handler / System Error Handler Reference

SysError
You can use the SysError procedure to simulate a system error. Ordinarily, however, only the Operating System invokes this procedure.
PROCEDURE SysError (errorCode: Integer);
errorCode
The system error ID corresponding to the system error condition identified.

DESCRIPTION
The SysError procedure generates a system error with the system error ID specified by the errorCode parameter. The value of the system error ID determines the exact response of the System Error Handler (for example, whether it can intercept the error) and determines the contents of the system error alert box displayed for the error.
The SysError procedure begins by saving all registers and the stack pointer and by storing the system error ID in a global variable (named DSErrCode). The Finder uses this global variable when reporting that an application unexpectedly quit.
If there is not a system error alert table in memory, SysError loads it in. (The global variable DSAlertTab stores a pointer to the current system error alert table. If no system error alert table is in memory, DSAlertTab is NIL.) If there is no table in memory (indicating that the error likely occurred at the beginning of system startup), the System Error Handler draws the "sad Macintosh" icon and plays appropriate ominous tones through the Macintosh speaker. Different tones correspond to different problems that the SysError procedure determines have occurred.
After allocating memory for QuickDraw global variables on the stack and initializing QuickDraw, SysError initializes a graphics port in which the alert box is drawn. The SysError procedure draws the alert box (in the rectangle specified by the global variable DSAlertRect) unless the errorCode parameter contains a negative value. Note that the system error alert box is not a Dialog Manager modal dialog box. Negative values are used to force the SysError procedure to display a sequence of consecutive messages in a system startup alert box without redrawing the entire alert box. If the value in the errorCode parameter does not correspond to an entry in the system error alert table, the default alert box definition at the start of the table is used, displaying the message "Sorry, a system error occurred."
The SysError procedure uses the value in the errorCode parameter to determine the contents of the system error alert box. It looks in the system error alert table resource for an alert definition whose definition ID matches the errorCode parameter. It then draws the text and icon of the alert box according to that alert definition in the system error alert table.
System error alert tables include procedures and button definitions. (See the description of the system error alert table resource in the section "The System Error Alert Table Resource" beginning on page 2-16, for details.) If the procedure definition ID in the table is not 0, SysError invokes the procedure with the specified ID. If the button definition ID in the table is 0, SysError returns control to the procedure that called it. This mechanism allows the disk-switch alert box to return control to the File Manager after the "Please insert the disk:" message has been displayed.
If a resume procedure has been defined, the button definition ID is incremented by 1. This mechanism allows the System Error Handler to use one of two layouts depending on whether a resume procedure has been defined. After drawing the buttons using QuickDraw rather than the Control Manager, SysError performs hit-testing on the buttons, highlighting them appropriately. When a button is pressed, the appropriate procedure is invoked. If there is no procedure code defined for a button, the SysError procedure returns to the routine that called it. The resume procedure is described in the next section.

SPECIAL CONSIDERATIONS
Calling the SysError procedure might cause a system crash even if no condition that would have caused a system crash existed prior to the invocation of SysError.
SysError works correctly only if the following conditions are met:

The trap dispatcher is operative. (See the chapter "Trap Manager" in this book for information about the trap dispatcher.)
The Font Manager procedure InitFonts has been called. Ordinarily, it is called when the system starts up.
Register A7 points to a reasonable place in memory (for example, not to video RAM).
A few important system data structures do not appear to be too badly damaged.

SEE ALSO
A list of system error IDs is provided in Table 2-1 on page 2-7.