TweetFollow Us on Twitter

XCMD Chat
Volume Number:4
Issue Number:11
Column Tag:HyperChat™

XCMD Cookbook

By Donald Koscheka, Apple Computer, Inc.

on HyperChat

A Nice Chat

While doing the Sunday crossword puzzle recently, I was hit with a very interesting thought. One of the clues in this particular puzzle called for a synonym for “small talk”. The answer was “chat”. This struck me as odd because in many ways HyperTalk is very much the preferred object oriented programming language for the Macintosh. One of the earliest object oriented languages, as you know, is called “SmallTalk”. By calling this column “HyperChat”, Fred makes a rather obscure reference to HyperTalk’s philosophical roots. Chat implies a looseness of speech, a vernacular that is easy to master. That is exactly what HyperTalk is - an easy to grasp interface to the Macintosh Toolbox. What HyperTalk lacks in power, it certainly makes up for in ease of understanding!

At the opposite end of the spectrum is Assembly language programming. This much maligned language conjures all sorts of anxieties in the minds of otherwise fearless programmers. Yet most professional programmers will admit that an understanding of assembly language can improve one’s ability to write efficient code in a higher-level language as well as better understand those mysterious looking dumps that one gets when suddenly presented with a memory dump from TMON or MACSBUG.

Worse yet, those of us who choose to work in higher level languages provide a great disservice to the assembly language programmer by not showing them how to interface with our languages. HyperTalk documentation is certainly sparse in describing how an assembly language programmer can write an XCMD in assembly.

Assembly Interface

I started writing this month’s column hoping to be of service to the assembly language programming community. I wasn’t very far along when I realized that this column offers a second service, at no extra charge to the reader.

The process of showing you how to interface to HyperCard in assembly language also introduces the Pascal and C programmer to debugging in Macsbug or TMON (Forth programmers take heart: Jörg Langkowski’s article in the December, 1987 issue of Mactutor provides you with the information you’ll need to write XCMDs; even if you don’t program in Forth-like languages, you should read Jörg’s column; his insights into the Macintosh are often astonishing).

The most important reason to code in Assembly language is that it provides a rich opportunity to improve on the more generic code generated by Pascal and C compilers. Consider the following string comparison in Pascal:

len: INTEGER;
Match : Boolean;
Str1  : Str255;
Str2  : Str255;

Str1 := ‘Hello World’;
Str2 := ‘GoodBye Cruel World’;


IF Length(Str1) <> Length( Str2 ) THEN 
 match := FALSE
ELSE
BEGIN
 Match := True;  { assume they will match}
 k := 1;

 While (k <= Length( Str1)) AND (match) DO
 IF Str1[k] <> Str2[k] THEN 
 match := False
 ELSE
 k := k + 1;
END;

Listing 1. String Comparisons in Pascal

String compares can be made more efficient than this in Pascal. I chose this example for its simplicity. In comparing strings, we must consider the end points, if the strings are not the same length, they are not equal. If you haven’t been programming in Assembly language, you may not see how this routine could be made more efficient. One measure of a program’s efficiency is a count of the number of bytes of instructions needed to execute the program. If you compile listing 1 and dump the object code, you would discover that the while loop requires 82 bytes of instructions to execute. Assembly language programmers know by instinct that 82 bytes is too much code to perform a single string compare.

An assembly language equivalent of the while loop in listing 1 can be shrunk by an order of magnitude as in listing 2. If you’re trying to speed up a particularly slow loop, a few bytes of well-written assembler might be just what the doctor ordered. But optimizing code is just one reason to familiarize yourself with assembly language. A more compelling reason for the high-level language is that an understanding of assembler will help you make sense of your TMON or MacsBug dumps.

 ; A0, A1 point to the 2 strings
 Move.b (A0)+, D1; get the length of string 1
 Move.b (A1)+, D2; get the length of string 2
 Cmp.b  D1,D2  ; are they the same length?
 Beq  CompareChars ; yes, go ahead and compare them
 Move #0, D0; set the result to false
 Bra  Done; and exit

CompareChars     ; compare Str1<->Str2
 Cmp.b  (A0)+,(A1)+; do the characters match?      
 Beq  Done; yes, see if we’re at end of string
 Dbra D1, CompareChars
 Move #1, D0; they match, set the result true

