Sector Dumps
Volume Number: 5
Issue Number: 7
Column Tag: HyperChat™
XCMD Corner: Sector Dumps 
By Donald Koscheka, Arthur Young & Company, MacTutor Contributing
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Reinventing the wheel often provides an opportunity to embellish on the original
design. Recently, I needed a file dump utility. Several packages are available “over the
counter”, but I needed a utility that dumps the entire file without having to manually
move from sector to sector as is the case with most commercial solutions. Moreover,
I use file dump tools frequently enough that I could afford to spend the effort writing
one for Hypercard.
I dump the file in a fairly typical way. Each line in the dump contains the “sector
address” of the first byte on the line followed by the hexadecimal dump of 16 bytes
followed by the ASCII interpretation of the data. Not all ASCII characters are
“printable” so we replace non-printing characters with the “.”, yielding a cleaner
display.
This month’s XFCN, FilePeek.c (listing 1) accepts two parameters. The first
parameter is the reference number of the opened file; the second parameter is the
sector you want dumped. HFS sectors are 512 bytes so filepeek returns 32 lines of 16
bytes apiece.
Dumping the entire contents of a file becomes a matter of calling FilePeek
repeatedly for all the logical sectors in the file.
The first line in the dump tells us how many bytes were read in. This number
can be equal to or less than a full sector. If line 1 contains less than a sector full of
data, then you know that logical end of file is after the last byte read in.
The Hypertalk afficianado will realize that this code can easily be written in
Hypertalk. I chose to commit my scheme to an XFCN only after discovering that the
Hypertalk version was too slow for my purposes.
The dumping scheme is amazingly simple. Position the file mark at the beginning
of the sector that you want to dump. If the start of the sector extends beyond end of
file, do nothing and return to hypercard with a result of zero (no bytes were read in),
otherwise read the sector into the buffer we allocated (buf).
The sector is presented to Hypercard as a series of haxadecimal characters.
Hypercard contains a call back “NumtoHex” which converts an arbitrary run of data to
a hex string. We lose portability when using a callback so you’ll need to write your
own hexdump algorithm or dig one up in the toolbox.
FilePeek dumps two bytes at a time (4 hex digits). This is analogous to dumping
the contents of a short. We can use a pointer to short (rPtr). To dump the ascii data,
we use a char pointer (cPtr) to the same data.
The current line in the dump is assembled by first displaying the “sector
address” of that line. The sector address is 512 * blk (blk = sector number).
The sector address is delineated by the “:” character. Following the sector
address, we display 16 bytes of data in hexadecimal format. The data is grouped into 8
words.
The hexadecimal data is followed by the ascii representation of the line. If the
character falls in the range of printing characters, we display the character,
otherwise print a “.”. Characters below the space (0x020) are not normally
considered printing characters. Likewise, Inside Macintosh indicates that no
characters above $D8 have a printable format. Using the period to represent
non-printing characters results in a less-cluttered looking dump.
We need to cycle the character pointer, cPtr, twice for every cycle on rPtr (a
character is half a word). We accumulate the ascii data into a separate string which we
then concatenate onto the end of the hex data.
Once the current line is assembled, we stick a carriage return on the end, block
move it to the output data handle and then go to the next 16 bytes in the input stream.
When the outer loop completes, outdata will contain 32 lines of 16 bytes apiece,
suitable for framing.
Figure 1.
How you open and close a file from Hypercard is a matter of taste. I prefer to
keep my interface to the file manager as clean as possible. This requires passing a
filename and working directory id to the file manager’s FSOpen call and subsequently
referring to the file by the reference number returned by FSOpen. To close the file,
pass the reference number to FSClose (last month I provided an XFCN that will return
a file name and working directory id from the standard file package).
Listings 2 and 3 are two simple XFCNs that open and close a file respectively.
FileOpen returns a reference number if the file opened ok (0 otherwise). Pass this
reference number to FilePeek along with the number of the sector you wish to dump.
Figure 1. is a sample card that I use to dump the contents of the file. The dump is
presented in a mono-spaced font to keep it “clean-looking”. The forward and back
arrows allow the user to “browse” sectors by moving 1 sector forward or backward.
The scripts for theses two buttons is fairly obvious so I’ve left them to the reader. The
scripts for open, close are contained in listing 4.
--1
-- file open button
on mouseUp
global fileName, DirectoryID
global fileRefNum, theSector
put getFileNameToOpen() into it
put item 1 of it into fileName
put item 2 of it into DirectoryID
put filename into card field “file name”
if filename is not empty then
Put FileOpen( fileName, DirectoryID ) into fileRefNum
end if
end mouseUp
-- Go to Sector
on mouseUp
global fileRefNum, theSector
if filerefnum is empty then
answer “You have to open a file first, silly!”
else
ask “Read what sector?” with “0”
if (it is not empty) then
put it into theSector
Peekat theSector
end if
end if
end mouseUp
-- file close
on mouseUp
global fileRefNum
put FileClose( fileRefNum ) into it
-- ignore the result of a closed file
end mouseUp
Listing 4. Scripts for the buttons
An interesting variation on this theme would be to dump the files in reverse order so
that it prints in ascending order on the LaserWriter. Several easy solutions exist for
this problem, and I’ll leave it as this month’s exercise to the reader. As a hint, I can
think of two ways to do this off hand, one easy but inefficient, the second a little more
challenging: (1) create a card for every sector (make sure your file is small first!) or
(2) Find out how many sectors the file contains before starting the dump ( a wonderful
opportunity to try your hand at XFCN writing).
Note on a bug in last month’s article:
Last month’s XFCN, GetFileName, incorrectly returns the working directory id of the
file selected from SFGetFile. Change the call to GetFileNameToOpen to Read:
/* 1 */
if( GetFileNameToOpen(typs,numTypes,FileName,&FileWDID ) ){
temp = (long)FileWDID & 0xFFFF;
NumToStr( paramPtr, temp, &WDIDString );
PtoCstr( WDIDString );
Listing 1: FilePeek.c
/********************************/
/* File: FilePeek.c */
/* */
/* Given the sector index into */
/* an existing file, read the */
/* sector in and “dump” it to */
/* the screen */
/* */
/* Paramters: */
/* param0 = file reference num */
/* ( file is open ) */
/* param1 = sector number */
/* (1 sector = 512 bytes) */
/* ---------------------------- */
/* To Build: */
/* */
/* (1) Create a project using */
/* this file as well as the */
/* XCMD.Glue.c file. (Set */
/* project type to XCMD (or */
/* XFCN) from the Project menu. */
/* */
/* (2) Bring the project up to */
/* date. */
/* */
/* (3) Build Code Resource. */
/* */
/* (4) Use ResEdit to copy the */
/* resource to your stack. */
/********************************/
#include