Specifications

Apple II Technical Notes
Apple IIGS
2 of 3 #73: Using User Tool Sets
If you do use the WAP in a conventional way, your xxxStatus function should return TRUE if
the WAP is nonzero; your xxxStartUp function should set the WAP to a non-zero value
pointing to some memory space you own (provided by the caller, or allocated with NewHandle
using a memory ID provided by the caller); and your xxxShutDown function should set the
WAP back to zero.
Since the X register contains the tool set and function number when one of your functions gets
control, it is not necessary for a tool set to be written to be used as a predetermined user tool set
number. At execution time, your tool set can compute the proper error codes and values to send
to GetWAP and SetWAP.
Note: At the bottom of page A-8 of the Apple IIGS Toolbox Reference, Volume 2, “lda
#$90” should read “lda #$8100” for version 1.0 prototype. On page A-10,
the figure should show two RTL addresses (6 bytes) on the stack.
ToStrip and ToBusyStrip Vectors
These two vectors are for tool sets to jump to when a function exits.
ToBusyStrip $E10180
ToStrip $E10184
Inputs: X = error code (0 if no error)
Y = number of bytes of input parameters to strip
When your function is ready to exit, set up the registers and jump to ToStrip. It shifts the six
bytes of RTL addresses up by Y bytes, sets up A and the carry flag appropriately, and returns to
whomever called the tool.
If the system busy flag needs to be decremented, jump to ToBusyStrip instead of ToStrip.
How Can I Load My Tool Set From Disk?
One way to load your tool set from disk is to use InitialLoad or InitialLoad2,
supplying a pathname like “9:MyToolset” (prefix 9 is initially set to the directory containing
your application; prefix 1 also works, but its length is limited to 64 characters). You can then
use SetTSPtr to tell the Tool Locator about your tool set, as shown in Appendix A.
Note that SetTSPtr calls your xxxBootInit function. Even if there is no useful work to be
done at BootInit time, you still need to have a BootInit function (function number 1) that
returns $0000 in the Accumulator and the carry flag cleared..
When you’re done with your tool set, call UserShutdown on the memory ID returned by
InitialLoad, so the memory it’s using is disposed of or made purgeable. (You can shut it