RESTORE

The RESTORE procedure restores the IDL variables and routines saved in a file by the SAVE procedure.

RESTORE provides a very simple interface that restores the entire contents of the specified SAVE file in a single atomic operation. To query the contents of a SAVE file without first restoring the data, or if you want to restore only selected items, use the interface provided by the IDL_Savefile object class instead.

While files containing IDL data variables can be restored by any version of IDL that supports those data types, files containing IDL routines and system variables can only be restored by the same or later versions of IDL. Therefore, you should always archive your IDL language source files (.PRO files) in case you need to recompile your code in an earlier version of IDL. See Version Compatibility of SAVE Files for details.

Tips:

Beginning with IDL 8.8.1, the List and Hash classes were ported from PRO code to C code for performance. Restoring a save file from previous versions of IDL will replace those definitions, destabilizing IDL. Use the SAVEFILE_CLEANUP routine to purge the ported routines from your save file to avoid this. Calling RESTORE with the /VERBOSE keyword will list all the symbols being restored, to help identify which save file needs to be cleaned up.
Beginning with IDL 7.1, double-clicking on a SAVE file that has the extension .sav and contains IDL variables will automatically start the IDL Workbench (if it is not already running) and restore the contained variables. Double-clicking on SAVE files that contain routines (again, with the .sav extension) will execute the contained routines in IDL, launching IDL in Virtual Machine mode if it is not already running.

Examples

Suppose that you have saved all the variables from a previous IDL session with the command:

SAVE, /VARIABLES, FILENAME = 'session1.sav'

If the file session1.sav is located in your current working directory, the variable associated with the file can be restored by entering:

RESTORE, 'session1.sav'

Note: To restore a file that is not in your current working directory, you must specify the file path.

Syntax

RESTORE [[, Filename] | [, FILENAME=name]] [, DESCRIPTION=variable] [, /NO_COMPILE] [, /RELAXED_STRUCTURE_ASSIGNMENT] [, RESTORED_OBJECTS=variable] [, /SKIP_EXISTING] [, /VERBOSE]

Arguments

Filename

A scalar string that contains the name of the SAVE file to be restored. If Filename is not an absolute path name, it is considered to be relative to the current working directory. If neither the Filename argument or the FILENAME keyword are present, IDL attempts to restore a file named idlsave.dat in the current working directory.

Keywords

DESCRIPTION

Set this keyword equal to a named variable that will contain the user-supplied description string for the specified save file. If no description was provided when the save file was created (via the DESCRIPTION keyword to the SAVEroutine), the variable specified by this keyword will contain an empty string.

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.

Note: If the structure or class definition has changed since the SAVE file was created, you should also set the RELAXED_STRUCTURE_ASSIGNMENT keyword.

This keyword is ignored for SAVE files that contain code.

FILENAME

This keyword serves exactly the same purpose as the Filename argument—only one of them needs to be provided. If both the Filename argument and the FILENAME keyword are provided, the file specified by the Filename argument is restored.

RELAXED_STRUCTURE_ASSIGNMENT

Normally, RESTORE is unable to restore a structure variable if the definition of its type has changed since the SAVE file was written. A common case where this occurs is when objects are saved and the class structure of the objects change before they are restored in another IDL session. In such cases, RESTORE issues an error, skips the structure, and continues restoring the remainder of the SAVE file.

Setting the RELAXED_STRUCTURE_ASSIGNMENT keyword causes RESTORE to restore such incompatible values using “relaxed structure assignment,” in which all possible data are restored using a field-by-field copy. (See the description of the STRUCT_ASSIGN procedure for additional details.)

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’ restore methods. If no objects are restored, the variable will contain a null object reference.

SKIP_EXISTING

By default, when restoring routines from a SAVE file, if a routine is already compiled in IDL, the routine from the SAVE file replaces the existing code. If you set /SKIP_EXISTING, then any routines in the SAVE file that are already compiled are quietly ignored.

Tip: This keyword is useful if you have a SAVE file from an older version of IDL, and you do not want the old routines within the file to replace your currently-compiled "new" routines.

VERBOSE

Set this keyword to have IDL print an informative message for each restored object.

Version History

Original	Introduced
6.1	Added DESCRIPTION keyword
8.0	Added automatic compilation when a structure variable or object reference has a corresponding `_define` file. Must use NO_COMPILE keyword to disable this automatic behavior. Added NO_COMPILE keyword
8.5.2	Added SKIP_EXISTING keyword