Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


CMSAVE

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
  $Id: cmsave.pro,v 1.16 2009/11/22 23:26:19 craigm Exp $



© 2017 Exelis Visual Information Solutions, Inc. |  Legal
My Account    |    Buy    |    Contact Us