TweetFollow Us on Twitter

XCMD Corner
Volume Number:4
Issue Number:7
Column Tag:HyperChat®

XCMD Corner

By Donald Koscheka, Apple Computers, Inc.

--Don Koscheka’s XCMD Corner

Last month I introduced XCMD programming. I explained the parameter block and discussed the interface between HyperTalk and the code that you write in either Pascal, “C” or the language of your choice. If you’re an experienced Macintosh programmer, that’s enough information to get started. The designers of HyperCard didn’t stop with just defining the interface for you. They went beyond what might be reasonably expected and provided some HyperTalk programming capabilities to the XCMD programmer. The XCMD programmer gains access to these capabilities through callbacks. Callbacks are procedures and functions that you call from your XCMD. Callbacks literally jump into Hypercard to perform some function.

Once you get the hang of XCMD programming, you’ll come to rely on some of the callbacks quite frequently. For example, Pascal programmers are accustomed to strings that are preceded by a length byte and that have a maximum of 255 characters (the Str255 type in Pascal) while HyperCard uses strings that have no length byte and are terminated with zero ( referred to as Zero-strings, zero-terminated strings or “C” strings). HyperTalk provides callbacks to convert from zero-terminated strings to Pascal and back again. The XCMD programmer can also use callbacks to retrieve and set the contents of fields and global containers as well as to send messages back to Hypercard.

One of the reasons that this access to HyperCard containers is so important is that XCMDs do not have access to the application globals. When Hypercard starts up, it takes control of its application globals and heap just as any application would. With Hypercard in control of the heap, your XCMD becomes a “guest” of Hypercard. You don’t have access to the globals from your XCMD so you’ll need a safe place to store information that you want to keep around.

A good candidate is a global container. Although Hypercard itself prefers to see text strings in containers, it’s not particular about what you put into a container; you can use the SetGlobal callback to put data into a global container, and GetGlobal to retrieve that data. Make sure that you declare any global containers in Hypercard before accessing them in an XCMD. Your XCMD may need to be backward compatible earlier versions of Hypercard that bombed if you called SetGlobal with an undeclared container name.

An interesting example of the use of callbacks is to send a card message back to HyperCard from a callback. The XCMD in listing 1, “SendMeAMessage”, takes one parameter which is the message to send back to HyperCard. Since messages are sent back as Pascal-format strings, we must convert the input string into a pascal string and then call SendCardMessage to send the message. As a matter of form, we set the return value to NIL indicating that this XCMD doesn’t have a result code (Hypercard will interpret NIL as empty).

The first callback that SendMeAMessage invokes, ZeroToPas, converts input parameter 1 from a zero-terminated string to a pascal-string. Input parameters are passed as handles so the parameter needs to be dereferenced one-time to convert the value to a pointer. ZeroToPas also expects you to pass a reference to the pascal-string into which you’ll store the converted Pascal-string. The second callback, SendCardMessage, sends the message back to Hypercard. To invoke this XCMD from a script use the form:

 SendMeAMessage “go next card”

Because Hypercard already handles message passing, this XCMD may not seem terribly useful. Nonetheless, it is a good illustration of callbacks and the technique is useful if you need to alert the user that some asynchronous event has completed.

{1}
{******************************}
{* File: SendMeAMessage.p *}
{******************************}
(******************************
 BUILD SEQUENCE
      (IGNORE LINK WARNINGS)
pascal SendMeAMessage.p
link -m ENTRYPOINT -rt XCMD=65534 
 -sn Main=SendMeAMessage 
 SendMeAMessage.p.o 
 “{Libraries}”Interface.o 
 “{PLibraries}”Paslib.o 
 -o “{xcmds}”testxcmds
******************************)

{$S SendMeAMessage }

UNIT Donald_Koscheka; 

{--------------INTERFACE----------------}
INTERFACE

USES  MemTypes, QuickDraw, OSIntf, ToolIntf, 
 PackIntf, HyperXCmd;

PROCEDURE EntryPoint( paramPtr: XCmdPtr);

{----------IMPLEMENTATION--------------}
IMPLEMENTATION
{$R-}
 
TYPE
 Str31  = String[31];
 
PROCEDURE SendMeAMessage(paramPtr:XCmdPtr);
 FORWARD;

{-------------- EntryPoint --------------}
PROCEDURE EntryPoint(paramPtr: XCmdPtr);
 BEGIN
 SendMeAMessage(paramPtr);
 END;

{------------ SendMeAMessage ------------}
PROCEDURE SendMeAMessage(paramPtr: XCmdPtr);
VAR
 theMessage : Str255;
 
{$I XCmdGlue.inc }
 
