idlastro / FITS I/O: FITSDIR

[Source code]

NAME
FITSDIR 
PURPOSE
Display selected FITS keywords from the headers of FITS files.   
EXPLANATION
The values of either user-specified or default FITS keywords are 
displayed in either the primary header and/or the first extension header.
Unless the /NOSIZE keyword is set, the data size is also displayed.
The default keywords are as follows (with keywords in 2nd row used if
those in the first row not found, and the 3rd row if neither the keywords
in the first or second rows found:)
DATE-OBS     TELESCOP   OBJECT    EXPTIME       
TDATEOBS     TELNAME    TARGNAME  INTEG        ;First Alternative
DATE         OBSERVAT             EXPOSURE     ;Second Alternative
             INSTRUME             EXPTIM       ;Third Alternative
 FITSDIR will also recognize gzip compressed files (must have a .gz 
 or FTZ extension).
CALLING SEQUENCE
FITSDIR , [ directory, TEXTOUT =, EXTEN=, KEYWORDS=, /NOSIZE, /NoTELESCOPE
                       ALT1_KEYWORDS= ,ALT2_KEYWORDS = ,ALT3_KEYWORDS =  
OPTIONAL INPUT PARAMETERS
DIRECTORY - Scalar string giving file name, disk or directory to be 
        searched.   Wildcard file names are allowed.    Examples of 
        valid names include 'iraf/*.fits' (Unix) or 'd:\myfiles\f*.fits',
        (Windows).  
OPTIONAL KEYWORD INPUT PARAMETER
KEYWORDS - FITS keywords to display, as either a vector of strings or as
           a comma delimited scalar string, e.g.'testname,dewar,filter'
           If not supplied, then the default keywords are 'DATE-OBS',
           'TELESCOP','OBJECT','EXPTIME'
ALT1_KEYWORDS - A list (either a vector of strings or a comma delimited
           strings of alternative keywords to use if the default 
           KEYWORDS cannot be found.   By default, 'TDATEOBS', is the 
           alternative to DATE-OBS, 'TELNAME' for 'TELESCOP','TARGNAME'
           for 'OBJECT', and 'INTEG' for EXPTIME
ALT2_KEYWORDS - A list (either a vector of strings or a comma delimited
           strings of alternative keywords to use if neither KEYWORDS 
           nor ALT1_KEYWORDS can be found.    
ALT3_KEYWORDS - A list (either a vector of strings or a comma delimited
           strings of alternative keywords to use if neither KEYWORDS 
           nor ALT1_KEYWORDS nor ALT2_KEYWORDS can be found.    
/NOSIZE - if set then information about the image size is not displayed  
TEXTOUT - Controls output device as described in TEXTOPEN procedure
         textout=1       TERMINAL using /more option
         textout=2       TERMINAL without /more option
         textout=3       .prt
         textout=4       laser.tmp
         textout=5       user must open file
         textout=7       Append to existing .prt file
         textout = filename (default extension of .prt)
 EXTEN - Specifies an extension number (/EXTEN works for first extension)
         which is checked for the  desired keywords.      FITSDIR searches
         both the extension header and the primary header when an extension
         number is specified.
 /NOTELESCOPE - If set, then if the default keywords are used, then the
          TELESCOPE (or TELNAME, OBSERVAT, INSTRUME) keywords are omitted
          to give more room for display other keywords.   The /NOTELESCOP
           keyword has no effect if the default keywords are not used.
OUTPUT PARAMETERS
None.
EXAMPLES
(1) Print info on all'*.fits' files in the current  directory using default
        keywords.   Include information from the first extension    
     IDL> fitsdir,/exten
(2) Write a driver program to display selected keywords in HST/ACS drizzled
     (*drz) images
       pro acsdir
      keywords = 'date-obs,targname,detector,filter1,filter2,exptime'
      fitsdir,'*drz.fits',key=keywords,/exten
      return & end
 (3)  Write info on all *.fits files in the Unix directory /usr2/smith, to a 
     file 'smith.txt' using the default keywords, but don't display the value
      of the TELESCOPE keyword
     IDL> fitsdir ,'/usr2/smith/*.fits',t='smith.txt', /NoTel 
PROCEDURE
FILE_SEARCH() is used to find the specified FITS files.   The 
header of each file is read, and the selected keywords are extracted.
The formatting is adjusted so that no value is truncated on display.        
SYSTEM VARIABLES
TEXTOPEN (called by FITSDIR) will automatically define the following 
non-standard system variables if they are not previously defined:
DEFSYSV,'!TEXTOUT',1
DEFSYSV,'!TEXTUNIT',0
PROCEDURES USED
FDECOMP, FXMOVE(), MRD_HREAD, REMCHAR, SPEC_DIR(), TEXTOPEN, TEXTCLOSE
MODIFICATION HISTORY
Written, W. Landsman,  HSTX    February, 1993
Search alternate keyword names    W.Landsman    October 1998
Avoid integer truncation for NAXISi >32767  W. Landsman  July 2000
Don't leave open unit    W. Landsman  July 2000 
Added EXTEN keyword, work with compressed files, additional alternate
keywords W. Landsman     December 2000
Don't assume floating pt. exposure time W. Landsman   September 2001
Major rewrite, KEYWORD & ALT*_KEYWORDS keywords, no truncation, 
      /NOSIZE keyword     W. Landsman,  SSAI   August 2002
Assume V5.3 or later W. Landsman November 2002
Fix case where no keywords supplied  W. Landsman January 2003
NAXIS* values must be integers W. Landsman SSAI  June 2003
Trim spaces off of input KEYWORD values W. Landsman March 2004
Treat .FTZ extension as gzip compressed  W. Landsman September 2004
Assume since V5.5, file_search() available W. Landsman Aug 2006
Don't assume all images compressed or uncompressed W. L. Apr 2010
Use V6.0 notation W.L. Feb 2011
Don't let a corrupted file cause an abort    W.L. Feb 2014
Let textopen.pro define !TEXTUNIT            W.L. Sep 2016