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_WDATA

CMSV_WDATA

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
  Bug fix for multi-dimensional byte array, 2013-04-18, CM
  NOTE: remember to modify CMSVLIB.PRO when changing library!
  $Id: cmsv_wdata.pro,v 1.11 2013/04/18 19:14:08 cmarkwar Exp $



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