;+
; Project     :	SOHO - CDS
;
; Name        :	CP_GET_ENTRY()
;
; Purpose     :	Retrieves latest entries for a given command mnemonic and set of indices
;               from the CDHS state database.
;
; Explanation : Returns a structure array containing the latest values associated with the 
;               user supplied command mnemonic and indeces. 
;               If values not found then outputs error message.
;
; Use         : < st = cp_get_entry ( mnemonic, indices, ERRMSG=ERRMSG ) >
;
; Inputs      : mnemonic = string containing parameter command mnemonic
;               indices  = integer array of parameter numbers required.
;
; Opt. Inputs : None.
;
; Outputs     : struct = structure array of type st_cdhsstate containing command mnemonic and parameter values.
;                        Entries in the order requested in indices.                        
;                 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    : 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 = ''
;                         CP_GET_ENTRY, ERRMSG=ERRMSG, ... 
;                         IF ERRMSG NE '' THEN ...
;
; Calls       :	cp_get_mnemonic, cp_get_indeces.
;                
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Category    :	Command preparation.
;
; Prev. Hist. :	None.
;
; Written     :	Version 0.0, Martin Carter, RAL, 7/11/95
;
; Modified    :	Version 0.1, MKC, 19/12/95
;                 Added delay tag.
;
; Version     :	Version 0.1, 19/12/95
;-
;**********************************************************

FUNCTION cp_get_entry, mnemonic, indices, ERRMSG=ERRMSG

  ; get all the latest parameters associated with this mnemonic

  s = cp_get_mnemonic ( mnemonic, /QUIET, ERRMSG=ERRMSG )

  ; check ok

  IF N_ELEMENTS(ERRMSG) NE 0 THEN IF ERRMSG NE '' THEN GOTO, HANDLE_ERROR

  ; get structure elements corresponding to requested indices

  ss = cp_get_indeces ( s, indices, ERRMSG=ERRMSG )

  ; check ok

  IF N_ELEMENTS(ERRMSG) NE 0 THEN IF ERRMSG NE '' THEN GOTO, HANDLE_ERROR

  ; check values OK

  IF N_ELEMENTS(ss) EQ 0 THEN BEGIN
    IF N_ELEMENTS(ERRMSG) NE 0 THEN BEGIN
      ERRMSG = 'INVALID ENTRY IN CDHS STATE DATABASE : ' + mnemonic
      GOTO, HANDLE_ERROR
    ENDIF ELSE $
      MESSAGE, 'INVALID ENTRY IN CDHS STATE DATABASE : ' + mnemonic
  ENDIF

  RETURN, ss
  
  ;  Error handling point.
  ;
  HANDLE_ERROR:

  ERRMSG = 'CP_GET_ENTRY: ' + ERRMSG 

  RETURN, -1
  
END