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


Harris Geospatial / Docs Center / Libraries / Markwardt / CMRESTORE

CMRESTORE

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
  $Id: cmrestore.pro,v 1.22 2009/11/22 23:31:00 craigm Exp $



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