Catalog XCMD
Volume Number: 5
Issue Number: 11
Column Tag: HyperChat™
Related Info: File Manager (PBxxx)
XCMD Corner: Catalog XCMD
By Donald Koscheka, Arthur Young & Co., MacTutor Contributing Editor
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Bullet Proofing
Recently, Joe Palooka wrote to complain about a bug in the GetFileName XCMD
that appeared in this column a few months back. Apparently, the xcmd bombed if you
passed it more than four file types. But this letter raises a more important issue: how
much bulletproofing should I do to my code examples?
Before you jump to the obvious conclusion, allow me to make my case.
Bulletproofing my code examples carries three liabilities for this column, size and
clarity and time. The former is obvious. This magazine can carry only a certain
number of pages per issue. Exceeding that page limit on a regular basis will result in
my column getting bumped or serialized. I would like to avoid either case.
Clarity is not so obvious and, in fact, is a function of size. The larger a program
is, the more unreadable it becomes. Bulletproofing code tends to be fairly routine, and
one can almost apply a formula to XCMDs for bulletproofing: (1) Are the input
parameters defined? (2) if so, are they properly conditioned (e.g. correct number of
data).
The final liability is time. My years of experience have taught me that a large
amount of a programming project’s time is spent anticipating exceptions. Working
under a monthly deadline, it is often necessary to eliminate this step. I don’t see any
contradiction here. If you intend to use my code in your own product, then it’s
incumbent on you test its effectiveness. Bulletproofing my examples will only make
your job harder and even then, I have no way of anticipating your exceptions (i.e. what
happens to subroutine x if I make this small change to its parameters?)
This code tends to take the form:
if( paramPtr->params[i] && **(paramPtr->params[i]) )...
Testing the input parameters is something else entirely and can easily exceed the
size of the “functional code”.
This is not to belittle the need for bulletproof code. Far from it. If you intend to
use the code in this column, you should use it as a starting point. In general, if you
intend to use somebody else’s code, you should seek answers to these questions: what
does the code do? what doesn’t the code do?
At any rate, I will leave this issue on your hands. Write to the editor and let him
know your feelings.
One good XCMD deserves another. Recently, Joe Zuffoletto called me to ask
whether I had any intentions of writing an XCMD that returns a catalog of a given
directory. You may recall that Joe gave us the series on adding standard Mac windows
to Hypercard. Such code cannot go unrewarded and so this month’s xcmd ...
Catalog accepts parameters in one of two forms. If you pass a pathname in the
first parameter, it will return a catalog of all files in that directory. If the first
parameter is empty, then Catalog will use the second parameter as directory reference
number. This second parameter requires further explaining by way of the file
manager.
When the user selects a file from the standard file dialog, the name as well as the
volume reference number is passed back to the caller. Under HFS, the volume
reference number masquerades as a working directory id. In reality, this reference
number acts as either a volume reference number or a working directory id. How the
file manager tells them apart is subtle but important:
Volume reference numbers are small negative integers such as -1, -2, -3... In
fact, if you pass such a number to Catalog, you will get a listing of the root directory of
the volume in question.
Working directory id’s are x. Working directories must not be confused with
directory id’s. Each file has a unique id assigned to it called a directory id. This id is a
long integer that uniquely identifies a file or folder. Working directory id’s by
contrast are integers and are not unique for a given folder. Working directories are
very much like file reference numbers. When a working directory is opened by the
call, PBOpenWD, a reference number is returned in the vRefNum field.
Listing 1:
/********************************/
/* File: Catalog.c */
/* */
/* Given the reference number of*/
/* a working directory or volume*/
/* return a list of all files & */
/* folders in that directory */
/* */
/* if a name is given, use it, */
/* otherwise, use the id passed */
/********************************/
#include
#include
#include
#include
#include
#include
#include
#include
#include “HyperXCmd.h”
#include “HyperUtils.h”
#define nil 0L
extern GetCatalog();
pascal void main( paramPtr )
XCmdBlockPtr paramPtr;
{
Handle catalog;
Str31 str;
short dirID;
/*** intialize the output container ***/
catalog = NewHandle( 0L );
/*** convert the wdid to a usable form ***/
if( paramPtr->params[1] ){
HLock( paramPtr->params[1] );
ZeroToPas( paramPtr, *(paramPtr->params[1]), &str );
HUnlock( paramPtr->params[1] );
dirID = (short)StrToNum( paramPtr, &str );
/*** given the id of a directory, ***/
/*** return a catalog for that directory ***/
GetCatalog( dirID, catalog );
}
else if( paramPtr->params[0] ){
char path[256];
CInfoPBRec catPB;
WDPBRec wdPB;
HLock( paramPtr->params[0] );
ZeroToPas( paramPtr, *(paramPtr->params[0]), &path );
HUnlock( paramPtr->params[0] );
/*** get a directory id to this path ***/
catPB.dirInfo.ioNamePtr = (StringPtr)path;
catPB.dirInfo.ioFDirIndex = 0;
catPB.dirInfo.ioVRefNum = 0;
if( PBGetCatInfo( &catPB, 0 ) == noErr )
if( catPB.dirInfo.ioFlAttrib & 0x010 ){ /*** it’s a
directory ***/
wdPB.ioNamePtr = (StringPtr)path;
wdPB.ioWDProcID = 0;
if( PBOpenWD( &wdPB, 0 ) == noErr ){
wdPB.ioWDVRefNum= catPB.dirInfo.ioVRefNum;
wdPB.ioWDDirID = catPB.dirInfo.ioDrDirID;
GetCatalog( wdPB.ioVRefNum, catalog );
PBCloseWD( &wdPB, 0 );
}
}
}
/*** append a null to the end of the ***/
/*** the directory for Hypercard ***/
AppendCharToHandle( catalog, ‘\0’ );
paramPtr->returnValue = catalog;
}
Listing 2:
#include
#include
#include
#include
#include
#include
#include
#include
#include “HyperXCmd.h”
#include “HyperUtils.h”
/*** If you read this column ***/
/*** column on a regular basis ***/
/*** you may want to add these ***/
/*** routines to HyperUtils.c ***/
/*** If you don’t have Hyper- ***/
/*** utils.c, you can obtain it ***/
/*** from MacTutor for a small ***/
/*** handling charge ***/
#define SYNC 0
AppendCharToHandle( theHand, theChar )
Handle theHand;
char theChar;
/****************************
* Given a valid handle, append
* the character passed in to
* the end of the handle
*
* This is a useful way to embed
* \r, \t or \0 into a container
* for use by hypercard.
****************************/
{
long hsiz = GetHandleSize( theHand );
char *dirP;
SetHandleSize( theHand, hsiz + 1 );
dirP = *theHand + hsiz;
*dirP= theChar;
}
GetCatalog( wdref, dirH )
short wdref;
Handle dirH;
/****************************
* Get a listing of the directory
* passed in.
* In:
* wdref == reference number of the
* the desired working directory
* dirH == handle to the output container.
* Note that we allocate all structures
* in the heap to minimize the impact
* a high directory valence might have
* on the stack.
****************************/
{
OSErr done = 0; /* goes true when done searching */
CInfoPBPtr catPB = (CInfoPBPtr)NewPtr( sizeof(CInfoPBRec));
WDPBPtr wdPB = (WDPBPtr)NewPtr( sizeof(WDPBRec));
char *fname = (char *)NewPtr( 256L );
if( catPB && wdPB && fname ){
catPB->dirInfo.ioNamePtr = (StringPtr)fname;
catPB->dirInfo.ioFDirIndex = 0;
catPB->dirInfo.ioVRefNum = wdref;
do{
*(catPB->dirInfo.ioNamePtr) = ‘\0’;
catPB->dirInfo.ioFDirIndex++;
catPB->dirInfo.ioDrDirID = 0;
if( (done = PBGetCatInfo( catPB, SYNC ) ) == noErr ){
pStrToField( fname, ‘’, dirH );
if( catPB->dirInfo.ioFlAttrib & 0x010 ){ /*** it’s a
directory ***/
AppendCharToHandle( dirH, ‘:’ );
}
AppendCharToHandle( dirH, ‘\r’ );
}
}while( !done );
DisposPtr( (Ptr)catPB );
DisposPtr( (Ptr)wdPB );
DisposPtr( (Ptr)fname );
}
}