All DatabasesMacTech Vol 04-1988
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
#include
#include
#include
#include
#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
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
Referenced by (27):