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."

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

FileZilla 3.27.0.1 - Fast and reliable F...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. Version 3.27.0.1: MSW: Add misssing file to .zip binary package... Read more
Spotify 1.0.59.395. - Stream music, crea...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
Sierra Cache Cleaner 11.0.6 - Clear cach...
Sierra Cache Cleaner is an award-winning general purpose tool for macOS X. SCC makes system maintenance simple with an easy point-and-click interface to many macOS X functions. Novice and expert... Read more
DiskCatalogMaker 7.1.2 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Live Home 3D Pro 3.1.2 - $69.99
Live Home 3D Pro, a successor of Live Interior 3D, is the powerful yet intuitive home design software that lets you build the house of your dreams right on your Mac. It has every feature of Live Home... Read more
Deeper 2.2.1 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
Pinegrow 3.04 - Mockup and design webpag...
Pinegrow (was Pinegrow Web Designer) is desktop app that lets you mockup and design webpages faster with multi-page editing, CSS and LESS styling, and smart components for Bootstrap, Foundation,... Read more
Deeper 2.2.1 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
Spotify 1.0.59.395. - Stream music, crea...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
FileZilla 3.27.0.1 - Fast and reliable F...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. Version 3.27.0.1: MSW: Add misssing file to .zip binary package... Read more

Latest Forum Discussions

See All

The best deals on the App Store this wee...
There are quite a few truly superb games on sale on the App Store this week. If you haven't played some of these, many of which are true classics, now's the time to jump on the bandwagon. Here are the deals you need to know about. [Read more] | Read more »
Realpolitiks Mobile (Games)
Realpolitiks Mobile 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: PLEASE NOTE: The game might not work properly on discontinued 1GB of RAM devices (iPhone 5s, iPhone 6, iPhone 6 Plus, iPad... | Read more »
Layton’s Mystery Journey (Games)
Layton’s Mystery Journey 1.0.0 Device: iOS Universal Category: Games Price: $15.99, Version: 1.0.0 (iTunes) Description: THE MUCH-LOVED LAYTON SERIES IS BACK WITH A 10TH ANNIVERSARY INSTALLMENT! Developed by LEVEL-5, LAYTON’S... | Read more »
Full Throttle Remastered (Games)
Full Throttle Remastered 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Originally released by LucasArts in 1995, Full Throttle is a classic graphic adventure game from industry legend Tim... | Read more »
Stunning shooter Morphite gets a new tra...
Morphite is officially landing on iOS in September. The game looks like the space shooter we've been needing on mobile, and we're going to see if it fits the bill quite shortly. The game's a collaborative effort between Blowfish Studios, We're Five... | Read more »
Layton's Mystery Journey arrives to...
As you might recall, Layton's Mystery Journey is headed to iOS and Android -- tomorrow! To celebrate the impending launch, Level-5's released a new trailer, complete with an adorable hamster. [Read more] | Read more »
Sidewords (Games)
Sidewords 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Grab a cup of coffee and relax with Sidewords. Sidewords is part logic puzzle, part word game, all original. No timers. No... | Read more »
Noodlecake Games' 'Leap On!...
Noodlecake Games is always good for some light-hearted arcade fun, and its latest project, Leap On! could carry on that tradition. It's a bit like high stakes tetherball in a way. Your job is to guide a cute little blob around a series of floating... | Read more »
RuneScape goes mobile later this year
Yes, RuneScape still exists. In fact, it's coming to iOS and Android in just a few short months. Jagex, creators of the hit fantasy MMORPG of yesteryear, is releasing RuneScape Mobile and Old School RuneScape for mobile devices, complete with... | Read more »
Crash of Cars wants you to capture the c...
Crash of Cars is going full on medieval in its latest update, introducing castles and all manner of new cars and skins fresh from the Dark Ages. The update introduces a new castle-themed map (complete with catapults) and a gladiator-style battle... | Read more »

Price Scanner via MacPrices.net

Save or Share
FotoJet Designer, is a simple but powerful new graphic design apps available on both Mac and Windows. With FotoJet Designer’s 900+ templates, thousands of resources, and powerful editing tools you... Read more
Logo Maker Shop iOS App Lets Businesses Get C...
A newly released app is designed to help business owners to get creative with their branding by designing their own logos. With more than 1,000 editable templates, Logo Maker Shop 1.0 provides the... Read more
Sale! New 15-inch MacBook Pros for up to $150...
Amazon has the new 2017 15″ MacBook Pros on sale for up to $150 off MSRP including free shipping: – 15″ 2.8GHz MacBook Pro Space Gray: $2249 $150 off MSRP – 15″ 2.89Hz MacBook Pro Space Gray: $2779 $... Read more
DEVONthink To Go 2.1.7 For iOS Brings Usabili...
DEVONtechnologies has updated DEVONthink To Go, the iOS companion to DEVONthink for Mac, with enhancements and bug fixes. Version 2.1.7 adds an option to clear the Global Inbox and makes the grid... Read more
15-inch 2.2GHz Retina MacBook Pro, Apple refu...
Apple has Certified Refurbished 2015 15″ 2.2GHz Retina MacBook Pros available for $1699. That’s $300 off MSRP, and it’s the lowest price available for a 15″ MacBook Pro. An Apple one-year warranty is... Read more
13-inch 2.3GHz Silver MacBook Pro on sale for...
B&H Photo has the new 2017 13″ 2.3GHz/256GB Silver MacBook Pro (MPXU2LL/A) on sale for $1399 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
Apple Tackles Distracted Driving With iOS 11...
One of the most important new features coming in iOS 11 is Do Not Disturb while driving, intended to help drivers stay more focused on the road. With Do Not Disturb while driving, your iPhone can... Read more
iMazing Mini for Mac: Free Automatic and Priv...
Geneva, Switzerland-based indie developer DigiDNA has released iMazing Mini, their free macOS utility designed to automatically back up iOS devices over any local Wi-Fi network. The app offers users... Read more
Clearance 2016 13-inch MacBook Airs, Apple re...
Apple dropped prices recently on Certified Refurbished 2016 13″ MacBook Airs, with models now available starting at $809. An Apple one-year warranty is included with each MacBook, and shipping is... Read more
9.7-inch 2017 iPads available for $299, save...
B&H Photo has 2017 9.7″ 32GB WiFi iPads on sale for $30 off MSRP for a limited time. Shipping is free, and pay sales tax in NY & NJ only: – 32GB iPad WiFi: $299, $30 off Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions - Apple...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Senior Payments Architect - *Apple* Pay - A...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
Manager, *Apple* Media Products - Apple Inc...
Job Summary The Apple Media Products Discovery, Fraud and Abuse team is responsible for protecting the integrity of Apple services. As a manager of the team, you Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.