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

Dropbox 193.4.5594 - Cloud backup and sy...
Dropbox is a file hosting service that provides cloud storage, file synchronization, personal cloud, and client software. It is a modern workspace that allows you to get to all of your files, manage... Read more
Google Chrome 122.0.6261.57 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Skype 8.113.0.210 - Voice-over-internet...
Skype is a telecommunications app that provides HD video calls, instant messaging, calling to any phone number or landline, and Skype for Business for productive cooperation on the projects. This... Read more
Tor Browser 13.0.10 - Anonymize Web brow...
Using Tor Browser you can protect yourself against tracking, surveillance, and censorship. Tor was originally designed, implemented, and deployed as a third-generation onion-routing project of the U.... Read more
Deeper 3.0.4 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
OnyX 4.5.5 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
Hopper Disassembler 5.14.1 - Binary disa...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
WhatsApp 24.3.78 - Desktop client for Wh...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
War Thunder 2.33.0.135 - Multiplayer war...
In War Thunder, aircraft, attack helicopters, ground forces and naval ships collaborate in realistic competitive battles. You can choose from over 1,500 vehicles and an extensive variety of combat... Read more
Iridient Developer 4.2 - Powerful image-...
Iridient Developer (was RAW Developer) is a powerful image-conversion application designed specifically for OS X. Iridient Developer gives advanced photographers total control over every aspect of... Read more

Latest Forum Discussions

See All

A Legitimate Massage Parlor, I Swear – T...
In this week’s Episode of The TouchArcade Show we talk about some of the major new releases on mobile this week including Warframe, we go over all the major news that came out from the Nintendo Direct Partner Showcase on Wednesday, we read our one... | Read more »
TouchArcade Game of the Week: ‘Rainbow S...
I feel like I am in a fever dream right now. What is this game that I’m playing? It’s a Rainbow Six game? But it’s all cutesy, and cartoony, and also kind of psychedelic? How is this a real thing? Well, it’s no fever dream, it is indeed a real thing... | Read more »
SwitchArcade Round-Up: ‘Promenade’, ‘Cho...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for February 23rd, 2024. It’s Friday, so we have to check out the remaining releases of the week. Not so many big ones today, but a healthy crop nonetheless. After summarizing all the... | Read more »
Steam Deck Weekly: Gundam Breaker 4 and...
Welcome to this week’s slightly shorter edition of the Steam Deck Weekly. I was a bit unwell this week so no reviews in this edition, but there is a lot of news and new Steam Deck Verified and Playable games to catch up on. I have something special... | Read more »
The 10 Best Run-And-Gun Games for Ninten...
The year 2024 is a rare one, because it is a year with a brand-new Contra game. Contra: Operation Galuga might be the freshest face on the block when it comes to Nintendo Switch run-and-gun action games, but it’s hardly fighting that war alone.... | Read more »
Version 1.4 of Reverse: 1999 will be lan...
Free up your diary for February 29th, as Bluepoch has announced the impending release of the award-winning Reverse: 1999s Version 1.4 update. The Prisoner in the Cave is an Ancient Greece-themed update with new recruits, gameplay modes, and plenty... | Read more »
Premium Mobile RPG ‘Ex Astris’ From ‘Ark...
Arknights developer Hypergryph’s premium RPG Ex Astris () recently had its release date confirmed, and we finally have an extended gameplay showcase. | Read more »
Apple Arcade Weekly Round-Up: Updates fo...
Following yesterday’s big Hello Kitty Island Adventure update, a few more notable game updates and events have gone live on Apple Arcade. Cypher 007 () has gotten its first content update in a few months taking you to Egypt for five new levels... | Read more »
‘Thunder Ray’ and ‘Hime’s Quest’ Are Now...
Crunchyroll has pushed two new games into the Crunchyroll Game Vault including Purple Tree Studio’s Thunder Ray which was already on iOS before as a premium release. Shaun even reviewed it last year. Read his review here. The second game is Poppy... | Read more »
Adorable Kitty-Collector Sequel ‘Neko At...
Ya’ll. This October will mark the ten-year anniversary of Hit Point launching Neko Atsume, the adorable kitty collecting sim that has become a runaway success and essentially created a sub-genre of cozy pet-collecting life sim games. Sure, the... | Read more »

