;+
; Project     : SOLAR-B - EIS
;
; Name        : EIS_CPT_TIMELINE
;
; Purpose     : Gets list of time line studies.
;
; Explanation : Gets list of time line studies.
;
; Use         : < result = eis_cpt_timeline ( study_details, control_details, time_period , timeline) >
;
; Inputs      : study_details    : STRUCTURE ARRAY of type EIS_study_detail.
;               control_details  : STRUCTURE of type EIS_control_details.
;               time_period      : DBLARR[2] TAI time to start and finish timeline.
;
; Opt. Inputs : None.
;
; Outputs     : result     : INT flag :
;                              1 : processed science plan OK.
;                              0 : processing failed.
;               timeline   : STRUCTURE ARRAY of type EIS_CPT_timeline updated
;
; Opt. Outputs: None.
;
; Keywords    : None.
;
; Calls       : None.
;
; Common      : None.
;
; Restrictions: None.
;
; Side effects: None.
;
; Category    : EIS_CPT.
;
; Prev. Hist. : None.
;
; Written     : Martin Carter RAL 23/09/05
;
; Modified    : Version 0.0, 23/09/05, MKC
;               Version 0.1, 29/09/05, MKC
;                 Changed behaviour with respect to errors and warnings and daisy-chain loops.
;               Version 0.2, 22/05/06, MKC
;                 Changed initialization of timeline for compatability with IDL 6.2.
;               Version 0.3, 19/06/06, MKC
;                 Changed tags study identifier and filler sequence identifier.
;                 Hardcoded study identifiers for response study.
;                 Removed type argument from routine eis cpt response timeline.
;
; Version     : 0.3, 19/06/06
;-
;**********************************************************

FUNCTION eis_cpt_timeline, study_details, control_details, time_period, timeline

  ; timeline is time-ordered list of studies as they will be run (including repeating studies)
  ; response sets of studies are added to timeline with a type tag

  ; initialize timeline

  eis_cpt_undefine, timeline

  ; get list of time tagged studies

  time_tagged_studies = WHERE(study_details.time_tagged, number_of_time_tagged_studies)

  ; if no studies on time line return

  IF number_of_time_tagged_studies GT 0 THEN BEGIN

    ; time order list

    time_tagged_studies = time_tagged_studies[SORT(study_details[time_tagged_studies].start_time)]

    ; loop through list extracting daisy-chains
    ; If study daisy-chain interrupted by a time-tagged study or end time then will cause warning
    ; and rest of daisy-chain will be omitted from timeline

    FOR k = 0, number_of_time_tagged_studies-1 DO BEGIN

      ; process daisy-chain
      ; only issue warning (rather than error) if last study chain interrupted by end of observation plan

      IF k LT number_of_time_tagged_studies-1 THEN $
        interrupt_time = study_details[time_tagged_studies[k+1]].start_time $
      ELSE $
        interrupt_time = time_period[1]

      IF NOT eis_cpt_daisy_chain(study_details, interrupt_time, time_tagged_studies[k], $
          study_details[time_tagged_studies[k]].start_time, timeline) THEN GOTO, error

    ENDFOR

  ENDIF

  ; check timeline defined

  IF KEYWORD_SET(timeline) THEN BEGIN

    ; get list of hunter studies on the timeline
    ; NB although timeline is extended will not go into the complications arising
    ; when the response study contains a hunter study
    ; use latest hunter study to set off flare response
    ; (NB use latest so that will have time of latest use for studies as expiry time)
    ; if no hunter studies then these will be set to -1

    xrt_flare_hunter_study = last_item(WHERE(study_details[timeline.index].XRT_flare_control_flag NE 0))

    eis_flare_hunter_study = last_item(WHERE(study_details[timeline.index].EIS_flare_control_flag NE 0))

    eis_event_hunter_study = last_item(WHERE(study_details[timeline.index].EIS_event_control_flag NE 0))

    ; find XRT flare response studies

    IF xrt_flare_hunter_study GE 0 THEN BEGIN

      IF NOT eis_cpt_response_timeline(study_details, time_period, xrt_flare_hunter_study, $
            1, timeline) THEN GOTO, error

      ; check if filler study

      IF control_details.xrt_flare_control.filler_identifier NE 0 THEN BEGIN

        ; find XRT filler studies

        IF NOT eis_cpt_response_timeline(study_details, time_period, xrt_flare_hunter_study, $
              2, timeline) THEN GOTO, error

      ENDIF

    ENDIF

    ; find EIS flare response studies

    IF eis_flare_hunter_study GE 0 THEN BEGIN

      IF NOT eis_cpt_response_timeline(study_details, time_period, eis_flare_hunter_study, $
          3, timeline) THEN GOTO, error

    ENDIF

    ; find EIS event response studies

    IF eis_event_hunter_study GE 0 THEN BEGIN

      IF NOT eis_cpt_response_timeline(study_details, time_period, eis_event_hunter_study, $
          4, timeline) THEN GOTO, error

    ENDIF

  ENDIF

  ; return finished OK flag

  RETURN, 1

error :

  ; issue routine name

  MESSAGE, 'ERROR', /INFORMATIONAL

  ; return error flag

  RETURN, 0

END