;+ ; NAME: ; CMSV_WVTYPE ; ; AUTHOR: ; Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 ; craigm@lheamail.gsfc.nasa.gov ; ; PURPOSE: ; Write variable type information to output block ; ; CALLING SEQUENCE: ; CMSV_WVTYPE, BLOCK, DATA, IDENT, $ ; HEAP=HEAP, SYSTEM=SYSTEM, UNIT=UNIT, $ ; OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG ; ; DESCRIPTION: ; ; CMSV_WVTYPE writes the type 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 type descriptor based on a ; variable passed by the user. Once the type descriptor has been ; written, the data portion can be written using the CMSV_WDATA ; procedure. ; ; CMSV_WVTYPE should recognize and correctly output type descriptors ; for all currently known IDL data types, except for object ; references. Type information is inferred from the DATA parameter ; passed by the user. ; ; Heap data is a special case, since the data itself are stored ; separately from the pointer in the SAVE file. Three steps must be ; satisfied: a HEAP_INDEX record must be written; a valid HEAP_DATA ; record must be written containing a type descriptor (written with ; this procedure) and the heap data; and the named pointer itself ; must be written. ; ; ; ================================================================== ; 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 only. 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 written 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 written ; from BLOCK. CMSVLIB routines will automatically advance ; the pointer. ; ; DATA - the data to be written, of any save-able data type. ; ; IDENT - for variables, the name of the variable as a string; for ; heap data, the heap index as an integer. ; ; KEYWORDS: ; ; HEAP - if set, the data is treated as heap data, and IDENT must be ; an integer heap index. ; ; SYSTEM - if set, the data is assumed to be a system variable. ; ; UNIT - a file unit. Currently ignored. ; ; 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 ; NOTE: remember to modify CMSVLIB.PRO when changing library! ; ; $Id: cmsv_wvtype.pro,v 1.14 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. ;-