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

Is there cross-platform play in slither....
So you've sunken plenty of hours into crawling around in slither.io on your iPhone or iPad. You've got your stories of tragedy and triumph, the times you coiled four snakes at one time balanced out by the others when you had a length of more than... | Read more »
Rodeo Stampede guide to running a better...
In Rodeo Stampede, honing your skills so you can jump from animal to animal and outrun the herd as long as possible is only half the fun. Once you've tamed a few animals, you can bring them home with you. [Read more] | Read more »
VoxSyn (Music)
VoxSyn 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: VoxSyn turns your voice into the most flexible vocal sound generator ever. Instantly following even subtle modulations of pitch and... | Read more »
Catch Battleplans on Google Play from Ju...
Real-time strategy title Battleplans is due for release on Google Play on June 30th, following its release for iOS systems last month. With its simple interface and pretty graphics, the crowd-pleaser brings a formerly overlooked genre out for the... | Read more »
iDoyle: The interactive Adventures of Sh...
iDoyle: The interactive Adventures of Sherlock Holmes - A Scandal in Bohemia 1.0 Device: iOS Universal Category: Books Price: $1.99, Version: 1.0 (iTunes) Description: Special Release Price $1.99 (Normally $3.99) | Read more »
Five popular free apps to help you slim...
Thanks to retail and advertising, we're used to thinking one season ahead. Here we are just a week into the summer and we're conditioned to start thinking about the fall. [Read more] | Read more »
How to ride longer and tame more animals...
It's hard to accurately describe Rodeo Stampede to people who haven't seen it yet. It's like if someone took Crossy Roadand Disco Zoo and put them in a blender, yet with a unique game mechanic that's still simple and fun for anyone. [Read more] | Read more »
Teeny Titans - A Teen Titans Go! Figure...
Teeny Titans - A Teen Titans Go! Figure Battling Game 1.0.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.0 (iTunes) Description: Teeny Titans, GO! Join Robin for a figure battling RPG of epic proportions! TEENY... | Read more »
NinjAwesome: Tips and tricks to be a mor...
Sorry about that headline, but I'm going to go ahead and assume that GameResort would not have named its game NinjAwesome without expecting some of that. It is, in fact, pretty awesome the way it combines an endless runner and old school arcade... | Read more »
Into Mirror (Games)
Into Mirror 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: "Is all that we see or seem, but a dream within a dream?"- Edgar Allan Poe New game by Lemon Jam Studio, the team behind Pursuit... | Read more »

Price Scanner via MacPrices.net

Research and Markets Releases iPhone 6s Plus...
A new analysis report from Dublin-based Research and Markets observes that with the iPhone 6s Plus, Apple introduced a new rear camera module. The new device has similar structure and technology than... Read more
Apple refurbished Retina MacBook Pros availab...
Apple has Certified Refurbished 2015 13″ and 15″ Retina MacBook Pros available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free... Read more
Apple refurbished 11-inch MacBook Airs availa...
Apple has Certified Refurbished 11″ MacBook Airs (the latest models), available for up to $170 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... 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
12-inch 32GB and 128GB WiFi iPad Pros on sale...
B&H Photo has 12″ 32GB & 128GB WiFi iPad Pros on sale for up to $80 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 12″ Space Gray 32GB WiFi iPad Pro: $749 $50... Read more
6-core Mac Pro available for $3799, save $200
B&H Photo has the 6-core 3.5GHz Mac Pro on sale for $200 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.5GHz 6-core Mac Pro (sku MD878LL/A): $3799.99, $200 off MSRP Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1179 $120 off MSRP - 13″ 2.7GHz/... Read more
Apple refurbished Mac minis available for up...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
13-inch 2.5GHz MacBook Pro on sale for $999,...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more

Jobs Board

*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* Retail - Multiple Positions, Towson...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
Music Marketing Lead, iTunes & *Apple*...
…Music Marketing Lead is responsible for developing robust marketing campaigns and programs for Apple Music and iTunes across the whole of Apple ecosystem. This Read more
*Apple* Valley Medical Clinic is Hiring - AP...
Apple Valley Medical Clinic is Hiring! Apple Valley Medical Clinic is an independently owned practice operating a Family Medicine Clinic, a 24/7 Urgent Care, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.