DONE  sne D0       ; Result is true if strings match,          
 false otherwise

Listing 2. String Compare in Assembler

Entering XCMDs

The real trick to writing an XCMD in assembly language is understanding that HyperCard expects to see an XCMD that was generated by the Pascal compiler. This implies that parameters are pushed on the stack from left to right and that subroutines are responsible for removing the pushed parameters from the stack. XCMDs receive only one parameter so the push order isn’t important. What is important is remembering to remove that parameter from the stack before returning to HyperCard. Listing 3 is the assembly language interface for XCMDs. The fields in the paramBlock record are identical to the Paramblock record in Pascal or C.

On entry to a subroutine in assembly language, the last item on the stack is the return address of the calling routine. Normally, when we are done with the subroutine, an rts (return from subroutine) instruction will pop this return address off the stack and into the Program Counter resuming execution at the instruction pointed to by that location. This won’t do for Pascal routines since convention dictates that we also remove the parameters from the stack. One way to do this would be to pop the return address into a temporary register, say D0, remove the parameters from the stack by adding the size of the parameters to the stack pointer and then pushing the contents of D0 onto the stack and executing an RTS. A more efficient method exists: Pop the return address into an address register, say A0. Unbias the stack parameters by adding 4 to the stack (the size in bytes of the parameter block pointer). Finally, since register A0 contains the return address, execute the Jmp Indirect instruction on A0: Jmp (A0).

Globals in XCMDs

If your XCMD requires local variables, you’re going to need a place to store them. Assembly language XCMDs bear the same restriction placed on high-level languages: you don’t have access to the globals. A simple solution would be to allocate a handle large enough to store all your globals and keep that handle available in an address register. This works fine if the data is very static but not very well otherwise since you could easily run out of registers while manipulating even a small number of handles. Pascal and C use a more efficient approach, one that you’ve already seen if you’ve done any debugging in TMON or Macsbug.

On entry to the subroutine, we know that the stack pointer, register A7, already points to the next available space on the stack (the bottom of the stack). Why don’t we allocate our data on the stack by pointing an address register, say A6, to the bottom of the stack, subtracting the number of bytes that we need for our locals from A7 effectively growing the stack by the amount we need (the stack grows downward). Now A6 points to our local variables and A7 continues its role as stack pointer below our local stack frame (figure 1 ).

The process of creating a stack frame can be performed with one assembly language instruction: link. Used judiciously, the link instruction buys us a whole lot more: it saves the old value of the address register and gives a reference point to the parameters passed by the caller.

By executing link A6,#LocalSize, before doing anything else, we set up up a stack frame at the stack bottom. If stacksize were set to zero, we wouldn’t actually allocate any stack space for globals, but the instruction would still provide a payback. Because nothing else was put on the stack between the call to this routine and our link instruction, A6 also doubles as a pointer to our parameters! First, 0(A6) contains the previous value of A6 (can you think of anything this might be useful for?), next 4(A6) is the return address, and 8(A6) is the paramblock pointer passed to us by HyperCard. By putting 8(A6) into A3, we save the pointer to our parameters in an address register.

The offsets defined in the parameter block equates now become offsets off A3 for each field. The first field in the record is paramCount(A3) the count of the number of parameters in the params array. Accessing the handles in the params array poses another question. The first handle in the array is at params(A3). Getting to the other handles in the params array requires a straightforward application of arithmetic. By definition, handles occupy 4 bytes in the Mac. Any array element, i, is at offset (i-1)*4 byte in the array. We subtract 1 from the element number because array indices count from 0 not from 1. If we put the array index into D0, subtract 1 and multiply by 4 we have the offset from the beginning of the array. All we need to do is add this number to params[A3] and we have the handle. The 68000 has just an instruction: indexed addressing with offset. Here is how this instruction can be used to get the third parameter in the list:

Moveq     #3, D0   ; Access the third parameter in the list 
Sub.w     #1, D0   ; arrays count from 0, not 1
Asl.w     #2, D0   ; shift left by 2 is same as multiply by 4! 
Move.l    params(A3,D0.w), A0 ; A0 now holds the third handle 

