;+
; Project     : SOLAR-B - EIS
;
; Name        : EIS_CPT_SEQUENCE_LINK
;
; Purpose     : Links sequences together converting study identifier link to sequence index.
;
; Explanation : Links sequences together converting study identifier link id to sequence index.
;               Returns link with :
;                  link = -1 if sequence terminated
;                  link = 0-nsequences-1
;
; Use         : < result = eis_cpt_sequence_link( sequences ) >
;
; Inputs      : sequences   : STRUCTURE ARRAY of type EIS_CPT_sequence.
;
; Opt. Inputs : None.
;
; Outputs     : result      : INT flag :
;                               1 : processed science plan OK.
;                               0 : processing failed.
;               sequences   : STRUCTURE ARRAY updates .link tag.
;
; Opt. Outputs: None.
;
; Keywords    : None.
;
; Calls       : None.
;
; Common      : None.
;
; Restrictions: None.
;
; Side effects: May output ASCII files.
;
; Category    : EIS_CPT.
;
; Prev. Hist. : None.
;
; Written     : Martin Carter RAL 17/09/05
;
; Modified    : Version 0.0, 17/09/05, MKC
;               Version 0.1, 19/07/06, MKC
;                 Changed check on no. of linked sequences to = 1
;               Version 0.2, 15/09/06, MKC
;                 Rearranged logic.
;                 Corrected bug with daisy-chained studies spanning more than one sequence table.
;
; Version     : 0.2, 15/09/06
;-
;**********************************************************

FUNCTION eis_cpt_sequence_link, sequences

  ; loop through sequence tables converting linked study identifiers to indexes into sequences array

  FOR s = 0, N_ELEMENTS(sequences)-1 DO BEGIN

    ; check if not last sequence in study

    IF NOT sequences[s].last THEN BEGIN

      ; link to next sequence in study

      sequences[s].link = s + 1

    ENDIF ELSE BEGIN

      ; check if sequence terminates

      IF sequences[s].linked_study_identifier EQ 0 THEN BEGIN

        ; terminated daisy-chain
        ; NB 0 is a valid link

         sequences[s].link = -1

      ENDIF ELSE BEGIN

        ; get next study
        ; NB all sequences in study have the same ID
        ; NB have already check that there is only one study corresponding to link_id

        list = WHERE(sequences.study_identifier EQ sequences[s].linked_study_identifier, count)

        sequences[s].link = list[0]

      ENDELSE

    ENDELSE

  ENDFOR

  ; return finished OK flag

  RETURN, 1

error :

  ; issue routine name

  MESSAGE, 'ERROR', /INFORMATIONAL

  ; return error flag

  RETURN, 0

END