PRO LIST_DETAIL, START, EEND, OBS, N_FOUND, ERRMSG=ERRMSG
;+
; Project     :	SOHO - CDS
;
; Name        :	LIST_DETAIL
;
; Purpose     :	List the CDS detailed science plan for a given date range.
;
; Explanation :	Extracts all the CDS detailed science plan entries which
;		intersect an input time range.
;
; Use         :	LIST_DETAIL, START, END, OBS, 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     :	OBS	= A structure variable containing the following tags
;			  for each planned observation:
;
;			STRUCT_TYPE= The character string 'CDS-DETAIL-LIST'
;			PROG_ID	   = Program ID, linking one or more studies
;				     together
;			STUDY_ID   = Number defining the study
;			STUDYVAR   = Number giving the study variation ID
;			SCI_OBJ    = Science objective from the daily science
;				     meeting
;			SCI_SPEC   = Specific science objective from meeting
;			CMP_NO	   = Campaign number
;			OBJECT	   = Code for object planned to be observed
;			OBJ_ID	   = Object identification
;			DATE_OBS   = Date/time of beginning of observation,
;				     in TAI format
;			DATE_END   = Date/time of end of observation, in TAI
;				     format
;			ORIG_DUR   = Original duration of the observation, in
;				     seconds, before being truncated by
;				     following time-tagged observations.
;			N_RASTERS1 = Variable number of rasters parameter
;			TIME_TAGGED= True (1) if the start of the study is to
;				     be a time-tagged event.  Otherwise, the
;				     study will begin immediately after the
;				     previous study.
;			TRACKING   = True (1) if feature tracking to be used,
;				     or false (0) otherwise
;			N_POINTINGS= Number of pointings to use with study.
;			N_REPEAT_S = Number of times to repeat study.
;			FLAG_MASTER= Nonzero if flag master.
;			GSET_ID	   = GSET ID number
;			GET_RAW	   = True if raw data should be collected.
;			PROG_NUM   = Study counter number (negative is
;				     predicted)
;
;		N_FOUND	= Number of planned observations found.
;
; 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 = ''
;                       LIST_DETAIL, ERRMSG=ERRMSG, ...
;                       IF ERRMSG NE '' THEN ...
;
;
; Calls       :	DATATYPE, DBOPEN, DBFIND, DBEXT, DBCLOSE, TRIM
;
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	If the number of planned observations found is zero, then the
;		output parameter OBS is not modified.
;
; Category    :	Planning, Database.
;
; Prev. Hist. :	None.
;
; Written     :	William Thompson, GSFC, 26 July 1994
;
; Modified    :	Version 1, William Thompson, GSFC, 3 August 1994
;               Version 2, Liyun Wang, GSFC/ARC, September 22, 1994
;                  Added the keyword ERRMSG.
;		Version 3, William Thompson, GSFC, 21 November 1994
;			Modified so that items which only touch requested range
;			are excluded.
;			Added item N_REPEAT_S.
;		Version 4, William Thompson, GSFC, 26 January 1995
;			Added tag STRUCT_TYPE
;		Version 5, William Thompson, GSFC, 13 February 1995
;			Changed the way that pointing is treated.
;		Version 6, William Thompson, GSFC, 8 May 1995
;			Modified to pay attention to DELETED field in database
;		Version 7, William Thompson, GSFC, 20 June 1995
;			Added tag FLAG_MASTER
;		Version 8, William Thompson, GSFC, 28 September 1995
;			Added tags ORIG_DUR, GSET_ID, GET_RAW
;		Version 9, William Thompson, GSFC, 4 June 1997
;			Added tag PROG_NUM
;		Version 10, William Thompson, GSFC, 26 May 1998
;			Look for entries in "_year" files
;
; Version     :	Version 10, 26 May 1998
;-
;
	ON_ERROR, 2
;
;  Check the number of parameters.
;
	N_FOUND = 0
        IF N_PARAMS() LT 4 THEN BEGIN
           MESSAGE = 'Syntax:  LIST_DETAIL, START, END, OBS, N_FOUND'
	   GOTO, HANDLE_ERROR
        ENDIF
;
;  Check the input parameters.
;
	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
;
;  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 detailed science plan database.
;
	TRAILER = ''
;
OPEN_DATABASE:
	DBOPEN, 'sci_details' + TRAILER
;
;  Find all the entries in the requested time range.
;
	ENTRIES = DBFIND('DATE_END>' + TRIM(TAI_START,'(F15.3)') +	$
		',DATE_OBS<' + TRIM(TAI_END,'(F15.3)') + ',DELETED=N', /SILENT)
	IF !ERR EQ 0 THEN BEGIN
	    IF TRAILER EQ '' THEN BEGIN
		TEMP = ANYTIM2UTC(START,/EXT)
		TRAILER = "_" + TRIM(TEMP.YEAR)
		FILE = FIND_WITH_DEF('sci_details'+TRAILER+'.dbf', '$ZDBASE')
		IF FILE NE '' THEN GOTO, OPEN_DATABASE
	    ENDIF
	    N_FOUND = 0
	    GOTO, FINISH
	END ELSE BEGIN
	    ENTRIES = ENTRIES(UNIQ(ENTRIES))
	    N_FOUND = N_ELEMENTS(ENTRIES)
	ENDELSE
