This Technical Note presents a short macro which an assembly language program can invoke to handle fatal error conditions.
Early versions of Apple-approved sample assembly language code for the Apple IIGS often invoked an APW macro named ERRORDEATH. This macro generated code that was appropriate for handling situations where program execution simply could not proceed due to "fatal" errors, such as a failure to load one or more tools that are required to display more sophisticated error dialogs or the inability to allocate sufficient direct page space for essential tool sets. The macro libraries of prototype APW systems included ERRORDEATH, but the release version does not to promote the use of more sophisticated error handling techniques in commercial software packages. The MPW IIGS release never included ERRORDEATH.
Below are two versions of ERRORDEATH; one is compatible with official standard releases of APW and the other with MPW IIGS. While Apple recommends avoiding the use of ERRORDEATH in software intended for commercial release, we feel the code is still useful for providing minimal error handling capability in prototype code and a brief, yet sophisticated, example of macro construction.
APW Assembler version: MPW IIGS Assembler version: MACRO MACRO &lab ERRORDEATH &text ErrorDeath &text &lab bcc end&syscnt bcc @EDeathEnd pha pha pea x&syscnt|-16 pea @Message>>16 pea x&syscnt pea @Message ldx #$1503 ldx #$1503 jsl $E10000 jsl $E10000 x&syscnt dc i1'end&syscnt-x&syscnt-1' @Message dc.B @EDeathEnd-@Message-1 dc c"&text" dc.B &text dc i1'13',i1'13' dc.B 13 dc c'Error was $' dc.B 'Error Was $' end&syscnt anop @EDeathEnd MEND MEnd
The "active ingredient" in the ERRORDEATH macro is the call to SysFailMgr ($1503), which is made if carry is set at the time control passes to the beginning of the expanded macro code sequence. The APW and MPW IIGS assembler macro expansion mechanisms insert the value represented by the character string argument marker, &text, into the generated code stream and provide SysFailMgr with a pointer to that string. The pseudo-argument, &syscnt, generates unique labels in the positions occupied by the expressions x&syscnt and end&syscnt, which makes it possible to invoke ERRORDEATH more than once during any particular source assembly. In the MPW IIGS version of the macro, the MPW IIGS assembler creates a unique label for any label beginning with the at sign (@), effectively doing the equivalent of the &syscnt in the APW version.
To use ERRORDEATH, simply invoke it after any code sequence or subroutine call that sets the carry when it encounters an error (clears it, otherwise) and leaves an appropriate error code in the accumulator. Note that all ProDOS and Toolbox calls observe this convention. When control passes to the beginning of the ERRORDEATH code sequence, the CPU should be in full-native mode, which means the emulation bit should be clear and the accumulator and index registers should be 16-bits wide). Here is a small code segment which demonstrates invoking the macro:
pushword #21 ; Dialog Manager pushword #0 ; Use any version _LoadOneTool ; If carry is now SET, following macro terminates program execution ; with the "sliding Apple" error screen. IfWeGoofed ERRORDEATH 'Cannot load Dialog Manager!' ; *** If no error, normal execution continues here ***
This and all of the other Apple II Technical Notes have been converted to HTML by Aaron Heiss as a public service to the Apple II community, with permission by Apple Computer, Inc. Any and all trademarks, registered and otherwise, are properties of their owners.