PRO LIST_NRT_RES, START, EEND, RES, N_FOUND, ERRMSG=ERRMSG,	$
		INSTRUMENT=INSTRUMENT
;+
; Project     :	SOHO - CDS
;
; Name        :	LIST_NRT_RES
;
; Purpose     :	List the NRT reserved times for a given period
;
; Explanation :	Extracts all the instrument NRT reserved times in the input
;		time range.
;
; Use         :	LIST_NRT_RES, START, END, RES, N_FOUND
;
; Inputs      :	START, END = The range of date/time values to use in searching
;			     the database.  Can be in any standard CDS time
;			     format.
;
; Opt. Inputs :	None.
;
; Outputs     :	RES	= A structure variable containing the following tags
;			  for each NRT reserved period:
;
;			INSTRUME   = Single letter code specifying the
;				     instrument.
;			START_TIME = The start time of the reserved time, in
;				     TAI format.
;			END_TIME   = The end time of the reserved time, in TAI
;				     format.
;			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 R=requested,
;				     C=confirmed, or D=denied.  Only the first
;				     character is stored in the database.
;
;		N_FOUND	= Number of NRT reserved periods found.
;
; Opt. Outputs:	None.
;
; Keywords    :	
;	INSTRUMENT= If passed, then only the NRT reserved periods for the
;		    specified instrument will be returned.  Can be either a
;		    code letter or the full name.  (See GET_INSTRUMENT.)
;
;       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 = ''
;                       LIST_NRT_RES, ERRMSG=ERRMSG, ... 
;                       IF ERRMSG NE '' THEN ...
;
;
; Calls       :	DATATYPE, DBOPEN, DBFIND, DBEXT, DBCLOSE, TRIM, GET_INSTRUMENT
;
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	If the number of planned NRT reserved periods found is zero,
;		then the output parameter RES is not modified.
;
; Category    :	Planning, Database.
;
; Prev. Hist. :	None.
;
; Written     :	William Thompson, GSFC, 3 April 1995
;
; Modified    :	Version 1, William Thompson, GSFC, 3 April 1995
;		Version 2, William Thompson, GSFC, 7 April 1995
;			Fixed bug with multiple entries.
;		Version 3, William Thompson, GSFC, 11 April 1995
;			Added keyword INSTRUMENT
;		Version 4, William Thompson, GSFC, 17 August 1995
;			Fixed bug when only one entry is found.
;		Version 5, William Thompson, GSFC, 13 March 1996
;			Changed order of parameters in output structure.
;
; Version     :	Version 5, 13 March 1996
;-
;
	ON_ERROR, 2
;
;  Check the number of parameters.
;
        IF N_PARAMS() LT 4 THEN BEGIN
           MESSAGE = 'Syntax:  LIST_NRT_RES, START, END, RES, N_FOUND'
	   GOTO, HANDLE_ERROR
        ENDIF
;
;  Check the input parameters.
;
	N_FOUND = 0
	IF N_ELEMENTS(START) NE 1 THEN BEGIN
           MESSAGE = 'START must be a scalar'
           GOTO, HANDLE_ERROR
	END ELSE IF N_ELEMENTS(EEND) NE 1 THEN BEGIN
           MESSAGE = 'END must be a scalar'
           GOTO, HANDLE_ERROR
	ENDIF
;
;  If the INSTRUMENT keyword was passed, then determine which instrument this
;  refers to.
;
	IF N_ELEMENTS(INSTRUMENT) EQ 1 THEN BEGIN
		GET_INSTRUMENT, INSTRUMENT, INS, ERRMSG=ERRMSG
		IF N_ELEMENTS(ERRMSG) NE 0 THEN IF ERRMSG(0) NE '' THEN BEGIN
			MESSAGE = ERRMSG
			GOTO, HANDLE_ERROR
		ENDIF
	ENDIF
;
;  Convert the input dates to TAI format.
;
	IF DATATYPE(START,1) EQ 'Double' THEN TAI_START = START ELSE	$
		TAI_START = UTC2TAI(START)
	IF DATATYPE(EEND,1) EQ 'Double' THEN TAI_END = EEND ELSE	$
		TAI_END = UTC2TAI(EEND)
;
;  Open the NRT reserved database.
;
	DBOPEN, 'nrt_reserved'
;
;  Find all the entries in the requested time range.
;
	TEST = 'END_TIME>' + TRIM(TAI_START,'(F15.3)') + ',START_TIME<' + $
		TRIM(TAI_END,'(F15.3)')
	IF N_ELEMENTS(INSTRUMENT) EQ 1 THEN TEST = TEST +	$
		',INSTRUME=' + INS.CODE
;
	ENTRIES = DBFIND(TEST, /SILENT)
	IF N_ELEMENTS(ENTRIES) GT 1 THEN ENTRIES = ENTRIES(UNIQ(ENTRIES))
	IF ENTRIES(0) LE 0 THEN BEGIN
		N_FOUND = 0
		GOTO, FINISH
	ENDIF
	N_FOUND = N_ELEMENTS(ENTRIES)
;
;  Extract the requested entries, sorted by start times.
;
	ENTRIES = DBSORT(ENTRIES,'start_time')
	DBEXT, ENTRIES, 'instrume,start_time,end_time,cmd_rate,status',	$
		INSTRUME, START_TIME, END_TIME, CMD_RATE, STATUS
;
;  Remove any entries that only touch the requested time range.
;
	W = WHERE((END_TIME NE TAI_START) AND (START_TIME NE TAI_END), N_FOUND)
	IF N_FOUND EQ 0 THEN GOTO, FINISH
;
;  Define the structure that the data will be returned in.
;
	RES = { START_TIME: 0.0D0,	$
		END_TIME: 0.0D0,	$
		INSTRUME: 'S',		$
		CMD_RATE: 0,		$
		STATUS: 'S'}
;
	IF N_FOUND EQ 1 THEN BEGIN
		RES.INSTRUME	= INSTRUME(W(0))
		RES.START_TIME	= START_TIME(W(0))
		RES.END_TIME	= END_TIME(W(0))
		RES.CMD_RATE	= CMD_RATE(W(0))
		RES.STATUS	= STATUS(W(0))
	END ELSE BEGIN
		RES = REPLICATE(RES, N_FOUND)
		RES.INSTRUME	= INSTRUME(W)
		RES.START_TIME	= START_TIME(W)
		RES.END_TIME	= END_TIME(W)
		RES.CMD_RATE	= CMD_RATE(W)
		RES.STATUS	= STATUS(W)
	ENDELSE
;
	GOTO, FINISH
;
;  Handle any errors encountered.
;
HANDLE_ERROR:
	IF N_ELEMENTS(ERRMSG) NE 0 THEN		$
		ERRMSG = 'LIST_NRT_RES: ' + MESSAGE ELSE MESSAGE, MESSAGE 
;
;  Close the database and return.
;
FINISH:
	DBCLOSE
;
	RETURN
	END