idlastro / FITS I/O: FITS_OPEN

[Source code]

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) files or Unix
           compressed files *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
Read gzip'ed files even if gzip is not installed W.L. October 2012
Handle axis sizes requiring 64 integer W.L.  April 2014
Support for .Z compressed files M. Zechmeister/W.L.  April 2014
Wrap filenames in "" when spawning subprocesses, to handle paths
with spaces or other atypical characters. M. Perrin Nov 2014