Getting Information About SAVE Files
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.
Note
The IDL_Savefile object does not provide methods that allow you to modify an existing SAVE file. The only way to modify an existing SAVE file is to restore its contents into a fresh IDL session, modify the contained routines or variables as necessary, and use the SAVE procedure to create a new version of the file.
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 (IDL Reference Guide).
Create a Savefile Object
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: A SAVE File of a Simple Routine (Application Programming), use the following command:
Similarly, to create a savefile object from the saved image data, use the following command:
Query the Savefile Object
Once you have created a savefile object, three methods allow you to retrieve information about its contents:
- The Contents method provides information about the SAVE file including the number and type of items contained therein.
- The Names method allows you to retrieve the names of routines and variables stored in the file.
- The Size method allows you to retrieve size and type information about the variables stored in the file.
Contents Method
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 (IDL Reference Guide).
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:
IDL Prints:
** Structure IDL_SAVEFILE_CONTENTS, 17 tags, length=176, data leng th=172: FILENAME STRING '/itt/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 '7.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.
Names Method
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 (IDL Reference Guide).
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:
IDL Prints:
Similarly, to retrieve the name of the variable saved in imagefile.sav, which is referred to by the myImage savefile object:
IDL Prints:
Size Method
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 (IDL Reference Guide) 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[0]
PRINT, 'Image Y size:', imagesize[1]
IDL Prints:
Restore Items from the Savefile Object
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 (IDL Reference Guide) for additional details.
For example, to restore the DRAW_ARROW procedure without restoring the ARROW procedure, do the following:
Note on Restoring Objects and Pointers
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 (IDL Reference Guide) for complete details.
Destroy the Savefile Object
To destroy a savefile object, use the OBJ_DESTROY procedure:
Destroying the savefile object will close the SAVE file with which the object is associated.
