; EGETHEAD
;---------------------------------------------------------------
;! returns parameter value from image header and error code
;# Verb Catalog
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2000, 2003, 2005
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
EGETHEAD  LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
EGETHEAD:  Verb to read image header parameters into adverbs.
USERID     -32000.0     32000.0    User ID.  0 => current user
                                     32000 => any user
INNAME                             Image name(name).
INCLASS                            Image name(class).
INSEQ           0.0      9999.0    Image name(seq. #). 0=>high
INDISK          0.0         9.0    Disk drive #. 0=>any
KEYWORD                            Name of header parameter.
                                   See EXPLAIN GETHEAD for list.
         @     Output:adverbs
KEYVALUE @                         Value of a numeric parm. =
         @                         KEYVALUE(1) + KEYVALUE(2).
KEYSTRNG @                         Value of a character-valued
         @                         parameter.
ERROR    @                         > 0 => error (e.g. keyword
         @                         not present)
----------------------------------------------------------------
EGETHEAD
Type: Verb
Use:  EGETHEAD is used to read the contents of the parameters in the
      header into POPS adverbs.  It may be used on any kind of image
      or uv data set.  It differs from GETHEAD in that missing
      keywords cause ERROR to be set rather than an error exception to
      be raised.
Adverbs:
  USERID......User ID of owner of image.  0 => current user
                32000 => any users
  INNAME......Image name(name).   Standard defaults.
  INCLASS.....Image name(class).  Standard defaults.
  INSEQ.......Image name(seq. #).  0 => highest.
  INDISK......Disk drive # of image.  0 => any
  KEYWORD.....The FITS name of the parameter.  No default.
              See EXPLAIN GETHEAD for list.  Minimum match is
              supported.
Output adverbs:
  KEYVALUE....The value of a numeric parameter is returned as
              KEYVALUE(1) + KEYVALUE(2).  The second term will be
              non-zero only for double precision parameters and will
              be small.
  KEYSTRNG....The value of a character parameter.
  ERROR.......> 0 => error, <= 0 => worked fine.
----------------------------------------------------------------
EGETHEAD

                            PURPOSE

     EGETHEAD provides read access to essentially all parameters in
the AIPS standard header.  Its use for character-valued header
parameters is rather limited at the present time, because AIPS has
only limited character string manipulation operators.  However, for
numeric parameters, the possible uses of GETHEAD are very wide indeed.
For example, to loop over all planes in a cube, a procedure could
contain the following statements:
             KEYWORD = 'NAXIS3'; EGETHEAD
             IF error; then
                print 'an error occurred
             else
                FOR Z = 1 TO KEYVALUE(1);
                     ...
                END ; END;
The list of keywords recognized by GETHEAD is given below:
'OBJECT  '     Source name (char*8)
'TELESCOP'     Telescope name (char*8)
'INSTRUME'     Receiver name (char*8)
'OBSERVER'     Observer name (char*8)
'DATE-OBS'     Date of observation (char*8 as yyyymmdd)
'DATE-MAP'     File creation date (char*8 as yyyymmdd)
'BUNIT   '     Brightness units (char*8)
'CTYPE1  ','CTYPE2  ','CTYPE3  ','CTYPE4  ','CTYPE5  ',
'CTYPE6  ','CTYPE7  '     Type of coordinate axis (char*8)
'CRVAL1  ','CRVAL2  ','CRVAL3  ','CRVAL4  ','CRVAL5  ',
'CRVAL6  ','CRVAL7  '     Value of coordinate at reference
                          pixel (real*8)
'CDELT1  ','CDELT2  ','CDELT3  ','CDELT4  ','CDELT5  ',
'CDELT6  ','CDELT7  '     Change of coordinate/pixel (real*4)
'CRPIX1  ','CRPIX2  ','CRPIX3  ','CRPIX4  ','CRPIX5  ',
'CRPIX6  ','CRPIX7  '     Reference pixel location (real*4)
'CROTA1  ','CROTA2  ','CROTA3  ','CROTA4  ','CROTA5  ',
'CROTA6  ','CROTA7  '     Rotation of coordinate (real*4)
'EPOCH   '     Epoch of coordinates (years, real*4)
'DATAMAX '     Maximum data value (real*4)
'DATAMIN '     Minimum data value (real*4)
'PRODUCT '     Clean product code: 1 - 4 => normal, components,
               residual, points  (integer)
'NITER   '     Number of Clean iterations (integer)
'BMAJ    '     Clean beam major axis (real*4, degrees)
'BMIN    '     Clean beam minor axis (real*4, degrees)
'BPA     '     Clean beam position angle (real*4, degrees)
'VELREF  '     Velocity definition code: 0 => none,
               1 - 3 => LSR, Sun, Obs  + 256 if radio
'ALTRVAL '     Alternate reference value: (real*8, frequency in Hz or
               velocity in m/sec)
'ALTRPIX '     Alternate reference pixel (real*4)
'OBSRA   '     Pointing position: RA (real*8, degrees)
'OBSDEC  '     Pointing position: Dec (real*8, degrees)
'RESTFREQ'     Line rest frequency (real*8, Hz)
'XSHIFT  '     Phase shift in RA (real*4, degrees)
'YSHIFT  '     Phase shift in Dec (real*4, degrees)
'PTYPE1  ','PTYPE2  ','PTYPE3  ','PTYPE4  ','PTYPE5  ',
'PTYPE6  ','PTYPE7  '     Random parameter type (char*8)
'SORTORD '     Sort order (char*2, UV data only)
'BLANK   '     Value of blanked pixel (real*4, floating maps only)
'IMNAME  '     Image name (char*12)
'IMCLASS '     Image class (char*6)
'IMSEQ   '     Image sequence number (integer)
'GCOUNT  '     Number of "groups" (real*8, UV data only)
                  this is the number of visibilities.
'PCOUNT  '     Number of random parameters (integer, UV data only)
'NAXIS   '     Number of axes (integer)
'NAXIS1  ','NAXIS2  ','NAXIS3  ','NAXIS4  ','NAXIS5  ',
'NAXIS6  ','NAXIS7  '     Number of points on axis n (integer)
'USERNO  '     Image owner number (integer)
'IMTYPE  '     Image type (character*2, MA or UV)
'EXTYPE1 ','EXTYPE2 ','EXTYPE3 ','EXTYPE4 ','EXTYPE5 '
'EXTYPE6 ','EXTYPE7 ','EXTYPE8 ','EXTYPE9 ','EXTYPE10'
'EXTYPE11', through 'EXTYPE50'
               Extension file type n (character*2)
'EXTVER1 ','EXTVER2 ','EXTVER3 ','EXTVER4 ','EXTVER5 '
'EXTVER6 ','EXTVER7 ','EXTVER8 ','EXTVER9 ','EXTVER10'
'EXTVER11', through 'EXTVER50'
               Max extension file version number (integer)
'IMGTYPE'      Image type: 1 non 3D, 2 3-D imaging
'XPOFF'        X offset of original image center from reference pixel
              (degrees)
'YPOFF'        Y offset of original image center from reference pixel
               (degrees)

Units: The units throughout are those of FITS (m-k-s plus degrees and
Jy).  In other words, angle coordinate reference values and increments
are in degrees, frequencies are in Hz, velocities in m/s.

AIPS headers now can also contain extra parameters represented within
the header file as keyword/value pairs.  If GETHEAD does not recognize
a keyword as part of its basic list, it will attempt to read it as a
header keyword and report any failure as a keyword missing error.  Two
keywords which are placed in this category by RESCALE are:

'ISCALE  '     Map scale factor (real*8)
'IZERO   '     Map offset       (real*8)
                  Current = ISCALE * initial  + IZERO

The verb IMHEADER will show all current header keywords of this sort.
----------------------------------------------------------------
