;+
; NAME:
;  oc_search_pos
;
; PURPOSE: (one line)
;  Search for stars in a catalog by position.
;
; DESCRIPTION:
;  This routine searches around a specified (ra, dec, radius) in a 
;  specified star catalog.  It returns a fully-populated star structure
;  for each star found.
;
;  This is the main callable external routine for the occultation position
;  searching.  It allows for selection of arbitrary catalogs, and it allows
;  for ra/dec to be either scalar or vector.
;
;  This routine is a wrapper to routines like oc_search_pos_fullcat,
;  oc_search_pos_subcat, etc.
;
; CATEGORY:
;  Star catalogs
;  
; CALLING SEQUENCE:
;  result = oc_search_pos_fullcat(RA, DEC, RADIUS, CATALOG, NSTARS,  $
;                            [, /VERBOSE] )
;
; INPUTS:
;  RA      -- Right ascension of center of search position.  Radians, J2000.
;              Scalar or vector.
;  DEC     -- Declination     of center of search position.  Radians, J2000.
;              Scalar or vector.
;  RADIUS  -- Search radius.  Radians.   Scalar.
;  CATALOG -- Name of the catalog or search routine to use.  This is parsed
;    in two steps.  First, a function name is constructed using the name, and 
;    this function is called if it exists.
;       oc_search_pos_single_CATALOG or    [if RA, DEC are scalars]
;       oc_search_pos_multiple_CATALOG     [if RA, DEC are vectors]
;
;    If this fails, then CATALOG is assumed to be a function name itself, and
;    is compiled and called directly.
;       oc_search_testing_july
;    
;    If this fails, then execution stops.
;
; OPTIONAL INPUT PARAMETERS:
;  _extra -- Passed on to searching routine.
;  
; KEYWORD INPUT PARAMETERS:
;  /VERBOSE -- If set, print error messages to screen.
;
; KEYWORD OUTPUT PARAMETERS:
;  None
;
; OUTPUTS:
;  result -- Array of structures [nstars], with each element being a 
;    fully-populated star structure containing RA, Dec, magnitude, etc.
;  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
;
; EXAMPLE:
; a=oc_search_pos(1,       3,       0.01, 'hd', nstars, /verbose)
; a=oc_search_pos([1,2,5], [3,4,6], 0.01, 'hd', nstars, /verbose)
; a=oc_search_pos([1,2,5], [3,4,6], 0.01,'oc_search_pos_single_hd',nstars,/v)
; 
; MODIFICATION HISTORY:
;  Written  15-Dec-2005 by Henry Throop, SwRI
;  Modified 23-Feb-2006 by HBT. Improved documentation and formatting.
;-

function oc_search_pos, ra, dec, radius, catalog, nstars, $
  VERBOSE=verbose, _extra=extra

; We start by assuming that the field passed in is a catalog name, rather than
; a function name.  We construct the catalog name, based on whether we're
; doing a single or multiple search

  if is_scalar(ra) then $
    func_single		= 'oc_search_pos_single_' +  catalog 

  if is_array(ra) then begin
    func_multiple	= 'oc_search_pos_multiple'
; call to '_multiple' requires passing the '_single'
    func_single		= 'oc_search_pos_single_' + catalog		
  end

; Now check if that constructed catalog name really exists

  exists	= total(routine_info(/FUNCT) eq strupcase(func_single))		; 1 if function already exists, 0 if not

; If it doesn't exists, then try to compile it, and then check again to see if
; it exists The RESOLVE_ROUTINE procedure causes an error if the named routine
; is not found.  Therefore, we must set up an error-handler before we call
; resolve_routine.

  catch, error_status
; If an error is set, execution moves to line following the 'catch' command...
  if (error_status ne 0) then begin		
    if keyword_set(VERBOSE) then print, !error_state.msg
    exists	= 0
    catch, /cancel
    goto, cont
  end

  if not(exists) then begin
; Try to resolve it again
    resolve_routine, func_single, /is_func
    catch, /cancel			
; 1 if function already exists, 0 if not
    exists	= total(routine_info(/FUNCT) eq strupcase(func_single))
  end

  catch, /cancel

; If the constructed function still doesn't exist, then we conclude that we
; were passed a function name proper.  Now, go ahead and just call *that*.  If
; it doesn't exist, we generate an error and stop, which is the proper
; behavior.

cont:

  if not(exists) then func_single	= catalog

; Now, call it!  We call differently based on whether it's a scalar or vector
; argument.

  if keyword_set(VERBOSE) and keyword_set(FUNC_MULTIPLE) then print, $
    'oc_search_pos: calling function ' + func_multiple

  if keyword_set(VERBOSE) then print, $
    'oc_search_pos: calling function ' + func_single

  if     keyword_set(FUNC_MULTIPLE) then $
    return, call_function(func_multiple, ra, dec, radius, $
      func_single, nstars, VERBOSE=verbose, _extra=extra)

  if not(keyword_set(FUNC_MULTIPLE)) then $
    return, call_function(func_single,   ra, dec, radius, $
      nstars, VERBOSE=verbose, _extra=extra)

  stop

end

;;;;;;;;;;;;;

pro other
; ** Routines here are for development and not end-user use. **

; Various calls that test the flexibility of oc_search_pos

  a=oc_search_pos(1, 3, 0.01, 'hd', nstars, /verbose)
  a=oc_search_pos([1,2,5], [3,4,6], 0.01, 'hd', nstars, /verbose)
  a=oc_search_pos([1,2,5], [3,4,6], 0.01, 'oc_search_pos_single_hd', nstars, /verbose)
  a=oc_search_pos([1,2], [3,4], 0.01, 'hdjunk', nstars, /verbose) ; should fail
  a=oc_search_pos(2, 3, 0.01, 'hdjunk', nstars, /verbose) ; should fail

end