;+
; Project     :	SOHO - CDS
;
; Name        :	CP_GET_MNEMONIC()
;
; Purpose     :	Retrieves latest entries for a given command mnemonic from the CDHS state database.
;
; Explanation : Returns a structure array containing the latest values associated with the 
;               user supplied command mnemonic. There may be multiple entries associated 
;               with a different parameter numbers. If no entries found then returns a 
;               structure with command mnemonic : "Unknown" and displays a popup message .
;
; Use         : < st = cp_get_mnemonic ( mnemonic, ERRMSG=ERRMSG ) >
;
; Inputs      : mnemonic = string containing parameter command mnemonic
;
; Opt. Inputs : None.
;
; Outputs     : struct = structure array of type st_cdhsstate containing command mnemonic and parameter values.                        
;                 struct.mnemonic = parameter mnemonic
;                 struct.date     = date values last changed
;                 struct.numberp  = no. of parameters associated with mnemonic
;                 struct.pnumber  = parameter number for this entry
;                 struct.load     = flag indicating whether value requires loading
;                 struct.delay    = delay in secs associated with command
;                 struct.active   = value for parameter
;                 struct.default  = default value for parameter
;                 struct.comment  = comment on parameter
;
; Opt. Outputs:	None.
;
; Keywords    : QUIET : suppresses popup message
;               GROUP : group for popup message box.
;               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_STATE, ERRMSG=ERRMSG, ... 
;                         IF ERRMSG NE '' THEN ...
;
; Calls       :	dbopen, db_info, dbfind, dbext, dbclose, rem_fst.
;                
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Category    :	Command preparation.
;
; Prev. Hist. :	None.
;
; Written     :	Version 0.0, Martin Carter, RAL, 24/5/94
;
; Modified    :	Version 0.1, MKC, 14/8/95
;                 Added comment field to structure.
;                 Changed active and default to LONGs.
;		Version 0.2, MKC, 28/9/95
;			Added keyword ERRMSG
;               Version 0.3, MKC 18/10/95
;                       Added check that pnumber and numberp are conistent.
;               Version 0.3, MKC, 19/12/95
;                 Added delay tag.
;
; Version     :	Version 0.4, 19/12/95
;-
;**********************************************************

FUNCTION cp_get_mnemonic, mnemonic, GROUP=group, QUIET=quiet, ERRMSG=ERRMSG

  ; set up structure 

  struct = { st_cdhsstate, date:'', mnemonic:'Unknown', pnumber:0, numberp:1, $
                           load:0, delay:0, active:0L, default:0L, comment:'' }

  ; open state database 

  dbopen, 'cdhsstate'

  ; check database has some entries
  ; else dbfind will flag error

  nentries = db_info ( 'entries' )

  IF nentries(0) EQ 0 THEN BEGIN
    
    ; display message 

    IF NOT KEYWORD_SET(quiet) THEN $      
      popup_msg, ['No entries', 'found'], $
                  title = 'WARNING MESSAGE', /modal, GROUP=group

    RETURN, struct

  ENDIF

  ; set up search criteria

  search = 'MNEMONIC=' + mnemonic

  list = dbfind ( search, /SILENT )

  ; list is array of entries in database
  ; if no entries then list contains a zero
  ; valid entries start at 1 

  IF list(0) EQ 0 THEN BEGIN

    ; display message 

    IF NOT KEYWORD_SET(quiet) THEN $      
      popup_msg, ['No entries', $
                  'found'], $
                  title = 'WARNING MESSAGE', /modal, GROUP=group

    RETURN, struct

  ENDIF

  nentries = N_ELEMENTS ( list )

  ; extract entries
  ; NB mnemonic may have more than one parameter associated with it

  dbext, list, 'PNUMBER', pnumber

  ; find latest unique pnumbers

  pinds = rem_fst ( pnumber )

  ; extract unique entries
  ; NB cannot use structure directly since scalars passed by value
  ;    results are arrays

  dbext, list(pinds), 'DATE,PNUMBER,NUMBERP,LOAD,DELAY,ACTIVE,DEFAULT,COMMENT',$
                       date,pnumber,numberp,load,delay,active,default,comment

  ; close database

  dbclose, 'cdhsstate'

  ; order parameters or convert single entry arrays to scalars
  ; NB values are arrays so can use SORT
  ; NB This works because items are all scalars

  IF N_ELEMENTS(date) EQ 1 THEN inds=0 ELSE inds=SORT(pnumber)

  date    = date(inds)
  pnumber = pnumber(inds)
  numberp = numberp(inds)
  load    = load(inds)
  delay   = delay(inds)
  active  = active(inds)
  default = default(inds)
  comment = comment(inds)

  ; check that number of parameters agree

  IF MIN ( numberp ) NE MAX ( numberp ) THEN BEGIN

    ; display message and invalidate command

    IF NOT KEYWORD_SET(quiet) THEN $      
      popup_msg, ['WARNING', $
                  'Contradictory values for number of parameters.'], $
                   title = 'ERROR MESSAGE',/modal, GROUP=group

    RETURN, struct

  ENDIF

  ; set up structure array

  struct = REPLICATE ( struct, N_ELEMENTS(inds) )

  ; return values in parameter order

  struct.mnemonic = mnemonic
  struct.date     = date
  struct.pnumber  = pnumber
  struct.numberp  = numberp
  struct.load     = load
  struct.delay    = delay
  struct.active   = active
  struct.default  = default
  struct.comment  = comment

  RETURN, struct
  
END