							20 June 1997
To the CAMMICE Team:

	This is revision 4.0 of the software to access the CAMMICE Level
Zero Data Files. Many of the problems with the previous version have been
fixed.  The speed of the routines has been approximately doubled and a
routine to obtain pitch angles of the MICS sectored rate scaler data has
been added. 

**************************************************************************
There are some changes in the calling routines for the MICS data.
These changes are listed in the file CHANGES.LIS. The calling programs
must be modified to use these new routines. 
**************************************************************************

A file called COMP_LZ.PRO is included to compile all modules. A second
procedure called SET_PATHS.PRO sets up some VMS-style paths to various
files that are needed by the program.  In particular it provides a path to
the housekeeping calibration files mhk_cals.dat and hhk_cals.dat.  The
other two strings are not used by the LZ code but they could be used by the
main program.   You should modify SET_PATHS.PRO to conform with your own
operating system. The paths should be formatted such that they can be added
to a file name to produce the required string for the openr procedure. 

As before, you will find following some brief instructions on how to run
the code to extract MICS data.  I have added a similar section on the HIT
data.  The modules TEST_MICS.PRO and TEST_HIT.PRO run all the routines and
print out the dimensions of the arrays. 

For the inevitable questions and comments please send me mail at
jim_roeder@qmail2.aero.org or call at (310)336-7081. 

Good Luck 
Jim Roeder, Aerospace

;------------------------------------------------------------------------------
To Read CAMMICE data from the LZ file:

1.	Open the input LZ file using opn_LZ in module RD_CAMLZ.PRO

	opn_LZ, filename, err 	; Filename must include the complete path
				; and extension.

	If no error was encountered then err will be a null string. Other
	wise it will return a explanation of the error

2.	Set the data interval by specifying either the min and max record to
	process or the min and max Universal Time to process using routines
	in file INTERVAL.PRO

	set_records, [min_record, max_record]	; First record in file is 1

	or

	set_times, [min_time, max_time]		; Times are in UT seconds
						; from start of day

;------------------------------------------------------------------------------

Now pick which type of data that you would like to extract.  There are separate
routines for each type.  For example MICS Direct Events, MICS Rates scalers,
etc.


3.	Extract MICS direct event data from file using routine get_mde from
	file GET_MICS.PRO 

	get_mde, times, eng, tof, esa, m, moq, err

	Returns six data arrays and error string.  If err is null string then
	data is good.  All arrays singly dimensioned 250 * number of records.
	Cross mode data have been combined with the normal mode data . If
	normal mode then cross mode data are filled with flags. 

	times	Universal times of points in msec
	eng	Energy in channels, 0-1023
	tof	Time-of-flight in channels, 0-1023
	esa	Electrostatic analyzer step, 0-31
	m	Mass group, 0-15, cross mode data only, filled with 255
		otherwise
	moq	Mass-per-charge group, 0-31, cross mode data only
	

4.	To read MICS Sectored Rate Scalers set the channel numbers desired
	using set_mrates in file MICS_CHA.PRO 	to input an index into the
	possible channels.  Values of 0-8 correspond 	to scalers MR0-8, and
	values of 9 and 10 correspond to DCR and FSR. The indices need
	not be in order. 
	
	set_mrates, [2, 9, 10]	; For example this selects, MR2, DCR, and FSR


	Extract MICS Sectored Rate Scalers data from file using routine
	get_msrates from file GET_MICS.PRO 

	get_msrates, times, delta, sectors, esa, chans, cnts, err

	Returns five data arrays and error string.  If err is null string then
	data is good.  All arrays except cnts singly dimensioned 
	(50*number of records)

	times	Universal times of points in long msec, bad = -1L
	delta	Accumulation times for each sector in msec
	sectors	Sector numbers, 0-31, bad = 255
	esa	Electrostatic analyzer step, 0-31, 255 for bad data
	chans	Channel numbers selected dim(nchannels)
	cnts	Compressed counts, dimensioned (nchannels, 50*nrecords)
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

