Getting through CUSToms

Technote PT 13July 1987

Revised by: March 1988
Written by: Rick Blair July 1987

This technical note provides a way for developers to allow sophisticated users to add code to an off-the-shelf application. Using this scheme, the user can easily install the code module; the application has to know how to call it and, optionally, be able to respond to a set of predefined calls from the custom package.


The following code makes heavy use of features of the Macintosh Programmer's Workshop. It also assumes a basic familiarity with the standard Sample program included with MPW. The Pascal code (which is here only as an example implementation of the mechanism) is presented as only those sections which differ from Sample.p. The assembly language code also includes MPW-only features, such as record templates. Some of these are explained in TN.PT.Signals.

In addition, since the order in which parameters to various routines are passed is critical, special care will have to be taken in writing interfaces for use with C. It is probably best to declare them as Pascal in the C source.


Basically, we create a code resource of type CUST with an entry point at the beginning which takes several parameters on the stack; this code is reached via a dispatching routine which is written in assembly language.

The data passed on the stack to this dispatcher includes:

* a selector (to specify the operation desired)

* the address of a section of application globals (for communication back and forth

between the application and the module when the stack parameters are insufficient)

* a handle which references the custom code resource on the stack.

Other parameters may be added (as long as they are pushed on the stack before the required ones) if desired. Since these extra parameters would always have to be included in any calls to a given package, it might be more convenient to use the application global space area which is accessed through the appaddr parameter.


Your application must contain the following global data and procedure declarations to support this model:

      custhandle: Handle;

      {the following globals constitute the data known to the custom code}
      appdispatch: ProcPtr; {address of dispatch routine custom code can call}
	 {examples of further application globals for the custom package:}
      paramptr: Ptr; {general pointer used as param. to appdispatch code}
      paramword1: INTEGER;
      paramword2: INTEGER;
      CUSTerr: INTEGER;
      {any other globals the module should get at}

     {the two assembly language glue routines which are linked into the
	PROCEDURE CustomInit(resID: INTEGER; VAR custhandle: Handle);
      EXTERNAL; {the routine used to set up the custhandle resource handle}

 	PROCEDURE CustomCall({application & package-specific paramters} 		            			selector: INTEGER; appaddr: UNIV Ptr; ourhandle: 					Handle);
      EXTERNAL; {this is the code dispatcher}

    	{this is called by the custom package to perform a service which is more 	 easily provided by the application; since we pass a pointer to it to the 	 package, CustDispatch must be at the outermost nesting level in the main 	 segment }

 	PROCEDURE CustDispatch(selector: INTEGER);

         CASE selector OF
         END; {CASE}
 	 END; {CustDispatch}

    {your initialization code should contain the following:}

      {Custom package initialization stuff}
      appdispatch := @CustDispatch; {put pointer where the package can see it}
      CustomInit(69,custhandle);    {our CUST resource has ID = 69}

    {then whenever you want to invoke the package you use CustomCall}

You must also assemble CustomInit and CustomCall and link them with into your application. The custom package itself can be written in any language which can produce stand-alone code.

The example

CustomCall is only referenced once in this example. When a variety of unrelated functions are provided, however, it is more convenient to provide a separate interfacing procedure to invoke each one and have them make their own CustomCall calls.

Note that this example is somewhat contrived; you probably wouldn't "externalize" the code for finding a word or sequence of characters like this. This is an idealized situation. More realistic uses would be: to add-on special routines to a database to perform custom calculations or the like; allow for localization when code is required (and hooks aren't already provided); let documents carry around code which may vary among software versions, etc. so that older documents would be able to work alongside the new ones, etc.

What it does

We simply add a new menu to the sample program which allows Find by characters or word. We just pass the menu item to the package and let it do the finding; it then calls back to the application dispatch routine to highlight text or display the "not found" message.

