IDL user manual
===============
:toc:

== Open/close a CEF file

=== cef_read (<filename>) -> integer

Reads a CEF file, loads all data and metadata in memory.

Returns the number of records in the file

.Example
------------------------------------------------------------------------------
IDL> n = CEF_READ("C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef")
% Loaded DLM: CEF.
1 : CEF.Open_CEF_file              :
C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef
1 : CEF.Read_CEF_header            : 2167422 records found in 3.48 seconds
1 : CEF.Read_CEF_header            : 11 values per record
1 : CEF.Display_variables          : 7 variables + 0 constants
1 : CEF.Read_CEF_file              : 2167422 records physically read in 2.74
seconds
1 : CEF.Read_CEF_file              : STATUS = 0 : OK : Terminaison correcte
------------------------------------------------------------------------------

=== cef_close

Will release all memory used to handle the file and its data


=== cef_verbosity, <level>

will change the verbosity level of the CEFLIB, which can be usefull to debug
problems while reading CEF files

Defaut <level> is 1, and can be increased up to 5

== Global metadata

=== cef_metanames () -> array of stings

Returns the list of metadata sections

------------------------------------------------------------
IDL> print, CEF_METANAMES()
MISSION MISSION_TIME_SPAN MISSION_AGENCY MISSION_DESCRIPTION
 MISSION_KEY_PERSONNEL MISSION_REFERENCES MISSION_REGION MISSION_CAVEATS
 OBSERVATORY OBSERVATORY_CAVEATS OBSERVATORY_DESCRIPTION OBSERVATORY_TIME_SPAN
 OBSERVATORY_REGION EXPERIMENT EXPERIMENT_DESCRIPTION INVESTIGATOR_COORDINATES
 EXPERIMENT_REFERENCES EXPERIMENT_KEY_PERSONNEL EXPERIMENT_CAVEATS
 INSTRUMENT_NAME INSTRUMENT_DESCRIPTION INSTRUMENT_TYPE MEASUREMENT_TYPE
 INSTRUMENT_CAVEATS DATASET_ID DATA_TYPE DATASET_TITLE DATASET_DESCRIPTION
 CONTACT_COORDINATES TIME_RESOLUTION MIN_TIME_RESOLUTION MAX_TIME_RESOLUTION
 PROCESSING_LEVEL ACKNOWLEDGEMENT DATASET_CAVEATS LOGICAL_FILE_ID
 VERSION_NUMBER DATASET_VERSION FILE_CAVEATS FILE_TYPE METADATA_TYPE
 METADATA_VERSION FILE_TIME_SPAN GENERATION_DATE
------------------------------------------------------------

=== cef_meta (<section>) -> array of strings

Returns the list of string entries for this metadata section

------------------------------------------------------------
IDL> print, CEF_META("DATASET_DESCRIPTION")
This dataset contains full resolution measurements of the magnetic field
vector from the FGM experiment on the Cluster C1 spacecraft
------------------------------------------------------------

=== cef_gattributes () -> array of strings

Returns the list of global attributes names

------------------------------------------------------------
IDL> print, CEF_GATTRIBUTES()
FILE_NAME FILE_FORMAT_VERSION END_OF_RECORD_MARKER DATA_UNTIL
------------------------------------------------------------

=== cef_gattr (<attribute>) -> string or  array of strings

Returns value of a global attribute:

- result should be a string if the attribute has an unique value
- or a list of strings for multi-valued attributes

------------------------------------------------------------
IDL> print, CEF_GATTR("FILE_NAME")
C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef
------------------------------------------------------------

== CEF variables

=== cef_varnames () -> array

Return the list of CEF variables found in the file

------------------------------------------------------------
IDL> print, CEF_VARNAMES()
time_tags half_interval B_vec_xyz_gse B_mag sc_pos_xyz_gse range tm
------------------------------------------------------------

=== cef_var (<var-name>) -> IDL array

