Previous Application Programming: Creating SAVE Files of Programs and Data Next

Creating SAVE Files of Program Files

The following examples create SAVE files that are stand-alone IDL applications that can be run on any Windows, UNIX or Mac OS X computer containing the IDL Virtual Machine or a licensed copy of IDL. See the following examples:

Example: A SAVE File of a Simple Routine

The following example creates two SAVE files. One SAVE file contains variable data, loaded from an image file. This SAVE file is then restored by the program in the main SAVE file, which uses a simple call to the ARROW procedure to point out an area of interest within the image.

Save Image Variable Data

  1. Start a fresh session of IDL. This avoids saving unwanted session information.

    2.  

  2. Read image data into a variable. Open an image file containing an MRI proton density scan of a human thorax, and read the data into a variable named image:
    3. READ_JPEG, (FILEPATH('pdthorax124.jpg', SUBDIRECTORY= $  
    ['examples', 'data'])), image

     

  3. Create a SAVE file containing the image data. Use the SAVE procedure to save the image variable in a SAVE file by entering the following:
    4. SAVE, image, FILENAME='imagefile.sav'

     

    This stores the SAVE file in your current working directory.

     


    Note
    When using the SAVE procedure, some users identify binary files containing variable data using a .dat extension instead of a .sav extension. While any extension can be used to identify files created with SAVE, it is recommended that you use the .sav extension to easily identify files that can be restored.

Save a Procedure that Restores Variable Data

  1. Create the program file. Create the following IDL program that first restores the image variable contained within the imagefile.sav file. This variable is used in the following program statements defining the size of the window and in the TV routine which displays the image. The ARROW routine then draws an arrow within the window. Enter the following lines in a text editor.
    2. PRO draw_arrow  
  
; Restore image data.  
RESTORE, 'imagefile.sav'  
  
; Get the dimensions of the image file.  
s = SIZE(image, /DIMENSIONS)  
  
; Prepare display device and display image.  
DEVICE, DECOMPOSED = 0  
WINDOW, 0, XSIZE=s[0], YSIZE=s[1], TITLE="Point of Interest"  
TV, image  
  
; Draw the arrow.  
ARROW, 40, 20, 165, 115  
  
; The IDL Virtual Manchine exits IDL when the end of a  
; program is reached if there are not internal events. The   
; WAIT statement here allows the user to view the .sav file   
; results for 10 seconds when executed through the IDL   
; Virtual Machine.  
WAIT, 10  
  
END

     

  2. Save the file. Name the saved file draw_arrow.pro.

    3.  

  3. Reset the IDL session. Enter the following at the IDL prompt to ensure that no unwanted session information is saved along with the program:
    4. .FULL_RESET_SESSION

     

  4. Compile the program. Enter the following at the IDL prompt: 
    5. .COMPILE draw_arrow

     

  5. Resolve dependencies. Use RESOLVE_ALL (or ITRESOLVE if the routine has any dependencies on iTools components) to iteratively compile any uncompiled user-written or library procedures or functions that are called in any already-compiled procedure or function:
    6. RESOLVE_ALL

     


    Note
    RESOLVE_ALL does not resolve procedures or functions that are called via quoted strings such as CALL_PROCEDURE, CALL_FUNCTION, or EXECUTE, or in keywords that can contain procedure names such as TICKFORMAT or EVENT_PRO. You must manually compile these routines.

     

  6. Create the SAVE file. Create a file called draw_arrow.sav that contains the user-defined draw_arrow procedure. When the SAVE procedure is called with the ROUTINES keyword and no arguments, it create a SAVE file containing all currently compiled routines. Because the procedures within the draw_arrow procedure are the only routines that are currently compiled in the IDL session, create the SAVE file as follows:
    7. SAVE, /ROUTINES, FILENAME='draw_arrow.sav'

     


    Note
    When the name of the SAVE file uses the .sav extension and has the same base name as the main level program, it can be automatically compiled by IDL. This means that it can be called from another routine or restored from the IDL command line using only the name of the saved routine. See Automatic Compilation for details.

     

  7. Test the SAVE file. Select Start Programs IDL 6.4 IDL Virtual Machine. Click on the splash screen and open draw_arrow.sav. You could also test the SAVE file from IDL, enter the following at the command prompt. 
    8. RESTORE, 'draw_arrow.sav'  
