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 / CMSV_RVTYPE

CMSV_RVTYPE

CMSV_RVTYPE

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 $



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