This section describes various ways to restore files created with the SAVE procedure. In order of increasing complexity and flexibility, your options are:
.savextension, compile one or more routines contained therein, and execute the specified routine. See Automatic Restoration, Compilation, and Execution.
These options are described in more detail below.
To restore, compile, and execute routines contained in a SAVE file that uses the extension
.sav and which contains an IDL routine with the same base name as the file, simply call the routine using its name. IDL will search for a file whose name matches the requested routine, then restore, compile, and execute the routine as described in Automatic Compilation.
For example, to restore and execute the
draw_arrow routine contained in the file
draw_arrow.sav (created in Example: Create a SAVE File of a Simple Routine), enter the following at the command line:
IDL will search for a file named either
draw_arrow.sav, beginning in the current working directory and then searching in each directory specified by
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.
Use the RESTORE procedure to explicitly restore the entire contents of a SAVE file. Using RESTORE is more powerful and flexible that relying on IDL's rules for automatic compilation, for the following reasons:
For example, in Example: Create a SAVE File of a Simple Routine, we created two SAVE files:
imagefile.sav file contains image variable data. To restore the image data, enter the following at the IDL command line:
IDL creates the variable image in the current scope using the saved variable data.
The IDL_Savefile object provides an object-oriented interface that allows you to query a SAVE file for information and restore one or more individual items from the file. Using IDL_Savefile, you can retrieve information about the user, machine, and system that created the SAVE file, as well as the number and size of the various items contained in the file (variables, common blocks, routines, etc). Individual items can be selectively restored from the SAVE file.
Use IDL_Savefile in preference to the RESTORE procedure when you need to obtain detailed information on the items contained within a SAVE file without first restoring it, or when you wish to restore only selected items. Use RESTORE when you want to restore everything from the SAVE file using a simple interface.
To use the IDL_Savefile object to restore items from an existing SAVE file, do the following:
The following sections describe each of these steps. For complete information on the IDL_Savefile object and its methods, see IDL_Savefile.
When an IDL_Savefile object is instantiated, it opens the actual SAVE file for reading and creates an in-memory representation of its contents - without actually restoring the file. The savefile object persists until it is explicitly destroyed (or until the IDL session ends); the SAVE file itself is held open for reading as long as the savefile object exists.
To create a savefile object from the
draw_arrow.sav file created in Example: Create a SAVE File of a Simple Routine, use the following command:
myRoutines = OBJ_NEW('IDL_Savefile', 'draw_arrow.sav')
Similarly, to create a savefile object from the saved image data, use the following command:
myImage = OBJ_NEW('IDL_Savefile', 'imagefile.sav')
Once you have created a savefile object, three methods allow you to retrieve information about its contents:
The Contents method returns a structure variable that describes the SAVE file and its contents. The individual fields in the returned structure are described in detail in IDL_Savefile::Contents.
In addition to providing information about the system that created the SAVE file, the Contents method allows you to determine the number of each type of saved item (variable, procedure, function, etc.) in the file. This information can be used to programmatically restore items from the SAVE file.
Assuming you have created the
myRoutines savefile object, the data returned by the Contents method looks like this:
savefileInfo = myRoutines->Contents() HELP, savefileInfo, /STRUCTURE
** Structure IDL_SAVEFILE_CONTENTS, 17 tags, length=176, data length=172: FILENAME STRING '/rsi/test/draw_arrow.sav' DESCRIPTION STRING '' FILETYPE STRING 'Portable (XDR)' USER STRING 'dquixote' HOST STRING 'DULCINEA' DATE STRING 'Thu May 08 12:04:46 2003' ARCH STRING 'x86' OS STRING 'Win32' RELEASE STRING '6.1' N_COMMON LONG64 0 N_VAR LONG64 0 N_SYSVAR LONG64 0 N_PROCEDURE LONG64 2 N_FUNCTION LONG64 0 N_OBJECT_HEAPVAR LONG64 0 N_POINTER_HEAPVAR LONG64 0 N_STRUCTDEF LONG64 0
From this you can determine the name of the SAVE file from which the information was extracted, the names of the user and computer who created the file, the creation date, and information about the IDL system that created the file. You can also see that the SAVE file contains definitions for two procedures and nothing else.
The Names method returns a string array containing the names of the variables, procedures, functions, or other items contained in the SAVE file. By default, the method returns the names of variables; keywords allow you to specify that names of other items should be retrieved. The available keyword options are described in IDL_Savefile::Names.
The names of items retrieved using the Names method can be supplied to the Size method to retrieve size and type information about the specific items, or to the Restore method to restore individual items.
For example, calling the Names method with the PROCEDURE keyword on the
myRoutines savefile object yields the names of the two procedures saved in the file:
Similarly, to retrieve the name of the variable saved in
imagefile.sav, which is referred to by the
myImage savefile object:
The Size method returns the same information about a variable stored in a SAVE file as the SIZE function does about a regular IDL variable. It accepts the same keywords as the SIZE function, and returns the same information using the same formats. The Size method differs only in that the argument is a string or integer identifier string (returned by the Names method) that specifies an item within a SAVE file, rather than an in-memory expression. See IDL_Savefile::Size for additional details.
For example, to determine the dimensions of the image stored in the
imagefile.sav file, do the following:
imagesize = myImage->Size('image', /DIMENSIONS) PRINT, 'Image X size:', imagesize PRINT, 'Image Y size:', imagesize
Image X size: 256 Image Y size: 256
The Restore method allows you to selectively restore one or more items from the SAVE file associated with a savefile object. Items to be restored are specified using the item name strings returned by the Names method. In addition to functions, procedures, and variables, you can also restore COMMON block definitions, structure definitions, and heap variables. See IDL_Savefile::Restore for additional details.
For example, to restore the DRAW_ARROW procedure without restoring the ARROW procedure, do the following:
Object references and pointers rely on special IDL variables called heap variables. When you restore a regular IDL variable that contains an object reference or a pointer, the associated heap variable is restored automatically; there is no need to restore the heap variables separately. It is, however, possible to restore the heap variables independently of any regular IDL variables; see Restoring Heap Variables Directly for complete details.
To destroy a savefile object, use the OBJ_DESTROY procedure:
OBJ_DESTROY, myRoutines OBJ_DESTROY, myImage
Destroying the savefile object will close the SAVE file with which the object is associated.
With IDL 5.4, RSI released a version of IDL that was 64-bit capable. The original IDL SAVE/RESTORE format used 32-bit offsets. In order to support 64-bit memory access, the IDL SAVE/RESTORE file format was modified to allow the use of 64-bit offsets within the file, while retaining the ability to read old files that use the 32-bit offsets.
The SAVE command always begins reading any SAVE file using 32-bit offsets. If the 64-bit offset command is detected, 64-bit offsets are then used for any subsequent commands.
.savfile using 32-bit offsets. If it sees the 64-bit offset command, it switches to 64-bit offsets for any commands following that one.
This configuration is fully backward compatible, in that any IDL program can read any SAVE file it has created, or by any earlier IDL version. Note however that files produced in IDL 5.4 using 64-bit offsets are not readable by older versions of IDL.
It has come to our attention that IDL users commonly transfer SAVE/RESTORE data files written by newer IDL versions to sites where they are restored by older versions of IDL. It is not generally reasonable to expect this sort of forward compatibility, and it does not fit the usual definition of backwards compatibility. RSI has always strived to maintain this compatibility. However, in IDL 5.4 this was not the case. The following steps were taken in IDL 5.5 to minimize the problems caused by the IDL 5.4 save format: