FUNCTION PRG_DETAIL, ERRMSG=ERRMSG, YEAR=YEAR
;+
; Project     :	SOHO - CDS
;
; Name        :	PRG_DETAIL()
;
; Purpose     :	Purges old and deleted CDS detailed science plan records
;
; Explanation :	This routine removes all entries from the SoHO/CDS detailed
;		science plan database which are marked for deletion.  Later,
;		this routine may be updated to age off old entries from the
;		database as well.
;
; Use         :	PRG_DETAIL
;
; Inputs      :	None.
;
; 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    :	YEAR	= If set, then all entries with a start date within
;			  that year are moved to a database specifically set
;			  aside for that year.
;
;		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 = PRG_DETAIL( ERRMSG=ERRMSG )
;				IF ERRMSG NE '' THEN ...
;
; Calls       :	DATATYPE, DBOPEN, DBFIND, DBEXT, DBCLOSE, TRIM
;
; Common      :	None.
;
; Restrictions:	None.
;
; Side effects:	None.
;
; Category    :	Planning, Databases.
;
; Prev. Hist. :	None.
;
; Written     :	William Thompson, GSFC, 8 May 1995
;
; Modified    :	Version 1, William Thompson, GSFC, 8 May 1995
;		Version 2, William Thompson, GSFC, 26 May 1998
;			Added keyword YEAR
;
; Version     :	Version 2, 26 May 1998
;-
;
	ON_ERROR, 2
;
;  Initialize RESULT to represent non-success.  If the routine is successful,
;  this value will be updated below.
;
	RESULT = 0
;
;  Make sure that the user has privilege to write into the database.
;
	IF !PRIV LT 3 THEN BEGIN $
           MESSAGE = '!PRIV must be 3 or greater to write into the database'
           GOTO, HANDLE_ERROR
	ENDIF
;
;  Open the details database for update, and search for entries which are
;  marked for deletion.  Delete any that are found.
;
	DBOPEN, 'sci_details', 1
	ENTRIES = DBFIND('DELETED=Y', /SILENT)
	IF !ERR GT 0 THEN DBDELETE, ENTRIES
;
;  Open the pointings database for update, and do the same there.
;
	DBOPEN, 'point_details', 1
	ENTRIES = DBFIND('DELETED=Y', /SILENT)
	IF !ERR GT 0 THEN DBDELETE, ENTRIES
;
;  If the year keyword was set, then create the new year database.  First, go
;  to the directory containing the main database.
;
	IF N_ELEMENTS(YEAR) EQ 1 THEN BEGIN
	    FOR I_TYPE = 0,1 DO BEGIN
		IF I_TYPE EQ 0 THEN FILE0 = 'sci_details' ELSE	$
			FILE0 = 'point_details'
		CD, CURRENT=CURRENT
		FILE = FIND_WITH_DEF(FILE0 + '.dbf', '$ZDBASE')
		BREAK_FILE, FILE, DISK, DIR
		CD, DISK+DIR
		TEMP = ANYTIM2UTC(TRIM(YEAR) + '-1-1', /EXT)
		TYEAR = TEMP.YEAR
		FILE = FILE0 + '_' + TRIM(TYEAR)
		IF FILE_EXIST(FILE+'.dbf') THEN BEGIN
		    MESSAGE = 'Database ' + FILE + ' already exists'
		    GOTO, HANDLE_ERROR
		ENDIF
;
;  Recreate the index file, to pick up any changes in the size parameter.
;
		DBCLOSE
		DBCREATE, FILE0, 1, /EXTERNAL
		DBOPEN, FILE0, 1
		DBINDEX
;
;  Find all entries which begin in the target year.
;
	    	DBEXT, -1, 'date_obs', DATE_OBS
		TEMP = TAI2UTC(DATE_OBS, /EXT)
		ENTRIES = WHERE(TEMP.YEAR EQ TYEAR, COUNT) + 1L
		IF COUNT EQ 0 THEN BEGIN
		    MESSAGE = 'No entries found for the year ' + TRIM(TYEAR)
		    GOTO, HANDLE_ERROR
		ENDIF
;
;  Create the new database by copying the old database.
;
	    	CASE OS_FAMILY() OF
		    'vms': COPY = 'COPY'
		    'unix': COPY = 'cp'
		    ELSE: BEGIN
			MESSAGE, 'Only supported in VMS or Unix'
			GOTO, HANDLE_ERROR
			END
		ENDCASE
		SPAWN, COPY + ' ' + FILE0 + '.dbf ' + FILE + '.dbf'
		SPAWN, COPY + ' ' + FILE0 + '.dbx ' + FILE + '.dbx'
		SPAWN, COPY + ' ' + FILE0 + '.dbh ' + FILE + '.dbh'
;
;  Delete the entries for that year in the current database.
;
	    	DBDELETE, ENTRIES
		DBCLOSE
		DBCOMPRESS, FILE0
;
;  Open the new database, and delete all entries but the ones in that year.
;
	    	DBOPEN, FILE, 1
		ENTRIES = WHERE(TEMP.YEAR NE TYEAR, COUNT) + 1L
		IF COUNT GT 0 THEN BEGIN
		    DBDELETE, ENTRIES
		    DBCLOSE
		    DBCOMPRESS, FILE
		ENDIF
		CD, CURRENT
	    ENDFOR
	ENDIF
;
;  Signal success.
;
	RESULT = 1
	GOTO, FINISH
;
;  Error handling point.
;
HANDLE_ERROR:
	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = 'PRG_DETAIL: ' + MESSAGE $
		ELSE MESSAGE, MESSAGE, /CONTINUE
;
;  Close the database, and return.
;
FINISH:
	DBCLOSE
;
	RETURN, RESULT
	END