5.	To read MICS Sectored Rate Scalers and compute the pitch angles 
	set the channel numbers desired using set_mrates in file MICS_CHA.PRO
 	to input an index into the possible channels.  Values of 0-8 
	correspond to scalers MR0-8, and values of 9 and 10 correspond to 
	DCR and FSR. The indices need not be in order. 
	
	set_mrates, [2, 9, 10]	; For example this selects, MR2, DCR, and FSR


	Extract MICS Sectored Rate Scalers data from file using routine
	get_msrts from file GET_MICS.PRO.

	The variable pa_mode must be input.  A zero value causes pitch 
	angles to be computed with a range of 0-180 degrees.  This is the 
	normal, standard  pitch angle.

	A non-zero value causes pitch angles to be computed with an output 
	range of 0-360 degrees.  Counts with pitch angles of 0-180 have 
	velocity vectors in the hemisphere which contains the sun position 
	vector.  Counts with pitch angles in the range 180-360 have 
	vectors that lie in the hemisphere which contains the anti-sun
	direction.

	Note that the 0-360 degree pitch angle calculation may return 
	spurious results for cases in which the magnetic field projection 
	in the spin plane is close to either the sun-aligned or 
	anti-sun-aligned directions.
	
	get_msrts, pa_mode, times, delta, sectors, esa, chans, cnts, pang, err

	Returns seven data arrays and error string.  If err is null string 
	then data is good.  All arrays except cnts singly dimensioned 
	(50*number of records)

	times	Universal times of points in long msec, bad = -1L
	delta	Accumulation times for each sector in msec
	sectors	Sector numbers, 0-31, bad = 255
	esa	Electrostatic analyzer step, 0-31, 255 for bad data
	chans	Channel numbers selected dim(nchannels)
	cnts	Compressed counts, dimensioned (nchannels, 50*nrecords)
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO
	pang	Pitch angles in degrees, either 0-180 or 0-360 depending on 
		pa_mode

6.	To read MICS Spin-Averaged Rate Scalers set the channel numbers desired
	using set_msrates in file MICS_CHA.PRO 	to input an index into the
	possible channels.  Note that this index is separate from the index
	mrates used for the sectored rate scalers.  Values of 0-15 correspond 
	to scalers MR Totals 0-15.  The indices need not be in order. 
	
	set_msrates, [2, 9]	; For example this selects, MR2, and MR9 Total


	Extract MICS Spin Averaged Rate Scalers data from file using routine
	get_mtotrts from file GET_MICS.PRO 

	get_mtotrts, times, esa, chans, cnts, err

	Returns three data arrays and error string.  If err is null string 
	then data is good.  All arrays except cnts singly dimensioned 
	(approximately 50/32*number of records)

	times	Universal times of points in msec
	esa	Electrostatic analyzer step, 0-31
	chans	Channel numbers selected dim(nchannels)
	cnts	Compressed counts, dimensioned (50/32*nrecords, nchannels)
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

6.	To read MICS Selected-Sector Single use the routine
	get_msing from file GET_MICS.PRO 

	get_msing, esa, timesa, sectora, cntsa, timesb, sectorb, cntsb, err

	Returns seven data arrays and error string.  If err is null string then
	data is good.  All arrays singly dimensioned except cntsa and cntsb 
	(approximately 50/32*number of records)

	esa	Electrostatic analyzer step, 0-31
	timesa	Universal times of points in msec of perpendicular sector
	sectora Sector number of perpendicular sector
	cntsa	Compressed counts for perpendicular sector, dimensioned 
		(approximately 50/32*nrecords, 4) with range of 0-255

	timesb	Universal times of points in msec of parallel sector
	sectorb Sector number of parallel sector
	cntsb	Compressed counts for parallel sector, dimensioned 
		may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

8.	To Read MICS Matrix Scalers extract data from file using routine
	get_mmatrx from file GET_MICS.PRO 

	get_mmatrx, times, cnts, odd, err

	Returns three data arrays and error string.  If err is null string then
	data is good.  

	times	Universal times of points in long msec, bad or missing = -1L
	cnts	Compressed counts, dimensioned (16, 32, nexp master frames)
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO
	odd	ESA flag, 0=first (even) half of analyzer pattern, 
		1=second (odd) half of analyzer pattern

9.	To Read MICS DPU status bits extract data from file using routine
	get_mdpustat from file GET_MICS.PRO 

	get_mdpustat, times, mdpustat, err

	Returns structure and error string.  If err is null string then
	data is good.  Structure contains all MDPU status telemetered 
	in TM words 12 and 15 

	times		Universal times of points in msec
	mdpustat	Structure details may be found in the MICS_STA.PRO
			module in the procedure def_mdpustat_strc, one full
			structure is returned for each S/C major frame.

10.	To Read MICS DPU analog housekeeping extract data from file using
	routine get_mdpuhk from file GET_MICS.PRO 

	get_mdpuhk, times, mdpuhk, err

	Returns two arrays and error string.  If err is null string then
	data is good.  Floating point array mdpuhk contains all MDPU 
	analog housekeeping status telemetered in TM word 12: MDPU HK A and B

	times	Universal times of points in msec
	mdpuhk	Array is floating point dimensioned 16 x nmajor frames
		All data is converted to physical units in the following 
		order:

		Spin Clock
		-6.8 V
		+6.8 V
		+28 V UNSW
		+28 V SW
		RAM Power
		HVPS
		VVPS
		BUPS Current mA
		DPU Temp
		Undef
		Undef
		Undef
		Undef
		Zero Monitor
		VCC + 5 V
		
