;+
; Project     : SOLAR-B - EIS
;
; Name        : EIS_CPT_OBSTBL_PLACE
;
; Purpose     : Places table in OBSTBL.
;
; Explanation : Finds best location to put table in OBSTBL.
;
; Use         : < res = eis_cpt_obstbl_place(obstbl, table, table_index) >
;
; Inputs      : obstbl         : STRUCTURE of type EIS_CPT_obstbl.
;               table          : BYTARR[] table data
;
; Opt. Inputs : table_index    : INT index of table to be checked.
;                                If table_index defined and NE -1 then specifies a single table that should be checked.
;                                On output table_index gives the table index if an exact match found else undefined.
;                                If undefined then does full search of tables.
;
; Outputs     : result         : INT flag :
;                                1 : processed OK.
;                                0 : processing failed.
;               table_index    : INT index of table found.
;                                Undefined if no place found for table
;
; Opt. Outputs: None.
;
; Keywords    : SEQUENCE          : FLAG indicating that processing a sequence.
;               LINELIST          : FLAG indicating that processing a linelist
;               AEC_EXPOSURE      : FLAG indicating that processing an AEC exposure table
;               AEC_TABLE         : FLAG indicating that processing an AEC control table
;               XRT_FLARE         : FLAG indicating that processing an XRT flare trigger  control table
;               EIS_FLARE         : FLAG indicating that processing an EIS flare trigger  control table
;               EIS_EVENT         : FLAG indicating that processing an EIS event trigger  control table
;               EXACT             : FLAG indicating should look for exact match when doing full search in unused tables
;                                   NB with proviso about last two bytes in sequence table
;               USED              : INT indicating should look in 'inuse = used' tables also.
;
; Calls       : None.
;
; Common      : None.
;
; Restrictions: None.
;
; Side effects: None.
;
; Category    : EIS_CPT.
;
; Prev. Hist. : None.
;
; Written     : Martin Carter RAL 04/03/05
;
; Modified    : Version 0.0, 04/03/05, MKC
;               Version 0.1, 29/04/05, MKC
;                 Changed use of !EIS_CPT_CONSTANTS.
;               Version 0.2, 16/05/05, MKC
;                 Changed processing of linelist map details.
;               Version 0.3, 25/06/05, MKC
;                 Added map entries for control tables.
;               Version 0.4, 28/06/05, MKC
;                 Added map entries for aec_exposure table.
;               Version 0.5, 16/09/05, MKC
;                 Split into two routines : PLACE and SET.
;                 Added EXACT and USED keywords.
;                 Renamed eis cpt place table.
;               Version 0.6, 04/10/05, MKC
;                 Added control table keywords.
;                 Changed so that if no place found then sets table_index to -1.
;               Version 0.7, 16/06/06, MKC
;                 Changed so that if no place found then table_index is undefined.
;                 Changed so that table_index is undefined or valid on input.
;
; Version     : 0.7, 16/06/06
;-
;**********************************************************

FUNCTION eis_cpt_obstbl_place, obstbl, table, table_index, SEQUENCE=sequence, LINELIST=linelist, $
                         AEC_EXPOSURE=aec_exposure, AEC_TABLE=aec_table, $
                         XRT_FLARE=xrt_flare, EIS_FLARE=eis_flare, EIS_EVENT=eis_event, $
                         USED=used, EXACT=exact

  ; get obstbl indexes of tables to be searched

  IF NOT eis_cpt_obstbl_index( 0, obstbl_indexes, max_length, number, SEQUENCE=sequence, LINELIST=linelist, $
                              AEC_EXPOSURE=aec_exposure, AEC_TABLE=aec_table, $
                              XRT_FLARE=xrt_flare, EIS_FLARE=eis_flare, EIS_EVENT=eis_event, $
                              /ALL) THEN GOTO, error

  ; check type of table

  IF KEYWORD_SET(sequence) THEN BEGIN

    ; get best place to put table (ignoring last two bytes)

    IF NOT eis_cpt_table_place(obstbl.data, obstbl_indexes, obstbl.map.sequences.used, table, table_index, $
                               /SEQUENCE, USED=used, EXACT=exact) THEN GOTO, error

  ENDIF ELSE IF KEYWORD_SET(linelist) THEN BEGIN

    ; get best place to put linelist

    IF NOT eis_cpt_table_place(obstbl.data, obstbl_indexes, obstbl.map.linelists.used, table, table_index, $
                               /LINELIST, USED=used, EXACT=exact) THEN GOTO, error

  ENDIF ELSE IF KEYWORD_SET(aec_exposure) THEN BEGIN

    ; check if match

    IF NOT eis_cpt_table_place(obstbl.data, obstbl_indexes, obstbl.map.aec_exposure.used, table, table_index, $
                               /AEC_EXPOSURE, USED=used, EXACT=exact) THEN GOTO, error

  ENDIF ELSE IF KEYWORD_SET(aec_table) THEN BEGIN

    ; check if match

    IF NOT eis_cpt_table_place(obstbl.data, obstbl_indexes, obstbl.map.aec_table.used, table, table_index, $
                               /AEC_TABLE, USED=used, EXACT=exact) THEN GOTO, error

  ENDIF ELSE IF KEYWORD_SET(xrt_flare) THEN BEGIN

    ; check if match

    IF NOT eis_cpt_table_place(obstbl.data, obstbl_indexes, obstbl.map.xrt_flare.used, table, table_index, $
                               /XRT_FLARE, USED=used, EXACT=exact) THEN GOTO, error

  ENDIF ELSE IF KEYWORD_SET(eis_flare) THEN BEGIN

    ; check if match

    IF NOT eis_cpt_table_place(obstbl.data, obstbl_indexes, obstbl.map.eis_flare.used, table, table_index, $
                               /EIS_FLARE, USED=used, EXACT=exact) THEN GOTO, error

  ENDIF ELSE IF KEYWORD_SET(eis_event) THEN BEGIN

    ; check if match

    IF NOT eis_cpt_table_place(obstbl.data, obstbl_indexes, obstbl.map.eis_event.used, table, table_index, $
                               /EIS_EVENT, USED=used, EXACT=exact) THEN GOTO, error

  ENDIF ELSE BEGIN

    MESSAGE, 'IMPLEMENTATION ERROR'

  ENDELSE

  ; return OK

  RETURN, 1

error :

  ; issue routine name

  MESSAGE, 'ERROR', /INFORMATIONAL

  ; return error

  RETURN, 0

END