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 it’s 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 didn’t 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 doesn’t. I don’t 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 we’re 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 block’s 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 */

#include“xcmd.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 doesn’t 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 don’t 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 C’s 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 doesn’t 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

#include“xcmd.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 xcmd’s 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,”Can’t open driver”);
 }
 else
 {
 error = SerReset(inport,config);
 if (error)
 setreturn(block,”Can’t set in port”);
 else
 {
 error = SerReset(outport,config);
 if (error)
 setreturn(block,”Can’t set in port”);
 else
 {
 error = SerHShake(inport,&shake) + SerHShake(outport,&shake);
 if (error)
 setreturn(block,”Can’t 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 */
#include“xcmd.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. */

#include“xcmd.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, I’ll 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.