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

Skype 7.5.0.738 - Voice-over-internet ph...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more
PushPal 3.0 - Mirror Android notificatio...
PushPal is a client for Pushbullet, which automatically shows you all of your phone's notifications right on your computer. This means you can see who's calling or read text messages even if your... Read more
Logic Pro X 10.1.1 - Music creation and...
Apple Logic Pro X is the most advanced version of Logic ever. Sophisticated new tools for professional songwriting, editing, and mixing are built around a modern interface that's designed to get... Read more
VLC Media Player 2.2.0 - Popular multime...
VLC Media Player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, MP3, OGG, ...) as well as DVDs, VCDs, and various streaming protocols. It... Read more
Sound Studio 4.7.8 - Robust audio record...
Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more
LibreOffice 4.4.1.2 - Free, open-source...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
VueScan 9.5.03 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Freeway Pro 7.0.3 - Drag-and-drop Web de...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With its user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
Cloud 3.3.0 - File sharing from your men...
Cloud is simple file sharing for the Mac. Drag a file from your Mac to the CloudApp icon in the menubar and we take care of the rest. A link to the file will automatically be copied to your clipboard... Read more
Cyberduck 4.6.5 - FTP and SFTP browser....
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more

Get The Whole Story – Lone Wolf Complete...
Get The Whole Story – Lone Wolf Complete is Now Available and On Sale Posted by Jessica Fisher on February 27th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Who Wore it Best? The Counting Dead vs....
Like it or not, the “clicker” genre, popularized by cute distractions like Candy Box and Cookie Clicker, seems like it’s here to stay. So Who Wore it Best? takes a look at two recent examples: The Counting Dead and AdVenture Capitalist. | Read more »
Card Crawl, the Mini Deck Building Game,...
Card Crawl, the Mini Deck Building Game, is Coming Soon Posted by Jessica Fisher on February 27th, 2015 [ permalink ] Tinytouchtales and Mexer have announced their new game, | Read more »
Witness an all new puzzle mechanic in Bl...
Well, BlastBall MAX is not one of those games and is bucking trends such as timers, elements of randomness, and tacked-on mechanics in favor of pure puzzle gameplay. When you first boot up the game you’ll see a grid made up of squares that are each... | Read more »
This Princess Has a Dragon and She isn’t...
This Princess Has a Dragon and She isn’t Afraid to Useit. | Read more »
Mecha Showdown Review
Mecha Showdown Review By Lee Hamlet on February 27th, 2015 Our Rating: :: IN A SPINUniversal App - Designed for iPhone and iPad Mecha Showdown replaces traditional buttons with a slot machine mechanic in this robot fighting game,... | Read more »
Reliance Games and Dreamworks Unveil Rea...
Reliance Games and Dreamworks Unveil Real Steel Champions Posted by Ellis Spice on February 27th, 2015 [ permalink ] Reliance Games and Dreamworks have announced that a third game in | Read more »
Sum Idea Review
Sum Idea Review By Jennifer Allen on February 27th, 2015 Our Rating: :: TAXING NUMBERSUniversal App - Designed for iPhone and iPad Sum Idea is a fairly charming but taxing puzzle game.   | Read more »
A New Badland Update Brings Daydream Lev...
A New Badland Update Brings Daydream Levels to Co-Op Posted by Ellis Spice on February 27th, 2015 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Slashing Demons Review
Slashing Demons Review By Lee Hamlet on February 27th, 2015 Our Rating: :: IT'S A LONG WAY TO THE TOPUniversal App - Designed for iPhone and iPad Slashing Demons lacks the depth or scope to take it beyond the point of being just... | Read more »

Price Scanner via MacPrices.net

Apple Launches Free Web-Based Pages and Other...
Apple’s new Web-only access to iWork productivity apps is a free level of iCloud service available to anyone, including people who don’t own or use Apple devices. The service includes access to Apple... Read more
Survey Reveals Solid State Disk (SSD) Technol...
In a recent SSD technology use survey, Kroll Ontrack, a firm specializing in data recovery, found that while nearly 90 percent of respondents leverage the performance and reliability benefits of SSD... Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store is offering Apple Certified Refurbished Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Updated Mac Price Trackers
We’ve updated our Mac Price Trackers with the latest information on prices, bundles, and availability on systems from Apple’s authorized internet/catalog resellers: - 15″ MacBook Pros - 13″ MacBook... Read more
Apple CEO Tim Cook to Deliver 2015 George Was...
Apple CEO Tim Cook will deliver the George Washington University’s Commencement address to GWU grads on May 17, at which time he will also be awarded an honorary doctorate of public service from the... Read more
Apple restocks refurbished Mac minis for up t...
The Apple Store has restocked Apple Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz... Read more
Save up to $50 on iPad Air 2s, NY tax only, f...
 B&H Photo has iPad Air 2s on sale for $50 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $469.99 $30 off - 64GB iPad Air 2 WiFi: $549 $50 off - 128GB iPad Air 2... Read more
16GB iPad Air 2 on sale for $447, save $52
Walmart has the 16GB iPad Air 2 WiFi on sale for $446.99 on their online store for a limited time. Choose free shipping or free local store pickup (if available). Sale price for online orders only,... Read more
iMacs on sale for up to $205 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1029 $70 off - 21″ 2.7GHz iMac: $1199 $100 off - 21″ 2.9GHz... Read more
Apple Takes 89 Percent Share of Global Smartp...
According to the latest research from Strategy Analytics, global smartphone operating profit reached US$21 billion in Q4 2014. The Android operating system captured a record-low 11 percent global... Read more

Jobs Board

Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional Read more
Event Director, *Apple* Retail Marketing -...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global engagement strategy and team. Delivering an overarching brand Read more
*Apple* Pay - Site Reliability Engineer - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.