|
|
Using IDL: Getting Information About Files and 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.
| 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.
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, 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
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 '6.4' 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:
PRINT, myRoutines->Names(/PROCEDURE)
IDL Prints:
ARROW DRAW_ARROW
Similarly, to retrieve the name of the variable saved in imagefile.sav, which is referred to by the myImage savefile object:
PRINT, myImage->Names()
IDL Prints:
IMAGE
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[0]
PRINT, 'Image Y size:', imagesize[1]
IDL Prints:
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:
myRoutines->Restore, 'draw_arrow'
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.
IDL Online Help (March 06, 2007)