TweetFollow Us on Twitter

Resource Jargon

Volume Number: 13 (1997)
Issue Number: 2
Column Tag: Toolbox Techniques

The Language of Resources

By Chris Stasny

A common sense introduction to the Resource Manager

Say Again?

I discovered a new version of English when I worked the oil fields of Trinidad years ago. Part of this dialect's uniqueness was due to the influence of multiple cultures on the island - notable for its heavy and complex accent. Eventually, I learned how to respond to things like, "And me anudder spanner. Dees one's too slight." (He wanted a larger wrench.)

Some years later I discovered that the Macintosh contained its own rendition of English, where common terms were linked in new ways to form powerful commands. This is clearly demonstrated in Resource Manager calls. Terms like USERESFILE and SETRESATTRS turn out to be everything expected and more. This article will focus on some common resource handling operations. While our syntax will be that of FutureBASIC II, the toolbox calls are so easily recognizable that programmers of all linguistic persuasions should be able to follow along without difficulty.

Resource Files

We all know that our application's resource fork is open and available. Some of us understand that the System's resource file is also open and available. In real life, there are usually between twenty and a hundred resource files open at any given moment, on any given Mac. Remember all of those font files and sound files that you dumped into the System Folder?

The layers of resources are guided strictly by the order they were opened via commands like OPENRESFILE or OPENRFPERM. If you think of your Mac as an oil drum, the System file is thrown into the barrel first and always resides at the bottom. It is followed by a plethora of extensions and additions that come online during startup. We cannot change this order. When we open a resource file, it is always thrown on top. [There are some exceptions. Most notably, CTB tools are loaded below the System resources. -ed.]

Application Heaps

When an application is double-clicked into life, a divider is used to segment the barrel in such a way that the application's resources are isolated from those of other programs. This divider does not extend all the way to the bottom of the drum, where system resources remain pooled and available for all to use. This means that resource files opened by that application can look down upon both application and system resources without ever being aware of items (owned by other applications) on the other side of the divider. This segment of the barrel is known as the application heap.

The search pattern here is important. If we ask the Resource Manager for a chunk of bits, it will respond by searching the top levels of information in our application's quadrant of the barrel. Each failure forces it to submerge deeper into the drum until it eventually finds itself scanning the System resources at the bottom. It is not possible to change this order. At best, we can tell the Resource Manager to start at a deeper level and ignore some of the sludge that has floated to the top. We do this with CALL USERESFILE(resRef).

After USERESFILE, we have effectively chopped off the top portion of the barrel, and items opened after the target file become invisible to the system. This procedure, when improperly used, often sends a program into a death spiral. Our first mistake is to assume that the call somehow changes the order of resource files. This is impossible. Our second mistake is to assume that we can put things right by calling USERESFILE with the application's resource reference number. This is also a fantasy. Here is the only safe way to switch forks in mid stream:

origRes = FN CURRESFILE
CALL USERESFILE(resRef)

‘ Handle your file-specific resource operations here.

CALL USERESFILE(origRes)

Rules to Load By

Let's backtrack for a moment to re-examine the operations involved in opening a resource file. During this operation, the Resource Manager loads a map into memory that lists all of the blocks behind the doors of the newly opened file. If, during creation of that map, the Manager sees something that the programmer marked as "Pre-load," the information is actually moved from the disk into RAM. (The resource can be marked this way either by checking the appropriate box in ResEdit or Resourcerer, or by using SETRESATTRS.)

When we look for a resource with a statement like FN GETRESOURCE, we don't actually dig through RAM searching for our unique block. The Resource Manager scans the maps that are held in memory to see if an entry matches our needs. This entry must be the same resource type with the proper ID or name. Our Manager, clever fellow that he is, does not blindly load a resource when he locates the entry. He first checks to see if the resource has been previously loaded and, if so, returns a handle to the existing item.

Toolbox calls that obtain resource handles are governed by very specific rules. Normally, the resource is moved from disk to memory, but you can circumvent this in cases where you may wish to do something like record and list available resources. The following example records the names of all sound resources without actually loading them into memory.

DIM sndName$(100)

‘ Don't load - just look
CALL SETRESLOAD(_false)

‘ Get res count, but don't let it extend past
‘ the arbitrary limits of the string array.
theCount = FN COUNTRESOURCES(_"snd ")
if theCount > 100 then theCount = 100