draw_arrow

See Executing SAVE Files for all the available ways to run a SAVE file.

Example: A Save File of a Simple Widget Application

The following example creates a native IDL application that displays an image in a simple widget interface. When any application runs in the IDL Virtual Machine, there must some element (such as widget or interface events, or a WAIT statement) that keeps the application from immediately exiting with the END statement is reached. This example includes a Done button for this reason. The example in Example: A SAVE File of a Simple Routine includes a WAIT statement.

  1. Create a .pro file. Enter the following in the IDL Editor, and save it as myApp.pro:
    2. PRO done_event, ev  
; When the 'Done' button is pressed, exit  
; the application.  
  
WIDGET_CONTROL, ev.TOP, /DESTROY  
  
END  
  
PRO myApp  
  
; Read an image file.  
READ_JPEG, (FILEPATH('endocell.jpg', SUBDIRECTORY = $  
   ['examples', 'data'])), image  
  
; Find the dimensions of the image.  
info = SIZE(image,/DIMENSIONS)  
xdim = info[0]  
ydim = info[1]  
  
; Create a base widget containing a draw widget  
; and a 'Done' button.  
wBase = WIDGET_BASE(/COLUMN)  
wDraw = WIDGET_DRAW(wBase, XSIZE=xdim, YSIZE=ydim)  
wButton = WIDGET_BUTTON(wBase, VALUE='Done', 
EVENT_PRO='done_event')  
  
; Realize the widgets.  
WIDGET_CONTROL, wBase, /REALIZE  
  
; Retrieve the widget ID of the draw widget.  
WIDGET_CONTROL, wDraw, GET_VALUE=index  
  
; Set the current drawable area to the draw widget.  
WSET, index  
  
; Display some data.  
TV, image  
  
; Call XMANAGER to manage the event loop.  
XMANAGER, 'myApp', wBase, /NO_BLOCK  
  
END

     

  2. Reset the IDL session. Enter the following at the IDL prompt to ensure that no unwanted session information is saved along with the program:
    3. .FULL_RESET_SESSION

     

  3. Compile the application. Select Run Compile to compile the .pro file.

    4.  

  4. Resolve dependencies. Type RESOLVE_ALL at the command line to resolve all procedures and functions that are called in the application:
    5. RESOLVE_ALL

     


    Note
    If your program relies on iTools components, use ITRESOLVE instead of RESOLVE_ALL.

     

  5. Create the SAVE file. Enter the following to save the compiled application as a SAVE file:
    6. SAVE, /ROUTINES, FILENAME = 'myApp.sav'

See Executing SAVE Files for ways to run the SAVE file.

Example: Creating a SAVE File of an Object Definition

When you create a SAVE file that contains an object defined in a .pro file, you must save the .pro file as a SAVE file, just like any other procedure you wish to distribute. However, it is important to note that if the object has any inherited properties from superclasses or other objects, and the object definitions exist in .pro files, you must also compile and include these object definition files in your SAVE file. Objects using a .pro extension typically exist in the IDL distribution's lib subdirectory and its subdirectories.


Note
Do not confuse the process of saving an instance of an object with saving its definition. A reference to an instantiated object is stored in an IDL variable, and must be saved in a SAVE file as a variable. An object definition, on the other hand, is an IDL routine, and must be saved in a SAVE file as a routine. It is important to remember that restoring an instance of an object does not restore the object's definition. If the object is defined in .pro code, you must save the object definition routine and the object instance variable in separate SAVE files, and restore both instance and definition in the target IDL session.

The IDL distribution includes and example of a composite object composed of an image, a surface, and a contour, which are combined into a single object called the IDLexShow3 object. To see this object being used in an application, run the show3_track.pro file in the examples/doc/objects directory. This procedure has dependencies on two objects (trackball.pro and IDLexShow3__define.pro). You must use RESOLVE_ALL and explicitly include these two objects in the CLASS keyword string array in order to create a valid SAVE file.

