The IDL_Savefile::Restore procedure method selectively restores individual items from the associated SAVE file.
Given the identifier for an item within the SAVE file, this method restores the item along with any additional items (such as structure definitions or heap variables) upon which the specified item depends. Use the IDL_Savefile::Names method to retrieve valid item identifiers.
By default, this method restores variables from the SAVE file; keywords can be used to restore items of other types.
See Notes on Restored Heap Variables regarding issues related to using this method to restore pointers or object references.
Syntax
Obj->[IDL_Savefile::]Restore, SaveItem [, /COMMON] [, /FUNCTION] [, NEW_HEAPVAR=variable] [, /NO_COMPILE] [, /OBJECT_HEAPVAR] [, /POINTER_HEAPVAR] [, /PROCEDURE] [, RESTORED_OBJECTS=variable] [, /STRUCTURE_DEFINITION] [, /VERBOSE]
Arguments
SaveItem
A scalar string or string array of identifiers for items to be restored from the SAVE file. Identifiers are retrieved from the SAVE file using the IDL_Savefile::Names method.
Note: If either the OBJECT_HEAPVAR keyword or the POINTER_HEAPVAR keyword is specified, SaveItem must be an integer or integer array.
Keywords
COMMON
Set this keyword to restore the main-level COMMON block definitions specified by SaveItem.
Note: To restore both a COMMON block definition and the variables it references, restore the definition first, then restore the variables.
FUNCTION
Set this keyword to restore the function(s) specified by SaveItem.
NEW_HEAPVAR
Set this keyword equal to a named variable that will contain valid references for heap variables.
Note: This keyword is only valid when either the OBJECT_HEAPVAR or the POINTER_HEAPVAR keyword is specified.
The returned variable will have the same structure as SaveItem, with each element in the returned array corresponding to the same element in the SaveItem array. If OBJECT_HEAPVAR is specified, the returned variable will contain an array of object references; if POINTER_HEAPVAR is specified, the returned variable will contain an array of pointers. See Notes on Restored Heap Variables for additional information on restoring heap variables.
NO_COMPILE
By default, when Restore encounters a structure variable or object reference, it automatically attempts to find a corresponding __define file (a .pro or .sav file in IDL’s path that contains the corresponding structure or class definition). If IDL finds a __define file, it compiles it automatically, before restoring the variable or object reference. Set the NO_COMPILE keyword to disable this automatic compilation behavior.
Automatic compilation of structure definitions is useful for object class definitions if you have defined the object methods within the same .pro or .sav file; compiling the __define file will also compile the class methods and make them available to the newly-restored variables.
Automatic compilation is also useful if the structure or class definition has changed since the SAVE file was created. Compiling the __define file will ensure that IDL caches the new structure definition first, before the variable is restored.
This keyword is ignored for SAVE files that contain code.
OBJECT_HEAPVAR
Set this keyword to restore the object heap variable(s) specified by SaveItem. To obtain valid references to the newly restored heap variables, you must also specify the NEW_HEAPVAR keyword. See Notes on Restored Heap Variables for additional information on restoring heap variables.
Note: Only heap variables whose save attribute is set to True (the default) will are saved. See HEAP_SAVE for additional details on save attributes.
POINTER_HEAPVAR
Set this keyword to restore the pointer heap variable(s) specified by SaveItem. To obtain valid references to the newly restored heap variables, you must also specify the NEW_HEAPVAR keyword. See Notes on Restored Heap Variables for additional information on restoring heap variables.
Note: Only heap variables whose save attribute is set to True (the default) will are saved. See HEAP_SAVE for additional details on save attributes.
PROCEDURE
Set this keyword to restore the procedure(s) specified by SaveItem.
RESTORED_OBJECTS
Set this keyword equal to a named variable that will contain an array of object references for any objects restored. The resulting list of objects is useful for programmatically calling the objects’ own restore methods (if any). If no objects are restored, the variable will contain a null object reference.
STRUCTURE_DEFINITION
Set this keyword to restore the named structure definition(s) specified by SaveItem. Named structure definitions are saved by IDL when a structure variable of that type is saved, and are restored when the variable is restored. The STRUCTURE_DEFINITION keyword allows you to restore just the definition, without the variable. This can be useful if you want to create a new variable of the same type, and have no use for the saved variable data.
VERBOSE
Set this keyword to print an informative message for each item restored.
Note: Messages are only printed for top-level named variables. Heap variable references returned by the NEW_HEAPVAR keyword will not generate individual messages.
Notes on Restored Heap Variables
IDL variables can contain object or pointer references to heap variables, and these heap variables can contain other such references, either to themselves or to other heap variables. There is no limit to the number of references that can be made to a given heap variable. This flexible design allows the construction of arbitrary data structures.
While the RESTORE procedure handles all details related to restoring heap variables in a way that is transparent to the IDL user, the IDL_Savefile::Restore method provides greater flexibility and thus requires greater care. When using the IDL_Savefile::Restore method to restore heap variables:
- An IDL_Savefile object will restore a given heap variable only once. This has implications for situations in which heap variables might be freed during the IDL_Savefile object’s lifetime. See Caution Regarding Restored Heap Variables for a complete discussion of this issue.
- The IDL_Savefile object makes it possible to restore a heap variable independently of any regular IDL variable that might refer to it. This feature is described in detail in Restoring Heap Variables Directly.
Understanding How Heap Variables are Restored
When the SAVE procedure saves variables that contain object or pointer references, the referenced heap variables are also saved. Internally, heap variables are represented by unique integers called heap identifiers, which are not generally accessible (or useful) to the IDL user. The unique integers used to identify heap variables are assigned by IDL when the variables are created, and are therefore only unique within that IDL session. A given heap variable will typically have completely different identifiers in two different IDL sessions.
When RESTORE later restores variables containing object or pointer references, the heap variables are likewise restored. Note, however, that the unique identifiers for the restored heap variables will be different from the identifiers they had in the IDL session in which the SAVE file was created. RESTORE handles the mapping of the old identifiers to the new ones internally, in a manner that is completely transparent to the IDL user. This allows the user to save and restore very complex data structures using the simple interface provided by the SAVE and RESTORE procedures.
Notice that when using SAVE and RESTORE, the user always deals with regular named variables. Heap variables are never explicitly saved or restored; they are referenced only indirectly, through the regular variables that refer to them. Working with restored heap variables directly would be inconvenient, because heap variables lack mnemonic names that allow for easy identification, and because the original integer identifiers assigned by IDL when the heap variables were created have no meaning in the IDL session into which the variables are restored.
The IDL_Savefile::Restore method duplicates the behavior of the RESTORE procedure with regard to heap variables. That is, when a regular IDL variable that refers to a pointer or object heap variable is restored, the heap variable is also restored automatically. In addition, although it is rarely (if ever) useful, the IDL_Savefile::Restore method provides the ability to restore heap variables without restoring the IDL variables that refer to them. To accomplish this, the IDL_Savefile object allows you to retrieve the integer heap identifiers stored in the SAVE file, using the POINTER_HEAPVAR and OBJECT_HEAPVAR keywords to the Names method. Note that it would be incorrect to treat these identifiers as object or pointer references, because they are not valid references in the restoring IDL session. For this reason, they are reported as simple integer values. They have no special meaning outside of that given to them by the IDL_Savefile object for a given object instance.
Note: Restoring heap variables independently of regular variables is not recommended; the mechanism is provided only for completeness. See Restoring Heap Variables Directly, for additional information.
Caution Regarding Restored Heap Variables
A given instance of an IDL_Savefile object will never restore a given pointer or object heap variable more than once, regardless of the number of pointers or object references that refer to that heap variable. While this reflects the expected behavior of pointers and object references. References to the same underlying quantity should all point to the same heap variable; you must take care in situations in which heap variables can be destroyed during the lifetime of the IDL_Savefile object.
To make the implications of this behavior clear, consider an example in which a SAVE file contains two variables, A and B, each of which is a pointer reference to the same underlying pointer heap variable. After instantiating an IDL_Savefile object named obj that refers to the SAVE file, execute the following IDL commands:
obj->RESTORE, 'a'
PTR_FREE, a
obj->RESTORE, 'b'
The result is that both restored variables A and B are dangling references to a non-existent heap variable. IDL does not re-create the heap variable when B is restored, because the IDL_Savefile object knows that it already restored it once. The process of freeing the heap variable using the PTR_FREE procedure does not influence the behavior of the IDL_Savefile object; as far as the savefile object is concerned, the heap variable referred to by the variable B has already been restored, and should not be restored again.
Tip: To force IDL to create multiple instances of a single saved heap variable, you can create multiple instances of the IDL_Savefile object referring to the same SAVE file, and use each one to create a distinct and separate instance of the heap variable. We caution you that this sort of code can become confusing very quickly.
Restoring Heap Variables Directly
The IDL_Savefile object is designed to provide a way to query and restore anything contained within a SAVE file. As a result, the savefile object provides a mechanism for restoring heap variables independently of any regular IDL variables that may refer to them.
Note: The ability to directly restore heap variables independently of any referring regular variable is provided for completeness only. Restoring heap variables directly as described in this section is rarely (if ever) useful. The recommended way to restore a heap variable is to restore a regular IDL variable that refers to the heap variable.
To restore a heap variable independently of any regular variable, do the following:
- Use either the POINTER_HEAPVAR or the OBJECT_HEAPVAR keyword (as appropriate) to the IDL_Savefile::Names method to retrieve the integer heap identifier of the heap variable.
- Use either the POINTER_HEAPVAR or the OBJECT_HEAPVAR keyword (as appropriate) and the NEW_HEAPVAR keyword to the IDL_Savefile::Restore method to associate the restored heap variable with a new regular variable.
The following IDL code provides an example of how this might look:
myPtr = PTR_NEW('99.00')
SAVE, myPtr, FILE='ptr.sav'
.FULL_RESET_SESSION
sObj = OBJ_NEW('IDL_Savefile', 'ptr.sav')
ptrName = sObj->Names(/POINTER_HEAPVAR)
sObj->Restore, ptrName[0], /POINTER_HEAPVAR, NEW_HEAPVAR=myNewPtr
PRINT, *myNewPtr
IDL Prints:
99.00
Tip: The above example is presented to depict the process of restoring a heap variable directly. It would have been much easier to restore the myPtr variable contained in the SAVE file.
Example
See Example for an example that restores variable data.
Version History
|
6.1 |
Introduced |
|
8.0 |
Added NO_COMPILE keyword
|