;+
; Project     : SOLAR-B - EIS
;
; Name        : EIS_CPT_DAISY_CHAIN
;
; Purpose     : Gets list of time line studies in daisy_chain.
;
; Explanation : Follows daisy-chain until terminates or interrupted.
;               Issues a warning if the daisy-chain interrupted.
;               Ensures that times in timeline are monotonic.
;
; Use         : < result = eis_cpt_timeline ( study_details, interrupt_time, link, start_time, timeline) >
;
; Inputs      : study_details  : STRUCTURE ARRAY of type EIS_study_detail.
;               interrupt_time : DOUBLE TAI time to finish timeline.
;               link           : INT index into study_details giving the start of the daisy-chain
;               start_time     : DOUBLE TAI start time of first study in daisy-chain
;               timeline       : STRUCTURE ARRAY of type EIS_CPT_timeline so far
;                                NB will be changed on exit
;
; 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    : COMPLETE : INT flag indicating should carry on until daisy-chain terminates.
;                          If there is a daisy-chain loop then will terminate after one pass through loop
;                          and set the loop tag.
;
; 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, 15/09/06, MKC
;                 Fixed bug with single looped study if COMPLETE used.
;                 Added check.
;                 Fixed bug with end time calculation.
;
; Version     : 0.2, 15/09/06
;-
;**********************************************************

FUNCTION eis_cpt_daisy_chain, study_details, interrupt_time, link, start_time, timeline, COMPLETE=complete

  ; set up current time

  current_time = start_time

  ; set up element of timeline

  element = {EIS_CPT_timeline}

  ; loop through daisy chains until interrupted by next time-tagged study or terminates
  ; adding studies to timeline list
  ; NB studies in loops will be added multiple times

  WHILE link GE 0 DO BEGIN

    ; start_time, end_time and link refer to the current study

    ; set up timeline element

    element.index = link

    element.time  = current_time

    element.loop  = -1

    ; move time to end time of study
    ; enforce minimum 1 second duration else can repeat indefinitely without running out of time

    current_time = current_time + ((study_details[link].duration*study_details[link].study_repeat_number)>1)

    ; add element to daisy chain timeline

    eis_cpt_add, daisy_chain, element

    ; check study not interrupted

    IF NOT KEYWORD_SET(complete) AND current_time GT interrupt_time THEN BEGIN

      ; signal warning

      eis_cpt_message, 'WARNING, study interrupted : '+$
                        STRING(study_details[link].study_identifier,FORMAT='(Z8.8)')+$
                        ' AT '+anytim2cal(interrupt_time)

      ; terminate processing

      link = -1

    ENDIF ELSE BEGIN

      ; get next study index
      ; if no linked study then link will be -1
      ; explicitly cut out links to study ID 0

      IF study_details[link].linked_study_identifier EQ 0 THEN BEGIN

        link = -1

      ENDIF ELSE BEGIN

        ; find link

        link = WHERE(study_details.study_identifier EQ study_details[link].linked_study_identifier)

        ; should have already checked link is unique
        ; if a study is linked from another study then its study identifier must be unique

        IF N_ELEMENTS(link) GT 1 THEN MESSAGE, 'IMPLEMENTATION ERROR'

        link = link[0]

      ENDELSE

      ; check if want to complete daisy-chain

      IF KEYWORD_SET(complete) THEN BEGIN

        ; test if loop encountered

        IF link GE 0 THEN BEGIN

          ; test for loop

          list = WHERE(link EQ daisy_chain.index, count)

          ; if loop encountered then set loop tag and terminate

          IF count GT 0 THEN BEGIN

            daisy_chain[N_ELEMENTS(daisy_chain)-1].loop = N_ELEMENTS(daisy_chain) - 1 - list[0]

            link = -1

          ENDIF

        ENDIF

      ENDIF

    ENDELSE

  ENDWHILE

  ; add daisy chain to timeline

  eis_cpt_add, timeline, daisy_chain

  ; return finished OK flag

  RETURN, 1

error :

  ; issue routine name

  MESSAGE, 'ERROR', /INFORMATIONAL

  ; return error flag

  RETURN, 0

END