;+
; NAME:
;  oc_scat
;
; PURPOSE: (one line)
;  call scat (Doug Mink) using spawn and report results
;
; DESCRIPTION:
;  call scat (Doug Mink) using spawn and report results
;
; CATEGORY:
;  Star catalogs.
;  
; CALLING SEQUENCE: 
;  ids = oc_scat(RA, DEC, RADIUS, NSTARS,  $
;                            CATALOG=catalog [, /VERBOSE] )
;
; INPUTS:
;  RA     -- Right ascension of center of search position.  Radians, J2000.
;  DEC    -- Declination     of center of search position.  Radians, J2000.
;  RADIUS -- Search radius.  Radians. 
;
;  Inputs are single values, not arrays.
;
; OPTIONAL INPUT PARAMETERS:
;  None
;
; KEYWORD INPUT PARAMETERS:
;  CATALOG= -- Name of the catalog to use; e.g., 'HD', 'TY2', 'UCAC2', '2MASS'
;    Defaults to 'HD' if not set.
;  /VERBOSE -- If set, print error messages to screen.
;
; KEYWORD OUTPUT PARAMETERS:
;  None
;
; OUTPUTS:
;  result -- Array of stars found by scat
;  NSTARS -- Number of stars found
;  
; COMMON BLOCKS:
;  None
;
; SIDE EFFECTS:
;  None
;
; RESTRICTIONS:
;  The proper environment variable must be set for the catalog called.
;   $TY2_PATH   -- For Tycho-2 catalog
;   $WCS_CATDIR -- For HD and other WCS-based catalogs
;   $UCAC2_PATH -- For UCAC2 catalog
;   $TMC_PATH -- For UCAC2 catalog
;
; EXAMPLE:
;  ids = oc_scat(0.5, 0.5, 0.01, nstars, catalog='hd')
; 
; MODIFICATION HISTORY:
;  Written  02-Jul-2006 by Leslie Young, SwRI, based on oc_search_pos_fullcat
;-

function oc_scat, ra, dec, radius, name_catalog, nstars, VERBOSE=verbose, $
                  command = command, scat=scat, nstars_max = nstars_max

;    d2r		= 2.*!dpi / 360d
;    r2d		= 1./d2r
;    d2as	= 60d*60d
    
    deg = !dpi/180.
    arcsec = deg/3600.d

    if not keyword_set(nstars_max) then $
	    nstars_max	= 10L       ; Maximum number of stars

    ; Loop through calls to oc_scat, increasing the 
    ; number of nstars_max until the number returned is
    ; less than the number asked for.

    repeat begin

        nstars_max = nstars_max * 100L

; Construct the command

        command	= 'scat ' + $ 
; Catalog name
        ' -c ' + name_catalog + $			
; Search radius in arcsec
        ' -r ' + string(radius/arcsec,format='(F20.5)') + $	
; Output in Degrees (not hms)
        ' -d' + $				
; Tab-delimited columns (also adds 11 lines of header info)
        ' -t' + $				
; J2000
        ' -j' + $				
; Max number returned
        ' -n ' + st(nstars_max) + $		
		  ' '    + string(ra/deg,format='(F19.12)') + $
          ' ' + string(dec/deg,format='(F19.12)') + ' j2000'
        
        
                                ; Execute the command and return output to array 'scat'

        if keyword_set(VERBOSE) then print, 'Executing command: ' + command
        spawn, command, scat

; Figure out how many stars, and how many header lines we have here We do this
; by counting back from the '---' marker on scat's output.  This works for TY2
; and HD catalogs with -t flag, but should be verified for new catalogs!  Scat
; does not directly return the number of stars -- it must be inferred from the
; output.
;
; If there is an error (as opposed to no stars found), there will be
; no '---', where(grep()) will return -1, and lines_header = 0.
; In this case, there are no good lines, and lines_header should equal
; the total number of lines

        lines_header	= max(where(grep(scat, '---'))) + 1
        if lines_header eq 0 then lines_header = n_elements(scat)

; Figure out how many header lines we have 
        nstars	= n_elements(scat) - lines_header

        if keyword_set(VERBOSE) then print, $
          'Found ' + st(nstars) + ' matching stars'

    endrep until nstars lt nstars_max

; If none found, then return

  if (nstars le 0) then return, -1

; If stars found, then prepare to read them in

  scat_chop	= scat[lines_header:*]


; Parse and store the scat output
; Scat will not return output with fixed column locations; therefore, IDL's
; FORMAT= routines do not work.  We therefore use tab-delimited output, and
; split on tabs, which prevents problems with ID's containing spaces.

  char_tab	= string(9B)

  ids		= strarr(nstars)

  for i = 0L, nstars-1 do begin
    ids[i]	= (ht_str_split(scat_chop[i], char=char_tab))[0]
  end

  return, ids

end