Specifications
Apple IIGS
#73: Using User Tool Sets 1 of 3
Apple II
Technical Notes
Developer Technical Support
®
Apple IIGS
#73: Using User Tool Sets
Revised by: Dave “flag bits” Lyons July 1991
Written by: Dave Lyons November 1989
This Technical Note explains how to write a user tool set and why writing a user tool set is better
than stealing a system tool set number.
Changes since January 1991: Expanded recommendation on where to keep user tool set files
on disk and clarified SetTSPtr information.
The Apple IIGS Toolbox Reference describes system tool sets, which are usually called through
the system tool dispatcher vectors 1 ($E10000) and 2 ($E10004).
There are 255 possible system tool set numbers (1 through 255). All of these are reserved for
definition by the system. If your program is “borrowing” a system tool set number, please feel
guilty and switch over to the user tool set numbers. There are 255 of them too, and they’re
called through user tool dispatcher vectors 1 ($E10008) and 2 ($E1000C). All 255 user tool set
numbers are available for the current application to use as it chooses. (Desk accessories are
forbidden to use user tool sets.)
Of the four tool dispatcher vectors, only the first one ($E10000) has received a lot of publicity.
$E10008 works just like $E10000, except that it passes control to a user tool set instead of a
system tool set.
The second vector of each pair ($E10004 and $E1000C) works just like the first, except that one
extra RTL address must be pushed onto the stack after any parameters are pushed. This way you
can have a subroutine to do some or all of your toolbox dispatching, and that subroutine can do
extra processing before or after the tool call, or both.
How Can I Write a User Tool Set?
Appendix A of Toolbox Reference, Volume 2, shows how to write a user tool set. Your tool
set’s Work Area Pointer is a four-byte value you can set with SetWAP and get with GetWAP.
The WAP value is already loaded into the Y and A registers every time one of your tool set’s
functions gets control. The traditional use for the WAP is to keep track of an area of memory
owned by your tool set.