FUNCTION xrt_cat2files, catrecs, urls=urls, doy=doy, $
                        verbose=verbose, quiet=quiet, qabort=qabort

; =========================================================================
;+
;
; PROJECT:
;       Solar-B / XRT
;
; NAME: 
;       XRT_CAT2FILES
;
; CATEGORY:
;       File I/O.
;
; PURPOSE: 
;       Map from XRT catalog entry to files -or- urls.
;       (Intent is that this routine is called from XRT_CAT.PRO, and
;       is not used directly.)
;
; CALLING SEQUENCE:
;
;       Result = XRT_CAT2FILES(catrecs [,urls=urls] [,doy=doy] 
;                      [,verbose=verbose] [,quiet=quiet] [,qabort=qabort])
;
; INPUTS:
;
;      CATRECS   - [Mandatory] (structure array, [Nimg])
;                  XRT catalog entries for desired data filenames.
;
; KEYWORDS:
;
;       /URLS    - [Optional] (Boolean) If set, return URLS instead of NFS
;                  filenames.
;
;       /DOY     - [Optional] (Boolean) If set, filename uses format
;                  ...yyyyDdoy_hhmmss.msec instead of
;                  ...yyyymmdd_hhmmss.msec (pre launch test data?).
;
;       /VERBOSE - [Optional] (Boolean) If set, print out extra
;                  information. Overrides "/quiet" (see Note #1).
;       /QUIET   - [Optional] (Boolean) If set, suppress messages
;                  (see Note #1).
;       /QSTOP   - [Optional] (Boolean) For debugging.
;
; OUTPUTS:
;
;       Returns  - [Mandatory] (string array, [Nimg])
;                  Full pathname (or URL to a remote data server)
;                  for each Level-0 XRT data file.
;       QABORT   - [Optional] (Boolean) Indicates that the program
;                  exited gracefully without completing. (Might be
;                  useful for calling programs.)
;                  0: Program ran to completion.
;                  1: Program aborted before completion.
;   
; EXAMPLES:
;
;       Get paths to local data archive:
;       IDL> files = xrt_cat2files(cat)
;
;       Get URL paths to remote data server:
;       IDL> files = xrt_cat2files(cat, /url)
;
; COMMON BLOCKS:
;
;       None
;
; NOTES:
;
;       1) There are three levels of verbosity.
;          a) "verbose" = highest priority. All errors and messages are
;                         displayed. ("if q_vb")
;          b) "quiet" = lower priority. No errors or messages are
;                       displayed. ("if q_qt")
;          c) neither = lowest priority. All errors and some messages are
;                       displayed. ("if not q_qt")
;
; 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:
;
;      10-Apr-2006 - S.L.Freeland - called from sot_time2files( w/CATALOG) 
;      11-Oct-2006 - S.L.Freeland - $FPP_DATA -> $SOT_DATA
;      27-Nov-2006 - S.L.Freeland - handle name change 
;                    (millisec->10ths resolution)
;
progver = 'v2007-Apr-24' ;--- (J.W.Cirtain) Converted to XRT purpose.
progver = 'v2007-Apr-24' ;--- (M.Weber) Cleaned up and fixed various bugs.
progver = 'v2007-May-18' ;--- (M.Weber) The EC_IMTY_ keyword has been
;                             added to the catalog, so now <xrt_cat2files>
;                             can correctly modify the filenames for 
;                             "dark" images.
progver = 'v2007-May-19' ;--- (M.Weber) Fixed a bug in correction to 
;                             filenames for "dark" images.
;
;-
; =========================================================================


;===== Set Booleans which control print statements.
;===== Keyword "verbose" overrules "quiet".
  q_vb = keyword_set(verbose)
  q_qt = keyword_set(quiet) and (not q_vb)


;===== Set some keyword Booleans, plus miscellaneous.
  qabort  = 0B
  sotdata = get_logenv('$SOT_DATA')
  xrtdata = get_logenv('$XRT_ARCHIVE')


;===== Determine if there is a local XRT data archive.
  obsdir=strtrim(gt_tagval(catrecs,/obsdir,missing=''),2)
  ssxrt=where(strupcase(obsdir) eq 'XRT',xcnt)
  xrt=xcnt gt 0
  case 1 of 
    keyword_set(urls): begin 
      top=get_logenv('SOLARB_LOCAL_SERVER') ; non-SAO centers may define this.
      if top(0) eq '' then top='http://sao-ftp.cfa.harvard.edu:/pub/hinode/'
    end
    else: begin 
      case 1 of 
        file_exist(xrtdata) and xrt: top=xrtdata
        else: top='/archive/hinode/' ; SAO center default
      endcase
      if not file_exist(top) then begin
        if (not q_qt) then box_message, 'XRT_CAT2FILES: No local XRT data ' $
                + 'found. Use /URLS to return remote names (urls). Aborting.'
        qabort = 1B
        return,''
      endif
    end
  endcase


;===== Process catalog into filenames.
  ftd=anytim(catrecs.anytim_dobs,/ecs)
  ft=strcompress(str_replace(str_replace(str_replace(ftd,' ','_'),'/',' '), $
                                                         ':',' '),/remove)
  if keyword_set(doy) then begin 
      doys=anytim2doy(anytim(catrecs.anytim_dobs,/int))
      sdoys=fstring(doys,format='("D",I3.3)')   
      ft=strmid(ft,0,4)+sdoys+strmid(ft,8,18)
  endif

  yymmdd=strmid(ftd,0,10)


;===== Modify filename prefix, as necessary.
  prefix = obsdir
  darkfix = strarr(n_elements(prefix))
  if xcnt gt 0 then obsdir(ssxrt)=''


;===== Putting it all together.
  fname=yymmdd+'/'+obsdir+'/'+strtrim(catrecs.hour,2)+'/'+prefix+ft+'.fits'
  subdir=(['xrt/'])(obsdir eq '') + '/level0/'
  fname=subdir+temporary(fname)
  retval = concat_dir(top,fname)


;===== Perform a correction until this is handled by the reformatter.
  sstrunc=where(catrecs.anytim_dobs ge 8.8015749e+08,ncnt) ; file name res change
  ; ideally this is handled by reformatter version, but not yet in catalog...
  if ncnt gt 0 then begin 
   retval(sstrunc)=strmids(retval(sstrunc),0,strpos(retval(sstrunc),'.fits')-2) $
                   + '.fits'
  endif

;===== Correction for darks must happen after the reformatter correction.
  ssdark = where(strtrim(gt_tagval(catrecs,/ec_imty_,missing=''),2) eq $
                 'dark', darkcnt)
  if (darkcnt ge 1) then begin
    retval[ssdark] = strmids(retval[ssdark], 0, strpos(retval[ssdark],'.fits')) $
                     + 'd.fits'
  endif


;===== Finish.

  return,retval


END ;======================================================================