FUNCTION READ_RASTER, TEL_MODE, UNIT, PACKET, RASTER, DATAWIN
;+
; Project     : SOHO - CDS
;
; Name        : READ_RASTER()
;
; Purpose     : Reads a complete NIS or GIS raster.
;
; Explanation : This procedure keeps reading and processing CDS science
;		telemetry packets until it encounters one that belongs to
;		a different raster.
;
; Use         : Result = READ_RASTER( TEL_MODE, UNIT, PACKET, RASTER, DATAWIN)
;
; Inputs      : TEL_MODE = Input mode, as used by READ_PACKET.
;		UNIT	 = Unit number input was opened with.
;		PACKET	 = Current telemetry packet.
;
; Opt. Inputs : None.
;
; Outputs     : PACKET	 = The last packet read in by this routine is returned
;			   in this parameter.  This is the next science packet
;			   after the end of the current raster.
;		RASTER	 = Structure variable from FORM_RASTER, containing all
;			   the metadata extracted from the science telemetry
;			   stream pertaining to the raster.
;		DATAWIN	 = Array from FORM_RASTER, containing all the data
;			   windows.
;
;		The result of the function is either true (1) if successful, or
;		false (0) if unsuccessful.
;
; Opt. Outputs: None.
;
; Keywords    : None.
;
; Calls       : CDS_MESSAGE, FIND_RASTER, FORM_RASTER, GET_SCI_PKT,
;		READ_EXPOSURE, ENGB_STORE, ENGB_EXPOSURE
;
; Common      : None.
;
; Restrictions: None.
;
; Side effects: If an error is discovered in parsing the raster header, then an
;		error message is written to the telemetry log, and the error is
;		brought to the attention of the CDS operator.
;
; Category    : Data Handling, Telemetry.
;
; Prev. Hist. : Although there is a previous routine with the same name, this
;		routine represents a complete rewrite.
;
; Written     : William Thompson, GSFC, 16 April 1993.
;
; Modified    : Version 1, William Thompson, GSFC, 16 April 1993.
;		Version 2, William Thompson, GSFC, 16 November 1993.
;			Split off DATAWIN from RASTER structure.
;		Version 3, William Thompson, GSFC, 13 June 1994.
;			Split RASTERLENGTH into NUMMIRRORPOS and NUMSLITPOS.
;		Version 4, William Thompson, GSFC, 31 August 1994
;			Modified to call CDS_MESSAGE to display current study
;			and raster counters.
;		Version 5, William Thompson, GSFC, 25 August 1995
;			Added calls to ENGB_STORE and ENGB_EXPOSURE
;		Version 6, William Thompson, GSFC, 1 November 1995
;			Enhanced message produced
;		Version 7, William Thompson, GSFC, 26 December 1995
;			Added warning for reset study counter.
;		Version 8, William Thompson, GSFC, 12 September 1996
;			Treat STUDYCOUNTER as an unsigned integer.
;
; Version     : Version 8, 12 September 1996
;-
;
	ON_ERROR, 2
;
;  Check the number of parameters.
;
	IF N_PARAMS() NE 5 THEN MESSAGE,	$
		'Syntax:  Result = READ_RASTER( TEL_MODE, UNIT, PACKET, ' + $
		'RASTER, DATAWIN )'
;
;  Find the next raster header packet in the telemetry stream.
;
FIND_NEXT_RASTER:
	IF NOT FIND_RASTER(TEL_MODE, UNIT, PACKET) THEN RETURN, 0
	CDS_MESSAGE,'Read raster header for Study: ' +			$
		TRIM(UNSIGN(PACKET.PKT.SCI.STUDYCOUNTER)) + ', Raster: ' + $
		TRIM(PACKET.PKT.SCI.RASTERCOUNTER), /CONTINUE, /ADD_TIME
	IF UNSIGN(PACKET.PKT.SCI.STUDYCOUNTER) LE 1 THEN CDS_MESSAGE,	$
		'Warning: Study counter may have been reset',		$
		/CONTINUE, /ATTENTION
;
;  Form the raster structure based on the information in the raster header
;  packet.  If an error occurs, then print the error message, skip to the next
;  packet and try again.
;
	IF NOT FORM_RASTER(PACKET, RASTER, DATAWIN, MSG) THEN BEGIN
		CDS_MESSAGE, MSG, /CONTINUE, /ATTENTION
		IF NOT GET_SCI_PKT(TEL_MODE,UNIT,PACKET,/NEXT) THEN RETURN,0
		GOTO, FIND_NEXT_RASTER
	ENDIF
;
;  For the GIS detector, initialize the information concerning Engineering B
;  packets.
;
	IF RASTER.INSTRUMENT EQ 'GIS' THEN BEGIN
		ENGB_STORE, /RESET
		ENGB_EXPOSURE, RASTER, /RESET
	ENDIF
;
;  Skip to the next science packet, but don't take any action if none are
;  found.
;
	TEST = GET_SCI_PKT(TEL_MODE,UNIT,PACKET,/NEXT)
;
;  Read in the exposures one by one.  For the GIS detector, save the
;  Engineering B information about this exposure for future use.
;
	N_EXPOSURES = (RASTER.HEADER.SCI.NUMMIRRORPOS > 1) *	$
		(RASTER.HEADER.SCI.NUMSLITPOS > 1)
	FOR EXPOSURE = 0, N_EXPOSURES-1 DO BEGIN
		READ_EXPOSURE,TEL_MODE,UNIT,EXPOSURE,PACKET,RASTER,DATAWIN
		IF RASTER.INSTRUMENT EQ 'GIS' THEN	$
			ENGB_EXPOSURE, RASTER, EXPOSURE
	ENDFOR
;
;  Return successful conclusion.
;
	RETURN, 1
	END