The Pascal source for the example application appears first:


      {$LOAD ::PInterfaces:most.dump}
      Memtypes,Quickdraw,OSIntf,ToolIntf,PackIntf {,MacPrint}
      , {$U ErrSignal.p} ErrSignal;

      appleID = 128; {resource IDs/menu IDs for Apple, File and Edit menus}
      fileID = 129;
      editID = 130;
      findID = 131;

      appleM = 1; {index for each menu in myMenus (array of menu handles)}
      fileM = 2;
      editM = 3;
      findM = 4;

      menuCount = 4; {total number of menus}

      windowID = 128; {resource ID for application's window}

      undoCommand = 1; {menu item numbers identifying
			  commands in Edit menu}
      cutCommand = 3;
      copyCommand = 4;
      pasteCommand = 5;
      clearCommand = 6;

      findcharsCommand = 1; {menu items for Custom menu}
      findwordCommand = 2;

      aboutMeCommand = 1; {menu item in apple menu for About sample item}

      aboutMeDLOG = 128;
      findDLOG = 129;
      infoDLOG = 130;

      {application dispatching code selectors}
      hilightSel = 0;
      notifySel = 1;

      errCode: INTEGER;
      dlogString: Str255;
      custhandle: Handle;

      {here is the area known to the custom code}
      appdispatch: ProcPtr; 	{address of dispatch routine custom
					 code can call}

	 {examples of further application globals for the custom package}
      paramptr: Ptr; {general pointer used as param. to appdispatch code}
      paramword1: INTEGER;
      paramword2: INTEGER;
      {any other globals the module should get at}

	PROCEDURE CustomInit(resID: INTEGER; VAR custhandle: Handle);
      EXTERNAL; {the routine used to set up the custhandle resource handle}

 	PROCEDURE CustomCall(text: Ptr; count: INTEGER; findstr: StringPtr; 		selector: INTEGER; appaddr: UNIV Ptr; ourhandle: Handle);
      EXTERNAL; {this is the code dispatcher}

 	{this will do the "about" dialog and }
	{the info dialog requested by the custom pack.}

 	PROCEDURE ShowADialog(meDlog: INTEGER);

 	    okButton = 1;
	    authorItem = 2;
 	    languageItem = 3;
 	    infoItem = 2;

 	    itemHit,itemType: INTEGER;
	    itemHdl: Handle;
	    itemRect: Rect;
 	    theDialog: DialogPtr;

	    theDialog := GetNewDialog(meDlog,NIL,WindowPtr( - 1));

 	    CASE meDlog OF
 	       aboutMeDLOG: BEGIN
               SetIText(itemHdl,'Ming The Vaseless');
               SetIText(itemHdl,'Pascal et al');

            infoDLOG: BEGIN {display the message requested by the custom 		                      package}
         END; {CASE}

         UNTIL (itemHit = okButton);

      END; {of ShowADialog}

	{this will put up the Find dialog to allow the user to type in the characters 	 to search for}

         okButton = 1;
         cancelButton = 2;
         fixedItem = 3;
         editItem = 4;

         itemHit,itemType: INTEGER;
         itemHdl: Handle;
         itemRect: Rect;
         theDialog: DialogPtr;

         theDialog := GetNewDialog(findDLOG,NIL,WindowPtr( - 1));

         UNTIL (itemHit IN [okButton,cancelButton]);
         DoCustomDialog := itemHit = okButton;

      END; {of DoCustomDialog}

	PROCEDURE DoCommand(mResult: LONGINT);
	(* partial procedure fragment *)

	{here is one of the case sections for the DoCommand procedure}

               IF DoCustomDialog THEN
                  MoveHHi(Handle(textH)); {stop it from fragmenting heap}
                  WITH textH^^ DO BEGIN
               HLock(hText); 		{ since we don't know what the }							{ package might be up to }

		{now call the package to find characters or words}
	               CustomCall(POINTER(ORD(hText^) + selEnd),
                     teLength - selEnd, @dlogString, theItem, @appdispatch,
                  END; {WITH}

  	    END; {OF menu CASE} {to indicate completion of command,}
         HiliteMenu(0); {call Menu Manager to unhighlight }
         {menu title (highlighted by    }
         {MenuSelect)        }
 	 END; {OF DoCommand}

    	{ this is called by the custom package to set the new selection }
	{ or display a message; it must be in CODE 1 at the outermost }
	{ lexical level}
 	PROCEDURE CustDispatch(selector: INTEGER);

         CASE selector OF
            hilightSel: 		{hilight the characters selected }
					{by the custom pack.}

		{paramptr=pointer to text to select, }
		{ paramword1&paramword2=start,end chars}

               WITH textH^^ DO
               {we'll subtract the start of text from}
		{paramptr to get the base offset...}
                 TESetSelect(ORD(paramptr) - StripAddress (ORD(hText^)) + 		      paramword1, ORD(paramptr) - StripAddress (ORD(hText^)) 		       	      + paramword2,textH);

            notifySel: {put up message per request from custom pack.}
            {paramptr points to string to display}

         END; {CASE}
 	 END; {CustDispatch}

	BEGIN {main program}
      { Initialization }
      InitGraf(@thePort); {initialize QuickDraw}
      InitFonts; {initialize Font Manager}
      FlushEvents(everyEvent - diskMask,0); {call OS Event Mgr to discard
                                           non-disk-inserted events}
      InitWindows; {initialize Window Manager}
      InitMenus; {initialize Menu Manager}
      TEInit; {initialize TextEdit}
      InitDialogs(NIL); {initialize Dialog Manager}
      InitCursor; {call QuickDraw to make cursor (pointer) an arrow}

      errCode := CatchSignal;
      IF errCode <> 0 THEN BEGIN

      SetUpMenus; {set up menus and menu bar}
      UnLoadSeg(@SetUpMenus); {remove the once-only code}

      {Custom package initialization stuff}
      appdispatch := @CustDispatch;
     CustomInit(69,custhandle); 		{should test custhandle for NIL
 						{and alert the user}
      dlogString := '';
	{etc. with the rest of initialization and the main event loop}

	; now for the assembly language code
	; first, the dispatching and initializing code that must be linked
	; into the application

; CustomCalling
; Custom packages initializing and dispatching
;   Rick Blair	May, 1987
;		INCLUDE 	'Traps.a'
;		INCLUDE 	'ToolEqu.a'
;		INCLUDE 	'QuickEqu.a'
;		INCLUDE 'SysEqu.a'

		LOAD	'most.dmp'	; from a dump of the files above

appdata	EQU		12
;Initialize a custom module
; Pascal call format:
;  CustomInit(resID:INTEGER;VAR custhandle:Handle);
; This will load the CUST module with the given resource ID, install a
; handle to it in custhandle, and set the module's appdata pointer to
; point to the address appaddr.
resID		EQU		8
custhandle	EQU		4

		SUBQ.L	#4,A7	;make room for handle from GetResource
		MOVE.L	#'CUST',-(A7)
		MOVE.W	resID+8(A7),-(A7);resource ID
		MOVE.L	(A7)+,A0
		MOVE.L	custhandle(A7),A1
		MOVE.L	A0,(A1)	;store handle in app's custhandle global
;(return with nil handle if GR failed)
		MOVE.L	(A7),A0	;get return address
		ADD.L	#10,A7	;strip everything
		JMP	(A0)	;adieu
;Call a custom module
;Pascal format:
; CustomCall( {parameters as desired} selector: INTEGER; appaddr: Ptr;
;              module: Handle);
;This will call the code whose handle is passed on the stack. If the 
;application was written in assembly language you would just
;dereference the handle and call it directly (you wouldn't need this at
		IMPORT	Signal
		MOVE.L	4(A7),A0	;get handle
		MOVE.L	(A0),D0
		BNE.S	@0	;if hasna' been purged, ga' ahead
		MOVE.L	A0,-(A7)	;push handle
		MOVE.W	ResErr,-(A7)
		JSR	Signal	;Signal is a NOP if a zero is passed to it
		MOVE.L	4(A7),A0	;handle again
; we don't lock the handle here (we can't save it so we can unlock it
;  later), so it's up to the package to lock/unlock itself
@0		MOVE.L	(A0),A0	;dereference
		JMP	(A0)	;call CUST code

; here is the module for the custom package itself

; CustomPack
; Example custom code package
;   Rick Blair	May, 1987
; This demonstrates the recommend structure of a code module which a 
; sophisticated user could add to an existing application which supported
; this mechanism. Aside from allowing for multiple routines within the 
; module (via a selector), provision is made for calling a routine
; dispatcher within the application itself.

;Finding text
;We support a call to find a string anywhere within a block of text
; (selector=0), and one to find the string only as a separate "word"
; with spaces around it (selector=1).
;PROCEDURE CustomCall(text:Ptr; count:INTEGER; findstr:^STRING;
;		        selector:INTEGER; appaddr: UNIV Ptr; ourhandle:Handle);
;Rather than return a result indicating whether they succeeded or not,
;these routines take whatever action is appropriate (the application
;may not even know what these routines actually do).
;Once a call succeeds or fails, it then takes action by making a call to
;one of the services provided by the application. In this case the two
;functions provided are just what we need; the ability to select text and
;the ability to put up a message saying "Text not found".

;		INCLUDE 	'Traps.a'
;		INCLUDE 	'ToolEqu.a'
;		INCLUDE 	'QuickEqu.a'
;		INCLUDE 'SysEqu.a'

		LOAD	'most.dmp'	; from a dump of the files above


		BRA.S	Entry	;skip header
		DC.W	0	;flags
		DC.B	'CUST'	;custom add-on code module
		DC.W	69	;resource ID (picked by Mr. Peabody & 				; Sherman)
		DC.W	$10	;version 1.0

StackFrame	RECORD	{A6Link},DECR
paramsize	EQU	*-8
;	call-specific parameters... (optional)
text		DS.L	1	;pointer to text block
count		DS.W	1	;word count of characters in text
findstr	DS.L	1	;pointer to p-string to find
;	selector(word, optional - you might only have 1 call)
selector	DS.W	1
fcharsCmd	EQU	1	; selector for "find characters"
fwordCmd	EQU	2	; selector for "find word"
;	pointer to app. globals	(long)
appaddr	DS.L	1
;	handle to this resource	(long)
ourhandle	DS.L	1
;	TOS:return address (long)
return		DS.L	1
;the stack link is built off the origin of the saved old A6 on the stack
A6Link		DS.L	1
LocalSize	EQU	*

;offsets into our application globals area
AppGlobals	RECORD	{appdispatch},DECR
appdispatch	DS.L	1
paramptr	DS.L	1
paramword1	DS.W	1
paramword2	DS.W	1
;CUSTerr	DS.W	1	;if we had possible errors
		WITH	StackFrame,AppGlobals
		LINK	A6,#LocalSize
;		MOVEM.L	...	;we'd save any non-trashable regs here
;first lock us down...
		MOVE.L	ourhandle(A6),A0

		MOVE.W	selector(A6),D0
		CMP.W	#fcharsCmd,D0
		BEQ.S	charfind	;go find characters
		CMP.W	#fwordCmd,D0
		BEQ.S	wordfind	;go find a word
;well, M. App didn't call us with a selector we know, so...

;unlock ourselves, clean up, return
; (if we wanted to return an error code we could stuff it into the app.
;  global area)
duhn		MOVE.L	ourhandle(A6),A0
;		MOVEM.L	...	;restore any registers here
		MOVE.L	(A7)+,A0	;return address
		ADD.L	#paramsize,A7;strip parameters
		JMP	(A0)

;selector codes for calls to application
hilight	EQU	0	;highlight characters, please
notify		EQU	1	;beep a little

;find the string "findstr" anywhere in the block "text"
		JSR	findchars		;see if findstr is anywhere in text
		BEQ.S	nofind	;if not then skip
		JSR	calcsels		;compute selstart and selend
didfind	MOVE.L	appaddr(A6),A0	;get pointer to appl. globals area
		MOVE.L	text(A6),paramptr(A0) ;setup text pointer and...
		MOVE.W	D0,paramword1(A0)	;start character position,
		MOVE.W	D1,paramword2(A0)	;end character position
		MOVE.W	#hilight,-(A7)	;pass proper selector
goapp		MOVE.L	appdispatch(A0),A0	;get dispatch address
		JSR	(A0)			;call the application to select the range
		BRA.S	duhn			;return to application (dejà vu)
nofind		MOVE.L	appaddr(A6),A0  	;get pointer to appl. globals area
		LEA	oopstring,A1    	;get pointer to "Not found" message
		MOVE.L	A1,paramptr(A0) 	;put string pointer in "paramptr"
		MOVE.W	#notify,-(A7) 	;tell app. to display message
		BRA.S	goapp
;figure selstart and selend
calcsels	NEG.W	D0	;		negate # characters unskipped in text
		SUBQ.W	#1,D0			;include 1st character
		ADD.W	count(A6),D0		;compute 1st character position for 						; select
		MOVE.L	findstr(A6),A1
		MOVE.B	(A1),D1		;get length of string
		EXT.W	D1
		ADD.W	D0,D1			;compute last char. pos. for select
;find the characters, but only if surrounded by space (including end or
; beg.)
;we could extend the test to check for other delimiters (";",".",etc.)
		JSR	findchars
wloop		BEQ.S	nofind
		MOVE.W	D0,D2			;save count of text remaining
		JSR	calcsels		;figure start and end offsets
		MOVE.L	text(A6),A1		;point to text
		TST.W	D0			;start=beginning of text?
		BEQ.S	@0			;yep, so it passes
		CMP.B	#' ',-1(A1,D0) 	;preceded by a space?
		BNE.S	@1			;nope, keep looking
@0		CMP.W	count(A6),D1 		;D1=length of text?
		BEQ.S	didfind		;yep, so it passes
		CMP.B	#' ',(A1,D1) 		;followed by a space?
		BEQ.S	didfind		;yes, so we've found it
;this wasn't paydirt, so keep panning
@1		MOVE.W	D2,D0			;restore chars remaining count
		BMI.S	nofind			;forget it if we ran out of text
		JSR	bigloop		;keep looking
		BRA.S	wloop			
;this code will find the string if it lies anywhere in the text
findchars	MOVE.L	text(A6),A0		;point A0 to chars to search
		MOVE.W	count(A6),D0		;size of text block
bigloop	MOVE.L	findstr(A6),A1;point A1 to chars to find
		MOVE.W	(A1)+,D1		;get length byte and 1st char. (skip 'em)
		CMP.W	#255,D1
		BGT.S	@1			;enter loop if length<>0
		ADDQ.L	#4,A7			;strip findchar's return address
		BRA	duhn			;return having done nothing
;search for first character
@0		CMP.B	(A0)+,D1		;this one match 1st character?
@1		DBEQ	D0,@0			;branch until found or done 'em all
		BNE.S	cnofind		;skip out if no match on 1st character
		MOVE.B	-2(A1),D1		;length of findstr
		EXT.W	D1
		SUBQ.W	#1,D1			;length sans 1st character
		BEQ.S	cfound			;if Length(findstr)=1, we're done
		CMP.W	D1,D0
		BLT.S	cnofind		;fail if findstr is longer than text left
		MOVE.L	A0,D2			;save this character position
		CMP.W	D1,D1			;force EQuality
		BRA.S	@3			;enter loop
@2		CMP.B	(A0)+,(A1)+		;match so far?
@3		DBNE	D1,@2			;check until mismatch or end of findstr

		MOVEA.L	D2,A0		;restore position (cc's unaffected)
		BNE.S	bigloop		;if no match then keep looking

cfound		MOVEQ	#1,D1	;return TRUE
cnofind		SUB.W	D1,D1	;return FALSE

oopstring	DC.B	'Pattern not found.'


#additions to the resource file

resource 'DLOG' (129, "Find dialog") {
	{72, 64, 164, 428},

resource 'DLOG' (130, "Info") {
	{66, 102, 224, 400},
	dboxproc, visible, nogoaway, 0x0, 130, ""

resource 'DITL' (130) {
/* 1 */ {130, 205, 150, 284},
		button {
			"OK already"
/* 2 */ {8, 32, 120, 296},				/* info */
		statictext {

resource 'DITL' (129) {
	 {	/* array DITLarray: 4 elements */
		/* [1] */
		{64, 48, 84, 121},
		Button {
		/* [2] */
		{64, 231, 84, 304},
		Button {
		/* [3] */
		{8, 8, 24, 352},
		StaticText {
			"Find what?"
		/* [4] */
		{32, 8, 48, 352},
		EditText {

resource 'MENU' (131, "Custom", preload) {
	131, textMenuProc, 0x3, enabled, "Custom",
		"Find Chars...",
			noicon, "F", nomark, plain;
		"Find Word...",
			noicon, "W", nomark, plain

type 'CTST' as 'STR ';

resource 'CTST' (0) {
	"Custom Application - Version 1.0"

include "CustomPack.code";

#  This makefile puts the program together incl. the CUST pack.

CustomTest		[[florin]][[florin]]  CustomCalling.a.o CustomTest.p.o ErrSignal.a.o
# the predefined rule for assembly will build CustomCalling.a.o,
#  CustomPack.code
	Link CustomTest.p.o CustomCalling.a.o ErrSignal.a.o [[partialdiff]]
		"{Libraries}"Interface.o [[partialdiff]]
		"{Libraries}"Runtime.o [[partialdiff]]
		"{PLibraries}"Paslib.o [[partialdiff]]
		-o CustomTest
CustomPack.code	[[florin]]	CustomPack.a.o
	Link CustomPack.a.o -rt CUST=69 -o CustomPack.code
# Put the resource file together (including the custom code resource)
CustomTest		[[florin]][[florin]]	CustomTest.r CustomPack.code
	Rez CustomTest.r -a -o CustomTest

Further Reference:

Previous Technote | Contents | Next Technote