Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support

Apple IIgs
#83:    Resource Manager Stuff

Revised by:    Dave "Eh?" Lyons                                September 1990
Written by:    Dave Lyons                                            May 1990

This Technical Note answers your miscellaneous Resource Manager questions.
Changes since July 1990:  Added note that LoadResource with SetResLoad(FALSE) 
can return lockErr, and added warning about adjusting the search depth.
_____________________________________________________________________________


What SetCurResourceFile Does

SetCurResourceFile is documented in Chapter 45 of the Apple IIgs Toolbox 
Reference, Volume 3 (see especially "Resource File Search Sequence" near the 
beginning of the chapter).

This explanation might make you think SetCurResourceFile rearranges the search 
path, but it does not; instead, it just makes searches start at a different 
place in the path.  SetCurResourceFile is useful for controlling what resource 
files are searched, not for changing the search order.


How the Toolbox Uses Resources as Templates

The toolbox uses several types of resources as templates for creating other 
objects.  Examples include rControlList, rControlTemplate, and rWindParam1.  
The toolbox automatically releases these resources from memory as soon as it 
is through with them, so there is no need to create your template resources 
with special purge levels in an effort to free more memory.  It is not a 
problem.


StartUpTools Opens Resource Forks Read-Only

When StartUpTools opens your application's resource fork, it opens it with 
read-only access.  If your application needs to make changes to the resources 
on disk, you need to close the fork and reopen it with read and write access.  
To close it, use GetCurResourceFile and CloseResourceFile; to reopen it, use 
LGetPathname2 and OpenResourceFile.



Calling StartUpTools From a Shell Application (File Type $B5, EXE)

StartUpTools tries to open the current application's resource fork.  It 
determines the pathname of the "current application" by examining prefix 9: 
and making a GET_NAME GS/OS call, but do not assume it will always construct 
the pathname this way.  If you call StartUpTools from a shell application and 
expect it to open your EXE file's resource fork, you will be disappointed.

If GS/OS has launched your application, life is good--usually, though, a shell 
has loaded your shell application directly, so GET_NAME returns the name of 
the shell instead of the name of your application file.

To open your shell file's resource fork, call ResourceStartUp, get the 
pathname by calling LGetPathname2 on your user ID, and pass the pathname to 
OpenResourceFile.


What's NIL in a Resource Map?

The resource maps for open resource files are kept in memory, and the 
structure is defined in chapter 45 of Apple IIgs Toolbox Reference, Volume 3.

The resHandle field of a resource reference record (ResRefRec) is defined as 
"Handle of resource in memory.  A NIL value indicates that the resource has 
not been loaded into memory."  In this case, NIL means that the middle two 
bytes of the four-byte field are zero.  In other words, a NIL entry in the 
resource map may have a non-zero value in the low-order byte.

LoadResource and SetResLoad(FALSE)

When you call LoadResource on a locked or fixed resource and SetResLoad is set 
to FALSE, you may get Memory Manager error $0204 (lockErr), because the 
Resource Manager tries to allocate a locked or fixed zero-length handle, which 
the Memory Manager does not permit.


Adjusting the Search Depth

If you wish to add some resource files to the beginning of a resource search 
path and adjust the depth so that the end point of the search is unchanged, 
it's tempting to use SetResourceFileDepth(0) to get the current depth, add 
one, and set this new depth with SetResourceFileDepth.

The problem is that the search depth is often -1 ($FFFF), meaning "search 
until the end of the chain."  If you add your adjustment to -1, you do not 
usually get the intended effect.  A solution is just to check for $FFFF and 
not adjust the depth in that case.


Further Reference
_____________________________________________________________________________
  o  Apple IIgs Toolbox Reference, Volume 3