If you fail to resolve all object dependencies, you will receive an error stating that there was an attempt to call and undefined procedure or function when you run the SAVE file. If the error references an object, add the object name to the CLASS keyword string array to resolve the problem. Undefined procedure or function errors are more likely to appear when you restore a SAVE file using the IDL Virtual Machine, which does not search !PATH to resolve routines. Using RESTORE at the command line does search !PATH. Therefore, a SAVE file that can be successfully executed using RESTORE may not succeed when called from the IDL Virtual Machine. If you are distributing SAVE files to users running the IDL Virtual Machine, make sure to test the SAVE file in the Virtual Machine.

Complete the following steps to create a save file of an object:

  1. Reset your session. Either start a new IDL session or enter the following at the IDL prompt to ensure that no unwanted session information is saved along with the program:
    2. .FULL_RESET_SESSION

     

  2. Open the main procedure. Open and compile show3_track.pro file by entering the following at the IDL command prompt:
    3. .COMPILE Show3_Track.pro

     

  3. Resolve object dependencies. Use the CLASS keyword to resolve dependencies to other object .pro files by passing it a string or string array containing the name(s) of the objects:
    4. RESOLVE_ALL, CLASS=['Trackball', 'IDLexShow3']

     

  4. Create the SAVE file. Enter the following at the IDL command prompt:
    5. SAVE, /ROUTINES, FILENAME='show3_track.sav'

     

  5. Test the SAVE file. Select Start Programs IDL 6.4 IDL Virtual Machine. Click on the splash screen and open show3_track.sav. You could also test the SAVE file from IDL. Enter the following at the command prompt. 
    6. RESTORE, 'show3_track.sav'  
show3_track

See Executing SAVE Files for all the available ways to run a SAVE file.

Example: A SAVE File of a Custom iPlot Display

The following example configures a custom iPlot display and stores the program in a SAVE file. Restoring the SAVE file opens iPlot with the specified data.


Note
When working with iTools, you can create an iTool State (.isv) file that contains data and application state information.You can share this file with other IDL users who have the same version or a newer version of IDL. See the iTool User's Guide for details. This is not the same as packaging iTools functionality into a SAVE file, which is described in this example. When iTools functionality is packaged into a SAVE file, it can be accessed by IDL users or through the IDL Virtual Machine.

  1. Access and save data. Save variable data from a batch file into a SAVE file:
    2. @plot01  
SAVE, FILENAME='plotdata01.sav'

     

  2. Create the program file. This program restores data, and creates a plot display in an iPlot display. Enter the following lines in a text editor:
    3. PRO ex_saveiplot   
  
; Define variables.   
RESTORE, 'plotdata01.sav'  
  
; Use the LINFIT function to fit the data to a line:  
coeff = LINFIT(YEAR, SOCKEYE)  
  
;YFIT is the fitted line:  
YFIT = coeff[0] + coeff[1]*YEAR  
  
; Plot the original data points with PSYM = 4, for diamonds:  
iPLOT, YEAR, SOCKEYE, /YNOZERO, SYM_INDEX = 4, $  
   SYM_COLOR=[255,0,0], LINESTYLE=6, $  
   TITLE = 'Quadratic Fit', XTITLE = 'Year', $  
   YTITLE = 'Sockeye Population'  
     
; Overplot the smooth curve using a plain line:  
iPLOT, YEAR, YFIT, /OVERPLOT  
  
END

     

  3. Reset you session. Enter the following at the IDL prompt to ensure that no unwanted session information is saved along with the program:
    4. .FULL_RESET_SESSION

     

  4. Compile the program. Use the .COMPILE executive command as follows: Compile the main program file:
    5. .COMPILE ex_saveiplot

     

  5. Resolve dependencies. Use ITRESOLVE to resolve dependencies upon iTool components:
    6. ITRESOLVE

     

  6. Create the SAVE file. Use the /ROUTINES keyword to include all currently compiled routines:
    7. SAVE, /ROUTINES, FILENAME='ex_saveiplot.sav'

     

  7. Test the SAVE file. Select Start Programs IDL 6.4 IDL Virtual Machine. Click on the splash screen and open ex_saveiplot.sav. You could also run the SAVE file from IDL. Enter the following at the command prompt. 
    8. RESTORE, 'ex_saveiplot.sav'  
ex_saveiplot

See Executing SAVE Files for all the available ways to run a SAVE file.

Other Examples of SAVE File Creation

See the following topics for additional SAVE file examples:

  IDL Online Help (March 06, 2007)