BEGIN {*** Body of XCMD ***}
 ZeroToPas( paramPtr^.params[1]^, theMessage );
 SendCardMessage( theMessage );
 paramPtr^.returnValue := NIL;
END; {*** Body of XCMD ***}
END.

Listing 1. SendACardMessage

XCMDs can also use callbacks to get the contents of a field or a global container. Listing 2, GetHomeInfo, uses two new callbacks (1) GetFieldByNum, to get the contents of background field 1 on the home card and (2) SetGlobal to set the contents of some global container.

GetHomeInfo Takes one parameter, the name of the global container to set. First, convert the parameter to a pascal-string. Next, use a series of callbacks to push the current card and go to the home stack. Once we get to the home stack, we call GetFieldByNum to get field data. The first parameter that GetFieldByNum takes is set to TRUE if you want to retrieve the contents of a card field and set to FALSE to retrieve the contents of a background field. The second parameter is the number of the field to retrieve. Alternatively, you could use GetFieldByID if you knew the id of the field or GetFieldByName if you knew the name.

GetFieldByNum returns a handle to the zero-terminated data that was stored in background field 1 of the home card. We then invoke SetGlobal to set the contents of the global container to whatever is stored in fieldData. Finally, we pop the current card to get back to where we started. A typical invocation of this XCMD is:


{2}
 global myData
 GetHomeInfo “myData”



PROCEDURE GetHomeInfo(paramPtr: XCmdPtr);
VAR
 globalName : Str255;
 fieldData: Handle;
 
{$I XCmdGlue.inc }
 
BEGIN
 WITH paramPtr^ DO
 BEGIN
 ZeroToPas( params[1]^, globalName );
 SendCardMessage( ‘Push Card’ );
 SendCardMessage( ‘Go Home’);
 
 fieldData := GetFieldByNum( FALSE, 1 );
 SetGlobal( globalName, fieldData );
 
 SendCardMessage( ‘Pop Card’);
 returnValue := NIL;
 END;
END;

Listing 2. Get Home Info.

So far I’ve showed you XCMDs that don’t do anything that you can’t already do in HyperTalk. A key feature of XCMD programming is that you can write your own commands to augment or add capabilities to Hypercard. Listing 3, “FCreateXFCN”, lets you create a file of any type from HyperCard. This XFCN demonstrates how XCMDs provide greater access to the toolbox than is available to the HyperTalk script writer.

FCreateXFCN introduces two new callbacks. NumToStr returns a result code to the script. NumToStr converts a signed long integer to a pascal-format string. If you don’t want a signed entity, use LongToStr instead which will convert the long integer without regard to sign.

The second callback introduced in this XFCN is PasToZero which takes a pascal format string and returns handle to a zero-terminated string. PasToZero is a handy way of copying from a pascal-string back to a zero-terminated string to return text to Hypercard.

I wrote the XFCN in “C” to show the difference in formats between Pascal and “C” XCMDS and to provide a template for “C” programmers. An important difference is that the parameter list, params, starts at index 0 for “C” and index 1 for Pascal.

FCreateXFCN first converts parameter 1 (params[0]) into a pascal-string and then moves the first four bytes of parameters 2 and 3 into the variables creator and type respectively. These two variables are of type OSType which is a special Macintosh type containing four consecutive ASCII characters. All four characters in this type are significant.

The result code will be empty if no error occurred and the file was created properly, otherwise it will return the OSErr number that occurred. First, convert the result code back to a pascal-string and then call PasToZero to convert that string into a handle to a zero-terminated string.

The XFCN would be more useful if it returned a brief description of the error in English, but I think I’ll leave that as an exercise for the student. Call FCreateXFCN with the following script:

Put FCreateXFCN( “New File Name”, “WILD”,  “STAK” )

The first parameter is the name of the file you wish to create, the second parameter is the creator and the last parameter is the file type. The foregoing invocation will create an empty stack. What can you do with that?

{3}
/*****************************\
*file: FCreateXFCN.c *
\*****************************/

/*****************************
 BUILD SEQUENCE
 
C -q2 -g FCreateXFCN.c
link  -sn Main=FCreateXFCN 
 -sn STDIO=FCreateXFCN 
  -sn INTENV=FCreateXFCN 
  -rt XFCN=300 
  -m FCREATEXFCN 
  FCreateXFCN.c.o 
  “{CLibraries}”CInterface.o 
  -o testXCMDs
 
*****************************/
#include<Types.h>
#include<OSUtils.h>
#include<Memory.h>
#include<Files.h>
#include<Resources.h>
#include  “HyperXCmd.h”

pascal void FCreateXFCN( paramPtr )
 XCmdBlockPtr  paramPtr;
