Futurebasic/Language/Reference/def apndstr

From Wikibooks, open books for an open world
Jump to navigation Jump to search

DEF APNDSTR Statement[edit | edit source]

DEF APNDSTR[edit | edit source]

Statement[edit | edit source]

✔ Appearance ✔ Standard ✔ Console

Syntax[edit | edit source]

DEF APNDSTR(string$, STR#resourceHndl&)

Description[edit | edit source]

This statement adds the specified string$ to the end of the relocatable block specified by STR#resourceHndl&. STR#resourceHndl& should be a handle to an existing "STR#" resource, or a handle to a block which you intend to save as an STR# resource. To create a new, empty handle for use with DEF APNDSTR, you should create it like this:

myHandle& = FN NEWHANDLE _clear (2)

After you have added strings to the new handle, you can save it as a resource by calling the ADDRESOURCE routine (http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-64.html).

To get a handle to an existing "STR#" resource for use with DEF APNDSTR, you can use any of a variety of Resource Manager functions such as GETRESOURCE: http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-50.html.

Note[edit | edit source]

Never use DEF APNDSTR on a purgeable resource, unless you first call FN HNOPURGE (str#handle&) (http://developer.apple.com/documentation/mac/Memory/Memory-91.html) to (temporarily) make it unpurgeable. If you think the resource may have been purged before you had a chance to call FN HNOPURGE, then you should also CALL LOADRESOURCE (str#handle&) (http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-56.html) to make sure it's loaded into memory.

If you are using DEF APNDSTR to update an existing "STR#" resource, then use CALL CHANGEDRESOURCE (str#handle&) (http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-63.html) after using DEF APNDSTR, to cause your changes to be written to disk when the resource file is closed or updated.

DEF APNDSTR could cause a system error if heap memory is very low or very fragmented. You can use the MEM(_maxAvail) function periodically to de-fragment memory.

See Also[edit | edit source]

STR#; DEF REMOVESTR; "Resource Manager" chapter (http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-9.html) in Inside Macintosh: http://developer.apple.com/documentation/macos8/mac8.html, More Macintosh Toolbox: http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-2.html.