Price Scanner via MacPrices.net

16-inch M3 Max MacBook Pro on sale for $300 o...
Amazon is offering a $300 instant discount on one of Apple’s 16″ M3 Max MacBook Pros today. Shipping is free: – 16″ M3 Max MacBook Pros (36GB/1TB/Space Black): $3199, $300 off MSRP Their price is the... Read more
Apple M2 Mac minis on sale for $100 off MSRP...
B&H Photo has Apple’s M2-powered Mac minis in stock and on sale for $100 off MSRP this weekend with prices available starting at $499. Free 1-2 day shipping is available to most US addresses: –... Read more
Apple Watch SE on sale for $50 off MSRP this...
Best Buy has all Apple Watch SE models on sale this weekend for $50 off MSRP on their online store. Sale prices available for online orders only, in-store prices may vary. Order online, and choose... Read more
Deal Alert! Apple 15-inch M2 MacBook Airs on...
Looking for the lowest sale price on a new 15″ M2 MacBook Air? Best Buy has Apple 15″ MacBook Airs with M2 CPUs in stock and on sale today for $300 off MSRP on their online store. Prices valid for... Read more
Amazon discounts iPad mini 6 models up to $12...
Amazon is offering Apple’s 8.3″ WiFi iPad minis for $100-$120 off MSRP, including free shipping, for a limited time. Prices start at $399. Amazon’s prices are among the lowest currently available for... Read more
Apple AirPods Pro with USB-C discounted to $1...
Walmart has Apple’s 2023 AirPods Pro with USB-C in stock and on sale for $199.99 on their online store. Their price is $50 off MSRP, and it’s currently one the lowest prices available for new AirPods... Read more
Apple has 14-inch M3 MacBook Pro with 16GB of...
Apple has 14″ M3 MacBook Pros with 16GB of RAM, Certified Refurbished, available for $270-$300 off MSRP. Each model features a new outer case, shipping is free, and an Apple 1-year warranty is... Read more
Save $318-$432 on 16-inch M3 Max MacBook Pros...
Apple retailer Expercom has 16″ M3 Max MacBook Pros on sale for $318-$432 off MSRP when bundled with a 3-year AppleCare+ Protection Plan. Discounts are available for Silver models as well a Space... Read more
New today at Apple: 16-inch M3 Pro/M3 Max Mac...
Apple is now offering 16″ M3 Pro and M3 Max MacBook Pros, Certified Refurbished, starting at $2119 and ranging up to $530 off MSRP. Each model features a new outer case, shipping is free, and an... Read more
Apple is now offering $300-$480 discounts on...
Apple is now offering 14″ M3 Pro and M3 Max MacBook Pros, Certified Refurbished, starting at $1699 and ranging up to $480 off MSRP. Each model features a new outer case, shipping is free, and an... Read more

Jobs Board

Part-time *Apple* and Peach Research Assist...
…and minimum qualifications: + Assist with planting, pruning, and harvesting of apple and peach trees + Conduct regular maintenance tasks to ensure optimal Read more
Housekeeper, *Apple* Valley Villa - Cassia...
Apple Valley Villa, part of a senior living community, is hiring entry-level Full-Time Housekeepers to join our team! We will train you for this position and offer a Read more
Sublease Associate Optometrist- *Apple* Val...
Sublease Associate Optometrist- Apple Valley, CA- Target Optical Date: Feb 22, 2024 Brand: Target Optical Location: Apple Valley, CA, US, 92307 **Requisition Read more
Sublease Associate Optometrist- *Apple* Val...
Sublease Associate Optometrist- Apple Valley, CA- Target Optical Date: Jan 24, 2024 Brand: Target Optical Location: Apple Valley, CA, US, 92307 **Requisition Read more
Housekeeper, *Apple* Valley Village - Cassi...
Apple Valley Village Health Care Center, a senior care campus, is hiring a Part-Time Housekeeper to join our team! We will train you for this position! In this role, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.