CMSV_WRAW Name
CMSV_WRAW
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Write raw SAVE data to output block
Calling Sequence
CMSV_WRAW, BLOCK, POINTER, DATA, UNIT=UNIT, $
STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
Description
This procedure writes raw integer or string data to an IDL SAVE
block in memory. This is the lowest level writing function in the
library, intended for developers who are investigating new and
existing SAVE file formats.
The data to be written is specified by the DATA parameter. The
data must be of type BYTE, LONG or STRING, and the type is
determined automatically from the data itself. [ The mnemonic
STRING LONG and BYTE keywords are accepted for programming clarity
but ignored. ]
This procedure accepts but currently ignores the UNIT keyword. It
is the caller's responsibility to write the BLOCK data to disk
when appropriate.
==================================================================
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. Must of type STRING, BYTE or LONG.
Keywords
LONG - ignored (to be used for clarity)
BYTE - ignored (to be used for clarity)
STRING - ignored (to be used for clarity)
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
Fixed bug in writing of empty strings, 28 Mar 2006, CM
Fixed bug when writing strings >128 characters, 2012-04-05, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!