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!