Executing SAVE Files

IDL SAVE files (created using the SAVE procedure) can contain one or more routines that have been packaged into a single binary file. SAVE files can also contain system or data variables.

Note: While IDL routines or data can be saved in a file with any extension, it is common to use the extension .sav for SAVE files. Using the .sav extension has two benefits: it makes it clear to another IDL user that the file contains IDL routines or data, and it allows IDL to locate routines with the same base name as the file in SAVE files located in IDL’s path.

This section describes various ways to restore files created with the SAVE procedure. In order of increasing complexity and flexibility, your options are:

• Using the IDL Virtual Machine to Run SAVE Files
• Executing SAVE Files in the IDL Workbench
• Executing SAVE Files From the Operating System
• Executing SAVE Files by Name
• Using RESTORE to Access SAVE Files
• Using the IDL_Savefile Object to Access SAVE Files

Using the IDL Virtual Machine to Run SAVE Files

Users without an IDL license can use the IDL Virtual Machine to access programs contained in SAVE files created in IDL version 6.0 or later.

Executing SAVE Files in the IDL Workbench

If you use the IDL Workbench File > Open menu item to select a SAVE file with the extension .sav, IDL will automatically restore the file, with the following results:

• If the SAVE file contains routines, the routines are restored and IDL attempts to run a routine with the same name as the .sav file.
• If the SAVE file contains data, the variables are restored in IDL’s $MAIN$ scope.

Similarly, if the SAVE file is included in an open project, double-clicking on the file in the Project Explorer view will restore the file’s contents as described above.

Executing SAVE Files From the Operating System

On Windows and Mac systems, you can execute or restore a SAVE file directly from the operating system’s file manager. Double-click on a file with the extension .sav in the Windows Explorer or Mac Finder.

If the SAVE file contains routines:

• If IDL is already running, the routines are restored and IDL attempts to run a routine with the same name as the .sav file.
• If IDL is not running, it launches in Virtual Machine mode, restores the routines and attempts to run a routine with the same name as the .sav file.

If the SAVE file contains data, the IDL Workbench launches automatically (if it is not already running) and the variables are restored in IDL’s $MAIN$ scope.

Executing SAVE Files by Name

You can execute a program stored in a SAVE file from the IDL command line by typing in the name of the routine if the file meets the following conditions:

• The SAVE file has the same base name as the routine you wish to run
• The SAVE file has the extension .sav
• The SAVE file is stored in a directory included in the !PATH system variable

Call the procedure with the same name as the .sav file to restore the program and execute it immediately using IDL’s automatic compilation mechanism. IDL will search the current directory then the path specified by !PATH for a .sav file with the name of the called routine and, if it finds the .sav file, it restores, compiles and executes it automatically.

For example, to restore and execute the draw_arrow routine contained in the file draw_arrow.sav (created in Example: A SAVE File of a Simple Routine), enter the following at the command line:

draw_arrow

IDL will search for a file named either draw_arrow.pro or draw_arrow.sav, beginning in the current working directory and then searching in each directory specified by !PATH. When it finds a file whose name matches (in this case, draw_arrow.sav), it will compile the routines in the file up to and including the routine whose name matches the filename. IDL then executes the routine with the matching name. See Automatic Compilation and Execution for additional details.

Using RESTORE to Access SAVE Files

Use the RESTORE procedure to explicitly restore the entire contents of a SAVE file that contains variable data or program files. Because calling a procedure with the same name as a SAVE file allows IDL to automatically find and restore the SAVE file, it isn’t always necessary to explicitly restore a .sav file using RESTORE. Cases in which you must use RESTORE include the following:

• When you are restoring a SAVE file containing variable data.
• When your SAVE file contains multiple routines, and you need to first call a routine that uses a different name than the .sav file. For example, if you have a SAVE file named routines.sav that contains the ARROW and BAR_PLOT procedures, you would need to restore routines.sav before calling ARROW or BAR_PLOT.

Using RESTORE is more powerful and flexible than relying on IDL’s rules for automatic compilation, for the following reasons:

• The restored SAVE file can contain IDL variable data
• If the restored SAVE file contains IDL routines, all routines contained in the file will be restored, and none will be executed
• The restored SAVE file can have any filename and extension
• The restored SAVE file can be located in any directory

For example, in Example: A SAVE File of a Simple Routine, we created two SAVE files: imagefile.sav and draw_arrow.sav. The imagefile.sav file contains image variable data. To restore the image data, enter the following at the IDL command line:

RESTORE, 'imagefile.sav'

IDL creates the variable image in the current scope using the saved variable data.

If the file you are attempting to restore is not located in your current working directory, you will need to specify a path to the file. RESTORE does not search for SAVE files in any other directory. For example, if draw_arrow.sav is located in myappdir, restore it using the following statement:

RESTORE, 'myappdir/draw_arrow.sav'

Using the IDL_Savefile Object to Access SAVE Files

You can use the IDL_Savefile object class to gain information about the contents of a SAVE file, and to selectively restore items from the save file. Once a routine has been restored via calls the IDL_Savefile object, you can execute it by typing its name at the IDL command prompt. For example, if an IDL program named myroutine is stored in myroutine.sav, which is located in a directory that is not in !PATH, entering the following at the IDL command line will restore the routine and execute it:

obj = OBJ_NEW('IDL_Savefile', 'path/myroutine.sav')

obj->RESTORE, 'myroutine'

myroutine

where path is the full path to the myroutine.sav file.