PRO PLAN_XCAT_SUMM, TSTART, TEND, ERRMSG=ERRMSG
;+
; Project     :	SOHO - CDS
;
; Name        :	PLAN_XCAT_SUMM
;
; Purpose     :	Prints out a summary of the plan for maintaining XCAT
;
; Category    :	Class4, Planning
;
; Explanation :	Prints out a summary of the CDS detailed science plan that can
;		be used to help maintain the XCAT catalog.  Only those
;		parameters that FITSGEN may have trouble determining are
;		printed out.
;
; Syntax      :	PLAN_XCAT_SUMM, TSTART, TEND
;
; Examples    :	PLAN_XCAT_SUMM, '1996/10/10', '1996/10/11'
;
; Inputs      :	TSTART	= The start date/time of the period to print out the
;			  summary of.  Can be in any CDS time format.
;		TEND	= The end date/time.
;
; Opt. Inputs :	None.
;
; Outputs     :	The summary is written to the temporary file plan_xcat_summ.txt
;		in the user's home directory.
;
; Opt. Outputs:	None.
;
; Keywords    :	ERRMSG    = If defined and passed, then any error messages 
;                           will be returned to the user in this parameter 
;                           rather than being printed to the screen.  If no
;                           errors are encountered, then a null string is
;                           returned.  In order to use this feature, the 
;                           string ERRMSG must be defined first, e.g.,
;
;                                ERRMSG = ''
;                                PLAN_XCAT_SUMM, ERRMSG=ERRMSG, ...
;                                IF ERRMSG NE '' THEN ...
;
; Calls       :	ANYTIM2TAI, LIST_DETAIL, CONCAT_DIR, GET_DETAIL, GET_STUDY,
;		TAI2UTC, TRIM, GET_RASTER, DELVARX, XPRINT
;
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Prev. Hist. :	None.
;
; History     :	Version 1, 17-Jan-1997, William Thompson, GSFC
;		Version 2, 28-Jul-1997, William Thompson, GSFC
;			Added keyword ERRMSG
;			Allow file to be saved instead of printed.
;		Version 3, 10-Aug-1997, William Thompson, GSFC
;			Rearranged output.
;			Added STUDY_ID, STUDYVAR, OBS_PROG, GSET_ID.
;			Don't print ZONE_ID unless GIS study.
;		Version 4, 19-Mar-1999, William Thompson, GSFC
;			Step through ALT and FLAG databases as well
;
; Contact     :	WTHOMPSON
;-
;
;  If !DEBUG is set to anything but zero, then stop within the routine on an
;  error.  Otherwise, return to the calling program on an error.
;
	IF !DEBUG EQ 0 THEN ON_ERROR, 2 ELSE ON_ERROR, 0
;
;  Check the input parameters.
;
	IF N_PARAMS() NE 2 THEN BEGIN
	    MESSAGE = 'Syntax: PLAN_XCAT_SUMM, TSTART, TEND'
	    GOTO, HANDLE_ERROR
	ENDIF
;
	MESSAGE = ''
	START_TIME = ANYTIM2TAI(TSTART, ERRMSG=MESSAGE)
	IF MESSAGE NE '' THEN GOTO, HANDLE_ERROR
	END_TIME   = ANYTIM2TAI(TEND, ERRMSG=MESSAGE)
	IF MESSAGE NE '' THEN GOTO, HANDLE_ERROR
	IF END_TIME LT START_TIME THEN BEGIN
	    MESSAGE = 'The end time must be after the start time'
	    GOTO, HANDLE_ERROR
	ENDIF
;
;  Step through the detailed, alternative, and flag databases.
;
	FILE_OPENED = 0
	N_FOUND_TOTAL = 0
	DATABASE = ['DETAIL','ALT','FLAG']
	FOR I_DATABASE = 0,2 DO BEGIN
;
;  Get the list of all the detailed entries covering the requested time range.
;
	    TEST = EXECUTE('LIST_' + DATABASE(I_DATABASE) +	$
		    ', START_TIME, END_TIME, LIST, N_FOUND, ERRMSG=MESSAGE')
	    IF MESSAGE NE '' THEN GOTO, HANDLE_ERROR
	    IF N_FOUND EQ 0 THEN GOTO, NEXT_DATABASE
;
;  Get the database dependent start and stop times.
;
	    CASE DATABASE(I_DATABASE) OF
		'DETAIL': DATE_OBS = LIST.DATE_OBS
		'ALT':    DATE_OBS = LIST.START_TIME
		'FLAG':   DATE_OBS = LIST.START_TIME
	    ENDCASE
;
;  Open up temporary output file.
;
	    IF NOT FILE_OPENED THEN BEGIN
		FILE = CONCAT_DIR(GETENV('HOME'), 'plan_xcat_summ.txt')
		OPENW, UNIT, FILE, /GET_LUN
		FILE_OPENED = 1
	    END ELSE FOR IDUMMY=0,1 DO PRINTF, UNIT, ''
;
;  Step through each of the plan entries, and get the full details on the
;  entry.
;
	    PRINTF, UNIT, 'Entries from ' + DATABASE(I_DATABASE) + ' database'
	    PRINTF, UNIT, ''
	    FOR I=0,N_FOUND-1 DO BEGIN
		TEST = EXECUTE('GET_' + DATABASE(I_DATABASE) +	$
			', DATE_OBS(I), OBS')
		GET_STUDY, OBS.STUDY_ID, OBS.STUDYVAR, STUDY
