Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]

Saving Compiled IDL Programs and Data

The SAVE procedure can be used to quickly save IDL routines and data variables in a binary format that can be shared with other IDL users, or with others who have installed the IDL Virtual Machine.

Warning
Variables and routines cannot be stored in the same SAVE file.

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 automatically locate and compile the routines in the file as described in Automatic Compilation.

If your program or utility consists of multiple routines, each procedure or function used by your program must be resolved and contained in a SAVE file. You have the following options:

If your program also contains variable data, you must create a separate SAVE file to contain the data. Variable data must be explicitly restored before any routine attempts to use the variables contained in the file. See Restoring Compiled IDL Programs and Data for more information.

Note
A SAVE file containing data will always be restorable. However, SAVE files created prior to IDL version 5.5 that contain IDL procedures, functions, and programs are not always portable between different versions of IDL. If you created your SAVE file with a version of IDL earlier than 5.5, you will need to recompile your original .pro files and re-create the SAVE file using the current version of IDL.

Example: Create a SAVE File of a Simple Routine

The following example creates two SAVE files. One SAVE file will contain 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. To create these files, do the following:

  1. Start a fresh session of IDL to avoid saving unwanted session information.
  2. 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. Use the SAVE procedure to save the image variable in a .sav 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.

  4. 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.
    5. 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 
 
END
  5. Save the file as draw_arrow.pro.
  6. Enter .FULL_RESET_SESSION at the IDL prompt. This will ensure that no unwanted session information is saved along with the program.
  7. Open draw_arrow.pro and compile it by entering:
    8. .COMPILE draw_arrow
  8. Use RESOLVE_ALL to iteratively compile any uncompiled user-written or library procedures or functions that are called in any already-compiled procedure or function:
    9. 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.

  1. Create a SAVE file called draw_arrow.sav containing 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 procedures are the only routines that are currently compiled, in the IDL session, create the SAVE file as follows:
    2. 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.

Example: Customize and Save an ASCII Template

When importing an ASCII data file into IDL, you must first describe the format of the data using the interactive ASCII_TEMPLATE function. If you have a number of ASCII files that have the same format, you can create and save a customized ASCII template using the SAVE procedure. After creating a SAVE file of your custom template, you can avoid having to repeatedly define the same fields and records when reading in ASCII files that have the same structure.

  1. At the IDL command line, enter the following to create the variable plotTemplate, which will contain your custom ASCII template: 
    2. plotTemplate = ASCII_TEMPLATE( )

    A dialog box appears, prompting you to select a file.

  2. Select the plot.txt file in the examples/data subdirectory of the IDL distribution.

    3. Note
    Another way to import ASCII data is to use the Import ASCII File toolbar button on the IDLDE toolbar. To use this feature, simply click the button and select plot.txt from the file selection dialog.

  3. After selecting the file, the Define Data Type/Range dialog appears. First, choose the field type. Since the data file is delimited by tabs (or whitespace) select the Delimited button. In the Data Starts at Line field, specify to begin reading the data at line 3, not line 1, since there are two comment lines at the beginning of the file. Click Next to continue.
  4. In the Define Delimiter/Fields dialog box, select Tab as the delimiter between data elements since it is known that tabs were used in the original file. Click Next.
  5. In the Field Specification dialog box, name each field as follows:
    • Click on the first row (row 1). In the Name field, enter time.
    • Select the second row and enter temperature1.
    • Select the third row and enter temperature2.
  6. Click Finish.
  7. Type the following line at the IDL command line to read in the plot.txt file using the custom template, plotTemplate:
    8. PLOT_ASCII = READ_ASCII(FILEPATH('plot.txt', SUBDIRECTORY = $
   ['examples', 'data']), TEMPLATE = plotTemplate)
  8. Enter the following line to print the plot.txt file data:
    9. PRINT, PLOT_ASCII

The file contents are printed in the Output Log window. Your output will resemble the following display.

  1. Create a SAVE file of your custom template by entering the following: 
    2. SAVE, plotTemplate, FILENAME='myPlotTemplate.sav'
  2. To restore the template so that you can read another ASCII file, enter:
    3. RESTORE, 'myPlotTemplate.sav'

    This file contains your custom ASCII template information stored in the structure variable, plotTemplate.

    Note
    If you are attempting to restore a file that is not in your current working directory, you will need to specify a path to the file.

  3. After restoring your custom template, you can read another ASCII file that is delimited in the same way as the original file by using the READ_ASCII function and specifying plotTemplate for the TEMPLATE:
    4. PLOT_ASCII = READ_ASCII(FILEPATH('plot.txt', $ 
   SUBDIRECTORY = ['examples', 'data']), $ 
   TEMPLATE = plotTemplate)
  4. Enter the following to display the contents of the file using the customized ASCII template structure previously defined using the dialog.
    5. PRINT, PLOT_ASCII

Example: Save the XROI Utility with ROI Data

You can easily share your own IDL routines or utilities with other IDL users by using the SAVE routine to create a binary file of your compiled code. The following example creates a SAVE file of the XROI utility (a .pro file) and from within this file, restores a secondary SAVE file containing selected regions of interest.

  1. Type XROI at the command line to open the XROI utility.
  2. In the file selection dialog, select mineral.png from the examples/data subdirectory of the IDL distribution.
  3. Select the Draw Polygon toolbar button and roughly outline the three large, angular areas of the image.
  4. Select File ® Save ROIs and name the file mineralROI.sav. This creates a SAVE file containing the regions of interest selected within the image.
  5. In the IDL Editor or any text editor, enter the following routine:
    6. PRO myXRoi 
 
; Restore ROI object data by specifying a value for the 
; RESTORED_OBJECTS keyword. 
RESTORE, 'mineralROI.sav', RESTORED_OBJECTS = myROI 
 
; Open XROI, specifying the previously defined value for the
; restored object data as the value for "REGIONS_IN". 
XROI, READ_PNG(FILEPATH('mineral.png', $ 
   SUBDIRECTORY = ['examples', 'data'])), $ 
   REGIONS_IN = myROI, /BLOCK 
 
END

    Save the routine as myXRoi.pro

  6. Exit and restart IDL or enter .FULL_RESET_SESSION at the IDL command line before creating a SAVE file to avoid saving unwanted session information.
  7. Compile the program you just created:
    8. .COMPILE myXRoi.pro
  8. Use RESOLVE_ALL to iteratively compile any uncompiled user-written or library procedures or functions that are called in any already-compiled procedure or function:
    9. 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.

  1. Create a SAVE file named myXRoi.sav, containing all of the XROI utility routines. When the SAVE procedure is called with the ROUTINES keyword and no arguments, it creates a SAVE file containing all currently compiled routines. Because the routines associated with the XROI utility are the only ones that are currently compiled in our IDL session, we can create a SAVE file as follows:
    2. SAVE, /ROUTINES, FILENAME='myXRoi.sav'
  2. It is not necessary to use RESTORE to open myXRoi.sav. If the SAVE file uses the .sav extension and has the same base name as the main level routine, and all necessary files (in this case, mineralROI.sav and myXRoi.sav) are stored in the current working directory, simply type the name of the file, minus the .sav extension, at the command line:
    3. myXRoi

The following figure will appear, showing the selected regions of interest.

Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]