NAME:
  photcal
 PURPOSE:   (one line only)
  Photometric calibration using two lists of partially overlapping sources.
 DESCRIPTION:
 CATEGORY:
  Photometry
 CALLING SEQUENCE:
  photcal,ra,dec,imag,imagerr,catra,catdec,catmag,ngood,photzp,
          photzperr,magrange
 INPUTS:
  ra   - J2000 right ascension of source (usually from a CCD image)
  dec  - J2000 declination of source (usually from a CCD image)
  imag - instrumental magnitude
  imagerr - uncertainty on the instrument magnitude
  catra   - J2000 right ascension of the catalog (known) source.
  catdec  - J2000 declination of the catalog (known) source.
  catmag  - Standard catalog magnitude
  catmagerr  - Uncertainty of the standard catalog magnitude
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
  MAXSEP - Maximum allowable separation in arcseconds between sources in the
              two lists that will be considered a match (default=1.5 arcsec).
  NODISPLAY - Flag, if set will suppress all plots
  UNIQUE - Flag, if set will force the linking of the two lists to be
              a one-to-one mapping.
  RETURN_ALL - Flag, if set will return all cross-correlated sources.
                 Normally, those that are marked as bad are removed from
                 INDEX1 and INDEX2 before returning.  If you want them
                 all for some other external processing you will set this.
 OUTPUTS:
  ngood   - Number of good matches
  photzp  - Photometric zero-point that when added to the instrumental
              magnitude will return the standard magnitude in the system
              of the catalog.
  photzperr - Uncertainty on the zero-point
  magrange  - magnitude range of the catalog stars used, 2-element vector
                 with [faintmag,brightmag]
 KEYWORD OUTPUT PARAMETERS:
  BAD    - Bad flag array, same length as the input arrays.
  INDEX1 - index into catalog list for the matched list of good stars
  INDEX2 - index into star list for the matched list of good stars
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
  Written by Marc W. Buie, Lowell Observatory, 2007/02/01
  2008/08/07, MWB, added MAXSEP, UNIQUE, and NODISPLAY keywords
  2011/04/25, MWB, added RETURN_ALL and BAD keywwords