;+
; Project     : SOHO - CDS     
;                   
; Name        : EMON_CDS_MODE
;               
; Purpose     : To extract and plot the CDS mode setting from telemetry.
;               
; Explanation : As above as an example of how to package EMON in batch mode.
;               
; Use         : IDL> emon_cds_mode [,doy, hours, year=year, /hard, /rt]
;
;               eg.  IDL> emon_cds_mode,244,[13,14],year=94,/hard
;
;                    would plot data for the 2 hrs (13:00 to 15:00) on 1/Sep/94
;
;                    IDL> emon_cds_mode,/rt
;
;                    would plot data from the current realtime session.
;    
; Inputs      : One of DOY or /rt must be supplied.
;               
; Opt. Inputs : DOY   - day of year for file name.  Only one day at a time is
;                       allowed.
;
;               HOUR  - scalar or vector giving the UT hours required (as in
;                       file names). If not realtime and not given then 0-23
;                       is assumed.
;         
;               OUTPUT - if the output structure (from a previous run of
;                        the procedure is used as input then the data in it
;                        are just replotted.  This saves reading the file 
;                        and is useful when the time plot range is to be
;                        adjusted (see keywords TIMERANGE and XSTYLE)
;               
; Outputs     : None
;               
; Opt. Outputs: OUTPUT - if given on the command line then the calibrated
;                        data will be returned in the specified variable.
;                        This is a structure of the form 
;                        {date:' ',data:0,label:strarr(10)}
;    
;                        Note that this variable should be undefined (or 
;                        have only one element (ie set output=0 before
;                        running) on entry otherwise it will
;                        be treated as an input array!
;
;               
; Keywords    : YEAR    - specify the year IF NOT current year.
;
;               HARD    - if want hard copy of plots.
;
;               RT      - if want to pick up only current realtime session.
;                         Note this will only read the current file to the end.
;                         It will not sit and wait for more data to come in
;                         as STM does in realtime mode.
;
;               TIMERANGE - set limits on time range axis eg use to expand
;                           plot scale after initial read of data from file.
;                           Can be in any CDS time format eg
;
;                           timerange=['1-jan-96 12:30','1-jan-96 14:00']
;                           
;                           note for the lazy (and if there is no ambiguity 
;                           in the day involved it is possible to just specify
;                           the time ie.
;         
;                           timerange=['14:00','14:30']
;                       
;                           alternatively you may use
;
;                           timerange=[t(0),t(100)]  
;                      
;                           where t is a CDS internal time structure.
;
;               XSTYLE - if you really want to specify the time limits
;                        rigidly then set this keyword (as in normal plot
;                        routine) otherwise some 'rounding off' of the time
;                        limits will probably occur.
;
; Calls       :
;
; Common      : None
;               
; Restrictions: Data files must be in $CDS_TM_DATA directory.
;               String time specifications are assumed in European format
;               ie day,month,year order.
;               
; Side effects: None
;               
; Category    : Util, telemetry
;               
; Prev. Hist. : None
;
; Written     : C D Pike, RAL, 31-Jan-95
;               
; Modified    : Change UTPLOT name.  CDP, 2-Oct-96
;
; Version     : Version 2, 2-Oct-96
;-            

pro emon_cds_mode, doy, hour, year=year, hard=hard, rt=rt, $
                   output=output,timerange=timerange,xstyle=xstyle

;
;  is input data to be used directly?
;
if n_elements(output) gt 1 then begin
   uts = output.date
   pds = output.data
   lab = tm_read_cal(4)
   lab = reform(lab(1,*))
   words = [' ',lab,' ']
   name = 'AKCMODE'
endif else begin   
   
;
;  else need to gather data from file
;
;  check input
;
   if n_params() eq 0 then begin
      if not keyword_set(rt) then begin
         print,'Use:  IDL> emon_cds_mode, [doy, hour, /hard, /rt]'
         print,' '
         print,'NB either doy OR /rt must be set.'
         print,' ' 
         return
      endif
   endif
   
;
;  either old file or current realtime
;
   if n_params() eq 1 and keyword_set(rt) then begin
      print,'Cannot specify doy AND /rt.'
      return
   endif

;
;  only one day allowed
;
   if n_elements(doy) gt 1 then begin
      print,'Only one day at a time please!'
      return
   endif

;
;  if want realtime session...
;
   if keyword_set(rt) then begin
      tmfiles = concat_dir('$CDS_TM_DATA',gt_rt_file())
   endif else begin

;
;  else select old TM files
;

;
;  format day number
;
      cday = strmid(string(doy+1000,form='(i4)'),1,3)

;
;  if not current year...
;
      if keyword_set(year) then begin
         if year gt 1000 then yr = year - 1900 else yr = year
         yr = string(yr,form='(i2)')
      endif else begin
         yr = strmid(systime(),22,2)
      endelse

;
;  depending on how many hours requested, form file names
;
      if n_params() eq 1 then hour = indgen(24)
      nf = n_elements(hour)
      tmfiles = strarr(nf)
      for i=0,nf-1 do begin
         chr = strmid(string(hour(i)+100,form='(i3)'),1,2)
         fdum = 'tm.'+yr+'_'+cday+'_'+chr
         tmfiles(i) = concat_dir('$CDS_TM_DATA',fdum)
      endfor
   endelse

   print,'Using data files.....'
   print_str,tmfiles

;
;  only after the one parameter AKCMODE
;
   name = 'AKCMODE'


;
;  call emon to do the work
;
   emon,ut_data,parm_data,parms,fname=tmfiles,pname=name,/batch

;
;  trap error return
;
   if ut_data(0) eq 0 then return

;
;  better sort in case of funnies
;
   utt = utc2sec(str2utc(ut_data,/dmy))
   nutt = sort(utt)
   uts = ut_data(nutt)
   pds = parm_data(nutt)

;
;  attempt to calibrate the data
;
   pds = tm_calib(name,pds,words)

endelse

;
;  here for either usage
;

;
;  hard copy wanted?
;
   if keyword_set(hard) then hard = 1 else hard = 0

;
;  set up plotting
;
window,xs=1000,ys=250,/free, $
       title='CDS Engineering telemetry monitor'
circle_sym, /fill
title = 'Engineering '+strmid(name,0,1)+': parameter - '+name

;
;  find time range
;
if not keyword_set(timerange) then begin
   timerange=[uts(0),uts(n_elements(uts)-1)]
endif else begin
   if datatype(timerange(0),1) eq 'String' then begin
      n1 = strpos(timerange(0),'/')
      n2 = strpos(timerange(0),'-')
      if n1 eq -1 and n2 eq -1 then timerange(0) = strmid(uts(0),0,10)+timerange(0)
      n1 = strpos(timerange(1),'/')
      n2 = strpos(timerange(1),'-')
      if n1 eq -1 and n2 eq -1 then timerange(1) = strmid(timerange(0),0,10)+timerange(1)
   endif
endelse

if n_elements(xstyle) eq 0 then xstyle=0
yt = 'CDS operational mode'
yr = [0,9]

;
;  and plot it
;
cds_utplot, uts, pds, /dmy, psym=8, title=title, $
        symsize=0.3, ytitle=yt,yrange=yr,ystyle=1,yticks=9,chars=1.1,$
        ytickname=[' ',words(1:8),' '],timerange=timerange,xstyle=xstyle 
if hard then begin
   ps
   cds_utplot, uts, pds, /dmy, psym=8, title=title, $
           symsize=0.3,ytitle=yt,yrange=yr,chars=1.1,yticks=9,ystyle=1,$
           ytickname=[' ',words(1:8),' '],timerange=timerange,xstyle=xstyle 
    psplot
endif

;
;  in case the return data were required
;
if n_elements(output) eq 0 then begin
   npds = n_elements(pds)
   output = replicate({date:' ',data:0,label:' '},npds)
   output.date = uts
   output.data = pds
   for i=0,npds-1 do output(i).label= words(pds(i))
endif

end