; Project     :	SOHO - CDS
;
; Name        :	GET_IEFTAB
;
; Purpose     :	Retrieves an IEF flag parameter data set from the IEFTAB database.
;
; Explanation : Extracts the parameters which define the flag generation scheme 
;               from the IEFTAB database. 
;
; Use         : < get_ieftab, ieftab_id, def >
;
; Inputs      : ieftab_id = IEF table ID number.
;
; Outputs     : def = structure containing IEF table database values.
;                  def.ieftab_id  = I*2      IEF table ID. 
;                                            If the requested IEF table is not found,
;				             then a simpler structure is returned, with
;				             this set to -1.
;                  def.desc       = C*65     Description of event generation scheme.
;                  def.upp_era    = 4(I*2)   Upper limit for each ERA measure (unsigned INT16)
;                  def.low_era    = 4(I*2)   Lower limit for each ERA measure (unsigned INT16)
;                  def.discrim    = I*2      Discriminator level (unsigned INT16)
;                  def.ev_type    = I*2      Event type (4 bits)
;                  def.pmode      = I*2      Pointing mode : NIS=0, VF=1, GIS=2 (2 bits)
;                  def.cmode      = I*2      Centroid mode : POS=0, NEG=1, ABS=2 (2 bits)
;                  def.c_banda    = I*2      Slit centre band A (INT16)
;                  def.c_bandb    = I*2      Slit centre band B (INT16)
;                  def.c_row      = I*2      Central row (INT16)
;                  def.detector   = C*1      'N'= NIS, 'G'= GIS.
;                  def.n_iefwins  = I*2      No. of IEF windows (<=3)
;                  def.iefwin_ids = 3(I*2)   IEFWIN database IDs
;
; Keywords    :
;       ERRMSG    = If defined and passed, then any error messages will be
;                   returned to the user in this parameter rather than
;                   depending on the MESSAGE routine in IDL.  If no errors are
;                   encountered, then a null string is returned.  In order to
;                   use this feature, ERRMSG must be defined first, e.g.
;
;                       ERRMSG = ''
;                       GET_DATAWIN, ERRMSG=ERRMSG, ... 
;                       IF ERRMSG NE '' THEN ...

; Calls       :	datatype, dbopen, dbbuild, dbclose.
;                
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Category    :	Command preparation.
;
; Prev. Hist. :	Adapted from get_datawin.
;
; Written     :	Version 0.0, Martin Carter, RAL, 18/10/95
;
; Modified    :	
;
; Version     :	Version 0.0, 18/10/95
;-
;**********************************************************

PRO get_ieftab, ieftab_id, def, ERRMSG=errmsg

	ON_ERROR, 2

;  Define a null result.  If the routine is successful, this will be updated
;  later.
;
	def = { ieftab_id : -1 }

;
;  Check the number of parameters.
;
        IF N_PARAMS() NE 2 THEN BEGIN
           MESSAGE = 'Syntax:  GET_IEFTAB, IEFTAB_ID, DEF'
	   GOTO, HANDLE_ERROR
        ENDIF

;
;  Check the input parameter iefwin_id
;
	type = datatype ( ieftab_id, 2 )
	IF type EQ 0 THEN BEGIN
           MESSAGE = 'IEFTAB_ID is undefined'
           GOTO, HANDLE_ERROR
	END ELSE IF type GE 4 THEN BEGIN
           MESSAGE = 'IEFTAB_ID must be an integer'
           GOTO, HANDLE_ERROR
	END ELSE IF N_ELEMENTS ( ieftab_id ) NE 1 THEN BEGIN
           MESSAGE = 'IEFTAB_ID must be a scalar'
           GOTO, HANDLE_ERROR
	ENDIF

; open database 

        dbopen, 'ieftab'
;
;  Search on the ID field.
;
	entries = dbfind ( 'IEFTAB_ID=' + STRTRIM ( ieftab_id, 2), /SILENT)

;
;  If no entries were found, then return immediately.
;
	IF entries(0) LT 1 THEN BEGIN
		MESSAGE = 'IEF table ID not found'
		GOTO, HANDLE_ERROR
	ENDIF

;
;  If more than one entry found, then return immediately.
;
	IF N_ELEMENTS(entries) GT 1 THEN BEGIN
		MESSAGE = 'Duplicate IEF table ID found'
		GOTO, HANDLE_ERROR
	ENDIF

; read entries from database (NB at most 12 at a time)

  dbext, entries, 'DESC,UPP_ERA,LOW_ERA,DISCRIM,EV_TYPE,PMODE,CMODE,C_BANDA,C_BANDB,C_ROW', $
                   desc,upp_era,low_era,discrim,ev_type,pmode,cmode,c_banda,c_bandb,c_row

  dbext, entries, 'DETECTOR,N_IEFWINS,IEFWIN_IDS', $
                   detector,n_iefwins,iefwin_ids

  ; set up structure array

  def = { ieftab_id : ieftab_id, desc : desc(0), upp_era : upp_era, low_era : low_era, $
          discrim : discrim(0), ev_type : ev_type(0), pmode : pmode(0), cmode : cmode(0), $
          c_banda : c_banda(0), c_bandb : c_bandb(0), c_row : c_row(0), detector : detector(0), $
          n_iefwins : n_iefwins(0), iefwin_ids : iefwin_ids }

  GOTO, FINISH
;
;  Error handling point.
;
HANDLE_ERROR:
	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = 'GET_IEFTAB: ' + MESSAGE $
		ELSE MESSAGE, MESSAGE, /CONTINUE
;
;  Close the database, and return.
;
FINISH:
	dbclose, 'ieftab
;
	RETURN

END