FITS_OPEN
Name
FITS_OPEN
Purpose
Opens a FITS (Flexible Image Transport System) data file.
Explanation
Used by FITS_READ and FITS_WRITE
Calling Sequence
FITS_OPEN, filename, fcb
Inputs
filename : name of the FITS file to open, scalar string
FITS_OPEN can also open gzip compressed (.gz) file *for
reading only*, although there is a performance penalty
FPACK ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ )
compressed FITS files can be read provided that the FPACK
software is installed.
Outputs
fcb : (FITS Control Block) a IDL structure containing information
concerning the file. It is an input to FITS_READ, FITS_WRITE
FITS_CLOSE and MODFITS.
Input Keyword Parameters
/APPEND: Set to append to an existing file.
/FPACK - Signal that the file is compressed with the FPACK software.
http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default,
FITS_OPEN assumes that if the file name extension ends in
.fz that it is fpack compressed. The FPACK software must
be installed on the system
/HPRINT - print headers with routine HPRINT as they are read.
(useful for debugging a strange file)
/NO_ABORT: Set to quietly return to calling program when an I/O error
is encountered, and return a non-null string
(containing the error message) in the keyword MESSAGE.
If /NO_ABORT not set, then FITS_OPEN will display the error
message and return to the calling program.
/UPDATE Set this keyword to open an existing file for update
/WRITE: Set this keyword to open a new file for writing.
Output Keyword Parameters
MESSAGE = value: Output error message. If the FITS file was opened
successfully, then message = ''.
Notes
The output FCB should be passed to the other FITS routines (FITS_OPEN,
FITS_READ, FITS_HELP, and FITS_WRITE). It has the following structure
when FITS_OPEN is called without /WRITE or /APPEND keywords set.
FCB.FILENAME - name of the input file
.UNIT - unit number the file is opened to
.FCOMPRESS - 1 if unit is a FPACK compressed file opened with
a pipe to SPAWN
.NEXTEND - number of extensions in the file.
.XTENSION - string array giving the extension type for each
extension.
.EXTNAME - string array giving the extension name for each
extension. (null string if not defined the extension)
.EXTVER - vector of extension version numbers (0 if not
defined)
.EXTLEVEL - vector of extension levels (0 if not defined)
.GCOUNT - vector with the number of groups in each extension.
.PCOUNT - vector with parameter count for each group
.BITPIX - BITPIX for each extension with values
8 byte data
16 short word integers
32 long word integers
-32 IEEE floating point
-64 IEEE double precision floating point
.NAXIS - number of axes for each extension. (0 for null data
units)
.AXIS - 2-D array where axis(*,N) gives the size of each axes
for extension N
.START_HEADER - vector giving the starting byte in the file
where each extension header begins
.START_DATA - vector giving the starting byte in the file
where the data for each extension begins
.HMAIN - keyword parameters (less standard required FITS
keywords) for the primary data unit.
.OPEN_FOR_WRITE - flag (0= open for read, 1=open for write,
2=open for update)
.LAST_EXTENSION - last extension number read.
.RANDOM_GROUPS - 1 if the PDU is random groups format,
0 otherwise
.NBYTES - total number of (uncompressed) bytes in the FITS file
When FITS open is called with the /WRITE or /APPEND option, FCB
contains:
FCB.FILENAME - name of the input file
.UNIT - unit number the file is opened to
.NEXTEND - number of extensions in the file.
.OPEN_FOR_WRITE - flag (1=open for write, 2=open for append
3=open for update)
Examples
Open a FITS file for reading:
FITS_OPEN,'myfile.fits',fcb
Open a new FITS file for output:
FITS_OPEN,'newfile.fits',fcb,/write
Procedures Used
GET_PIPE_FILESIZE (for Fcompress'ed files) HPRINT, SXDELPAR, SXPAR()
History
Written by: D. Lindler August, 1995
July, 1996 NICMOS Modified to allow open for overwrite
to allow primary header to be modified
DJL Oct. 15, 1996 corrected to properly extend AXIS when more
than 100 extensions present
Converted to IDL V5.0 W. Landsman September 1997
Use Message = '' rather than !ERR =1 as preferred signal of normal
operation W. Landsman November 2000
Lindler, Dec, 2001, Modified to use 64 bit words for storing byte
positions within the file to allow support for very large
files
Work with gzip compressed files W. Landsman January 2003
Fix gzip compress for V5.4 and earlier W.Landsman/M.Fitzgerald Dec 2003
Assume since V5.3 (STRSPLIT, OPENR,/COMPRESS) W. Landsman Feb 2004
Treat FTZ extension as gzip compressed W. Landsman Sep 2004
Assume since V5.4 fstat.compress available W. Landsman Apr 2006
FCB.Filename now expands any wildcards W. Landsman July 2006
Make ndata 64bit for very large files B. Garwood/W. Landsman Sep 2006
Open with /SWAP_IF_LITTLE_ENDIAN, remove obsolete keywords to OPEN
W. Landsman Sep 2006
Warn that one cannot open a compressed file for update W.L. April 2007
Use post-V6.0 notation W.L. October 2010
Support FPACK compressed files, new .FCOMPRESS tag to FCB structure
W.L. December 2010