;+
; NAME:
;   CMSV_RVTYPE
;
; AUTHOR:
;   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
;   craigm@lheamail.gsfc.nasa.gov
;
; PURPOSE:
;   Read variable type information from input block or file unit
;
; CALLING SEQUENCE:
;   CMSV_RVTYPE, BLOCK, POINTER, NAME, SIZE, UNIT=UNIT, $
;          TEMPLATE=TEMPLATE, SUFFIX=SUFFIX, $
;          /NO_CREATE, /NO_TYPE, /HEAP, /SYSTEM, $
;          STRUCTURE_NAME=STNAME, $
;          NAMED_STRUCTS=STRUCTS, NAMED_CLASSES=CLASSES, $
;          OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
;   
; DESCRIPTION: 
;
;   CMSV_RVTYPE reads the type portion of an IDL SAVE variable record.
;   An IDL variable is stored in two components: the type descriptor
;   which describes the name, type, and dimensions of the variable;
;   and the data record, which contains the raw data of the variable.
;   This procedure reads the type descriptor returns it to the user.
;   This procedure can also determine the name of a variable; the heap
;   index number of a heap variable; and other important information.
;   Once the type of the data has been determined, the data portion
;   can be read using the CMSV_RDATA procedure.
;
;   CMSV_RVTYPE should recognize and correctly return type descriptor
;   information about all known IDL data types, as of this writing.
;   It should be noted that CMSV_RDATA will not necessarily be capable
;   of reading all of these data types, but the description of the
;   data should still be readable.  Users can then use this
;   information to print a summary of the file contents for example.
;
;   The type information are normally returned in the SIZE parameter,
;   which gives the IDL variable type, and the dimensions of the
;   variable just as the IDL built-in function SIZE() would do.
;   However, in the case of structures, there is much more information
;   to convey.  To assist the user a blank template structure is
;   returned in the keyword parameter TEMPLATE, which they can then
;   pass on to CMSV_RDATA.
;
;   Users should be aware of structure and class name clashes.  The
;   problem arises because CMSV_RVTYPE must actually instantiate any
;   named structures or classes in the file.  If these named
;   structures clash with the definitions of the structures on the
;   user's local computer, then an error will result.  To prevent
;   this, the user can use the SUFFIX keyword.  If the SUFFIX keyword
;   contains a string, then this string is appended to any structure
;   names discovered in the save file, before instantiation.  Thus, as
;   long as the suffix is a unique string, there will be no clashes
;   with local structure definitions.  Users are advised to pick a
;   different suffix for *each* save file that they open.
;
;   CMSV_RVTYPE also provides some diagnostic information about the
;   variable.  Users can pass the NAMED_STRUCTS and NAMED_CLASSES
;   keywords in order to discover what named structures, classes and
;   superclasses are stored in the save file (this is especially
;   useful with the NO_TYPE keyword).  Since the contents of
;   NAMED_STRUCTS and NAMED_CLASSES are not destroyed, but appended to
;   instead, users are advised to clear these variables when opening
;   each new file.
;   
;
; ==================================================================
;   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.
; ==================================================================
;
; BLOCK, POINTER, OFFSET
;
;   This procedure can read data from a byte array, a file unit, or
;   both.  In fact, this procedure is designed to implement "lazy"
;   reading from a file, which is to say, it normally reads from a
;   byte array of data.  However, if the requested data goes beyond
;   the end of the byte array, more data is read from the file on
;   demand.  This way the user gets the benefit of fast memory access
;   for small reads, but guaranteed file access for large reads.
;
;   The terminology is as follows: BLOCK is a byte array which
;   represents a portion of, or an entire, IDL SAVE file.  The block
;   may be a cached portion of an on-disk file, or an entire in-memory
;   SAVE file.  POINTER is the current file pointer within BLOCK
;   (i.e., the next byte to be read is BLOCK[POINTER]).  Hence, a
;   POINTER value of 0 refers to the start of the block.  OFFSET is
;   the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
;   OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
;   The following diagram shows the meanings for BLOCK, POINTER and
;   OFFSET schematically:
;
;
;                 0 <-  OFFSET  -> |
;   FILE          |----------------|------*--------|--------->
;
;   BLOCK                          |------*--------|
;                                  0      ^ POINTER
;     
;
;   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:
;
;   BLOCK - a byte array, a cache of the SAVE file.  Users will
;           usually not access this array directly.  Users are advised
;           to clear BLOCK after calling POINT_LUN.
;
;   POINTER - a long integer, a pointer to the next byte to be read
;             from BLOCK.  CMSVLIB routines will automatically
;             advance the pointer.
;
;   NAME - upon return, the identifier of the variable.  For named
;          variables, NAME is a string.  For heap variables, NAME is
;          an integer heap index.
;
;   SIZE - upon return, an integers array describing the variable type
;          and size, in the same format as returned by the built-in
;          function SIZE.
;
; KEYWORDS:
;
;   TEMPLATE - upon return, if the variable is a structure, TEMPLATE
;              will contain a single blank template structure, which
;              can be used in calls to CMSV_RDATA.
;
;   NO_CREATE - if set, then do not create any template structures
;               (saves execution time and structure name clashes).
;
;   NO_TYPE - if set, do not read type information.  CMSV_RVTYPE
;             returns only the variable NAME or heap index.
;
;   HEAP - if set, then read the variable type assuming it is a heap
;          variable (a HEAP_DATA record).
;
;   SYSTEM - if set, then read the variable type assuming it is a
;            system variable (a SYSTEM_VARIABLE record).
;
;   SUFFIX - a scalar string, the suffix to be appended to any
;            structure names to force them to be unique.
;
;   STRUCTURE_NAME - upon return, if the variable is a named
;                    structure, STRUCTURE_NAME will contain the name
;                    of the structure as a string.
;
;   NAMED_CLASSES /
;   NAMED_STRUCTS - upon input, this keyword should contain an
;                   undefined or a string array value.
;
;                   If the variable contains any named structure/class
;                   definitions, CMSV_RVTYPE will append those names
;                   upon return, including any enclosed structures or
;                   superclasses.
;
;   UNIT - a file unit.  If a library routine reads to the end of
;          BLOCK, or if BLOCK is undefined, then this file UNIT will
;          be accessed for more data.  If undefined, then BLOCK must
;          contain the entire file in memory.
;
;   OFFSET - the file offset of byte zero of BLOCK.  Default: 0
;            (OFFSET is not used by this routine at this time)
;
;   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:
;
;
; SEE ALSO:
;
;   CMRESTORE, SAVE, RESTORE, CMSVLIB
;
; MODIFICATION HISTORY:
;   Written, 2000
;   Documented, 24 Jan 2001
;   Added notification about RSI License, 13 May 2002, CM
;   Avoid using reserved word INHERITS, 07 Mar 2006, CM
;   NOTE: remember to modify CMSVLIB.PRO when changing library!
;
; $Id: cmsv_rvtype.pro,v 1.13 2009/11/22 22:50:49 craigm Exp $
;
;-
; Copyright (C) 2000-2001, 2002, 2006, 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.
;-