=pod

=head1 NAME



B<funhead - display a header in a Funtools file>



=head1 SYNOPSIS





funhead  [-a] [-s] [-t] [-L] <iname> [oname ename]





=head1 OPTIONS





  -a    # display all extension headers
  -s    # display 79 chars instead of 80 before the new-line
  -t    # prepend data type char to each line of output
  -L    # output in rdb/starbase list format




=head1 DESCRIPTION




B<funhead> displays the FITS header parameters in the specified 
FITS Extension.

The first argument to the program specifies the Funtools input file
to display.  If "stdin" is specified, data are read from
the standard input. Funtools Bracket
Notation is used to specify particular FITS extension to process.
Normally, the full 80 characters of each header card is output,
followed by a new-line. 


If the B<-a> switch is specified, the header from each FITS
extensions in the file is displayed. Note, however, that the B<-a>
switch does not work with FITS files input via stdin. We hope to
remove this restriction in a future release.


If the B<-s> switch is specified, only 79 characters are output
before the new-line. This helps the display on 80 character terminals.


If the B<-t> switch is specified, the data type of the parameter
is output as a one character prefix, followed by 77 characters of the
param.  The parameter data types are defined as: FUN_PAR_UNKNOWN
('u'), FUN_PAR_COMMENT ('c'), FUN_PAR_LOGICAL ('l'), FUN_PAR_INTEGER
('i'), FUN_PAR_STRING ('s'), FUN_PAR_REAL ('r'), FUN_PAR_COMPLEX ('x').


If the B<-L> (rdb table) switch is used, the output will conform
to starbase/rdb data base list format.


For example to display the EVENTS extension (binary table):

  [sh] funhead "foo.fits[EVENTS]"
  XTENSION= 'BINTABLE'            /  FITS 3D BINARY TABLE                      
  BITPIX  =                    8  /  Binary data                               
  NAXIS   =                    2  /  Table is a matrix                         
  NAXIS1  =                   20  /  Width of table in bytes                   
  NAXIS2  =                30760  /  Number of entries in table                
  PCOUNT  =                    0  /  Random parameter count                    
  GCOUNT  =                    1  /  Group count                               
  TFIELDS =                    7  /  Number of fields in each row              
  EXTNAME = 'EVENTS  '            /  Table name                                
  EXTVER  =                    1  /  Version number of table                   
  TFORM1  = '1I      '            /  Data type for field                       
  TTYPE1  = 'X       '            /  Label for field                           
  TUNIT1  = '        '            /  Physical units for field                  
  TFORM2  = '1I      '            /  Data type for field                       
    etc. ...
  END                                                                          



To display the third header:

  [sh] funhead "foo.fits[3]"
  XTENSION= 'BINTABLE'            /  FITS 3D BINARY TABLE                      
  BITPIX  =                    8  /  Binary data                               
  NAXIS   =                    2  /  Table is a matrix                         
  NAXIS1  =                   32  /  Width of table in bytes                   
  NAXIS2  =                   40  /  Number of entries in table                
  PCOUNT  =                    0  /  Random parameter count                    
  GCOUNT  =                    1  /  Group count                               
  TFIELDS =                    7  /  Number of fields in each row              
  EXTNAME = 'TGR     '            /  Table name                                
  EXTVER  =                    1  /  Version number of table                   
  TFORM1  = '1D      '            /  Data type for field                       
    etc. ...
  END                                                                          



To display the primary header (i.e., extension 0):

  sh> funhead "coma.fits[0]"
  SIMPLE  =                    T /STANDARD FITS FORMAT                         
  BITPIX  =                   16 /2-BYTE TWOS-COMPL INTEGER                    
  NAXIS   =                    2 /NUMBER OF AXES                               
  NAXIS1  =                  800 /                                             
  NAXIS2  =                  800 /                                             
  DATATYPE= 'INTEGER*2'          /SHORT INTEGER                                
  END                                                                          



The funhead program also can edit (i.e. add, delete, or modify) or
display individual headers parameters. Edit mode is signalled by the
presence of two additional command-line arguments: output file and
edit command file, in that order. Edit mode acts as a filter: the
output file will contain the entire input FITS file, including other
extensions. The edit command file can be "stdin", in which case edit
command are read from the standard input.


The edit command file contains parameter comments (having '#' in the
first column) and delete and assignment(modify or add) operations.  A
delete operation is specified by preceding the parameter name with a
minus sign "-".  A display operation (very useful in interactive
sessions, i.e., where the edit commands are taken from stdin) is
specified by preceding the parameter name with a question mark "?". In
either case, a parameter value need not be specified.  An assignment
operation is specified in the same two ways that a parameter is
specified in a text header (but without the comment character that
precedes header params), i.e.:



=over 4




=item *

FITS-style comments have an equal sign "=" between the keyword and
value and an optional slash "/" to signify a comment. The strict FITS
rules on column positions are not enforced.



=item *

Free-form comments can have an optional colon separator between the
keyword and value. In the absence of quote, all tokens after the
keyword are part of the value, i.e. no comment is allowed.


=back




For example, the following interactive session checks for the
existence of parameters, adds new parameters, modifies them, and
modifies and deletes existing parameters:

  sh$ ./funhead snr.ev foo.fits -
  # look for FOO1
  ? FOO1
  WARNING: FOO1 not found
  # add new foo1
  FOO1 = 100
  # add foo2
  FOO2 = 200
  # reset foo1 to a different value
  FOO1 -1
  # delete foo2
  -FOO2
  # change existing value
  EXTVER 2
  ? XS-SORT
  XS-SORT = 'EOF     '            /  type of event sort
  # delete existing value
  -XS-SORT
  # exit
  ^D



See Column-based Text Files
for more information about header parameter format.







=head1 SEE ALSO



See funtools(n) for a list of Funtools help pages


=cut
