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 Read gzip'ed files even if gzip is not installed W.L. October 2012