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_RREC

CMSV_RREC

CMSV_RREC

Name


  CMSV_RREC

Author


  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
  craigm@lheamail.gsfc.nasa.gov

Purpose


  Read SAVE-formatted record header from input block or file unit

Calling Sequence


  CMSV_RREC, BLOCK, POINTER, DATA, UNIT=UNIT, $
        BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME, NEXT_BLOCK=NEXT_BLOCK, $
        INITIALIZE=INITIALIZE, FULL=FULL, PROMOTE64=PROMOTE64, $
        OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
 

Description



  This procedure reads the header of an IDL SAVE record. The header
  consists of four bytes at the beginning of each record which
  indentifies the type and size of the record. This procedure also
  additionally reads many full records as noted below.
  Users can determine the block type by examining the values
  returned in the BLOCK_TYPE and BLOCK_NAME keywords. The following
  values are supported. Some record types contain additional data.
  CMSV_RREC reads some of these record types automatically (those
  entries below marked with [this procedure]). Other records do not
  contain any additional data at all (those entries marked with an
  [empty]), and thus require no further processing.
    BLOCK_TYPE BLOCK_TYPE READ RECORD DATA WITH...
      0 = 'START_MARKER' [empty]
      1 = 'COMMON_BLOCK' [this procedure]
      2 = 'VARIABLE' CMSV_RVTYPE / CMSV_RDATA
      3 = 'SYSTEM_VARIABLE' CMSV_RVTYPE / CMSV_RDATA
      6 = 'END_MARKER' [empty]
      10 = 'TIMESTAMP' [this procedure]
      12 = 'COMPILED' no published procedure
      13 = 'IDENTIFICATION' [this procedure]
      14 = 'VERSION' [this procedure]
      15 = 'HEAP_INDEX' [this procedure]
      16 = 'HEAP_DATA' CMSV_RVTYPE
      17 = 'PROMOTE64' [empty]
      19 = 'NOTICE' [this procedure]
  For records that contain variable data, the external procedures
  CMSV_RVTYPE and CMSV_RDATA must be used, as noted above.
  Otherwise CMSV_RREC will read and convert the appropriate data
  automatically and return it in the DATA positional parameter.
  The offset of the next record is returned in the NEXT_BLOCK
  keyword. For file input, the command, "POINT_LUN, UNIT,
  NEXT_BLOCK" will position the file pointer to the next block.
  Users should be aware that the SAVE files produced by IDL version
  5.4 appear to have a different header format. The new header size
  is five bytes, and is incompatible with the older format. In
  order to activate the longer header size, the PROMOTE64 keyword
  must be set.
  By default the entire record is not read from the file at once.
  Users that wish to operate on the entire record immediately should
  set the FULL keyword.
  After issuing a POINT_LUN the block cache in BLOCK must be reset
  using the /INITIALIZE keyword.
  ==================================================================
  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.
  ==================================================================
  SPECIFIC RECORD TYPES
  CMSV_RREC reads certain specific record types automatically and
  returns the data in the positional parameter data. Users should
  pass a named variable in this parameter to retrieve the return
  value.
  When a record of type 'VERSION' (14) is encountered, it is read,
  and returned as a structure. The returned data are of the form:
        { FORMAT_VERSION: 0L, $ ; Format version number of file
          ARCH: '', $ ; !VERSION.ARCH of creating host
          OS: '', $ ; !VERSION.OS of creating host
          RELEASE: '' } ; !VERSION.RELEASE of creating host
  When a record of type 'TIMESTAMP' (10) is encountered, it is read,
  and returned as a structure. The returned data are of the form:
          { SAVE_DATE: '', $ ; Date the save file was created
            SAVE_USER: '', $ ; User name who created file
            SAVE_HOST: '' } ; Host name that created file
  Save files created by IDL version 4 do not contain a timestamp
  record.
  When a record of type 'IDENTIFICATION' (13) is encountered, it is
  read, and returned as a structure. The returned data are of the
  form:
          { AUTHOR: '', $ ; Author of SAVE file
            TITLE: '', $ ; Title of SAVE file
            IDCODE: '' } ; Identifying code for SAVE file
  It appears that this record is not used in IDL version 5 or later.
  When a record of type 'COMMON_BLOCK' (1) is encountered, it is
  read and returned. A common block descriptor consists of an array
  of strings whose first element is the common block name, and whose
  remaining elements are the common block variable names. No
  variable data are stored with the common block definition.
  When a record of type 'HEAP_INDEX' (15) is encountered, it is read
  and returned in DATA. The heap index specifies a list of which
  heap variables are stored in the current save file. These indices
  are simply numbers which identify each heap variable (i.e.,
  "<PtrHeapVar2>" would have an index of 2). Users should note that
  the heap index will not necessarily be sequentially increasing,
  and may have gaps.
  When a record of type 'NOTICE' (19) is encountered, it is read and
  returned in DATA. It is a structure with one field: {TEXT: ''},
  where TEXT is the text content of the notice.
  Users should consult CMSV_RDATA for instructions on how to read
  heap data.
 
  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.

Keywords



  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)
  BLOCK_TYPE - upon return, the numeric record type, as described
                above.
  BLOCK_NAME - upon return, a scalar string specifying the record
                type, as specified above.
  NEXT_BLOCK - upon return, file offset of the next record in the
                file.
  INITIALIZE - if set, then BLOCK and POINTER are initialized to a
                pristine state. All data in these two variables is
                lost before reading the next record.
  FULL - if set, then the entire record will be read into BLOCK.
  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
  Fix typo for RHEAP call, CM, 21 Apr 2001
  Added notification about RSI License, 13 May 2002, CM
  Added NOTICE record type, 09 Jun 2003, CM
  Read record header as ULONG, 26 Sep 2009, CM
  Bug fix to previous change, 22 Nov 2009, CM
  Support for newer IDL 64-bit files which use a
    "standard" record header size and a previously unused
    field, 11 Jan 2010, CM
  NOTE: remember to modify CMSVLIB.PRO when changing library!
  $Id: cmsv_rrec.pro,v 1.15 2010/01/11 08:58:13 craigm Exp $



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