Since stack frames are oriented from the highest memory location they occupy to the lowest, local variables are always referred to by negative offsets. In Pascal, the following declaration

VAR
myInt   : INTEGER;
myLong  : LongINt;
myRect  : Rect;

would have the following counterpart in assembly language:

myInt        EQU -4        ; locals start at offset -4 in the frame
myLong  EQU myInt-2; Integers are 2 bytes
myRect      EQU myLong-4  ; longs are 4 bytes
LocalSize EQU myRect-8  ; rectangles are 8 bytes.
LocalSize is equal to 14 bytes.  The stack frame is set up to read:
LINK    A6,#LocalSize; create the local variable pool.
Move.w  (A0),D0

If you’re having a bit of difficulty with this material, try writing a simple XCMD in Pascal or C and disassembling it in TMON or Macsbug. You can do this by invoking the Debugger call as the first statement in you XCMD.

Exiting the XCMD

Leaving the XCMD requires a little house cleaning. First, we restore the registers that were saved onto the stack. Next, we execute an unlink (UNLK) instruction to undo the last Link instruction. At this point, the stack looks just like it did when we entered the XCMD. More importantly (A7) is the return address of the calling routine. Popping this value into A0 allows us to save the return address in a safe place so that we can remove the parameters from the stack. We know how much space the parameters take. The stack contains only one parameter, XCmdBlkPtr, whose length is four bytes. Adding 4 to A7 shrinks the stack to the right size. Now all that’s left is to Jmp to the location pointed to in A0 and we’re done!

Conclusion

If you’re already programming in assembly language, this article is enough to get you started with XCMDs, especially if you’re not familiar with Pascal calling conventions. If you’re a Pascal or C programmer, the above discussion should help you to debug your code by explaining some of the assembly code you may have been looking at in TMON or Macsbug. In any case, understanding how compilers take your statements and convert them into machine executable code is a great way to learn more about the inner-workings of your programs and those seemingly mysterious bugs that just are not obvious in your Pascal or C source code. Hopefully, I’ve been able to fill some gaps in your debugging skills with this information. If the information in this article was useful, please let me know, I’ll be happy to offer more information on assembly language and debugging techniques.


;******************************
;* File: SimpleXCMD.a*
;* *
;* A simple XCMD written in *
;* Assembly language to show*
;* how XCMDs are written in *
;* assembler...  *
;* -------------------------- *
;* By:  Donald Koscheka   *
;* Date:16 July, 1988*
;******************************

;******************************
;* Build Sequence
;*
;* asm -w SimpleXCMD.a
;* link  -rt XCMD=1200 -sn Main=SimpleXCMD
;* SimpleXCMD.a.o
;* -o “YourStackName”
;******************************

;***  ParamBlock structure***
paramCountEQU    0   
params  EQU paramCount+2
returnValue EQU  params+( 16 * 4 )     
passFlagEQU returnValue + 4 
entryPointEQU    passFlag + 2   
request EQU entryPoint + 4  
result  EQU request + 2
inArgs  EQU result + 2
outArgs EQU inArgs + ( 8 * 4 )
pBlkSizeEQU outArgs + (4 * 4 )

;*** ------------------ ***
;*** THE LOCAL VARIABLES  ***
;*** (WILL GO ON STACK)   ***
;*** Note that the stack frame***
;*** counts backwards from 0***
;*** so that the value of ***
;*** LocalSiz will always be  ***
;*** negative    ***

LOCALS  EQU 0
LASTLOCAL EQU    LOCALS
LOCALSIZEQU LASTLOCAL
;*** ------------------ ***


SimpleXCMDMAIN   EXPORT
;******************************
;* In:
;*
;* 0(A7) == Return Address
;* 4(A7) == ParamBlockPtr
;* 
;* Link A6 to create a stackframe
;* that points to these vars.
;******************************

 ;*** Set Up Stack Frame
 LINK   A6,#LOCALSIZ ; Size of the local frame
 MOVEM.LD5-D7/A3/A4,-(SP) ; save some registers
 
 ;*** Get Pointer to paramblock
 MOVE.L 8(A6), A3; Point to parameters
 CLR.L  returnValue(A3) ; set to “empty”
 TST.W  paramCount(A3)  ; Any Parameters?
 BEQ    DONE; no, just return
 
   ;*** Insert your code here.  If your XCMD doesn’t take any 
 ;*** parameters eliminate the atest on paramcount ...
 
