Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 1 - Resource Manager / Resource Manager Reference

Resource Manager Routines / Getting and Setting Resource Information

SetResAttrs

You can use the SetResAttrs procedure to change a resource's attributes in the resource map in memory.

PROCEDURE SetResAttrs (theResource: Handle; attrs: Integer);

theResource

A handle to a resource.

attrs

The resource attributes to set.

DESCRIPTION

Given a handle to a resource, SetResAttrs changes the resource attributes of the resource to those specified in the attrs parameter. The SetResAttrs procedure changes the information in the resource map in memory, not in the file on disk. The resProtected attribute changes immediately. Other attribute changes take effect the next time the specified resource is read into memory but are not made permanent until the Resource Manager updates the resource fork.

If the value of the parameter theResource isn't a valid handle to a resource, SetResAttrs does nothing, and the ResError function returns the result code resNotFound.

Each attribute is identified by a specific bit in the low-order byte of a word. If the bit corresponding to an attribute contains 1, then that attribute is set; if the bit contains 0, then that attribute is not set. You can use these constants to specify each attribute:

CONST
   resSysHeap     =  64;   {set if read into system heap}
   resPurgeable   =  32;   {set if purgeable}
   resLocked      =  16;   {set if locked}
   resProtected   =   8;   {set if protected}
   resPreload     =   4;   {set if to be preloaded}
   resChanged     =   2;   {set if to be written to resource fork}

The resSysHeap attribute determines whether the resource is read into your application's heap (resSysHeap attribute set to 0) or the system heap (resSysHeap attribute set to 1). You should set this bit to 0 for your application's resources. Note that if you do set the resSysHeap attribute to 1 and the resource is too large for the system heap, the bit is cleared and the resource is read into the application heap.

Set the resPurgeable attribute to 1 to make the resource purgeable; you can set it to 0 to make the resource nonpurgeable. However, do not use SetResAttrs to make a purgeable resource nonpurgeable.

Because a locked resource is nonrelocatable and nonpurgeable, the resLocked attribute overrides the resPurgeable attribute. If you set the resLocked attribute to 1, the resource is nonpurgeable regardless of whether or not you set resPurgeable. If you
set the resLocked attribute to 0, the resource is purgeable or nonpurgeable depending on the value of the resPurgeable attribute.

If you set the resProtected attribute to 1, your application can't use Resource Manager routines to change the resource ID or resource name, modify the resource contents, or remove the resource from its resource fork. If you set the resProtected attribute to 0, you remove this protection. Note that this attribute change takes effect immediately.

If you set the resPreload attribute to 1, the Resource Manager reads the resource's resource data into memory immediately after opening its resource fork. You can use this setting to make multiple resources available for your application as soon as possible, rather than reading each one into memory separately.

The resChanged attribute indicates whether or not the resource has been changed; do not use SetResAttrs to set the resChanged attribute. Be sure the attrs parameter passed to SetResAttrs doesn't change the current setting of this attribute. To determine the attribute's current setting, call the GetResAttrs function. To set
the resChanged attribute, call the ChangedResource procedure. Note
that the resChanged attribute is used only while the resource map is in memory. The resChanged attribute must be 0 in the resource fork on disk.

If you want the Resource Manager to write the modified resource map to disk after a subsequent call to UpdateResFile or when your application terminates, call the ChangedResource procedure after you call SetResAttrs.

WARNING

Do not use SetResAttrs to change a purgeable resource. If you make a purgeable resource nonpurgeable by setting the resPurgeable attribute with SetResAttrs, the resource doesn't become nonpurgeable until the next time the specified resource is read into memory. Thus, the resource might be purged while you're changing it.

SPECIAL CONSIDERATIONS

The SetResAttrs procedure does not return an error if you are setting the attributes of a resource in a resource file that has a read-only resource map. To find out whether this is the case, use GetResFileAttrs.

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 about resource attributes, see "The Resource Map" beginning on page 1-7.

For a description of the GetResFileAttrs function, see page 1-110. To mark a resource as changed, use the ChangedResource procedure, described next.