/****************************
* In:   Paramblock:
*param[0] == filename
*param[1] == TYPE
*param[2] == CREATOR
* Out:  result code in returnValue
****************************/
{
char    *fname;
OSType  type, creator;
Str31 str;
char    vName[33];
short   error, vRefnum;

/** coerce the volume reference  ***
***number from the system **/
GetVol( vName, &vRefnum );
 
/**extract the filename from  ***
***the parameter list     **/
fname   = *(paramPtr->params[0]);
BlockMove(*(paramPtr->params[1]),&creator,4 );
BlockMove(*(paramPtr->params[2]),&type,4 );
 
error = Create( fname, vRefnum, 
 creator, type );
 
FlushVol( 0L, vRefnum );
 
if( !error )
 paramPtr->returnValue = 0L;
else{
 NumToStr( paramPtr, (long)error, &str );
 paramPtr->returnValue = 
 PasToZero( paramPtr, &str );
 }
}

#include <XCmdGlue.inc.c>

Listing 3. FCreateXFCN

Although this article covered some of the more frequently used callbacks, my objective was to present you with the spirit of the callback mechanism. You should have no trouble using any of the callbacks that are currently defined in the HyperCard Developer’s ToolKit (available from APDA). The most important lesson here is that before you go off and write an XCMD, check the callback list to see how you might incorporate them into your XCMDs. Try to get the callbacks to do as much work as possible for you so that you can concentrate on the code that you are trying to write.

Next Month: SortList, an XCMD that sorts a field by line.

end HyperChat
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Dragon Dictate 6.0 - Premium voice-recog...
With Dragon Dictate speech recognition software, you can use your voice to create and edit text or interact with your favorite Mac applications. Far more than just speech-to-text, Dragon Dictate lets... Read more
OmniFocus 3.11.7 - GTD task manager with...
OmniFocus is an organizer app. It uses projects to organize tasks naturally, and then add tags to organize across projects. Easily enter tasks when you’re on the go, and process them when you have... Read more
rekordbox 6.5.1.0009 - Professional DJ m...
rekordbox is the best way of preparing and managing your tracks, be it at home, in the studio, or even on the plane! It allows you to import music from other music-management software using the... Read more
1Password 7.8.1 - Powerful password mana...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
Ableton Live 10.1.35 - Record music usin...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
Microsoft Office 365, 2019 16.48 - Popul...
Microsoft Office 365. The essentials to get it all done. Unmistakably Office, designed for Mac Get started quickly with new, modern versions of Word, Excel, PowerPoint, Outlook and OneNote-... Read more
Adobe After Effects 18.1 - Create profes...
After Effects is available as part of Adobe Creative Cloud for $52.99/month (or $20.99/month for a single app license). The new, more connected After Effects can make the impossible possible. Get... Read more
Adobe Audition 14.1 - Professional post-...
Audition is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Audition customer). Adobe Audition empowers you to create and deliver... Read more
Adobe Animate 21.0.5 - Animation authori...
Animate is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Flash Professional customer). Animate (was Flash CC) lets you share work... Read more
Adobe Photoshop 22.3.1 - Professional im...
You can download Photoshop for Mac as a part of Creative Cloud for only $20.99/month (or $9.99/month if you have purchased an earlier software version). Adobe Photoshop is a recognized classic of... Read more

Latest Forum Discussions

See All

