FUNCTION ADD_NRT_RES, RES, ERRMSG=ERRMSG
;+
; Project     :	SOHO - CDS
;
; Name        :	ADD_NRT_RES()
;
; Purpose     :	Adds an entry to the NRT reserved database.
;
; Explanation :	This procedure adds an entry for a given instrument for NRT
;		reserved time to the "nrt_reserved" database.
;
; Use         :	Result = ADD_NRT_RES( RES )
;
;		IF ADD_NRT_RES( RES ) EQ 0 THEN ...
;
; Inputs      :	RES = A structure variable containing the following tags:
;
;			INSTRUME   = Single letter code specifying the
;				     instrument.
;			START_TIME = The start time of the reserved time
;			END_TIME   = The end time of the reserved time.
;			CMD_RATE   = The expected average number of OBDH block
;				     commands per minute between the start time
;				     and end time.
;			STATUS	   = The acceptance status for this activity.
;				     Possible values are REQUESTED, CONFIRMED,
;				     or DENIED.  Only the first character is
;				     stored in the database.
;
;		      It can also be an array of such structures.
;
; 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_NRT_RES( ERRMSG=ERRMSG, ... )
;                       IF ERRMSG NE '' THEN ...
;
; Calls       :	DATATYPE, DBOPEN, DB_INFO, DBBUILD, DBCLOSE, DBFIND, DBMATCH
;
; Common      :	None.
;
; Restrictions:	Only this routine or CLR_NRT_RES can be used to add or delete
;		NRT reserved entries to the database.  Modifying the database
;		by hand could corrupt its integrity.
;
;		The data types and sizes of the structure elements must match
;		the definitions in the database.
;
;		!PRIV must be 2 or greater to use this routine.
;
; Side effects:	None.
;
; Category    :	Planning, Databases.
;
; Prev. Hist. :	None.
;
; Written     :	William Thompson, GSFC, 3 April 1995
;
; Modified    :	Version 1, William Thompson, GSFC, 3 April 1995
;		Version 2, William Thompson, GSFC, 22 May 1995
;			Modified to allow array inputs.
;
; Version     :	Version 2, 22 May 1995
;-
;
	ON_ERROR, 2
;
;  Check the input parameters
;
	IF N_PARAMS() NE 1 THEN BEGIN
		MESSAGE = 'Syntax:  Result = ADD_NRT_RES(RES)'
		GOTO, HANDLE_ERROR
	ENDIF
;
;  Make sure that the user has privilege to write into the database.
;
	IF !PRIV LT 2 THEN BEGIN
	   MESSAGE = '!PRIV must be 2 or greater to write into the database'
	   GOTO, HANDLE_ERROR
	ENDIF
;
;  Initialize the STATUS_CODE array.
;
	STATUS_CODE = STRARR(N_ELEMENTS(RES))
;
;  Check each of the structure components to verify that it is of the correct
;  type and size.
;
	FOR I = 0,N_ELEMENTS(RES)-1 DO BEGIN
	    IF DATATYPE(RES(I).INSTRUME,1) NE 'String' THEN BEGIN
	       MESSAGE = 'Tag INSTRUME must be a character string'
	       GOTO, HANDLE_ERROR
	    END ELSE IF N_ELEMENTS(RES(I).INSTRUME) NE 1 THEN BEGIN
	       MESSAGE = 'Tag INSTRUME must be a scalar'
	       GOTO, HANDLE_ERROR
	    END ELSE IF STRLEN(RES(I).INSTRUME) NE 1 THEN BEGIN $
	       MESSAGE = 'Tag INSTRUME must be a single character'
	       GOTO, HANDLE_ERROR
	    ENDIF
;
	    IF DATATYPE(RES(I).START_TIME,1) NE 'Double' THEN BEGIN
	       MESSAGE = 'Tag START_TIME must be a double precision number'
	       GOTO, HANDLE_ERROR
	    END ELSE IF N_ELEMENTS(RES(I).START_TIME) NE 1 THEN BEGIN
	       MESSAGE = 'Tag START_TIME must be a scalar'
	       GOTO, HANDLE_ERROR
	    ENDIF
;
	    IF DATATYPE(RES(I).END_TIME,1) NE 'Double' THEN BEGIN
	       MESSAGE = 'Tag END_TIME must be a double precision number'
	       GOTO, HANDLE_ERROR
	    END ELSE IF N_ELEMENTS(RES(I).END_TIME) NE 1 THEN BEGIN
	       MESSAGE = 'Tag END_TIME must be a scalar'
	       GOTO, HANDLE_ERROR
	    ENDIF
;
	    IF DATATYPE(RES(I).CMD_RATE,1) NE 'Integer' THEN BEGIN
	       MESSAGE = 'Tag CMD_RATE must be a short integer'
	       GOTO, HANDLE_ERROR
	    END ELSE IF N_ELEMENTS(RES(I).CMD_RATE) NE 1 THEN BEGIN
	       MESSAGE = 'Tag CMD_RATE must be a scalar'
	       GOTO, HANDLE_ERROR
	    ENDIF
;
	    IF DATATYPE(RES(I).STATUS,1) NE 'String' THEN BEGIN
	       MESSAGE = 'Tag STATUS must be a character string'
	       GOTO, HANDLE_ERROR
	    END ELSE IF N_ELEMENTS(RES(I).STATUS) NE 1 THEN BEGIN
	       MESSAGE = 'Tag STATUS must be a scalar'
	       GOTO, HANDLE_ERROR
	    ENDIF
;
;  Make sure that the instrument code is valid.
;
	    GET_INSTRUMENT, RES(I).INSTRUME, TEMP
	    IF TEMP.CODE EQ '' THEN BEGIN
	        MESSAGE = 'Instrument ' + RES(I).INSTRUME +	$
			' not found in database'
	        GOTO, HANDLE_ERROR
	    ENDIF
	    IF I EQ 0 THEN INS = REPLICATE(TEMP,N_ELEMENTS(RES)) ELSE	$
		INS(I) = TEMP
;
;  Make sure that the STATUS tag is valid.
;
	    CASE STRUPCASE(RES(I).STATUS) OF
		'REQUESTED':	STATUS_CODE(I) = 'R'
		'CONFIRMED':	STATUS_CODE(I) = 'C'
		'DENIED':	STATUS_CODE(I) = 'D'
		ELSE: BEGIN
			MESSAGE = 'Status code ' + RES(I).STATUS +	$
				' not recognized'
			GOTO, HANDLE_ERROR
			END
	    ENDCASE
	ENDFOR
;
;  Open the database for write access.
;
	DBOPEN, 'nrt_reserved', 1
;
;  Append the data to the opened database.
;
	DBBUILD, RES.START_TIME, RES.END_TIME, INS.CODE, RES.CMD_RATE,	$
		STATUS_CODE, STATUS=STATUS
	IF STATUS EQ 0 THEN BEGIN
	   MESSAGE = 'Write to NRT reserved database was not successful'
	   GOTO, HANDLE_ERROR
	ENDIF
;
	RESULT = 1
	GOTO, FINISH
;
;  Handle any errors encountered.
;
HANDLE_ERROR:
	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = 'ADD_NRT_RES: ' + MESSAGE $
		ELSE MESSAGE, MESSAGE, /CONTINUE
	RESULT = 0
;
;  Close the database, and return whether the routine was successful or not.
;
FINISH:
	DBCLOSE
;
	RETURN, RESULT
	END