CMSV_WVTYPE Name
CMSV_WVTYPE Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Write variable type information to output block
Calling Sequence
CMSV_WVTYPE, BLOCK, DATA, IDENT, $
HEAP=HEAP, SYSTEM=SYSTEM, UNIT=UNIT, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
Description
CMSV_WVTYPE writes 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 writes the type descriptor based on a
variable passed by the user. Once the type descriptor has been
written, the data portion can be written using the CMSV_WDATA
procedure.
CMSV_WVTYPE should recognize and correctly output type descriptors
for all currently known IDL data types, except for object
references. Type information is inferred from the DATA parameter
passed by the user.
Heap data is a special case, since the data itself are stored
separately from the pointer in the SAVE file. Three steps must be
satisfied: a HEAP_INDEX record must be written; a valid HEAP_DATA
record must be written containing a type descriptor (written with
this procedure) and the heap data; and the named pointer itself
must be written.
==================================================================
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 writes data to a byte array only. The intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
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 written 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 or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be written
from BLOCK. CMSVLIB routines will automatically advance
the pointer.
DATA - the data to be written, of any save-able data type.
IDENT - for variables, the name of the variable as a string; for
heap data, the heap index as an integer.
Keywords
HEAP - if set, the data is treated as heap data, and IDENT must be
an integer heap index.
SYSTEM - if set, the data is assumed to be a system variable.
UNIT - a file unit. Currently ignored.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
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
NOTE: remember to modify CMSVLIB.PRO when changing library!