NAME:
  refnet
 PURPOSE:
  Support routine for calling ``REFNET'' to get stars from master catalogs.
 DESCRIPTION:

 CATEGORY:
  Astrometry

 CALLING SEQUENCE:
  refnet,ra,dec,width,height,bmaglim,rmaglim,starfile

 INPUTS:
  ra      - Right ascension of center of field for extraction (J2000)
              input can be in radians (double,float) or
              a string HH:MM:SS.S  (see RAPARSE for valid syntax).
  dec     - Declination of center of field for extraction (J2000, radians).
              input can be in radians (double,float) or
              a string +DD:MM:SS.S  (see DECPARSE for valid syntax).
  width   - Half-width of field to extract (arcsec).
  height  - Half-height of field to extract (arcsec).
  bmaglim - Limiting Blue magnitude to extract. (Ignored for Gaia)
  rmaglim - Limiting Red magnitude to extract   (G mag for Gaia).
  starfile- File name for the results of the catalog extraction.

 OPTIONAL INPUT PARAMETERS:

 KEYWORD INPUT PARAMETERS:

  GAIA     - Set this keyword to some value in decimal years to get
                stars from the Gaia catalog.  Doing so will ensure that
                the final output file (starfile) is computed for the
                epoch you provide with this keyword.  You also get another
                file named starfile+'.gcat' which is an ASCII table with
                all of the Gaia information.
  TWOMASS  - String.  Set to 'J', 'H', or 'K' to request 2MASS point-source
                   catalog data in that filter.  Ignored if GAIA is used.
  DEBUG - Flag, if set prints debugging information
  NOCONVERT - Flag, if set suppresses natural conversion of GAIA file,
                 not used for other types.

 OUTPUTS:
  The output is all to the file and contains a list of stars from the
    USNO catalog according to the input constraints, unless GAIA is set
    in which case you get Gaia catalog stars.

 KEYWORD OUTPUT PARAMETERS:

 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:
  You must define an evironment variable, USNO_CAT, that points to the
  directory where the data live.  Default is the current directory.
  To use 2MASS you need to set TWOMASS_CAT.  To use Gaia you need to set
  GAIA_CAT.  You must also have write permission in the current working
  directory.

 PROCEDURE:
   calls refnet for USNO stars, refnetx for 2MASS, or grefnet for Gaia.

 MODIFICATION HISTORY:
  1997/05/08, Written by Marc W. Buie, Lowell Observatory
  1997/11/24, MWB, Added CATPATH keyword
  1999/06/22, MWB, changed CATPATH default
  2002/02/06, MWB, rewrite for new refnet version
  2005/06/26, MWB, added TWOMASS (2MASS catalog) support
  2018/05/08, MWB, added GAIA option
  2018/11/14, MWB, added DEBUG keyword
  2021/01/28, MWB, added NOCONVERT keyword