The HEAP_SAVE function is used to query whether a pointer or object heap variable is savable. It can also be used to change the heap variable save attribute.

Every pointer and object heap variable has a save attribute, which is either set (True) or not set (False). This attribute determines whether the SAVE procedure will write the contents of the heap variable to a save file or not. When SAVE encounters a pointer or object reference, it checks the save attribute of the referenced heap variable and does one of the following:

  1. If the save attribute is True (the default), it saves the referenced heap variable, and it recursively follows any pointer or object references the heap variable might contain to find any other heap variables it should also save.
  2. If the save attribute is False, it does not save the referenced heap variable, and it does not follow any pointers or object references the heap variable might contain.

Later, when RESTORE or an IDL_SAVEFILE object is used to restore the pointer or object reference from the save file, one of the following will occur:

  1. If the heap variable’s save attribute is set, RESTORE will create a new heap variable containing the data from the saved heap variable, and the pointer or object reference will be set to refer to the new heap variable.
  2. If the heap variable’s save attribute is not set, the save file does not contain data for the heap variable. The heap variable is therefore not restored, and the pointer or object reference will be set to NULL.

IDL creates heap variables with their save attribute set to True by default; this is appropriate for the vast majority of IDL applications. Clearing the save attribute is not a very common operation, but there are situations in which it can be useful. For example, an object might use a pointer to hold data that it computes at runtime. Such data might be large, it might be subject to frequent change as the object state changes, or it might be easily recomputed. Rather than saving such data, you might choose to clear the save attribute so that the data won’t be saved. When the pointer or object is restored it will be set to NULL, and the application can recompute the data as necessary.

Syntax

Result = HEAP_SAVE(HeapVar [, Set])

Return Value

Returns the value of the save attribute(s) of the heap variables referenced by HeapVar, as they exist when HEAP_SAVE is called, and before the Set parameter (if present) is applied. The result is of type byte, and has the same structure as HeapVar, with each element set to 1 (True) if the save attribute of the corresponding heap variable is set, and 0 (False) otherwise.

Arguments

HeapVar

A pointer, object reference, or array of pointers or object references to be processed.

Set

A scalar value that is used to modify the save attributes of the heap variables referenced by HeapVar. Set this argument to 0 (zero) to clear the save attributes, or to a non-zero value to set the save attributes. If the Set argument is not present, HEAP_SAVE does not alter the save attributes.

Note: The HEAP_NOSAVE procedure provides a shorthand method of clearing the save attributes of heap variables.

Version History

6.2

Introduced

See Also

HEAP_NOSAVE