‘ Get each resource handle and request 
‘ info on it.
FOR i = 1 TO theCount
 rHndl& = FN GETINDRESOURCE(_"snd ",i)
 CALL GETRESINFO(rHndl&,rID,rType&,rName$)
 sndName$(i) = rName$
NEXT

‘ Restore normal resource loading
CALL SETRESLOAD(_zTrue)

The example used COUNTRESOURCES and GETINDRESOURCE. These calls start at the top of the barrel and continue until they encounter the aging rusty steel at the bottom. (Don't forget, if USERESFILE was invoked, the top of the barrel may have been cut off, and our point of origin for the search may have started lower in the drum than expected.) We could have easily examined the resources that existed in one file to the exclusion of all others by switching to calls that contain "1" in their names. FN COUNT1RESOURCES would return the number of sound resources in the most recently designated file. FN GET1INDRESOURCE would retrieve the indexed resource only in that file.

Let's bring this all together in a routine that searches for sound resources in the System file.

DIM sndName$(100)
origRes = FN CURRESFILE

‘ Ignore anything above the System file.
CALL USERESFILE(0)
CALL SETRESLOAD(_false)

‘ We only want resources in the current file.
theCount = FN COUNT1RESOURCES(_"snd ")
if theCount > 100 then theCount = 100
FOR i = 1 TO theCount

‘ Get indexed resources only from the top file.
 rHndl& = FN GET1INDRESOURCE(_"snd ",i)
 CALL GETRESINFO(rHndl&,rID,rType&,rName$)
 sndName$(i) = rName$
NEXT
CALL SETRESLOAD(_zTrue)

‘ Put things back like we found them.
CALL USERESFILE(origRes)

We have now clearly established the limits of a resource operation. USERESFILE tells us where to start searching, and a "1" in the toolbox name tells us that we should stop after searching a single file. Absence of the "1" forces our search to extend to the deepest recesses of the drum.

Shared Responsibilities

In most cases resources are loaded into memory and used, rather than just being inventoried and listed. The conditions under which these items enter RAM is another perplexing methodology that begs for explanation. The complexity centers around the fact that the management of a resource becomes the shared responsibility of the Resource and Memory Managers.

The Resource Manager begins by examining a resource's attributes to see if it should be purgeable or locked, and allocates the correct memory through FN NEWHANDLE. It can even be loaded into the system heap instead of the application heap, so that it may be shared with other applications that can look downward from their side of the dividers and see it. You may recognize these attributes as check boxes in ResEdit dialogs that are labeled Purgeable, Lock, and System Heap.

Armed with attribute information, the Resource Manager asks the Memory Manager (politely, of course) for a block of memory that is purgeable (or not), locked (or not), or in the system or application heap. Information is moved into that block. This is (practically) the only time resource attributes are examined - when the resource is loaded. From this point forward, the Memory Manager is in charge of the block. Memory Manager calls like HLOCK and HNOPURGE are used to handle the item as it floats around in the heap.

There is one very important exception to this rule. Never use CALL DISPOSEHANDLE on a resource handle. The Memory Manager would carry out its assignment by throwing away the information contained in the handle, but the Resource Manager (who was diligently tracking the block on his own personal tiny clipboard) would be left with a firm grip on an indeterminate chunk of RAM. It's not a pretty sight.

Lock and Purge

To lock or not to lock. That is the question. Most of the time, when I am called upon to debug a particular resource operation, I see abuses that would be too embarrassing to discuss on a daytime talk show. We have a tendency to ignore the attributes set up by the programmer who created the resource in the first place. As with SETRESLOAD and USERESFILE, we need to remain conscious of the creator's intent as we manipulate these items.

Assume that your application has a large preference resource that is loaded at startup. If we lock this piece of information in place, we have locked up a big, otherwise usable piece of binary real estate. Making it non-purgeable would have a similar effect. It may be our intent to move the entire resource into a global record or to examine individual pieces and branch to other operations. Either way, this resource would be marked as purgeable by its creator, but must temporarily be held in memory. We do it like this:

rHndl& = FN GETRESOURCE(_"PREF",_myPrefID)
LONG IF rHndl&

 ‘ Record the status of the handle.
 hState = FN HGETSTATE(rHndl&)

 ‘ Make sure it stays in memory.
 OSErr = FN HNOPURGE(rHndl&)

 ‘ Handle resource operations here,
 ‘ then restore the handle to its original state.
 OSErr = FN HSETSTATE(rHndl&,hState)
END IF

Some toolbox routines handle purging without a programmer's assistance. Picture resources are among the most abused in all of Mac-dom. Take the following (really bad) example.

‘ Bad example! Don't try this at home.

DIM t,l,b,r

rHndl& = FN GETPICTURE(_myPictureID)
OSErr = FN HLOCK(rHndl&)
t;8 = [rHndl&]+_picFrame
CALL OFFSETRECT(t,-l, -t)
CALL DRAWPICTURE(rHndl&,t)
CALL DISPOSEHANDLE(rHndl&)

This example was so wretched that it was painful to type, but it represents the type of resource handling that is common in most programs. The first error was to lock the picture handle. If this picture was to be used often during the course of an application (as might be the case with a tool palette picture), its creator would have marked it as non-purgeable. In most cases, even the purgeable attribute would be turned off so that the picture could be expunged if required. Locking is generally a bad thing and would normally be done only on a temporary basis. (Remember HGETSTATE and HSETSTATE?) In our case, the HLOCK was unnecessary, since QuickDraw manages this particular resource during its operation, and undesirable since low-level picture operations may actually move or resize the picture resource.

Our next major mistake was to assume that the picture was loaded into memory. We immediately went to work on a resource handle without checking it for validity. Then, we disposed of the handle, which was being jointly tracked by the Resource Manager and the Memory Manager. Since DISPOSEHANDLE is a Memory Manager call, the Resource Manager was left out of the operation and is likely to cause serious damage when it next reaches for that resource.

Here's how we should have handled the operation.

  DIM t,l,b,r
 
  rHndl& = FN GETPICTURE(_myPictureID)
  LONG IF rHndl&
   t;8 = [rHndl&]+_picFrame
   CALL OFFSETRECT(t,-l, -t)
   CALL DRAWPICTURE(rHndl&,t)
  END IF

If this was a startup picture, it would probably never be needed again. The moment that the memory it occupied was required for some other operation, the picture would be purged from RAM. On the other hand, if the application's partition was large and the user's requirements small, it might remain in place for the duration.

Later, when the user decided to view the application's "About" box, we would use exactly the same routine to display the picture a second time. If plenty of space was available and the picture had managed to remain in memory, it would not be reloaded. A handle to the existing data would be returned from FN GETPICTURE. If constraints had forced the resource out of memory, it would be reloaded as a result of the call. This debugged example was more memory-efficient, and took fewer lines of code.

Handle Hand-off

While the ownership of resource handles seems to be preordained, we may still exercise control over who will ultimately own the handle. A call to DETACHRESOURCE does this. It pulls the resource's entry from a file's resource map. It does not remove the handle from memory or change the attributes of that handle. After this call, the Memory Manager controls the block, and the Resource Manager ceases to acknowledge its existence. If you wish to dispose of it, you'll have to use DISPOSEHANDLE.

While there is no call that completely releases a Memory Manager handle to the control of the Resource Manager, there is a procedure that turns a handle into a resource: ADDRESOURCE. This call takes a great deal of setup and is best documented in FN pGreplaceRes in the Runtime.INCL file of a Program Generator project. But there are some important rules that deserve attention. When a resource is added, it is added to the current resource file. Use CURRESFILE and USERESFILE to change this during such operations. Adding a resource is a blind operation that allows duplication. If you add a preference resource to your application three times, you'll end up with three copies of the resource in your file.

Slow Execution

Because most folks have a hard time understanding resources, there is a tendency to write out a resource every time it is modified. Apple engineers are no exception. Most of us remember the early days of the Macintosh 840AV. An uninformed ROM rat patched the toolbox call CHANGEDRESOURCE to make it call UPDATERESFILE each time it was called. This was a bad thing. Let me explain why.

When your program calls UPDATERESFILE or WRITERESOURCE, the entire file may be written to disk. Remember that resources are not really magical. They occupy space on a disk, and are ordered according to strict internal guidelines. If you replace a picture that is 50K with one that is 100K, there is no sorcerer's potion that compresses the new resource into the same space used by the old one. The file is simply rewritten, starting at the beginning of the old 50K resource.

When the AV's were first released, folks complained that resource handlers like ResEdit and Program Generator slowed to a crawl. This is because a simple operation (CHANGEDRESOURCE), which was supposed to set a single bit in a single flag, ended up rewriting the file. The reality is that it is almost never necessary to update the file or write its resources. This happens automatically when the file is closed.

There is one additional feature of CHANGEDRESOURCE that deserves attention: You should never call CHANGEDRESOURCE on a purgeable block. When the file is closed, the Resource Manager scans its list to see what has been modified. Then it rewrites the file with these new items in place. If, in the interim, the Memory Manager has purged the block, you will see random data written to the disk. If you have ever seen a file explode from a few hundred K to several megabytes, this is the likely reason. Mark resources in the following manner to prevent this problem.

OSErr = FN HNOPURGE(rHndl&)
CALL CHANGEDRESOURCE(rHndl&)

Conclusion

Our list of rules to live by grows ever more complex. In the olden days, we were just supposed to remember not to tug on Superman's cape or spit into the wind. Now we must watch resource attributes and referee a tenuous cease-fire between two headstrong Macintosh Managers. My friends from Trinidad might beg for simplicity. "And me anudder monager. Dees ones too complex."

 
AAPL
$116.31
Apple Inc.
+1.64
MSFT
$48.70
Microsoft Corpora
+0.48
GOOG
$534.83
Google Inc.
-2.16

MacTech Search:
Community Search:

Software Updates via MacUpdate

Herald 5.0.1 - Notification plugin for M...
Note: Versions 2.1.3 (for OS X 10.7), 3.0.6 (for OS X 10.8), and 4.0.8 (for OS X 10.9) are no longer supported by the developer. Herald is a notification plugin for Mail.app, Apple's Mac OS X email... Read more
Firetask 3.7 - Innovative task managemen...
Firetask uniquely combines the advantages of classical priority-and-due-date-based task management with GTD. Stay focused and on top of your commitments - Firetask's "Today" view shows all relevant... Read more
TechTool Pro 7.0.6 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
PhotoDesk 3.0.1 - Instagram client for p...
PhotoDesk lets you view, like, comment, and download Instagram pictures/videos! (NO Uploads! / Image Posting! Instagram forbids that! AND you *need* an *existing* Instagram account). But you can do... Read more
SuperDuper! 2.7.3 - Advanced disk clonin...
SuperDuper! is an advanced, yet easy to use disk copying program. It can, of course, make a straight copy, or "clone" -- useful when you want to move all your data from one machine to another, or do... Read more
MacJournal 6.1.5 - Create, maintain, and...
MacJournal is the world's most popular journaling software for the Mac. MacJournal 6 adds a calendar mode that show entries from any journal, geolocation, word count, and progress tracking, as well... Read more
Skim 1.4.10 - PDF Reader and note-taker...
Skim is a PDF reader and note-taker for OS X. It is designed to help you read and annotate scientific papers in PDF, but is also great for viewing any PDF file. Skim includes many features and has a... Read more
FontExplorer X Pro 4.2.2 - Font manageme...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
SoftRAID 5.0.5 - High-quality RAID manag...
SoftRAID allows you to create and manage disk arrays to increase performance and reliability. SoftRAID's intuitive interface and powerful feature set makes this utility a must have for any Mac OS X... Read more
DEVONthink Pro 2.8.2 - Knowledge base, i...
Save 10% with our exclusive coupon code: MACUPDATE10 DEVONthink Pro is your essential assistant for today's world, where almost everything is digital. From shopping receipts to important research... Read more

Latest Forum Discussions

See All

Weather or Not - Reports and Forecasts...
Weather or Not - Reports and Forecasts for your Calendar 1.0.0 Device: iOS iPhone Category: Weather Price: $2.99, Version: 1.0.0 (iTunes) Description: Weather or Not is a beautiful and intuitive way to check the weather and... | Read more »
Sago Mini Road Trip (Education)
Sago Mini Road Trip 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Go for a fun-filled drive with Jinja the cat. Pick a destination, select a vehicle and hit the road. What will Jinja... | Read more »
New Tower Defense Game, Kingdom Rush: Or...
New Tower Defense Game, Kingdom Rush: Origins, is Available Today Posted by Jessica Fisher on November 20th, 2014 [ permalink ] iPad Only App - Designed for the iPad | Read more »
Sunburn! (Games)
Sunburn! 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: Your ship is gone. Your crew is scattered. One option remains. Gather your crew... and jump into the sun. Reunite your... | Read more »
Tapventures Review
Tapventures Review By Jennifer Allen on November 20th, 2014 Our Rating: :: ODDLY COMPELLINGUniversal App - Designed for iPhone and iPad Tapventures is an increasingly hands-off one-tap RPG, but expect it to hook you despite your... | Read more »
Who Wore it Best? The Hunger Games: Girl...
With The Hunger Games: Mockingjay Part 1 out this weekend, Who Wore it Best? pits two Hunger Games tie-ins, Girl on Fire and Panem Run, against each other in a brutal and pointless fight to the death. I wonder where we got that idea from? | Read more »
Ironkill Review
Ironkill Review By Jennifer Allen on November 20th, 2014 Our Rating: :: LACKLUSTER PUNCHINGUniversal App - Designed for iPhone and iPad Ironkill is a freemium focused fighting game that doesn’t offer particularly thrilling fights... | Read more »
Real-Time Multiplayer Match-3 RPG Crusad...
Real-Time Multiplayer Match-3 RPG Crusaders Quest Set to Launch Next Month Posted by Ellis Spice on November 20th, 2014 [ permalink ] | Read more »
Checkpoint Champion Review
Checkpoint Champion Review By Jennifer Allen on November 20th, 2014 Our Rating: :: SPEEDY DRIFTINGUniversal App - Designed for iPhone and iPad Checkpoint Champion is a drift-focused racing game that’s ideal for short but fun gaming... | Read more »
MediaFire iOS 8 Native Update Brings New...
MediaFire iOS 8 Native Update Brings New “Power Upload” Feature to iPad and iPhone Posted by Jessica Fisher on November 20th, 2014 [ | Read more »

Price Scanner via MacPrices.net

64GB iPod touch on sale for $249, save $50
Best Buy has the 64GB iPod touch on sale for $249 on their online store for a limited time. Their price is $50 off MSRP. Choose free shipping or free local store pickup (if available). Sale price for... Read more
15″ 2.2GHz Retina MacBook Pro on sale for $17...
 B&H Photo has the 2014 15″ 2.2GHz Retina MacBook Pro on sale for $1799.99 for a limited time. Shipping is free, and B&H charges NY sales tax only. B&H will also include free copies of... Read more
New Logitech AnyAngle Case/Stand Brings Flexi...
Logitec has announced the newest addition to its suite of tablet products — the Logitech AnyAngle. A protective case with an any-angle stand for iPad Air 2 and all iPad mini models, AnyAngle is the... Read more
2013 15-inch 2.0GHz Retina MacBook Pro availa...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros available for $1499 including free shipping plus NY sales tax only. Their price is $500 off original MSRP. B&H will... Read more
16GB Retina iPad mini on sale today for $199,...
 Staples has 2nd generation 16GB Retina iPad minis on sale for $199 on their online store for a limited time. Their price is $100 off MSRP. Choose free shipping or free local store pickup (if... Read more
Developers Start Designing Apps for Apple Wat...
Apple has announced the availability of WatchKit, software that gives developers a set of tools to easily create experiences designed specifically for Apple Watch. Apple’s developer community can now... Read more
C Spire Launches iPad Air 2 and iPad Mini 3 o...
C Spire has announced that iPad Air 2 with Wi-Fi + Cellular and iPad mini 3 with Wi-Fi + Cellular are now available on its 4G LTE network. C Spire offers both new iPads with a range of data plans... Read more
Are You On Your Last PC? – The ‘Book Mystique
Will your current PC be your last? Quite possibly so if you define “personal computer” as a traditional desktop or laptop form factor machine according to some commentators. So then, the upshot that... Read more
Save up to $180 on MacBook Airs with Apple re...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
16GB iPad mini available for $219, save $30
Walmart has 16GB iPad minis (1st generation) available for $219 on their online store. Their price is $30 off MSRP. Choose free shipping or free store pickup (if available). Price for online orders... Read more

Jobs Board

*Apple* Solutions Consultant (ASC)- Retail S...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Store Leader Program - College Gradu...
Job Description: Job Summary As an Apple Store Leader Program agent, you can continue your education as you major in the art of leadership at the Apple Store. You'll Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.