Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Reading Resources Into Memory

RGetResource

You can use the RGetResource function to get resource data for a resource and include ROM-resident system resources in the Resource Manager's search of resource maps.

FUNCTION RGetResource (theType: ResType; theID: Integer): Handle;

theType

A resource type.

theID

An integer that uniquely identifies a resource of the specified type.

DESCRIPTION

The RGetResource function searches the resource maps in memory for the resource specified by the parameters theType and theID. The resource maps in memory, which represent all open resource forks, are arranged as a linked list. The RGetResource function first uses GetResource to search this list. The GetResource function starts with the current resource file and progresses through the list in order (that is, in reverse chronological order in which the resource forks were opened) until it finds the resource's entry in one of the resource maps. If GetResource doesn't find the specified resource in its search of the resource maps of open resource forks (which includes the System file's resource fork), RGetResource sets the global variable RomMapInsert to TRUE, then calls GetResource again. In response, GetResource performs the same search, but this time it looks in the resource map of the ROM-resident resources before searching the resource map of the System file.

If RGetResource finds the specified resource entry in one of the resource maps and the entry contains a valid handle, the function returns that handle. If the entry contains a handle whose value is NIL, and if you haven't called SetResLoad with the load parameter set to FALSE, RGetResource attempts to read the resource into memory.

If it can't find the resource data, RGetResource returns NIL, and ResError returns the result code resNotFound. The RGetResource function also returns NIL if the resource data to be read into memory won't fit, in which case ResError returns an appropriate Memory Manager result code. If you call RGetResource with a resource type that can't be found in any of the resource maps of the open resource forks, the function returns NIL, but ResError returns the result code noErr. You should always check that the value of the returned handle is not NIL.

SPECIAL CONSIDERATIONS

The RGetResource function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

RESULT CODES

noErr	0	No error
resNotFound	-192	Resource not found

SEE ALSO

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

For more information, see "Inserting the ROM Resource Map" beginning on page 1-128.

For a description of the UseResFile procedure, see page 1-65. The SetResLoad procedure is described next.