----------- DD SYSTEM PROGRAM MANUAL ---------------------
LEVEL 2
V.2.4
A. Fedorov
Last updating: May 11, 2002
GENERAL NOTES
First of all look at Brief Instruments Description
to understand some hardware properties.
Using CALL_EXTERNAL function
Interface of IDL to DD data base is realised by CALL_EXTERNAL function.
The standard way to use this function is:
A = CALL_EXTERNAL(DDLIB+'Name_of_libfile.so', $
'Name_Of_function', $
Argument_list)
Here:
- DDLIB - string containing the path to Library files. To get this
path use the command:
DDLIB = getenv('DDLIB')
- 'Name_of_libfile.so', 'Name_Of_function',Argument_list are arguments
which should be exactly, as described below in particular interfaces
description. The Argument_list always contains the ID of
Virtual Instrument, start time of requested data and data time interval.
Open and Close the Virtual Instrument DataBase
Each open virtual instrument is referred by unique ID, the LONG non-negative
value. Each interface call contains ID in arguments. If the Virtual
Instrument is not open yet, you should set ID = -1 and then call the
interface function. The DataBase will be open automatically.
The function returns to you non-negative ID or negative error identifier.
So, check returned ID to be sure the Virtual Instrument exists, open
and you sent valid time. In one
session you can open any number of Virtual Instruments simultaneously.
Use different variables to keep IDs of different open simultaneously
Virtual Instrument (like open file discriptors).
Before finishing the program you should close ALL open Virtual Instruments.
To do that you have to call:
error = call_external(DDLIB+'DD_idl.so','CloseID',ID)
Time Manipulation
DD system uses time in two formats:
- The string format: "YYYYDDDHHMMSSMLS". See "User manual" for complete
description. Mostly important is to remember that DDD means Day Of Year - 1,
e.i. the Janiary 1st equel to zero.
- The double format: DOUBLE value means seconds from 00:00 of
January 1st., 1970.
The most of Virtual Instruments calls return the Time in second format. The
conversion can be made by two calls:
- Double to String:
TimeString = call_external('DD_idl.so','GetTime',TimeDouble, /S_VALUE)
- String to Double:
TimeDouble = call_external('DD_idl.so','GetDTime',TimeString, /D_VALUE)
INTERFACES DESCRIPTION
INTERBALL-TAIL ATTITUDES
To get instant attitudes of the INTERBALL-Tail S/C call:
Ret=call_external(DDLIB+'libIDLAT.so',$
'getframe',$
Size,$
Time,$
Attid,$
flag)
Here:
- Size - number or requested points to obtain attitudes. Size
should be LONG type of variable.
- Time - array of DOUBLES with dimension Size containing
requested times. The double time format is described above.
- Attid is float array (9,Size). The first dimension (9) is
the GSE coordinates of spacesraft axis: XSCx, XSCy, XSCz,
YSCx, YSCy, YSCz, ZSCx, ZXSCy, ZSCz.
- Flag integer array of Size indicating validity of the data.
1 - data valid, 0 - attitudes unavalable for the requested time.
To see an example press:
CORALL INTERFACE
CORALL Raw Spectra
To obtain CORALL raw spectra use IDL call:
RetSize=call_external(DDLIB+'idl_corall.so',$
'GetCORALLSpectra',$
ID, $
Spectra,$
Time,$
Size,$
Mode,$
STime,$
TInt)
Here:
- - ID - LONG identifier of virtual instrument. Use LONG(-1) if instrument
is not open yet;
- - Spectra - array of spectra 32 X 5 X SIZE of INT;
- - Time - time of start of each spectra. This is an array dimension SIZE of DOUBLE;
- - Size - LONG size of allocated arrays;
- - Mode - array dimension SIZE of INT;
- - StartTime - string of Start Time in DD format
- - TimeInterval - string of Time interval in DD format
Function returns actual size of obtained data. If the real size of requested data
is greater than SIZE value, the trailer of the data is omited.
To get an example click:
CORALL constant instrument information
Each S/C spin CORALL reads <32 energy step> X <32 azimuth sectorsp> X
<5 polar channels> data values. According the mode of data compressin (0 - 8)
several nearest azimuthal sectors and energy steps can be combined before
data transmittion to telemetry. To get information about data compression degree
and about energy levels call:
ERROR = call_external(DDLIB+'idl_corall.so','GetCORALLInform',$
ID, $
Energy, $
TimeShift, $
AzimuthNumber, $
EnergiesNumber )
Here:
- ID - LONG value. The identifier virtual the instrument.
Use -1 to open DataBase
- Energy - array ESteps X Modes of DOUBLE. Array of Energy values for
each step for each mode.
- TimeShift - Array of ESteps X Modes of DOUBLE. Array contains the
time interval between start of spectrum accumulation and time of
specific energy measurement.
- AzimuthNumber - Array Modes size of INT. The number of azimuthal
sectors per spin depending on Mode.
- EnergiesNumber - Array Modes size of INT.The number of Energy
Steps depending on Mode.
Function returns negative value in case of error. To see an example
press:
CORALL Decoded and Calibrated Spectra
To obtain CORALL decoded to original and calibrated spectra use IDL call:
RetSize=call_external('../idl_corall.so',$
'GetCORALLSPC',$
ID, $
Spectra,$
Azim,$
Time,$
OneSectorT,$
EffFlag,$
Size,$
STime,$
TInt)
Here:
- - ID - LONG identifier of virtual instrument. Use LONG(-1) if the instrument
is not open yet;
- - Spectra - Calibrated spectra. Array 32 X 5 X Size of FLOAT;
- - Azim - Azimuthal sector number. Array dimension Size of LONG;
- - Time - time of start of each spectra. This is an array dimension SIZE of DOUBLE;
- - OneSectorT - one azimuthal sector duration. DOUBLE value in seconds;
- - EffFlag - LONG value to control data processing: 0 - raw decompressed data,
1 - processing with relative geometrical factor of channels,
2 - adding MCP deadtime processing;
- - Size - LONG size of allocated arrays;
- - Mode - array dimension SIZE of INT;
- - STime - string of Start Time in DD format
- - TInt - string of Time interval in DD format
All data are decompressed, that is equivalit to mode "0".
Function returns actual size of obtained data. If the real size of requested data
is greater than SIZE value, the trailer of the data is omited.
To get an example click:
ELECTRON INTERFACE
ELECTRON Spectra
To get ELECTRON spectra use IDL call :
RetSize=call_external(DDLIB+'getelec.so','get_elecsp',$
ID, $
Time,$
StartTime,$
TimeInterval,$
Mode,$
Spectra,$
SIZE)
Here:
- - ID - identifier of particular database. Use -1 to open DataBase
- - Spectra - array of spectra 8 X 32 X SIZE of INT
- - Time - array of DOUBLE with SIZE dimension
- - Size - INT value af allocated size for returned data
- - Mode - array of INT SIZE dimension.
- - StartTime - string of Start Time in DD format
- - TimeInterval - string of Time interval in DD format
Function returns actual size of received data. To get an example
press:
ELECTRON instrument information
The ELECTRON instrument has a maximum 32 energy steps and 12 modes.
All constants are arrays with size 12 at least in last dimension.
To get ELECTRON instrument constants you can use interface call:
err = call_external(DDLIB+'getelec.so','GetInfo', $
ID, $
Energies, $
EBounds, $
DeltaT, $
AccumTime)
Here:
- ID - LONG value. The identifier of particular database.
Use -1 to open DataBase
- Energies - array 32 X 12 of DOUBLE. Array of Energy values for
each step for each mode in eV.
- EBOunds - Array of size = 12 of DOUBLE. Array contains
the boundaries of energy steps. It used for graphycal purposes only.
- DeltaTr - Array of size = 12 of DOUBLE. The spectra time
resolution depending on Mode. This value used for graphycal purposes only.
- AccumTime - Array of size = 12 of DOUBLE. The accumulation time
for one enegry step depending on Mode in seconds.
Function returns negative value in case of error. To see an example
press:
MAGNETOMETERS INTERFACE
High Resolution Magnetic Field
To see an example press:
Tzyganenko-96 INTERFACE
To see an example press: