CMSAVE Name
CMSAVE
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Save IDL variables to a file. (IDL v5 and greater)
Calling Sequence (various)
CMSAVE, var1, var2, ..., FILENAME=filename [, NAMES=names]
CMSAVE, DATA=pointers, NAMES=names, FILENAME=filename
CMSAVE, DATA=handles, NAMES=names, FILENAME=filename
CMSAVE, DATA=structure, FILENAME=filename
Description
CMSAVE is a replacement for the built-in IDL procedure SAVE, with
more flexibility and increased capabilities.
CMSAVE produces output files that are compatible with the standard
save format of IDL versions 4 and 5 (and perhaps greater).
Variables may be restored by using either the built-in procedure
RESTORE, or CMRESTORE. The CMSV utility library must be installed
in your IDL path to use CMSAVE and CMRESTORE.
The primary advantages to CMSAVE are the ability to append
additional variables to an existing SAVE file, and several
flexible ways to pass the data and variable names to be saved.
CMSAVE also attempts to run on all IDL versions.
To append variables to an existing file, simply specify the APPEND
keyword, and the filename of an existing writable SAVE file.
Variables will be appended to the end of the file. It is possible
to append a variable with the same name as an existing variable in
a file. Both data values are stored in the file. However the
results upon restore are undefined. There is also a limitation
that only one series of heap values -- pointed-to data -- may be
saved in a file.
By the normal convention of the built-in SAVE command, both the
data and variable names to be saved are passed as parameters on
the command line. Each parameter must be a named variable; both
the name and value are saved.
This convention may be used in invoking CMSAVE as well. However,
in addition to passing the data by positional parameter, the user
can pass the data using the DATA keyword. If the DATA keyword is
used, then an array of pointers or handles may be passed, or a
structure of values may be passed. (see below) If both are
passed, then the positional parameters take precedence.
It is also possible to explicitly rename the saved variables: the
saved name does not need to be the name of the named variable.
Use the NAMES keyword to override the default name. By default
the name is drawn from any named variables, or from the structure
tag names if the DATA keyword is used with a structure. The NAMES
keyword takes precedence over these values. NOTE: Values passed
by pointer or handle are not named by default, and so will not be
saved unless the NAMES keyword is used.
==================================================================
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 --
Files written by CMSAVE should be readable with all known versions
of IDL at the time of this writing (version 4 - version 5.4). It
is expected that this compatibility will persist.
CMSAVE cannot write objects, 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 CMSAVE 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.
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
VAR{i} - The variables to be saved. 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.
Variables can also be specified by passing an array of
handles or pointers in the DATA keyword.
If no variables are passed as positional parameters or
using DATA, then CMSAVE will assume that *all* variables
at the caller's level should be saved (this is similar
behavior to the built-in SAVE routine). Note that system
variables cannot be saved with CMSAVE.
Keywords
ALL - for compatibility with the built-in SAVE routine. Ignored.
Note that CMSAVE cannot save system variables.
FILENAME - the name of the output file.
Default: 'cmsave.sav'
DATA - A list of data elements to be saved to the output file.
The data elements can be one of the following. The means
of extracting the data, and the method of naming each
variable, are also indicated.
* An array of pointers to the variables
Data: pointed-to value Name: from NAMES keyword
* An array of handles to the variables
Data: pointed-to value Name: from NAMES keyword
* A 1-element structure containing data to be saved.
Data: tag value Name: tag name
Data values are saved one by one, using the appropriate
name. Note that any variables passed as positional
parameters will cause the DATA keyword to be ignored.
The calling routine is responsible for deallocating any
pointer or handle resources.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
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. This can be especially useful to
rename local variables, and to give names to expressions.
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 NAMES keyword values override the tag
names.
APPEND - if set, then the specified variables are appended to an
existing file.
Repeated variables will not cause an error, however they
may not be restored properly using the built-in RESTORE
procedure. It may also not be permitted to append
variables that contain heap pointers, to a save file
which already contains heap data.
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 written; use the VARSTATUS keyword to detect such
situations.
VARSTATUS - upon return, an integer array indicating the status of
the save 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.
XDR - for compatibility with the built-in SAVE routine. Ignored.
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. Data are passed by pointer.
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. Data are passed by structure.
See Also
CMRESTORE, SAVE, RESTORE, CMSVLIB
Modification History
Written, 14 May 2000
Documented, 22 Sep 2000
Made "more" compatible with SAVE; additional documentation, 11 Jan
2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM