;+
; NAME:
;	vu_getdata
; PURPOSE:
;	Provides a standardized way of reading in tomography files
; CATEGORY:
;	Tomography I/O
; CALLING SEQUENCE:
	FUNCTION vu_getdata, hdr, ff, ut0=ut0, ihdr=ihdr, count=count, fresh=fresh, $
		last_hdr=last_hdr, silent=silent, _extra=_extra,						$
		bfield=bfield, bcount=bcount, bhdr=bhdr, bff=bff
; INPUTS:
;	hdr				array; type: header structure
;	ff				array; data arrays associated with 'hdr' array
;						If not specified, then data will be read using
;						href=vu_select= or href=vu_read=.
; OPTIONAL INPUT PARAMETERS:
;	/fresh			if set, input variables hdr and ff are destroyed, triggering
;					selection of new data files.
;
;	ihdr = ihdr		scalar; type: integer
;						Identifies 'principal header'; the only effect of this
;						keyword is, that if ut0 is NOT set then the return value
;						of ut is hdr[ihdr].time ihdr takes precedence over ut0
;
;	ut0 = ut0		scalar; type: float; default: none
;					array[1]; type: time structure
;						Carrington variable or time structure.
;						Alternative way of selecting the 'principal header' if
;						keyword ihdr is NOT set: ihdr is set to the index
;						of the header with time closest to ut0
;
;	For additional keywords see href=vu_select= and href=vu_read=
; OUTPUTS:
;	Result			scalar; type: float
;					array[1]; type: time structure
;						'Principal time'.
;						Set to iput value of 'ut0' if specified, or else set
;						to the time of the 'principal header' hdr[ihdr].time
;
;	hdr				array; type: header structure
;	ff				array; data arrays associated with 'hdr' array
;						Data read by vu_select or vu_read
; OPTIONAL OUTPUT PARAMETERS:
;	count=count		scalar; type: integer
;						# headers and files read; 0 if something went wrong
;	ihdr=ihdr		scalar; type: integer
;						index of 'principal header'.
;						If specified as input value it is checked to stay
;						inside array limits. If no input 'ihdr' is specified
;						then the 'ihdr' value nearest to 'ut0' is selected.
; INCLUDE:
	@compile_opt.pro			; On error, return to caller
; CALLS:
;	InitVar, destroyvar, vu_select, vu_read, vu_get, Carrington, TimeGet
;	TimeUnit, IsType, TimeOp
; PROCEDURE:
;	ut can be a Carrington variable or a time structure. Use href=Carrington= to
;	settle on either one of these.
; MODIFICATION HISTORY:
;	APR-2001, Paul Hick (UCSD/CASS)
;	JUL-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Modified use of keyword ut0. ut0 now only sets the return
;		value of ihdr, not the return value ut anymore (used to be set to
;		hdr[ihdr].time if hdr referred to a time sequence.
;-

InitVar, silent  , 0

InitVar, fresh	 , /key
InitVar, last_hdr, /key

is_ut0 = IsType(ut0, /defined)
IF is_ut0 THEN ut0 = ut0[0]			; Safety belt, just in case ut0 is float array[1]

IF fresh OR NOT IsType(hdr, /structure) THEN destroyvar, hdr, ff

CASE 1 OF
IsType(hdr, /undefined)	: hdr = vu_select(/pick, /check, /read, ff=ff, count=count, silent=silent, _extra=_extra)
IsType(ff , /undefined)	: ff  = vu_read(hdr, count=count, silent=silent, _extra=_extra)
ELSE: count = n_elements(hdr)
ENDCASE

bcount = 0

CASE count OF
0   : BEGIN

	destroyvar, hdr, ff
	ut_out = !TheTime

END
ELSE: BEGIN

	IF is_ut0 AND IsType(ihdr, /undefined) THEN BEGIN
		time = vu_get(hdr,/uttime)
		tmp = min( abs(TimeOp(/subtract, vu_get(hdr,/uttime),Carrington(ut0,/get_time),TimeUnit(/day))), ihdr)
		IF count GT 1 THEN IF silent LE 1 THEN	$
			message, /info, '#'+strcompress(ihdr)+' at '+TimeGet(time[ihdr], /ymd)
	ENDIF

	InitVar, ihdr, last_hdr*(count-1)
	ihdr = (ihdr > 0) < (count-1)

	ut_out = vu_get(hdr[ihdr], /uttime)

	IF vu_get(hdr[0],/plasma) AND IsType(bfield, /defined) THEN BEGIN

		SetFileSpec, hdr.file
		fb = filepath(root=(GetFileSpec(upto='dir'))[0],bfield+strmid(GetFileSpec(from='name'),strlen(hdr[0].prefix)))

		CASE 1 OF
		IsType(bhdr, /undefined): bhdr = vu_select(fb, /check, /read, ff=bff, count=bcount, silent=silent, _extra=_extra)
		IsType(bff , /undefined): bff  = vu_read(bhdr, count=bcount, silent=silent, _extra=_extra)
		ELSE: bcount = n_elements(bhdr)
		ENDCASE
		
	ENDIF

END
ENDCASE

IF is_ut0 THEN ut_out = ut0

RETURN, ut_out  &  END