;+ ; NAME: ; CMSVREAD ; ; AUTHOR: ; Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 ; craigm@lheamail.gsfc.nasa.gov ; ; PURPOSE: ; Read a single variable from an open SAVE file ; ; CALLING SEQUENCE: ; ; CMSVREAD, UNIT, DATA [, NAME=NAME, /NO_DATA, VERSION=VERSION, ; TIMESTAMP=TIMESTAMP ] ; ; DESCRIPTION: ; ; CMSVREAD reads a single IDL variable from an open IDL SAVE file. ; The file should already have been opened as a normal file using ; OPENR. ; ; CMSVREAD is a simplified version of the CMSVLIB package, and as ; such is not capable of reading heap data (pointers) or object ; data. Strings, structures, and all array types are supported. ; ; 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. ; ; ================================================================== ; 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. ; ================================================================== ; ; INPUTS: ; ; UNIT - the open file unit. ; ; DATA - a named variable, into which the new data is to be read. ; ; KEYWORDS: ; ; NAME - upon output, the name of the saved variable is returned in ; this keyword. If a failure or end of file condition ; occurs, name will be undefined upon return. ; ; STRUCTURE_NAME - if the data to be read is a structure, upon ; output, this keyword will contain the name of the ; structure. A value of '' indicates an anonymous ; structure. ; ; SIZE - upon output, the SIZE type of the data is returned in this ; keyword. ; ; NO_DATA - if set, no data is read from the file, only the variable ; name and type. ; ; TIMESTAMP - after the first call to CMSVREAD on a newly opened ; file, this keyword will contain the file timestamp ; structure. ; ; VERSION - after the first call to CMSVREAD on a newly opened file, ; this keyword will contain the file version information, ; if available. ; ; QUIET - if set, error messages are not printed. ; Default: an error causes errors to be printed with MESSAGE ; ; STATUS - upon return, this keyword will contain 1 for success and ; 0 for failure. ; ; ERRMSG - upon return with a failure, this keyword will contain the ; error condition as a string. ; ; EXAMPLE: ; ; Read all variables from a file, and print help on them. ; ; openr, 50, 'test.sav' ; name = '' ; while n_elements(name) GT 0 do begin ;; EOF signalled by NAME undefined ; cmsvread, 50, data, name=name ; help, name, data ; end ; close, 50 ; ; SEE ALSO: ; ; CMSVWRITE, CMRESTORE, CMSAVE, RESTORE, CMSVLIB ; ; MODIFICATION HISTORY: ; Written and documented, 11 Jan 2001, CM ; Added notification about RSI License, 13 May 2002, CM ; Remove support for undocumented AUTOPROMOTE64 keyword, ; 11 Jan 2010, CM ; NOTE: remember to modify CMSVLIB.PRO when changing library! ; ; $Id: cmsvread.pro,v 1.9 2010/01/11 08:58:13 craigm Exp $ ; ;- ; Copyright (C) 2001, Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy, modify, and distribute modified or ; unmodified copies is granted, provided this copyright and disclaimer ; are included unchanged. ;-