Creates an IDL variable, with the content of a given CEF-variable.

It should be an array of 1 to 6 dimensions of string, integer, float, 
depending on type of the CEF variable.

.Exemple
----
filename = "C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef"

n = CEF_READ (filename)
t = CEF_VAR ("time_tags")
b = CEF_VAR ("b_vec_xyz_gse")
----

=== cef_vattributes (<cef-varname>) -> array of strings

Returns the list of attributes names for a given variable

------------------------------------------------------------
IDL> print, CEF_VATTRIBUTES("B_vec_xyz_gse")
PARAMETER_TYPE ENTITY PROPERTY FLUCTUATIONS CATDESC UNITS SI_CONVERSION
 TENSOR_ORDER COORDINATE_SYSTEM REPRESENTATION_1 SIZES VALUE_TYPE
 SIGNIFICANT_DIGITS FILLVAL QUALITY FIELDNAM LABLAXIS DEPEND_0 LABEL_1
------------------------------------------------------------

=== cef_vattr (<cef-varname>, <attribute>) -> string ot array of strings

Returns attribute value for a given CEF variable attribute:

- result should be a string if the attribute has an unique value
- or a list of strings for multi-valued attributes

------------------------------------------------------------
IDL> print, CEF_VATTR("B_vec_xyz_gse", "SI_CONVERSION")
1.0E-9>T
------------------------------------------------------------

=== cef_depends (<cef-varname>) -> array of strings

Returns a list of DEPEND_i variables names for a given CEF variable

The first one corresponds to the DEPEND_0, then DEPEND_1, DEPEND_2, ...

Values can be empty strings if DEPEND_i attribute is not set. 

------------------------------------------------------------
IDL> print, CEF_DEPENDS("B_vec_xyz_gse")    
time_tags
------------------------------------------------------------

== Time-tags functions

=== milli_to_julian (<time-tag-variable>) -> array of double

CEFLIB time-tags are coded internally in milli-seconds from 1958

This function converts these time-tags into corresponding Julian days

Input can be a scalar or an array, of ISO_TIME or ISO_TIME_RANGE data

=== milli_to_epoch (<time-tag-variable>) -> array of double

CEFLIB time-tags are coded internally in milli-seconds from 1958

This function converts these time-tags into corresponding CEF Epoch time

Input can be a scalar or an array, of ISO_TIME or ISO_TIME_RANGE data

=== milli_to_isotime (<time-tag-variable>,<number-of-digits>) -> array of strings

This function will convert internal time-tags in ISOTIME strings.

The first argument could be an ISO_TIME or ISO_TIME_RANGE CEF variable

The second arguments give the number of digits expected for fractional seconds:
(0: seconds, 3: milli-seconds, 6: micro-seconds)

.Exemple
How to open a CEF file and print time-tags with micro-seconds resolution :

	nrec = CEF_READ ("some-cef-file.cef")
	print, MILLI_TO_ISOTIME (CEF_VAR ("time_tags"), 6)

== Examples of use

------------------------------------------------------------------------------------
PRO fgm

	filename = "C1_CP_FGM_FULL__20050101_000000_20050102_000000_V070906.cef"

	n = CEF_READ (filename)
	t = CEF_VAR ("time_tags")
	b = CEF_VAR ("b_vec_xyz_gse")

	tt = MILLI_TO_JULIAN (t)

	bx = b [0,*]
	by = b [1,*]
	bz = b [2,*]

	temp = LABEL_DATE (date_format = "%H:%I")

	PLOT,  tt, bx, COLOR = 'ff0000'x, $
			TITLE = "FGM DATA", $
			xtickformat = "LABEL_DATE", $
			BACKGROUND = 'ffffff'x
	OPLOT, tt, by, COLOR = '00ff00'x
	OPLOT, tt, bz, COLOR = '0000ff'x

END
------------------------------------------------------------------------------------