CMRESTORE Name
CMRESTORE
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Restore variables from an IDL SAVE file.
Calling Sequence (various)
CMRESTORE, filename (implicit)
CMRESTORE, filename, var1, var2, ..., [, NAMES=names]
CMRESTORE, filename, DATA=pointers, NAMES=names, PASS_METHOD='POINTER'
CMRESTORE, filename, DATA=handles, NAMES=names, PASS_METHOD='HANDLE'
CMRESTORE, filename, DATA=structure, PASS_METHOD='STRUCT'
Description
CMRESTORE is a replacement for the built-in IDL procedure RESTORE.
It restores variables and data from an existing IDL SAVE file,
written either by SAVE or CMSAVE. The CMSV utility library must
be installed in your IDL path to use CMSAVE and CMRESTORE.
The primary advantage to CMRESTORE is the ability to selectively
restore only certain variables from the input file (based on
name). CMRESTORE provides a number of ways to pass the data
between routines, typically using a pointer or structure, which
avoids the unsafe practice of restoring variables in the caller's
namespace. However, CMRESTORE can restore variables into the
caller's namespace, but users should be aware that this capacity
is somewhat limited in IDL versions 5.2 and below.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
Compatibility
-- File Format --
CMRESTORE should be able to read files written by SAVE and CMSAVE
from IDL version 4 to version 5.4.
CMRESTORE cannot restore objects, pointers, compressed files, or
data sets larger than 2 gigabytes.
Data types available in newer versions of IDL, such as pointers
and long integers, will not be readable in older versions of IDL
which do not have those data types.
-- Calling Interface --
For the most part, all capabilities of CMRESTORE are available to
the user. However, it should be noted that passing variables by
positional parameter is not available under IDL 4, unless NAMES is
used to name the variables explicitly. Also, under IDL versions
5.2 and previous, it is not possible for CMRESTORE to restore
variables into the caller's name space if they are not yet
defined.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
Inputs
FILENAME - the name of the SAVE file.
Default: none, this parameter must be specified.
VAR{i} - The values to be restored. By default the save name is
taken from the named variables that are passed. These
default names can be overridden by using the NAMES
keyword.
If no variables are passed as positional parameters, they
can still be saved using the DATA keyword. By invoking
CMRESTORE without positional parameters or DATA,
CMRESTORE automatically will attempt to restore the
variables to the calling routine's name space (the
"implicit" technique).
NOTE: in IDL 5.2 and below, user routines are not
allowed to *CREATE* new variables in the caller's name
space. CMRESTORE may fail if the variable in
undefined in the caller. Therefore you must define it
before calling CMRESTORE. The safer practice is to
use the VAR{i} positional parameters, or the DATA
keyword.
Keywords
FILENAME - the name of the SAVE file. The positional FILENAME
parameter takes precedence over the keyword FILENAME
parameter.
NOTE that if you pass variables as positional
parameters, then the first parameter *must* be the file
name, and the FILENAME *keyword* will be ignored.
PASS_METHOD - a scalar string, describing the method of passing
data between the caller and CMRESTORE. The keyword
can take the value 'ARGUMENT', 'POINTER', 'HANDLE'
or 'STRUCT'. A value of 'ARGUMENT' indicates that
data values will be passed by command line argument,
and is the default. Other values are described
below.
DATA - A list of data elements to be restored from the output
file. The data elements can be one of the following,
depending on the value of PASS_METHOD. The means of
extracting the data, and the method of naming each
variable, are also indicated.
* PASS_METHOD='POINTER': An array of pointers to the variables
Data: pointed-to value Name: from NAMES keyword
* PASS_METHOD='HANDLE': An array of handles to the variables
Data: pointed-to value Name: from NAMES keyword
* PASS_METHOD='STRUCT': A structure containing data to be saved
Data: tag value Name: tag name
Data values are restored one by one, using the appropriate
name. Note that any variables passed as positional
parameters will cause the DATA keyword to be ignored.
CMRESTORE will allocate any pointer or handle resources.
The calling routine is responsible for deallocating any
pointer or handle resources.
NAMES - a string array, giving the names for each variable.
If the data are passed by positional parameters, the names
are assigned according to the position of the parameter in
the procedure call.
If the data are passed by an array of pointers or handles,
then the names are assigned according to the position of
the data in the array. In this case there is no other way
to supply the variable name. NAMES is required.
If the data are passed in a structure, then the names are
assigned according to the position of the data in the
structure. The values specified in the names keyword
override the tag names.
STATUS - upon return, an integer indicating the status of the
operation. A value of 1 indicates success, while 0
indicates failure. A failure condition does not
necessarily indicate that an individual variable could
not be restored; use the VARSTATUS keyword to detect such
situations.
VARSTATUS - upon return, an integer array indicating the status of
the restore operation for each variable. A value of 1
at position i in the array indicates success for the
ith variable, while a value of 0 indicates failure.
ERRMSG - upon return, a string indicating the status of the
operation. The empty string indicates success, while a
non-empty string indicates failure and describes the
error condition.
QUIET - if set, then the error message is returned to the calling
routine. By default an error condition causes execution
to stop and the message to be printed on the console.
VERBOSE - if set, then a short message is printed for each
variable.
Example
CMSAVE, VAR1, VAR2, FILENAME='test.sav'
CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']
Save the data in VAR1 and VAR2 to the file test.sav. In the
first case the saved variable names will be VAR1 and VAR2. In
the second case the saved variable names will be A and B.
POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B.
STRUCTURE = {A: VAR1, B: VAR2}
CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B.
See Also
CMSAVE, SAVE, RESTORE
Modification History
Written, 14 May 2000
Documented, 22 Sep 2000
Restore into caller's name space now permitted, 11 Jan 2001
Documented "implicit" restore a little better, w/ errors, 01 Mar 2001
Make version checks with correct precision, 19 Jul 2001, CM
Restore with no args automatically does ALL, is this right?,
CM, 20 Aug 2001
Added notification about RSI License, 13 May 2002, CM
Handle the case of CMRESTORE, FILENAME, X properly, 03 Sep 2008, CM
(thanks to Sergey Koposov for reporting)
Report CMSVLIB version number when /VERBOSE is set, 22 Nov 2009,
CM
Change to accomodate lack of GDL functionality when restoring
all variables, 22 Nov 2009, CM