;+ ; 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 $ ; ;- ; Copyright (C) 2000-2001, Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy, modify, and distribute modified or ; unmodified copies is granted, provided this copyright and disclaimer ; are included unchanged. ;-