DONE    ;*** Prepare for Return to HyperCard
 MOVEM.L(SP)+,D5-D7/A3/A4 ; restore registers
 UNLK   A6; wipe out stack frame
 MOVE.L (A7)+, A0; get the return address
 ADD.L  #4, A7   ; unbias the stack
 JMP    (A0); return to HyperCard
 END

Listing 3. SimpleXCMD in Assembly Language

end HyperChat
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Adobe InCopy CC 2018 13.0.1.207 - Create...
InCopy CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous InCopy customer). Adobe InCopy CC 2018, ideal for large team projects... Read more
Microsoft Office 2016 15.40 - Popular pr...
Microsoft Office 2016 - Unmistakably Office, designed for Mac. The new versions of Word, Excel, PowerPoint, Outlook and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more
Adobe InDesign CC 2018 13.0.1.207 - Prof...
InDesign CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous InDesign customer). Adobe InDesign CC 2018 is part of Creative Cloud.... Read more
Apple iOS 11.1.2 - The latest version of...
iOS 11 sets a new standard for what is already the world’s most advanced mobile operating system. It makes iPhone better than before. It makes iPad more capable than ever. And now it opens up both to... Read more
Slack 2.9.0 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.9.0: Slack now officially, and fully, supports Japanese.... Read more
iExplorer 4.1.9 - View and transfer file...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
PCalc 4.5.3 - Full-featured scientific c...
PCalc is a full-featured, scriptable scientific calculator with support for hexadecimal, octal, and binary calculations, as well as an RPN mode, programmable functions, and an extensive set of unit... Read more
iExplorer 4.1.9 - View and transfer file...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
PCalc 4.5.3 - Full-featured scientific c...
PCalc is a full-featured, scriptable scientific calculator with support for hexadecimal, octal, and binary calculations, as well as an RPN mode, programmable functions, and an extensive set of unit... Read more
Slack 2.9.0 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.9.0: Slack now officially, and fully, supports Japanese.... Read more

Latest Forum Discussions

See All

Rules of Survival guide - how to be the...
The PUBG craze makes its way to mobile, with more and more battle royale games debuting on iOS and Android. Rules of Survival joins the ranks of mobile PUBG-likes, offering a classic battle royale experiences that doesn't vary too much from its... | Read more »
The best new games we played this week -...
The weekend is upon us friends, and it's time to take a look back and reflect on all of the wonderful games we've played over the past few days. This week was jam packed with new releases. There were some big, long awaited launches, some fun... | Read more »
Lineage II: Revolution guide - tips and...
At long last, Lineage II: Revolution has now come to western shores, bring Netmarble's sweeping MMORPG to mobile devices. It's an addictive, epic experience, but some of the systems in the game can be a bit overwhelming. Here are a few tips to help... | Read more »
A Boy and His Blob (Games)
A Boy and His Blob 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
Fight terrible monsters and collect epic...
Released on Western markets early last month, Dragon Project, created by Japanese developer COLOPL, brings epic monster hunting action to mobile for the very first time. Collect a huge array of weapons and armor, and join up with friends to fight... | Read more »
I Am The Hero (Games)
I Am The Hero 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: I Am The Hero is a pixel art, beat 'em up, fighting game that tells the story of a "Hero" with a glorious but mysterious past.... | Read more »
Kauldron (Music)
Kauldron 1.0 Device: iOS Universal Category: Music Price: $3.99, Version: 1.0 (iTunes) Description: Kauldron is our warmest sounding, punchiest synth yet! A completely new modeling technology, combined with carefully designed... | Read more »
Lineage II: Revolution is mobile’s bigge...
NCSoft’s hit fantasy MMORPG series has just made the leap to mobile with the help of Netmarble in Lineage II: Revolution. With over 1.5 million players having already pre-registered ahead of the game’s launch, Revolution hit the app stores... | Read more »
Swing skilfully in new physics-based pla...
Sometimes it’s the most difficult of obstacles that can be the most rewarding. One game hoping to prove this is OCMO, the new tough but fair platformer from developers Team Ocmo. Primed to set every speedrunner’s pulse racing, as an otherworldly... | Read more »
RPGolf (Games)
RPGolf 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Once upon a time, the kingdom was a land of peace, harmony, and an all-consuming passion for the greatest sport - GOLF. Everyone in the... | Read more »

