PRO GET_TILTCAL, SPECTRUM, REQ_DATE, COEFF, ERRMSG=ERRMSG
;+
; Project     :	SOHO - CDS
;
; Name        :	GET_TILTCAL
;
; Purpose     :	Get the NIS tilt calibration for a given date.
;
; Category    :	Calibration, NIS, Coordinates
;
; Explanation :	Looks up the NIS tilt calibration in the database for a given
;		spectrum and date combination.  First, the software finds the
;		largest effective date which is on or earlier than the
;		observation date.  If there are multiple entries with the same
;		effective date, then the one with the latest entry date is
;		used.
;
; Syntax      :	GET_TILTCAL, SPECTRUM, REQ_DATE, COEFF
;
; Examples    :	GET_TILTCAL, 1, DATE, TILTCAL
;		IF TILTCAL.DATE NE '' THEN ...
;
; Inputs      :	SPECTRUM = Either 1 or 2
;
;		REQ_DATE = The date to use in searching for a wavelength
;			   calibration.
;
; Opt. Inputs :	None.
;
; Outputs     :	COEFF	 = The NIS tilt calibration coefficients.  The
;			   polynomial
;
;				TILT = POLY(PIXEL, COEFF)
;
;			   returns the tilt as a function of pixel position.

;
; 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_TILTCAL, ERRMSG=ERRMSG, ...
;				IF ERRMSG NE '' THEN ...
;
; Calls       :	
;
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Prev. Hist. :	None.
;
; History     :	Version 1, 13-Jan-1998, William Thompson, GSFC
;               Modified, 26-Nov-2004, Zarro (L-3Com/GSFC) -
;                - added DBCLOSE on error handling
;
; Contact     :	WTHOMPSON
;-
;
	ON_ERROR, 2
;
;  Check the input parameters.
;
	IF N_PARAMS() NE 3 THEN BEGIN
	    MESSAGE = 'Syntax:  GET_TILTCAL, SPECTRUM, REQ_DATE, COEFF'
	    GOTO, HANDLE_ERROR
	ENDIF
;
;  Convert the observation date to TAI format.  Reformat the time to
;  millisecond accuracy.  This is necessary so that the times are written out
;  in a controlled way.
;
	TAI = DOUBLE( STRING( ANYTIM2TAI(REQ_DATE), FORMAT='(F15.3)' ))
;
;  Check the spectrum value.
;
	IF (SPECTRUM NE 1) AND (SPECTRUM NE 2) THEN BEGIN
	    MESSAGE = 'SPECTRUM must be either 1 or 2'
	    GOTO, HANDLE_ERROR
	ENDIF
;
;  Find all entries in the database matching the search criteria.
;
	DBOPEN, 'nis_tilt'
	ENTRIES = DBFIND('SPECTRUM=' + TRIM(SPECTRUM) + ',DATE_EFF<' +	$
		TRIM(TAI,'(F15.3)'), /SILENT)
;
;  If nothing found, then pick the earliest date in the database.
;
	IF ENTRIES(0) LE 0 THEN BEGIN
	    MESSAGE, /CONTINUE, 'No data found for date ' +	$
		    ANYTIM2UTC(REQ_DATE,/VMS) + ', using earliest date'
	    ENTRIES = DBFIND('SPECTRUM=' + TRIM(SPECTRUM), /SILENT)
	    IF ENTRIES(0) LE 0 THEN BEGIN
		MESSAGE='No data found for spectrum ' + trim(SPECTRUM)
		GOTO, HANDLE_ERROR
	    ENDIF
	    IF N_ELEMENTS(ENTRIES) GT 1 THEN	$
		    ENTRIES = DBSORT(ENTRIES, 'DATE_EFF')
;
;  Otherwise, pick the latest date matching the search criteria.
;
	END ELSE IF N_ELEMENTS(ENTRIES) GT 1 THEN	$
		ENTRIES = DBSORT(ENTRIES, 'DATE_EFF', REVERSE=[1])
;
;  Find all entries with the selected effective date, and sort on the entry
;  date.
;
	DBEXT, ENTRIES(0), 'date_eff', DATE_EFF
	ENTRIES = DBFIND('SPECTRUM=' + TRIM(SPECTRUM) + ',DATE_EFF=' +	$
		TRIM(DATE_EFF,'(F15.3)'), /SILENT)
	IF N_ELEMENTS(ENTRIES) GT 1 THEN	$
		ENTRIES = DBSORT(ENTRIES, 'DATE', REVERSE=[1])
;
;  Extract the data.
;
	DBEXT, ENTRIES(0), 'n_coeff,coeff', N_COEFF, COEFF
	DBCLOSE
	COEFF = COEFF(0:N_COEFF(0)-1)
	RETURN
;
;  Error handling point.
;
HANDLE_ERROR:
	DBCLOSE
	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = 'GET_EFFICIENCY: ' + MESSAGE $
		ELSE MESSAGE, MESSAGE
;
	END