TweetFollow Us on Twitter

Charting Resource Map
Volume Number:6
Issue Number:9
Column Tag:XCMD Corner

Related Info: Resource Manager

Charting The Resource Map

By Donald Koscheka, Ernst & Young, MacTutor Contributing Editor

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

Fourth Party Developers

If you read this column regularly, you may be a charter member of a new class of programmers that Apple has recently labelled as “Fourth party developers”. This term is used to denote those programmers who add or modify an existing package for a customer. By this token, XCMDs are 4th party programs since you are adding code to an off-the-shelf product (Hypercard) to enhance its capabilities.

4th Party Programming seems to be an interesting way to make a living. First off, the assignments are manageable since most 4th party work tends to be minor additions to existing work. Second, the 4th party developer needs to be a master of all trades. Gone are the days when a programmer could specialize in data base design, or system software or report generation.

If 4th party programming becomes commercially viable, the practitioner will need to be well-versed in many areas but it’s a safe bet that you can focus your expertise on the following: I/O, communications, searching, sorting, report generation, file translators and graphics. The problem is, most programmers don’t have a repertoire that spans this wide a spectrum. If you feel equally comfortable talking LAP as you do discussing the TIFF format, then maybe you should try your hand at becoming a 4th party programmer.

Personally, I think this area can turn out to be very interesting. I remain skeptical as to whether anyone can make a living at it, but I’m willing to consider anything. After all, the most far-fetched ideas are often the ones that lead to innovation.

End of Sermon.

Charting The Resource Map

Although I’ve read just about every page of Inside Macintosh at least twice, there are certain pages that I still find myself glossing over. I don’t skip these pages out of lack of interest, every manager in the Toolbox has some interesting nuance that is just begging to be exploited. I gloss over certain sections of IM solely because I know that reading that section will lead me down a long path that I just never seem to have time for.

One such path for me is decoding the format of the resource fork. I have always looked on pages I-128 through 1-131 as a sort of black hole; the resource forks just seemed too convoluted to ever have to try to understand. Besides, anything one needs to do with the resource fork can be done via the high level resource manager calls. Or so it would seem. But here’s a simple request that cannot be resolved by the resource manager -- give me a list of the type and id of all resources in a particular resource file.

One needs to understand the spirit of the resource manager in order to understand why this seemingly simple problem doesn’t have a simple solution. The resource manager was intended to act as what I call “soft virtual EPROM”. In essence, resources should only be created during the construction of an application. Once the product ships, the resource fork should remain stable. This is exactly how Engineers use EPROM in computer designs. The “soft” nature of resources alludes to the fact that resources are easy to change as one might need to do to internationalize a certain package. This does not mean that the resource fork should be used for storing dynamically altering data. The resource manager is NOT a data base. A lot of early Mac programmers abused the resource fork by using it as a simple sort of data base. The RM doesn’t respond well to constantly changing data -- it is relatively slow for writing and it lacks any inherent compaction scheme. Neither of these are a shortcoming, the resource fork was never meant to be used as a random access data base. Any programmer who uses the resource fork in this way is asking for trouble and is building an inherently unstable program -- if you have data base needs, either buy or develop a data base, but please, keep your paws out of the resource fork.

The next attribute of the resource fork that is significant is its “virtual” nature. The resource manager has a built-in mechanism for searching all open resource files for a given resource. This is good -- it frees the programmer from needing to know how to access the system resources, they just magically appear along with your resources at load time. Of course there is nothing magical about the resource manager develops this virtual behaviour, each file contains a resource map that is loaded into memory when the resource fork is opened. Each resource map stores a handle to the next resource map in the search order. Thus searching all open resource forks becomes straightforward. But herein lies the crux of our problem. The resource manager itself wants to search all open resource files. If we want to get a list of all resources stored in a particular file, then we would first have to close down all open resource files so that they are excluded from the search path. This would be bad and not even worth trying because shutting down your system resource fork and application resource fork would almost certainly be fatal to the application.

Thus, to read all resources from one particular resource file, we are forced to scan the resource map for that file. Listing 1 (GetRsrcList.c) returns a list of all resources by type and id (names will be added in the future, you can use the resource manager to get the name for now). Notice that in order to do this, I needed to reconstruct the structures used in the resource file. I couldn’t find these structures in my libraries so I create my own.