Price Scanner via MacPrices.net

Early Black Friday sale: Apple iMacs for up t...
B&H Photo has 27-inch iMacs in stock and on sale for up $130-$150 off MSRP including free shipping. B&H charges sales tax in NY & NJ only: – 27″ 3.8GHz iMac (MNED2LL/A): $2149 $150 off... Read more
Apple restocks refurbished Mac minis starting...
Apple has restocked Certified Refurbished Mac minis starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: – 1.4GHz Mac mini: $419 $80 off MSRP – 2.6GHz Mac... Read more
Save on 12″ MacBooks, Apple refurbished model...
Apple has Certified Refurbished 2017 12″ Retina MacBooks available for $200-$240 off the cost of new models. Apple will include a standard one-year warranty with each MacBook, and shipping is free.... Read more
Early Holiday sale: 12″ iPad Pros for up to $...
B&H Photo has 12″ iPad Pros on sale today for up to $130 off MSRP. Shipping is free, and B&H collects no sales tax outside NY & NJ: – 12″ 64GB WiFi iPad Pro: $749, save $50 – 12″ 256GB... Read more
Holiday sale prices on Apple 13″ MacBook Pros...
B&H Photo has 2017 13″ MacBook Pros in stock today and on sale for $100-$150 off MSRP, each including free shipping plus NY & NJ sales tax only: – 13-inch 2.3GHz/128GB Space Gray MacBook Pro... Read more
Sale: 13″ MacBook Airs starting at $899, $100...
B&H Photo has 2017 13″ MacBook Airs on sale today for $100 off MSRP including free shipping. B&H charges NY & NJ sales tax only: – 13″ 1.8GHz/128GB MacBook Air (MQD32LL/A): $899, $100 off... Read more
Week’s Best Deal on 13″ MacBook Pros: Apple r...
Apple has a full line of Apple Certified Refurbished 2017 13″ MacBook Pros available for $200-$300 off MSRP. A standard Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
Deal: 15″ 2.6GHz MacBook Pro for $1799 w/free...
B&H Photo has clearance 2016 15″ 2.6GHz Touch Bar MacBook Pros in stock today and available for $600 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 15″ 2.... Read more
Black Friday pricing on the 1.4GHz Mac mini....
MacMall has the 1.4GHz Mac mini on sale for $399 including free shipping. Their price is $100 off MSRP (20% off), and it’s the lowest price for available for this model from any reseller. MacMall’s... Read more
Early Black Friday deal: 15″ Apple MacBook Pr...
B&H Photo has 15″ MacBook Pros on sale for up to $200 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 15″ 2.8GHz MacBook Pro Space Gray (MPTR2LL/A): $2199, $200... Read more

Jobs Board

Product Manager - *Apple* Pay on the *Appl...
Job Summary Apple is looking for a talented product manager to drive the expansion of Apple Pay on the Apple Online Store. This position includes a unique Read more
*Apple* Pro/Consumer Apps Support Engineer -...
…exemplify AppleCare's expert technical support paired with exceptional customer service for Apple 's software apps. This person is a problem solver, who understands Read more
Partner Marketing Manager, *Apple* Pay - Ap...
Job Summary The Apple Pay partner marketing team is looking for a Marketing Manager to develop and drive US programs. The right candidate will be passionate about Read more
*Apple* Solution Consultant - Apple (United...
# Apple Solution Consultant - Rochester, MN Job Number: 113037950 Rochester, MN, Minnesota, United States Posted: 19-Sep-2017 Weekly Hours: 40.00 **Job Summary** Are Read more
Sr. Experience Producer, Today at *Apple* -...
# Sr. Experience Producer, Today at Apple Job Number: 56495251 Santa Clara Valley, California, United States Posted: 23-Jun-2017 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.