MidasWiki - User contributions [en]

Equipment Flags

2019-07-16T09:13:46Z

Gerritzen: /* EQ_PERIODIC */

{{Pagelinks}}

==== Links ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Equipment List Parameters]]
* [[Equipment List Parameters#Type|Equipment Type]]
</div>

'''<div id="Equipment Type"></div>'''
==Equipment Flags==
The following equipment flags (of the form EQ_xxx, defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h.html midas.h]) are supported in the Equipment [[Equipment List Parameters#Type|Type]] field in the EQUIPMENT structure of a frontend.
The selected flag determines the Equipment Type.

===EQ_PERIODIC ===
; Periodic Event [[#Equipment Flags|Equipment Type]]
: In this equipment Type, no hardware requirement is necessary to trigger the readout function. Instead, the [[Equipment List Parameters#Readout Routine|readout routine]] associated with this equipment is called periodically. The [[Equipment List Parameters#Period|Period]] field in the equipment declaration is used in this case to specify the time interval between calls to the readout function.

===EQ_POLLED===
;Polling Event [[#Equipment Flags|Equipment Type]]
: In this equipment Type, the name of the routine polling on a trigger source is "poll_event()". This routine must be provided in the [[Frontend user code]] by the user. As polling consists of checking a variable for a TRUE condition, if the loop count is infinite and the condition never becomes TRUE, the frontend would not be able to respond to any network commands. Therefore the loop count is determined when the frontend starts for the first time so that it returns after a given time-out if no event is available. This time-out is usually of the order of 500 milliseconds. The EQ_POLLED equipment type is mainly used for data acquisition based on a hardware condition becoming TRUE, at which time the [[Equipment List Parameters#Readout Routine|readout routine]] associated with the equipment is called. See [[Frontend user code#Function poll_event| example]].

===EQ_INTERRUPT===
; Interrupt Event [[#Equipment Flags|Equipment Type]]
: This flag is similar to the [[#EQ_POLLED|EQ_POLLED]] mode, except a hardware interrupt is used to trigger the event rather than a polling loop. Instead of passing a pointer to the polling routine, in EQ_INTERRUPT mode a pointer to the '''interrupt configuration routine''' is passed to the system. Midas requires complete configuration and control of the interrupt source. This is provided by the interrupt configuration routine (called [[Frontend user code#Function interrupt_configure|interrupt_configure()]]) that must be provided in the [[Frontend user code|Frontend code]] by the user. When a valid interrupt is received, the [[Frontend user code#Event Readout routine|readout routine]] associated with the equipment is called.

=== EQ_MULTITHREAD ===
;Multithread Event Readout [[#Equipment Flags|Equipment Type]]
:This flag implements the multi-threading capability within the frontend code. The polling is performed within a separate thread and uses the "Midas Ring Buffer Functions" (rb_xxx in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8c.html midas.c]) for inter-thread communication. EQ_MULTITHREAD is similar to [[#EQ_POLLED |EQ_POLLED]] mode, except for the polling function which in the case of EQ_MULTITHREAD resides in a separate thread. This new type has been added to take advantage of the multi-core processor to free up CPU for tasks other than polling.

=== EQ_SLOW===
; Slow Control Event [[#Equipment Flags|Equipment Type]]
: This flag declares the equipment as a Slow Control Equipment (see [[Slow Control System]]). This will enable the call to the '''idle''' function part of the class driver. This flag also causes event data to be sent automatically to the <span style="color: purple; font-style:italic;">/equipment/variables/</span> ODB subtree.

===EQ_MANUAL_TRIG===
; Manual triggered event [[#Equipment Flags|Equipment Type]]
: This flag enables the equipment to be [[Frontend user code#Manual Trigger|triggered]] by a remote procedure call (RPC). If EQ_MANUAL_TRIGGER is selected, the web interface will provide an extra button to trigger the equipment. The event may also be triggered by a client via RPC ([[Frontend user code#Manual Trigger|see example]]).

=== EQ_EB===

;Event Builder event [[#Equipment Flags|Equipment Type]]
: This flag identifies the equipment as a <b>fragment event</b> and should be ORed with [[#EQ_POLLED|EQ_POLLED]] in order to be identified by the [[Event Builder]].

=== EQ_FRAGMENTED===
; Fragmented Event [[#Equipment Flags|Equipment Type]]
: Flag enabled large events (beyond the Midas configuration limit) to be handled by the system ('''see WARNING below'''). This flag required that a valid ''max_event_size_frag'' variable was defined in the user [[Frontend Operation#Frontend|Frontend]] code. The ''max_event_size variable'' was used as fragment size in this case. This option was meant to be used in experiments where the event '''rate''' was not an issue but the '''size''' of the data needed to be extremely large.

<div style="background-color:mistyrose;">
:: '''WARNING'''
::* This flag is obsolescent (not maintained). It was added for small memory cpus (e.g VxWorks PPC) to send very large events (beyond the Midas configuration limit) back to the host computer.
::* With modern large-memory cpus (e.g. VMIC), '''instead of using this flag, the buffer sizes should be increased to accommodate a large event''' (see [[Event Buffer]]).
::* The fragmented event mechanism is '''not to be confused''' with "event fragments" used by the [[Event Builder]].
</div>

[[Category:Equipment]] [[Category:Event]] [[Category:Frontend]]

/Equipment ODB tree

2019-07-16T09:13:21Z

Gerritzen: /* Period */ Added note that units are milliseconds

{{Pagelinks}}

== Links ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Frontend user code]]
* [[Event Structure]]
* [[Equipment List Parameters]]
*
</div>

== Purpose ==
The ODB /Equipment tree contains user and system information related to a frontend.

== Creating the /Equipment tree ==
An empty /Equipment tree will be created by mlogger.

If an [[ Frontend Operation#Equipments and Events|Equipment]] is defined in [[Frontend user code]], the first time the frontend is run, if that equipment does not exist in the ODB, it
will be created (using db_create_record) in the ODB as a subtree under the /Equipment tree with the values supplied in the [[Frontend user code]].

== Example of /Equipment tree ==

The following is an example of the /Equipment tree from an experiment obtained with the [[odbedit|odbedit ls command]] listing all the defined equipments in the experiment :

[local:pol:S]Settings>ls /Equipment -l
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
POL_ACQ DIR
Scaler DIR
Trigger DIR
VME DIR
SisPulser DIR
INFO DIR
HISTO DIR

The following is a listing of one of the equipments in the /Equipment tree shown above :

[local:pol:S]Settings>ls /Equipment/info/ -lr
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
INFO DIR
Common DIR
Event ID WORD 1 2 9h 0 RWD 3
Trigger mask WORD 1 2 9h 0 RWD 8
Buffer STRING 1 32 9h 0 RWD SYSTEM
Type INT 1 4 9h 0 RWD 1
Source INT 1 4 9h 0 RWD 0
Format STRING 1 8 9h 0 RWD MIDAS
Enabled BOOL 1 4 9h 0 RWD y
Read on INT 1 4 9h 0 RWD 257
Period INT 1 4 9h 0 RWD 100
Event limit DOUBLE 1 8 9h 0 RWD 0
Num subevents DWORD 1 4 9h 0 RWD 0
Log history INT 1 4 2h 0 RWD 60
Frontend host STRING 1 32 9h 0 RWD lxpol.triumf.ca
Frontend name STRING 1 32 9h 0 RWD pol_fevme
Frontend file name STRING 1 256 9h 0 RWD pol_fevme.cxx
Status STRING 1 256 9h 0 RWD pol_fevme@lxpol.triumf.ca
Status color STRING 1 32 9h 0 RWD #00FF00
Hidden BOOL 1 4 9h 0 RWD n
<div id="Example Variables subtree"></div>
Variables DIR
DBUG FLOAT 9 4 2h 0 RWD
[0] 0
[1] 101
[2] 10201
[3] 10201
[4] 101
[5] 2
[6] 4
[7] 1
[8] 1

CYCL FLOAT 15 4 2h 0 RWD
[0] 1
[1] 9800
[2] 98
[3] 100
[4] 9
[5] 98
[6] 9800
[7] 9
[8] 9
[9] 8.9682
[10] 8.966
[11] 0.0504
[12] 0
[13] 8.7906
[14] 0
SUMS DOUBLE 4 8 2h 0 RWD
[0] 0
[1] 50002
[2] 0
[3] 0
<div id="Example Statistics subtree"></div>
Statistics DIR
Events sent DOUBLE 1 8 8h 0 RWD 176
Events per sec. DOUBLE 1 8 8h 0 RWD 0
kBytes per sec. DOUBLE 1 8 8h 0 RWD 0
<div id="Example Settings subtree"></div>
Settings DIR
Names DBUG STRING 12 32 9h 0 RWD
[0] Data still buffered
[1] Num SIS LNE events
[2] LNE count from SIS
[3] LNE preset value
[4] number of bins
[5] data bytes code
[6] num enabled channels
[7] discard first bin
[8] discard first cycle
[9] not used
[10] not used
[11] not used
Names CYCL STRING 15 32 9h 0 RWD
[0] Scan type code
[1] Number good cycles
[2] Number supercycles
[3] Cycle num within supercycle
[4] Sweep number
[5] Num cycles skipped
[6] Num cycles histogrammed
[7] DAC Increment number
[8] DAC Set Value (volts)
[9] DAC Readback (volts)
[10] ADC1 Average
[11] ADC2 Average
[12] ADC3 Average
[13] ADC4 Average
[14] spare

Names SUMS STRING 4 32 9h 0 RWD
[0] SC Sum ch17
[1] SC Sum ch18
[2] SC Sum ch19
[3] SC Sum ch20

== Keys in the <span style="color: purple;">''/Equipment''</span> ODB tree ==

=== <span style="color: purple;">''<equipment-name>''</span> subtree ===
This subtree in the [[#top|/Equipment ODB tree]] The [[#top|/Equipment ODB tree]]
will be named for an [[Frontend Operation#Equipments and Events|Equipment]] defined in the [[Frontend user code]]. No two subtrees in an experiment can have the same name. An <equipment-name> subtree will be present for every defined equipment in all the frontend(s) run on the experiment.

<div id="initial values"></div>
This subtree will be created (if it does not already exist) the first time the defining frontend is run, and the '''initial values''' set are defined in the [[Equipment List Parameters]] in the [[Frontend user code]] that defines this particular equipment.

'''Note:''' that if these parameters are later changed in the ODB, they will '''not''' be overwritten by the values in the frontend, if the frontend is restarted.

<br>
---------
<br>

==== <span style="color: purple;">''Common''</span> subtree ====
This subtree in an [[#<equipment-name> subtree|/Equipment/<equipment-name> subtree]] contains the parameters used by the system to process the [[Frontend Operation#Equipments and Events|Equipment]].

The initial values of the Common parameters are set when this tree is created (see [[#initial value|initial values]]).

<br>
---------
<br>
===== <span style="color: purple;">''Event ID''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' WORD
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] contains the Event ID of this equipment. See '''[[Equipment List Parameters#EventID|EventID]]''' for details.

<br>
---------
<br>
===== <span style="color: purple;">''Trigger mask''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' WORD
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] contains the Trigger mask of this equipment. See '''[[Equipment List Parameters#TriggerMask|TriggerMask]]''' for details.

<br>
---------
<br>

===== <span style="color: purple;">''Buffer''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] contains the Buffer parameter of this equipment. See
'''[[Equipment List Parameters#Buffer|Buffer]]''' for details.
For Events that are to be logged as banks, Buffer is set to "SYSTEM".

<br>
---------
<br>

===== <span style="color: purple;">''Type''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] contains the Type of this equipment. See '''[[Equipment List Parameters#Type|Type]]''' for details.
The Type is one of the defined '''Equipment Flags'''.

<br>
---------
<br>

===== <span style="color: purple;">''Source''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] contains the Interrupt or Event Source of this equipment. See '''[[Equipment List Parameters#Source|Source]]''' for details.

<br>
---------
<br>

===== <span style="color: purple;">''Format''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] contains the data format used for generating the event of this equipment. See '''[[Equipment List Parameters#Format|Format]]''' for details.

<br>
---------
<br>

===== <span style="color: purple;">''Enabled''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] indicated whether this equipment is active. See '''[[Equipment List Parameters#Enabled|Enabled]]''' for details.

<br>
---------
<br>

===== <span style="color: purple;">''Read on''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] specifies when the read-out of an event occurs or is enabled. It is set to one or a combination of [[ReadOn Flags]]. See '''[[Equipment List Parameters#ReadOn|Read on]]''' for details.

<br>
---------
<br>

===== <span style="color: purple;">''Period''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] specifies the time interval or time-out (units are milliseconds). See '''[[Equipment List Parameters#Period|Period]]''' for details.

<br>
---------
<br>

===== <span style="color: purple;">''Event limit''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
* '''Default:'''
</div>

This key in the [[#Common subtree|Common subtree]] specifies the time interval or time-out. See '''[[Equipment List Parameters#Event limit|Event limit]]''' for details.

<br>
---------
<br>

===== <span style="color: purple;">''Num subevents''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] enables the super-event capability. See '''[[Equipment List Parameters#Number of subevents|Number of subevents]]''' for details.

<br>
---------
<br>

===== <span style="color: purple;">''Log history''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' See [[#initial value|initial value]]
</div>

This key in the [[#Common subtree|Common subtree]] enables the [[History System]] for this equipment. See '''[[Equipment List Parameters#Log History|Log History]]''' for details.
A value of 0 disables history logging. This parameter also controls how frequently the history events are generated.

<br>
---------
<br>

===== <span style="color: purple;">''Frontend host''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#Common subtree|Common subtree]] contains the name of the Frontend host running the [[Frontend user code]] that defines this particular equipment.
It is filled by the system.

<br>
---------
<br>

===== <span style="color: purple;">''Frontend name''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#Common subtree|Common subtree]] contains the [[Frontend user code#frontend Name|Frontend name]] defined in the [[Frontend user code]] that defines this particular equipment.
It is filled by the system.

<br>
---------
<br>

===== <span style="color: purple;">''Frontend file name''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#Common subtree|Common subtree]] contains the filename of the [[Frontend user code]] that defines this particular equipment.
It is filled by the system.

<br>
---------
<br>

===== <span style="color: purple;">''Status''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#Common subtree|Common subtree]] contains the combination of [[#Frontend name|Frontend name]] and [[#Frontend host|Frontend host]] Frontend host that define this particular equipment. It is filled by the system and used by the [[Status Page#mhttpd status page]].

<br>
---------
<br>

===== <span style="color: purple;">''Status color''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "#00FF00"
</div>

This key in the [[#Common subtree|Common subtree]] contains a colour code to be used for the display of this equipment on the [[Status Page#mhttpd status page]].

<br>
---------
<br>

===== <span style="color: purple;">''Hidden''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>

This key in the [[#Common subtree|Common subtree]] if set to "y" will prevent the display of this equipment on the [[Status Page#mhttpd status page]].

<br>
---------
<br>

==== <span style="color: purple;">''Variables''</span> subtree ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>

This is a subtree in the [[#Top|/Equipment ODB Tree]].

If either
* the [[#Read on|Read on]] parameter contains the [[ReadOn Flags|RO_ODB flag]] or
* [[#Log history|Log history]] is non-zero, i.e. History logging is enabled
the event data will be copied to the ODB and listed in this subtree.

In that case, this subtree will contain array(s) of event data named for the bankname(s) in the readout function (see [[Frontend user code#Event Readout routine]].
See [[#Example Variables subtree|example]] above.

<br>
---------
<br>

==== <span style="color: purple;">''Statistics''</span> subtree ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>

This subtree in the [[#Top|/Equipment ODB Tree]] contains statistics written by the system.

<br>
---------
<br>

===== <span style="color: purple;">''Events sent''</span> subtree =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
</div>
This key in the [[#Statistics subtree|Statistics]] subtree contains the number of events of [[#Event ID|Event ID]] sent. It is filled by the system and used for display on the [[Status Page#mhttpd status page]]. See [[#Example Statistics subtree|example]] above.

<br>
---------
<br>

===== <span style="color: purple;">''Events per sec''</span> subtree =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
</div>
This key in the [[#Statistics subtree|Statistics]] subtree contains the number of events of [[#Event ID|Event ID]] sent per second. It is filled by the system and used for display on the [[Status Page#mhttpd status page]].

<br>
---------
<br>

===== <span style="color: purple;">''kBytes per sec''</span> subtree =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
</div>
This key in the [[#Statistics subtree|Statistics]] subtree contains the number of kBytes per second for events of [[#Event ID|Event ID]] sent. It is filled by the system and used for display on the [[Status Page#mhttpd status page]].

<br>
---------
<br>

==== <span style="color: purple;">''Settings''</span> subtree ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>

This subtree in the [[#Top|/Equipment ODB Tree]] contains user-defined settings, some of which may be used by the system.
Any values defined in this subtree will appear in [[Event Notification (Hot-Link)#experim_dot_h|experim.h]] files.

<br>
---------
<br>

===== <span style="color: purple;">''<Names>''</span> subtree =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING (ARRAY)
</div>

These optional key(s) in the [[#Settings subtree|Settings]] subtree are used to define the names of variables in the [[#Variables subtree|Variables subtree]].
If more than one bank is defined, there will be multiple keys named for the bankname, which will be arrays whose elements contain the name of each variable in the bank.
These keys are added by the user.

The Names array(s) (if present) will be used by the [[Status Page|mhttpd status page]] in the
[[Status Page#Equipment Information|display]] of the Equipment variables, and by the [[History System]] to generate tags. See [[#Example Settings subtree|example]] above.

[[Category:ODB Tree]] [[Category:Equipment]] [[Category:History]]

History System

2019-06-05T11:31:47Z

Gerritzen: /* Example */

{{Pagelinks}}

== Links ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[/History ODB tree]]
* [[History Page]]
* [[Mhformat|MIDAS history file format]]
* [[Keys in the ODB /Logger tree|/Logger ODB tree]]
* [[Keys in the ODB /Logger/History subtree|/Logger/History subtree]]
*
</div>

<div id="history file"></div>
= Introduction =

The history system is an add-on capability built into the MIDAS data logger [[mlogger]] to record useful information in parallel to the data logging.
This information is recorded with a time stamp and saved into a '''history file''' (see [[#History drivers|History drivers]]) for later retrieval. One set of files is created per day containing all the requested history events. The history data may be displayed in graphical form using the [[mhttpd]] MIDAS webserver utility, giving the user an easy way of seeing how experimental variables have changed with time.
The history logging will be in action only if the MIDAS data logger is running, but it is not necessary to have any [[Keys in the ODB /Logger tree#/Logger/Channels subtree|data logging channel]] enabled.

= MidasHistoryInterface =

The new history configuration defines history channels similar to logger channels. Each history channel creates a history interface class (class MidasHistoryInterface). The [[mlogger|data logger]] can use this interface to write data into the history, mhttpd, mhist & co can use this interface to read data from the history. The interface is defined in history.h

* http://ladd00.triumf.ca/~daqweb/doc/midas/include/history.h

= History drivers =

Presently, the MIDAS distribution contains these drivers:

; MIDAS-History
: this is the traditional history driver, with data stored in the .hst binary files. (format is documented here [[mhformat]], see also [[mhist]] and [[mhdump]])
: By default ODB subtree '''[[Keys in the ODB /Logger/History subtree#MIDAS subtree |"MIDAS"]]''' is set up to write MIDAS-history.

; ODBC-History
: stores history data in SQL database using the ODBC abstraction layer. See [[#MIDAS ODBC SQL History system|ODBC SQL History system]].

: By default ODB subtree '''[[Keys in the ODB /Logger/History subtree#ODBC subtree|"ODBC"]]''' is set up to write ODBC-history.

; SQLITE-History
: stores data in SQL database as SQLITE3 .sqlite3 files. The SQL table format is similar to ODBC-history, performance is similar, no database server required.
: By default ODB subtree '''[[Keys in the ODB /Logger/History subtree#SQLITE subtree|"SQLITE"]]''' is set up to write SQLITE-history.

; MYSQL-History
:
: By default ODB subtree '''[[Keys in the ODB /Logger/History subtree#MYSQL subtree|"MYSQL"]]''' is set up to write MYSQL-history.

; FILE-History
: stores each variable in its own file, making it much easier to trace the history of a particular variable.
: By default ODB subtree '''[[Keys in the ODB /Logger/History subtree#FILE subtree|FILE]]''' is set up to write FILE-history.

More drivers can be easily added by the user (create history_xxx.cxx, add constructor to hs_get_history(), create the ODB subtree <span style="color:purple; font-style:italic">/Logger/History/xxx/channel</span>).

= Location of History Files =
;MIDAS-history
:By default, the traditional MIDAS-history is enabled, writing history files into the MIDAS data directory path given by the ODB key [[Keys in the ODB /Logger tree#Data dir|Data dir]].
:If history data is important, it is recommended to write it to a directory that is backed up or archived. (The MIDAS data directory is usually located on a scratch data disk without backups).

:The location of the MIDAS-history data files can be changed by use of the ODB Key [[Keys in the ODB /Logger tree#History dir|History dir]].

;ODBC-History
:The location of ODBC-History files is ...

;SQLITE-History
:The location of SQLITE-History files is the directory path given by the ODB key [[Keys in the ODB /Logger/History subtree#Sqlite dir|Sqlite dir]].

;MYSQL-History
:The location of MYSQL-History files is ...

;FILE-History
:The location of FILE-History files is the directory path given by the ODB key [[Keys in the ODB /Logger/History subtree#History dir|History dir]].

= Types of History Events =

There are two basic types of history events, which are defined in different ways:

* "[[#Frontend History Event|Frontend]]" (or "Equipment") History event composed in the frontend. See [[#Frontend History Event|Frontend History Event]] for details.
* "Virtual" (or "Links") History event composed within the ODB under the [[/History ODB tree#Links subtree|/History/Links subtree]]. See [[#Virtual History Event|Virtual History Event]] for details.

Both these history event definitions take effect when the data logger gets a start run [[Run States and Transitions|transition]]. Any modifications made during the run are not applied until the start of the next run.

== Virtual History Event ==
The history of any ODB variable can be recorded in a "virtual" history event by creating a link to that variable in the [[/History ODB tree#Links subtree|/History/Links subtree]]. This is used for ODB variables that are not in an Equipment.

; To enable Virtual History Events
: Create links as desired in [[/History ODB tree#Links subtree|/History/Links subtree]].

History events are created for each entry under ODB subdirectory {{Odbpath|path=/History/Links}}.

Two types of links are permitted:
<dl>
<dt> ODB key {{Odbpath|path=/history/links/aaa}} is a link to a subdirectory</dt>
<dd><ol>
<li> db_watch() is setup to watch this subdirectory</li>
<li> tags are created for each subdirectory entry (1 tag per entry)</li>
<li> There is no possibility for naming array elements, so 1 tag per array, regardless of the number of elements.</li> </ol></dd>
<dt>ODB key {{Odbpath|path=/history/links/bbb}} is a subdirectory with links to ODB values</dt>
<dd> <ol>
<li>db_watch is setup to watch each link target</li>
<li> tags are created for each link (1 tag per link)</li>
<li> tag name is the link name (NOT the target name). There is no possibility for naming array elements</li>
</ol></dd>
</dl>

Mixing links and subdirectories is not permitted.

The update period of history events created for {{Odbpath|path=/history/links}} is controlled by entries in {{Odbpath|path=/history/links periods}}. Numeric values of periods are same as for a [[#Frontend History Event|Frontend History event]]. Numeric value 0 disables the history for a particular event.

See [https://midas.triumf.ca/elog/Midas/1087 MidasElog#1087] for more information.

== Frontend History Event ==

Each [[Frontend Operation#Equipments and Events|Equipment]] has the capability to generate "history data".

; To enable Frontend History Events

: Set the [[/Equipment ODB tree#Log history|Log history]] ODB key of each equipment to be logged '''non-zero'''. (See [[Equipment List Parameters#Log History|Log History parameter]]). (You may need to restart the frontend.)

This causes the event contents to be copied to the ODB [[/Equipment ODB tree#Variables subtree|/Equipment/''<equipment-name>''/Variables subtree]] for the use of the History system. history events are created by parsing the content of {{Odbpath|path=/Equipment/<equipment-name>/variables}}.

For each equipment, history is controlled by the value of {{Odbpath|path=/Equipment/<equipment-name>/common/period}} as follows:
* 0 = history disabled
* 1 = history is enabled
* >1 = history is enabled, throttled down

The throttling is implemented in log_history()/watch_history() by this algorithm:
the very first history event is recorded, then all changed to the data are ignored until "period" seconds has elapsed. Then the next history event will be recorded, and following
changes will be ignored until "period" second elapses, and so forth. Period value "1" has special meaning - there is no throttling, all history events are logged.

This information is from [https://midas.triumf.ca/elog/Midas/1087 MidasElog#1087].

=== Sequence for frontend History Event ===
The main steps for the frontend History Event is as follows:

* The user code in the frontend equipment Event Readout routines reads the data, placing it into a MIDAS data bank
* In mfe.c, if the key [[/Equipment ODB tree#Log history|Log history]] > 0 (i.e. the history system is enabled for this equipment), this data bank is written into ODB (by update_odb()).
* This ODB write triggers an ODB hot-link into mlogger
* The hot-link calls mlogger.c::log_history(), which calls hs_write() to write the data into the history file. The frequency of the history writes is specified by the number of seconds between writes stored in the ODB key [[/Equipment ODB tree#Log history|Log history]].
* history.c::hs_write() or history_odbc::hs_write_odbc() writes the data into a history file or into an SQL database.

= How to Write History events =
* Enable desired [[#To enable Frontend History Events|Frontend]] and/or [[#To enable Virtual History Events|Virtual]] history events
* [[#Select the history driver|Select the history driver]]
* Follow instructions below for selected driver:
** [[#Write MIDAS-History events|Write MIDAS-history events]]
** [[#Write ODBC-History events|Write ODBC-history events]]
** [[#Write SQLITE-History events|Write SQLITE-history events]]
** [[#Write MYSQL-History events|Write MYSQL-history events]]
** [[#Write FILE-History events|Write FILE-history events]]

== Select the history driver ==

* Select the '''[[#History drivers|history driver]]''' and therefore the [[Keys in the ODB /Logger/History subtree#<history-logging-channel> subtrees|history-logging-channel]] to use to write the MIDAS-history files.
* set [[Keys in the ODB /Logger/History subtree#Active|Active]] ODB key in the selected [[Keys in the ODB /Logger/History subtree#<history-logging-channel> subtrees|history-logging-channel]] to "y". All other logging channels should be disabled.
* set [[/History ODB tree#LoggerHistoryChannel|LoggerHistoryChannel]] ODB key to the selected [[#History drivers|History channel]].

== Write MIDAS-History events ==
* Enable desired [[#To enable Frontend History Events|Frontend]] and/or [[#To enable Virtual History Events|Virtual]] history events
* Perform steps in [[#Select the history driver|Select History Driver]] with [[#History drivers|history driver]] "MIDAS".
* Restart [[mhttpd]] and [[mlogger]], start the run.

MIDAS-history files will be saved into the [[#Location of History Files|MIDAS-history data directory]].

== Write ODBC-History events ==

See [[#MIDAS ODBC SQL History system|MIDAS ODBC SQL History system]].
* If necessary, [[#Set up a MySQL database|set up a MySQL database]].
* Enable desired virtual and frontend history events (see [[#Virtual History Event|Virtual history events]] and [[#Frontend History Event|Frontend history events]]).
* Perform steps in [[#Select the history driver|Select History Driver]] with [[#History drivers|history driver]] "ODBC".
* Check ODB Key [[Keys in the ODB /Logger/History subtree#Writer_ODBC_DSN|Writer_ODBC_DSN]] is set to "history writer" and Key [[Keys in the ODB /Logger/History subtree#Reader_ODBC_DSN|Reader_ODBC_DSN]] is set to "history reader" (the default values)
* set [[Keys in the ODB /Logger/History subtree#Debug|Debug]] to 1 if desired
* restart [[mlogger]] in verbose mode (i.e. mlogger -v), and observe how it issues SQL commands to create the tables and columns corresponding to MIDAS-history events and tags.
* restart [[mhttpd]]

'''Notes'''
# [[mlogger]] is programmed to raise alarms if connection to SQL database is interrupted or if some events cannot be written into the database (i.e. data type mismatch, SQL syntax errors, etc). The traditional MIDAS-history never raised alarms because it "never failed" - other than from "disk full" errors, which are immediately obvious.
# With ODBC History enabled, [[mhttpd]] will only use history information from the SQL database to make history plots and to extract history variable names for the history plot editor. The ODB {{Odbpath|path=/History}} subtrees[[/History ODB tree#Tags subtree|Tags]] and [[/History ODB tree#Events subtree|Events]] are not used.
# variable names presented to the user may change from MIDAS names to SQL names (use the history panel "Label" text fields to create permanent plot labels).

== Write SQLITE-history events ==

No special configuration required.

* Enable desired virtual and frontend history events (see [[#Virtual History Event|Virtual history events]] and [[#Frontend History Event|Frontend history events]]).
* Perform steps to [[#Select the history driver|Select History Driver]] with [[#History drivers|history driver]] "SQLITE".

* Create a directory for storage of sqlite history files
* save its path in the ODB key [[Keys in the ODB /Logger/History subtree#Sqlite dir|Sqlite dir]]
* restart [[mhttpd]] and [[mlogger]]

In the history data directory (in [[Keys in the ODB /Logger/History subtree#Sqlite dir|Sqlite dir]]) you should see files with name "mh_xxx.sqlite3" corresponding to your equipment and variable names.

== Write MYSQL-history events ==

* Enable desired virtual and frontend history events (see [[#Virtual History Event|Virtual history events]] and [[#Frontend History Event|Frontend history events]]).
* Perform steps to [[#Select the history driver|Select History Driver]] with [[#History drivers|history driver]] "SQLITE".
...........

== Write FILE-history events ==

* Enable desired virtual and frontend history events (see [[#Virtual History Event|Virtual history events]] and [[#Frontend History Event|Frontend history events]]).
* Perform steps to [[#Select the history driver|Select History Driver]] with [[#History drivers|history driver]] "SQLITE".
* Assign directory path for saved files using the ODB key [[Keys in the ODB /Logger/History subtree#History dir|History dir]].
...........

<br>
---------------
<br>

= History Events =
The following information is derived from [https://midas.triumf.ca/elog/Midas/1087 MidasElog#1087].

A "history event" is a history atomic unit of data. Associated with each history event is a timestamp (unix time),
a name (limited to NAME_LENGTH in the old history) and a list of history tags that describe the individual data
values inside the history event.

When making history plots in [[mhttpd]] (see [[History Page]]) for each curve on the plot, one selects a history event (from the list
of currently active events, recently active events or the list of all events that ever existed), then from the list of tags
inside the history event one selects the particular variable that will be plotted.

== Old MIDAS history events ==
In the old MIDAS history, all history events are written into one history file (.hst file + optional .def and .idx event definition and time index files
which can be/are regenerated automatically from the .hst file). History events are identified by 16-bit history event IDs, the persistent mapping
from history event names and the 16-bit history event IDs is stored in ODB subtree {{Odbpath|path=/History/Events}}. In addition the list of all known history event tags is
stored in ODB subtree {{Odbpath|path=/History/Tags}}. For per-equipment history, the 16-bit history event ID is the value of ODB key [[/Equipment ODB tree#Event ID|/Equipment/<equipment-name>/Common/Event ID]].

== SQL history events ==
In the SQL history (MySQL, SQLITE, etc), each history event is an SQL table. The history event tags are the SQL table columns.

== FILE history events ==
In the new FILE history, each history event is written into a separate file, tag definition are recorded in text format in the file header, history event
data is appended to the file in binary format (fixed record size). If the history event definition is changed, a new file will be started.

= History Event Construction =
The [[mlogger]] creates [[#Frontend history event]]s in open_history() by parsing the ODB subtree {{Odbpath|path=/equipment/<equipment-name>/variables}}. Each ODB entry under the {{Odbpath|path=variables/}} subtree is referred to as a "variable". Each variable can be a single ODB value, an array of ODB values, or a subdirectory (corresponding to TID_STRUCT structured data banks). As each variable is processed, one or more tags are created to describe it.

Single ODB values will generally produce a single tag, while arrays can produce (depending whether the array is "[[#Named Arrays|Named]]" or not)
* multiple tags - one per array element ("Named" array) or
* one single tag - describing the whole array

The code can generate two types of history:
<dl>
<dt> "per-equipment" history</dt>
<dd> will have the tags for all variables concatenated together into one single history event</dd>
<dt> "per-variable" history</dt>
<dd> will have one history event defined for each variable. Inside could be one tag (for single odb values and unnamed array) or multiple tags (for named arrays and structured data
banks).</dd>
</dl>

Per-equipment history is the original MIDAS history implementation. Per-variable history was added to permit efficient data storage in SQL tables. Its initial implementation used 1 ODB hotlink for each variable and it was easy to exceed the maximum permitted number of ODB hotlinks (db_open_record()). To reduce consumption of hotlinks, db_watch() has been implemented and now per-variable history only uses 1 ODB hotlink per equipment.

;NOTE
: With db_watch, per-equipment history is no longer available. '''Per-variable history is the new default''' (and the only option).

[https://midas.triumf.ca/elog/Midas/1087 MidasElog#1087]

= Construction of history event tags =
Currently,
* single ODB values are treated as arrays of length "1"
* string ODB entries are not permitted

History event tags are constructed in the [[mlogger]] add_equipment(). Presently there are some quirks with the generation of history event tags (see [https://midas.triumf.ca/elog/Midas/1088]),
e.g. single odb values are treated as arrays of length "1" and "string" ODB entries are not permitted.

For variables of type TID_KEY (subdirectories, corresponding to TID_STRUCT structured banks), one tag is generated for each subdirectory entry. Tag names for {{Odbpath|path=/equipment/<equipment-name>/variables/aaa/bbb}} will be "aaa_bbb" (with an underscore). Subdirectory entries of type TID_KEY and TID_LINK are currently not supported.

For "[[#Named Arrays|Named Arrays]]", individual tags are generated for each array element. Tag names are taken from the ''Names'' array. For empty tag names (empty names array), tags are "aaa_0", "aaa_1", etc (for {{Odbpath|path=/equipment/<equipment-name>/variables/aaa}}).

For "[[#Named Arrays|Single Names Arrays]]", tag names have the variable name appended (with a space), for {{Odbpath|path=/equipment/<equipment-name>/variables/aaa}} and an empty names array, tags will be "aaa_0 aaa", "aaa_1 aaa", etc. For a populated names array, the tags will be "name0 aaa", "name1 aaa", etc.

For unnamed arrays and single odb variables (in ODB, single odb variables are arrays of length 1), a single tag is generated.

== Named Arrays ==

'''Named Arrays''' have a "Names" entry in {{Odbpath|path=/equipment/<equipment-name>/settings}}.

For example, to add names to {{Odbpath|path=/equipment/<equipment-name>/variables/aaa}}, create a string array {{Odbpath|path=/equipment/<equipment-name>/settings/names aaa}}. The names array should be at least as long as the corresponding data array. Individual entries in the names array can be left blank (tag names will be "aaa_0", "aaa_1", etc). Duplicate tag names are not permitted.

A single "Names" entry can be created to name all arrays in variables with the same names ('''"Single Names"''').

Create {{Odbpath|path=/equipment/<equipment-name>/settings/names}} and arrays {{Odbpath|path=/equipment/<equipment-name>/variables/aaa}} and {{Odbpath|path=/equipment/<equipment-name>/variables/bbb}} will have
history tags "name0 aaa", "name1 aaa", "name0 bbb", "name1 bbb", etc. If "names" are left blank, tag names will be "aaa_0 aaa", "aaa_1 aaa", "bbb_0 bbb", "bbb_1 bbb", etc.

In the [[mhttpd]] web server [[History Page]] variables viewer, "single name" arrays are displayed in a 2D table.

This information is from [https://midas.triumf.ca/elog/Midas/1088].

= Historical note on MIDAS-History Tag names =
Tags are only used for MIDAS-history events.

The mlogger/mhttpd implementation of <span style="color:purple; font-style:italic">/History/Tags</span> has proved troublesome and we are moving away from it.

;During the transition period:
: Implementations starting with Version 4435 of [[mlogger]] and [[mhttpd]] (i.e. "new" versions) will now work '''without''' <span style="color:purple; font-style:italic">/History/Tags</span>. The history tags are read directly from the history files themselves. To run in this mode, set ODB key [[/History ODB tree#DisableTags|/History/DisableTags]] to "y". Existing [[/History ODB tree#Tags subtree|/History/Tags subtree]] will be automatically deleted.

Two downsides to running like this are
* it is slower and tags become non-persistent
* if some frontends have not been running for a while, their variables may vanish from the history panel editor.

== New-style History Tags ==
For the above two reasons, using <span style="color:purple; font-style:italic">/History/Tags</span> is still recommended.
However, the format of the tags is now changed to simplify management and reduce ODB size.

; For NEW implementations
: the key [[/History ODB tree#CreateOldTags|CreateOldTags]] will not be present. "New-style" history tags will be created automatically in the [[/History ODB tree#Tags subtree|Tags subtree]].

;If you have old-style tags
: [[mlogger]] will automatically convert the old tags to this new format (this is why you should make a backup of your ODB).

** using "old" (i.e. pre Version 4435) mlogger with "new" mhttpd is OK: new mhttpd understands both formats of /History/Tags.
** using "old" mhttpd with "new" mlogger is OK provided the ODB key [[/History ODB tree#CreateOldTags|/History/CreateOldTags]] is set to "y" before starting mlogger.

== Old-style History Tags ==
Prior to versions 4435 of [[mlogger]] and [[mhttpd]], old-style history tags were generated.
See
* http://ladd00.triumf.ca/~daqweb/doc/midas-old/html/F_History_logging.html
for details.

<br>
---------------
<br>

= MIDAS ODBC SQL History system =

This section describes the internal workings of the MIDAS SQL history system.

The SQL history system implements the MIDAS history using a SQL database for data storage instead of flat binary files.

The SQL history code lives in a separate files history.h and history_sql.cxx. The present implementation uses the ODBC API for accessing SQL databases.
MySQL is fully supported, Pgsql support is partially implemented, support for arbitrary ODBC drivers should be easy to add in history_sql and most SQL operations are done using an interface class.

Preliminary testing with MySQL and PgSQL indicates that disk space requirements are the same for both storage mechanisms using flat binary files or either of the 2 SQL databases. All 3 tested storage mechanisms store the data uncompressed. (Observed gzip-1 compression ratios from CERN-ALPHA history files are 50% or better).

Preliminary testing also indicates that MySQL database is "not too slow" for use by T2K/ND280 slow control system. Using MySQL, performance seems to improve somewhat compared to traditional MIDAS-history because each SQL table is stored into a separate file, compared to everything-in-one-file in traditional MIDAS-history.

== Set up a MySQL database ==

In order to setup a MySQL database, the following is needed:

* the server hostname and port number
* database name
* user name and password.

It is recommended to create 3 different users:

* a "root" user with full priveleges,
* a "reader" user with read-only priveleges
* and a "writer" user with "insert, create table, and add column" priveleges (no permission to drop table, remove columns, etc)

=== Example ===
#Setup a MySQL database (RHEL/SL 5)

ssh root@localhost
service mysqld start
/usr/bin/mysql_secure_installation (enter current password for root: press <enter>, then accept default answer "Y" to all questions)
mysqladmin -p create history
using mysql-administrator, create 2 users:
history_writer, with database "history" schema privileges: select, insert, create, alter, index
history_reader, with database "history" schema privileges: select

#Setup $HOME/.odbc.ini file:

cat $HOME/.odbc.ini
[history_writer]
Description = history_writer
Driver = /usr/lib64/libmyodbc3.so
SERVER = ladd05.triumf.ca
PORT =
Database = history
OPTION = 3
SOCKET =
User = history_writer
Password = ******
[history_reader]
Description = history_reader
Driver = /usr/lib64/libmyodbc3.so
SERVER = ladd05.triumf.ca
PORT =
Database = history
OPTION = 3
SOCKET =
User = history_reader
Password =

Note: if you are using mhist you will need a separate .odbc.ini file for each user that you have connecting to the database (through MIDAS).

== Layout of SQL tables ==

* One table is created for each history event. Table name is the same as the history event name (as reported by [[mhdump]]).
* one column is created for each history tag (history variable). Column name is the same as the tag name (as reported by mhdump). For array tags, one column is created for each array element: array a[3] will produce columns a_0, a_1 and a_2.
* two special columns are always created: _i_time and _t_time are the timestamps in the UNIX-time integer format and in the SQL "time" format. (A priori, it is not clear which timestamp format is more useful for end users. mhttpd uses the _i_time integer time format). Note that this timestamp is the time when mlogger receives the hot-link signal (see above) and it can be a few seconds behind the time when the user placed the data into the MIDAS bank. For high precision (and sub-second time resolution) time stamps, users should generate their own timestamps and include them as part of the data itself.
* a special table called _history_index is created to remember the mapping between SQL names and MIDAS names for event names, variable name and tag names.

=== Schema Evolution ===

* when new data fields are added, new SQL columns are created automatically
* existing SQL columns are never deleted
* arrays are expanded automatically, and arrays never shrink.
* if the type of a data field changes, a conflict may occur with existing SQL columns, for example if previous type was "FLOAT" and new type is "DOUBLE", the existing SQL columns would have the SQL data type "float", too narrow to store new values. mlogger will complain about this. Such conflicts may be resolved by changing the type of the SQL column using SQL tools. In general, SQL names are created from MIDAS names by replacing all non-alphanumerical characters to an underscore "_". If this procedure creates duplicate column names, the column names and made unique by appending them with a random number, i.e. MIDAS names "A+B" and "A-B" will be translated to "A_B" and "A_B_12345" (random integer). True MIDAS names are saved into the _history_index.

[[Category:history]]

Keys in the ODB /Logger/History subtree

2019-06-05T11:30:38Z

Gerritzen: /* MYSQL subtree */

== Links ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[/Logger ODB tree| /Logger tree]]
* [[/History ODB tree| /History tree]]
* [[History System]]
* [[Logging to a mySQL database]]
* [[Keys in the ODB /Logger/Channels subtree| /Logger/Channels subtree]]
* [[Keys in the ODB /Logger/SQL subtree| /Logger/SQL subtree]]
* [[mlogger |MIDAS logger (mlogger)]]
</div>
<br>
---------------
<br>

=<span style="color: purple;">''/Logger/History''</span> subtree =

The ODB <span style="color: purple;">''/Logger/History''</span> subtree is a subdirectory of the [[Keys in the ODB /Logger tree | ODB /Logger tree]], created
when the MIDAS logger utility [[mlogger]] is started for the first time. The keys will be filled with default values which users may change as required to customize their experiments.

When [[mlogger]] is started for the first time, it now creates '''five''' <span style="color: purple;"> /Logger/History/<''history-logging-channel''></span> ODB subtrees to control the five default history-logging-channels'', named for each of the default
[[History System#History drivers|History drivers]].

The keys present in each history-logging-channel are described below.

<br>
---------------
<br>

= Example =
The following example shows the <span style="color:purple; font-style:italic">/Logger/History </span> ODB subtree after creation by [[mlogger]] (obtained using the [[odbedit]] '''ls''' command).
See below for information on individual keys.

<pre>
[local:midas:S]/>ls -r /Logger/History
History
MIDAS
Type MIDAS
Active y
Debug 0
PerVariableHistory 0
ODBC
Type ODBC
Active n
Debug 0
Writer_ODBC_DSN history_writer
Reader_ODBC_DSN history_reader
SQLITE
Type SQLITE
Active n
Debug 0
Sqlite dir
MYSQL
Type MYSQL
Active n
Debug 0
MYSQL Writer mysql_writer.txt
MYSQL Reader mysql_reader.txt
FILE
Type FILE
Active n
Debug 0
History dir
</pre>

<br>
-----
<br>

= <span style="color: purple;">''<history-logging-channel>''</span> subtrees =

Each <''history-logging-channel''> subtree in the [[#top|Logger/History subtree]]
is created (by [[mlogger]]) to control one of the [[History System#History drivers|history drivers]] available, and named for that history driver.
<br>Presently the five following history-logging-channel subtrees are created :
* MIDAS
* ODBC
* SQLITE
* MYSQL
* FILE
(see [[#Example|Example]] above).

By default, only the MIDAS-history logging channel is [[#active|Active]].

;NOTE
: In older MIDAS versions, the history-logging-channel subtrees were named 0,1,2... respectively

<br>
-----
<br>

== Keys common to all history logging channel subtrees ==
The following three keys are common to all [[#<history-logging-channel> subtrees|history logging channel subtrees]] :

=== <span style="color: purple;">''Type''</span>===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' [[History System#History drivers|History driver]] name
</div>

Each [[#<history-logging-channel> subtrees |history-logging-channel subtree]] contains a <span style="color: purple;">''Type''</span> key which specifies the type of
[[History System#History drivers|History driver]] for this channel.

When the subtree is created, the <span style="color: purple;">''Type''</span> key is set to the respective History driver name, e.g.
: ODB key <span style="color: purple;">/Logger/History/'''MIDAS'''/Type</span> will be set to '''"MIDAS"'''
: ODB key <span style="color: purple;">/Logger/History/'''ODBC'''/Type</span> will be set to '''"ODBC"'''

and so on (see [[#Example|Example]] above for all five logging channels).

<br>
---------------
<br>
=== <span style="color: purple;">''Active''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>

Each [[#<history-logging-channel> subtrees |history-logging-channel subtree]] contains a <span style="color: purple;">''Active''</span> key
which enables or disables history logging in this channel.

By default, only the MIDAS-history logging channel will be set active, i.e. ODB key <span style="color: purple;">/Logger/History/'''MIDAS'''/Active</span> will be set to "y".

<br>
;Note
: This key in the [[#MIDAS subtree|MIDAS subtree]] replaces obsolete key [[Keys in the ODB /Logger tree #/Logger/WriteFileHistory|/Logger/WriteFileHistory]]

<br>
--------------
<br>

=== <span style="color: purple;">''Debug''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>

Each [[#<history-logging-channel> subtrees |history-logging-channel subtree]] contains a <span style="color: purple;">''Debug''</span> key
which controls the debug level for this channel. If set to 0, debugging is disabled.

;Note
:This key in the [[#ODBC subtree|ODBC subtree]] replaces obsolete key [[Keys in the ODB /Logger tree #/Logger/ODBC_Debug |/Logger/ODBC_Debug]]

<br>
--------------
<br>

== <span style="color: purple;">''MIDAS''</span> subtree ==

This is the [[#<history-logging-channel> subtrees| history-logging-channel subtree]] that controls [[History System#History drivers|MIDAS-history]] logging.

For those Keys common to all history-logging-channels see
*[[#Type|Type]]
*[[#Active|Active]]
*[[#Debug|Debug]]

;Note
: By default, this logging channel will be set active.

The following section(s) describe keys unique to the <span style="color: purple;">''MIDAS''</span> subtree :

=== <span style="color: purple;">''PerVariableHistory''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>

This key is present in the [[#MIDAS subtree|MIDAS subtree]] (whose [[#Type|Type]] key set to "MIDAS").

The default value of 0 is intended to operate the MIDAS-history in "traditional" mode. In this mode:
* there is one history record for each equipment
* history record id is equal to the equipment id
* Subtrees <span style="color: purple;">/History/Events</span> and <span style="color: purple;">/History/Tags</span> are not required and can be safely deleted

;Note
: this key replaces obsolete key <span style="color: purple;">/History/PerVariableHistory</span>

<br>
--------------
<br>

== <span style="color: purple;">''ODBC''</span> subtree ==

This is the [[#<history-logging-channel> subtrees| history-logging-channel subtree]] that controls [[History System#History drivers|ODBC-history]] logging.

For those Keys common to all history-logging-channels see
*[[#Type|Type]]
*[[#Active|Active]]
*[[#Debug|Debug]]

;Note
:[[#Debug|Debug]] key in this subtree replaces obsolete key [[Keys in the ODB /Logger tree #/Logger/ODBC_Debug |/Logger/ODBC_Debug]].

The following section(s) describe keys unique to the ODBC subtree:

=== <span style="color: purple;">''Writer_ODBC_DSN''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "history_writer"
</div>

This key is present in the [[#ODBC subtree|ODBC]] subtree (whose [[#Type|Type]] key is set to "ODBC").

It contains the ODBC Data Source Name for writing and is used by [[mlogger]].

;Note
: this key replaces obsolete key [[Keys in the ODB /Logger tree #/Logger/ODBC DSN |/Logger/ODBC DSN]]
<br>
--------------
<br>

=== <span style="color: purple;">''Reader_ODBC_DSN''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "history_reader"
</div>

This key is present in the [[#ODBC subtree|ODBC]] subtree (whose [[#Type|Type]] key is set to "ODBC").

It contains the ODBC Data Source Name for reading, and is used by [[mhttpd]] and [[mhist]] utilities.

;Note
: this key replaces obsolete key <span style="color: purple;">/history/ODB_DSN</span>

<br>
--------------
<br>

== <span style="color: purple;">''SQLITE''</span> subtree ==

This is the [[#<history-logging-channel> subtrees| history-logging-channel subtree]] that controls [[History System#History drivers|SQLITE-history]] logging.

For those Keys common to all history-logging-channels see
*[[#Type|Type]]
*[[#Active|Active]]
*[[#Debug|Debug]]

The following section(s) describe keys unique to the SQLITE subtree :

=== <span style="color: purple;">''Sqlite dir''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key is present in the [[#SQLITE subtree|SQLITE subtree]] (whose [[#Type|Type]] key is set to "SQLITE").

It contains the location of SQLITE database files, and is of the form "/file/system/path".

<br>
--------------
<br>

== <span style="color: purple;">''MYSQL''</span> subtree ==

This is the [[#<history-logging-channel> subtrees| history-logging-channel subtree]] that controls [[History System#History drivers|MYSQL-history]] logging.

For those Keys common to all history-logging-channels see
*[[#Type|Type]]
*[[#Active|Active]]
*[[#Debug|Debug]]

The following section(s) describe keys unique to the MYSQL subtree :

=== <span style="color: purple;">''MYSQL Writer''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' mysql_writer.txt
</div>

This key is present in the [[#MYSQL subtree|MYSQL subtree]] (whose [[#Type|Type]] key is set to "MYSQL").

It contains the name of the config file for the MYSQL database and the history writer account. This file should look similar to the following:
<pre>
server=localhost
port=3306
database=history
socket=/var/lib/mysql/mysql.sock
user=history_writer
password=[password of mysql user]
buffer=10000
</pre>

<br>
--------------
<br>

=== <span style="color: purple;">''MYSQL Reader''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' mysql_reader.txt
</div>

This key is present in the [[#MYSQL subtree|MYSQL subtree]] (whose [[#Type|Type]] key is set to "MYSQL").

It contains the name of the config file for the MYSQL database and the history reader account. This file should look similar to the following:
<pre>
server=localhost
port=3306
database=history
socket=/var/lib/mysql/mysql.sock
user=history_reader
password=[password of mysql user]
buffer=10000
</pre>

<br>
--------------
<br>

== <span style="color: purple;">''FILE''</span> subtree ==

This is the [[#<history-logging-channel> subtrees| history-logging-channel subtree]] that controls [[History System#History drivers|FILE-history]] logging.

For those Keys common to all history-logging-channels see
*[[#Type|Type]]
*[[#Active|Active]]
*[[#Debug|Debug]]

The following section(s) describe keys unique to the FILE subtree :

=== <span style="color: purple;">''History dir''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' ""
</div>

This key is present in the [[#FILE subtree|FILE subtree]] (whose [[#Type|Type]] key is set to "FILE").

It contains the name of the directory in which the FILE-history files are to be stored.

<br>
--------------
<br>

[[Category: Logger Tree]] [[Category:History]]