PRO GET_OBJECT, OBJECT, DESC, ERRMSG=ERRMSG
;+
; Project     :	SOHO - CDS
;
; Name        :	GET_OBJECT
;
; Purpose     :	Extracts a SOHO object description from the database
;
; Explanation :	This routine extracts parameters which describes a SOHO
;		object name abbreviation.
;
; Use         :	GET_OBJECT, OBJECT, DESC
;
; Inputs      :	OBJECT	= Either the unique object code, or the unique object
;			  description.
;
; Opt. Inputs :	None.
;
; Outputs     :	DESC	= Structure containing the object description.  It
;			  contains the following tags:
;
;			OBJECT	    = Three-letter object code.  If a match is
;				      not found, then this set to the null
;				      string.
;			OBJECT_DESC = Expanded-out name of the object.
;
; 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 = ''
;                       GET_OBJECT, ERRMSG=ERRMSG, ... 
;                       IF ERRMSG NE '' THEN ...
;
;
; Calls       :	DATATYPE, DBOPEN, DBFIND, DBEXT, DBCLOSE
;
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Category    :	Planning, Databases.
;
; Prev. Hist. :	None.
;
; Written     :	William Thompson, GSFC, 25 July 1994
;
; Modified    :	Version 1, William Thompson, GSFC, 27 July 1994
;               Version 2, Liyun Wang, GSFC/ARC, September 22, 1994
;                  Added the keyword ERRMSG.
;		Version 3, William Thompson, GSFC, 8 November 1994
;			Changed so that a blank but non-null result is returned
;			if OBJECT is a blank string.
;		Version 4, William Thompson, GSFC, 17 February 1995
;			Changed so that one can either search on the code value
;			or the description.  Fixed bug when two-letter
;			abbreviations are used.
;		Version 5, William Thompson, GSFC, 28 April 1995
;			Returns an error string when no entry is found.
;		Version 6, William Thompson, GSFC, 22 May 1995
;			Made output variable a named structure.
;		Version 7, William Thompson, GSFC, 14 August 1995
;			Modified to call LIST_OBJECT.  Together with changes to
;			that routine, this routine is speeded up.
;			Allow format where abbreviation is followed by the
;			description, e.g. "LMB Solar limb"
;			Make not found error message more descriptive.
;
; Version     :	Version 7, 14 August 1995.
;-
;
	ON_ERROR, 2
;
;  Define a null result.  If the routine is successful, this will be updated
;  later.
;
	DESC = {OBJ_DESC, OBJECT: '', OBJECT_DESC: ''}
;
;  Check the number of parameters.
;
        IF N_PARAMS() NE 2 THEN BEGIN
           MESSAGE = 'Syntax:  GET_OBJECT, OBJECT, DESC'
	   GOTO, HANDLE_ERROR
        ENDIF
;
;  Check the input parameter OBJECT.
;
	IF DATATYPE(OBJECT,1) NE 'String' THEN BEGIN
           MESSAGE = 'OBJECT must be a character string'
           GOTO, HANDLE_ERROR
	END ELSE IF N_ELEMENTS(OBJECT) NE 1 THEN BEGIN
           MESSAGE = 'OBJECT must be a scalar'
           GOTO, HANDLE_ERROR
	ENDIF
;
;  If the object is blank, then return a dummy result.
;
	IF STRTRIM(OBJECT) EQ '' THEN BEGIN
		DESC = {OBJ_DESC, OBJECT: '  ', OBJECT_DESC: ''}
		GOTO, FINISH
	ENDIF
;
;  Call LIST_OBJECT to extract a list of all objects in the database.
;
	LIST_OBJECT, O, N_FOUND
	IF N_FOUND EQ 0 THEN GOTO, FINISH
;
;  Depending on the length of the input string, search on either the OBJECT or
;  the OBJECT_DESC field.
;
	TEST = STRUPCASE(STRTRIM(OBJECT,2))
	IF STRLEN(STRTRIM(OBJECT,2)) GT 3 THEN BEGIN
		W = WHERE(STRUPCASE(O.OBJECT_DESC) EQ TEST, COUNT)
;
;  If not found, perhaps the first word is really the abbreviation.
;
		IF COUNT EQ 0 THEN BEGIN
			TEST = GETTOK(STRCOMPRESS(TEST),' ')
			W = WHERE(STRUPCASE(O.OBJECT) EQ TEST, COUNT)
		ENDIF
	END ELSE BEGIN
		W = WHERE(STRUPCASE(O.OBJECT) EQ TEST, COUNT)
	ENDELSE
;
;  If no entries were found, then return immediately.
;
	IF COUNT EQ 0 THEN BEGIN
		MESSAGE = 'Object entry "' + OBJECT + '" not found'
		GOTO, HANDLE_ERROR
	ENDIF
;
;  Extract the relevant entry from the database.
;
	DESC = O(W(0))
	GOTO, FINISH
;
;  Error handling point.
;
HANDLE_ERROR:
	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = 'GET_OBJECT: ' + MESSAGE $
		ELSE MESSAGE, MESSAGE, /CONTINUE
;
FINISH:
	RETURN
	END