;
;  Print out the MAIN-level parameters.
;
		IF I GT 0 THEN PRINTF, UNIT, ''
		PRINTF, UNIT, TAI2UTC(DATE_OBS(I), /VMS) + ' -- ' +	$
			TRIM(STUDY.OBS_PROG) + ', version ' +		$
			TRIM(OBS.STUDYVAR)
		PRINTF, UNIT, ''
		PRINTF, UNIT, 'PROG_ID  = ' + TRIM(OBS.PROG_ID)
		PRINTF, UNIT, 'STUDY_ID = ' + TRIM(OBS.STUDY_ID)
		PRINTF, UNIT, 'STUDYVAR = ' + TRIM(OBS.STUDYVAR)
		PRINTF, UNIT, 'OBS_PROG = ' + TRIM(STUDY.OBS_PROG)
		PRINTF, UNIT, 'SCI_OBJ  = ' + TRIM(OBS.SCI_OBJ)
		PRINTF, UNIT, 'SCI_SPEC = ' + TRIM(OBS.SCI_SPEC)
		PRINTF, UNIT, 'CMP_NO   = ' + TRIM(OBS.CMP_NO)
		PRINTF, UNIT, 'OBJECT   = ' + TRIM(OBS.OBJECT)
		OBJ_ID = TRIM(OBS.OBJ_ID)
		IF OBJ_ID NE '' THEN	$
			PRINTF, UNIT, 'OBJ_ID   = ' + TRIM(OBJ_ID)
		IF OBS.TRACKING NE 0 THEN	$
			PRINTF, UNIT, 'TRACKING = ' + TRIM(OBS.TRACKING)
		PRINTF, UNIT, ''
;
;  Step through the rasters of the study, and print out the EXPERIMENT-level
;  parameters.
;
		RAS_ID  = -999
		RAS_VAR = -999
		FOR J=0,N_ELEMENTS(STUDY.RASTERS)-1 DO BEGIN
		    RASTER = STUDY.RASTERS(J)
		    IF (RAS_ID NE RASTER.RAS_ID) OR	$
			    (RAS_VAR NE RASTER.RAS_VAR) THEN BEGIN
			RAS_ID  = RASTER.RAS_ID
			RAS_VAR = RASTER.RAS_VAR
			GET_RASTER, RAS_ID, RAS_VAR, RASDEF
			IF RASDEF.RAS_ID GT 0 THEN BEGIN
			    PRINTF, UNIT, '    OBS_SEQ  = R' + TRIM(RAS_ID) + $
				    'V' + TRIM(RAS_VAR)
			    PRINTF, UNIT, '    RAS_ID   = ' + TRIM(RAS_ID)
			    PRINTF, UNIT, '    RAS_VAR  = ' + TRIM(RAS_VAR)
			    IF RASDEF.DETECTOR EQ 'N' THEN		$
				    PRINTF, UNIT, '    EXPTIME  = ' +	$
				    TRIM(RASDEF.EXPTIME)
			    PRINTF, UNIT, '    OBS_MODE = ' +		$
				    RASDEF.DETECTOR + 'IS-S' +		$
				    TRIM(RASDEF.SLIT_NUM) + '-R' +	$
				    TRIM(RAS_ID>0) + '-E' +		$
				    TRIM(RASDEF.EXPTIME)
			    IF RASDEF.DETECTOR EQ 'G' THEN BEGIN
				PRINTF, UNIT, '    GSET_ID  = ' +	$
					TRIM(OBS.GSET_ID)
				PRINTF, UNIT, '    ZONE_ID  = ' +	$
					TRIM(OBS.POINTINGS(0).ZONE_ID)
			    ENDIF
			    PRINTF, UNIT, ''
			ENDIF
		    ENDIF
		ENDFOR
	    ENDFOR
;
;  Keep track of the total number of entries processed, and go on to the next
;  database.
;
NEXT_DATABASE:
	    N_FOUND_TOTAL = N_FOUND_TOTAL + N_FOUND
	ENDFOR
;
;  If no entries at all were processed, then generate an error message.
;
	IF N_FOUND_TOTAL EQ 0 THEN BEGIN
	    MESSAGE = 'No plan entries found for selected date range'
	    GOTO, HANDLE_ERROR
	ENDIF
;
;  Close the file, and delete the logical unit number parameter, so that the
;  program knows that the file has been closed.
;
	FREE_LUN, UNIT
	DELVARX, UNIT
;
;  Print the file and return.
;
	TEXT = ['Output complete, do you want to print it?',	$
		'',						$
		'(If no, then the output will be saved in file',	$
		FILE+')']
	IF XANSWER(TEXT) THEN XPRINT, FILE, /DELETE
	RETURN
;
; Error handling point.
;
HANDLE_ERROR:
	IF N_ELEMENTS(UNIT) EQ 1 THEN FREE_LUN,UNIT
	IF N_ELEMENTS(ERRMSG) EQ 0 THEN MESSAGE, MESSAGE ELSE	$
		ERRMSG = 'PLAN_XCAT_SUMM: ' + MESSAGE
	END