CMSV_WDATA Name
CMSV_WDATA Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Write SAVE-formatted data variable record to output block or file
Calling Sequence
CMSV_WDATA, BLOCK, POINTER, DATA, UNIT=UNIT, TEMPORARY=TEMPORARY, $
PTR_INDEX=PTR_INDEX, PTR_DATA=PTR_DATA, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
Description
CMSV_WDATA writes the data 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 raw data to the output. The initial
type descriptor portion of the record must have already been
writtenusing the CMSV_WVTYPE procedure.
Under normal circumstances a user will write variable or heap data
using the CMSV_WREC procedure.
CMSV_WDATA supports the following variable types:
BYTE(1),INT(2),LONG(3) - integer types
UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
STRING(7) - string type
STRUCT(8) - structure type
POINTER(10) - pointer type - SEE BELOW
NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED
Arrays and structures containing any of the supported types are
supported (including structures within structures).
The caller must specify in the DATA parameter, the data to be
written to output. The variable passed as DATA must have the same
type and dimensions as passed to CMSV_WVTYPE.
Unlike most of the other output routines, this procedure is able
to send its output to a file rather than to the BLOCK buffer. If
the UNIT keyword is specified then output is sent to that file
UNIT, after any pending BLOCK data is first sent. Users should
note that after such operations, the BLOCK POINTER and OFFSET
parameters may be modified (ie reset to new values).
See CMSV_WREC for instructions on how to write heap data.
[ This code assumes the record header and type descriptor have
been written with CMSV_WREC and CMSV_WVTYPE. ]
==================================================================
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 or a file. If the UNIT
keyword is specified then file is sent to the specified unit
number rather than to the buffer BLOCK. However, 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 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 or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
DATA - the data to be written, of any save-able data type.
Keywords
TEMPORARY - if set, then the input DATA are discarded after being
written, as a memory economy provision.
PTR_INDEX - a heap index array for the data being written, if any
heap data records have been written.
Default: no pointers are written
PTR_DATA - an array of pointers, pointing to the heap values being
written.
Default: no pointers are written
UNIT - a file unit. If specified then data are directed to the
file unit rather than to the buffer BLOCK.
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
Added support for byte scalars and arrays (!), 27 Mar 2006, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!