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

Spotify 1.0.36.124. - Stream music, crea...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
Firefox 48.0.2 - Fast, safe Web browser.
Firefox offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals and casual... Read more
BBEdit 11.6.1 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
OmniGraffle Pro 6.6.1 - Create diagrams,...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more
OmniGraffle 6.6.1 - Create diagrams, flo...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more
Dropbox 8.4.21 - Cloud backup and synchr...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keep them up-to-date between systems... Read more
BetterTouchTool 1.84 - Customize Multi-T...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
ScreenFlow 6.1 - Create screen recording...
ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your entire monitor while also capturing your video camera, microphone and your... Read more
f.lux 37.7 - Adjusts the color of your d...
f.lux makes the color of your computer's display adapt to the time of day, warm at night and like sunlight during the day. Ever notice how people texting at night have that eerie blue glow? Or wake... Read more
BetterTouchTool 1.84 - Customize Multi-T...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more

Become the King of Avalon in FunPlus’ la...
King Arthur is dead. Considering the legend dates back to the 5th century, it would be surprising if he wasn’t. But in the context of real-time MMO game King of Avalon: Dragon Warfare, Arthur’s death plunges the kingdom into chaos. Evil sorceress... | Read more »
Nightgate (Games)
Nightgate 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: *** Launch Sale: 25% OFF for a limited time! *** In the year 2398, after a great war, a network of intelligent computers known as... | Read more »
3 best fantasy football apps to get you...
Last season didn't go the way you wanted it to in fantasy football. You were super happy following your drafts or auctions, convinced you had outsmarted everyone. You were all set to hustle on the waiver wire, work out some sweet trades, and make... | Read more »
Pokemon GO update: Take me to your leade...
The Team Leaders in Pokemon GO have had it pretty easy up until now. They show up when players reach level 5, make their cases for joining their respective teams, and that's pretty much it. Light work, as Floyd Mayweather might say. [Read more] | Read more »
Ruismaker FM (Music)
Ruismaker FM 1.0 Device: iOS Universal Category: Music Price: $4.99, Version: 1.0 (iTunes) Description: Following up on the success of Ruismaker, here's her crazy twin-sister, designed for people who want to design their own... | Read more »
Space Marshals 2 (Games)
Space Marshals 2 1.0.15 Device: iOS iPhone Category: Games Price: $5.99, Version: 1.0.15 (iTunes) Description: The sci-fi wild west adventure in outer space continues with Space Marshals 2. This tactical top-down shooter puts you in... | Read more »
Dungeon Warfare (Games)
Dungeon Warfare 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: Dungeon Warfare is a challenging tower defense game where you become a dungeon lord to defend your dungeon against greedy... | Read more »
Solitairica (Games)
Solitairica 1.0.7 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.7 (iTunes) Description: Solitairica takes RPG combat and challenging rogue-like progression to a fresh new place—the world of solitaire! | Read more »
Bowmasters tips, tricks and hints
At least for this writer, archery was one of the more pleasant surprises of the 2016 Rio Olympics. As opposed to target shooting with guns, which was dreadfully boring, watching people shoot arrows at targets was pretty darn cool. [Read more] | Read more »
Best apps for watching live TV
The Olympics have come and gone, leaving nearly everyone in a temporary state of "What the heck am I going to watch on TV right now?" Besides old reruns of Golden Girls, but that goes without saying. [Read more] | Read more »

Price Scanner via MacPrices.net

27-inch iMacs on sale for up to $220 off MSRP
B&H Photo has 27″ Apple iMacs on sale for up to $200 off MSRP including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2099 $200 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1899 $100... Read more
Apple refurbished 13-inch MacBook Airs availa...
Apple has Certified Refurbished 2016 and 2015 13″ MacBook Airs now available starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: - 2016 13″ 1.6GHz/8GB/... Read more
Apple refurbished iPad mini 2s available for...
Apple is offering Certified Refurbished iPad mini 2s for up to $80 off the cost of new minis. An Apple one-year warranty is included with each model, and shipping is free: - 16GB iPad mini 2 WiFi: $... Read more
Save up to $600 with Apple refurbished Mac Pr...
Apple has Certified Refurbished Mac Pros available 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 following... Read more
Mac Pros on sale for $200 off MSRP
B&H Photo has Mac Pros on sale for $200 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3799, $200... Read more
Will We See A 10.5″ iPad Pro in 2017? – The ‘...
A MacRumors report, cites a research note from KGI Securities analyst Ming-Chi Kuo, saying a new size iPad model is in the works. According to the highly respected Cho, who has a strong track record... Read more
IOGEAR USB-C Docking Station Transforms Lapto...
IOGEAR has announced the launch of its innovative USB-C Docking Station with Power Delivery which turns USB-C enabled laptops into desktop workstations. The new IOGEAR USB-C Docking Station features... Read more
12-inch Retina MacBooks on sale for up to $10...
Amazon has 2016 12″ Apple Retina MacBooks on sale for $100 off MSRP. Shipping is free: - 12″ 1.1GHz Space Gray Retina MacBook: $1199 $100 off MSRP - 12″ 1.1GHz Silver Retina MacBook: $1224.99 $75 off... Read more
13-inch 2.5GHz MacBook Pro (Apple refurbished...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros... Read more
21-inch iMacs on sale for up to $120 off MSRP
B&H Photo has 21″ iMacs on sale for up to $120 off MSRP including free shipping plus NY sales tax only: - 21″ 3.1GHz iMac 4K: $1379 $120 off MSRP - 21″ 2.8GHz iMac: $1199.99 $100 off MSRP - 21″ 1... Read more

Jobs Board

*Apple* Mobile Master - Best Buy (United Sta...
What does a Best Buy Apple Mobile Master do? At Best Buy, our mission is to leverage the unique talents and passions of our employees to inspire, delight, and enrich Read more
*Apple* Retail - Multiple Positions Akron, O...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Simply Mac *Apple* Specialist- Repair Techn...
…The Technician is a master at working with our customers to diagnose and repair Apple devices in a manner that exceeds the expectations set forth by Apple Read more
*Apple* Retail - Multiple Positions Germanto...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Professional Learning Specialist - A...
# Apple Professional Learning Specialist Job Number: 51234379 Portland, Maine, Maine, United States Posted: Aug. 18, 2016 Weekly Hours: 40.00 **Job Summary** The Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.