; This IDL module contains two functions for retrieving or displaying the full
; contents of a FITS binary table file.  get_fits returns a structure for one
; HDU with the header in an ASCII string array, and all of the column arrays
; labled by column name.  show_fits displays the HDU, keyword, and column tree
; with keyword values.  Only column formats are shown since their arrays can be
; quite long.

; To run from the IDL prompt:
; IDL> .RUN get_fits
; IDL> path = '/home/gbtdata/AGBT02A_069_01/SpectralProcessor/'
; IDL> ft = get_fits(path + '2003_06_17_09:22:34.fits', 1)
; IDL> show_fits, path + '2003_06_17_09:22:34.fits'

; This routine returns a structure of the specified HDU containing the header
; as a string array, and all of the colums in an array of anonymous structures
; with each structure member labeled by the column name. Keyword values in
; the header string array keyword elements must be parsed with the fxpar()
; function.  An HDU structure is retrieved with
;     ft = get_fits(path + '2003_06_17_09:22:34.fits', 1)
; The extension name may be retrieved with
;     extname = ft.name
; The header string array may be retrieved with
;     hdr = ft.header
; To get a specific keyword value use
;     utcstop = fxpar(ft.header, 'UTCSTOP')
; The number of structures (table rows) in the binary table structure array is
;     sz = size(ft.table)
;     num_rows = sz(1)
; To find the column names in the table use
;     help, /structures, ft.table
; To get the contents of, for example, row 1 of the 'DATA' column use
;     dat = ft.table(1).DATA
; Valid HDU numbers run from 1 to the number of HDU's in the file.  The main
; header (HDU 0) may be retrieved with the headfits() function.

function get_fits, file_path, hdu_num

    res = mrdfits(file_path, hdu_num, hdr, /silent, STATUS=status)
    if status EQ 0 then begin
	extname = fxpar(hdr, 'EXTNAME')
	return, { name: extname, header: hdr, table: res }
    endif else begin
	return, 0
    endelse
end

; show_fits displays the HDU headers and table column structure for a
; specified FITS file

pro show_fits, file_path

    mhdr = headfits(file_path)
    print, '---------------- Main Header ----------------'
    sz = size(mhdr)
    num_lines = sz(1)
    for i = 0, num_lines - 1, 1 do begin
	if ((strpos(mhdr(i), 'SIMPLE') NE 0) AND $
	    (strpos(mhdr(i), 'END') NE 0) AND $
	    (strpos(mhdr(i), 'BITPIX') NE 0) AND $
	    (strpos(mhdr(i), 'EXTEND') NE 0) AND $
	    (strpos(mhdr(i), 'NAXIS') NE 0) AND $
	    (strpos(mhdr(i), 'COMMENT') NE 0)) then print, mhdr(i)
    endfor
    hdu_num = 1
    repeat begin
	res = mrdfits(file_path, hdu_num, hdr, /silent, STATUS=status)
	if status EQ 0 then begin
	    extname = fxpar(hdr, 'EXTNAME')
	    print, ''
	    hn = strtrim(string(hdu_num), 2)
	    print, '--------------- HDU ', hn, ' ', extname, ' ---------------'
	    sz = size(hdr)
	    num_lines = sz(1)
	    for i = 0, num_lines - 1, 1 do begin
		if ((strpos(hdr(i), 'XTENSION') NE 0) AND $
		    (strpos(hdr(i), 'END') NE 0) AND $
		    (strpos(hdr(i), 'PCOUNT') NE 0) AND $
		    (strpos(hdr(i), 'GCOUNT') NE 0) AND $
		    (strpos(hdr(i), 'TTYPE') NE 0) AND $
		    (strpos(hdr(i), 'TFORM') NE 0) AND $
		    (strpos(hdr(i), 'EXTNAME') NE 0) AND $
		    (strpos(hdr(i), 'COMMENT') NE 0)) then print, hdr(i)
	    endfor
	    sz = size(res)
	    num_rows = sz(1)
	    nr = strtrim(string(num_rows), 2)
	    print, '  ', nr, ' table rows, each with the following structure:'
	    help, /structures, res
	endif
	hdu_num = hdu_num + 1
    endrep until status LT 0
end