CMSAVEDIR Name
CMSAVEDIR
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Display a directory of the variables in an IDL SAVE file.
Calling Sequence
CMSAVEDIR, filename [, /VERBOSE, /QUIET, ... ]
Description
CMSAVEDIR will display a listing of the variables and other
objects stored in an IDL SAVE file.
For command-line users the primary function of CMSAVEDIR will be
to find out what data is stored in a file and when it was saved.
For that, they simply need to type: CMSAVEDIR, 'myfile.sav'
CMSAVEDIR also offers a number of features for programmers.
CMSAVEDIR essentially interrogates the save file and discovers the
numbers, names and types of each of the variables stored in the
file. Programmers can use that information to decide whether or
how to open a file using the other routines in the CMSVLIB.
Various keyword parameters are used return this information, as
documented 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 --
CMSAVEDIR cannot examine compressed save files, or files larger
than 2 gigabytes.
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 - a scalar string, the name of the file to be examined.
Keywords
VERBOSE - if set, print more detailed information about the input file.
QUIET - if set, then do not print any output. Programmers can use
this keyword to allow CMSAVEDIR to return information
about the file silently.
STATUS - upon output, 1 for success, otherwise to indicate
failure.
ERRMSG - upon output, if a failure occurs, a message describing
the error condition.
N_VARIABLES - upon output, the number of variables in the file.
VAR_NAMES - upon output, contains a string array of the names of
the variables stored in the file.
TYPES - upon output, an 11xN_VARIABLES array containing the SIZE
information of each variable in the file.
N_PRO - upon output, the number of procedures stored in the file.
PRO_NAMES - upon output, the names of the procedures stored in the
file, as a string array.
N_FUNCTION - upon output, the number of functions stored in the
file.
FUNC_NAMES - upon output, the names of the functions stored in the
file, as a string array.
NAMED_STRUCTS - upon output, a string array listing any named
structures which appear in the SAVE file.
NAMED_CLASSES - upon output, a string array listing any named
class structures which appear in the SAVE file.
TIMESTAMP - upon output, contains the timestamp record information
in a structure. The fields of the structure are:
SAVE_DATE - string - date saved
SAVE_USER - string - user who saved file
SAVE_HOST - string - host name on which file
saved
VERSION - upon output, contains the version record information in
a structure. The fields of the structure are:
FORMAT_VERSION - integer - major format version
ARCH - string - saving host's !VERSION.ARCH
OS - string - saving host's !VERSION.OS
RELEASE - string - saving host's !VERSION.RELEASE
NOTICE - upon output, contains any textual notice included within
the file. The fields of the structure are:
TEXT - string - text of the notice
FORCE - if set, will force CMSAVEDIR to open the file even if it
detects a potential incompatibility.
Example
IDL> cmsavedir, 'int_str_intarr.sav'
** int_str_intarr.sav
** Sun Apr 9 20:28:25 2000 (craigm@beach.gsfc.nasa.gov)
** IDL v5.2 (linux)
A INT = 0
B STRING = 'hello'
C INT = Array[3]
** 3 variable(s), 0 heap value(s) and 0 procedure(s) in 1376 bytes
See Also
CMRESTORE, CMSAVE, SAVE, RESTORE, CMSVLIB
Modification History
Documented, 12 Jan 2001, CM
Added USAGE message, 09 Jun 2001, CM
Fixed bug in printing common variables, 17 Mar 2002, CM
Added notification about RSI License, 13 May 2002, CM
Added NOTICE record type, 09 Jun 2003, CM