Moonlight Sculptor is an upcoming MMORPG...
Kakao Games and XL Games – who you might be familiar with from their previous game ArcheAge – have announced that their MMORPG Moonlight Sculptor is now available to pre-order for iOS and Android devices. Moonlight Sculptor has previously launched... | Read more »
MU Archangel is now open for pre-registr...
MU Archangel is now open for pre-registration in Southeast Asia following its massive success in other territories. Players from Singapore, Thailand, Malaysia, Indonesia, and the Philippines (except Vietnam) can now join in on the fun by applying... | Read more »
Compete, a new social media app you can...
Whoever told you you can’t get rich making videos has obviously never heard of Compete, Competitive Media Technologies Limited’s hot new social media app where you can rake in all the dough just by doing what you love. Video monetization that... | Read more »
Bethesda has released a new DOOM mobile...
Bethesda Softworks has released a new DOOM game out of the blue exclusively for mobile devices. It’s called Mighty DOOM and is currently only available as an early access title on Android but will be expanding to more users in the future. [Read... | Read more »
Anagraphs is a word puzzle game with a t...
Cinq-Mars Media has released its word puzzle game Anagraphs for iOS and Android devices. The game released last week after a short delay in getting it onto the appropriate platforms. [Read more] | Read more »
These are the top 5 best iPhone games li...
Fortnite has been the big hitter in mobile gaming this year, and it's not hard to see why. Thanks to some excellent marketing, and a polished experience that almost anyone can enjoy, it's really taken the App Store by storm. But there are other... | Read more »
The top 5 best iPhone games like Pokemon...
Pokemon GO is still the, if you'll excuse the pun, go-to game if you want some AR action on your phone. But it's not the only choice out there, and if you've got a hankering for something a bit different, then your eyes might already have started... | Read more »
The top 5 best iPhone games like Starcra...
Starcraft sits at the top of the RTS tree for a number of very good reasons. It also isn't on mobile, again, for a number of very good reasons. But that doesn't mean you can't find a way to indulge your sci-fi, competitive, massive, or engaging RTS... | Read more »
Apple Arcade: Ranked - Top 25 [Updated 4...
In case you missed it, I am on a quest to rank every Apple Arcade game there is. [Read more] | Read more »
The top 5 best iPhone games like The Roo...
The Room has had a massive impact on the world of mobile gaming. Not only is it a brilliant adventure, it also shows how the touchscreen controls on your iPhone can be turned into something far more elegant and tactile than just a bunch of buttons... | Read more »

Price Scanner via MacPrices.net

B&H is offering clearance prices on lefto...
Apple reseller B&H Photo has clearance 2020 13″ 1.4GHz Intel-based MacBook Pros on sale today for $200-$300 off Apple’s original MSRP with prices starting at only $1099. Expedited shipping is... Read more
Roundup of Today’s Best MacBook Deals: M1 Mac...
Apple resellers are offering sale prices on Apple’s M1-powered 13″ MacBook Airs ranging up to $190 off MSRP. Here’s where to pick one up today, and as always, keep an eye on our 13″ MacBook Air Price... Read more
Apple AirPods Pro drop to new low price of on...
Amazon has Apple’s AirPods Pro on sale today for a new low price of only $197 shipped. That’s $52 off MSRP and the lowest price currently available for a set of AirPods Pro from any Apple reseller.... Read more
Apple restocks clearance 13″ Intel-based MacB...
Apple has clearance, Certified Refurbished, 2020 13″ Intel-based MacBook Airs available starting at only $809 and up to $280 off original MSRP. Each MacBook features a new outer case, comes with a... Read more
OWC drops prices on 2020 Intel multi-core Mac...
Other World Computing has clearance 2020 Intel-based Mac minis on sale starting at only $499. Both 4-core and 6-core models are in stock today. These are new, unopened, factory-sealed minis: – 3.6GHz... Read more
Save $50 off Apple’s 10.9″ iPad Air today at...
B&H Photo has new 10.9″ Apple iPad Airs in stock and on sale today for up to $50 off MSRP. Expedited shipping is free to most addresses in the US. Note that some sale prices may be restricted to... Read more
Rare Apple sale: Get a HomePod mini for $10 o...
Apple reseller Expercom has the Space Gray HomePod mini on sale today for $89 shipped. Their price is $10 off Apple’s MSRP, and it’s currently the only sale price available for a HomePod mini among... Read more
Apple has M1 Mac minis available starting at...
Apple has a full line of standard configuration M1 Mac minis available in their Certified Refurbished section starting at only $589 and up to $140 off MSRP. Each mini comes with Apple’s one-year... Read more
New sale at Amazon: $55-$70 discounts on Appl...
Amazon has 7.9″ iPad minis on sale today for up to $70 off Apple’s MSRP, each including free shipping. Prices start at $344. These are the same iPad minis sold by Apple in their retail and online... Read more
Apple offering 13″ M1 MacBook Airs for as lit...
Apple has a full line of 2020 13″ M1 MacBook Airs available, Certified Refurbished, starting at only $849 and up to $190 off original MSRP. These are the cheapest M1 MacBook Airs for sale today at... Read more

Jobs Board

*Apple* Valley 20hr Teller - Wells Fargo (Un...
…or scheduled + Ability to stand for extended periods of time **Street Address** **MN- Apple Valley:** 14325 Cedar Ave - Apple Valley, MN **Disclaimer** All offers Read more
*Apple* Valley 20hr Teller - Wells Fargo (Un...
…or scheduled + Ability to stand for extended periods of time **Street Address** **MN- Apple Valley:** 14325 Cedar Ave - Apple Valley, MN **Disclaimer** All offers Read more
Desktop Support Technician - *Apple* / Mac...
…infrastructure and internal desktop systems. Must have an IT background that includes Apple / Mac support. **Overview:** + Responds to routine technical questions or Read more
Geek Squad *Apple* Consultation Professiona...
**801042BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store Number or Department:** 000214-Willowbrook-Store Read more
*Apple* Mobility Specialist - Best Buy (Unit...
**800879BR** **Job Title:** Apple Mobility Specialist **Job Category:** Store Associates **Store Number or Department:** 000803-Lansing-Store **Job Description:** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.