Name

---

      DBCIRCLE

Purpose

---

      Find sources in a database within specified radius of specified center

Explanation

---

      Database must include items named 'RA' (in hours) and 'DEC' (in degrees)
      and must have previously been opened with DBOPEN

Calling Sequence

---

    list = DBCIRCLE( ra_cen, dec_cen, [radius, dis, sublist, /SILENT,
                                /GALACTIC, TO_B1950, /TO_J2000, COUNT= ] )

Inputs

---

      RA_CEN - Right ascension of the search center in decimal HOURS, scalar
      DEC_CEN - Declination of the search center in decimal DEGREES, scalar
              RA_CEN and DEC_CEN should be in the same equinox as the
              currently opened catalog.

Optional Input

---

      RADIUS - Radius of the search field in arc minutes, scalar.
              DBCIRCLE prompts for RADIUS if not supplied.
      SUBLIST - Vector giving entry numbers in currently opened database
              to be searched. Default is to search all entries

Outputs

---

    LIST - Vector giving entry numbers in the currently opened catalog
            which have positions within the specified search circle
            LIST is set to -1 if no sources fall within the search circle

Optional Output

---

      DIS - The distance in arcminutes of each entry specified by LIST
              to the search center (given by RA_CEN and DEC_CEN)

Optional Keyword Input

---

      /GALACTIC - if set, then the first two parameters are interpreted as
                Galactic coordinates in degrees, and is converted internally
                to J2000 celestial to search the database.
      /SILENT - If this keyword is set, then DBCIRCLE will not print the
              number of entries found at the terminal
      /TO_J2000 - If this keyword is set, then the entered coordinates are
              assumed to be in equinox B1950, and will be converted to
              J2000 before searching the database
      /TO_B1950 - If this keyword is set, then the entered coordinates are
              assumed to be in equinox J2000, and will be converted to
              B1950 before searching the database
              NOTE: The user must determine on his own whether the database
              is in B1950 or J2000 coordinates.

Optional Keyword Output

---

      COUNT - - Integer scalar giving the number of valid matches

Method

---

      A DBFIND search is first performed on a square area of given radius.
      The list is the restricted to a circular area by using GCIRC to
      compute the distance of each object to the field center.
  RESTRICTIONS;
      The database must have items 'RA' (in hours) and 'DEC' (in degrees).
      Alternatively, the database could have items RA_OBJ and DEC_OBJ
      (both in degrees)

Example

---

      Find all Hipparcos stars within 40' of the nucleus of M33
      (at J2000 1h 33m 50.9s 30d 39' 36.7'')
      IDL> dbopen,'hipparcos'
      IDL> list = dbcircle( ten(1,33,50.9), ten(3,39,36.7), 40)

Procedure Calls

---

      BPRECESS, DBFIND(), DBEXT, DB_INFO(), GCIRC, GLACTC, JPRECESS

Revision History

---

      Written W. Landsman STX January 1990
      Fixed search when crossing 0h July 1990
      Spiffed up code a bit October, 1991
      Leave DIS vector unchanged if no entries found W. Landsman July 1999
      Use maximum declination, rather than declination at field center to
      correct RA for latitude effect W. Landsman September 1999
      Added COUNT, GALACTIC keywords W. Landsman December 2008
      Fix problem when RA range exceeds 24h W. Landsman April 2009
      Work as advertised for RA_OBJ field W. Landsman June 2010