PRO eis_prep_obs_struc, ss, n_limit=n_limit, overwrite=overwrite

;+
; NAME:
;     EIS_PREP_OBS_STRUC
;
; PURPOSE:
;     This routine is to batch calibrate a set of EIS files that have
;     been identified with the routine eis_obs_structure.
;
; CATEGORY:
;     Hinode; EIS; calibration.
;
; CALLING SEQUENCE:
;     EIS_PREP_OBS_STRUC, Struc
;
; INPUTS:
;     Ss:  A structure in the format returned by EIS_OBS_STRUCTURE.
;
; OPTIONAL INPUTS:
;     N_Limit:  This limits the number of files that get prepped to
;               n_limit. 
;
; KEYWORD PARAMETERS:
;     OVERWRITE: If set, then any files that already exist on the
;                user's computer will be overwritten.
;
; OUTPUTS:
;     Downloads (if necessary) the level-0 files corresponding to the
;     entries in SS, and then calibrates them with eis_prep. The files
;     are ingested into the user's $HINODE directory.
;
; EXAMPLE:
;     Calibrate the set of "cool_loop" rasters:
;      IDL> ss=eis_obs_structure('1-jan-2006','1-jan-2022',rast_acr='cool_loop')
;      IDL> eis_prep_obs_struc, ss
;
; MODIFICATION HISTORY:
;     Ver.1, 28-Mar-2022, Peter Young
;     Ver.2, 01-Apr-2022, Peter Young
;       Added n_limit= optional input.
;     Ver.3, 14-May-2024, Peter Young
;       Added /overwrite keyword.
;-


IF n_params() LT 1 THEN BEGIN
  print,'Use:  IDL> eis_prep_obs_struc, struc'
  print,''
  print,'   where struc is the output from eis_obs_structure.'
  return
ENDIF 

IF n_tags(ss) EQ 0 THEN BEGIN
  print,'% EIS_PREP_OBS_STRUC: the input must be a structure. Returning...'
  return
ENDIF 

chck=getenv('HINODE_DATA')
IF chck EQ '' THEN BEGIN
  print,'% EIS_PREP_OBS_STRUC: the environment variable $HINODE_DATA is not defined. Please read EIS Software Note No. 18. Returning...'
  return
ENDIF 

n=n_elements(ss)

IF n_elements(n_limit) EQ 0 THEN n_limit=n

outdir=getenv('IDL_TMPDIR')

;
; The following is in the case the routine previously crashed and left
; some files in the temp directory.
;
list=file_search(outdir,'eis_*.fits',count=count)
IF count NE 0 THEN eis_ingest,list,/gzip,force=overwrite

;
; The logic below is that I first check if the level-1 file exists. If
; not, then I see if the level-0 file is present. If no, then the file
; is downloaded from the VSO. The calibration is then performed.
;
nfiles=0
FOR i=0,n-1 DO BEGIN
  file=eis_find_file(ss[i].date_obs,/lev,count=count,twind=5)
  IF count EQ 0 OR keyword_set(overwrite) THEN BEGIN
    file=eis_find_file(ss[i].date_obs,count=count,twind=5)
    IF count EQ 0 OR keyword_set(overwrite) THEN eis_vso_download_files,ss[i],overwrite=overwrite
    file=eis_find_file(ss[i].date_obs,count=count,twind=5)
    IF count NE 0 THEN BEGIN
      eis_prep,file,/retain,/quiet,/save,/default,outdir=outdir
      nfiles=nfiles+1
      IF nfiles EQ n_limit THEN BREAK 
    ENDIF 
  ENDIF 
ENDFOR


;
; Ingest the set of level-1 files.
;
list=file_search(outdir,'eis_*.fits')
eis_ingest,list,/gzip,force=overwrite


END