TweetFollow Us on Twitter

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 or source 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.

Catalog

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<MacTypes.h>
#include<OSUtil.h>
#include<MemoryMgr.h>
#include<FileMgr.h>
#include<ResourceMgr.h>
#include<pascal.h>
#include<string.h>
#include<hfs.h>
#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;
 WDPBRecwdPB;
 
 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<MacTypes.h>
#include<OSUtil.h>
#include<MemoryMgr.h>
#include<FileMgr.h>
#include<ResourceMgr.h>
#include<pascal.h>
#include<hfs.h>
#include<string.h>
#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 SYNC0

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));
 WDPBPtrwdPB= (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 );
 }
}

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Avatar Legends: Realms Collide pre-regis...
Despite the staying power that the series has, Avatar: The Last Airbender surprisingly fumbled in the mobile gaming sphere, with Generations shuttering about a mere year after launch. Now, Tilting Point is giving it a go, with the upcoming Avatar... | Read more »
Return to the glory days of tactical RPG...
Back on the old Sega Mega Drive, or Genesis depending on where you are, there was a little series of tactical role-playing games called Shining Force, and I adored them. It started a love for this grid-based genre that persisted through the years... | Read more »
Take on the grandest beasts of all as th...
It has been hyped for a while but now it is finally here, the new Dancing in the Tempest season has arrived in Monster Hunter Now. Kicking off a banner summer for the game, it is time to strap on your boots and face the greatest threat yet, as the... | Read more »
The indie hit Vault of the Void will lan...
In a market where a lot of AAA games are starting to feel like reboots, remakes, or the same thing we’ve seen ten times with a different name slapped on it, indie developers are a boon. Especially ones who build a successful game singlehandedly,... | Read more »
Stumble Guys tries to catch up to the hy...
Do you remember when the Fallout TV series launched on Amazon and everyone nearly lost their minds? Well, it appears that Scopely missed that particular craze, and only now are we going to get a Fallout crossover, and by now, I mean in version 0.... | Read more »
Bid farewell to Penacony as Honkai: Star...
Penacony has been a story of twists, exciting new characters, and strong allies, and soon Honkai: Star Rail will be finishing it with a bang. Version 2.3, fittingly titled Farewell Penacony, will be launching June 19th and will feature updates to... | Read more »
HoYoverse roll out their plans for Anime...
For those who are looking to book a getaway in July, you might give some thought to Los Angeles between the 4th and 7th, which just so happens to coincide with the Anime Expo 2024. Amongst all the storied attendees is HoYoverse, who will be... | Read more »
The first rule of Brok the InvestiGator...
Mobile gamers were recently able to get their hands on BROK the InvestiGator, a point-and-click following the adventures of the titular reptile, a detective who can solve crimes through wit or brawn. If you were one that chose the latter then... | Read more »
Diablo Immortal celebrates second annive...
It has been two years since Diablo Immortal launched and despite some very valid criticism of its business model, it has done pretty well for itself. The Tempest class also gives it a lot of grace. To celebrate this anniversary, the March of the... | Read more »
Pokemon GO pulls on its jersey for a foo...
There have been a lot of jokes about this, some by me, but Pokemon Go has genuinely done a lot of good by getting people out and about.Pokemon GO Fest 2024: Madrid is fast approaching, and Niantic has set up a new area in a bit to get people to... | Read more »

Price Scanner via MacPrices.net

Apple Watch Ultra Watch 2 on sale for $719, s...
Amazon is offering an $80 discount on every Apple Watch Ultra 2 model this week. Their price is now $719. Shipping is free. For the latest prices & deals, keep an eye on our Apple Watch Price... Read more
New sale at Amazon: 16-inch M3 Pro and M3 Max...
Amazon is offering instant discounts on 16″ M3 Pro and 16″ M3 Max MacBook Pros ranging up to $350 off MSRP. Shipping is free. These are the lowest prices currently available for new 16″ Apple MacBook... Read more
Get a 13-inch M2 MacBook Air today at Apple f...
Apple has 13″ M2 MacBook Airs available for only $849 today in their Certified Refurbished store. These are the cheapest M2-powered MacBooks for sale at Apple. Apple’s one-year warranty is included,... Read more
Clearance Mac Studio with M1 Max CPU availabl...
Apple has clearance M1 Max Mac Studios available in their Certified Refurbished store for $270 off original MSRP. Each Mac Studio comes with Apple’s one-year warranty, and shipping is free: – Mac... Read more
Apple has 24-inch M3 iMacs on sale for $200-$...
Apple has a full line of 24-inch M3 iMacs available in their Certified Refurbished store starting at $1099 and ranging up to $260 off original MSRP. Each iMac is in like-new condition and comes with... Read more
24-inch M1 iMacs are available at Apple start...
Apple has clearance M1 iMacs available in their Certified Refurbished store starting at $1049 and ranging up to $300 off original MSRP. Each iMac is in like-new condition and comes with Apple’s... Read more
Back to School savings: Take $50-$100 off new...
Apple will take $50-$100 off new 11″ and 13″ M2 iPad Airs for all teachers, students, and staff of any educational institution with a .edu email address as part of their Apple Education discount,... Read more
Could A Smarter Siri Infused With AI (‘Apple...
FEATURE – The iPhone is already smart, but it’s about to become more intelligent. AI — short for artificial intelligence — is widely expected to be the main topic of discussion at this year’s WWDC (... Read more
Update: For WWDC, Amazon has lowered prices o...
Amazon has every configuration and color of Apple’s M3 MacBook Airs now on sale for $170-$210 off MSRP, starting at only $899 shipped, as Apple holds their annual WWDC conference this week. Their... Read more
Deal Alert! 2nd-generation Apple AirPods on s...
Amazon has 2nd generation Apple AirPods on sale right now for only $79.99 shipped. That’s $50 (38%) off Apple’s MSRP. Their price is the lowest currently available for a new set of AirPods from any... Read more

Jobs Board

Beauty Consultant - *Apple* Blossom Mall -...
Beauty Consultant - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Senior Software Engineer - *Apple* Fundamen...
…center of Microsoft's efforts to empower our users to do more. The Apple Fundamentals team focused on defining and improving the end-to-end developer experience in Read more
Sublease Associate Optometrist- *Apple* Val...
Sublease Associate Optometrist- Apple Valley, CA- Target Optical Date: Jun 17, 2024 Brand: Target Optical Location: Apple Valley, CA, US, 92307 **Requisition Read more
Rehabilitation Medicine Technician - *Apple*...
Rehabilitation Medicine Technician - Apple Hill (Outpatient Clinic) - Day/Evening Location: York Hospital, York, PA Schedule: Part Time Sign-On Bonus Eligible Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.