FUNCTION ADD_TILTCAL, DATE_EFF, SPECTRUM, COEFF, ERRMSG=ERRMSG
;+
; Project     :	SOHO - CDS
;
; Name        :	ADD_TILTCAL()
;
; Purpose     :	Register NIS tilt calibrations in the database.
;
; Category    :	Calibration, NIS, Coordinates
;
; Explanation :	Adds an NIS tilt calibration to the database.  The calibration
;		is marked with the current date/time.
;
; Syntax      :	Result = ADD_TILTCAL( DATE_EFF, SPECTRUM, COEFF )
;
; Examples    :	IF NOT ADD_TILTCAL('1995-12-2',1,COEFF) THEN ...
;
; Inputs      :	DATE_EFF = The date, and optionally time, that the value
;			   becomes effective.  In other words, the calibration
;			   value should be applied to all science data taken on
;			   or after that date.  Can be in any CDS time format.
;
;			   The current date is also stored along with the data.
;			   When the database is read in, the most current
;			   version for a given date is used.
;
;			   For example, if there were two values of DATE_EFF in
;			   the database,
;
;				DATE_EFF = 1995/12/02
;				DATE_EFF = 1996/09/16
;
;			   then the first would be used for all data taken
;			   between 1995/12/02 and 1996/09/16, and the second
;			   would be used for all data from 1996/09/16 on.  If
;			   there was more than one entry in the database with
;			   an effective date of 1996/09/16, then the most
;			   recent one would be used.
;
;			   There is one thing to watch out for in maintaining
;			   the database.  Taking the above example, if one
;			   added a calibration with an effective date of
;			   1996/05/01, then it would be applied to data between
;			   that date and the next date in the database,
;			   i.e. 1996/09/16.  If one wanted the new calibration
;			   to apply to all data after 1996/05/01, then one
;			   would have to also add a new entry for 1996/09/16.
;
;		SPECTRUM = Either 1 or 2
;
;		COEFF	 = The NIS tilt calibration coefficients.  The
;			   polynomial
;
;				TILT = POLY(PIXEL, COEFF)
;
;			   returns the tilt as a function of pixel position.
;
; Opt. Inputs :	None.
;
; Outputs     :	The result of the function is a logical value representing
;		whether or not the operation was successful, where 1 is
;		successful and 0 is unsuccessful.
;
; 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 = ''
;				Result = ADD_TILTCAL( ERRMSG=ERRMSG, ... )
;				IF ERRMSG NE '' THEN ...
;
; Calls       :	DATATYPE, GET_UTC, UTC2TAI, DBOPEN, DBBUILD, DBCLOSE
;
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Prev. Hist. :	None.
;
; History     :	Version 1, 13-Jan-1998, William Thompson, GSFC
;
; Contact     :	WTHOMPSON
;-
;
	ON_ERROR, 2
;
;  Initialize RESULT to represent non-success.  If the routine is successful,
;  this value will be updated below.
;
	RESULT = 0
;
;  Check the number of parameters.
;
	IF N_PARAMS() NE 3 THEN BEGIN
	    MESSAGE = 'Syntax:  Result = ADD_TILTCAL( DATE_EFF, COEFF )'
	    GOTO, HANDLE_ERROR
	ENDIF
;
;  Make sure that the user has privilege to write into the database.
;
	IF NOT PRIV_ZDBASE(/CALIB) THEN BEGIN
	    MESSAGE = 'No write privilege to database'
	    GOTO, HANDLE_ERROR
	END ELSE IF !PRIV LT 2 THEN BEGIN $
            MESSAGE = '!PRIV must be 2 or greater to write into the database'
            GOTO, HANDLE_ERROR
	ENDIF
;
;  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
;
;  Check the dimensions of COEFF.
;
	IF N_ELEMENTS(COEFF) GT 10 THEN BEGIN
	    MESSAGE = 'COEFF must have no more than 10 elements'
	    GOTO, HANDLE_ERROR
	ENDIF
;
;  Convert the effective 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_EFF = DOUBLE( STRING( ANYTIM2TAI(DATE_EFF), FORMAT='(F15.3)' ))
;
;  Get the current date, and convert to a TAI value.
;
	GET_UTC, UTC
	TAI = UTC2TAI(UTC)
;
;  Pad the coefficients out to 10 elements.
;
	C = DBLARR(10)
	C(0) = COEFF(*)
;
;  Open the database and insert the data.
;
	DBOPEN, 'nis_tilt', 1
	DBBUILD, TAI, TAI_EFF, FIX(SPECTRUM), FIX(N_ELEMENTS(COEFF)), C, $
		STATUS=STATUS
	IF STATUS EQ 0 THEN BEGIN
	    MESSAGE = 'Write to nis_tilt database was not successful'
	    GOTO, HANDLE_ERROR
	ENDIF
;
;  If we got this far, then we must have been successful.
;
	RESULT = 1
	GOTO, FINISH
;
;  Error handling point.
;
HANDLE_ERROR:
	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = 'ADD_TILTCAL: ' + MESSAGE $
		ELSE MESSAGE, MESSAGE, /CONTINUE
;
;  Close the database, and return whether the routine was successful or not.
;
FINISH:
	DBCLOSE
;
	RETURN, RESULT
	END