Path: utzoo!attcan!telly!lethe!yunexus!ists!helios.physics.utoronto.ca!news-server.csri.toronto.edu!cs.utexas.edu!sdd.hp.com!elroy.jpl.nasa.gov!jarthur!nntp-server.caltech.edu!toddpw
From: toddpw@chairie.caltech.edu (Todd P. Whitesel)
Newsgroups: comp.sys.apple2
Subject: The word on tool patching
Message-ID: <1991Feb22.054339.2414@nntp-server.caltech.edu>
Date: 22 Feb 91 05:43:39 GMT
Sender: toddpw@nntp-server.caltech.edu (Todd P. Whitesel)
Organization: California Institute of Technology, Pasadena
Lines: 58

The following is quoted from IIgs tech note #87, concerning tool dispatcher
patching. The full text is on tybalt.caltech.edu (I'm not sure if apple.com
has this one yet, it's more recent than january '90 which is where apple.com
appears to be frozen.)

This note describes Apple's official word on patching the tool dispatcher,
and it presents a good reason for using SetTSPtr and SetDefaultTPT. The
warning in toolbox ref 3 for applications not to call SetDefaultTPT is
a good one, but it doesn't consider INIT's applications and neither do I --
the reason being that SetDefaultTPT is only dangerous because it forces
all currently loaded tools to stay loaded, and when INITs are running this
is not nearly as dangerous as when Applications, real desktop applications,
are running.

Tool functions have to expect two RTL's on the stack because that is how
the 'second' tool vectors ($e1/4 and $e1/c) are called -- with two RTL's on
the stack. The normal vectors add an RTL before calling the actual tool
functions -- the whole reason for doing it is to allow for high level
languages that require tool glue (Orca/C does this with functions that
return structs, I believe, but didn't do it properly and DTS put out a
fixed library), or applications that call internal subroutines which
call the toolbox and then handle errors automatically, and so on.

Todd Whitesel
toddpw @ tybalt.caltech.edu
_____________________________________________________________________________

This Technical Note presents the Apple standard way to patch into the Apple 
IIgs Tool Dispatcher vectors.

This Note presents MPW IIgs assembly-language code which provides the Apple-
standard way for utilities to patch and unpatch the Tool Dispatcher vectors.  
If all Tool Dispatcher patches follow this protocol, patches can be installed 
and removed in any order, without ever accidentally unpatching somebody who 
patched in after the one getting removed.

Using this protocol, each patch begins with a header in a standard form--a form 
recognizable by these routines (see PatchHeader).  This way routines (like 
RemoveE10000) can scan through the list of patches and remove one from the 
middle.

If your patch is going to stay in the system until shutdown, use this standard 
patch protocol anyway.  This way other utilities can still recognize your 
patch and scan past it to find the next one.  This Note is not just to show 
you a way to patch the tool dispatcher--it's to show you the way.  If you patch 
tool dispatcher vectors in any other way, you strip other utilities of their 
ability to remove their patches.

Of course, patching the Tool Dispatcher vectors slows down all toolbox calls, 
so you shouldn't patch the tool dispatcher without a pretty good reason.  If 
you need to patch a toolbox function, it is usually better to do it by 
modifying a tool set's function pointer table instead of patching the 
dispatcher.

The code in this note is specific to the System tool dispatch vectors ($E10000 
and $E10004), but the same technique is recommended for the User tool dispatch 
vectors--just change $E10000 to $E10008, $E10004 to $E1000C, and 
ToolPointerTable to UserToolPointerTable.


Brought to you by Super Global Mega Corp .com