CMSV_RRAW Name
CMSV_RRAW
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Read raw SAVE data from input block or file unit
Calling Sequence
DATA = CMSV_RRAW( BLOCK, POINTER, NELT, UNIT=UNIT, $
STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG )
Description
This function reads raw integer or string data from an IDL SAVE
file. This is the lowest level reading function in the library,
intended for developers who are investigating new and existing
SAVE file formats.
The primary use of this function will be to read raw integer and
string data from the input. By default, a single value is read as
a scalar; however a vector of values can be read using the NELT
parameter. Special keywords are provided for the common data
types STRING, LONG and BYTE. Other integer types can be read
using the TYPE keyword. Users who want to read the data from an
IDL variable should use CMSV_RDATA, which can handle
multidimensional data, as well as floating point and structure
data.
A secondary use of this function is to buffer the data in BLOCK.
This will ensure that BLOCK contains enough data to convert NELT
integers without reading from disk. CMSV_RRAW itself does not
convert any values so the return value should be ignored.
==================================================================
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.
NELT - optional parameter specifying the number of values to read.
If unspecified, then a scalar value is read and returned.
If specified, then a vector of NELT values is read and
returned.
Keywords
BUFFER - if set, CMSV_RRAW will ensure that BLOCK contains at
least NELT values without converting them. The return
value should be ignored. This keyword is ignored for
strings.
LONG - if set, the values are converted as LONG integers.
BYTE - if set, the values are converted as BYTEs.
STRING - if set, the values are converted as STRINGs. Each string
may be of variable length.
TYPE - if none of the above keywords is set, then values of type
TYPE are read. TYPE should be a string, one of 'BYTE',
'FIX', 'LONG', 'ULONG', 'LONG64', or 'ULONG64'.
If no type is specified then BYTEs are read.
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 used by this routine)
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!