Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Getting and Setting the Current Resource File

UseResFile

You can use the UseResFile procedure to set the current resource file.

PROCEDURE UseResFile (refNum: Integer);

refNum

The file reference number for a resource fork.

DESCRIPTION

The UseResFile procedure searches the list of files whose resource forks have been opened for the file specified by the refNum parameter. If the specified file is found, the Resource Manager sets the current resource file to the specified file. If there's no resource fork open for a file with that reference number, UseResFile does nothing. To set the current resource file to the System file, use 0 for the refNum parameter.

Open resource forks are arranged as a linked list with the most recently opened resource fork at the beginning. When searching open resource forks, the Resource Manager starts with the most recently opened file. You can call the UseResFile procedure to set the current resource file to a file opened earlier, and thereby start subsequent searches with the specified file. In this way, you can cause any files higher in the resource chain to be left out of subsequent searches.

When a new resource fork is opened, this action overrides previous calls to UseResFile and the entire list is searched. For example, if five resource forks are opened in the order R0, R1, R2, R3, and R4, the search order is R4-R3-R2-R1-R0. Calling UseResFile(R2) changes the search order to R2-R1-R0; R4 and R3 are not searched. When the resource fork of a new file (R5) is opened, the search order becomes R5-R4-R3-R2-R1-R0.

You typically call CurResFile to get and save the current resource file, UseResFile to set the current resource file to the desired file, then (after you are finished using the resource) UseResFile to restore the current resource file to its previous value. Calling UseResFile(0) causes the Resource Manager to search only the System file's resource map. This is useful if you no longer wish to override a system resource with one by the same name in your application's resource fork.

SPECIAL CONSIDERATIONS

The FSpOpenResFile, HOpenResFile, and OpenResFile functions, which also set the current resource file, override previous calls to UseResFile.

ASSEMBLY-LANGUAGE INFORMATION

The settings of the system global variables RomMapInsert and TmpResLoad affect resource search order. These global variables determine whether the Resource Manager searches ROM-resident resources before the System file's resources.

The Resource Manager normally searches ROM resources only when you use the RGetResource function to get a handle to the resource, and even then only after it searches the System file's resource fork. To search for a resource in ROM before searching the System file's resource fork, your application must first alter the resource search order by inserting the ROM resource map in front of the System file's resource map.

When the value of the system global variable RomMapInsert is TRUE, the Resource Manager inserts the ROM resource map before the System file's resource map for the next call only (including any Resource Manager routine that gets a resource, not just RGetResource). When the value of RomMapInsert is TRUE, the adjacent variable TmpResLoad determines whether the value of the global variable ResLoad is considered TRUE or FALSE, overriding the actual value of ResLoad for the next call only. The values of the RomMapInsert and TmpResLoad variables are cleared after each call to a Resource Manager routine.

You can use two global constants to set these variables in tandem. Set the system global variable RomMapInsert to the global constant mapTrue to insert the ROM resource map with SetResLoad(TRUE). Set the system global variable RomMapInsert to the global constant mapFalse to insert the ROM resource map with SetResLoad(FALSE).

RESULT CODES

noErr	0	No error
resFNotFound	-193	Resource file not found

SEE ALSO

To check for errors, call the ResError function as described on page 1-47.

For an example of the use of the UseResFile procedure, see Listing 1-8 on page 1-23.

For descriptions of the FSpOpenResFile, HOpenResFile, and OpenResFile functions, see page 1-54 through page 1-62. For a description of the SetResLoad procedure, see page 1-74.