Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


Harris Geospatial / Docs Center / Libraries / Markwardt / CMSV_RRAW

CMSV_RRAW

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!
  $Id: cmsv_rraw.pro,v 1.7 2009/11/22 22:50:49 craigm Exp $



© 2017 Exelis Visual Information Solutions, Inc. |  Legal
My Account    |    Buy    |    Contact Us