FUNCTION PRG_PLAN, ERRMSG=ERRMSG, YEAR=YEAR
;+
; Project     :	SOHO - CDS
;
; Name        :	PRG_PLAN()
;
; Purpose     :	Purges old and deleted SOHO science plan records
;
; Explanation :	This routine removes all entries from the SoHO/CDS 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_PLAN
;
; 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_PLAN( 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 database for update, and search for entries which are marked for
;  deletion.  If any are found, then delete them.
;
	DBOPEN, 'sci_plan', 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
	    CD, CURRENT=CURRENT
	    FILE = FIND_WITH_DEF('sci_plan.dbf', '$ZDBASE')
	    BREAK_FILE, FILE, DISK, DIR
	    CD, DISK+DIR
	    TEMP = ANYTIM2UTC(TRIM(YEAR) + '-1-1', /EXT)
	    TYEAR = TEMP.YEAR
	    FILE = 'sci_plan_' + 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, 'sci_plan', 1, /EXTERNAL
	    DBOPEN, 'sci_plan', 1
	    DBINDEX
;
;  Find all entries which begin in the target year.
;
	    DBEXT, -1, 'start_time', START_TIME
	    TEMP = TAI2UTC(START_TIME, /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 + ' sci_plan.dbf ' + FILE + '.dbf'
	    SPAWN, COPY + ' sci_plan.dbx ' + FILE + '.dbx'
	    SPAWN, COPY + ' sci_plan.dbh ' + FILE + '.dbh'
;
;  Delete the entries for that year in the current database.
;
	    DBDELETE, ENTRIES
	    DBCLOSE
	    DBCOMPRESS, 'sci_plan'
;
;  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
	ENDIF
;
;  Signal success.
;
	RESULT = 1
	GOTO, FINISH
;
;  Error handling point.
;
HANDLE_ERROR:
	IF N_ELEMENTS(CURRENT) EQ 1 THEN CD, CURRENT
	IF N_ELEMENTS(ERRMSG) NE 0 THEN ERRMSG = 'PRG_PLAN: ' + MESSAGE $
		ELSE MESSAGE, MESSAGE, /CONTINUE
;
;  Close the database, and return.
;
FINISH:
	DBCLOSE
;
	RETURN, RESULT
	END