>  Docs Center  >  Libraries  >  Markwardt  >  CMSV_WDATA






  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770


  Write SAVE-formatted data variable record to output block or file

Calling Sequence



  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.
  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:
  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.


  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.


  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
              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.


See Also


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!

© 2020 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us