11.	To Read MICS Sensor analog housekeeping extract data from file using
	routine get_micshk from file GET_MICS.PRO 

	get_micshk, times, micshk, err

	Returns two arrays and error string.  If err is null string then
	data is good.  Floating point array micshk contains all MICS sensor 
	analog housekeeping status telemetered in TM word 12: 
	Sensor Status H and L

	times	Universal times of points in msec
	micshk	All data is converted to physical units. Array is floating 
		point dimensioned 7 x nmajor frames in following order
		
		MICS Elect Temp
		BUPS Temp
		+5 V Mon
		+13 V Mon
		-5 V Mon
		-13 V Mon
		CHPS V Mon
			
12.	To Read MICS sensor status extract data from file using
	routine get_micsstat from file GET_MICS.PRO 

	get_micsstat, times, mstat, err

	Returns two arrays and error string.  If err is null string then
	data is good.  Long word array mstat contains all MICS sensor 
	status bits telemetered in TM word 12: Sensor Status H and L

	times	Universal times of points in msec
	mstat	Array is longword dimensioned nmajor frames 
		bits defined as follows:

		Bit #	Function
		0	Not used
		1	Proton ID, 0=On, 1=Off
		2	Energy Threshold, 0=High, 1=Low
		3	E Channel, 0=On, 1=Off
		4-7	TAC Slope, 12=180, 8=200, 9=220, 10=800, 11=500
		8-15	E Cal = ((raw+0.5)*5.88 keV
		16-19	CHPS Step, 0=Off, 1=90V, 2=1248V, 3=2310V
			4=2349V, 5=2389V, 6=2429V, 7=2469V, 8=2509V,
			9=2549V, 10=2588V, 11=2628V, 12=2668V, 13=2708V,
			14=2748V, 15=2788V
		20	T Cal, 0=Off, 1=On
		21	Stop, 0=Off, 1=On
		22-23	T Cal, 0=21.7ns, 1=62.2ns, 2=104.6ns, 3=139.4ns
		24-27	Ev Counter
		28	Trigger, 0=On, 1=Off
		29	Calibration, 0=Off, 1=On
		30-31	Trigger Mode, 0=E+T, 1=E*T, 2=E, 3=T

;------------------------------------------------------------------------------
Similar routines are available for the HIT data:

13.	Extract HIT direct event data from file using routine get_hde from
	file GET_HIT.PRO 

	get_hde, times, eng, deng, eprime, sample, m, err

	Returns six data arrays and error string.  If err is null string then
	data is good.  All arrays singly dimensioned 250 * number of records.
	Cross mode data have been combined with the normal mode data . If
	normal mode then cross mode data are filled with flags. 

	times	Universal times of points in msec
	eng	Energy in channels, 0-1023
	deng	Energy loss channel, 0-1023
	eprime	Energy primed
	sample	Time slice identifier
	m	Mass group, 0-15, cross mode data only, filled with 255
		otherwise
	
14.	To read HIT Sectored Rate Scalers set the channel numbers desired
	using set_hrates in file HIT_CHA.PRO to input an index into the
	possible channels.  Values of 0-11 correspond to scalers HR0-11, 
	and values of 12-17 correspond to HID0,2, 5-8.  The indices need
	not be in order. 
	
	set_hrates, [2, 9, 15]	; For example this selects, HR2, HR9, and 
				; HID6

	Extract HIT Sectored Rate Scalers data from file using routine
	get_msrates from file GET_HIT.PRO 

	get_hsrates, times, mf, sectors, chans, cnts, err

	Returns five data arrays and error string.  If err is null string then
	data is good.  All arrays except cnts singly dimensioned 
	(25*number of records)

	times	Universal times of points in long msec, bad = -1L
	mf	Minor frame numbers, 0-249
	sectors	Sector numbers, 0-31, bad = 255
	chans	Channel numbers selected dim(nchannels)
	cnts	Compressed counts, dimensioned (nchannels, 25*nrecords)
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

15.	To read HIT Spin-Averaged Rate Scalers set the channel numbers desired
	using set_msrates in file HIT_CHA.PRO 	to input an index into the
	possible channels.  Note that this index is separate from the index
	mrates used for the sectored rate scalers.  Values of 0-15 correspond 
	to scalers HR Totals 12-15, HID1, 2, 4, 9, 10, 12, and HS1-6.  The 
	indices need not be in order. 
	
	set_hsrates, [2, 9]	; For example this selects, HR2, and 
				; HID12 Total


	Extract HIT Spin Averaged Rate Scalers data from file using routine
	get_htotrts from file GET_HIT.PRO 

	get_htotrts, times, chans, cnts, err

	Returns three data arrays and error string.  If err is null string 
	then data is good.  All arrays except cnts singly dimensioned 
	(approximately 50/32*number of records)

	times	Universal times of points in msec
	chans	Channel numbers selected dim(nchannels)
	cnts	Compressed counts, dimensioned (50/32*nrecords, nchannels)
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

16.	To read HIT Selected-Sector Single use the routine
	get_hsing from file GET_HIT.PRO 

	get_hsing, timesa, sectora, cntsa, timesb, sectorb, cntsb, err

	Returns six data arrays and error string.  If err is null string then
	data is good.  All arrays singly dimensioned except cntsa and cntsb 
	(approximately 50/32*number of records)

	timesa	Universal times of points in msec of perpendicular sector
	sectora Sector number of perpendicular sector
	cntsa	Compressed counts for perpendicular sector, dimensioned 
		(4, approximately 50/32*nrecords) with range of 0-255

	timesb	Universal times of points in msec of parallel sector
	sectorb Sector number of parallel sector
	cntsb	Compressed counts for parallel sector, dimensioned 
		(4, approximately 50/32*nrecords) with range of 0-255
		may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

17.	To read HIT X Scaler data from file use routine get_hxrates 
	from file GET_HIT.PRO.

	Returns six data arrays and error string.  If err is null string then
	data is good.  All output arrays dimensioned ( 25*nrecords)

	get_hxrates, times, sectors, stype, snum, cnts, err

	times	Universal times of points in long msec, bad = -1L
	sectors	Sector numbers, 0-31, bad = 255
	stype	Scaler type, HR=0, HS=1, HID=2
	snum	Scaler number, HR=0-15, HS=0-7, HID=0-10, 12
	cnts	Compressed counts
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

18.	To read HIT Y Scaler data from file use routine get_hyrates 
	from file GET_HIT.PRO.

	Returns six data arrays and error string.  If err is null string then
	data is good.  All output arrays dimensioned ( 50*nrecords)

	get_hyrates, times, sectors, stype, snum, cnts, err

	times	Universal times of points in long msec, bad = -1L
	sectors	Sector numbers, 0-31, bad = 255
	stype	Scaler type, HR=0, HS=1, HID=2
	snum	Scaler number, HR=0-15, HS=0-7, HID=0-10, 12
	cnts	Compressed counts
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

19.	To Read HIT Matrix Scalers extract data from file using routine
	get_hmatrx from file GET_HIT.PRO 

	get_hmatrx, times, cnts, err

	Returns two data arrays and error string.  If err is null string then
	data is good.  Full set of data returned for each experiment 
	master frame read (approx nrec/11)

	times	Universal times of points in long msec, bad or missing = -1L
		dimensioned ( nrec / 11)
	cnts	Compressed counts, dimensioned (16, 32, nrec/11)
		0-255, may be decompressed using the routine decomprs_cnts 
		in module DECOMPRS.PRO

20.	To Read HIT DPU status bits extract data from file using routine
	get_hdpustat from file GET_HIT.PRO 

	get_hdpustat, times, hdpustat, err

	Returns structure and error string for each record.  If err is 
	null string then data is good.  Structure contains all HDPU
	status telemetered in TM words 11 and 15 

	times		Universal times of points in msec
	mdpustat	Structure details may be found in the HIT_STA.PRO
			module in the procedure def_hdpustat_strc

21.	To Read HIT DPU analog housekeeping extract data from file using
	routine get_hdpuhk from file GET_HIT.PRO 

	get_hdpuhk, times, hdpuhk, err

	Returns two arrays and error string.  If err is null string then
	data is good.  Floating point array hdpuhk contains all HDPU 
	analog housekeeping status telemetered in TM word 11: MDPU HK A and B

	times	Universal times of points in msec
	hdpuhk	Array is floating point dimensioned 16 x nmajor frames
		All data is converted to physical units in the following 
		order:

		Spin Clock
		-6.0 V
		+6.0 V
		-15 V UNSW
		+15 V SW
		RAM Power
		Det Bias
		HIT Sensor Temp
		HIT Electronics Temp
		DPU Temp
		Undef
		Undef
		Undef
		Undef
		Zero Monitor
		VCC + 5 V
		
;------------------------------------------------------------------------------

22.      When finished processing close the input LZ file using cls_LZ
        in module RD_CAMLZ.PRO

        cls_LZ          ; No arguments
;------------------------------------------------------------------------------