;
;  Extract the requested entries, sorted by start times.
;
	ENTRIES = DBSORT(ENTRIES,'date_obs')
	DBEXT, ENTRIES, 'prog_id,study_id,studyvar,sci_obj,sci_spec,cmp_no', $
		PROG_ID, STUDY_ID, STUDYVAR, SCI_OBJ, SCI_SPEC, CMP_NO
	DBEXT, ENTRIES, 'object,obj_id,date_obs,date_end,n_rasters1', $
		OBJECT, OBJ_ID, DATE_OBS, DATE_END, N_RASTERS1
	DBEXT, ENTRIES, 'time_tagged,tracking,n_pointings,n_repeat_s', $
		TIME_TAGGED, TRACKING, N_POINTINGS, N_REPEAT_S
	DBEXT, ENTRIES, 'flag_master,orig_dur,gset_id,get_raw,prog_num', $
		FLAG_MASTER, ORIG_DUR, GSET_ID, GET_RAW, PROG_NUM
;
;  Remove any entries that only touch the requested time range.
;
	W = WHERE((DATE_END NE TAI_START) AND (DATE_OBS NE TAI_END), N_FOUND)
	IF N_FOUND EQ 0 THEN GOTO, FINISH
;
;  Define the structure that the data will be returned in.
;
	OBS = { STRUCT_TYPE: 'CDS-DETAIL-LIST',	$
		PROG_ID: 0,		$
		STUDY_ID: 0,		$
		STUDYVAR: 0,		$
		SCI_OBJ: 'String',	$
		SCI_SPEC: 'String',	$
		CMP_NO: 0,		$
		OBJECT: 'String',	$
		OBJ_ID: 'String',	$
		DATE_OBS: 0.0D0,	$
		DATE_END: 0.0D0,	$
		ORIG_DUR: 0.0D0,	$
		N_RASTERS1: 0,		$
		TIME_TAGGED: 0B,	$
		TRACKING: 0B,		$
		N_POINTINGS: 0,		$
		N_REPEAT_S: 0,		$
		FLAG_MASTER: 0,		$
		GSET_ID: 0,		$
		GET_RAW: 0B,		$
		PROG_NUM: 0L}
;
	IF N_FOUND EQ 1 THEN BEGIN
		OBS.PROG_ID	= PROG_ID(W(0))
		OBS.STUDY_ID	= STUDY_ID(W(0))
		OBS.STUDYVAR	= STUDYVAR(W(0))
		OBS.SCI_OBJ	= SCI_OBJ(W(0))
		OBS.SCI_SPEC	= SCI_SPEC(W(0))
		OBS.CMP_NO	= CMP_NO(W(0))
		OBS.OBJECT	= OBJECT(W(0))
		OBS.OBJ_ID	= OBJ_ID(W(0))
		OBS.DATE_OBS	= DATE_OBS(W(0))
		OBS.DATE_END	= DATE_END(W(0))
		OBS.ORIG_DUR	= ORIG_DUR(W(0))
		OBS.N_RASTERS1	= N_RASTERS1(W(0))
		OBS.TIME_TAGGED	= TIME_TAGGED(W(0))
		OBS.TRACKING	= TRACKING(W(0))
		OBS.N_POINTINGS	= N_POINTINGS(W(0))
		OBS.N_REPEAT_S	= N_REPEAT_S(W(0))
		OBS.FLAG_MASTER	= FLAG_MASTER(W(0))
		OBS.GSET_ID	= GSET_ID(W(0))
		OBS.GET_RAW	= GET_RAW(W(0))
		OBS.PROG_NUM	= PROG_NUM(W(0))
	END ELSE BEGIN
		OBS = REPLICATE(OBS, N_FOUND)
		OBS.PROG_ID	= PROG_ID(W)
		OBS.STUDY_ID	= STUDY_ID(W)
		OBS.STUDYVAR	= STUDYVAR(W)
		OBS.SCI_OBJ	= SCI_OBJ(W)
		OBS.SCI_SPEC	= SCI_SPEC(W)
		OBS.CMP_NO	= CMP_NO(W)
		OBS.OBJECT	= OBJECT(W)
		OBS.OBJ_ID	= OBJ_ID(W)
		OBS.DATE_OBS	= DATE_OBS(W)
		OBS.DATE_END	= DATE_END(W)
		OBS.ORIG_DUR	= ORIG_DUR(W)
		OBS.N_RASTERS1	= N_RASTERS1(W)
		OBS.TIME_TAGGED	= TIME_TAGGED(W)
		OBS.TRACKING	= TRACKING(W)
		OBS.N_POINTINGS	= N_POINTINGS(W)
		OBS.N_REPEAT_S	= N_REPEAT_S(W)
		OBS.FLAG_MASTER	= FLAG_MASTER(W)
		OBS.GSET_ID	= GSET_ID(W)
		OBS.GET_RAW	= GET_RAW(W)
		OBS.PROG_NUM	= PROG_NUM(W)
	ENDELSE
	GOTO, FINISH
;
;  Error handling point.
;
HANDLE_ERROR:
	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = 'LIST_DETAIL: ' + MESSAGE $
		ELSE MESSAGE, MESSAGE, /CONTINUE
;
;  Close the database and return.
;
FINISH:
	DBCLOSE
;
	RETURN
	END