PRO xrt_file_search, path, time1, time2, output, nfiles

; =========================================================================
;		
;+
; PROJECT:
;       Hinode / XRT
;
; NAME:
;	XRT_FILE_SEARCH
;
; CATEGORY:
;       File search
;
; PURPOSE:
;	Construct a list of XRT image filenames for a given time range.
;
;
; CALLING SEQUENCE:
;     xrt_file_search, path, time1, time2, output [,nfiles]
;
; INPUTS:
;
;      	  path       - [Mandatory] (string scalar) 
;                      The XRT FITS archive 
;         time1      - [Mandatory] (string scalar)
;                      The start time of the observations.
;
;      	  time2      - [Mandatory] (string scalar)
;                      The end time of the observations.
;
;	   
; OUTPUTS:
;
;	output      - [Mandatory] (structure array, [Nimg])
;                     Each image gets a short structure of information,
;                     including the FITS filename. List of filenames 
;                     within time range = "output.filename", which 
;                     may be used as an input to <xrt_prep.pro>.
;	nfiles      - [Optional] (integer scalar)
;                     The number of images in the time range.
;
; EXAMPLES:
;
;       Find a list XRT FITS files:
;       IDL> xrt_file_search, '/archive/hinode/xrt/level0/',        $
;       IDL>   '12-Feb-2006 00:00', '12-Feb-2006 06:00', list, nfiles
;
;
; COMMON BLOCKS: 
;       None.
;
;
; CONTACT:
;
;       Comments, feedback, and bug reports regarding this routine may be
;       directed to this email address:
;                xrt_manager ~at~ head.cfa.harvard.edu
;
; MODIFICATION HISTORY:
;
progver = 'v2007.Jan 23' ;--- (JWC) Written. Cleaned up by MW.
;
;
;-
; =========================================================================

 

 ;; ----------------------------------------------------------------------

  ;; --- check the procedure call

  if ((n_params() eq 4) or (n_params() eq 5)) then begin
    ;--- OK
  endif else begin
    print, 'XRT_FILE_SEARCH: Incorrect number of parameters. Aborting...'
    return
  endelse

  if ((n_elements(path) eq 1) and (n_elements(time1) eq 1) and $
      (n_elements(time2) eq 1)) then begin
    ;--- OK
  endif else begin
    print, 'XRT_FILE_SEARCH: Inputs cannot be arrays. Aborting...'
    return
  endelse

  ;--- set up

  ss = {filter1:    '',$
        filter2:    '',$
        exptime:   0.0,$
        naxis1:      0,$
        naxis2:      0,$
        date_obs:   '',$
        time:     0.d0,$
        listing:    '',$
        filename:    ''}
  rm = replicate(ss,1000)

  grid = time2file(timegrid(time1,time2,/hour))
  cntr = 0
  for i=0,n_elements(grid)-1 do begin

    ;; --- loop over hourly directories during the specified time

    yy = strmid(grid[i],0,4)
    mm = strmid(grid[i],4,2)
    dd = strmid(grid[i],6,2)
    hh = strmid(grid[i],9,4)

    dir = concat_dir(PATH,yy)
    dir = concat_dir(dir,mm)
    dir = concat_dir(dir,dd)
    dir = concat_dir(dir,'H'+hh)

    file = file_search(concat_dir(dir,'XRT*.fits'),count=nfiles)
    t1   = anytim(time1)
    t2   = anytim(time2)

    ;; --- loop over the files in the directory

    for j=0,nfiles-1 do begin
      header = headfits(file[j])

      rm[cntr].filter1  = fxpar(header,'EC_FW1_')
      rm[cntr].filter2  = fxpar(header,'EC_FW2_')
      rm[cntr].exptime  = fxpar(header,'EXPTIME')
      rm[cntr].naxis1   = fxpar(header,'NAXIS1')
      rm[cntr].naxis2   = fxpar(header,'NAXIS2')
      rm[cntr].date_obs = fxpar(header,'DATE_OBS')
      rm[cntr].time     = anytim(rm[cntr].date_obs)
      rm[cntr].filename = file[j]
      rm[cntr].listing  = xrt_title(header,/listing)

      cntr = cntr + 1
      if cntr eq n_elements(rm) then rm = [rm,replicate(ss,1000)]
    endfor

  endfor
  if cntr eq 0 then begin
    output = -1
    return
  endif else rm = rm[0:cntr-1]

  mm = where(rm.time ge anytim(time1) AND rm.time le anytim(time2),nfiles)
  if nfiles eq 0 then begin
    output = -1
    return
  endif else output = rm[mm]

  ;; ----------------------------------------------------------------------

  if not(keyword_set(test_array)) then return

  mm = struct_where(output,nfiles,test_array=test_array)
  if nfiles eq 0 then begin
    output = -1
    return
  endif else output = output[mm]

  return

END