CMSV_OPEN Name
CMSV_OPEN
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Open IDL SAVE file for reading or writing
Calling Sequence
CMSV_OPEN, UNIT, FILENAME, OFFSET, $
ACCESS=ACCESS, /FORCE, /GET_LUN, /REOPEN, $
COMPATIBILITY=COMPATIBILITY, $
STATUS=STATUS, ERRMSG=ERRMSG
Description
CMSV_OPEN opens an IDL SAVE-formatted file for reading or writing.
The mode of operation is controlled by the ACCESS keyword, which
may be either 'R' for reading, 'W' for writing, or 'RW' for
read/write access.
'R': In the case of reading, the specified file is opened with
read-only access, and the first bytes are examined to verify that
it is indeed a valid IDL SAVE file.
'W': In the case of writing, the specified file is opened with
write access, and the initial file signature is written.
'RW': In the case of read-write access, the file must already
exist as a valid SAVE file. Users are advised that every time
they switch between reading and writing operations, they must use
POINT_LUN to flush the file buffers.
The CMSVLIB routines do not support file sizes greater than 2 GB,
nor SAVE files created with the COMPRESS option.
Upon return, the file pointer is positioned at the start of the
first valid SAVE record. The file offset is returned in OFFSET.
The user is responsible for reading or writing the remainder of
the file with other library routines.
The file unit is determined based on the following criteria. This
behavior is similar to the OPEN family of procedures, except for
the REOPEN keyword.
* If REOPEN is set then it is assumed that UNIT is an
already-open file, and FILENAME is ignored.
* If GET_LUN is set then a file unit is allocated with GET_LUN,
and upon success this unit is returned in UNIT.
* Otherwise it is asssumed that UNIT is a valid but unopened
file unit. Upon successful return, UNIT is opened.
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.
==================================================================
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.
==================================================================
Inputs
UNIT - a logical unit number (a scalar). In the case of GET_LUN,
a file unit will be allocated and returned in UNIT. In the
default case, or REOPEN, UNIT must be a valid file unit
upon input. For REOPEN the corresponding file must be
seekable.
FILENAME - a scalar string specifying the filename path (ignored
for REOPEN).
OFFSET - upon return, the file offset of the next available SAVE
record.
Keywords
ACCESS - a scalar string, case insensitive:
'R' - read-only access
'W' - write access (new file)
'RW' - read-write access (existing file)
Default: 'R' - read-only
GET_LUN - if set, the file unit is allocated using GET_LUN
FORCE - if set, then the file is opened despite a detected file
format inconsistency.
REOPEN - if set, then an already-opened file is manipulated. The
valid file unit must be specified by UNIT, and FILENAME
is ignored.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
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
Change BLOCK to STREAM to support VMS properly, 14 Feb 2001, CM
Added notification about RSI License, 13 May 2002, CM
NOTE: remember to modify CMSVLIB.PRO when changing library!