;PROGRAM: STEREO_MAG_TO_ASCII, FILENAME, MAGDATA=MAGDATA, NOASCIIDUMP=NOASCIIDUMP,ASCII_FILENAME=ASCII_FILENAME
;
;INPUT:
;   FILENAME (REQUIRED): The file name (including path) of a STEREO/MAG CDF file.
;
;KEYWORDS (all optional):
;   MAGDATA: The name of a variable into which to output the STEREO/MAG into IDL. The variable will
;      be a structure with this form: {Epoch: DOUBLE[NUMRECS], BFIELD: FLOAT[4, NUMRECS]} where
;      NUMRECS is the number of data points (records) in the MAG CDF file. The Epoch element contains
;      the times of the records in the CDF_EPOCH format. Use IDL's CDF_EPOCH routine to convert this
;      into a more usable time format if desired. The 4 elements of the BFIELD element are the
;      three element vector (Bx,By,Bz) or (Br,Bn,Bt) of the magnetic field in nT. The fourth field
;      is the total magnetic field magnitude also in nT.
;   NOASCIIDUMP: If set, this routine will not produce an ascii file.
;   ASCII_FILENAME: If set, this must be a string giving the full path and file name for the output
;      ascii data. If not set, the default output ascii file name will be FILENAME+'.txt'.
;   
;PURPOSE:
;This procedure reads the contents of STEREO/MAG CDF file ouputs it to an ascii file and/or
;into an IDL structure. The default behavior with no keywords set is to read the MAG CDF
;file indicated by the FILENAME input and will output the data contents of the file into
;an ascii file with a file name of FILENAME+'.txt' (the output file name can be overriden with the
;ASCII_FILENAME keyword).
;
;The columns of the output ascii file are:
;Year   Month   Day   Hour   Minute   Second   Millisecond   Bx   By   Bz   Btotal
;
;NOTE:
;This routine is deliberately simple. At this time, no metadata is output into the ascii file.
;
;
function read_STEREO_MAG, filename

mycdfid = cdf_open(filename)

if not keyword_set(mycdfid) then begin
   print, 'Cannot find file ',filename
   return, 0
endif

cdf_control, mycdfid, get_var_info=epoch_info, variable='Epoch'
numrecs = epoch_info.maxrec

cdf_varget, mycdfid, 'Epoch', myepoch, rec_count=numrecs
cdf_varget, mycdfid, 'BFIELD', mybfield, rec_count=numrecs

cdf_close, mycdfid

return, {Epoch: reform(myepoch), BField: mybfield}
end


pro STEREO_MAG_to_ascii, filename, magdata = magdata, noasciidump = noasciidump, $
   ascii_filename = ascii_filename

magdata = read_STEREO_MAG(filename)

if not keyword_set(magdata) then return

if keyword_set(noasciidump) then return

if not keyword_set(ascii_filename) then ascii_filename = filename + '.txt'

openw, asciilun, ascii_filename, /get_lun

format = '( 7I5, 4F)'
for i = 0l, n_elements(magdata.Epoch)-1 do begin
   CDF_EPOCH, magdata.Epoch[i], Year , Month, Day, Hour, Minute, Second, Milli, /breakdown_epoch
   printf, asciilun, Year, Month, Day, Hour, Minute, Second, Milli, magdata.Bfield[*,i], format=format
endfor

close, asciilun

return
end