Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Reading Resources Into Memory

Get1NamedResource

You can use the Get1NamedResource function to get a named resource in the current resource file.

FUNCTION Get1NamedResource (theType: ResType; name: Str255)
                            : Handle;

theType

A resource type.

name

A name that uniquely identifies a resource of the specified type.

DESCRIPTION

The Get1NamedResource function searches the current resource file's resource map in memory for the resource specified by the parameters theType and name. If Get1NamedResource finds an entry for the resource in the current resource file's resource map 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, Get1NamedResource attempts to read the resource into memory.

If it can't find the resource data, Get1NamedResource returns NIL, and ResError returns the result code resNotFound. The Get1NamedResource 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 Get1NamedResource with a resource type that can't be found in the resource map of the current resource file, 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.

You can change the search order by calling the UseResFile procedure before Get1NamedResource.

SPECIAL CONSIDERATIONS

The Get1NamedResource 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.

To include ROM-resident system resources in the Resource Manager's search of the resource maps for open resource forks, use the RGetResource function, described next.

For information about the UseResFile and SetResLoad procedures, see page 1-65 and page 1-74, respectively.