HFS Tree Climb
Volume Number: 5
Issue Number: 8
Column Tag: HyperChat™
XCMD Corner: HFS Tree Climbing
By Donald Koscheka, Arthur Young & Co., MacTutor Contributing Editor
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Hyper Lite
In keeping with the spirit of the summer season, this month’s XCMD is light and
easy. Not too long ago, I promised to provide an XCMD that, given the name and
directory id of a file, returned that file’s full pathname. Such a utility is eminently
useful in the current incantation of Hypercard.
Hypercard is fully capable of opening a file, reading and writing its contents and
then closing the file. Unfortunately, unless you know the full path name of the file,
you are limited to accessing files in Hypercard’s working directory.
One of the first published XCMDs was a little gem from Steve Maller of Apple
Computer Inc. that eliminates this MSDOS-compatible feature of Hypercard. Steve’s
FileName.p presents the user with the standard file package and returns the full
pathname of the file specified.
If you are a regular reader of this column, you’ll recall that I translated Steve’s
XCMD from pascal to “C”. You also know that my version lost something in the
translation. Rather than return a full pathname, GetFileName.c returns the file’s
name and working directory id. I felt this was more useful because the file’s name and
wdid open up access to most of the file manager calls for the XCMD programmer. Still,
if you want to continue to use Hypercard’s built-in file I/O, getfileName won’t be of
much use since it doesn’t return the full pathname required by hypercard.
Listing 1 (FullPathName.c) is a simple XCMD that accepts the filename and
working directory id as input and returns the fullpathname of the file as output.
As is often the case, this XCMD first converts the input data from c-string format
to pascal strings and numbers as needed. Note that the default return value will be the
name of the file that was passed in param[0].
A Review of HFS
As a rule, we don’t come into contact with full pathnames very often on the
Macintosh so the format may require a little explaining. If you want to explore the
Hierarchical File System in greater detail, take the time to read Chapter 19 of volume
IV of Inside Macintosh. If you don’t have volume IV handy, the following discussion will
get help you understand the code.
Devices that can store and retrieve data on the Macintosh are called “ volumes”.
Files are organized on volumes in folders. Folders can contain other folders yielding a
hierarchical or “Tree structure”. The order in which folders are stored in this tree
structure specify a path to any file that is contained in that folder.
The root of this tree is the volume name. If we stick a “:” onto the end of the
volume name, we have the beginning of a full pathname. In other words full pathnames
always start with the volume name. Each path in the pathname is delineated by the “:”.
Thus, Hd: folder:file specifies a valid pathname. The last item in the pathname is the
name of the file itself. The folder that holds this file is referred to by a unique
directory id. When the user selects a file using SFGetFile or SFPutFile, the file
manager returns the file’s name as well as the directory id. For historical purposes,
the directory id is stored in the vRefNum field of the reply record. This little tweak is
how Apple was able to make HFS backward compatible with the flat-file system.
Tree Climbing
The folder that contains the file represents the deepest node on the tree. The next
folder up the hierarchy is called the parent. Knowing the parent’s id, we can call
PBGetCatInfo to get its name as well as the directory id of its parent folder. We climb
the tree by continuously feeding a parent directory id into PBGetCatInfo until we detect
an error (no more folders on this path).
Tree climbing suggests recursion. The routine ClimbTree in Listing 1 calls
PBGetCatInfo to get information about the directory whose id was passed in. We kick it
off by first getting information about the folder that holds the file. This is the
directory whose id was returned in the reply record.
Each activation of climbTree uses the same catalog parameter block (cpb) which
was allocated in the stack frame of FullPathName. This is legal because the only
information that is unique to each activation is the directory id (passed as a parameter
in child) as well as a pointer to the string the PBGetCatInfo uses to store the folder’s
name. Each activation allocates memory for the name string and sets cpb’s ioNamePtr
field to point to its own copy of the string.
I allocate the string, folder_name, in the heap and point to it on the stack because
successful recursion dictates that one be mindful of the stack at all times. Even if
there is no danger of overflowing the stack, a little defensive programming goes a long
way.
A nice feature of the recursion is that we can build the string in forward order.
Although we walked the tree backwards, we don’t actually put the full pathname
together until we reach the root which is detected by discovering that it has no parent
folder. Once we reach the root, the stack unwinds in the order of
root->parent->child->filename.
The following script, working with GetFileName.c (See Mactutor Vol. 5 No. 6)
returns the full pathname of a file selected via standard dialog:
--1
on mouseup
put getfilenametoOpen() into it
if item 1 of it is not empty then
put Fullpathname(item 1 of it, item 2 of it) into it
end if
end mouseup
Because Hierarchical File System can’t handle pathnames longer than 256
characters, I limit the string returned by Fullpathname to 256 characters. If you
want to return the full path regardless of length, you can modify the concat routine in
“HyperUtils.c” to “grow” the output string on demand.
Listing: FullPathName.c
/********************************/
/* File: FullPathName.c */
/* Given the name and working */
/* directory of a file, walk the*/
/* directory tree to determine */