XCMD Text Jig
Volume Number: | | 7
|
Issue Number: | | 2
|
Column Tag: | | abc
|
Related Info: File Mgr (PBxxx)
Towards A Test Jig for XCMDs
By Bob Gordon, Minneapolis, MN
jig n. A device for guiding a tool or for holding machine work in place.
I must have been lucky--the first time I ran my first XCMD it worked. Admittedly, it was not complete, but it did do more or less what it was supposed to do. Subsequently I have worked on several other XCMDs with much less success. Running them yielded various interesting crashes, which were impossible to deal with from FoxBase.
A Small Aside About FoxBase
FoxBase is a database package and language available for the Macintosh from Fox Software of Toledo, Ohio, of all places. It is highly compatible with dBase III and FoxBase on MS-DOS machines. That is, I suppose, useful in some cases. The really nice things about FoxBase on the Mac are the development environment and its speed. The Fox people have extended the language and provided the tools to make it possible to develop Mac-like applications with relative ease. It is possible to fairly rapidly bring up a custom database application with multiple screens (FoxBase in its current incarnation does not have scrolling windows. This has not been a serious problem.), menus, a variety of reports, full control of fonts, styles and sizes, etc. Speed of database functions seems to be a Fox tradition. For a while, FoxBase was overwhelmingly the fastest database package available on the Mac. Now it may be simply the fastest. These days I do most of my programming in FoxBase primarily because my clients are interested in having a working program in a short time.
So what does FoxBase have to do with XCMDs? Simply that FoxBase supports them. If you need a capability not available in FoxBase, just like HyperCard, you can write an XCMD.
And Now Back to our Program
The main problem I was having was the difficulty of seeing what was happening inside the XCMD from FoxBase (I assume there would be a similar problem with HyperCard). This is coupled with the awkwardness of the development process. One builds the code resource in C or Pascal (I use Think C). Quits that. Starts FoxBase (or HyperCard with perhaps using ResEdit to install the Resource). And runs the program to see what happens. Then back to C as necessary. Anyway, that is what I was doing. Since I wanted to be able to write XCMDs more easily, I decided to develop a little test jig to hold the XCMD while it is under development. With this, I would be able to run the XCMD directly from C. This would reduce my turn-around times considerably and enable me to use various debugging techniques inside the C code.
The basic idea is to have a small program from which we can call our XCMD-under-development. That part is fairly straight forward. The other part is that XCMDs from HyperCard and FoxBase assume the existence of call backs. These are various useful routines built into the host environment. Since the XCMD should not care where its running from, the test jig would have to supply the call back routines as well. Now, at this point I must admit that the program presented here is not complete I didnt write all the call backs. I only wrote the ones I needed. Writing the remaining call backs is, as they say, an exercise for the reader. HyperCard poses an additional problem. It receives messages. FoxBase doesnt. I dont deal with HyperCard messages at all.
Conditional Compilation
In order to make the development process as painless as possible, there should be a minimum of changes as we move the XCMD from the test jig to the its actual host. In C such variations are easily accomplished using conditional compilation directives available in the pre-processor. In xcmd.h, which is a header file to be included in any XCMD, there is a #define statement:
/* 1 */
#define XTEST
This is used to indicate that the XCMD is in the development environment. In several places throughout the code there are tests to see if XTEST is defined. If it is, that code is compiled. For example, here is the start of the XCMD itself:
/* 2 */
#ifdef XTEST
pascal void xserial(block)
#else
pascal void main(block)
#endif
When under test, the XCMD is a C function named xserial, when XTEST is not defined, and were ready to build the code resource, the XCMD becomes main(). With this technique all the code used for the test environment can stay in the source files. When XTEST is not defined (simply by commenting it out), the test code is not compiled and not linked in. It is as if it does not exist.
Another Comment About FoxBase
While FoxBase uses XCMDS and can run most HyperCard XCMDs, it includes a number of additional fields in the parameter block that facilitate their writing and use. Of particular interest are the utillong and utilhandle items. These are, in effect, static variables that retain their value between calls to the XCMD. You can assign a value, and it will be there the next time you make a call. The two items, publong and pubhandle, are similar except they are shared among all XCMDs. They are globals for all XCMDs loaded in a FoxBase program. The other items should be reasonably identifiable.
The reason I bring this up here, is that there is another conditional compilation flag which determines whether or not to include these. It is called FOX. Unless you are writing an XCMD for FoxBase, comment it out.
Setting Up the Parameter Block
While a call to an XCMD from HyperCard or FoxBase looks reasonably ordinary, the XCMD does not see things in the same way as a regular function. All information is passed in a parameter block. For the test jig to work, this must be set up correctly. There are two functions involved in this: xinit() and xpars().
xinit() initializes the parameter block. The block itself is simply a local variable in the main test program. The most important thing that xinit() does is create sixteen handles to hold the parameters that may be passed to an XCMD. I simply created sixteen handles of 255 bytes each. While this may look a little silly, it simplifies xpars(), and in a simple test environment, who cares?
xpars() sets up the parameter block prior to each call. It accepts a pointer to the parameter block and a variable number of strings, which are the XCMD parameters passed in. It copies the parameters into the handles stored in the parameter block and sets the number of parameters in block.paramCount. The call to xpars() must end with a null string so xpars() can know when to stop collecting parameters. By the way, xpars() uses the ANSI C approach in dealing with functions with variable numbers of arguments.
One nice thing about developing XCMDs in C is that XCMDs expect C strings as parameters. It reduces (a little bit) the hassle of converting strings from one kind to another.
Once the parameter block is set up, we can call the XCMD.
Call Back Routines
As mentioned above, for the test jig to work, it must mimic the host environment. For FoxBase this is fairly straight forward. One simply has to duplicate the various utility routines. HyperCard can receive messages that can invoke almost any HyperTalk operation.
All the call back routines are called the same way: one sets up the parameters in the parameter blocks inArgs array, sets a code representing the operation to do in block.request, and then does DoJSR(blockptr). This process is normally handled via a glue routine so the typical call looks a bit more conventional:
/* 3 */
a_long = StrToLong(blockptr,s);
where blockptr is the pointer to the parameter block and s is a (Pascal) string to convert.
To build the test jig, each call back that you use has to be a function in C as well as the normal glue routine with #ifdef to select which version is appropriate. Here is an abbreviated version of StrToLong:
/* 4 */
#includexcmd.h
pascal long StrToLong(block,s)
XCmdBlockPtr block;
char *s;
{
#ifdef XTEST
/* C code to convert a Pascal string to a long */
return(n);
#else /* standard glue */
block->inArgs[0] = (long)s;
block->request = xreqStrToLong;
block->entryPoint();
return( (long)block->outArgs[0]);
#endif
}
In other words, what you have to do is re-write the glue routine file so that it automatically selects the standard glue if you are building the code resource or it actually carries out the desired operation if you are using the test jig. For most of the call backs, this is not a major problem because the routines are simple, basic operations. Many of them are conversions. Code to carry them out is available in most programming texts. (This is not to say I have actually implemented them all. In fact I have only made one or two).
If you need to use any of the Get/Set field routines, I think the simplest thing to do would be to cheat. Your XCMD probably doesnt care what value it gets as long as it gets something. So you could just return some sensible value. If you need to store a value in a field and recall it later, just keep the value in a static parameter. The point is, keep it simple. The purpose of all this is to facilitate testing your XCMD not to rewrite HyperCard or FoxBase.
The Development Process
With the test jig, all development and testing takes place in C. You can put printf()s any where you want. Inside your XCMD if you wish. You can use a source-code debugger. You dont need to get out of the C environment until you know your XCMD does what it is supposed to do. This is very useful if you have to do some exploratory programming to figure out how things are supposed to work.
In addition to the test code, the XCMD under development, the modified call back/glue routines, you need to have the ANSI library linked into your project. I use the ANSI library so I can use printf() for debugging. Even though it is no longer called (with the XTEST turned off), Think C will include it. If I was going to build a career writing XCMDs, I would write a custom printf() that would be controlled through XTEST.
You will by now have realized that this is not a Macintosh application. No windows, no menus, no event loop. In fact, there is no user interface at all. I am taking advantage of Think Cs extremely rapid turn-around. If I need to change an input to make a particular test, I simply go into xtest.c and modify the calls to xpars() and run the project. And all this was done on a one Meg Mac Plus.
Once you have your XCMD developed, documented, debugged using the test jig, you are ready to create the code resource. This involves four steps: 1. Change the project type (in Think C). The test jig thinks it is an application, you must change this to a code resource. Think C will warn you that it will have to reload and recompile everything. 2. Comment out the #define XTEST in xcmd.h. This will turn off all the test specific code. 3. Remove the ANSI library. 4. Build the code resource.
About This XCMD
xserial was written so I could dial the phone from FoxBase. It uses a modem to do this; I have actually called some people so I know it works. It generally doesnt care what it gets back. In doing so I got to learn a little about using the Mac serial ports (thanks to Tom Scheiderich, MacTutor, June 1988). I revised it slightly for this article (it now actually gets the result back from the modem). I am not going to discuss it in detail because it is really just here so the test routine has something to test.
The Code
The code is fairly straight forward. Most of it has comments to describe the test jig requirements.
Listing: xcmd.h
#include<PrintMgr.h>
/* define XTEST for callbacks to be imitated in C code */
#define XTEST
/* define FOX for xcmds to be used in FoxBase environment */
#define FOX
typedef struct
{
short paramCount;
Handle params[16];
Handle returnValue;
short passflag;
void (*entryPoint)();
short request;
short result;
long inArgs[8];
long outArgs[4];
#ifdef FOX
/* these fields of the XCMD parameter block used only in
* foxbase
*/
short version;
short options;
WindowPtronscreen;
GrafPtroffscreen;
THPrintPrintRec;
TPPrPort printPort;
short foxuser;
short setresource;
long utillong1;
long utillong2;
long utillong3;
long utillong4;
Handle utilhandle1;
Handle utilhandle2;
Handle utilhandle3;
Handle utilhandle4;
long publong;
Handle pubhandle;
long reserved1;
long reserved2;
#endif
}
XCmdBlock, *XCmdBlockPtr;
#define errorFlag(short) -1
#define NIL (Handle) 0
#define True(short)1
#define False (short) 0
/* useful key names */
#define TAB 9
#define CR13
#define LF10
/* function prototypes for test routines */
void xpars(XCmdBlock*,...);
/* function prototypes for xcmd routines */
long HandleToNum(XCmdBlockPtr,Handle);
char *ctop(char *);
char *ptoc(char *);
void setreturn(XCmdBlockPtr,char *);
Handle CopyStrToHand(char *);
/* function prototypes for call back routines */
pascal long StrToLong(XCmdBlockPtr,char *);
/* defines for call back routines */
#define xreqStrToLong9
/****************************************************/
Listing: xtest.c
#includexcmd.h
#include<FileMgr.h>
#include<MacTypes.h>
#include<string.h>
#include<MemoryMgr.h>
#ifdef XTEST
#include<stdio.h>
#endif
/* this is the main program for the xcmd test jig
* it defines the parameter block (for both HyperCard and FoxBase)
* initializes it, sets up parameters and calls the xcmd
*/
#ifdef XTEST
/* prototype for xcmd under test */
pascal void xserial(XCmdBlock *);
main()
{
XCmdBlockb;
XCmdBlock*pb;
printf(\nStarting XCMD Test);
pb = &b;
/* initialize the xcmd block. THIS MUST BE DONE BEFORE ANY
* USE OF THE BLOCK
*/
xinit(pb);
/* call xpars to set the xcmds parameters prior to each
* call. all parameters are strings. there can be 0 to 16
* parameters. xpars accepts a variable number of
* parameters; the last parameter
* must be an empty string to terminate the list.
*/
xpars(pb,1",1200",N,8",1",S,R,);
xserial(pb);
printf(\n return value %s,*(pb->returnValue));
wait(1);
xpars(pb,ATZ\r,);
xserial(pb);
printf(\n ATZ return value %s,*(pb->returnValue));
wait(1);
xpars(pb,);
xserial(pb);
printf(\n return value %s,*(pb->returnValue));
xpars(pb,);
xserial(pb);
printf(\n return value %s,*(pb->returnValue));
xpars(pb,ATDP8231770\r,);
xserial(pb);
printf(\n DIAL return value %s,*(pb->returnValue));
wait(30); /* wait for 30 seconds after dialing */
xpars(pb,);
xserial(pb);
printf(\n return value %s,*(pb->returnValue));
xpars(pb,);
xserial(pb);
printf(\n return value %s,*(pb->returnValue));
}
#endif
/******************************************************/
Listing: xinit.c
/* xinit
* initializes xcmd parameter block
*/
#include xcmd.h
#ifdef XTEST
xinit(pb)
XCmdBlock*pb;
{
short i;
/* for testing purposes, we simply set up 16 handles of 255
* bytes each and leave them around. while a bit sloppy, it
* does not make any difference in the test environment.
*/
pb->paramCount = 0;
for(i = 0;i <= 15;i++)
pb->params[i] = NewHandle(255);
/* the following are only available in the FoxBase
* version of the XCMD.
*/
#ifdef FOX
pb->version = 1;
pb->options = 0;
pb->PrintRec = 0L;
pb->printPort = 0L;
pb->foxuser = -1;
pb->setresource = -1;
pb->utillong1 = 0L;
pb->utillong2 = 0L;
pb->utillong3 = 0L;
pb->utillong4 = 0L;
pb->utilhandle1 = 0L;
pb->utilhandle2 = 0L;
pb->utilhandle3 = 0L;
pb->utilhandle4 = 0L;
#endif
}
#endif
Listing: xpars.c
#include<stdarg.h>
#include<string.h>
#include xcmd.h
/* Copies supplied parameters (each comes in as a string
* to the supplied parameter block and sets the number of
* parameters field appropriately. Note that this routine
* can handle a variable number of arguments. It uses the
* macros (in stdarg.h) supplied with Think C to manage
* the variable number of arguments correctly. The last
* argument must be a null string ().
*/
#ifdef XTEST
void xpars(XCmdBlock *pb,...)
{
va_listxp;
char *s;
short i;
va_start(xp,pb);
s = va_arg(xp,char *);
i = 0;
while (*s && i <= 15) /* can have a max of 16 arguments */
{
strcpy(*(pb->params[i]),s);
i++;
s = va_arg(xp,char *);
}
pb->paramCount = i;
va_end(xp);
}
#endif
Listing: xserial.c
#include<FileMgr.h>
#include<MacTypes.h>
#include<string.h>
#include<MemoryMgr.h>
#include<SerialDvr.h>
#include xcmd.h
void setreturn(XCmdBlockPtr,char *);
Handle CopyStrToHand(char *);
#define Mzero 34
#define Azero 48
#ifdef XTEST
pascal void xserial(block)
#else
pascal void main(block)
#endif
register XCmdBlockPtr block;
{
#define Bufsz 64
short port;
unsigned short baud;
short databits;
short stopbits;
short parity;
short handshake;
short config;
short error;
short inport;
short outport;
char *s;
short i;
long length;
SerShk shake;
char inbuf[Bufsz];
error = 0; /* no error */
setreturn(block,None);
switch (block->paramCount)
{
case 0: /* receive string */
inport = block->utillong1;
SerGetBuf(inport,&length);
if (length)
{
if (length < Bufsz)
{
FSRead(inport,&length,inbuf);
inbuf[length] = 0;
/* null terminate to make a C string */
setreturn(block,inbuf);
}
}
else
setreturn(block,No data);
break;
case 1: /* send string */
outport = block->utillong2;
s = (char *)*(block->params[0]);
length = s_len(s);
error = FSWrite(outport,&length,s);
if (error)
setreturn(block,Write error);
return;
break;
case 7: /* initialize */
port = (short) HandleToNum(block,block->params[0]);
baud = (short) HandleToNum(block,block->params[1]);
parity = *(char *)*(block->params[2]);
databits = (short) HandleToNum(block,block->params[3]);
stopbits = (short) HandleToNum(block,block->params[4]);
handshake = *(char *)*(block->params[5]);
s = (char *)*(block->params[6]);
i = 0;
while (s[i])
{
switch(s[i])
{
case R : endline[i] = 13; break;
case L : endline[i] = 10; break;
}
i++;
}
endline[i] = 0;
switch (baud)
{
case 300 : baud = 380; break;
case 600 :
case 1200: baud = 94; break;
case 1800:
case 2400: baud = 46; break;
case 3600:
case 4800: baud = 22; break;
case 7200:
case 9600: baud = 18; break;
case 19200:baud = 4; break;
case 57600:
default :baud = 94; break;
}
switch (parity)
{
case N : parity = 8192; break;
case O : parity = 12288; break;
case E : parity = 4096; break;
default :parity = 8192; break;
}
switch (databits)
{
case 7 : databits = 1024; break;
case 8 : databits = 3072; break;
default: databits = 3072; break;
}
switch (stopbits)
{
case 1 : stopbits = 16384; break;
case 2 : stopbits = -16384; break;
default: stopbits = 16384; break;
}
switch (handshake)
{
case H :
case S :
case N :
default :shake.fXOn = 0;
shake.fCTS = 0;
shake.xOn = 0;
shake.xOff = 0;
shake.errs = 0;
shake.evts = 0;
shake.fInX = 0;
shake.fDTR = 0;
}
config = baud + parity + databits + stopbits;
switch (port)
{
case 1 :
inport = -6;
outport = -7;
error = RAMSDOpen(sPortA);
break;
case 2 :
inport = -8;
outport = -9;
error = RAMSDOpen(sPortB);
break;
}
if (error)
{
setreturn(block,Cant open driver);
}
else
{
error = SerReset(inport,config);
if (error)
setreturn(block,Cant set in port);
else
{
error = SerReset(outport,config);
if (error)
setreturn(block,Cant set in port);
else
{
error = SerHShake(inport,&shake) + SerHShake(outport,&shake);
if (error)
setreturn(block,Cant set handshaking);
else
{
block->utillong1 = inport;
block->utillong2 = outport;
}
}
}
}
}
}
void setreturn(block,s)
XCmdBlockPtr block;
char *s;
{
block->returnValue = (Handle) CopyStrToHand(s);
}
Handle CopyStrToHand(s)
char *s;
{
Handle h;
h = (Handle)NewHandle((long) s_len(s) + 1);
s_copy ((char *)(*h),s);
return(h);
}
Listing: HandleToNum.c
/* converts a string to a long */
#includexcmd.h
long HandleToNum(block,h)
XCmdBlockPtr block;
Handle h;
{
char s[128];
long num;
s_copy(s,*h);
num = StrToLong(block, (char *) ctop(s));
return(num);
}
Listing: StrToLong.c
/* This is the call back routine/glue routine as modified for use in
the test jig. The bottom part (after the #else) is the standard glue;
the first part is C code that duplicates the function of the call back.
I wrote this from scratch, you could also use library functions to provide
the operations needed. */
#includexcmd.h
pascal long StrToLong(block,s)
XCmdBlockPtr block;
char *s;
{
#ifdef XTEST
long n;
short slen;
char c;
long place;
slen = s[0];
n = 0L;
place = 1L;
while(slen)
{
if (s[slen] >= 0 && s[slen] <= 9)
{
c = s[slen] - 0;
n += c * place;
place *= 10;
}
slen--;
}
return(n);
#else
block->inArgs[0] = (long)s;
block->request = xreqStrToLong;
block->entryPoint();
return( (long)block->outArgs[0]);
#endif
}
The following are small utility functions that are needed at various points.
Listing: ctop.c
#include xcmd.h
/* converts c string to pascal string */
char *ctop(s)
char *s;
{
short i,l;
for (i = 0,l=0; s[i] != 0; ++i)
++l;
while(i--)
s[i+1] = s[i];
s[0] = l;
return(s);
}
Listing: s_copy.c
/* s_copy */
s_copy(d,s)
char *d;
char *s;
{
while (*d++ = *s++)
;
}
Listing: s_len.c
/* s_len
* returns length of a string
*/
short s_len(s)
char *s;
{
short i;
i = 0;
while (*s++)
i++;
return i;
}
Listing: wait.c
/* waits for the specified number of seconds. should be used
* only for testing as this throws the program into a tight
* loop and nothing else is done.
*/
wait(amount)
short amount;
{
long start;
long test;
GetDateTime(&start);
do {
GetDateTime(&test);
}
while (test - start < amount);
}
Final Notes
As I noted, I have only written one or two call back routines for use in the test jig, and only one is included here. If anyone finds this useful and writes other call backs, send them to me care of MacTutor. If we get a fairly complete set, Ill put them together in a subsequent article for everyone to use.
If you are interested in more information about FoxBase, I have a newsletter you might wish to see.
Keep those cards and letters coming. Until next time.