Our strategy for scanning the resource file goes like this (refer to page I-131 for a good picture of this strategy). First, we read in the resource header (256 bytes). The resource header contains, among other things, the offset and length of the resource map. I find it noteworthy that the resource map always follows the resource data in the file. This seems reasonable enough. Since we know how big the resource map is, allocate a pointer that contains enough space to read the map into, then move the file mark to the start of the map and read it in. Once the map is read in, we need to move through two levels: the type list and the reference list. The type list immediately follows the map header and tells us how many types of resources the fork contains as well as the resource type (4 bytes), the number of resources of that type and where the reference list starts for that type. Type lists and reference lists are constant-sized structures so we can increment a pointer to sashay nicely through the lists.

Each resource type contains a reference list. This list holds information about each individual resource. There are as many entries as there are resources of a given type (counting from 0 not 1). If your file contains 4 XCMDs then your XCMD reference list will contain 4 contiguous entries, one for each XCMD. Pascal programmers take note -- the count is stored as 1 less than the actual number of items. We walk the reference list thusly:

/* 1 */

 for( i = 0; i <= rTL->r_count; i++ ){
 rRef = (resRefPtr)((long)rTL + (long)rTyp->r_ref );
 for( j = 0; j <= rTyp->r_count; j++ )
 rRef++;

 rTyp++; 
 }

The outer loop (i) walks through the type list (again these are stored contiguously immediately following the the resource map header). If rTyp is a pointer to a type list entry (an 8-byte struct), then all we need to do to move to the next type is increment the pointer. “C” is a natural for this type of work but the equivalent Pascal code looks like this:

/* 2 */

 rTyp = ResTypPtr( ORD4( rTyp ) + LongInt( sizeof( ResTyp) );
       { rTyp++ }

Each type entry contains the offset to the start of the reference list for this type. This offset is relative to the start of the type list itself. Adding this offset to the start of the type list (rTL in the example above) yields the physical location of the reference list. Each resource in the file has a reference list entry. To scan all resources of a given type (eg ‘XCMD’) we can increment the pointer to the reference list entries (rRef).

You may never need to know how to scan a resource map but it does serve two pedantic purposes -- it shows how resource files are created and it absolutely convinces the serious programmer that the resource fork is not intended to be a data base. The 16-bit offsets used throughout the fork should provide some clue as to the limitations on the fork’s capacity. For example, what is the maximum number of resource types that you can have? What is the total number of resources that can be stored safely in the resource fork? Listing 1 provides clues to the answers (hint: study the structures). Understanding limits is an important part of programming. See what you can do with this information.

The resource manager is fun to poke around in and I will visit this theme in the future. In the meantime, if you have an interesting problem that needs solving in an XCMD, drop me a line. I’ll see what I can do.

Listing 1:  GetRsrcList.c

/********************************/
/* File: GetRsrcList.c    */
/* */
/* Given the name of a file,  */
/* return a list of all the */
/* resources in that file.  The */
/* list contains 1 line per */
/* resource with the following  */
/* format:*/
/* */
/* item1 == Resource Type */
/* item2 == Resource ID   */
/* item3 == Resource name */
/* */
/* If the resource fork is empty*/
/* or non-existent, return empty*/
/* */
/* ----------------------------  */
/* ©1990 Donald Koscheka  */
/* All Rights Reserved    */
/********************************/

#define UsingHypercard

#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

/*** definition of resource header ***/
typedef struct {
 long r_data_offset;
 long r_map_offset;
 long r_data_size;
 long r_map_size;
 char r_reserved[112];
 char r_application[128];
} resHdr, *resHdrPtr, **resHdrHand;

/*** definition of resource map ***/
typedef struct {
 long   r_header[4];/* duplicates first 16 bytes in header*/
 long   next_map;
 short  f_ref;
 short  attributes;
 short  r_type_list;
 short  r_name_list;
} resMap, *resMapPtr, **resMapHand;

/*** definition of type list entry ***/
typedef struct {
 char   r_type[4]; /*** this resource type   ***/
 short  r_count; /*** # of resources of this type ***/
 short  r_ref;   
 /*** offset from start of type list to***/
 /*** reference list for resources of  ***/
 /*** this type (not used here)    ***/
} resTyp, *resTypPtr, **resTypHand;

/*** definition of resource type list ***/
typedef struct {
 short  r_count; /* 0..n */
 resTyp r_typ[]; /* array of type entries */
} resTypeList, *resTypeListPtr, **resTypeListHand;

/*** definition of resource reference list ***/
typedef struct {
 short  r_id;    
 short  r_name;  
 /* offset from start of name list to this name */
 long r_offset;  /* offset to date (hi byte == attributes */
 Handle r_handle;/* handle when resource is in memory */
} resRef, *resRefPtr, **resRefHand;

pascal void main( paramPtr )
 XCmdBlockPtr  paramPtr;
{
 resMapPtrrMap = NIL;
 resTypeListPtr  rTL;
 resTypPtrrTyp;
 resRefPtrrRef;
 Handle rsrcList = NIL; /* the output*/
 resHdr rHdr;
 Str31  fName;   /* name of the file */
 short  ref;
 OSErr  err;
 long   temp;
 short  i,j;/* loop counters*/
 Str255 str;
 
 paramPtr->returnValue = NIL; /* prepare for the worst */
 /* (but plan for the best) */
 
 if( paramPtr->params[0] ){

 HLock( paramPtr->params[0] );
 ZeroToPas( paramPtr, *(paramPtr->params[0]), &fName );
 HUnlock( paramPtr->params[0] );

 err  = (short)OpenRF( &fName, -1, &ref );

 if( !err ) /*** Move to  start of  file & read header ***/
 err = SetFPos( ref, fsFromStart, 0L );
 else
 return;
 
 if( !err ){/*** read in the resource header ***/
 temp = (long)sizeof( resHdr );
 err = FSRead( ref, &temp, &rHdr );
 }
 
 if( !err ) /*** Move to start of map & read it in ***/
 err = SetFPos( ref, fsFromStart, rHdr.r_map_offset );
 
 if( !err ){
 rMap = (resMapPtr)NewPtr( rHdr.r_map_size );
 err = FSRead( ref, &rHdr.r_map_size, rMap);
 }
 
 if( !err ){
 /*** this calculation doesn’t seem correct ***/
 rTL = (resTypeListPtr)((long)rMap + (long)(rMap->r_type_list));

 /*** move to the start of the reference list ***/
 rTyp = (resTypPtr)((long)rTL + (long)sizeof( short )); 
 
 /* Allocate handle for the output list*/
 if( rsrcList = NewHandle( 0L ) ){
 for( i = 0; i <= rTL->r_count; i++ ){
 rRef = (resRefPtr)((long)rTL + (long)rTyp->r_ref );
 for( j = 0; j <= rTyp->r_count; j++ ){
 /*** read the reference list entry int ***/
 
 /*** add this type & id to the output list ***/
 AppendCharToHandle( rsrcList, (char)rTyp->r_type[0]);
 AppendCharToHandle( rsrcList, (char)rTyp->r_type[1]);
 AppendCharToHandle( rsrcList, (char)rTyp->r_type[2]);
 AppendCharToHandle( rsrcList, (char)rTyp->r_type[3]);
 AppendCharToHandle( rsrcList, ‘,’);
 
 /*** convert id to a string & add to list ***/
 NumToStr( paramPtr, (long)rRef->r_id, &str );
 pStrToField( (char *)str, ‘\r’,  rsrcList );
 rRef++;
 }/* for j = 0 to # of resources of this type */
 rTyp++; 
 }/* for i = 0 to the number of resource types */
 
 }/* if( rsrcList allocated */
 
 AppendCharToHandle( rsrcList, ‘\0’ );
 } 
 
 if( rMap )
 DisposPtr( (Ptr)rMap );
 /*** Only reach here if file was opened     ***/
 err = FSClose( ref );
 }
 
 paramPtr->returnValue = rsrcList;
}

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

How to be a star in Britney Spears: Amer...
If you've ever wanted to be a star, baby, then you've probably already checked out Britney Spears: American Dream and are happily making your way up the charts. But fame doesn't come easy, and everyone needs a helping hand sometimes. So we've got... | Read more »
AppSpy is hiring a part time Staff Write...
| Read more »
How to save lives in ER Surgery Simulato...
A serious earthquake has struck a nearby town in ER Surgery Simulator - Emergency Doctor, and it’s up to you to save the victims. [Read more] | Read more »
Tips and tricks to get a high score in G...
Ketchapp Games loves the endless runner genre. And its newest game, Gravity Switch, is no exception. Gravity Switch takes a fresh approach, though, as you move a block, suspended in zero gravity, safely through a maze of shifting pillars. If the... | Read more »
Tips and tricks to get a high score in S...
Smash Fu is a high-paced tile-tapping game that requires quick reflexes and some practice. You’ll have to smash bricks with the skill of a seasoned black belt to get a high score. To raise the stakes a bit, you’ll also have to avoid tapping any... | Read more »
How to keep the ball rolling in Dropple
If you're new to the minimalist puzzler Dropple, you may find yourself struggling to make it beyond the first couple of steps before your ball falls into the endless abyss below. [Read more] | Read more »
How not to die in Traffic Rider
Traffic Rider, an Out Run-esque game in which your ride a motorcycle recklessly into trffic, might not seem particularly complicated. [Read more] | Read more »
How to adjust your chess game for Regici...
At first glance you might likenWarhammer 40,000: Regicide to Chess - and you'd be right. Regicideputs its own spin on the classic board game though, so some of your tried and true methods may not work quite so well here. [Read more] | Read more »
Rush Rally 2 (Games)
Rush Rally 2 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: -- Rush Rally 2 is the most authentic and thrilling rally simulation on your mobile, all running at an astounding 60fps. Console... | Read more »
Warhammer 40000: Regicide (Games)
Warhammer 40000: Regicide 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: ++NOTE: Optimized for with iPad Air, iPad mini 2, iPhone 5 and up. ++ "“This game has no right to be as good as it... | Read more »

Price Scanner via MacPrices.net

Textkraft Professional Becomes A Mobile Produ...
The new update 4.1 of Textkraft Professional for the iPad comes with many new and updated features that will be particularly of interest to self-publishers of e-books. Highlights include import and... Read more
SnipNotes 2.0 – Intelligent note-taking for i...
Indie software developer Felix Lisczyk has announced the release and immediate availability of SnipNotes 2.0, the next major version of his productivity app for iOS devices and Apple Watch.... Read more
Pitch Clock – The Entrepreneur’s Wingman Laun...
Grand Rapids, Michigan based Skunk Tank has announced the release and immediate availability of Pitch Clock – The Entrepreneur’s Wingman 1.1, the company’s new business app available exclusively on... Read more
13-inch 2.9GHz Retina MacBook Pro on sale for...
B&H Photo has the 13″ 2.9GHz Retina MacBook Pro (model #MF841LL/A) on sale for $1599 including free shipping plus NY tax only. Their price is $200 off MSRP. Amazon also has the 13″ 3.9GHz Retina... Read more
Apple price trackers, updated continuously
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: - 15″... Read more
Clearance 12-inch Retina MacBooks available s...
B&H Photo has dropped prices on leftover 2015 12″ Retina MacBooks with models now available starting at $999. Shipping is free, and B&H charges NY tax only: - 12″ 1.1GHz Gray Retina MacBook... Read more
Check Apple prices on any device with the iTr...
MacPrices is proud to offer readers a free iOS app (iPhones, iPads, & iPod touch) and Android app (Google Play and Amazon App Store) called iTracx, which allows you to glance at today’s lowest... Read more
New 2016 13-inch 256GB MacBook Air on sale fo...
B&H Photo has the new 13″ 1.6GHz/256GB MacBook Air (model MMGG2LL/A) on sale for $1149 including free shipping plus NY sales tax only. Their price is $50 off MSRP. Amazon has the 13″ 1.6GHz/256GB... Read more
Apple refurbished iPad Air 2s available start...
Apple has Certified Refurbished iPad Air 2 available starting at $339. Apple’s one-year warranty is included with each model, and shipping is free: - 128GB Wi-Fi iPad Air 2: $499 - 64GB Wi-Fi iPad... Read more
Accenture and Vatican Opera Romana Pellegrina...
Accenture has announced that the official mobile application for the Extraordinary Jubilee Year of Mercy declared by Pope Francis has been built and launched by Accenture Mobility, part of Accenture... Read more

Jobs Board

ISCS *Apple* ID Site Support Engineer - APP...
…position, we are looking for an individual who has experience supporting customers with Apple ID issues and enjoys this area of support. This person should be Read more
Automotive Sales Consultant - Apple Ford Linc...
…you. The best candidates are smart, technologically savvy and are customer focused. Apple Ford Lincoln Apple Valley is different, because: $30,000 annual salary Read more
*Apple* Support Technician II - Worldventure...
…global, fast growing member based travel company, is currently sourcing for an Apple Support Technician II to be based in our Plano headquarters. WorldVentures is Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Editor, *Apple* News - APPLE (United States...
Job Summary The Apple News team is looking for a passionate...a news organization. Description * Program Top Stories in Apple News * Post on Apple News Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.