MidasWiki - User contributions [en]

/Experiment ODB tree

2019-05-29T01:40:23Z

Suz:

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[odbedit]]
*
*
</div>

== Creating the <span style="color: purple;">''/Experiment''</span> tree ==
The <span style="color: purple;">''/Experiment''</span> ODB tree is created automatically when the '''[[odbedit #Creating the ODB|ODB is first created]]'''.

== Purpose ==
The <span style="color: purple;">''/Experiment''</span> ODB tree contains information relevent to the experiment. Other optional keys are added by '''[[mhttpd]]''' or by
the user to customize their experiment.

== Examples ==
When initially created, the <span style="color: purple;">''/Experiment''</span> tree contains the following keys:
[local:midas:S]/>ls -lrt /experiment
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Experiment DIR
Name STRING 1 32 14s 0 RWD midas
Buffer sizes DIR
SYSMSG DWORD 1 4 11h 0 RWD 100000
Security DIR
Enable non-localhost RPC BOOL 1 4 46s 0 RWD n
RPC ports DIR
ODBEdit DWORD 1 4 38m 0 RWD 0
RPC hosts DIR
Allowed hosts STRING 10 256 38m 3 RWD
[0] localhost
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
Disable RPC hosts check BOOL 1 4 46s 0 RWD n

The following example shows the <span style="color: purple;">''/Experiment''</span> tree for a typical experiment:

[local:midas:R]/>ls -lrt /experiment
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Experiment DIR
Name STRING 1 32 7s 0 RWD midas
<span style="color: purple;">Buffer sizes</span> DIR
SYSMSG DWORD 1 4 23h 0 RWD 100000
SYSTEM DWORD 1 4 23h 0 RWD 640000000
BUF0 DWORD 1 4 23h 0 RWD 80000000
BUF1 DWORD 1 4 23h 0 RWD 80000000
....... <span style="color: green;">''other user-defined buffers not shown ''</span>
<span style="color: purple;">Security</span> DIR
Enable non-localhost RPC BOOL 1 4 38m 0 RWD n
<span style="color: purple;">RPC ports</span> DIR
ODBEdit DWORD 1 4 38m 0 RWD 0
Logger DWORD 1 4 35m 0 RWD 0
mhttpd DWORD 1 4 23m 0 RWD 0
<span style="color: purple;">RPC hosts</span> DIR
Allowed hosts STRING 10 256 38m 3 RWD
[0] localhost
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
Disable RPC hosts check BOOL 1 4 38m 0 RWD n
<span style="color: purple;">mhttpd hosts</span> DIR
Allowed hosts STRING 10 256 5h 0 RWD
[0]
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
midas http port INT 1 4 5h 0 RWD 8080
midas https port INT 1 4 5h 0 RWD 8443
http redirect to https BOOL 1 4 5h 0 RWD y
Start-Stop Buttons BOOL 1 4 8h 0 RWD y
Pause-Resume Buttons BOOL 1 4 8h 0 RWD n
<span style="color: purple;">Status items</span> DIR
Experiment Name -> /Experiment/Name
MAX_EVENT_SIZE DWORD 1 4 23h 0 RWD 4194304
Midas server port DWORD 1 4 3m 0 RWD 1175
Transition debug flag INT 1 4 23h 0 RWD 0
Transition connect timeout INT 1 4 23h 0 RWD 10000
Transition timeout INT 1 4 23h 0 RWD 120000
<span style="color: purple;">edit on start</span> DIR
experiment number DWORD 1 4 2h 0 RWD 9499
field STRING 1 32 2h 0 RWD 19000.2(0.0)G
comment-> /Experiment/run parameters/comment
STRING 1 80 2h 0 RWD Testing with low beam
Number of channels -> /Run Parameters/number of channels
DWORD 1 4 2h 0 RWD 20
Write Data -> /Logger/Write data
BOOL 1 4 2h 0 RWD n
Number of cycles -> /Equipment/FIFO_acq/frontend/hardware/num cycles
DWORD 1 4 2h 0 RWD 0
<span style="color: purple;">Parameter Comments</span> DIR
field STRING 1 32 >99d 0 RWD <i>Entered in Tesla unit</i>
Num cycles STRING 1 80 >99d 0 RWD <i>Stop run after num cycles is reached. Enter 0 to disable (free running)</i>
<span style="color: purple;">Run Parameters</span> DIR
Comment STRING 1 80 2h 0 RWD Testing with low beam
Run Description STRING 1 256 7h 0 RWD Sequencer Tests
Number of channels DWORD 1 4 2h 0 RWD 20
<span style="color: purple;">Lock when running</span> DIR
Num channels -> /Run Parameters/number of channels
DWORD 1 4 2h 0 RWD 20
<span style="color: purple;">edit on sequence</span> DIR
title STRING 1 128 2h 0 RWD none
experiment number DWORD 1 4 2h 0 RWD 9438
experimenter STRING 1 32 2h 0 RWD gls
sample STRING 1 36 2h 0 RWD NA
run description -> /Experiment/run parameters/run description
STRING 1 256 7h 0 RWD Sequencer Tests
Write Data -> /Logger/Write data
BOOL 1 4 2h 0 RWD n
Number of cycles -> /Equipment/FIFO_acq/frontend/hardware/num cycles
DWORD 1 4 2h 0 RWD 0
Prevent start on alarms BOOL 1 4 22h 0 RWD n
Prevent start on required BOOL 1 4 22h 0 RWD n
<span style="color: purple;">Status items</span> DIR
Experiment Name -> /Experiment/Name
STRING 1 32 7s 0 RWD midas
Start-Stop Buttons BOOL 1 4 5h 0 RWD y
Pause-Resume Buttons BOOL 1 4 5h 0 RWD n

== Keys in <span style="color: purple;">''/Experiment''</span> tree==

The keys in the ODB <span style="color: purple;">''/Experiment tree''</span>
are described in the following sections.

=== <span style="color: purple;">''Name ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This key in the [[#top|/Experiment tree]]
contains the name of the experiment. It is created by the MIDAS system when the ODB is created.

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

=== <span style="color: purple;">''Buffer Sizes ''</span> subtree ===
* '''Type:''' DIR

This key in the [[#top|/Experiment tree]] is a subtree to contain the sizes of the
Midas Buffers for the experiment. Created by the MIDAS system with default values. The sizes can be changed to optimize the memory usage. See '''[[Event Buffer]]''' Size(s) for details. Other user-defined
buffers may be present (e.g. for '''[[event filtering]]''').
<br>
--------
<br>

==== <span style="color: purple;">''SYSMSG ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 100000 Bytes
</div>
This key in the [[#Buffer Sizes|/Experiment/Buffer Sizes subtree]]
contains the size of SYSMSG buffer. This buffer is used for MIDAS messages.
The default value of this key is defined by MESSAGE_BUFFER_SIZE in $MIDASSYS/include/msystem.h .

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

==== <span style="color: purple;">''SYSTEM ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 32MiBytes
</div>
This key in the [[#Buffer Sizes|/Experiment/Buffer Sizes subtree]]
contains the size of SYSTEM buffer. The default value of this key is
DEFAULT_BUFFER_SIZE = 32 MiB (defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h_source.html midas.h]).
The actual SYSTEM buffer size is set by this key. To increase the SYSTEM buffer size (e.g. for very large events), see [[Event Buffer]].
<br>
--------
<br>

=== <span style="color: purple;">''MAX_EVENT_SIZE ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 4MiBytes
</div>
This key in the [[#top|/Experiment tree]]
specifies the maximum event size that can be acquired. The default value of this key is
DEFAULT_MAX_EVENT_SIZE = 4 MiB (defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h_source.html midas.h]).
The actual maximum event size is set by this key, and can be increased for larger events if needed (see [[Event Buffer]] for more information).

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

=== <span style="color: purple;">''midas http port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 8080
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the listening port for the HTTP server (default 8080). This will be redirected to the secure HTTPS port given by [[#midas https port|midas https port]] if the key [[#http redirect to https|http redirect to https]] is set to "y".

If the http port are supplied with the "--http" option when starting {{Utility|name=mhttpd}}, the port supplied will overwrite the default value stored in this key. See [[mhttpd]] for details.

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''midas https port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 8443
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the listening port (default 8443) for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]).

If the https port is supplied with the "--https" option when starting {{Utility|name=mhttpd}}, the port supplied will overwrite the default value stored in this key. See [[mhttpd]] for details.

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''http redirect to https''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' y
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. If set to "y", connections to the http port (specified by the key [[#midas http port|midas http port]] will be redirected to hte https port (specified by the key [[#midas https port|midas https port]], i.e. the listening port for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]).

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''midas server port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 1175
</div>

This key is created when [[mserver]] is started for the first time. It contains the default value of the port used by [[mserver]]. This is set to MIDAS_TCP_PORT = 1175 ( midas.h). A different port can be used by starting [[mserver]] with the -p argument.

;NOTE
: This key was added in May 2015 (see [[Security]]).

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

=== <span style="color: purple;">''Start-Stop Buttons''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' y
</div>
This key in the [[#top|/Experiment tree]] is added automatically by '''[[mhttpd]]''' to allow the user to suppress the Start or Stop buttons from appearing on the [[Status Page]]. By default, Start/Stop buttons are shown.

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

=== <span style="color: purple;">''Pause-Resume Buttons''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' n
</div>
This key in the [[#top|/Experiment tree]] is added automatically by '''[[mhttpd]]'''.
By default the Pause/Resume menu buttons do not appear on the [[Status Page]]. The user can allow these buttons
to appear during the run by setting this key to "y".

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

=== <span style="color: purple;">''Transition debug flag ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#top|/Experiment tree]] contains a flag that, if set to 1, causes messages reporting transition progress to be output.
<br>
--------
<br>

=== <span style="color: purple;">''Transition connect timeout''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 10000
</div>
This key in the [[#top|/Experiment tree]] contains the
value of timeout for remote rpc connect
<br>
--------
<br>

=== <span style="color: purple;">''Transition timeout''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 120000
</div>
This key in the [[#top|/Experiment tree]] contains the
value of timeout for transition
<br>
--------
<br>

=== <span style="color: purple;">''Prevent start on alarms''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
This key in the [[#top|/Experiment tree]] if set true
will prevent the run from starting if an [[Alarm System|alarm]] is true, i.e.
the run start procedure will fail if an alarm has been [[/Alarms ODB tree#Triggered|Triggered]] for a client, provided a valid [[/Alarms ODB tree#alarms class|alarms class]] has
been entered in the client's [[/Programs ODB tree#Alarm class|Alarm class]] key.

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

=== <span style="color: purple;">''Prevent start on required program''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
This key in the [[#top|/Experiment tree]] if set true ("y")
will prevent the run from starting if one of the '''required''' clients is not running. A client is flagged as "required" by setting the ODB key
[[/Programs ODB tree#Required|Required]] to "y".
<br>
--------
<br>

=== <span style="color: purple;">''Edit on Sequence ''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
This optional subdirectory in the [[#top|/Experiment tree]] may
contain user-defined parameters which will be displayed for editing at the start of each [[Sequencer|Sequence]]. See [[Edit-on-Sequence Parameters]] for details.

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

=== <span style="color: purple;">''Edit on Start ''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
This optional subdirectory in the [[#top|/Experiment tree]] may
contain user-defined parameters which will be displayed for editing at the beginning of each run. See '''[[Edit-on-start Parameters]]''' for details.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] contains user-defined links to ODB parameters to prevent them being changed when the run is in progress. See '''[[Lock when running]]''' for details.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] may contain user-defined parameter comments that give more information about
the '''[[Edit-on-start Parameters]]'''. See [[Edit-on-start Parameters#edit-on-start parameter comments|creating parameter comments]] for details.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] may contain user-defined parameters or parameter(s)
with reserved names (i.e. [[#Run Description|Run Description]]).

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

==== <span style="color: purple;">''Run Description''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This ODB key is used by the [[Sequencer]] [[Sequencer#RUNDESCRIPTION|RUNDESCRIPTION]] command to store the
run description.

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

==== <span style="color: purple;">''<parameter name>''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
The user may define parameters here e.g. for linking as '''[[Edit-on-start Parameters|Edit-on-start]]''' or '''[[Edit-on-Sequence Parameters|Edit-on-Sequence]]''' parameters.

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

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

This key in the [[#top|/Experiment tree]] is a subtree which by default contains a link to the [[#Name|experiment name]]. Any links or keys
created by the user in this optional subdirectory will be displayed on the [[mhttpd]] main status page.
<br>
--------
<br>

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

This optional subtree in the [[#top|/Experiment tree]] is created when the '''[[odbedit]]''' commands <span style="color:saddlebrown; font-style:bold; ">passwd</span> or <span style="color:saddlebrown; font-style:bold; ">webpasswd</span> are issued. It enables a user to set up security features. See '''[[Security]]'''.
<br>
--------
<br>

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

Setting the key to "n" (the default) causes access by unauthorized hosts to be prevented by the system checking the RPC access control list (see [[#RPC hosts subtree|RPC hosts/Allowed hosts]]).

If MIDAS clients have to connect from random hosts (i.e. dynamically assigned random DHCP addresses), one can disable the host name checks by
setting this key to "y". This configuration is insecure and should only be done on a private network behind a firewall. See [https://midas.triumf.ca/elog/Midas/1080 Note 1080].

; NOTE
: This key was added August 2015. Used by [[mserver]] to improve network [[Security]] for the MIDAS experiment.

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

==== <span style="color: purple;">''Enable non-localhost RPC''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
The default value of this key is "n", denying access by external network connections. If running an experiment that requires external network connections, this key must be set to "y" and the key [[#RPC hosts|RPC hosts]] must be filled. See [https://midas.triumf.ca/elog/Midas/1080 Note 1080].

; NOTE
: This key was added August 2015. Used by [[mserver]] to improve network [[Security]] for the MIDAS experiment.

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

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]'''). This subdirectory contains the names of MIDAS clients and their fixed TCP port numbers. When a client is started for the first time, an entry named for the client will be created in this subtree.
<br>
--------
<br>

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

When a MIDAS client is started, a key will be created named for that client. It will contain the fixed TCP port number that the MIDAS client is using.
Clients started on the local host will have TCP port numbers of 0 (default).

Once a remote [[Frontend Operation|frontend]] is bound to a fixed port, appropriate openings can be made in the firewall, etc. Default port number value
will be 0 meaning "use random port", same as now. See [https://midas.triumf.ca/elog/Midas/1079].

;NOTE
: This feature was added August 2015. It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

<div id="Allowed hosts (rpc hosts)"></div> 
===== <span style="color: purple;">''Allowed hosts''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING array
* '''Default:''' "localhost"
</div>
This key in the [[#RPC hosts subtree|/Experiment/Security/RPC hosts subtree]] is new as of August 2015 and is created by the system (i.e. midas.c).

It is part of the improved security features of MIDAS (See '''[[Security]]''') and is used to maintain a Network Access Control list.
The access control list array is self-growing - it will have at least 10 empty entries at the end at all times.

The default value for {{Odbpath|path=Allowed hosts[0]}} is "localhost", which will reject all external connections, even when permitted by [[#Enable external RPC connections|Enable external RPC connections]]. The user will be required to enter the names of all machines that will run midas clients in this array. See [https://midas.triumf.ca/elog/Midas/1090].

All clients' db_watch() routines watch the access control list and automatically reload it when it is changed, so there is no need to restart clients.

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

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

<div id="Allowed hosts (mhttpd hosts)"></div> 
===== <span style="color: purple;">''Allowed hosts''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING array
* '''Default:''' "localhost"
</div>
This key in the [[#RPC hosts subtree|/Experiment/Security/mhttpd hosts subtree]] is new as of August 2015 and is created by the system (i.e. midas.c).

It is part of the improved security features of MIDAS (See '''[[Security]]''') and is used to maintain an access control list for [[mhttpd]]. An empty list means free access from everywhere. Access control is also controlled by the [[mhttpd]] "-a" command line arguments. Hosts supplied by the "-a" command line arguments are not added to the access control list by the system.

The access control list is watched by {{Utility|name=mhttpd}}, therefore there is no need to restart it after updating the list.
<br>
--------
<br>

<div style="background-color:silver">
== <span style="font-size:120%;">The following keys in the /Experiment tree are OBSOLETE:</span> ==

=== <span style="color: purple;">''CSS File''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Status: OBSOLETE'''
* '''Default:''' "mhttpd.css"
</div>
This key in the [[#top|/Experiment tree]] contains the name of the [[Custom Page Features#MIDAS stylesheet|MIDAS stylesheet]] file for the use of those writing [[Custom Page|Custom Web Pages]].

;NOTE
: Serving resource file is now done differently. See [[Custom Page Features#MIDAS resource files|serving MIDAS resource file]]. Also mhttpd.css has be replaced by midas.css.
<br>
--------
<br>

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

</div>
This key in the [[#top|/Experiment tree]] contains the name of the [[mhttpd.js|Javascript library]] file for the use of those writing [[Custom Page|Custom Web Pages]].

;NOTE
: Serving resource file is now done differently. See [[Custom Page Features#MIDAS resource files|serving MIDAS resource files]].

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

=== <span style="color: purple;">''Menu Buttons''</span> ===
<div style="column-count:3;-moz-column-count:2;-webkit-column-count:2">
* '''Type:''' STRING
* '''Status: OBSOLETE'''
* '''Default:''' "Status, ODB, Messages, ELog, Alarms, Programs, History, Sequencer, Chat, Config, Help"
</div>
This key in the [[#top|/Experiment tree]]
is added automatically by '''[[mhttpd]]''' to allow the Menu buttons that appear on the '''[[mhttpd|Main Status Page]]''' to be customized by
removing unnecessary buttons or by changing their order.

The Start/Stop/Pause/Resume buttons are not now included in <span style="color: purple;">''Menu Buttons''</span>.
* To suppress/display the Start/Stop buttons use key [[#Start-Stop Buttons|Start-Stop Buttons]].
* To display/suppress the Pause/Resume buttons, use key [[#Pause-Resume Buttons|Pause-Resume Buttons]].

; Note
:If [[MSCB Page#MIDAS with MSCB support|MSCB support]] is built into MIDAS, the default will also include the MSCB Menu button (see [[MSCB Page]]).

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

=== <span style="color: purple;">''Mongoose listening_port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Status: OBSOLETE'''
* '''Default:''' "8080r,8443s"
</div>
<br>
:This key in the [[#top|/Experiment tree]] existed for a short time in midas versions May-August 2015.
: It has been '''replaced by the ODB keys [[#midas http port|midas http port]] and [[#midas https port|midas https port]].'''
<br>
<span style="font-size:80%">
This key in the [[#top|/Experiment tree]] was created when [[mhttpd]] was run for the first time. It contained the listening ports for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]). The ports are the HTTP port (default 8080) which is to be redirected to the secure HTTPS port (default 8443).
If ports were supplied with the "--mg" option when starting {{Utility|name=mhttpd}}, their values will overwrite the default values stored in this key. See [[mhttpd]] for details.
</span>
<br>
--------
<br>

=== <span style="color: purple;">''Mongoose access_control_list''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Status: OBSOLETE'''
* '''Default:''' ""
</div>
<br>
:This key in the [[#top|/Experiment tree]] existed for a short time in midas versions May-August 2015.
:'''Use the [[#mhttpd hosts subtree|mhttpd hosts/Allowed hosts]] access control list or the [[mhttpd]] "-a hostname" parameter to restrict access.'''
<br>
<span style="font-size:80%">
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the access control list (ACL) for the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server. By default, this key is empty and there is no access control. The format of the ACL is described under access_control_list at [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/Options.md?at=develop Mongoose Configuration Options].
</span>
<br>
--------
<br>

=== <span style="font-size:120%; font-style:bold">The following keys in the /Experiment/Security subdirectory are OBSOLETE - replaced by the [[Security|security features]] added Aug 2015</span> ===
==== <span style="color: purple;">''Password ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Status: OBSOLETE'''
* '''Default:'''
</div>

;Notes
<ol>
<li>This feature pre-dates the improved [[Security]] features (August 2015)</li>
<li> Do not set this key except through the {{Odbedit cmd|cmd=passwd}}. Setting an unencrypted password will lock you out of the ODB unless {{Utility|name=odbedit}} is listed in the [[#Allowed programs subtree|allowed programs subtree]].</li>
<li>This security feature is not proof against malicious access. See [[Security]] for details.</li>
</ol>

This optional key in the [[#Security|/Experiment/Security subtree]]
contains the encrypted password. This Key is created when the {{Odbedit cmd|cmd=passwd}} is issued. See [[Security#Restrict user access|Restrict user access]] for details.

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

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

;Notes
* This subtree pre-dates the improved [[Security]] features (August 2015) and is not to be confused with [[#RPC hosts subtree|RPC hosts/Allowed hosts]] array.
* This security feature is not proof against malicious access. See [[Security]] for details.

This subtree in the [[#Security|/Experiment/Security subtree]] is created when the {{Odbedit cmd|cmd=passwd}} is issued. When created, this subtree is empty.
Optionally, it may contain user-defined names of remote hosts allowed to have free access (i.e. without password) to the current experiment.

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

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

;Notes
* This subtree pre-dates the improved [[Security]] features (August 2015)
* This feature is not proof against malicious access. See [[Security]] for details.

This optional subtree in the [[#Security|/Experiment/Security subtree]] is created when the {{Odbedit cmd|cmd=passwd}} is issued. When created, this subtree is empty.
Optionally, it may contain user-defined names of clients allowed to have free access (i.e. without password) to the current experiment. See [[Security #Allowed programs]].

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

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

;Notes
* This key pre-dates (and has been superceded by) the improved [[Security]] features (August 2015)
* This feature is not proof against malicious access. See [[Security]] for details.

If [[Security#Restrict user access|restriction on user web access]] has been set up, this key in the [[#Security|/Experiment/Security subtree]]
will contain an encrypted password for Web server access. This key is created by using the {{Odbedit cmd|cmd=webpasswd}}.

If this key is present, the user will be requested to provide the "Web Password" when accessing the requested experiment in "Write Access" mode. The "Read Only Access" mode is still available (without a password) to all users.

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

</div> 
[[Category:ODB Tree]] [[Category:Experiment]] [[Category:Security]]

/Custom ODB tree

2019-05-28T23:40:13Z

Suz:

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[mhttpd |MIDAS web server (mhttpd)]]
* mhttpd [[Custom Page]]
* [[Custom Page Features]]
* mhttpd [[Status Page]]
* [[Mhttpd.js|MIDAS Javascript Library]]
</div>

= Purpose =
The {{Odbpath|path=/Custom}} ODB tree is required if the user wishes to create [[mhttpd]] custom pages. It contains essential data needed for [[mhttpd]] to display a custom page. The {{Odbpath|path=/images}} subtree is required if an imagefile (*.gif) is to be displayed on the custom page. Optionally, labels, bars and fills can be superimposed on the image.

= Creating the <span style="color:purple; font-style:italic;">/Custom</span> tree =
The {{Odbpath|path=/Custom}} ODB tree is an optional tree that may be [[ODB#Creating ODB keys|created by the user]].

<div id="Custom-Button"></div><div id="Custom-Link"></div>
= Keys in the /Custom tree =
The optional ODB {{Odbpath|path=/Custom}} tree may contain any of the following :

* keys pointing to '''local''' external files containing custom web pages (html/javascript files)
* keys pointing to '''local''' external files containing resources for custom web pages (e.g. .css style files, .js javascript file, images).
** Note: files that are have a '.' in the Key name are assumed to be resource files and are treated differently. See also the [[#Path key|Path key]] notes below.
** Note: .css, .js, .pdf, .jpg, .gif, .png, .svg, .ps, .eps, .xls, .doc, .txt, .asc, .zip files should get served up with the correct MIME types
* keys containing the html code for [[Internal Custom Page#How to create an Internal Custom Page|internal custom webpages]]
* <span style="color:purple; font-style:italic">Path</span> variable, used to indicate where to look on host machine for external files.
* <span style="color:purple; font-style:italic">/pwd</span> subtree used to contain custom password keys
* <span style="color:purple; font-style:italic">/images</span> subtree used to specify images for custom pages

Keys defined in this tree pointing to custom web pages of any kind are called '''''custom-links'''''.
* External ''custom-links'' contain the path and filename of the external custom page file (or may be a symbolic link to a custom-link)
* Internal ''custom-links'' contain the code for an [[Internal Custom Page]].

If ''custom-links'' are defined in this tree, except where [[#Key names|noted below]], the ''custom-links'' will appear as '''''custom-buttons''''' on the [[mhttpd]] [[Status Page]]. By clicking on one of these ''custom-buttons'', the custom page will be visible in a new frame (see also [[#Key names|Key names]]).

We will note some of the subtleties of how the Custom tree keys are used in the following sub-sections.

== Key names ==
The user chooses the names of any keys in the <span style="color:purple; font-style:italic;">/Custom</span> ODB tree except for
* the key name <span style="color:purple; font-style:italic">Status</span> is reserved (see [[Custom Page#Custom Status page|Custom Status Page]]).
* the key name <span style="color:purple; font-style:italic">pwd</span> is reserved (see optional [[#Pwd subtree|Pwd subtree]] for custom passwords)
* the key name <span style="color:purple; font-style:italic">Path</span> is reserved (see optional [[#Path key|Path key] for details)
* keys in the <span style="color:purple; font-style:italic">/images</span> subtree have defined names except for the user-defined [[#<Image-name> subtree|<Image-name> subtree]].

There are two characters that have '''special meaning''' if they are the last character of a ''custom-link'' in the {{Odbpath|path=/Custom}} tree :
* The character "'''&'''" forces the page to be opened within the current frame when the ''custom-button'' is pressed. If this character is omitted, the page will be opened in a new frame. The "&" character is omitted from the name of the button.
* The character "'''!'''" suppresses the ''custom-button'' from appearing on the [[Status Page]], forming a ''hidden-link''.

The ''hidden-link'' feature can be used to provide external webpages hidden from the user, such as a stylesheet or a file of Javascript functions needed by other custom pages.

The {{Odbpath|path=/Custom}} tree in the [[#Example|example]] below would produce one ''custom-button'', i.e.{{Button|name=ppg cycle}}.

;NOTE
: To avoid confusion, do not use custom-links that only differ by the special characters "&" and "!" (e.g. "test", "test&" and "test!") in the same ODB.

= Path key =

When creating custom external web pages you will usually want to use other resource files, like CSS style sheets or images.

One way to do that is to specify each of the files that you need to use in the {{Odbpath|path=/Custom}} tree. For instance, suppose you had a HTML file called {{File|name=control.html}} that used an image called {{File|name=valve.png}}. You could

Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Control STRING 1 256 1h 0 RWD /home/expt/online/custom/control.html
valve.png! STRING 1 256 1h 0 RWD /home/expt/online/custom/valve.png

You would then be able to refer to that png normally in your HTML

...
<img src="valve.png!">
...

This approach can get tedious however, if you have a large number of resource files to add.

An alternative is given by the {{Odbpath|path=Path}} ODB key. This key can be used to specify a directory on the server file system where files should be searched for. So, for instance, if the {{Odbpath|path=/Custom}} tree is set to

Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Path STRING 1 256 1h 0 RWD /home/expt/online/custom/
Control STRING 1 256 1h 0 RWD control.html

you can instruct {{Utility|name=mhttpd}} to look in the directory {{Filepath|path=/home/expt/online/custom/}} and then map the custom page 'Control' to
{{Filepath|path=/home/expt/online/custom/control.html}}.

One very important point: when the key {{Odbpath|path=/Custom/Path}} is defined, mhttpd will treat differently how it serves up resources, depending on whether there is a '.' in the resource web address. So, for instance, for the custom page described above

<pre>
https://myhost:8443/?cmd=custom&page=Control
or http://myhost:8081/CS/Control (very old MIDAS versions )
</pre>

you will need to have a ODB key called {{Odbpath|path=/Custom/Control}}, as described above.

However, if you have the ODB key {{Odbpath|path=/Custom/Path}} and you access content like
<pre>
https://myhost:8443/?cmd=custom&page=valve.png
or http://myhost:8081/CS/valve.png (very old MIDAS versions )
</pre>
then {{Utility|name=mhttpd}} will automatically figure out that it should use the file

Value of "/Custom/Path" + valve.png
i.e. /home/expt/online/custom/valve.png

So the benefit is that with the {{Odbpath|path=/Custom/Path}} key set, you can just place all your resource files in the directory pointed to by /Custom/Path and mhttpd will find them, '''without needing to specify them individually ''' {{Odbpath|path=/Custom}} as custom-links.

See also [[Custom Page Features#Resource files]] for more examples.

= Example =
The following example using the [[odbedit]] '''ls''' command shows the optional custom tree for an experiment.
<br>Note the use of the "&" and "!" characters in the names of the custom keys (see [[#Key names|key names]] for details).
[local:pol:S]/ls -lr /Custom
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
custom DIR
ppg_cycle& STRING 1 80 36h 0 RWD /home/pol/online/pol/custom/pol_sc.html
pol_functions! STRING 1 80 36h 0 RWD /home/pol/online/pol/custom/pol_functions.js
style! STRING 1 80 36h 0 RWD /home/pol/online/pol/custom/style.css
images DIR
pol_sc.gif DIR
background STRING 1 80 36h 0 RWD /home/pol/online/pol/custom/pol_sc.gif
labels DIR
num bins DIR
Src STRING 1 256 36h 0 RWD /Equipment/pol_acq/settings/output/num bins per cycle
Format STRING 1 32 36h 0 RWD %d
Font STRING 1 32 36h 0 RWD Medium
X INT 1 4 36h 0 RWD 315
Y INT 1 4 36h 0 RWD 502
Align INT 1 4 36h 0 RWD 0
FGColor STRING 1 8 36h 0 RWD FFFFFF
BGColor STRING 1 8 36h 0 RWD 0000FF
dwell time DIR
Src STRING 1 256 36h 0 RWD /Equipment/POL_ACQ/Settings/input/dwell time (ms)
Format STRING 1 32 36h 0 RWD %f ms
Font STRING 1 32 36h 0 RWD large
X INT 1 4 36h 0 RWD 145
Y INT 1 4 36h 0 RWD 430
Align INT 1 4 36h 0 RWD 0
FGColor STRING 1 8 36h 0 RWD FFFFFF
BGColor STRING 1 8 36h 0 RWD 0000FF
fills DIR
SSLevelBox DIR
Src STRING 1 256 36h 0 RWD /Equipment/TpcGasPlc/GasCalc/Calculated[136]
X INT 1 4 36h 0 RWD 578
Y INT 1 4 36h 0 RWD 490
Limits DOUBLE 3 8 2s 0 RWD
[0] 0
[1] 1
[2] 2
Fillcolors STRING 4 8 2s 0 RWD
[0] 000000
[1] 00FF00
[2] 808080
bars DIR
temp DIR
Src STRING 1 256 36h 0 RWD /Equipment/Temperature/Variables/Readback[5]
X INT 1 4 36h 0 RWD 42
Y INT 1 4 36h 0 RWD 68
Width INT 1 4 36h 0 RWD 10
Height INT 1 4 36h 0 RWD 50
Direction INT 1 4 36h 0 RWD 0
Axis INT 1 4 36h 0 RWD 1
Logscale BOOL 1 4 >99d 0 RWD n
Min DOUBLE 1 8 >99d 0 RWD 0
Max DOUBLE 1 8 >99d 0 RWD 0
FGcolor STRING 1 8 2s 0 RWD 000000
BGcolor STRING 1 8 2s 0 RWD FFFFFF
BDcolor STRING 1 8 2s 0 RWD 808080

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

This optional subtree in the [[#top|/Custom ODB tree]] is created by the user if [[Custom Page]] write access is to be [[Custom Page Features#Password protection of ODB variables|password protected]].

== <span style="color:purple; font-style:italic"><password></span> ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' ""
</div>
The '''name''' of the optional key(s) in the <span style="color:purple; font-style:italic">/Pwd</span> subtree defines a password that the user must specify to gain access to a [[Custom Page Features#Password protection of ODB variables|password-protected]]
item on a [[Custom Page]].

=== Password examples ===
If the password is ''CustomPwd'', the ODB key <span style="color:purple; font-style:italic">/Custom/Pwd/CustomPwd</span> would be defined.

By using an explicit name, one can use a single password for all controls on a page, or one could use several passwords on the same page. For example, a shift crew password for the less severe controls could be defined as ''ShiftPwd'', and an "expert" password ''ExpertPwd'' for the critical things.

In this case, the ODB would have two passwords defined, i.e.
<span style="color:purple; font-style:italic">/Custom/Pwd/ExpertPwd</span>
<span style="color:purple; font-style:italic">/Custom/Pwd/ShiftPwd</span>

The password is of course not secure in the sense that it is placed in plain text into the ODB, but its purpose is to prevent accidental modification, rather than malicious interference.

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

This optional subtree in the [[#top|/Custom ODB tree]] is created by the user. It is required if an imagefile (*.gif) is to be displayed on a custom page.
This subtree is also required for any '''labels, bars''' or '''fills''' to be superimposed on the image.

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

== <span style="color:purple; font-style:italic"><Image-name></span> subtree ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
* '''Default:'''
</div>
User-created subdirectory usually named for the corresponding gif-image, e.g. "pol_sc.gif" in the [[#Example|example]] above. For multiple images, multiple subdirectories may be defined. The user
chooses the name of this key.

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

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

This key in the [[#<Image-name> subtree|<image-name> subtree]] contains the path and filename of the image file to be loaded into a custom page. Only '''gif''' format is supported for the image. This optional key is created by the user.

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

=== <span style="color:purple; font-style:italic">Labels</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
* '''Default:'''
</div>
User-created subdirectory in the [[#<Image-name> subtree|<image-name> subtree]] required if '''labels''' are to be superimposed on an image on a custom page.

<br>
---------
<br>
==== <span style="color:purple; font-style:italic"><label-name></span> subtree ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
* '''Default:'''
</div>
User-created subdirectory in the [[#Labels subtree|Labels subtree]] containing keys to define this label as listed below. There will be a <span style="color:purple; font-style:italic"><label-name></span> subtree for each label superimposed on the custom image.

The user creates keys in this subtree with the names and types as listed below. See also the [[#Example|example]] above.
<br>
---------
<br>

<div id="Labels Src"></div>
===== <span style="color:purple; font-style:italic">Src</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING [256]
* '''Default:'''
</div>
This key in the [[#<label-name>subtree|<label-name> subtree]] contains the path of a valid ODB Key variable. This is the value to be used for this label on an image.

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

===== <span style="color:purple; font-style:italic">Format</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING [32]
* '''Default:''' "%1.1f"
</div>
This key in the [[#<label-name>subtree|<label-name> subtree]] contains the format for this label on the image. Format specifications (c.f. "printf" in C) are used to convert the value specified by the [[#Labels Src|Src key]] into the output string that appears on the image.
For example,
* "Count Rate:%5d kB/s" used to display an integer value
* "%5.2f%% iBu" used to display a floating point value. Note "%%" displays the "%" sign.

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

===== <span style="color:purple; font-style:italic">Font</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING[32]
* '''Default:''' "Medium"
</div>
This key in the [[#<label-name>subtree|<label-name> subtree]] contains the font size for this label. Supported values are "small", "medium" or "giant".

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

<div id="Labels X"></div>
===== <span style="color:purple; font-style:italic">X</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#<label-name>subtree|<label-name> subtree]] contains the X position for this label in pixels.

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

<div id="Labels Y"></div>
===== <span style="color:purple; font-style:italic">Y</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#<label-name>subtree|<label-name> subtree]] contains the Y position for this label in pixels.

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

===== <span style="color:purple; font-style:italic">Align</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#<label-name>subtree|<label-name> subtree]] contains an integer representing Horizontal Alignment for this label. Set to one of 0 (left), 1 (center) or 2 (right).

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

<div id="Labels FGColor"></div>
===== <span style="color:purple; font-style:italic">FGColor</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING [8]
* '''Default:''' "000000"
</div>
This key in the [[#<label-name>subtree|<label-name> subtree]] contains the foreground colour for this label in the format RRGGBB (hex). See [[#Colour table|colour table]].

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

<div id="Labels BGColor"></div>
===== <span style="color:purple; font-style:italic">BGColor</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING [8]
* '''Default:''' "FFFFFF"
</div>
This key in the [[#<label-name>subtree|<label-name> subtree]] contains the background colour for this label in the format RRGGBB (hex). See [[#Colour table|colour table]].

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

=== <span style="color:purple; font-style:italic">Bars</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
* '''Default:'''
</div>
User-created subdirectory in the [[#<Image-name> subtree|<image-name> subtree]] required if '''bars''' are to be superimposed on an image on a custom page.

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

==== <span style="color:purple; font-style:italic"><bar-name></span> subtree ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
* '''Default:'''
</div>
User-created subdirectory in the [[#Bars subtree|Fills subtree]] containing keys to define this '''bar''' as listed below. There will be a <span style="color:purple; font-style:italic"><bar-name></span> subtree for each bar superimposed on the custom image.

The user creates keys in this subtree with the names and types as listed below. See also the [[#Example|example]] above.
<br>
---------
<br>

<div id="Bars Src"></div>
===== <span style="color:purple; font-style:italic">Src</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING [256]
* '''Default:'''
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the path of a valid ODB Key variable. This is the value to be used for this bar.

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

<div id="Bars X"></div>
===== <span style="color:purple; font-style:italic">X</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the X position for this bar in pixels.

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

<div id="Bars Y"></div>
===== <span style="color:purple; font-style:italic">Y</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the Y position for this bar in pixels.

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

===== <span style="color:purple; font-style:italic">Width</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 10
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the width of this bar in pixels.

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

===== <span style="color:purple; font-style:italic">Height</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 100
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the height of this bar in pixels.

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

===== <span style="color:purple; font-style:italic">Direction</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains an integer denoting the direction of this bar. It can be either 0 (vertical) or 1 (horizontal).

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

===== <span style="color:purple; font-style:italic">Axis</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 1
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains an integer specifying the axis of this bar. It can be either 0 (none), 1 (left) or 2 (right).

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

===== <span style="color:purple; font-style:italic">Logscale</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] specifies whether the axis of this bar is logarithmic. Set to "y" for logarithmic, otherwise "n".

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

===== <span style="color:purple; font-style:italic">Min</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
* '''Default:''' 0
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the minimum value for the axis of the bar.

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

===== <span style="color:purple; font-style:italic">Max</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
* '''Default:''' 10
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the maximum value for the axis of the bar.

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

<div id="Bars FGColor"></div>
===== <span style="color:purple; font-style:italic">FGColor</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING [8]
* '''Default:''' "000000"
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the foreground colour for this bar in the format RRGGBB (hex). See [[#Colour table|colour table]].

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

<div id="Bars BGColor"></div>
===== <span style="color:purple; font-style:italic">BGColor</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING [8]
* '''Default:''' "FFFFFF"
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the background colour for this bar in the format RRGGBB (hex). See [[#Colour table|colour table]].

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

===== <span style="color:purple; font-style:italic">BDColor</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING [8]
* '''Default:''' "808080"
</div>
This key in the [[#<bar-name>subtree|<bar-name> subtree]] contains the border colour for this bar in the format RRGGBB (hex). See [[#Colour table|colour table]].

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

=== <span style="color:purple; font-style:italic">Fills</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
* '''Default:'''
</div>
User-created subdirectory in the [[#<Image-name> subtree|<image-name> subtree]] required if '''fills''' are to be superimposed on an image on a custom page.
A "fill" can change the colour of a region on the image. The contents of the ODB key defined in [[#Fills Src|Src]] determines the colour as defined by the Limits and Fillcolors arrays.

<br>
---------
<br>
==== <span style="color:purple; font-style:italic"><fill-name></span> subtree ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
* '''Default:'''
</div>
User-created subdirectory in the [[#Fills subtree|Fills subtree]] containing keys to define this fill as listed below. There will be a <span style="color:purple; font-style:italic"><fill-name></span> subtree for each fill superimposed on the custom image.

The user creates keys in this subtree with the names and types as listed below. See also the [[#Example|example]] above.
<br>
---------
<br>

<div id="Fills Src"></div>
===== <span style="color:purple; font-style:italic">Src</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This key in the [[#<fill-name>subtree|<fill-name> subtree]] contains the path of a valid ODB Key variable. Unless a [[#logic_calculation|logic calculation]] is included, the contents of this key determines the value used for the fill
on the image defined by the key [[#Background|Background]] (see fill-name "SSLevelBox" in the [[#Example|example]] above).
<div id="logic_calculation"></div>
If a '''logic calculation''' is included, up to two operators are permitted, and they must be either
;
: ">>" (shift to the right) or
: "&" (bitwise AND).

A hexadecimal number preceded by "0x" is also supported.
This feature enables a SRC key that is actually a bit pattern to be used for a fill.

In the following example, a gas valve is open if bit 14 of PLCR[136] is TRUE and closed if bit 15 is TRUE (bits are from 0-15). The contents of PLCR[136] are shifted to the right by 14 and then a logical AND is performed to clear all but the lowest 2 bits. The result is used to colour the valve body lime green if the valve is open, and black if it is closed. If neither bit is set (i.e. the valve is neither open nor closed) the valve body is coloured red to indicate an error. Anything else (i.e. both bits TRUE) will give a gray colour.

[local:t2kgas:S]/>ls /custom/images/Pump_20.gif/fills/d2vb3
Src /Equipment/TpcGasPlc/Variables/PLCR[136] >> 14 & 0x3
X 905
Y 536
limits
0
1
2
3
Fillcolors
808080
00FF00
000000
808080

Any fill that requires a more complicated calculation than this will have to be done using Javascript in the custom page. The calculated value can then be stored in an ODB key, which is then defined as a Fill [[#Fills Src|Src]] key.

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

<div id="Fills X"></div>
===== <span style="color:purple; font-style:italic">X</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:'''
</div>
This key in the [[#<fill-name>subtree|<fill-name> subtree]] contains the X position for this fill in pixels.

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

<div id="Fills Y"></div>
===== <span style="color:purple; font-style:italic">Y</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:'''
</div>
This key in the [[#<fill-name>subtree|<fill-name> subtree]] contains the Y position for this fill in pixels.

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

===== <span style="color:purple; font-style:italic">Limits</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT array
* '''Default:'''
</div>
This key in the [[#<fill-name>subtree|<fill-name> subtree]] is a variable-length array containing the values of the limits that when reached cause a colour change. Array length must match length of array <span style="color:purple; font-style:italic">Fillcolors</span>.

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

===== <span style="color:purple; font-style:italic">Fillcolors</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT array
* '''Default:'''
</div>
This key in the [[#<fill-name>subtree|<fill-name> subtree]] is a variable-length array containing the colours corresponding to the [[#Limits|Limits]] array. The colours are defined in the format RRGGBB (hex). See [[#Colour table|colour table]]. Array length must match length of <span style="color:purple; font-style:italic">Limits</span> array.

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

= Colour Table =
For convenience, a colour reference table is shown here for some common colours:
{| class="wikitable" style="margin: auto; ext-align: left; width: 25%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 255); font-weight: bold;" | Colour
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(204, 204, 255); font-weight: bold;" | RGB Value

|-
| colspan="1" rowspan="1" style="vertical-align: top; color: black; font-weight: normal;" | Black
| colspan="1" rowspan="1" style="vertical-align: top; color: black; font-weight: normal;" | 000000

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: silver; color: white; font-weight: normal;" | White
| colspan="1" rowspan="1" style="vertical-align: top; background-color: silver; color: white; font-weight: normal;" | FFFFFF

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: white; color: red; font-weight: normal;" | Red
| colspan="1" rowspan="1" style="vertical-align: top; color: black; font-weight: normal;" | FF0000

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: silver; color: lime; font-weight: normal;" | Lime green
| colspan="1" rowspan="1" style="vertical-align: top; background-color: silver; color: lime; font-weight: normal;" | 00FF00

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: white; color: blue; font-weight: normal;" | Blue
| colspan="1" rowspan="1" style="vertical-align: top; color: black; font-weight: normal;" | 0000FF

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: silver; color: yellow; font-weight: normal;" | Yellow
| colspan="1" rowspan="1" style="vertical-align: top; background-color: silver; color: yellow; font-weight: normal;" | FFFF00

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: white; color: grey; font-weight: normal;" | Grey
| colspan="1" rowspan="1" style="vertical-align: top; color: black; font-weight: normal;" | 808080

|}

[[Category:ODB Tree]] [[Category:Custom]]

Custom Page Features

2019-05-28T23:25:19Z

Suz:

{{Pagelinks}}
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Mhttpd|mhttpd MIDAS web server]]
* [[ODB Page]]
* [[Custom Page]]
* [[/Custom ODB tree]]
* [[Mhttpd.js|MIDAS Javascript library (mhttpd.js)]]
* [[mjsonrpc|MIDAS JSON RPC library functions (mjsonrpc)]]
* [[odbedit]]
</div>

= Introduction =
;NOTE
: Since 2018, many of the features described here can now be implemented more simply using the mod* JS functions (see [[Custom Page|Custom Web Page]]).
: '''If writing a new web page, it is strongly recommended you make use of the mod*JS features. '''

This page describes some of the special features provided for use on a user-created [[Custom Page|Custom Web Page]] using the [[#The MIDAS Javascript Library]], which was the recommended way to write Custom Pages before the [[Custom Page#modb* Javascript scheme]] was available.

<br><br>

= The MIDAS Javascript Library =
The MIDAS Javascript Library [[mhttpd.js]] includes routines written in Javascript and AJAX to provide features useful for writers of [[Custom Page]]s, such as access to the ODB. Recently asynchronous [[mjsonrpc|JSON-RPC functions]] using [[mjsonrpc#Javascript client library|Promises]] has been added (January 2016).
;NOTE
:To use functions in this library, it '''must be [[mhttpd.js#include js lib|included in the HTML code]]'''.

Many of the older routines (ODBGet, ODBSet) use '''synchronous''' RPC requests. With synchronous request, a second RPC request must wait until the first request is complete. This can significantly slow down web pages where many calls to ODBGet are made. For this reason, functions were developed that can be synchronous or '''asynchronous''' (e.g. ODBMCopy) that include a callback mechanism. The data from ODBMCopy can be formatted in [[mjsonrpc#JSON general information|JSON]].

Web developers are moving away from synchronous RPC requests, which are now deprecated [https://midas.triumf.ca/elog/Midas/1128]. Some modern browsers return a warning on a synchronous RPC request.

A new group of JSON-RPC functions using [[mjsonrpc#Javascript client library|Promises]] has been added to the MIDAS Javascript Library (January 2016). These are asynchronous only, and they also provide more functionality and have better error handling than the older AJAX calls, which are also inconsistent in how they handle Booleans. They also have much improved handling of reading/writing arrays to the ODB. Before 2018 it was recommended that all new Custom Pages are written using these JSON-RPC functions. {{Important|text=Since 2018 the [[Custom Page#modb* Javascript scheme]] is recommended for new Custom Pages}}.

The MIDAS Javascript Library routines requires an up-to-date browser that supports Promises (see [https://midas.triumf.ca/elog/Midas/1145]). If using an older browser version, the asynchronous AJAX calls (e.g. ODBMCopy) should be used in order to avoid having to rewrite the web page at a later date to remove all synchronous calls.

<br><br>
== Access the ODB using mjson-rpc asynchronous functions ==

Access to the ODB is provided by the [[Mhttpd.js|MIDAS Javascript Library]], which (since January 2016) includes the [[mjsonrpc]] functions. It is [[#The MIDAS Javascript Library|recommended]] that these functions are used for '''new''' pages rather than the older AJAX calls (see below).

To run these functions you need
# to [[mhttpd.js#include js lib|include the Javascript library in the HTML code]]'''
# to use an up-to-date browser that supports Promises (see [https://midas.triumf.ca/elog/Midas/1145]).

Examples showing how to read and write to the ODB can be found at [[mjsonrpc#examples]]. Also included are examples using arrays.

<br><br>
== Access the ODB using asynchronous AJAX calls ==
;NOTE
: It is recommended that asynchronous MIDAS JSON-RPC functions are used for new pages rather than the older AJAX calls (see [[#Access the ODB using mjson-rpc asynchronous functions|above]]).

[[#Example 2 : Asynchronous calls using Javascript and AJAX|Example 2]] uses the asynchronous call ODBMCopy() with callback to read the data. The data are converted into JSON format. In this case, when accessing the JSON data, ''the ODB Keynames must be in the same case as they are in the ODB'', even though the case is ignored by the ODB. If you find this feature annoying, use [[#Access the ODB using mjson-rpc asynchronous functions|mjson-rpc function db_get_values()]] as all keynames are converted to lower case.

<br><br>
== Access the ODB using synchronous AJAX requests ==
;NOTE
: Synchronous requests are now deprecated (see [[#The MIDAS Javascript Library|above]]). New pages should be written [[#Using mjson-rpc asynchronous functions]].

See [[#Example 3 : Synchronous Calls using Javascript and AJAX]].

<br><br>
= Access the ODB with HTML-style <span style="color:seagreen font-style:italic"><odb></span> tags =

;NOTE
: This method pre-dates the [[Mhttpd.js|MIDAS Javascript Library]]. It is recommended that the [[Mhttpd.js|MIDAS Javascript Library]] be used for ODB access.

If Javascript (JS) is not available, the older HTML-style {{HtmlTag|tag=<odb>}} tags are still available and provide limited functionality.

The HTML-style {{HtmlTag|tag=<odb>}} tag has been defined for read/write access to the ODB under HTML. The {{HtmlTag|tag=<odb>}} tags are declared within enclosing HTML {{HtmlTag|tag=<form...>....</form>}} tags.

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"
|+ Access to ODB from HTML
|-
| colspan="1" rowspan="1" style="text-align: center; vertical-align: top; background-color: rgb(204, 204, 255); font-weight: bold;" | HTML ODB tag
| colspan="1" rowspan="1" style="text-align: center; vertical-align: top; background-color: rgb(204, 204, 255); font-weight: bold;" | Meaning

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path">
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: black" |Display ODB field (read only)

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path" edit=1 pwd="CustomPwd">
| Display an Editable ODB field (inline style). Optional password protection with '''pwd''' .

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path" edit=2 pwd="CustomPwd">
| Display an Editable ODB field (popup style). Optional password protection with '''pwd''' .
|}

;NOTE
: The Optional password protection with '''pwd''' (documented in the [http://ladd00.triumf.ca/~daqweb/doc/midas-old/html/RC_customize_ODB.html#RC_Access_Control| OldMidas Document]) may not be working.
: Use the [[/Experiment ODB tree#Security subtree|Web Password security]] instead.

{{HtmlTag|tag=<odb>}} tags are included in the HTML code e.g.

{{Html|text= Experiment Name: <odb src="/Experiment/Name"> <br> Run Number: <odb src="/runinfo/run number" edit=1>}}

See also [[Custom Page#How to write a Custom Page|HTML Custom Page example]].

<br><br>
= ODB RPC access =
The [[Mhttpd.js|MIDAS Javascript Library]] function ODBRpc() defined for RPC access.

This permits buttons on MIDAS "custom" web pages to invoke RPC calls directly into user frontend programs, for example to turn hardware modules on or off.

<br><br>
= JSON support =
[[mjsonrpc#JSON general information|JSON]] support is provided with the [[Mhttpd.js|MIDAS Javascript Library]].

<br><br>
= Access to the MIDAS Menu buttons =

;NOTE
: '''New (since 2018) custom pages using the [[Custom Page#modb* Javascript scheme]] should follow the instructions there to include the standard MIDAS Menu buttons.'''
<br><br>
Access to the standard MIDAS Menu buttons can be provided with HTML {{HtmlTag|tag=<input...>}} tags of the form:


{{Html|text=<input name="cmd" value=''<button-name>'' type="submit" >}}
Valid values are the standard MIDAS Menu buttons, i.e. (Start, Pause, Resume, Stop, ODB, Elog, Alarms, History, Programs etc). The {{HtmlTag|tag=<input...>}} tags must be declared within enclosing HTML {{HtmlTag|tag=<form...>....</form>}} tags (see above).

The following HTML fragment shows the inclusion of three of the standard buttons, giving access to the Main Status, ODB and Messages pages :

{{Html|text= <form name="form1" method="Get" action="/CS/MyExpt&"> <br> <input name="cmd" value="Status" type="submit"> <br> <input name="cmd" value="ODB" type="submit"> <br> <input name="cmd" value="Messages" type="submit"> <br> ... <br> </form> }}

See also [[#Redirect]].

<br><br>
= Redirect =

When buttons are included on a Custom Page, after pressing a button (e.g. the Start or Stop button) it may be desirable to return to the same custom page, rather than returning to the [[Status Page]].

This can be done by including an HTML {{HtmlTag|tag=<input...>}} tag with the attributes ''type'' set to "hidden" and ''name'' set to "redir". This name ("redir") is detected by [[Mhttpd]], causing a redirect to the specified custom link in the ''value'' attribute.

For example, the following redirects the screen back to the custom page link {{Odbpath|path=/Custom/my_custom_page&}} when buttons are pressed:
{{Html|text=<input type=hidden name="redir" value="my_custom_page&">}}

See also [[#Replace Status Page by a Custom page|Redirect when a Custom Page replaces the Status Page]].
<br><br>

= CustomScript Buttons =

[[/Customscript ODB tree#Customscript-button|CustomScript buttons]] can be provided on [[Custom Page|Custom Pages]]. These buttons are equivalent to optional '''script buttons''' on the [[Status Page]], which call a script to perform a particular action when the button is pressed. See [[/Script ODB tree#Script-button|script buttons]] for details. Customscript buttons can be set up through the [[/Customscript ODB tree]].

Any key <span style="color:purple; font-style:italic">/CustomScript/test</span> will appear as a customscript-button
<span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">test</span> on a custom page whose code includes an HTML {{HtmlTag|tag=<input...>}} tag of the form:
{{Html|text=<input type=submit name=customscript value="test">}}
where the action of the button <span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">test</span> will be found in the <span style="color:purple; font-style:italic">/customscript/test</span> subdirectory.

After pressing a customscript-button, the ''type=submit'' in the HTML {{HtmlTag|tag=<input>}} will cause a page reload. This will result in a switch to the [[Status Page]], unless a [[#redirect]] input tag is included to redirect back to the original custom page.

== Customscript button without a page reload ==
To define a customscript button that does '''not''' cause a page reload, set the ''type'' in the HTML {{HtmlTag|tag=<input>}} to "button", i.e.
{{Html|text=<input name="customscript" value="test" type="button" onClick=cs_button(this.value)> }}
and use ''"onClick"'' to call a function to [[#Send an Ajax Request]] instead. The following function sends an asynchronous request, with an optional callback.
{{HtmlTag|tag=<script>}}
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
function cs_button(cmd, callback)<br>
{ // send a request to execute a custom script
: var url;
: var request = XMLHttpRequestGeneric();
:
: url = ODBUrlBase
: if(document.getElementById("redir") != null)
:: url += '?redir='+document.getElementById('redir').value
: url+='&customscript='+ encodeURIComponent(cmd);
: request.open('GET', url, true); // asynchronous request
: request.send(null);
: if(callback!=undefined) {
:: request.onreadystatechange = function() {
::: if (request.readyState == 4) {
:::: if (request.status == 200)
::::: callback();
:::: else
::::: alert('cs_button: Error after sending request to Custom Script "'+cmd+'" :\nHTTP Status: '+request.status)
::: }
:: }
: }
: else {
:: if (request.status != 200)
::: alert('cs_button: Error after sending request to Custom Script "'+cmd+'" :\nHTTP Status: '+request.status)
: }
}
</div>
{{HtmlTag|tag=</script>}}

<br><br>
= Resource files =
== MIDAS resource files ==
A number of resource files have been provided in the MIDAS packages under {{Filepath|path=../packages/midas/resources}}. When including a MIDAS resource file, no key in {{Odbpath|path=/Custom}} needs to be defined as the MIDAS resources directory is searched automatically.

One such resource file is a condensed stylesheet {{File|name=midas.css}} for users who would like their custom pages to have a similar "look and feel" to that of the standard pages. To include the MIDAS stylesheet, in the HTML header, add
{{HtmlTag|tag=<link rel="stylesheet" type="text/css" href="midas.css">}}
Other resource files can provide [[Custom Page#How to use the standard MIDAS navigation bars on your custom page|the standard MIDAS navigation bars]].

== Custom resource files ==
It is often desirable to serve resource files (i.e. '''local files''' such as an external stylesheet, javascript files or images'''<sup>***</sup>''') to a custom page. The following sections describe two alternative ways of serving resource files to a custom page:
* [[#Resource files served WITH /custom/path key defined|with /custom/path key defined]]
* [[#Resource files served WITHOUT /custom/path key defined|without /custom/path key defined]]
See also serving resources to a [[#Replace Status Page by a Custom Status page|Custom Status page]].
;NOTE
: '''<sup>***</sup>''' To superimpose labels, bars or fills onto an image, the image cannot be served as a resource file. See [[#Image insertion]].

=== Resource files served WITH <span style="color: purple; font-style:italic;">/custom/path</span> key defined ===
When a number of resource files are required, it is convenient to place them in the same directory on the disk, and create a key {{Odbpath|path=/Custom/Path}} to contain this directory.

$ ls /home/midas/online/custom/
custom_functions.js custom_globals.js custom_page.html custom_stylesheet.css test_image.png
With the {{Odbpath|path=/Custom/Path}} key defined, [[/Custom ODB tree#Custom-Link|custom-links]] for individual resource files need not be created in the {{Odbpath|path=/Custom/Path}} tree. The custom-link {{Odbpath|path=custom_page&}} '''is''' required so that the custom page can be accessed from the [[/Custom ODB tree#Custom-Button|custom-button]] {{Button|name=custom_page}} on the Status Page. The key name ends in the special character "&" so that it will open in the same window as the Status page (see [[/Custom ODB tree#Key names|key names]]).
$ odbedit
[local:exp:S] ls /custom
path /home/midas/online/custom/
custom_page& custom_page.html

A {{HtmlTag|tag=<script>}} tag for each resource file to be served (specifying the file name) is then placed in the header of {{File|name=custom_page.html}}
i.e.
{{Html|text=<script type="text/javascript" src="custom_functions.js"></script>}}
{{Html|text=<script type="text/javascript" src="custom_globals.js"></script>}}
<br> and a {{HtmlTag|tag=<link>}} tag for an external stylesheet
{{Html|text=<link type="text/css" rel="stylesheet" href="custom_stylesheet.css" title="Stylesheet">}}
An image tag is placed in the body of {{File|name=custom_page.html}}
{{Html|text=<img src="test_image.png"> }}
[[mhttpd]] then loads the resource file from the directory indicated by the Path key with the correct MIME type (see [[/Custom ODB tree#Keys in the /Custom tree|Custom tree keys]] for supported MIME types).

=== Resource files served WITHOUT <span style="color: purple; font-style:italic;">/custom/path</span> key defined ===
Alternatively, resource files can be served to a [[Custom Page]] by creating a key for every resource file in the [[/Custom ODB tree]]. These keys must contain the full path of the file on the disk, and the key {{Odbpath|path=/Custom/Path}} must NOT be defined. The resource files can be in different directories on the disk. By defining the key names with an appropriate file extension, the resource files are served with the appropriate MIME types. The key names end in the special character "!" so that they will not appear on the Status page as custom-links (see [[/Custom ODB tree#Key names|key names]].

Without the {{Odbpath|path=/Custom/Path}} key, the links for the above example in the {{Odbpath|path=/Custom}} tree might look like
$ odbedit
[local:exp:S] ls /custom
custom_page& /home/midas/online/custom/custom_page.html
custom_functions.js! /home/midas/online/resources/custom_functions.js
globals.js! /home/midas/online/resources/custom_functions.js
stylesheet.css! /home/midas/online/stylesheets/custom_stylesheet.css
image.png! /home/midas/images/test_image.png

assuming the resource files are now in the subdirectories indicated.
The {{HtmlTag|tag=<script>}} tag for each resource file to be served (specifying the custom-link) is then placed in the header of {{File|name=custom_page.html}}
i.e.
{{Html|text=<script type="text/javascript" src="custom_functions.js!"></script>}}
{{Html|text=<script type="text/javascript" src="globals.js!"></script>}}
<br> and a {{HtmlTag|tag=<link>}} tag for an external stylesheet
{{Html|text=<link type="text/css" rel="stylesheet" href="stylesheet.css!" title="Stylesheet">}}
An image tag is placed in the body of {{File|name=custom_page.html}}
{{Html|text=<img src="image.png!"> }}

<br><br>

The resulting Demo custom page is shown in Figure 1, which can be compared with Figure 2 (no stylesheet).
{| class="wikitable"
|-
! Figure 1 !! Figure 2
|-
| Demo Custom Page using MIDAS stylesheet || Demo Custom Page
|-

| [[File:Mhxcustom03.jpg|thumb|300px]] || [[File:Mhxcustom02.jpg|thumb|200px]]
|}
<br clear=all>

<br><br>
= Alias-Buttons and Hyperlinks =
Any hyperlink can easily be included on a [[Custom Page]] by using the standard HTML anchor {{HtmlTag|tag=<a...>}} tag, e.g.
{{Html|text=<a href="http://ladd00.triumf.ca/~daqweb/doc/midas/html/">Midas Help</a>}}

Links on a custom page equivalent to [[/Alias ODB tree#Alias-Buttons|alias-buttons]] can also be made e.g.
{{Html|text=<button type="button" onclick="document.location.href='/Alias/alias&';">alias</button>}}
See the [[/Alias ODB tree]] for details.

<br><br>
= Page refresh =
The following {{HtmlTag|tag=<meta...>}} tag included in the HTML header code will cause the whole custom page to refresh in 60 seconds :
{{Html|text=<meta http-equiv="Refresh" content="60">}}
It is also possible to [[#Periodic update of parts of a custom page|periodically update parts]] of a custom page.

<br><br>
= Periodic update of parts of a custom page =

The functionality of [[Mhttpd.js|ODBGet]] together with the window.setInterval() function
can be used to update parts of the web page periodically.
For example the Javascript fragment below contains a function which updates the current run number every 10 seconds in the background:

<div style="background-color:floralwhite; color:steelblue; font-style:italic"> 
window.setInterval("Refresh()", 10000);<br>
function Refresh() {<br>
:document.getElementById("run_number").innerHTML = ODBGet('/Runinfo/Run number');<br>
}
</div>
The custom page has to
* [[Mhttpd.js#include js lib|include the MIDAS JS library]] to access ODBGet
* contain an element with id="run_number", such as
{{Html|text=<td id="run_number"></td>}}

<br><br>
= Display last MIDAS message(s) =

The message log (see [[Message System]]) can be accessed from a custom page using a call to the JavaScript library function [[Mhttpd.js|ODBGetMsg]] (provided the [[Mhttpd.js#include js lib|JS library is included]]).

This allows the inclusion of the "Last Midas message" on a custom page, e.g.
{{JS|text=document.write('Last message:'+ODBGetMsg("midas",0,1))}}
More messages may be displayed by increasing the third parameter to ODBGetMsg.
;Note
: Parameters were changed August 2015. See [[Mhttpd.js|ODBGetMsg]] for older versions.
: Coming soon - a [[mjsonrpc]] function

<br><br>
= Generate a message log entry =

A custom page can generate a message to be sent to the MIDAS message log (see [[Message System]]). A call to mjsonrpc_cm_msg() will generate a message if using the [[mjsonrpc]] functions. Otherwise, use the AJAX function [[Mhttpd.js|ODBGenerateMsg]]. To use these functions, the [[Mhttpd.js#include js lib|JS library must be included]] in the html code.

<br><br>
= Checkboxes =
;NOTE
: '''New (since 2018) custom pages using the [[Custom Page#modb* Javascript scheme]] should use [[Custom Page#modbcheckbox|modbcheckbox]] to create a checkbox.'''
<Br><br>

The function [[Mhttpd.js|ODBSet]] (provided the [[Mhttpd.js#include js lib|JS library is included]]) can be used when one clicks on a checkbox for example:
{{Html|text=<input name="box0" type="checkbox" onClick="ODBSet(my_path, this.checked?'1':'0')">}}
If used as above, the state of the checkbox must be initialized when the page is loaded. This can be done with some JavaScript code called on initialization, e.g.
{{JS|text=document.form1.box0.checked= ODBGet(my_path)); // initialize to the correct value}}

<br><br>
= Replace Status Page by a Custom page =

Click to enlarge thumbnail
[[File:Mhcustom_status.jpg|thumbnail|left|Figure 3: ODB /Custom/Status custom-link to a custom status page]]
<div style="clear: both"></div> 

If a custom-link with the [[/Custom ODB tree#Key names|reserved key name]] '''Status''' (not "Status&" or "Status!") is created in the [[/Custom ODB tree]] (as shown in Figure 3), then that custom page will '''replace the default Status Page'''.

Clicking on the {{Button|name=Status}} button on any of the sub-pages (e.g. [[ODB Page]], [[Programs Page]] etc.) will now return to the Custom Status Page. If there are buttons on the Custom Status page, you '''must''' include a [[#Redirect]] statement of the form
{{Html|text=<input type=hidden name="redir" value="../">}}
or you will see the message
Invalid custom page:NULL path

If the Custom Status page includes [[#Resource files]] served on a regular custom page with a statement such as
{{Html|text=<script type="text/javascript" src="cs_functions!">}}
to serve them in a Custom Status page, the statement would be
{{Html|text=<script type="text/javascript" src="<span style="font-weight:bold">/CS/</span>cs_functions!">}}
In fact, this statement can be used in a regular custom page, as the "/CS/" is ignored in that case.

To return to the default Status Page, delete the <span style="color: purple; font-style:italic;">/Custom/Status</span> key.

<br><br>
= Start, Stop and Check if a program is running =
There are [[mjsonrpc]] functions that implemented all three program management functions - start program,
stop program and "is running?" as JSON-RPC methods.

<br><br>
= Send an Ajax request =
By sending an Ajax request from a custom page, you can make a button perform a specific function.

All functions in midas are controlled through special URLs. So the URL
http://<host:port>/?cmd=Start&value=10
will start run #10.

Although it is easier to use an HTML input statement to [[#Access to the MIDAS Menu buttons]],
to send an Ajax request, you can use the function ''XMLHttpRequestGeneric'' which is in the MIDAS Javascript library [[mhttpd.js]].
Then the HTML code would be

{{Html|text=<input type="button" onclick="start()">}}

and in your JavaScript code add a function ''start()'':

<div style="background-color:floralwhite; color:steelblue; font-style:italic">
function start()
{
: var request = XMLHttpRequestGeneric();

: url = '?cmd=Start&value=10';
: request.open('GET', url, true); // asynchronous request
: request.send(null);
} <br>
</div>
See also [[#Access to the MIDAS Menu buttons]]. Another example with optional callback can be found in [[#Customscript button without a page reload]].

This mechanism can be used for starting a particular program, see for example (see [https://midas.triumf.ca/elog/Midas/1046]). However, this functionality is now provided by [[mjsonrpc]] functions - see [[#Start, Stop and Check if a program is running]].

<br><br>
= Image insertion =
An image can be loaded from the web using an HTML {{HtmlTag|tag=<img...>}}, e.g.
{{Html|text="TRIUMF logo" <img src="https://lixenon.triumf.ca/InternalDocuments/Alice/figures/TRIUMF-logo.jpg/image_preview">}}
or a MIDAS History image can be inserted into a custom page using an HTML {{HtmlTag|tag=<img...>}} tag of the following form:
{{Html|text=blah<img src="http://hostname.domain:port/HS/Meterdis.gif&scale=12h&width=300">}}

If the image file is on the local disk, it can be loaded as a '''resource file'''. The image can be of format .pdf, .jpg, .gif, .png. See loading [[#Resource files]].

If you wish to superimpose features such as '''labels and fills''', the image file cannot be served as a [[#Resource files|resource file]]. Instead, the image file must be in '''gif''' format, and must be included in the {{Odbpath|path=/Custom/images}} subtree (Figure 4). Image insertion into a Custom page will be illustrated using the Demo custom page shown in [[#MIDAS stylesheet|Figure 2]]. All the files required for this demo can be found in the MIDAS package at $MIDASSYS/examples/custom. If you do not wish to create
the keys yourself, proceed to [[#Superimposing Labels, Bars and Fills onto a gif image]].

Make a [[/Custom ODB tree#Custom-Link|custom-link]] to the Demo custom page file ''myexpt.html'' , i.e.
[local:js:S]/>ls /custom
myexpt& /home/test/packages/midas/examples/custom/myexpt.html

To make the image ''myexpt.gif'' visible on the custom page, the path and filename of the image file must be defined in the {{Odbpath|path=/Custom/images}} subtree. To do this,
create the subtrees {{Odbpath|path=/Custom/images/myexpt.gif}} where the subtree name "myexpt.gif" is named for the image file you are going to use. Multiple images can be used, by creating multiple imagefile subtrees.

In the imagefile subtree {{Odbpath|path=myexpt.gif}}, create the STRING key {{Odbpath|path=Background}}, and set it to contain the path and name of the image file. The tree structure should then look similar to Figure 4, minus the labels/bars/fill subtrees which will be added to the ODB later.

The image must also be referenced in the custom HTML file ''myexpt.html'' in the "src" field of an HTML {{HtmlTag|tag=<img...>}} tag, e.g.
{{Html|text=<img '''src="myexpt.gif"'''>}}

Click to enlarge thumbnail
[[File:Mhcustom_images.jpg|thumbnail|left|Figure 4: /Custom/Images ODB Tree]]
<br clear=all>
Once the image is visible, enable [[#HTML mapping]], optionally [[#Display mouse position]] and proceed to [[#Superimposing Labels, Bars and Fills onto a gif image]].

<br><br>
== HTML mapping ==
Note that if additional features such as active clickable areas and labels, bars and fills superimposed on the image are also required, HTML mapping must also be activated with the HTML {{HtmlTag|tag=<map...>}} tag and the "usemap" attribute of the HTML {{HtmlTag|tag=<img>}} tag
{{Html|text= <map '''name="myexpt.map"'''> <br> <img src="myexpt.gif" '''usemap="#myexpt.map"'''> <br>...<br> </map>"}}

<br><br>
== Display mouse position ==
[[File:Cursor.png|thumbnail|left|Figure 5: MEG Gas System Custom Page showing cursor position]]
<div style="clear: both"></div> 

When writing custom pages with large background images and labels and fills placed on that image, it is hard to figure out X and Y coordinates of the labels. This can now be simplified by using the function ''getMouseXY()'' in the development JavaScript built-in library [[develop.js]]. This function supplies the X,Y position of the cursor if an element of ID "'''refimg'''" is present. This JS library '''must be [[develop.js|included in the custom page]]''' in order to use it:

Then, set the "id" attribute of the background HTML {{HtmlTag|tag=<img...>}} tag to "refimg", e.g.

<div style="background-color:floralwhite; color:seagreen; font-style:italic">
: <img '''id="refimg"''' src="ebit_pc.gif" usemap="#Custom1"> 
: <map name="Custom1">
: .....
: </map>
</div>

If the "'''refimg'''" tag is present, the cursor changes into a crosshair, and its absolute and relative locations in respect to the reference image are shown in the status bar (Figure 5).

<br><br>
== Superimposing Labels, Bars and Fills onto a gif image ==
You can enhance your custom page by superimposing multiple features based on ODB variables onto an image (e.g. [[#Display mouse position|Figure 5]]), such as

* labels: "live" ODB values positioned in a particular location of the page
* bars : "bar level" showing graphically ODB values such as levels or rate etc.
* fills : "color level" where colour is used as the level indicator.

Each entry (label/bar/fill) will have an ODB tree associated to it defining the ODB variable path, X/Y position, colour, etc. Each time the page is updated, the latest ODB value/level/rate will be shown based on the ODB parameter to which the label, bar or fill is linked - hence the term "live". The overlay of the requested features is done onto the selected image file.

This powerful new extension brings the [[mhttpd]] capability closer to other experimental web controllers similar to EPICS.

;Note
: Be sure to enable the feature to [[#Display mouse position]] in order to facilitate finding the X,Y positions of the various features.
: [[#HTML mapping]] must be activated for labels/bars/fills to work

A Demo custom page showing labels, bars and fills superimposed on an image is shown in [[#MIDAS stylesheet|Figure 2]].
All the files for this demo can be found in $MIDASSYS/examples/custom/. The file xcustom.odb contains the ODB keys required, including those to insert the image and superimpose the various labels, fills etc. This file can be loaded into the ODB with the {{Odbedit cmd|cmd=load}}.

<br><br>
=== Adding Labels ===

[[File:Mhcustom_label.jpg|thumbnail|left|Figure 6: /Custom/Images/Labels ODB subtree]]

In order to include a readout of ODB values (i.e. labels), on the image, a further ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Labels}} must be created. Creating a subdirectory for a particular label i.e. {{Odbpath|path=<label name>}} in the {{Odbpath|path=Labels}} subtree will, at the next custom web page refresh, cause the complete structure for that label to be created and filled with default values. Once the {{Odbpath|path=<label name>}} subtree is created, the user fills the various keys as desired. See [[/Custom ODB tree#Labels subtree]] for details of the various fields. This procedure is repeated for all the labels required, using a unique {{Odbpath|path=<label name>}} subdirectory for each label. An example of a {{Odbpath|path=<label name>}} subtree is shown in Figure 6.

<div style="clear: both"></div> 

<br><br>
=== Adding Bars ===

[[File:Mhcustom_fill.jpg|thumbnail|left|Figure 7: /Custom/Images/Fills ODB subtree]]

In a similar way, Bars can be superimposed on the image. Create a new ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Bars}}. Create a subdirectory for a particular Bar ({{Odbpath|path=<bar name>}}) in the {{Odbpath|path=Bars}} subdirectory. Refresh the web page and fill the various keys as desired. See [[/Custom ODB tree#Bars subtree]] for details of the various fields. Examples of a <bar-name> subtree is shown in Figure 7.

<div style="clear: both"></div> 

<br><br>
=== Adding Fills ===
[[File:Mhcustom_bar.jpg|thumbnail|left|Figure 8: /Custom/Images/Bars ODB subtree]]

In a similar way, Fills can be superimposed on the image. Create new ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Fills}}. Create a subdirectory for a particular Fill ({{Odbpath|path=<fill name>}}) in the {{Odbpath|path=Fills}} subdirectory. Refresh the web page and fill the various keys as desired. See [[/Custom ODB tree#Fills subtree]] for details of the various fields. Examples of a ({{Odbpath|path=<fill name>}} subtree is shown in Figure 8.

<div style="clear: both"></div> 

<br><br>
== Mapping active areas onto the image ==
Provided [[#HTML mapping]] is activated, "clickable" areas can be created on the image.

This can be done now with a new function like this:
{{Html|text= <area shape="rect" coords="40,200,100,300" alt="Main Valve" href="Custom1?cmd=Toggle&odb=/Equipment/Environment/Variables/Output[2]">}}

This defines a clickable map on top of the custom image. The area(s) should match with some area(s) on the image, e.g. the box of a valve. Determining the co-ordinates of this area is simplified by using the Display mouse position feature.

By clicking on this area, the supplied path to the ODB is used (in this case {{Odbpath|path=/Equipment/Environment/Variables/Output[2]}}) and its value is toggled. If the valve value is then used in the image via a [[#Adding Fills|Fill]] statement to change the color of the valve, it can turn green or red depending on its state. This is illustrated in [[#Display mouse position|Figure 5]].

Clicking an active area can also be made to open a new custom page, for example:
{{Html|text=<area shape=rect coords="687,530, 890,648" alt="Pump detail" href = "Pump!" title="Click for Details">}}
{{Html|text=<area shape=rect coords="560,574,775,662" alt="Buffer Tank detail" href = "BufferTank!" title="Click for Details">}}
where ''Pump!'' and ''BufferTank!'' are defined as links to custom pages in the [[/Custom ODB tree]].

<br><br>
== Edit boxes floating on top of a graphic ==

An edit box can be placed on top of a graphic in a particular position by means of an HTML <span style="color:green"><div></span> tag. Using the ODBEdit function from the Midas JS library [[Mhttpd.js]], the custom page code would look like this:

{| style="text-align: left; width: 100%; background-color: floralwhite;" border="0" cellpadding="1" cellspacing="1"
|-
|<pre style="background-color:floralwhite; color:seagreen; font-style:italic">
<div style="position:absolute; top:100px; left:50px;">
<script type="text/javascript"> </pre>
<pre style="background-color:floralwhite; color:steelblue; font-style:italic;">
document.write('Run number: ')
path='/runinfo/run number'
rn = ODBGet(path)
document.write('<a href="#" onclick="ODBEdit(path)" >')
document.write(rn)
document.write('</a>');</pre>
<pre style="background-color:floralwhite; color:seagreen; font-style:italic;">
</script>
</div>
<img src="custom.gif">
</pre>
|}

The same thing could be done with the HTML-style {{HtmlTag|tag=<odb>}} tag :
<pre style="background-color:floralwhite; color:seagreen; font-style:italic">
<div style="position:absolute; top:100px; left:50px;">
Run number: <odb src="/Runinfo/run number" edit=1>
</div>
<img src="custom.gif">
</pre>

<br><br>
= Examples =
For more examples of accessing the ODB with the Javascript library [[mhttpd.js]] look at the example experiment in the MIDAS package $MIDASSYS/examples/javascript1/example.html.

== Example 1 : Asynchronous calls using mjsonrpc functions ==
See [[mjsonrpc#examples]]

== Example 2 : Asynchronous calls using Javascript and AJAX ==

Example 2 shows html code illustrating the use of ODBMCopy(), where innerHTML is used to display the data. On a page with images or a lot of data, innerHTML allows you to update variables without having to reload the whole page. In the example, a timer causes the page to update every 10s (reread the data). Often the ODB data for the whole page can be read by one asynchronous ODBMCopy() call, rather than scattering synchronous ODBGet() calls throughout the page.

Access to the ODB is provided by the [[Mhttpd.js|MIDAS Javascript Library]], included with the line <span style="color:green"><script src='mhttpd.js'></script></span>.

<div style="background-color:floralwhite; color:seagreen; font-style:italic">
<html> <br>
<head> <br>
<title>MyTitle</title> <br>
<script src='mhttpd.js'></script>
<script> </div>
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
var updatePeriod = 10000; // in msec <br>
var updateTimerId = 0; <br>
var counter=0; <br>
function update() { <br>
:clearTimeout(updateTimerId); <br>
: load();
: if (updatePeriod > 0)
: updateTimerId = setTimeout('update()', updatePeriod);
} <br>
function load() { <br>
: document.getElementById('LastUpdated').innerHTML = "Updating..." + new Date;
: var paths = [ "/Runinfo", "/Experiment"];
: var data_odb=ODBMCopy(paths, mcopy_callback, "json")
: counter++;
: document.getElementById('counter').innerHTML = 'Counter: '+ counter
} <br>
function mcopy_callback(data) { <br>
: var obj= JSON.parse(data);
: var runinfo=obj[0];
: document.getElementById('rn').innerHTML = 'Run Number ='+ parseInt(runinfo["Run number"]);
: document.getElementById('state').innerHTML ='Run State= '+ runinfo.State;
: var experiment=obj[1];
: document.getElementById('name').innerHTML='Experiment name = '+ experiment.Name <br>
}<br> </div>
<div style="background-color:floralwhite; color:seagreen; font-style:italic">
</script> <br>
</head> <br>
<body> <br>
<b>Javascript code using ODBMCopy with callback</b> <br>
The data on the page is updated every 10 sec using a timer<br>
<p id="LastUpdated" > Last updated: never</p><br>
<p id="rn"> Run Number : unknown </p><br>
<p id="state"> State : unknown</p><br>
<p id="name"> Experiment name : unknown </p><br>
<p id="counter">Counter: zero </p><br>
<script type="text/javascript"> </div>
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
: if (updatePeriod > 0)
: update(); </div>
<div style="background-color:floralwhite; color:seagreen; font-style:italic">
</script> <br>
</body> </html></div>

<br><br>
== Example 3 : Synchronous Calls using Javascript and AJAX ==
In the following example, JS functions ODBGet and ODBEdit from the [[Mhttpd.js|MIDAS Javascript Library]] are used to access the ODB.
;NOTE
# Synchronous calls are now deprecated (see [[#The MIDAS Javascript Library|above]]).
# The Javascript library '''must be [[mhttpd.js#include js lib|included in the HTML code]]'''.

{{Html|text=<script>}}
{{JS|text=document.write ('Experiment Name: '+ ODBGet("/Experiment/Name")) <br> var alarm_path="/alarms/Alarm system active"; <br> var alarm_active=ODBGet(alarm_path); <br> document.write('<a href="#" onclick="ODBEdit(alarm_path)" >'+alarm_active+'</a>')}}
{{Html|text=</script>}}

[[Category:Custom]]

Custom Page Features

2019-05-28T22:03:51Z

Suz:

{{Pagelinks}}
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Mhttpd|mhttpd MIDAS web server]]
* [[ODB Page]]
* [[Custom Page]]
* [[/Custom ODB tree]]
* [[Mhttpd.js|MIDAS Javascript library (mhttpd.js)]]
* [[mjsonrpc|MIDAS JSON RPC library functions (mjsonrpc)]]
* [[odbedit]]
</div>

= Introduction =
;NOTE
: Since 2018, many of the features described here can now be implemented more simply using the mod* JS functions (see [[Custom Page|Custom Web Page]]).
: '''If writing a new web page, it is strongly recommended you make use of the mod*JS features. '''

This page describes some of the special features provided for use on a user-created [[Custom Page|Custom Web Page]] using the [[#The MIDAS Javascript Library]], which was the recommended way to write Custom Pages before the [[Custom Page#modb* Javascript scheme]] was available.

<br><br>

= The MIDAS Javascript Library =
The MIDAS Javascript Library [[mhttpd.js]] includes routines written in Javascript and AJAX to provide features useful for writers of [[Custom Page]]s, such as access to the ODB. Recently asynchronous [[mjsonrpc|JSON-RPC functions]] using [[mjsonrpc#Javascript client library|Promises]] has been added (January 2016).
;NOTE
:To use functions in this library, it '''must be [[mhttpd.js#include js lib|included in the HTML code]]'''.

Many of the older routines (ODBGet, ODBSet) use '''synchronous''' RPC requests. With synchronous request, a second RPC request must wait until the first request is complete. This can significantly slow down web pages where many calls to ODBGet are made. For this reason, functions were developed that can be synchronous or '''asynchronous''' (e.g. ODBMCopy) that include a callback mechanism. The data from ODBMCopy can be formatted in [[mjsonrpc#JSON general information|JSON]].

Web developers are moving away from synchronous RPC requests, which are now deprecated [https://midas.triumf.ca/elog/Midas/1128]. Some modern browsers return a warning on a synchronous RPC request.

A new group of JSON-RPC functions using [[mjsonrpc#Javascript client library|Promises]] has been added to the MIDAS Javascript Library (January 2016). These are asynchronous only, and they also provide more functionality and have better error handling than the older AJAX calls, which are also inconsistent in how they handle Booleans. They also have much improved handling of reading/writing arrays to the ODB. Before 2018 it was recommended that all new Custom Pages are written using these JSON-RPC functions. {{Important|text=Since 2018 the [[Custom Page#modb* Javascript scheme]] is recommended for new Custom Pages}}.

The MIDAS Javascript Library routines requires an up-to-date browser that supports Promises (see [https://midas.triumf.ca/elog/Midas/1145]). If using an older browser version, the asynchronous AJAX calls (e.g. ODBMCopy) should be used in order to avoid having to rewrite the web page at a later date to remove all synchronous calls.

<br><br>
== Access the ODB using mjson-rpc asynchronous functions ==

Access to the ODB is provided by the [[Mhttpd.js|MIDAS Javascript Library]], which (since January 2016) includes the [[mjsonrpc]] functions. It is [[#The MIDAS Javascript Library|recommended]] that these functions are used for '''new''' pages rather than the older AJAX calls (see below).

To run these functions you need
# to [[mhttpd.js#include js lib|include the Javascript library in the HTML code]]'''
# to use an up-to-date browser that supports Promises (see [https://midas.triumf.ca/elog/Midas/1145]).

Examples showing how to read and write to the ODB can be found at [[mjsonrpc#examples]]. Also included are examples using arrays.

<br><br>
== Access the ODB using asynchronous AJAX calls ==
;NOTE
: It is recommended that asynchronous MIDAS JSON-RPC functions are used for new pages rather than the older AJAX calls (see [[#Access the ODB using mjson-rpc asynchronous functions|above]]).

[[#Example 2 : Asynchronous calls using Javascript and AJAX|Example 2]] uses the asynchronous call ODBMCopy() with callback to read the data. The data are converted into JSON format. In this case, when accessing the JSON data, ''the ODB Keynames must be in the same case as they are in the ODB'', even though the case is ignored by the ODB. If you find this feature annoying, use [[#Access the ODB using mjson-rpc asynchronous functions|mjson-rpc function db_get_values()]] as all keynames are converted to lower case.

<br><br>
== Access the ODB using synchronous AJAX requests ==
;NOTE
: Synchronous requests are now deprecated (see [[#The MIDAS Javascript Library|above]]). New pages should be written [[#Using mjson-rpc asynchronous functions]].

See [[#Example 3 : Synchronous Calls using Javascript and AJAX]].

<br><br>
= Access the ODB with HTML-style <span style="color:seagreen font-style:italic"><odb></span> tags =

;NOTE
: This method pre-dates the [[Mhttpd.js|MIDAS Javascript Library]]. It is recommended that the [[Mhttpd.js|MIDAS Javascript Library]] be used for ODB access.

If Javascript (JS) is not available, the older HTML-style {{HtmlTag|tag=<odb>}} tags are still available and provide limited functionality.

The HTML-style {{HtmlTag|tag=<odb>}} tag has been defined for read/write access to the ODB under HTML. The {{HtmlTag|tag=<odb>}} tags are declared within enclosing HTML {{HtmlTag|tag=<form...>....</form>}} tags.

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"
|+ Access to ODB from HTML
|-
| colspan="1" rowspan="1" style="text-align: center; vertical-align: top; background-color: rgb(204, 204, 255); font-weight: bold;" | HTML ODB tag
| colspan="1" rowspan="1" style="text-align: center; vertical-align: top; background-color: rgb(204, 204, 255); font-weight: bold;" | Meaning

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path">
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: black" |Display ODB field (read only)

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path" edit=1 pwd="CustomPwd">
| Display an Editable ODB field (inline style). Optional password protection with '''pwd''' .

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path" edit=2 pwd="CustomPwd">
| Display an Editable ODB field (popup style). Optional password protection with '''pwd''' .
|}

;NOTE
: The Optional password protection with '''pwd''' (documented in the [http://ladd00.triumf.ca/~daqweb/doc/midas-old/html/RC_customize_ODB.html#RC_Access_Control| OldMidas Document]) may not be working.
: Use the [[/Experiment ODB tree#Security subtree|Web Password security]] instead.

{{HtmlTag|tag=<odb>}} tags are included in the HTML code e.g.

{{Html|text= Experiment Name: <odb src="/Experiment/Name"> <br> Run Number: <odb src="/runinfo/run number" edit=1>}}

See also [[Custom Page#How to write a Custom Page|HTML Custom Page example]].

<br><br>
= ODB RPC access =
The [[Mhttpd.js|MIDAS Javascript Library]] function ODBRpc() defined for RPC access.

This permits buttons on MIDAS "custom" web pages to invoke RPC calls directly into user frontend programs, for example to turn hardware modules on or off.

<br><br>
= JSON support =
[[mjsonrpc#JSON general information|JSON]] support is provided with the [[Mhttpd.js|MIDAS Javascript Library]].

<br><br>
= Access to the MIDAS Menu buttons =
Access to the standard MIDAS Menu buttons can be provided with HTML {{HtmlTag|tag=<input...>}} tags of the form:


{{Html|text=<input name="cmd" value=''<button-name>'' type="submit" >}}
Valid values are the standard MIDAS Menu buttons, i.e. (Start, Pause, Resume, Stop, ODB, Elog, Alarms, History, Programs etc). The {{HtmlTag|tag=<input...>}} tags must be declared within enclosing HTML {{HtmlTag|tag=<form...>....</form>}} tags (see above).

The following HTML fragment shows the inclusion of three of the standard buttons, giving access to the Main Status, ODB and Messages pages :

{{Html|text= <form name="form1" method="Get" action="/CS/MyExpt&"> <br> <input name="cmd" value="Status" type="submit"> <br> <input name="cmd" value="ODB" type="submit"> <br> <input name="cmd" value="Messages" type="submit"> <br> ... <br> </form> }}

See also [[#Redirect]].

<br><br>
= Redirect =

When buttons are included on a Custom Page, after pressing a button (e.g. the Start or Stop button) it may be desirable to return to the same custom page, rather than returning to the [[Status Page]].

This can be done by including an HTML {{HtmlTag|tag=<input...>}} tag with the attributes ''type'' set to "hidden" and ''name'' set to "redir". This name ("redir") is detected by [[Mhttpd]], causing a redirect to the specified custom link in the ''value'' attribute.

For example, the following redirects the screen back to the custom page link {{Odbpath|path=/Custom/my_custom_page&}} when buttons are pressed:
{{Html|text=<input type=hidden name="redir" value="my_custom_page&">}}

See also [[#Replace Status Page by a Custom page|Redirect when a Custom Page replaces the Status Page]].
<br><br>

= CustomScript Buttons =

[[/Customscript ODB tree#Customscript-button|CustomScript buttons]] can be provided on [[Custom Page|Custom Pages]]. These buttons are equivalent to optional '''script buttons''' on the [[Status Page]], which call a script to perform a particular action when the button is pressed. See [[/Script ODB tree#Script-button|script buttons]] for details. Customscript buttons can be set up through the [[/Customscript ODB tree]].

Any key <span style="color:purple; font-style:italic">/CustomScript/test</span> will appear as a customscript-button
<span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">test</span> on a custom page whose code includes an HTML {{HtmlTag|tag=<input...>}} tag of the form:
{{Html|text=<input type=submit name=customscript value="test">}}
where the action of the button <span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">test</span> will be found in the <span style="color:purple; font-style:italic">/customscript/test</span> subdirectory.

After pressing a customscript-button, the ''type=submit'' in the HTML {{HtmlTag|tag=<input>}} will cause a page reload. This will result in a switch to the [[Status Page]], unless a [[#redirect]] input tag is included to redirect back to the original custom page.

== Customscript button without a page reload ==
To define a customscript button that does '''not''' cause a page reload, set the ''type'' in the HTML {{HtmlTag|tag=<input>}} to "button", i.e.
{{Html|text=<input name="customscript" value="test" type="button" onClick=cs_button(this.value)> }}
and use ''"onClick"'' to call a function to [[#Send an Ajax Request]] instead. The following function sends an asynchronous request, with an optional callback.
{{HtmlTag|tag=<script>}}
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
function cs_button(cmd, callback)<br>
{ // send a request to execute a custom script
: var url;
: var request = XMLHttpRequestGeneric();
:
: url = ODBUrlBase
: if(document.getElementById("redir") != null)
:: url += '?redir='+document.getElementById('redir').value
: url+='&customscript='+ encodeURIComponent(cmd);
: request.open('GET', url, true); // asynchronous request
: request.send(null);
: if(callback!=undefined) {
:: request.onreadystatechange = function() {
::: if (request.readyState == 4) {
:::: if (request.status == 200)
::::: callback();
:::: else
::::: alert('cs_button: Error after sending request to Custom Script "'+cmd+'" :\nHTTP Status: '+request.status)
::: }
:: }
: }
: else {
:: if (request.status != 200)
::: alert('cs_button: Error after sending request to Custom Script "'+cmd+'" :\nHTTP Status: '+request.status)
: }
}
</div>
{{HtmlTag|tag=</script>}}

<br><br>
= Resource files =
It is often desirable to serve resource files (i.e. '''local files''' such as an external stylesheet, javascript files or images'''<sup>***</sup>''') to a custom page. The following sections describe two alternative ways of serving resource files to a custom page:
* [[#Resource files served WITH /custom/path key defined|with /custom/path key defined]]
* [[#Resource files served WITHOUT /custom/path key defined|without /custom/path key defined]]
See also serving resources to a [[#Replace Status Page by a Custom Status page|Custom Status page]].
;NOTE
: '''<sup>***</sup>''' To superimpose labels, bars or fills onto an image, the image cannot be served as a resource file. See [[#Image insertion]].

== Resource files served WITH <span style="color: purple; font-style:italic;">/custom/path</span> key defined ==
When a number of resource files are required, it is convenient to place them in the same directory on the disk, and create a key {{Odbpath|path=/Custom/Path}} to contain this directory.

$ ls /home/midas/online/custom/
custom_functions.js custom_globals.js custom_page.html custom_stylesheet.css test_image.png
With the {{Odbpath|path=/Custom/Path}} key defined, [[/Custom ODB tree#Custom-Link|custom-links]] for individual resource files need not be created in the {{Odbpath|path=/Custom/Path}} tree. The custom-link {{Odbpath|path=custom_page&}} '''is''' required so that the custom page can be accessed from the [[/Custom ODB tree#Custom-Button|custom-button]] {{Button|name=custom_page}} on the Status Page. The key name ends in the special character "&" so that it will open in the same window as the Status page (see [[/Custom ODB tree#Key names|key names]]).
$ odbedit
[local:exp:S] ls /custom
path /home/midas/online/custom/
custom_page& custom_page.html

A {{HtmlTag|tag=<script>}} tag for each resource file to be served (specifying the file name) is then placed in the header of {{File|name=custom_page.html}}
i.e.
{{Html|text=<script type="text/javascript" src="custom_functions.js"></script>}}
{{Html|text=<script type="text/javascript" src="custom_globals.js"></script>}}
<br> and a {{HtmlTag|tag=<link>}} tag for an external stylesheet
{{Html|text=<link type="text/css" rel="stylesheet" href="custom_stylesheet.css" title="Stylesheet">}}
An image tag is placed in the body of {{File|name=custom_page.html}}
{{Html|text=<img src="test_image.png"> }}
[[mhttpd]] then loads the resource file from the directory indicated by the Path key with the correct MIME type (see [[/Custom ODB tree#Keys in the /Custom tree|Custom tree keys]] for supported MIME types).

== Resource files served WITHOUT <span style="color: purple; font-style:italic;">/custom/path</span> key defined ==
Alternatively, resource files can be served to a [[Custom Page]] by creating a key for every resource file in the [[/Custom ODB tree]]. These keys must contain the full path of the file on the disk, and the key {{Odbpath|path=/Custom/Path}} must NOT be defined. The resource files can be in different directories on the disk. By defining the key names with an appropriate file extension, the resource files are served with the appropriate MIME types. The key names end in the special character "!" so that they will not appear on the Status page as custom-links (see [[/Custom ODB tree#Key names|key names]].

Without the {{Odbpath|path=/Custom/Path}} key, the links for the above example in the {{Odbpath|path=/Custom}} tree might look like
$ odbedit
[local:exp:S] ls /custom
custom_page& /home/midas/online/custom/custom_page.html
custom_functions.js! /home/midas/online/resources/custom_functions.js
globals.js! /home/midas/online/resources/custom_functions.js
stylesheet.css! /home/midas/online/stylesheets/custom_stylesheet.css
image.png! /home/midas/images/test_image.png

assuming the resource files are now in the subdirectories indicated.
The {{HtmlTag|tag=<script>}} tag for each resource file to be served (specifying the custom-link) is then placed in the header of {{File|name=custom_page.html}}
i.e.
{{Html|text=<script type="text/javascript" src="custom_functions.js!"></script>}}
{{Html|text=<script type="text/javascript" src="globals.js!"></script>}}
<br> and a {{HtmlTag|tag=<link>}} tag for an external stylesheet
{{Html|text=<link type="text/css" rel="stylesheet" href="stylesheet.css!" title="Stylesheet">}}
An image tag is placed in the body of {{File|name=custom_page.html}}
{{Html|text=<img src="image.png!"> }}

<br><br>
= MIDAS stylesheet =

The MIDAS package provides a condensed stylesheet
: {{Filepath|path=/home/midas/packages/midas/resources/}}{{File|name=mhttpd.css}}
for users who would like their custom pages to have a similar "look and feel" to that of the standard pages.

To include the MIDAS stylesheet, in the HTML header, add
{{HtmlTag|tag=<link rel="stylesheet" type="text/css" href="mhttpd.css">}}
No ''custom link'' needs to be defined.
<br>

The resulting Demo custom page is shown in Figure 1, which can be compared with Figure 2 (no stylesheet).
{| class="wikitable"
|-
! Figure 1 !! Figure 2
|-
| Demo Custom Page using MIDAS stylesheet || Demo Custom Page
|-

| [[File:Mhxcustom03.jpg|thumb|300px]] || [[File:Mhxcustom02.jpg|thumb|200px]]
|}
<br clear=all>

<br><br>
= Alias-Buttons and Hyperlinks =
Any hyperlink can easily be included on a [[Custom Page]] by using the standard HTML anchor {{HtmlTag|tag=<a...>}} tag, e.g.
{{Html|text=<a href="http://ladd00.triumf.ca/~daqweb/doc/midas/html/">Midas Help</a>}}

Links on a custom page equivalent to [[/Alias ODB tree#Alias-Buttons|alias-buttons]] can also be made e.g.
{{Html|text=<button type="button" onclick="document.location.href='/Alias/alias&';">alias</button>}}
See the [[/Alias ODB tree]] for details.

<br><br>
= Page refresh =
The following {{HtmlTag|tag=<meta...>}} tag included in the HTML header code will cause the whole custom page to refresh in 60 seconds :
{{Html|text=<meta http-equiv="Refresh" content="60">}}
It is also possible to [[#Periodic update of parts of a custom page|periodically update parts]] of a custom page.

<br><br>
= Periodic update of parts of a custom page =

The functionality of [[Mhttpd.js|ODBGet]] together with the window.setInterval() function
can be used to update parts of the web page periodically.
For example the Javascript fragment below contains a function which updates the current run number every 10 seconds in the background:

<div style="background-color:floralwhite; color:steelblue; font-style:italic"> 
window.setInterval("Refresh()", 10000);<br>
function Refresh() {<br>
:document.getElementById("run_number").innerHTML = ODBGet('/Runinfo/Run number');<br>
}
</div>
The custom page has to
* [[Mhttpd.js#include js lib|include the MIDAS JS library]] to access ODBGet
* contain an element with id="run_number", such as
{{Html|text=<td id="run_number"></td>}}

<br><br>
= Display last MIDAS message(s) =

The message log (see [[Message System]]) can be accessed from a custom page using a call to the JavaScript library function [[Mhttpd.js|ODBGetMsg]] (provided the [[Mhttpd.js#include js lib|JS library is included]]).

This allows the inclusion of the "Last Midas message" on a custom page, e.g.
{{JS|text=document.write('Last message:'+ODBGetMsg("midas",0,1))}}
More messages may be displayed by increasing the third parameter to ODBGetMsg.
;Note
: Parameters were changed August 2015. See [[Mhttpd.js|ODBGetMsg]] for older versions.
: Coming soon - a [[mjsonrpc]] function

<br><br>
= Generate a message log entry =

A custom page can generate a message to be sent to the MIDAS message log (see [[Message System]]). A call to mjsonrpc_cm_msg() will generate a message if using the [[mjsonrpc]] functions. Otherwise, use the AJAX function [[Mhttpd.js|ODBGenerateMsg]]. To use these functions, the [[Mhttpd.js#include js lib|JS library must be included]] in the html code.

<br><br>
= Checkboxes =
The function [[Mhttpd.js|ODBSet]] (provided the [[Mhttpd.js#include js lib|JS library is included]]) can be used when one clicks on a checkbox for example:
{{Html|text=<input name="box0" type="checkbox" onClick="ODBSet(my_path, this.checked?'1':'0')">}}
If used as above, the state of the checkbox must be initialized when the page is loaded. This can be done with some JavaScript code called on initialization, e.g.
{{JS|text=document.form1.box0.checked= ODBGet(my_path)); // initialize to the correct value}}

<br><br>
= Replace Status Page by a Custom page =

Click to enlarge thumbnail
[[File:Mhcustom_status.jpg|thumbnail|left|Figure 3: ODB /Custom/Status custom-link to a custom status page]]
<div style="clear: both"></div> 

If a custom-link with the [[/Custom ODB tree#Key names|reserved key name]] '''Status''' (not "Status&" or "Status!") is created in the [[/Custom ODB tree]] (as shown in Figure 3), then that custom page will '''replace the default Status Page'''.

Clicking on the {{Button|name=Status}} button on any of the sub-pages (e.g. [[ODB Page]], [[Programs Page]] etc.) will now return to the Custom Status Page. If there are buttons on the Custom Status page, you '''must''' include a [[#Redirect]] statement of the form
{{Html|text=<input type=hidden name="redir" value="../">}}
or you will see the message
Invalid custom page:NULL path

If the Custom Status page includes [[#Resource files]] served on a regular custom page with a statement such as
{{Html|text=<script type="text/javascript" src="cs_functions!">}}
to serve them in a Custom Status page, the statement would be
{{Html|text=<script type="text/javascript" src="<span style="font-weight:bold">/CS/</span>cs_functions!">}}
In fact, this statement can be used in a regular custom page, as the "/CS/" is ignored in that case.

To return to the default Status Page, delete the <span style="color: purple; font-style:italic;">/Custom/Status</span> key.

<br><br>
= Start, Stop and Check if a program is running =
There are [[mjsonrpc]] functions that implemented all three program management functions - start program,
stop program and "is running?" as JSON-RPC methods.

<br><br>
= Send an Ajax request =
By sending an Ajax request from a custom page, you can make a button perform a specific function.

All functions in midas are controlled through special URLs. So the URL
http://<host:port>/?cmd=Start&value=10
will start run #10.

Although it is easier to use an HTML input statement to [[#Access to the MIDAS Menu buttons]],
to send an Ajax request, you can use the function ''XMLHttpRequestGeneric'' which is in the MIDAS Javascript library [[mhttpd.js]].
Then the HTML code would be

{{Html|text=<input type="button" onclick="start()">}}

and in your JavaScript code add a function ''start()'':

<div style="background-color:floralwhite; color:steelblue; font-style:italic">
function start()
{
: var request = XMLHttpRequestGeneric();

: url = '?cmd=Start&value=10';
: request.open('GET', url, true); // asynchronous request
: request.send(null);
} <br>
</div>
See also [[#Access to the MIDAS Menu buttons]]. Another example with optional callback can be found in [[#Customscript button without a page reload]].

This mechanism can be used for starting a particular program, see for example (see [https://midas.triumf.ca/elog/Midas/1046]). However, this functionality is now provided by [[mjsonrpc]] functions - see [[#Start, Stop and Check if a program is running]].

<br><br>
= Image insertion =
An image can be loaded from the web using an HTML {{HtmlTag|tag=<img...>}}, e.g.
{{Html|text="TRIUMF logo" <img src="https://lixenon.triumf.ca/InternalDocuments/Alice/figures/TRIUMF-logo.jpg/image_preview">}}
or a MIDAS History image can be inserted into a custom page using an HTML {{HtmlTag|tag=<img...>}} tag of the following form:
{{Html|text=blah<img src="http://hostname.domain:port/HS/Meterdis.gif&scale=12h&width=300">}}

If the image file is on the local disk, it can be loaded as a '''resource file'''. The image can be of format .pdf, .jpg, .gif, .png. See loading [[#Resource files]].

If you wish to superimpose features such as '''labels and fills''', the image file cannot be served as a [[#Resource files|resource file]]. Instead, the image file must be in '''gif''' format, and must be included in the {{Odbpath|path=/Custom/images}} subtree (Figure 4). Image insertion into a Custom page will be illustrated using the Demo custom page shown in [[#MIDAS stylesheet|Figure 2]]. All the files required for this demo can be found in the MIDAS package at $MIDASSYS/examples/custom. If you do not wish to create
the keys yourself, proceed to [[#Superimposing Labels, Bars and Fills onto a gif image]].

Make a [[/Custom ODB tree#Custom-Link|custom-link]] to the Demo custom page file ''myexpt.html'' , i.e.
[local:js:S]/>ls /custom
myexpt& /home/test/packages/midas/examples/custom/myexpt.html

To make the image ''myexpt.gif'' visible on the custom page, the path and filename of the image file must be defined in the {{Odbpath|path=/Custom/images}} subtree. To do this,
create the subtrees {{Odbpath|path=/Custom/images/myexpt.gif}} where the subtree name "myexpt.gif" is named for the image file you are going to use. Multiple images can be used, by creating multiple imagefile subtrees.

In the imagefile subtree {{Odbpath|path=myexpt.gif}}, create the STRING key {{Odbpath|path=Background}}, and set it to contain the path and name of the image file. The tree structure should then look similar to Figure 4, minus the labels/bars/fill subtrees which will be added to the ODB later.

The image must also be referenced in the custom HTML file ''myexpt.html'' in the "src" field of an HTML {{HtmlTag|tag=<img...>}} tag, e.g.
{{Html|text=<img '''src="myexpt.gif"'''>}}

Click to enlarge thumbnail
[[File:Mhcustom_images.jpg|thumbnail|left|Figure 4: /Custom/Images ODB Tree]]
<br clear=all>
Once the image is visible, enable [[#HTML mapping]], optionally [[#Display mouse position]] and proceed to [[#Superimposing Labels, Bars and Fills onto a gif image]].

<br><br>
== HTML mapping ==
Note that if additional features such as active clickable areas and labels, bars and fills superimposed on the image are also required, HTML mapping must also be activated with the HTML {{HtmlTag|tag=<map...>}} tag and the "usemap" attribute of the HTML {{HtmlTag|tag=<img>}} tag
{{Html|text= <map '''name="myexpt.map"'''> <br> <img src="myexpt.gif" '''usemap="#myexpt.map"'''> <br>...<br> </map>"}}

<br><br>
== Display mouse position ==
[[File:Cursor.png|thumbnail|left|Figure 5: MEG Gas System Custom Page showing cursor position]]
<div style="clear: both"></div> 

When writing custom pages with large background images and labels and fills placed on that image, it is hard to figure out X and Y coordinates of the labels. This can now be simplified by using the function ''getMouseXY()'' in the development JavaScript built-in library [[develop.js]]. This function supplies the X,Y position of the cursor if an element of ID "'''refimg'''" is present. This JS library '''must be [[develop.js|included in the custom page]]''' in order to use it:

Then, set the "id" attribute of the background HTML {{HtmlTag|tag=<img...>}} tag to "refimg", e.g.

<div style="background-color:floralwhite; color:seagreen; font-style:italic">
: <img '''id="refimg"''' src="ebit_pc.gif" usemap="#Custom1"> 
: <map name="Custom1">
: .....
: </map>
</div>

If the "'''refimg'''" tag is present, the cursor changes into a crosshair, and its absolute and relative locations in respect to the reference image are shown in the status bar (Figure 5).

<br><br>
== Superimposing Labels, Bars and Fills onto a gif image ==
You can enhance your custom page by superimposing multiple features based on ODB variables onto an image (e.g. [[#Display mouse position|Figure 5]]), such as

* labels: "live" ODB values positioned in a particular location of the page
* bars : "bar level" showing graphically ODB values such as levels or rate etc.
* fills : "color level" where colour is used as the level indicator.

Each entry (label/bar/fill) will have an ODB tree associated to it defining the ODB variable path, X/Y position, colour, etc. Each time the page is updated, the latest ODB value/level/rate will be shown based on the ODB parameter to which the label, bar or fill is linked - hence the term "live". The overlay of the requested features is done onto the selected image file.

This powerful new extension brings the [[mhttpd]] capability closer to other experimental web controllers similar to EPICS.

;Note
: Be sure to enable the feature to [[#Display mouse position]] in order to facilitate finding the X,Y positions of the various features.
: [[#HTML mapping]] must be activated for labels/bars/fills to work

A Demo custom page showing labels, bars and fills superimposed on an image is shown in [[#MIDAS stylesheet|Figure 2]].
All the files for this demo can be found in $MIDASSYS/examples/custom/. The file xcustom.odb contains the ODB keys required, including those to insert the image and superimpose the various labels, fills etc. This file can be loaded into the ODB with the {{Odbedit cmd|cmd=load}}.

<br><br>
=== Adding Labels ===

[[File:Mhcustom_label.jpg|thumbnail|left|Figure 6: /Custom/Images/Labels ODB subtree]]

In order to include a readout of ODB values (i.e. labels), on the image, a further ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Labels}} must be created. Creating a subdirectory for a particular label i.e. {{Odbpath|path=<label name>}} in the {{Odbpath|path=Labels}} subtree will, at the next custom web page refresh, cause the complete structure for that label to be created and filled with default values. Once the {{Odbpath|path=<label name>}} subtree is created, the user fills the various keys as desired. See [[/Custom ODB tree#Labels subtree]] for details of the various fields. This procedure is repeated for all the labels required, using a unique {{Odbpath|path=<label name>}} subdirectory for each label. An example of a {{Odbpath|path=<label name>}} subtree is shown in Figure 6.

<div style="clear: both"></div> 

<br><br>
=== Adding Bars ===

[[File:Mhcustom_fill.jpg|thumbnail|left|Figure 7: /Custom/Images/Fills ODB subtree]]

In a similar way, Bars can be superimposed on the image. Create a new ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Bars}}. Create a subdirectory for a particular Bar ({{Odbpath|path=<bar name>}}) in the {{Odbpath|path=Bars}} subdirectory. Refresh the web page and fill the various keys as desired. See [[/Custom ODB tree#Bars subtree]] for details of the various fields. Examples of a <bar-name> subtree is shown in Figure 7.

<div style="clear: both"></div> 

<br><br>
=== Adding Fills ===
[[File:Mhcustom_bar.jpg|thumbnail|left|Figure 8: /Custom/Images/Bars ODB subtree]]

In a similar way, Fills can be superimposed on the image. Create new ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Fills}}. Create a subdirectory for a particular Fill ({{Odbpath|path=<fill name>}}) in the {{Odbpath|path=Fills}} subdirectory. Refresh the web page and fill the various keys as desired. See [[/Custom ODB tree#Fills subtree]] for details of the various fields. Examples of a ({{Odbpath|path=<fill name>}} subtree is shown in Figure 8.

<div style="clear: both"></div> 

<br><br>
== Mapping active areas onto the image ==
Provided [[#HTML mapping]] is activated, "clickable" areas can be created on the image.

This can be done now with a new function like this:
{{Html|text= <area shape="rect" coords="40,200,100,300" alt="Main Valve" href="Custom1?cmd=Toggle&odb=/Equipment/Environment/Variables/Output[2]">}}

This defines a clickable map on top of the custom image. The area(s) should match with some area(s) on the image, e.g. the box of a valve. Determining the co-ordinates of this area is simplified by using the Display mouse position feature.

By clicking on this area, the supplied path to the ODB is used (in this case {{Odbpath|path=/Equipment/Environment/Variables/Output[2]}}) and its value is toggled. If the valve value is then used in the image via a [[#Adding Fills|Fill]] statement to change the color of the valve, it can turn green or red depending on its state. This is illustrated in [[#Display mouse position|Figure 5]].

Clicking an active area can also be made to open a new custom page, for example:
{{Html|text=<area shape=rect coords="687,530, 890,648" alt="Pump detail" href = "Pump!" title="Click for Details">}}
{{Html|text=<area shape=rect coords="560,574,775,662" alt="Buffer Tank detail" href = "BufferTank!" title="Click for Details">}}
where ''Pump!'' and ''BufferTank!'' are defined as links to custom pages in the [[/Custom ODB tree]].

<br><br>
== Edit boxes floating on top of a graphic ==

An edit box can be placed on top of a graphic in a particular position by means of an HTML <span style="color:green"><div></span> tag. Using the ODBEdit function from the Midas JS library [[Mhttpd.js]], the custom page code would look like this:

{| style="text-align: left; width: 100%; background-color: floralwhite;" border="0" cellpadding="1" cellspacing="1"
|-
|<pre style="background-color:floralwhite; color:seagreen; font-style:italic">
<div style="position:absolute; top:100px; left:50px;">
<script type="text/javascript"> </pre>
<pre style="background-color:floralwhite; color:steelblue; font-style:italic;">
document.write('Run number: ')
path='/runinfo/run number'
rn = ODBGet(path)
document.write('<a href="#" onclick="ODBEdit(path)" >')
document.write(rn)
document.write('</a>');</pre>
<pre style="background-color:floralwhite; color:seagreen; font-style:italic;">
</script>
</div>
<img src="custom.gif">
</pre>
|}

The same thing could be done with the HTML-style {{HtmlTag|tag=<odb>}} tag :
<pre style="background-color:floralwhite; color:seagreen; font-style:italic">
<div style="position:absolute; top:100px; left:50px;">
Run number: <odb src="/Runinfo/run number" edit=1>
</div>
<img src="custom.gif">
</pre>

<br><br>
= Examples =
For more examples of accessing the ODB with the Javascript library [[mhttpd.js]] look at the example experiment in the MIDAS package $MIDASSYS/examples/javascript1/example.html.

== Example 1 : Asynchronous calls using mjsonrpc functions ==
See [[mjsonrpc#examples]]

== Example 2 : Asynchronous calls using Javascript and AJAX ==

Example 2 shows html code illustrating the use of ODBMCopy(), where innerHTML is used to display the data. On a page with images or a lot of data, innerHTML allows you to update variables without having to reload the whole page. In the example, a timer causes the page to update every 10s (reread the data). Often the ODB data for the whole page can be read by one asynchronous ODBMCopy() call, rather than scattering synchronous ODBGet() calls throughout the page.

Access to the ODB is provided by the [[Mhttpd.js|MIDAS Javascript Library]], included with the line <span style="color:green"><script src='mhttpd.js'></script></span>.

<div style="background-color:floralwhite; color:seagreen; font-style:italic">
<html> <br>
<head> <br>
<title>MyTitle</title> <br>
<script src='mhttpd.js'></script>
<script> </div>
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
var updatePeriod = 10000; // in msec <br>
var updateTimerId = 0; <br>
var counter=0; <br>
function update() { <br>
:clearTimeout(updateTimerId); <br>
: load();
: if (updatePeriod > 0)
: updateTimerId = setTimeout('update()', updatePeriod);
} <br>
function load() { <br>
: document.getElementById('LastUpdated').innerHTML = "Updating..." + new Date;
: var paths = [ "/Runinfo", "/Experiment"];
: var data_odb=ODBMCopy(paths, mcopy_callback, "json")
: counter++;
: document.getElementById('counter').innerHTML = 'Counter: '+ counter
} <br>
function mcopy_callback(data) { <br>
: var obj= JSON.parse(data);
: var runinfo=obj[0];
: document.getElementById('rn').innerHTML = 'Run Number ='+ parseInt(runinfo["Run number"]);
: document.getElementById('state').innerHTML ='Run State= '+ runinfo.State;
: var experiment=obj[1];
: document.getElementById('name').innerHTML='Experiment name = '+ experiment.Name <br>
}<br> </div>
<div style="background-color:floralwhite; color:seagreen; font-style:italic">
</script> <br>
</head> <br>
<body> <br>
<b>Javascript code using ODBMCopy with callback</b> <br>
The data on the page is updated every 10 sec using a timer<br>
<p id="LastUpdated" > Last updated: never</p><br>
<p id="rn"> Run Number : unknown </p><br>
<p id="state"> State : unknown</p><br>
<p id="name"> Experiment name : unknown </p><br>
<p id="counter">Counter: zero </p><br>
<script type="text/javascript"> </div>
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
: if (updatePeriod > 0)
: update(); </div>
<div style="background-color:floralwhite; color:seagreen; font-style:italic">
</script> <br>
</body> </html></div>

<br><br>
== Example 3 : Synchronous Calls using Javascript and AJAX ==
In the following example, JS functions ODBGet and ODBEdit from the [[Mhttpd.js|MIDAS Javascript Library]] are used to access the ODB.
;NOTE
# Synchronous calls are now deprecated (see [[#The MIDAS Javascript Library|above]]).
# The Javascript library '''must be [[mhttpd.js#include js lib|included in the HTML code]]'''.

{{Html|text=<script>}}
{{JS|text=document.write ('Experiment Name: '+ ODBGet("/Experiment/Name")) <br> var alarm_path="/alarms/Alarm system active"; <br> var alarm_active=ODBGet(alarm_path); <br> document.write('<a href="#" onclick="ODBEdit(alarm_path)" >'+alarm_active+'</a>')}}
{{Html|text=</script>}}

[[Category:Custom]]

Custom Page

2019-05-28T21:40:50Z

Suz:

{{Pagelinks}}

= Links =
{{mhttpdpages3|[[Custom Page Features]]|[[/Custom ODB tree]]|[[Mhttpd.js|MIDAS Javascript library]]}}

= Purpose =
A user-created [[mhttpd]] Custom Web Page accessible from the [[Status Page]] allows the user additional flexibility. For example, a custom page may present the essential parameters of the controlled experiment in a more compact way. A custom page may even replace the default [[Status Page]].

= Introduction =
Custom web pages provide the user with a means of creating secondary user-created web page(s) activated within the standard MIDAS web interface. These custom pages usually display ODB parameters or data to the user. They can contain specific links to the ODB so the user may also input information relevant to the experiment. Users create Custom Pages when the standard pages do not meet their requirements completely.

We note that MIDAS has provided a number of different ways of providing custom pages over the years. A new scheme of custom pages making use of modern HTML5 techniques has been introduced in 2017. This page will mostly only be providing documentation for the new scheme of custom pages.

= Examples of Custom Pages =

Click on the thumbnails to enlarge.

{|
|-
| [[File:Capture_sgas.png|thumb|left|Figure 1: MEG Gas System]] || '''Example 1'''
This page (Figure 1) from the MEG experiment at PSI shows a complex gas system. This shows the use of "fills" and "labels". Open valves are represented as green circles, closed valves as red circles. If, for example, an open valve is clicked, the valve closes, and the circle turns red (provided the user successfully supplied the correct password).
|-
| [[File:custom_ROOT_analyzer_page.png|thumb|left|Figure 2: ROOT Analyzer (MEG Experiment)]] || '''Example 2'''
Many MIDAS experiments work with ROOT based analyzers today. One problem is that the graphical output of the root analyzer can only be seen through the X server and not through the web. At the MEG experiment, this problem was solved in an elegant way: The ROOT analyzer runs in the background, using a "virtual" X server called Xvfb. It plots its output (several panels) normally using this X server, then saves this panels every ten seconds into GIF files. These GIF files are then served through mhttpd using a custom page. The output is shown in Figure 2.

The buttons on the left sides are actually HTML buttons on that custom page overlaid to the GIF image, which in this case shows one of the 800 PMT channels digitized at 1.6 GSPS. With these buttons one can cycle through the different GIF images, which then automatically update ever ten seconds. Of course it is not possible to feed interaction back to the analyzer (i.e. the waveform cannot be fitted interactively) but for monitoring an experiment in production mode this tool is extremely helpful, since it is seamlessly integrated into mhttpd. All the magic is done with JavaScript, and the buttons are overlaid on the graphics using CSS with absolute positioning. The analysis ratio on the top right is also done with JavaScript accessing the required information from the ODB.

For details using Xvfb server, please contact Ryu Sawada <sawada@icepp.s.u-tokyo.ac.jp>.
|-
| [[File:deap_custom_scb.png|thumb|left|Figure 3: SCB Setup (Deap Experiment)]] || '''Example 3'''
This custom page from the Deap Experiment (Figure 3) allows the users to easily set individual channels, or a group of channels, or all channels of the SCB modules to a particular value.
|}

= Access a Custom Page from the Regular MIDAS pages =
Access to a Custom Page is set up through the [[/Custom ODB tree]] (see [[/Custom ODB tree#Keys in the /Custom tree|custom-link]]). This associates a custom page file on the disk with a menu item on the left navigation bar. Clicking on the resulting link will display that custom page.

Often a custom page requires resources such as *.css (stylesheets) or *.js (javascript) files. It is convenient to store all such files with the custom page file (*.html) in
a particular directory, e.g. /home/expt/online/custom. By creating an ODB key /Custom/Path, all the custom page files and resources can be served easily from this directory.
See [[Custom Page Features#Resource files]] for more information.

If the key {{Odbpath|path=/Custom/myPage&}} (see Note) is created, e.g.
odbedit> ls /Custom
Path /home/expt/online/custom
myPage& mypage.html

the custom link on the left navigation bar will be <code>myPage</code> and the URL for the resulting custom page will be of the form <code>http://myhost.mydomain:myport/cmd=?Custom&page=myPage</code> (see also [[mhttpd#usage]]).
Clicking on <code>myPage</code> will display the custom page in the same window.

;Note
: Without the "&" symbol in the key name, the page would appear in a new window. See [[/Custom ODB tree#Key names|Key names]] for more information.

= How to write a custom page =
A custom page is usually written in a combination of HTML and Javascript. It can contain any of the features described below. A [[Mjsonrpc | Javascript MjsonRPC Library]] has been written to provide access to the ODB and other functions.

In what follows, we describe a scheme for writing custom pages with the set of modb* javascript functions. The advantages of using these modb* javascript functions are

* modb* functions hide details about the underlying MjsonRPC calls, which should allow a user to write pretty and sophisticated custom pages quickly and cleanly.
* modb* functions ensure that all the periodic updates of the ODB value (and other MIDAS information) are done in a single MjsonRPC batch call, which should ensure optimal page loading speed.
* modb* functions encapsulate the underlying communication. Should the communication change in the future, the custom pages do not have to be changed.

It is also possible for users to write their custom pages using only the underlying [[Mjsonrpc | MjsonRPC library]] calls, but they then need to ensure on their own that the page loading remains efficient. In particular, if you combine the standard MIDAS navigation bars (described in next section) with your own periodic MjsonRPC calls then you will probably need at least two separate periodic RPC calls to populate the custom page (instead of one call). It will also require more coding to implement the custom page with only MjsonRPC calls.

== How to use the standard MIDAS navigation bars on your custom page ==

If you want to have your custom page use the same header and navigation bars as the standard MIDAS pages, you need to use the following syntax

<pre>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="midas.css">
<script src="controls.js"></script>
<script src="midas.js"></script>
<script src="mhttpd.js"></script>
<title>myPage</title>
</head>

<body class="mcss" onload="mhttpd_init('myPage');">


<div id="mheader"></div>
<div id="msidenav"></div>

<div id="mmain">
ADD YOUR HTML/JS CODE here...
</div>
</pre>

The call <code>mhttpd_init('myPage')</code> is executed when the page is loaded, and <code>myPage</code> is the name of the page shown on the left menu bar. This corresponds to an ODB entry /Custom/myPage.
This pattern will allow you to use the standard MIDAS navigation whether you are using the modb* functions or the underlying [[Mjsonrpc | javascript libraries]].

= modb* Javascript scheme =

The general scheme of the custom page scheme is to write <code><div name="modb..."></div></code> or <code><span name="modb..."></span></code> tags with special names, most of them starting with "modb..." ("MIDAS-ODB"). Use a <code><div></code> tag if you want the element to appear in a separate line, and use the <code><span></code> tag if you want to display the element in-line. The following description uses only <code><div></code> tags, but all of them can be changed to <code><span></code>. All HTML tags with "modb..." names are scanned by the <code>mhttp_init('name')</code> function upon page load, and their inner contents is replaced by the requested ODB value or some graphics. The contents is then updated regularly. Updates are once per second by default. This can be changed by passing a second argument to <code>mhttpd_init('name', interval)</code> where "interval" is in milliseconds.

== modbset(path, value) ==

To set values in the ODB, the midas JavaScript function mjsonrpc_db_paste() is usually called. This function is implemented as a JavaScript promise, which lets you chain several request in order to change values inside the ODB in a certain order. If that functionality is not required, the simplified modbset() function can be called, which also implements standard error handling. Two versions of this function exist, one which accepts a single ODB path and a single value, and one which accepts an array of ODB paths and values:

<code>
modbset("odb path", value)
</code>

<code>
modbset(["odb path1", "odb path2", ...], [value1, value2, ...])
</code>

These functions are typically used by custom JavaScript code, like when some value in an experiment exceeds some limit and some action has to be taken like to close a valve. If the call fails (like if mhttpd is dead), a window with an error description is shown.

== modb ==

This special HTML div tag (abbreviation stands for Midas ODB) <code><div name="modb" data-odb-path="/Some/Path" onchange="func()"></code> can be used to call a user-defined function func() if a value in the ODB changes. This function must be defined inline or in a separate <script>...</script> section, and can execute any operation, such as opening a dialog box, hiding/unhiding parts of the custom page, or changing colors and styles of page elements.

The current value of the ODB entry is available inside the "onchange" function as '''this.value'''. Following tag will call a function which logs the current run number in the JavaScript console window:
<br /><br />
<code><div name="modb" data-odb-path="/Runinfo/Run number" onchange="func(this.value)">

<script>function func(value) {
console.log(value);
}</script>
</code>
<br /><br />
If the ODB path does not point to an individual value but to a subdirectory, the whole subdirectory is mapped to '''this.value''' as a JavaSctipt object such as
<br /><br />
<code><div name="modb" data-odb-path="/Runinfo" onchange="func(this.value)">

<script>function func(value) {
console.log(value["run number"]);
}</script>
<br />
</code>
<br /><br />
Note that ODB entries are mapped to JavaScript objects without change. So if an ODB entry name contains a blank, it must be accessed via the JS square bracket '''value["run number"]''' as shown in the above example. Otherwise, the entry can be accessed via the dot notation, such as '''value.state''' for /Runinfo/State for example.

== modbvalue ==

This special HTML div tag (abbreviation stands for "Midas ODB VALUE")
<br /><br />
<code><div name="modbvalue" data-odb-path="/Some/Path"></code>
<br /><br />
is now automatically replaced by the value in the ODB found at the given path and updated regularly as described above Following options are valid for this tag:

{| class="wikitable"
|+ Table 1: List of valid options for modbvalue tag
|-
! Option !! Example !! Meaning
|-
| name || name="modbvalue" || Tells the framework to replace this tag with an ODB value
|-
| data-odb-path || data-odb-path = "/Runinfo/Run number" || Path to the value in the ODB
|-
| data-odb-editable || data-odb-editable="1" || If set, the value is not only shown, but is also clickable for in-line editing. Hitting return send the new value to the ODB.
|-
| data-format || data-format="f3" || Specify format of data shown. See Table 2 below for options.
|}

Table 2 below lists the format specifiers supported with a modbvalue tag <code>data-format="..."</code>:

{| class="wikitable"
|+ Table 2: Format specifiers for modbvalue tag <code>data-format="..."</code>
|-
! Option !! Example !! Meaning
|-
| d || 1234 || Shows a number in decimal encoding
|-
| x || 0x4D2 || Shows a number in hexadecimal encoding
|-
| b || 10011010010b|| Shows a number in binary encoding. Options d, x, b can be combined, like <code>data-format="dxb"</code>
|-
| f<x> || 1.234 || Shows a floating point number with <x> digits after the decimal. A value of f0 shows only the integer part.
|-
| p<x> || 1.23 || Shows a floating point number with <x> significant digits of precision, independent of the decimal. For example a value of p2 can render a number to 12000 or to 0.00012
|}

== modbbutton ==

This tag generates a push-button which can set a certain ODB entry to a specific value. To set the "Run number" to 100, one can use the following tag:
<br /><br />
<code><button name="modbbutton" class="mbutton" data-odb-path="/Runinfo/Run number" data-odb-value="100">[Button Text]</button></code>

== modbcheckbox ==

This tag generates a check box which can set a certain ODB entry to true or false. To set the "Write data" flag for the logger true or false, one can use the following tag:
<br /><br />
<code><input type="checkbox" name="modbcheckbox" data-odb-path="/Logger/Write data" /></code>
<br /><br />
If the ODB value changed by this control is of type integer, its value will be set to 1 or 0.

== modbhbar ==

The following tag:
<br /><br />
<code><div name="modbhbar" style="width: 500px; height: 18px;" data-odb-path="/Runinfo/Run number" data-max-value="10" data-color="lightgreen" ></div></code>
<br /><br />
shows a horizontal bar with a total length of 500px. Depending on the ODB value {{Odbpath|path=Run number}}. If {{Odbpath|path=Run number}} is 10, then the bar is filled all the way to the right, if {{Odbpath|path=Run number}} is 5, the bar is only filled halfway. Following options are possible:

{| class="wikitable"
|-
! Setting !! Meaning !! Required
|-
| style="width: 500px" || Total width of the horizontal bar || Yes
|-
| style="height: 18px" || Height of the horizontal bar || Yes
|-
| style="color: red" || Color of horizontal bar || Transparent if not present
|-
| style="background-color: red" || Background color of horizontal bar || Transparent if not present
|-
| data-odb-path || ODB path of value being displayed || Yes
|-
| data-min-value || Left limit of bar range || 0 if not present
|-
| data-max-value || Right limit of bar range || 1 if not present
|-
| data-log || Logarithmic display || No
|-
| data-print-value || If "1", data value is shown as text overlay || No
|}

== mhaxis ==

A horizontal bar can be combined with an axis with tick marks and labels. The axis can be above or below the bar.

The following tag:
<br /><br />
<code><div name="mhaxis" style="width: 500px; height: 22px;" data-min-value="0" data-max-value="10" ></div></code>
<br /><br />
shows a horizontal axis next to the bar. Following options are possible:

{| class="wikitable"
|-
! Setting !! Meaning !! Required
|-
| style="width: 500px" || Total width of the axis, must match the width of the horizontal bar || Yes
|-
| style="height: 18px" || Height of the axis, must be enough to display labels || Yes
|-
| style="vertical-align: top" || Must be "top" if the axis is below the bar || "bottom" if not given
|-
| data-min-value || Left limit of axis range || Yes
|-
| data-max-value || Right limit of axis range || Yes
|-
| data-log || Logarithmic display || No
|}

== modbvbar ==

Same as <code>modbhbar</code>, except the bar grows vertically instead of horizontally.

== mvaxis ==

Same as <code>mhaxis</code>, except the axis is shown vertically instead of horizontally.

== modbthermo ==

The following tag:
<br /><br />
<code><div name="modbthermo" style="width: 30px; height: 100px;" data-odb-path="/Runinfo/Run number" data-min-value="-10" data-max-value="30" data-color="blue" data-print-value="1" ></div></code>
<br /><br />
shows a vertical thermometer ranging from -10 to 30. Depending on the ODB value {{Odbpath|path=Run number}}. The run number was chosen instead of a real temperature since this ODB variable exists in all midas installations by default, so it's good for testing. Following options are possible:

{| class="wikitable"
|-
! Setting !! Meaning !! Required
|-
| style="width: 30px" || Width of the thermometer || Yes
|-
| style="height: 100px" || Total height of the thermometer || Yes
|-
| data-odb-path || ODB path of value being displayed || Yes
|-
| data-max-value || Upper range || Yes
|-
| data-min-value || Lower range || 0 if not present
|-
| data-color || Color of thermometer || Black if not present
|-
| data-background-color || Color of thermometer background || Transparent if not present
|-
| data-print-value || If "1", data value is shown below the thermometer || No
|-
| data-format || Specifies format of temperature shown below gauge. See Table 2 for options. || No
|}

== modbgauge ==

The following tag:
<br /><br />
<code><div name="modbgauge" style="width: 100px; height: 50px;" data-odb-path="/Runinfo/Run number" data-min-value="0" data-max-value="10" data-color="darkgreen"></div></code>
<br /><br />
shows a circular gauge ranging from 0 to 10. Depending on the ODB value "Run number". Following options are possible:

{| class="wikitable"
|-
! Setting !! Meaning !! Required
|-
| style="width: 100px" || Width of the gauge || Yes
|-
| style="height: 50px" || Total height of the gauge || Yes
|-
| data-odb-path || ODB path of value being displayed || Yes
|-
| data-max-value || Upper range || Yes
|-
| data-min-value || Lower range || 0 if not present
|-
| data-color || Color of gauge || Black if not present
|-
| data-background-color || Color of gauge background || Transparent if not present
|-
| data-print-value || If "1", data value is shown below the gauge || No
|-
| data-format || Specifies format of temperature shown below gauge. See Table 2 for options. || No
|-
| data-scale || If "1", the min and max values of the range are shown below the gauge || No
|}

If the gauge scale is not shown, the gauge height should be half the gauge width. If the scale is shown, 15px must be added to the height.

= mhistory =

Custom pages can contain one or more specific history panels usually shown on the "History" page. This makes it easy to combine current readings of values together with the history of these values.

The following tag:
<br /><br />
<code><div name="mhistory" data-group="<group>" data-panel="<panel>" style="width: 320px; height: 200px;" ></div></code>
<br /><br />
shows a history panel defined in the ODB under /History/Display/<group>/<panel> (replace <group>/<panel> with groups and panels from your experiment).

Following options are possible:

{| class="wikitable"
|-
| data-group || ODB group of history. Has to match a group under /History/Display || Yes
|-
| data-panel || ODB panel name of history. Has to match a panel name under /History/Display/<group>/ || Yes
|-
| data-scale || Time scale of history plot. Use 10m for 10 minutes and 5h for 5 hours. If not specified, the value from the ODB under /History/Display/<group>/<panel>/Timescale is used. || No
|-
| style="width: 320px" || Width of the history panel || No
|-
| style="height: 200px" || Height of the history panel || No
|-
| style="border: 1px solid black" || Border around the history panel || No
|}

If width and height are omitted, the default values of 320px and 200px are used. History panels are automatically updated every 30 seconds.

NOTE: It is planned to change the static history panels to dynamic ones using JavaScript. This will allow users to interactively zoom and scroll through the history with the mouse. The syntax of the "mhistory" tag will however stay the same so it is safe to use this tag now without having to change it after dynamic panels are implemented.

== Changing properties of controls dynamically ==

All custom controls can be changed dynamically (meaning depending on their value) by implementing a '''onchange''' function. This function has access to the current value and can change any of the parameters of the control. Following callback for example changes the color of a thermometer to red if the value is above 30 and to blue if it is below:
<br /><br />
<code>onchange="this.dataset.color=this.value > 30?'red':'blue';"</code>

= Complete Example =

The following code shows an example page (contained in {{Filepath|path=resources/a_example.html}} in the MIDAS distribution) of a custom page implementing most of the new features. You activate this page by putting in the ODB:

<pre>
/Custom
Path /midas/resources
Test a_example.html
</pre>

== Code ==
The file '''a_example.html''' contains the following code:

<pre>
<!DOCTYPE html>
<html class="mcss">
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="midas.css">
<script src="controls.js"></script>
<script src="midas.js"></script>
<script src="mhttpd.js"></script>
<title>Example</title>

<style>
.mtable td { padding: 10px; }
</style>
</head>

<body class="mcss" onload="mhttpd_init('Example');">


<div id="mheader"></div>
<div id="msidenav"></div>

<div id="mmain">
<table class="mtable">
<tr>
<th colspan="2" class="mtableheader">Status</th>
</tr>
<tr>
<td style="width: 200px;">
Run number:
</td>
<td>
<div name="modbvalue" data-odb-path="/Runinfo/Run number" data-odb-editable="1"></div>
</td>
</tr>
<tr>
<td>
Last run start:
</td>
<td>
<div name="modbvalue" data-odb-path="/Runinfo/Start time"></div>
</td>
</tr>
<tr>
<td>
Last run stop:
</td>
<td>
<div name="modbvalue" data-odb-path="/Runinfo/Stop time"></div>
</td>
</tr>
<tr>
<td>
Check box:
</td>
<td>

<input type="checkbox" name="modbcheckbox" data-odb-path="/Logger/Write data"></input>

<div name="modb" data-odb-path="/Logger/Write data" onchange="dlgAlert('Flag has changed');"></div>
</td>
</tr>
<tr>
<td>
Color box:
</td>
<td>

<div name="modbbox" style="width: 30px; height: 30px;" data-odb-path="/Logger/Write data"
data-color="lightgreen" data-background-color="red"></div>
</td>
</tr>
<tr>
<td>
Horizontal bars:
</td>
<td>
<div name="modbhbar" style="width:300px;height:20px;color:orange;" data-odb-path="/Runinfo/Run number"
data-max-value="10" data-print-value="1"></div><br />

<div name="mhaxis" style="width:500px;height:22px;" data-min-value="0" data-max-value="10"></div>
<div name="modbhbar" style="width: 500px; height: 18px;color:lightblue" data-odb-path="/Runinfo/Run number"
data-max-value="10"></div><br />

<div name="modbhbar" style="width: 200px; height: 10px;color:lightgreen;background-color:white"
data-odb-path="/Runinfo/Run number" data-min-value="0.1" data-max-value="10" data-log="1"></div>
<div name="mhaxis" style="width:200px;height:22px;vertical-align:top;" data-min-value="0.1"
data-max-value="10" data-line="0" data-log="1"></div>
</td>
</tr>
<tr>
<td>
Vertical bars:
</td>
<td>
<span name="mvaxis" style="width:100px;height:200px;text-align:right;" data-min-value="0" data-max-value="20"></span><span name="modbvbar"
style="width:20px;height:200px;color:yellow;" data-odb-path="/Runinfo/Run number"
data-min-value="0" data-max-value="20"></span>
<span name="modbvbar" style="width:10px;height:200px;vertical-align:top;color:red" data-odb-path="/Runinfo/Run number" data-min-value="0.1"
data-max-value="10" data-log="1"></span><span name="mvaxis" style="width:100px;height:200px;text-align:left;" data-min-value="0.1"
data-max-value="10" data-log="1"></span>
</td>
</tr>

<tr>
<td>
Thermometer:
</td>
<td>
<div name="modbthermo" style="width:30px;height:100px;" data-odb-path="/Runinfo/Run number" data-min-value="-10" data-max-value="30"
data-color="darkgreen"></div>
<div name="modbthermo" style="width:60px;height:100px;" data-odb-path="/Runinfo/Run number" data-min-value="-10" data-max-value="30"
data-color="blue" data-scale="1"
onchange="this.dataset.color=this.value > 9?'red':'blue';"></div>
<div name="modbthermo" style="width:30px;height:100px;" data-odb-path="/Runinfo/Run number" data-min-value="-10" data-max-value="30"
data-color="blue" data-background-color="white" data-value="1"></div>
</td>
</tr>

<tr>
<td>
Gauges:
</td>
<td>
<div name="modbgauge" style="width:100px;height:50px;" data-odb-path="/Runinfo/Run number" data-min-value="0" data-max-value="10"
data-color="darkgreen" data-background-color="lightgrey" ></div>
<div name="modbgauge" style="width:100px;height:65px;" data-odb-path="/Runinfo/Run number" data-min-value="0" data-max-value="10"
data-color="red" data-value="1" data-scale="1"></div>
</td>
</tr>

<tr>
<td colspan="2" style="text-align: center;">

<div style="position:relative;width:300px;margin:auto">

<img src="tank.gif"> 


<div name="modbvalue" data-odb-path="/Runinfo/Run number" data-odb-editable="1"
style="position:absolute;top:157px;left:288px;"></div>


<div name="modbvbar" style="position:absolute;top:80px;left:10px;width:104px;height:170px;"
data-odb-path="/Runinfo/Run number" data-max-value="11" data-color="green"
onchange="this.firstChild.style.backgroundColor=(this.value > 9)?'red':'green';"></div>


<div name="modbthermo" style="position:absolute;top:140px;left:20px;width:20px;height:100px;"
data-odb-path="/Runinfo/Run number" data-min-value="-10" data-max-value="30"
data-color="blue" data-value="1"></div>

</div>
</td>
</tr>

<tr>
<td colspan="2" style="text-align: center;">

<button name="modbbutton" class="mbutton" data-odb-path="/Runinfo/Run number" data-odb-value="1">Set run
number to 1
</button>
<button name="modbbutton" class="mbutton" data-odb-path="/Runinfo/Run number" data-odb-value="5">Set run
number to 5
</button>
<button name="modbbutton" class="mbutton" data-odb-path="/Runinfo/Run number" data-odb-value="10">Set run
number to 10
</button>
</td>
</tr>
</table>
</div>

</body>
</html>
</pre>

which results in the page shown in Figure 1 below:

[[File:Custom17.png|frame|left|Figure 1 Example custom page using most features]]

<div style="clear: both"></div> 

= Old custom page feature =

There are a number of deprecated custom page features, which can be seen here: [[Old Custom Page Features]].

[[Category:mhttpd Pages]] [[Category:Custom]]

Keys in the ODB /Logger/Channels subtree

2019-05-22T23:09:27Z

Suz:

==== Links ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Keys in the ODB /Logger tree| /Logger tree]]
* [[Keys in the ODB /Logger/SQL subtree |/Logger/SQL subtree]]
* [[/Logger ODB tree #Example | Example /Logger tree]]
* [[mlogger]]
</div>

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

The ODB <span style="color: purple;">''/Logger/Channels''</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.

By default, only '''one''' logging channel with the value 0 if defined (i.e. Logging Channel 0). [[#Multiple Logging Channels | Multiple logging channels]] may be defined by the user.

<br>
-----
<br>

== Multiple Logging Channels ==

By default, only one logging channel is created (Logging Channel 0). To create multiple logging channels, an existing Channel subtree can be copied.

e.g. to create a second logging channel (Channel 1) using [[odbedit]]

[local]cd /Logger
[loca]]logger>cd channels
[local]Channels>ls
0
[local]Channels>copy 0 1
[local]Channels>ls
0
1

If more than one logging channel is defined, there will be a multiple subtrees
* <span style="color: purple;">''/Logger/Channels/0/''</span>,
* <span style="color: purple;">''/Logger/Channels/1/''</span>,
* <span style="color: purple;">''...</span>
present, each with a
[[#Settings subtree|Settings]] and [[#Statistics subtree|Statistics]] subtree.

Thus '''the parameters for each logging channel can be set individually.'''

To send different events to different logging channels, they may be selected by [[#Event ID | Event ID key]] or
[[#Trigger mask | Trigger mask key]].

<br>
-----
<br>

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

The keys in the ODB <span style="color: purple;">''/Logger/Channels/<logging-channel-number>/Settings''</span> subtree are shown below
for the default logging channel 0.

For a single logging channel 0, one subtree
* <span style="color: purple;">''/Logger/Channels/0/Settings''</span>
will be present.

If [[#Multiple Logging Channels | multiple logging channels]] are defined, each
will contain its own ODB <span style="color: purple;">''Settings''</span> subtree,

i.e.
* <span style="color: purple;">''/Logger/Channels/0/Settings''</span>
* <span style="color: purple;">''/Logger/Channels/1/Settings''</span>

<br>
-----
<br>

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

If this ODB key in the [[#Settings subtree|Settings subtree]] is set to "y", this logging channel is active. Data are only logged from channels that are active.
Set to "n" to disable data logging from this channel.

'''Note''' that for data to be logged from any active logging channel, the [[Keys in the ODB /Logger tree #/Logger/Write data |/Logger/Write data key]]
must '''also''' be set to "y".

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

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

This ODB key in the [[#Settings subtree|Settings subtree]] specifies the type of media on which the logging should take place. It can be "Disk", "Tape" or "FTP" (see [[#/Logger/Channels/0/Settings/Filename |Filename key]]).

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

=== <span style="color: purple;">''Filename''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "run%05d.mid"
</div>

This ODB key in the [[#Settings subtree|Settings subtree]] is set up as follows:

; For '''disk''' logging : ODB key <span style="color: purple;">''Filename''</span> specifies the name of a file to contain the data. Default value is "run%05d.mid" where "%05d" is replaced by the current run number in the same way as described for the ODB key [[Keys in the ODB /Logger tree #/Logger/Dump File |/Logger/Dump File]]. If subruns are enabled, the filename may be of the form "run%05d_%02d.mid". See [[subruns]] for details.
; : The key <span style="color: purple;">''Filename''</span> may contain a directory string in addition to a filename, so that different logging channels may have their data logged into specific directories. If the key does NOT also contain a directory string, the directory given in the key [[Keys in the ODB /Logger tree #/Logger/Data dir|/Logger/Data dir key]] will be used. The contents of the key <span style="color: purple;">''Filename''</span> must match that of the [[#/Logger/Channels/0/Settings/Format |Format key]].

;For '''tape''' logging : key <span style="color: purple;">''Filename''</span> specifies a tape device i.e.
<ul>
<li> /dev/nrmt0 or /dev/nst0 under UNIX or </li>
<li> \\.\tape0 under Windows NT. </li>
</ul>
<div style="background-color:mistyrose">WARNING: tape logging is no longer maintained</div>

; FTP mode : the data is written directly to a remote computer via FTP. Key <span style="color: purple;">''Filename''</span> specifies the access information for the FTP server. It has the following format:

<host name>, <port number>, <user name>, <password>, <directory>, <file name>

: for example

myhost.my.domain,21,john,password,/usr/users/data,run%05d.mid

The normal FTP port number is 21, or 1021 for a Unitree Archive like the one used at the Paul Scherrer Institute.

By using the FTP mode, a back-end computer can write directly to the archive.

<br>
-----
<br>

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

This ODB key in the [[#Settings subtree|Settings subtree]] specifies the format to be used for writing the data to the logging channel. It can take one of four values: MIDAS, ROOT, ASCII and DUMP.

For disk logging, the extension for the [[#Filename|Filename]] key above must match one of the following:
<ul>
<li> .mid for MIDAS (or .mid.gz - see [[#Compression | Compression]] key)</li>
<li> .root for ROOT</li>
<li> .asc for ASCII</li>
<li> .txt for DUMP</li>
</ul>

For [[ROOT]] format the data logger will automatically convert the format specified in the [[Explanation of Equipment List Parameters#Format|frontend equipment list]] to ROOT format (see format for details). The ASCII format converts events into readable text format which can be easily analyzed by programs that have problems reading binary data. While the ASCII format tries to minimize the file size by printing one event per line, the DUMP format gives a very detailed ASCII representation of the event including bank information, serial numbers etc., so it should be used mainly for diagnostics.

<br>
-----
<br>

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

This ODB key in the [[#Settings subtree|Settings subtree]] defines the Compression Level of the data. If set to 0, compression is turned off. If set > 0, the data files are compressed before being written. In this case,

* the file extension ".gz" must be appended to the [[#/Logger/Channels/0/Settings/Filename |Filename key]] (see also [[#Format |Format]] key)
* and ZLIB support must be compiled into the MIDAS package (see [[Compilation & Build #NEED_ZLIB |NEED_ZLIB]] ).

This feature applies only to files saved onto disk in [[Event Structure|MIDAS format]]. ROOT format is already compressed.

<br>
-----
<br>

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

If this ODB key in the [[#Settings subtree|Settings subtree]] is set to "y", a complete dump of the ODB is performed to this logging channel before and after every run. The format of the ODB dump is set by the key [[#ODB dump format]]. The ODB content is reflects the status at begin-of-run event and at end-of-run event. These special events have an ID of EVENTID_BOR (0x8000) and EVENTID_EOR (0x8001) (defined in
[http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h.html midas.h]) and a serial number equal to the current run number, and are not visible using the [[mdump]] utility. An analyzer in the off-line analysis stage can use these special events to restore the ODB to its online state.

The dump of the ODB into the event stream for this logger channel is independent of the [[Keys in the ODB /Logger tree #/Logger/ODB Dump |/Logger/ODB Dump key]], which is used to dump the ODB to a file on disk in the [[#ODB dump format|specified format]].

<br>
-----
<br>

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

This ODB key in the [[#Settings subtree|Settings subtree]] defines the format of the ODB Dump file, providing
the ODB key [[#ODB Dump]] is set to "y". The default is now "json" (since March 2019) and the filename of the odb dump file
saved at end-of-run is is "last.json".

Users who wish to use "xml" should set this key to "xml" and [[Keys in the ODB /Logger tree#ODB Last Dump File]] to "last.xml".

<br>
-----
<br>
=== <span style="color: purple;">''Log messages''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 0
</div>

This ODB key in the [[#Settings subtree|Settings subtree]] is a bit-field for logging system messages as message events along with the event data from the experiment.
If a bit in this field is set, the respective system message is written to the logging channel as a message event with an ID of EVENTID_MESSAGE (0x8002) (defined in
[http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h.html midas.h]). The bits are 1 for error, 2 for info, 4 for debug, 8 for user, 16 for log, 32 for talk, 64 for call messages and 255 to log all messages. For an explanation of these messages refer to [[Buffer Manager]] ,
[[#Event ID | Event ID]] key and
[[#Trigger mask | Trigger mask]] key.

<br>
-----
<br>

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

This ODB key in the [[#Settings subtree|Settings subtree]] specifies the buffer where the logger will find the event. It is usually set to "SYSTEM" and is specified in the equipment list for this event.

<br>
-----
<br>

<div id="EventFiltering"></div>
<div id="EventID"></div>
=== <span style="color: purple;">''Event ID ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' -1
</div>

This ODB key in the [[#Settings subtree|Settings subtree]] contains the ID of the event(s) to be logged (see [[MIDAS Event Structure|EventID]]). It is specified in the [[Equipment List Parameters#EventID|Equipment List]] for this event.

To log events with any ID, <span style="color: purple; font-style:italic;">Event ID</span> is set to -1 (EVENTID_ALL). <span style="color: purple; font-style:italic;">Event ID</span> key and/or [[#/Logger/Channels/0/Settings/Trigger mask | Trigger mask ]] key may be used to select events to be sent to different logging channels, or as an [[Event Filtering]] system.

<br>
-----
<br>

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

This ODB key in the [[#Settings subtree|Settings subtree]] specifies which events to log based on the [[MIDAS Event Structure|Trigger Mask]] of the event. It is specified in the [[Equipment List Parameters#TriggerMask|Equipment List]] of this event.

For a logging channel to receive all events, -1 is used for both the
[[#/Logger/Channels/0/Settings/Event ID | Event ID key]]
and the <span style="color: purple;">''Trigger mask''</span> key .

Either the <span style="color: purple; font-style:italic;">Trigger Mask</span> or <span style="color: purple; font-style:italic;">Event ID</span> key may be used to select events to be sent to particular logging channels, or for [[Event Filtering]].

<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:''' 0
</div>

The value of this ODB key <span style="color: purple; font-style:italic;">Event limit</span> in the [[#Settings subtree|Settings subtree]] can be used to stop a run when set to a non-zero value. The statistics value [[#Events written|Events written]] is checked against the <span style="color: purple; font-style:italic;">Event limit</span> value. When this condition is reached, the run is stopped automatically by the data logger [[Mlogger|mlogger]]. The next run can then be started automatically if desired (see [[Keys in the ODB /Logger tree #/Logger/Auto restart|Auto restart]]).

<br>
-----
<br>

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

The value of this ODB key <span style="color: purple; font-style:italic;">Byte limit</span> in the [[#Settings subtree|Settings subtree]] can be used to stop a run when set non-zero. The statistics value [[#Bytes written|Bytes written]] is checked against the <span style="color: purple; font-style:italic;">Byte limit</span> value. When this conditions is reached, the run is stopped automatically by the data logger [[Mlogger|mlogger]]. The next run can then be started automatically if desired (see [[Keys in the ODB /Logger tree #/Logger/Auto restart|Auto restart]]). ).

<br>
-----
<br>

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

The value of the ODB key <span style="color: purple; font-style:italic;">Subrun Byte limit</span> in the [[#Settings subtree|Settings subtree]] can be used to stop a [[subruns|subrun]] when set non-zero. When this condition is reached, the run is stopped automatically by the data logger ([[mlogger]]). The next run can then be started automatically if desired (see [[Keys in the ODB /Logger tree #/Logger/Auto restart |Auto restart]]).

<br>
-----
<br>
=== <span style="color: purple;">''Tape capacity''</span> (obsolete) ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
* '''Default:''' 0
</div>

The value of the ODB key <span style="color: purple; font-style:italic;">Tape capacity</span> in the [[#Settings subtree|Settings subtree]] can be used to stop a run when set to non-zero. The value in the key [[#Bytes written total|Bytes written total]] is checked against the limit set by <span style="color: purple; font-style:italic;">Tape capacity</span>. When this condition is reached, the run is stopped automatically by the data logger.
<div style="background-color:mistyrose;">Warning: writing directly to tape is not maintained</div>
<br>
-----
<br>

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

This ODB key in the [[#Settings subtree|Settings subtree]] optionally specifies a subdirectory, which is appended to the directory string in the key [[Keys in the ODB /Logger/Channels tree #Filename | Filename]].

It is used to place the data log file into a date-stamped subdirectory. This is useful where a large numbers of data files are produced, or experiments are active for a long time, and it is desirable to store the data in sub-directories according to their date. This can be done automatically using the <span style="color: purple; font-style:italic;">Subdir format</span> key.

If the <span style="color: purple;">''Subdir format''</span> key is not empty, the data log file will be placed in a subdirectory. The name of this subdirectory is composed by the given <span style="color: purple;">''Subdir format''</span> string. Its format follows the definition of the system call strftime() . (See man strftime). Ordinary characters placed in the format string are copied to the output character array "s" without conversion. Conversion specifiers are introduced by a '%' character, and are replaced in "s" as follows for the most common ones:

* %Y : Year (ex: 2002)
* %y : Year (range:00..99)
* %m : Month (range: 01..12)
* %d : Day (range: 00..31)

The other characters are: %a, %A, %b, %B, %c, %C, %d, %D, %e, %E, %G, %g, %h, %H, %I, %j, %k, %l, %m, %M, %n, %O, %p, %P, %r, %R, %s, %S, %t, %T, %u, %U, %V, %w, %W, %x, %X, %y, %Y, %z, %Z, %+. (See man strftime for explanation).

<br>
-----
<br>

=== <span style="color: purple;">''Current filename''</span> ===

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

This ODB key in the [[#Settings subtree|Settings subtree]] will reflect the full path of the current saved data file.

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

=== <span style="color: purple;">''Data checksum''</span> ===

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

This ODB key in the [[#Settings subtree|Settings subtree]] can be set to
one of: NONE CRC32C SHA256 SHA512 ZLIB.

See Note on defaults under [[#Compress]] below.
<br>
-----
<br>
<br>

=== <span style="color: purple;">''File checksum''</span> ===

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

This ODB key in the [[#Settings subtree|Settings subtree]] can be set to one of: NONE CRC32C SHA256 SHA512 ZLIB.

See Note on defaults under [[#Compress]] below
<br>
-----
<br>
<br>

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

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

This ODB key in the [[#Settings subtree|Settings subtree]] can be set to one of : none gzip lz4 bzip2 pbzip2.

;Note
The defaults of "free" compression (LZ4) and output file data integrity protected by checksums (CRC32C)
are "free" in the sense that turning
them off would not noticeably improve the system performance. (Some users may want to enable better compression,
such as BZIP2 or PBZIP2 and better checksums, such as SHA256 or SHA512 - both choices that have significant CPU-use cost).
<br>
-----
<br>
<br>

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

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

This ODB key in the [[#Settings subtree|Settings subtree]] can be set to one of: NULL FILE FTP ROOT PIPE.

== <span style="color: purple;">''Statistics''</span> subtree ==
The keys in the ODB <span style="color: purple;">''/Logger/Channels/<logging-channel-number>/Statistics''</span> subtree are shown below
for the default logging channel 0.

For a single logging channel 0, one ODB subtree
* <span style="color: purple;">''/Logger/Channels/0/Statistics''</span>
will be present.

If [[#Multiple Logging Channels | multiple logging channels]] are defined, each
will contain its own ODB <span style="color: purple;">''Statistics''</span> subtree,

i.e.
* <span style="color: purple;">''/Logger/Channels/0/Statistics''</span>
* <span style="color: purple;">''/Logger/Channels/1/Statistics''</span>

<br>
-----
<br>

=== <span style="color: purple;">''Events written''</span> ===

<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
* '''Default:''' 0
</div>

This ODB key in the [[#Statistics subtree|Statistics subtree]] contains the number of events written. Cleared at begin-of-run. <span style="color: purple;">''Events written''</span> statistics are used to determine when to stop a run automatically by checking against the [[#/Logger/Channels/0/Settings/Event limit|Event limit key]].

<br>
-----
<br>

=== <span style="color: purple;">''Bytes written''</span> ===

<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
* '''Default:''' 0
</div>

This ODB key in the [[#Statistics subtree|Statistics subtree]] contains the number of bytes written. Cleared at begin-of-run. <span style="color: purple;">''Bytes written''</span> statistics are used to determine when to stop a run automatically by checking against the [[#Byte limit|Byte limit]] key.

<br>
-----
<br>

=== <span style="color: purple;">''Bytes written uncompressed''</span> ===

<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
* '''Default:''' 0
</div>

If [[#Compression |Compression level]] is 0 (i.e. data not compressed), the values of the ODB keys in the [[#Statistics subtree|Statistics subtree]]
<span style="color: purple;">''Bytes written uncompressed''</span> and [[#/Logger/Channels/0/Settings/Bytes written|Bytes written]] will be identical.

<br>
-----
<br>

=== <span style="color: purple;">''Bytes written total''</span> ===

<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DOUBLE
* '''Default:''' 0
</div>

This ODB key in the [[#Statistics subtree|Statistics subtree]] contains the total number of bytes written. Cleared only when a tape is rewound with the [[odbedit]] command ''rewind''. The <span style="color: purple;">''Bytes written total''</span> entry can therefore be used as an indicator of when a tape is full by checking against the limit [[#/Logger/Channels/0/Settings/Tape Capacity|Tape Capacity]].
<div style="background-color:mistyrose;">Warning: writing directly to tape is not maintained</div>

<br>
-----
<br>

=== <span style="color: purple;">''Files written''</span> ===

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

This ODB key in the [[#Statistics subtree|Statistics subtree]] contains the number of files written. Cleared only when a tape is rewound with the [[odbedit]] command ''rewind''. <span style="color: purple;">''Files written''</span> value can be used off-line to determine how many files on a tape have to be skipped in order to reach a specific run.
<div style="background-color:mistyrose;">Warning: writing directly to tape is not maintained</div>

[[Category:Logger Tree]]

Keys in the ODB /Logger tree

2019-05-22T22:44:17Z

Suz:

{{Pagelinks}}

==== Links ====
<div style="column-count:4;-moz-column-count:4;-webkit-column-count:4">
* [[/Logger ODB tree| /Logger tree]]
* [[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]]
* [[Keys in the ODB /Logger/History subtree |/Logger/History subtree]]
* [[/History ODB tree]]
* [[mlogger |MIDAS logger (mlogger)]]
</div>
<br>
---------------
<br>
== Keys in the <span style="color: purple;">''/Logger''</span> tree ==
=== <span style="color: purple;">''Data dir''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' <Path of experiment given in [[exptab]] >
</div>

This key in the ODB [[#top|/Logger tree]] specifies in which directory files produced by the MIDAS logger utility ([[mlogger]]) should be written.
Once mlogger is running , the key <span style="color: purple;">''Data dir''</span> will be pointing to the location of

* the data file(s) (unless overruled by the [[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/Filename | Filename ]] key(s) ),
* the message log file (unless overruled by [[#/Logger/Message File | Message File]]),
* the ODB dump files (unless overruled by [[#/Logger/ODB Dump File | ODB Dump File]]),

* and the optional
** elog files (unless overruled by [[#/Logger/Elog dir|Elog dir]]),
** [[History System|MIDAS history files]] (unless overruled by [[#/Logger/History dir | History Dir]])

It is preferable to use a full directory path for this key (i.e. "''/home/username/online/data''" rather than a relative path, such as the current directory "''./''"). If set to the current directory, running a client such as [[odbedit]] from a different directory will result in a second midas.log file created in that directory.

When '''[[#Multiple Logging Channels| multiple logging channels]]''' are enabled,
by default, the data path for <b>all</b> the defined logging channels is set to the same location, given by the <span style="color: purple;">''Data dir''</span> key.
However, the data from individual logging channels can also be saved in different locations, using
the ODB key <span style="color: purple;">''/Logger/Channels/<channel-number>/Settings/Filename''</span>
for each defined logging channel (channel number 0,1...).

The [[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/Filename | Filename key]] for each enabled logging channel can contain the full path of the location of the ''.mid, .ybs, .asc'' data file.

If the latter key contains the full directory path (i.e. contains the OS specific <b>DIR_SEPARATOR</b> (e.g. "/" for Linux or "\" for Windows),
then the global key <span style="color: purple;">''Data dir''</span> will be overruled by the setting for that particular channel.

For example,
<ul>
<li>If key [[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/Filename | Filename ]] contains <em>"run%05.mid"</em>. key <span style="color: purple;">''Data dir''</span> will <b>not</b> be overruled</li>
<li>If key [[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/Filename | Filename ]] contains <em>"/data1/ch1log/run%05.mid"</em>. key <span style="color: purple;">''Data dir''</span> <b>will</b> be overruled </li>
</ul>

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

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

This key in the ODB [[#top|/Logger tree]] specifies the filename of the [[Message System#MIDAS Log file|MIDAS Message log file]] .

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

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

When this key in the ODB [[#top|/Logger tree]] is set to "y" (i.e. TRUE), a new run is automatically restarted when the previous run has been stopped by the MIDAS logger ([[mlogger]])
due to an event or byte limit.

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

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

Providing [[#Auto restart|Auto restart key]] is set TRUE, the automatic start of the next run will be delayed by the number of milliseconds specified by this key in the ODB [[#top|/Logger tree]].

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

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

This key in the ODB [[#top|/Logger tree]] allows for runs with a certain duration. To use this option, the user creates and sets this variable to a non-zero '''integer''' value (in seconds). After a run has lasted for this duration, it will be stopped automatically by the MIDAS logger ([[mlogger]]). To automatically produce sequences of runs all with the same duration, also set the
[[#/Logger/Auto restart|/Logger/Auto restart key]] to "y"

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

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

Data logging is enabled when this key in the ODB [[#top|/Logger tree]] is set to "y". It can be set to "n" (FALSE) temporarily to make a short test run without data logging.
This key is a predefined key for enabling data logging.

Note that the [[Keys in the ODB /Logger/Channels tree #Active | Active key]] (in the appropriate
[[Keys in the ODB /Logger/Channels tree #Settings subtree |logging channel subtree ]] )
must <b>also</b>
be set to "y" for the data from that channel to be logged.

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

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

If this key in the ODB [[#top|/Logger tree]] is set to "y", a dump of the complete ODB will be written to the file specified by the key [[#ODB Dump file|ODB Dump file]] at the end of each run.
<ul>

;NOTE
<li>The ODB contents is <b>always</b> saved into a file (default is "last.json") at the beginning of each run regardless of the setting of this key.</li> The format is specified by the [[Keys in the ODB /Logger/Channels subtree#ODB dump format]] key.

<li>The ODB contents can also be saved into the data stream as an event (see [[Keys in the ODB /Logger/Channels tree #ODB Dump|ODB Dump per logging channel]]). </li>
</ul>

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

=== <span style="color: purple;">''ODB Dump File ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "run%05d.json"
</div>

This key in the ODB [[#top|/Logger tree]] specifies the filename in which the dump of the complete ODB will be
written at the end of each run if the [[#ODB Dump]] key is set to "y". The default for the format of the file
is now json (since March 2019). Previously it was "run%05d.odb", with the format being xml by default.

If this filename contains a "%", the "%" will be replaced by the current run number (cf. format string of printf() C function). The format specifier "%05d" from the example would be evaluated to a five digit run number with leading zeros e.g. run00002.json. The ODB dump file can be used for off-line analysis to check run parameters etc. (See also
[[Keys in the ODB /Logger/Channels tree #/Logger/Channels/0/Settings/ODB Dump | ODB Dump per logging channel]]).

<ul>
<li><b>Note:</b> The location of the ODB dump files can also be specified in this field. If the ODB Dump File string contains a DIR_SEPARATOR,
it is considered as an absolute path. If no DIR_SEPARATOR is present, the dump file will be written to the location given by [[#Data dir |Data dir key]].
</li>
</ul>

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

=== <span style="color: purple;">''ODB Last Dump File ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "last.json"
</div>

This key in the ODB [[#top|/Logger tree]] contains the filename of the odb dump file last saved. It is always saved, independent of the setting of the key [[#ODB Dump]].

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

This key in the ODB [[#top|/Logger tree]] is obsolete. Use [[Keys in the ODB /Logger/History subtree#/Logger/History/0/Active|Active]] key instead.

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

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

If this key in the ODB [[#top|/Logger tree]] is set to "y", MIDAS messages during mounting tapes and writing of EOF marks are generated. This can be useful all users in a counting house to be informed about the tape status.

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

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

This key in the ODB [[#top|/Logger tree]] is now obsolete. It has been replaced by [[Keys in the ODB /Logger/History subtree#/Logger/History/1/Debug|Debug]] key.

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

=== <span style="color: purple;">''ODBC DSN''</span> (obsolete) ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the ODB [[#top|/Logger tree]] is now obsolete. It has been replaced by [[Keys in the ODB /Logger/History subtree#/Logger/History/1/Writer_ODBC_DSN|Writer_ODBC_DSN]] key.

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

=== <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 in the ODB [[#top|/Logger tree]] is used to reassign the location of the saved [[Keys in the ODB /Logger/History subtree#/Logger/History/0/Type|MIDAS type]] history files from the default location given by the [[#Data dir |Data dir key]].

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

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

This optional key in the ODB [[#top|/Logger tree]] is used to reassign the location of the saved Elog files from the default location given by the [[#Data dir |Data dir key]].

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

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

This optional key in the ODB [[#top|/Logger tree]] contains the duration in seconds for each [[subruns|subrun]]. After this time, a new subrun will be started by the MIDAS logger [[mlogger]].

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

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

This key in the ODB [[#top|/Logger tree]] allows the user to manually request a new [[subruns|subrun]]. The MIDAS logger ([[mlogger]]) will stop the present subrun and start a new one. The key
<span style="color: purple;">''Next subrun''</span> will be set false.

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

== <span style="color: purple;">''/Logger/Channels''</span> subtree ==
* '''Type:''' DIR

This subdirectory is created and used by the [[mlogger]] utility for data logging. See [[Keys in the ODB /Logger/Channels subtree| /Logger/Channels subtree]].

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

== <span style="color: purple;">''/Logger/SQL''</span> subtree ==
* '''Type:''' DIR

Optional directory in the ODB [[#top|/Logger tree]] for [[logging to a mySQL database]]. This ODB subtree will be created if mySQL support has been [[Building options |built into]] the [[mlogger|MIDAS logger]].

See [[Keys in the ODB /Logger/SQL subtree| /Logger/SQL subtree]]

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

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

This subdirectory in the [[#top|/Logger tree]] is created by the [[mlogger]] utility and used by the [[History System]].

See [[Keys in the ODB /Logger/History subtree |keys in /Logger/History subtree]]

[[Category:Data Logging]]

Template:Pagelinks

2018-12-12T00:32:40Z

Suz:

<noinclude>
Usage: {{Pagelinks}}
</noinclude>
<div style="column-count:7;-moz-column-count:6;-webkit-column-count:6">
* [[Midas_documentation|Midas Doc]]
* [[Feature_listing|Feature Listing]]
* [[Application_listing|Application Listing]]
* [[Online_Database|Online Database]]
* [[FAQ|FAQ]]
* [[:Category:Contents|Index]]
</div>
<br>

FAQ

2018-11-29T22:30:29Z

Suz:

{{Pagelinks}}

= Frequently Asked Questions =

There is a related page of [[Installation/Compilation problems|Common Installation Problems]].
__FORCETOC__

== How to recover from a corrupted ODB ==

* Stop your front-ends, [[mlogger]], [[mhttpd]], etc.
* Remove the shared memory associated to ODB buffer. Find the shared memory segment by doing
ls -l /dev/shm
then remove the segment that will be something like /dev/shm/*_test_ODB_SHM
where "test" is the experiment name.
* Move the old ODB files. These will be in the location given by [[Exptab]], e.g. ~/online
cd online
mv .ODB.SHM .ODB.SHM.BAD
* Restart ODB with larger size using [[odbedit]] e.g.
odbedit -s 100000000
* Reload the last saved ODB dump you have (see [[ODB#Save and reload the ODB|save and reload the ODB]]). These dumps are typically called something like 'online/history/*.xml'.
So from {{Utility|name=odbedit}} you do something like
odbedit> load history/run00071.xml
* Your ODB should now be fixed.

Note that sometimes it seems that you also need to remove the buffers associated with the system messages (called SYSMSG) as well as the buffers associated with the ODB.

See also [[odbinit]].

== How to get odbedit to show run state ==

Question: I've seen the ODB prompt displaying the run state, how do you do that?

Answer: Modify the /System/prompt field. The "S" is the trick.

<pre>
Fri> odb -e bnmr1 -h isdaq01
[host:expt:Stopped]/cd /System/
[host:expt:Stopped]/System>ls
Clients
Client Notify 0
Prompt [%h:%e:%S]%p
Tmp
[host:expt:Stopped]/System
[host:expt:Stopped]/Systemset prompt [%h:%e:%S]%p>
[host:expt:Stopped]/System>ls
Clients
Client Notify 0
Prompt [%h:%e:%S]%p>
Tmp
[host:expt:Stopped]/System>set Prompt [%h:%e:%s]%p>
[host:expt:S]/System>set Prompt [%h:%e:%S]%p>
[host:expt:Stopped]/System>
</pre>

See also [[/System ODB tree#Prompt]].

== Increasing Number of Hot-links ==

MIDAS, by default, allows you to have a maximum of 256 individual [[Event Notification (Hot-Link)|hot-links]] to be registered. If you find that you need more hot-links than that, follow the procedure below:

<ol>
<li> Use odbedit to save current ODB
<pre>
odbedit
save current_odb.odb
</pre>
<li> Stop all the running MIDAS processes, including mlogger and mserver using the web
interface. Then stop mhttpd as well. To stop mhttpd just do

<pre>
killall mhttpd
</pre>

<li> Remove your old ODB (we will recreate it after modifying MIDAS, using the backup you just
made).
<pre>
mv .ODB.SHM .ODB.SHM.20161104
rm /dev/shm/<expname>_ODB_SHM
</pre>

where <expname> is the name of your experiment.

<li> Make the following modifications to midas. In this particular case I have increased the
max number of open records from 256 to 1024. You would need to change the constants if you
want to change to other values
<pre>
diff --git a/include/midas.h b/include/midas.h
index 02b30dd..33be7be 100644
--- a/include/midas.h
+++ b/include/midas.h
@@ -254,7 +254,7 @@ typedef std::vector<std::string> STRING_LIST;
-#define MAX_OPEN_RECORDS 256 /**< number of open DB records */
+#define MAX_OPEN_RECORDS 1024 /**< number of open DB records */
diff --git a/src/odb.c b/src/odb.c
index 47ace8f..ac1bef3 100755
--- a/src/odb.c
+++ b/src/odb.c
@@ -699,8 +699,8 @@ static void db_validate_sizes()
- assert(sizeof(DATABASE_CLIENT) == 2112);
- assert(sizeof(DATABASE_HEADER) == 135232);
+ assert(sizeof(DATABASE_CLIENT) == 8256);
+ assert(sizeof(DATABASE_HEADER) == 528448);
</pre>
The calculation is as follows (in case you want a different number of open records):
DATABASE_CLIENT = 64 + 8*MAX_OPEN_ERCORDS = 64 + 8*1024 = 8256
DATABASE_HEADER = 64 + 64*DATABASE_CLIENT = 64 + 64*8256 = 528448

<li> Rebuild MIDAS
<pre>
cd $MIDASSYS
make clean; make
</pre>

<li> Create new ODB
<pre>
odbedit -s 1000000
</pre>
Note, you should change the size of the ODB to whatever you need.

<li> reload your original ODB
<pre>
[local:exp:Stopped] load current_odb.odb
</pre>

<li> Rebuild all your frontend programs (and other user-specific programs) against new MIDAS; they should then work and you should be able to produce more open records.
</ol>

[[Category:Troubleshooting]]

Odbinit

2018-11-21T00:35:59Z

Suz: Created page with "{{Pagelinks}} = Links = <div style="column-count:3;-moz-column-count:3;-webkit-column-count:3"> * odbedit command list * Odbedit examples * Using the ODB * ..."

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[odbedit command list]]
* [[Odbedit examples]]
* [[ODB|Using the ODB]]
* [[mhttpd]] webserver
* [[Online Database|ODB structure]]
</div>

= Purpose =
The utility {{Utility|name=odbinit}} initializes the ODB.

;NOTE
: Normally, <span style="color:darkcyan;font-style:italic">odbedit</span> is sufficient to [[FAQ#How to recover from a corrupted ODB|recover from a corrupted ODB]]

However, if this does not solve the problem, it may be necessary to use {{Utility|name=odbinit}}, then reload the contents of the ODB from a saved file.
= Usage =
<pre>
[mpet@titan01 ~/online_npet]$ odbinit -h
Checking environment... experiment name is "npet", remote hostname is ""
usage: odbinit [options...]
options:
[-e Experiment] --- specify experiment name
[-s size] --- specify new size of ODB in bytes, default is 1048576
[--env] --- create new env.sh and env.csh files in the current directory
[--exptab] --- create new exptab file in the current directory
[--cleanup] --- cleanup (preserve) old (existing) ODB files
[-n] --- dry run, report everything that will be done, but do not actually do anything
</pre>

= Example =
In this case, the ODB shared memory is corrupted, and the .ODB.SHM has been recreated with a size of 0.
<pre>
[mpet@titan01 ~/online_npet]$ ls -l .ODB.SHM
-rw-r--r-- 1 mpet users 0 Nov 20 14:44 .ODB.SHM

[mpet@titan01 ~/online_npet]$ odbinit
Checking environment... experiment name is "npet", remote hostname is ""
Checking command line... experiment "npet", cleanup 0, dry_run 0, create_exptab 0, create_env 0
Checking MIDASSYS....../home/mpet/packages/midas_nov2018
Checking exptab... experiments defined in exptab file "/home/mpet/online/exptab":
0: "mpet"
1: "npet" <-- selected experiment
2: "test"

Checking exptab... selected experiment "npet", experiment directory "/home/mpet/online_npet/"

Checking experiment directory "/home/mpet/online_npet/"
Found existing ODB save file: "/home/mpet/online_npet/.ODB.SHM"
Looks like this experiment ODB is already initialized.
To create new empty ODB, please rerun odbinit with the "--cleanup" option.
[mpet@titan01 ~/online_npet]$
[mpet@titan01 ~/online_npet]$ odbinit --cleanup
Checking environment... experiment name is "npet", remote hostname is ""
Checking command line... experiment "npet", cleanup 1, dry_run 0, create_exptab 0, create_env 0
Checking MIDASSYS....../home/mpet/packages/midas_nov2018
Checking exptab... experiments defined in exptab file "/home/mpet/online/exptab":
0: "mpet"
1: "npet" <-- selected experiment
2: "test"

Checking exptab... selected experiment "npet", experiment directory "/home/mpet/online_npet/"

Checking experiment directory "/home/mpet/online_npet/"
Found existing ODB save file: "/home/mpet/online_npet/.ODB.SHM"

Checking shared memory...
Deleting old ODB shared memory...
Deleted existing ODB shared memory, please check that all MIDAS programs are stopped and try again.
[mpet@titan01 ~/online_npet]$
[mpet@titan01 ~/online_npet]$
[mpet@titan01 ~/online_npet]$
[mpet@titan01 ~/online_npet]$ odbinit --cleanup
Checking environment... experiment name is "npet", remote hostname is ""
Checking command line... experiment "npet", cleanup 1, dry_run 0, create_exptab 0, create_env 0
Checking MIDASSYS....../home/mpet/packages/midas_nov2018
Checking exptab... experiments defined in exptab file "/home/mpet/online/exptab":
0: "mpet"
1: "npet" <-- selected experiment
2: "test"

Checking exptab... selected experiment "npet", experiment directory "/home/mpet/online_npet/"

Checking experiment directory "/home/mpet/online_npet/"
Found existing ODB save file: "/home/mpet/online_npet/.ODB.SHM"

Checking shared memory...
Deleting old ODB shared memory...
[system.c:1015:ss_shm_delete,ERROR] shm_unlink(/npet_ODB_SHM) errno 2 (No such file or directory)
Good: no ODB shared memory
Deleting old ODB semaphore...
Deleting old ODB semaphore... create status 1, delete status 1
Preserving old ODB save file /home/mpet/online_npet/.ODB.SHM" to "/home/mpet/online_npet/.ODB.SHM.1542755393"

Checking ODB size...
Requested ODB size is 0 bytes
ODB size file is "/home/mpet/online_npet//.ODB_SIZE.TXT"
ODB size file "/home/mpet/online_npet//.ODB_SIZE.TXT" does not exist, creating it...
Saved ODB size from "/home/mpet/online_npet//.ODB_SIZE.TXT" is 1048576 bytes
We will initialize ODB for experiment "npet" on host "" with size 1048576 bytes

Creating ODB...
Creating ODB... db_open_database() status 302
Saving ODB...
Saving ODB... db_close_database() status 1
Connecting to experiment...

Connected to ODB for experiment "npet" on host "" with size 1048576 bytes
Checking experiment name... status 1, found "npet"
Disconnecting from experiment...

Done
</pre>
Now [[ODB Access and Use#Save and reload the ODB|reload the ODB]] from a saved file using the {{Utility|name=odbedit}} command "load".

[[Category:Utilities]]

ODB Access and Use

2018-11-21T00:24:59Z

Suz:

{{Pagelinks}}
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[odbedit]]
* [[Odbedit command list]]
* [[mhttpd]] ODB page
* [[Online Database|ODB structure]]
*
</div>
= Purpose =
This page gives details on how users may access and use the ODB.

= Introduction =
The MIDAS Online Data Base (ODB) is the main communication platform between MIDAS applications. It contains all the information needed to run an experiment. A description of [[Online Database#The ODB Structure|the ODB Structure]] and a list of all the ODB trees used by the system can be found in [[Online Database]].

= ODB Keys =

The ODB is hierarchically structured, similar to a file system, with directories and sub-directories (or trees and subtrees). The data are stored in key/data pairs, similar to the Windows NT registry. ODB keys can be dynamically created and deleted. The data associated with a key can be of different types such as: byte, words, double words, float, strings, etc. or arrays of any of those.

A key can also be a directory or a symbolic link. ODB Key names are '''case-independent''', and '''may contain spaces'''.

As of Jan 2017, ODB key names are now checked to ensure they are UTF-8 compliant. This check will show up in (at least) two ways:

# Attempts to create a new ODB variable if the ODB key is not UTF-8 compliant.
# When a program first connects to the ODB, it runs a check to ensure that the ODB is valid. This will now include a check that all key names are UTF-8 compliant. Any non-UTF8 compliant key names will be replaced by a string of the pointer to the key.

This behaviour (checking UTF-8 compatibility and automatically fixing ODB names) can be disabled by setting an environment variable

MIDAS_INVALID_STRING_IS_OK

It doesn't matter what the environment variable is set to; it just needs to be set. Note also that this variable is only checked once, when a program starts.

<br>

= Accessing the ODB =

The MIDAS ODB can be accessed '''interactively''' in two ways:
* [[odbedit|odbedit application]] command line.
* Midas server [[mhttpd]] ODB page

For non-interactive access,
* The MIDAS library provides a complete '''set of functions''' (in C/C++) to manage and operate on ODB keys (see [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/group__odbfunctionc.html odb functions]).
Examples of many of these routines in use can be found in [[Frontend user code]].

* Scripts can easily access the odb using the [[odbedit]] ''-c'' argument. Examples of this can be found in [[#Accessing the ODB from a script|Script Access]]

* A set of Javascript functions are provided to allow the web server [[Custom Page|Custom Pages]] to access the ODB.

= Creating the ODB =

After installation of MIDAS, before any other applications are started, the ODB must be created by the user (see [[odbedit #Creating the ODB|creating the ODB ]]). Running [[odbedit]] to create the ODB also causes the trees [[/Runinfo ODB tree|/Runinfo]], [[/Experiment ODB tree|/Experiment]], [[/System ODB tree|/System]] to be created and filled with default values. Other system applications will automatically create their own initial ODB structure
filled with default values (for example, the [[mlogger|data logger]] creates the [[/Logger ODB tree]]. The user may then modify these configurations to fit his/her requirements (see [[#Customizing|customizing]]). A list of the trees in the ODB used by the system can be found [[Online Database|here]].

== Shared-memory files ==
[[odbedit #Creating the ODB|Creating the ODB ]]also creates
all the shared-memory files needed for the experiment (see list below). By default, these files will be created in the area indicated in the [[exptab]] file for your experiment.
<pre>
.ALARM.SHM .ELOG.SHM .HISTORY.SHM .MSG.SHM .ODB.SHM .SYSMSG.SHM .SYSTEM.SHM
</pre>

= Customizing the ODB =
The user customizes the ODB for their experiment by modifying the values of "system" parameters (e.g. [[Keys in the ODB /Logger tree]], or adding extra keys under existing trees as needed, e.g. "Edit on Start" parameters under the [[/Experiment ODB tree]]. The user may creates "optional" trees e.g. ([[/Script ODB tree]], [[/Custom ODB tree]]) populating them with keys as required.
The user is also free to create his/her own tree structure under root (/) for his/her own purposes.

== Creating ODB keys ==

The easiest way to create, set (and delete if necessary) [[#ODB Keys|ODB keys]] is to use the [[ODB Page]] of the web server [[mhttpd]]. This also includes creating '''subdirectories''' and '''symbolic links'''. See [[ODB Page#Create an ODB key]] for details.

Alternatively, [[odbedit]] can be used as demonstrated in the following example. [[Odbedit]] is more powerful, also allowing the user to for example re-order, copy or rename the keys (see [[odbedit command list]]).

Once a directory is created, keys can be created of the types supported by MIDAS (see [[Midas Data Types]]), e.g. INT DWORD BOOL FLOAT DOUBLE STRING. Arrays of all these types can also be created. Values are then assigned to the keys using the {{Odbedit cmd|cmd=set}}.

=== Example ===
This example shows how to create an ODB tree (<span style="color:purple; font-style:italic">/Custom</span>) using [[odbedit]]. Creating the same tree using the [[ODB Page]] is easy (see [[ODB Page#Create an ODB key]] for more information).

The [[odbedit]] commands are shown in red. Comments are shown in green and preceded by a "#".
$ odbedit
[local:midas:S]/>pwd <span style="color:green; font-style:normal"># show current directory (tree) </span>
/
[local:midas:S]/><span style="color:red; font-style:normal">mkdir custom/images</span> <span style="color:green; font-style:normal"># make directory "custom" and subdirectory "images"</span>
[local:midas:S]/><span style="color:red; font-style:normal">ls</span> <span style="color:green; font-style:normal"># list all keys</span>
System
Programs
Experiment
Runinfo
Alarms
Custom
[local:midas:S]/><span style="color:red; font-style:normal">cd custom </span> <span style="color:green; font-style:normal"># change directory to "/custom" </span>
[local:midas:S]/custom><span style="color:red; font-style:normal">ls</span>
images
[local:midas:S]/custom><span style="color:red; font-style:normal">create string "custom page&"</span> <span style="color:green; font-style:normal"># Create a key of type STRING. Note use of quotes as key name contains a space </span>
String length [32]: 128
[local:midas:S]/custom><span style="color:red; font-style:normal">set "custom page&" /home/midas/custom/custom.html</span> <span style="color:green; font-style:normal"># Set key to a value.
# Could type instead "set cus" followed by tab to demonstrate tab-completion </span>
[local:midas:S]/custom><span style="color:red; font-style:normal">ls -r</span> <span style="color:green; font-style:normal"># list recursively </span>
custom
images
custom page& /home/midas/custom/custom.html

== Creating arrays ==
Creating arrays in the ODB is simple using the [[ODB Page]] (see [[ODB Page#Create an ODB key]] for more information).

The following example demonstrates the use of [[odbedit]] to create an array, set its elements to various value, and expand it. An array can be truncated using the [[odbedit]] ''trunc'' command.
[local:pol:S]/test>create int fred[5]
[local:pol:S]/test>set fred[*] 5
[local:pol:S]/test>set fred[1..3] 6
[local:pol:S]/test>set fred[8] 9
[local:pol:S]/test>ls
fred
5
6
6
6
5
0
0
0
9

== Reordering ODB keys ==
Sometimes it may be desired to reorder the ODB keys once created. This must be done using [[odbedit]].

The {{Odbedit cmd|cmd=move}} is used for this purpose as in the following example:

The key "custom" can be moved to the top (or bottom) of the list, e.g.

[local:midas:S]/>ls
System
Programs
Experiment
Runinfo
Alarms
Custom

The key "Custom" can be moved to the top

[local:midas:S]/>move custom top
[local:midas:S]/>ls
Custom
System
Programs
Experiment
Runinfo
Alarms

or to any position, e.g.

[local:midas:Stopped]/>move custom 1
[local:midas:Stopped]/>ls
System
Custom
Programs
Experiment
Runinfo
Alarms

== Create a subdirectory in the ODB ==
Creating a subdirectory is very easy to do using the [[ODB Page]]. See [[ODB Page#Create an ODB key|Create an ODB key]].

Using [[odbedit]], select the desired directory using {{Odbedit cmd|cmd=cd}} then make the directory with {{Odbedit cmd|cmd=mkdir}} e.g.

[local:test:S]cd /Experiment
[local:test:S]mkdir "edit on start"

== Create a symbolic link in the ODB ==
Creating a symbolic link is easy to do using the [[ODB Page]]. See [[ODB Page#Create an ODB key|Create an ODB key]].

Creating the same symbolic link with [[odbedit]]
[local:test:S]cd /Experiment/edit on start
[local:test:S]Edit on Start> ln "/logger/write data" "write data"
[local:test:S]Edit on Start> ls
write data -> /logger/write data
y

= Save and reload the ODB =
The ODB can be saved at its current position in several formats (ascii, xml as a c structure) using the [[odbedit]] ''save'' command, and reloaded from a saved file with the [[odbedit]] ''load'' command.
; NOTE
: JSON format has been added (January 2016). See [[#JSON]].

e.g. to save the ODB into a file in the local directory in ASCII format :
<pre>
[local:exp:Stopped]/>save my_exp.odb
</pre>
and to load the ODB from a previously saved file in the local directory :
<pre>
[local:npet:Stopped]/>load saved.odb
</pre>
Since the ODB may become [[#Corrupted ODB|corrupted]], a copy is saved automatically at the beginning of each run. Since this file is overwritten each time, users often also save a copy (that will not be overwritten) at the end of each run (see [[Keys in the ODB /Logger tree#ODB Dump|ODB Dump]]) along with the data for that run. (The ODB contents can also be sent to the logging channel and saved with the run data - see [[Keys in the ODB /Logger/Channels tree #ODB Dump|ODB Dump in /Logger/Channels subtree]]).

Users can then return their ODB to the state it was in for any particular run.

The entire database need not be loaded. Saved ASCII files can be made of just a part of the database, and these can be reloaded into the database. Since the full path is given in the saved file, the file can be loaded from any position in the database.

The saved ASCII file may of course be edited prior to loading, if keynames or values need to be changed. If the keys in the load file do not exist, they will be created. If they do exist, the values from the file will be loaded.

= '''experim.h''' include file =

The [[odbedit]] '''make''' command creates "''experim.h''", a file containing a C structure and ascii representation of part of the ODB. The file is created in the current directory.
e.g.
[local:midas:S]/>make
Analyzer "Analyzer" not found in ODB, skipping analyzer parameters.
"experim.h" has been written to /home/midas/online

The file ''experim.h'' contains C structures for the ODB trees <span style="color:purple; font-style:italic">/Experiment, /Analyzer/Parameters</span>, and <span style="color:purple; font-style:italic">/Equipment/<equipment-name>/Settings</span> if these trees are present. All C structures are accompanied by a string representation which can be used in the ''db_create_record'' function to setup an ODB structure which matches the required C structure, ensuring that the required keys are present in the ODB (see
[[Frontend user code#Function begin_of_run|Frontend]] or [[Event Notification (Hot-Link)#How to set up a Hot-Link|setting up a hot link]]).

If the name of the analyzer is not the default (i.e. "Analyzer"), then in order to include the analyzer section, the ODB key <span style="color:purple; font-style:italic">/<Analyzer-name>/Parameters</span> has to be present, where <Analyzer-name> is the name of the analyzer.

The command used is then "make <Analyzer-name> ".

An example ''experim.h'' can be found at
[http://ladd00.triumf.ca/~daqweb/doc/midas/examples/Triumf/c/experim.h].

= JSON =
New commands have been added (January 2016) which correspond to JSON encoding of ODB data see [[mjsonrpc#JSON encoding of ODB data]].
The command {{Odbedit cmd|cmd=json}} encodes all ODB data and metadata. ODB can be fully reloaded or restored from ODB JSON save files.
<pre>
$ odbedit
[local:js:S]>cd /Equipment/rpcexample/variables
[local:js:S]Variables>ls
SLOW
1273
1376610644
74.31448279461522
[local:js:S]Variables>json
status: 1, json: {
"SLOW/key" : { "type" : 10, "num_values" : 3, "access_mode" : 7, "last_written" : 1448506616 },
"SLOW" : [ 1273, 1376610644, 7.4314482794615216e+01 ]
}
</pre>
The {{Odbedit cmd|cmd=jsls}} encodes a single ODB directory and returns the full information printed by the {{Odbedit cmd|cmd=ls -l}}.
<pre>
[local:js:S]Variables>jsls
jsls "/Equipment/RpcExample/Variables", status: 1, json: {
"SLOW/key" : { "type" : 10, "num_values" : 3, "access_mode" : 7, "last_written" : 1448506616 },
"SLOW" : [ 1273, 1376610644, 7.4314482794615216e+01 ]
}
</pre>
The {{Odbedit cmd|cmd=jsvalues}} list the data in a format for exporting ODB data to web pages: links are followed to their final values and ODB key names are converted to lower case for use with case-sensitive languages such as Javascript.
<pre>
[local:js:S]Variables>jsvalues
status: 1, json: {
"slow/name" : "SLOW",
"slow/last_written" : 1448506616,
"slow" : [ 1273, 1376610644, 7.4314482794615216e+01 ]
}
</pre>
= Corrupted ODB =
If the ODB becomes corrupted, [[odbedit]] may no longer work, and other clients will also fail to open the database. In this case, the old ODB should be deleted and a new one created. The contents of the ODB can be reloaded from a [[#Save and reload the ODB|saved ODB file]].
Follow the instructions in [[Recovery from Corrupted ODB]].

= Accessing the ODB from a script =
The external command feature of [[odbedit]] (see [[Odbedit#Using an external command]]) allows for sophisticated scripts to be created that can manipulate the ODB.
Such scripts can for example

* check ODB parameters prior to beginning of run
* send run parameters to the electronic logbook
* set some ODB parameters when a script button on the [[mhttpd]] main status page is pressed
* load a particular saved odb file when a button on a custom page is pressed (e.g. load a "tune")

Examples of shell scripts that may send [[odbedit]] commands :

* script run at end-of-run or begin-of-run (see [[#Example end-of-run script|below]])
* script run when a [[/Script ODB tree#Script-button|script-button]] or [[Custom Page Features#CustomScript Buttons|Customscript button]] is pressed

Script writers may find it useful to [#Message Page and message log|send messages to the MIDAS message log]] to indicate progress or error.

== Example end-of-run script ==
The following is part of a script run at end-of-run, where it reads some parameters from the odb and saves them in a temporary file to be sent to the elog.

To make the script run at end of run, the name of the script is entered in the ODB key {{Odbpath|path=/Programs/Execute on stop run}} (see [[/Programs ODB tree#Execute on stop run]]). Similarly, a script may be made to run at the beginning of run by entering its name in the ODB key {{Odbpath|path=/Programs/Execute on start run}} (see [[/Programs ODB tree#Execute on start run]]).

#!/bin/tcsh
# This script is started at the end of each run. It takes some parameters
# from the odb and creates an entry in the elog
.....
# Start collecting information from ODB first
set Run_number = `odb -e $MIDAS_EXPT_NAME -c 'ls "/Runinfo/Run number"'`
set number = `echo $Run_number | awk '{print $3}'`
set sample = `odb -e $MIDAS_EXPT_NAME -c 'ls "/Experiment/Edit on Start/sample"'`
set Sample = `echo $sample | awk '{print $2}'`
.....
# Now create the temporary file to be sent to the elog
echo "Run # $number" >> $fin
odb -e $MIDAS_EXPT_NAME -c 'ls "/Runinfo/Start time"' >> $fin
odb -e $MIDAS_EXPT_NAME -c 'ls "/Runinfo/Stop time"' >> $fin
echo "$Sample at T = $T K, H = $H T and RF = $RF mW">> $fin
.....

= Chat command =
The {{Odbedit cmd|cmd=chat}} can be used to communicate between users, each running {{Utility|name=odbedit}} clients. The chat messages are also (sing Aug 2016) sent to the {{Utility|name=mhttpd}} [[Chat Page]]. The {{Odbedit cmd|cmd=msg}} can be also be used interactively to generate chat messages. If chat messages do not appear in the [[Chat Page]] see [[#Troubleshooting]].
<pre>
[local:js:S]/>chat
Your name> george
Exit chat mode with empty line.
> Are you there?
[george,USER] Are you there?
19:33:59 [fred,USER] Hallo George
</pre>

= Msg command - send a message =
The parameters of the {{Odbedit cmd|cmd=msg}} have been changed (August 2016). The {{Odbedit cmd|cmd=msg}} now works differently '''interactively''' than from the [[odbedit#Using an external command|command line]]. A hidden parameter "facility" has been added, which is either set to "chat" or "midas".
== To web server Chat page ==
'''Interactively''', the {{Odbedit cmd|cmd=msg}} works like the [[#Chat command]], sending a chat message which appears on the web server [[Chat Page]] and on any other {{Utility|name=odbedit}} session for that experiment. The chat message does NOT appear in the MIDAS [[Message System#midas.log|message log]] or [[Message Page]]. In this case, the "facility" is hard-coded as "chat" and there are two parameters, "user" and "message", e.g.
<pre>
[local:js:S]/>msg fred "hi, are you there?"
[fred,USER] hi, are you there?
</pre>
== To web server Message Page and message log ==
To send a message to the webserver [[Message Page]] and the [[Message System#midas.log|message logfile]] ( {{File|name=midas.log}}) use the [[odbedit#Using an external command|command line]] with the {{Odbedit cmd|cmd=msg}}. In this case, the "facility" is hard-coded as "midas", and there are three parameters, two of which are optional:
; type (optional)
: Default is 8 (MT_USER). If supplied, it must be set to one of the '''numerical''' values 1 (MT_ERROR), 2 (MT_INFO), 4 (MT_DEBUG) or 8 (MT_USER), as defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/html/ midas.h].
; name (optional)
: Ignored unless the type is MT_ERROR. Default is "script".
; message
: the message to be sent, enclosed in quotes if it includes spaces

See Table 1 below for examples.

{| class="wikitable"
|+ Table 1 : examples of {{Odbedit cmd|cmd=msg}}
|-
! odbedit -c 'msg command' !!colspan='2'| Type !! Name !! Resulting Message !! Explanation
|-
| 'msg 2 "testing 123" '
| 2
| '''MT_INFO'''
|
| [ODBEdit,'''INFO'''] testing 123
| Message type supplied. Program name set to "ODBEdit".
|-
| 'msg "testing 123" '
| 8
| '''MT_USER'''
|
| [script,'''USER'''] testing 123
| Message type omitted, defaults to MT_USER <br>which sets program name to "script".
|-
| 'msg 1 my_name "error message" '
| 1
| '''MT_ERROR'''
| my_name
|[ODBEdit,'''ERROR'''] [odbedit.cxx:2490:my_name,ERROR] error message
| Name parameter is supplied. Error message appears with a red background.
|-
| 'msg 1 "error message" '
| 1
| '''MT_ERROR '''
|
| [ODBEdit,'''ERROR'''] [odbedit.cxx:2490:script,ERROR] error message
| Name parameter omitted, default name is "script"
|}

=== Troubleshooting ===
If the message does not appear on the [[Chat Page]] (interactive) or [[Message Page]] (command line), check that the ODB key [[Keys in the ODB /Logger tree#Data dir|/Logger/Data dir]] is set to a '''full directory path''', such as ''/home/user/online/js'', not a relative path such as the current directory "./". If set to a full directory path, all clients will use the '''same''' {{File|name=midas.log}} file, regardless of which directory they were started from. With a relative path, {{Utility|name=mhttpd}} and {{Utility|name=odbedit}} must be started in the same directory
for messages/chat to appear in the appropriate [[mhttpd]] page.

[[Category:ODB]]

Installation/Compilation problems

2018-11-21T00:14:34Z

Suz:

{{Pagelinks}}

== Installation/Compilation Problems ==

=== SSL certificate errors ===

At some sites you might get a SSL server certificate error during the git clone operation, like

<pre>
error: SSL certificate problem, verify that the CA cert is OK. Details:
</pre>

This indicates that you don't have the proper certificate authority (CA) files installed on your computer. Possible solutions:

* The easiest way out is to tell git to ignore the SSL verification with

<pre>
git config --global http.sslVerify false
</pre>

* Set the environment variable GIT_SSL_NO_VERIFY=true.
* But the best solution is to just actually install the correct certificate authority files.

=== CERNLIB Errors ===

There are some older analyzer programs included in MIDAS that use PAW/HBOOK. MIDAS will try to build these programs if you have the CERNLIB environment variable set. This may cause errors trying to build mana.cxx, like

<pre>
gcc -Dextname -DHAVE_HBOOK -c -g -O2 -Wall -Wno-strict-aliasing -Wuninitialized -Iinclude -Idrivers -I../mxml -I./mscb
-DHAVE_FTPLIB -D_LARGEFILE64_SOURCE -DHAVE_ROOT -pthread -m64 -I/usr/local/packages/root-5.32/include/root -DHAVE_ZLIB
-DHAVE_MSCB -DOS_LINUX -fPIC -Wno-unused-function -o linux/lib/hmana.o src/mana.cxx
src/mana.cxx: In function 'INT book_ntuples()':
src/mana.cxx:791: error: invalid conversion from 'const void*' to 'void*'
</pre>

Unless you care about this functionality, the easiest solution is to unset the environment variable CERNLIB before compiling.

=== MacOS 10.11 (El Capitan) openssl errors ===

Starting with version 10.11, MacOS has removed the openssl header files (they have been apparently deprecated for a while). This causes a compiler error when trying to build the mongoose web server that MIDAS uses:

<pre>
gcc -c -g -O2 -Wall <snip> src/mongoose.c
src/mongoose.c:322:10: fatal error: 'openssl/ssl.h' file not found
#include <openssl/ssl.h>
</pre>

In order to fix this you need to install the openssl libraries using MacPorts. If you haven't used MacPorts, the instructions would be

# Install MacPorts using [https://www.macports.org/install.php MacPorts Installation Guide]
# Install the openssl library
<pre>
sudo port install openssl
</pre>

Once you've done that the installation will work correctly.

[[Category:Installation]] [[Category:Troubleshooting]]

Category:Troubleshooting

2018-11-21T00:12:19Z

Suz: Created page with "Category:Contents"

[[Category:Contents]]

FAQ

2018-11-21T00:10:49Z

Suz:

{{Pagelinks}}

= Frequently Asked Questions =

There is a related page of [[Installation/Compilation problems|Common Installation Problems]].
__FORCETOC__

== How to recover from a corrupted ODB ==

* Stop your front-ends, [[mlogger]], [[mhttpd]], etc.
* Remove the shared memory associated to ODB buffer. Find the shared memory segment by doing
ls -l /dev/shm
then remove the segment that will be something like /dev/shm/*_test_ODB_SHM
* Move the old ODB files. These will be in the location given by [[Exptab]], e.g. ~/online
cd online
mv .ODB.SHM .ODB.SHM.BAD
* Restart ODB with larger size using [[odbedit]] e.g.
odbedit -s 100000000
* Reload the last saved ODB dump you have (see [[ODB#Save and reload the ODB|save and reload the ODB]]). These dumps are typically called something like 'online/history/*.xml'.
So from {{Utility|name=odbedit}} you do something like
odbedit> load history/run00071.xml
* Your ODB should now be fixed.

Note that sometimes it seems that you also need to remove the buffers associated with the system messages (called SYSMSG) as well as the buffers associated with the ODB.

See also [[odbinit]].

== How to get odbedit to show run state ==

Question: I've seen the ODB prompt displaying the run state, how do you do that?

Answer: Modify the /System/prompt field. The "S" is the trick.

<pre>
Fri> odb -e bnmr1 -h isdaq01
[host:expt:Stopped]/cd /System/
[host:expt:Stopped]/System>ls
Clients
Client Notify 0
Prompt [%h:%e:%S]%p
Tmp
[host:expt:Stopped]/System
[host:expt:Stopped]/Systemset prompt [%h:%e:%S]%p>
[host:expt:Stopped]/System>ls
Clients
Client Notify 0
Prompt [%h:%e:%S]%p>
Tmp
[host:expt:Stopped]/System>set Prompt [%h:%e:%s]%p>
[host:expt:S]/System>set Prompt [%h:%e:%S]%p>
[host:expt:Stopped]/System>
</pre>

See also [[/System ODB tree#Prompt]].

== Increasing Number of Hot-links ==

MIDAS, by default, allows you to have a maximum of 256 individual [[Event Notification (Hot-Link)|hot-links]] to be registered. If you find that you need more hot-links than that, follow the procedure below:

<ol>
<li> Use odbedit to save current ODB
<pre>
odbedit
save current_odb.odb
</pre>
<li> Stop all the running MIDAS processes, including mlogger and mserver using the web
interface. Then stop mhttpd as well. To stop mhttpd just do

<pre>
killall mhttpd
</pre>

<li> Remove your old ODB (we will recreate it after modifying MIDAS, using the backup you just
made).
<pre>
mv .ODB.SHM .ODB.SHM.20161104
rm /dev/shm/<expname>_ODB_SHM
</pre>

where <expname> is the name of your experiment.

<li> Make the following modifications to midas. In this particular case I have increased the
max number of open records from 256 to 1024. You would need to change the constants if you
want to change to other values
<pre>
diff --git a/include/midas.h b/include/midas.h
index 02b30dd..33be7be 100644
--- a/include/midas.h
+++ b/include/midas.h
@@ -254,7 +254,7 @@ typedef std::vector<std::string> STRING_LIST;
-#define MAX_OPEN_RECORDS 256 /**< number of open DB records */
+#define MAX_OPEN_RECORDS 1024 /**< number of open DB records */
diff --git a/src/odb.c b/src/odb.c
index 47ace8f..ac1bef3 100755
--- a/src/odb.c
+++ b/src/odb.c
@@ -699,8 +699,8 @@ static void db_validate_sizes()
- assert(sizeof(DATABASE_CLIENT) == 2112);
- assert(sizeof(DATABASE_HEADER) == 135232);
+ assert(sizeof(DATABASE_CLIENT) == 8256);
+ assert(sizeof(DATABASE_HEADER) == 528448);
</pre>
The calculation is as follows (in case you want a different number of open records):
DATABASE_CLIENT = 64 + 8*MAX_OPEN_ERCORDS = 64 + 8*1024 = 8256
DATABASE_HEADER = 64 + 64*DATABASE_CLIENT = 64 + 64*8256 = 528448

<li> Rebuild MIDAS
<pre>
cd $MIDASSYS
make clean; make
</pre>

<li> Create new ODB
<pre>
odbedit -s 1000000
</pre>
Note, you should change the size of the ODB to whatever you need.

<li> reload your original ODB
<pre>
[local:exp:Stopped] load current_odb.odb
</pre>

<li> Rebuild all your frontend programs (and other user-specific programs) against new MIDAS; they should then work and you should be able to produce more open records.
</ol>

[[Category:Troubleshooting]]

Application listing

2018-11-20T23:35:56Z

Suz:

{{Pagelinks}}

=== Introduction ===
The MIDAS package after [[Compilation & Build]] will contain a new directory
: <span style="color:#005c1F; font-style:italic ">$MIDASSYS/linux/</span> <span style="color:white;">space</span> or <span style="color:white;">space</span> <span style="color:#005c1F; font-style:italic ">$MIDASSYS/linux-m32/</span>
under which the MIDAS library (in {{Filepath|path=../lib}}) and the images (in {{Filepath|path=../bin}}) will be placed. Most of the MIDAS applications are located here. There a few other applications that can be manually built under {{Filepath|path=/$MIDASSYS/utils}} as well.

* '''[[dio]]''' → ''Direct I/O driver utility''

* '''[[Frontend Application]]''' → ''User-built - communicates with hardware ''

* '''[[hvedit]]''' → ''High Voltage editor and GUI''

* '''[[lazylogger]]''' → ''Data archiver''

* '''[[mlogger]]''' → ''Event logger''

* '''[[mchart]]''' → ''Assembles data for stripchart''

* '''[[Mdump|mdump]]''' → ''Display contents of event banks''

* '''[[Melog|melog]]''' → ''Send information to elog''

* '''[[mevb]]''' → ''Event builder application''

* '''[[mh2sql]]''' → ''Import history files into SQL database''

* '''[[Mhdump|mhdump]]''' → ''Display history events''

* '''[[mhttpd]]''' → ''Webserver for Run Control''

* '''[[mlxspeaker]]''' → ''Audible messaging''

* '''[[mserver]]''' → ''Remote server''

* '''[[mstat]]''' → ''Monitor and display''

* '''[[mtape]]''' → ''Tape manipulator''

* '''[[odbedit]]''' → ''ODB Editor/Run control''

* '''[[odbhist]]''' → '' ODB parameter history display''

* '''[[odbinit]]''' → '' Initialize ODB ''

* '''[[stripchart]]''' → ''Stripchart data display''

[[Category:Utilities]]

Old and Obsolete versions

2018-01-05T03:00:01Z

Suz: Created page with "{{Pagelinks}} = Purpose = For various reasons, not all experimenters are able or willing to update to the latest MIDAS version in a timely fashion. Therefore, documentation..."

{{Pagelinks}}

= Purpose =
For various reasons, not all experimenters are able or willing to update to the latest MIDAS version in a timely fashion.
Therefore, documentation for old and/or obsolete versions of the MIDAS code and utilities will be moved to this area.

= web server mhttpd =
There was an important change to the web server [[mhttpd]] in MIDAS versions downloaded after '''May 2015'''. Prior to May 2015, mhttpd was insecure. The only way to secure this version was to run behind a firewall. As part of the May 2015 upgrade to MIDAS [[Security]], a secure alternative to running behind a firewall was developed. The MIDAS Web Server {{Utility|name=mhttpd}} was explicitly linked with OpenSSL to provide secure HTTPS connections via the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server. To connect to an experiment using {{Utility|name=mhttpd}}, a username and password are now required.

== mhttpd - pre May 2015 ==
;Note
* HTTP-only (pre-May2015) versions of mhttpd should only be used '''behind a firewall'''
* If Web [[Security]] is an issue, update to the latest version of mhttpd which uses HTTPS/OpenSSL.

=== Arguments ===

-p port : port number e.g. 8080 (no default). See [[#Usage|usage]].
[-h hostname ] : see [[Common Parameters to MIDAS Utilities]]
[-e experiment] : see [[Common Parameters to MIDAS Utilities]]
[-v] : display verbose HTTP communication
[-D] : starts program as a daemon
[-E] : only display ELog system
[-H] : only display history plots
[-a hostname] : only allow access for specific host(s). Several [-a Hostname] statements might be given
[-help]

=== Usage ===
The command '''mhttpd -p port''' can be used to start the web server. In this case, the TCP/IP port number is '''required''' as an argument in order to listen to the web-based request.
<br>e.g. if mhttpd is started on IP host machine "myhost" on port 8081 as follows
: mhttpd -p 8081 -D
access to the [[#Features|''Midas status page'']] can be obtained by pointing a web browser to
http://myhost.mydomain:8081

;Note
If [[Exptab|multiple experiments]] run on the same host, a web server for each experiment must be started on a different port, e.g.
mhttpd -e expt1 -p 8081 -D
mhttpd -e expt2 -p 8082 -D

=== Improve Security with SSL Proxy ===
Improved security for HTTP is gained by using an SSL (https) proxy. See [[Setup MIDAS experiment#mhttpd with HTTP|Setting up an SSL proxy]].
</div>

[[Category:Contents]]

Mhttpd

2018-01-05T02:53:57Z

Suz:

{{Pagelinks}}
= Links =
{{mhttpdpages3|[[Mhttpd.js|MIDAS Javascript Library]]|[[odbedit]]|[[Security]]}}

= Purpose =
The {{Utility|name=mhttpd}} utility runs the '''MIDAS Web Server''' which allows the user to communicate with an experiment using any web browser. It is used primarily for run control.

= Web security =

For '''maximum web security''', {{Utility|name=mhttpd}} should be run behind a password-protected '''Apache HTTPS proxy''' (see [[Security]] for details). {{Utility|name=mhttpd}} should be built with HTTPS and built-in passwords disabled, http access restricted to localhost (or the host of the httpd, if they are not the same).

Alternatively, mhttpd can be run with '''good web security''' using password-protected secure HTTPS connections. This is the default case, where mhttpd is explicitly linked with OpenSSL to provide secure HTTPS connections via the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server. To connect to an experiment using {{Utility|name=mhttpd}}, a username and password are required.
By default, users can connect from anywhere, providing they know the correct username and password. However, web access can be restricted by using the {{Utility|name=mhttpd}} access control list in the ODB at [[/Experiment ODB tree#mhttpd hosts subtree|Allowed hosts]], and/or by using the "-a" argument to {{Utility|name=mhttpd}}.

= Arguments =
-h connect to midas server [[mserver]] on given host
-e experiment to connect to
-v display verbose HTTP communication
-D become a daemon
-E only display ELog system
-H only display history plots
-a only allow access for specific host(s), several [-a Hostname] statements might be given (default list
in ODB at [[/Experiment ODB tree#mhttpd hosts subtree|/Experiment/security/mhttpd hosts/allowed hosts]])
--http port - bind to specified HTTP port (default is ODB [[/Experiment ODB tree#midas http port|/Experiment/midas http port]])
--https port - bind to specified HTTPS port (default is ODB [[/Experiment ODB tree#midas https port|/Experiment/midas https port]])
-help display usage information

= Usage =
== To start the webserver using HTTPS/SSL (Mongoose) ==
* ''"mhttpd"'' or
* ''"mhttpd -v"'' to get debug information, or
* ''"mhttpd -D"'' to run in the background
* ''"mhttpd -a myHost1 -a myHost2"'' to restrict web access
All are equivalent to
* ''"mhttpd --https 8443 --http 8080"''
Starting {{Utility|name=mhttpd}} like this will redirect the default HTTP port of 8080 to the secure HTTPS port 8443. If the ports are not supplied, the default ports will be read from the ODB keys [[/Experiment ODB tree#midas http port|midas http port]] and [[/Experiment ODB tree#midas https port|midas https port]]. If ports are supplied, their values will overwrite the default values stored in the ODB. When {{Utility|name=mhttpd}} is started with a secure port for the first time, a password file (and optionally an SSL certificate) need to be created. See [[#HTTPS/SSL server (Mongoose)|mhttpd HTTPS/SSL server]] for more information.

If {{Utility|name=mhttpd}} is started on IP host machine "myhost" using the default ports, the [[#Features|''Midas status page'']] can be accessed by pointing a web browser to
* https://myhost.mydomain:8443
* or to http://myhost.mydomain:8080 which will be redirected automatically to https://myhost.mydomain:8443

The automatic redirect may be convenient for users who are used to using the older HTTP-only version of {{Utility|name=mhttpd}} with a particular HTTP port (e.g. 8080) for their experiment. The redirect can be disabled by setting the ODB key [[/Experiment ODB tree#http redirect to https|http redirect to https]] to "n". This also bypasses the user authentification.

== To start the webserver when running behind a firewall ==
In this case, only the http port is in use.
* ''"mhttpd"'' or
* ''"mhttpd -v"'' to get debug information, or
* ''"mhttpd -D"'' to run in the background
* ''"mhttpd --http 8080"''

The [[#Features|''Midas status page'']] can be accessed by pointing a web browser to
* http://myhost.mydomain:8080

=== Multiple experiments ===
If [[Exptab|multiple experiments]] run on the same host, a web server for each experiment must be started on a different port, e.g.
* ''"mhttpd -e expt1 -D"'' use default ports
* ''"mhttpd -e expt2 --http 8081 --https 8444 -D"'' use supplied ports

= Features =
The Midas web server {{Utility|name=mhttpd}} provides a means for run control including monitoring of the run parameters.
Its main feature is a web page invoked through any web browser accessing the Midas experimental URL at a defined port (see [[#Usage|Usage]]).

The contents of this '''Midas status page''' is composed with minimal information relative to the experiment. It contains a collection of buttons and links to other pages to further describe and control the configuration of the experiment.

* Minimal display on the main [[Status Page]]
** Experiment name, time & date, page refresh rate
** Standard Menu Buttons (see below)
** User defined buttons (e.g. alias links, run scripts, custom pages etc.)
** run comments and condition display section (if enabled)
** Equipment list with current running condition, number of event received, event rate, data rate for each equipment.
** Data logging statistics (number of event recorded, data size recorder, compression factor, usage storage level) if enabled.
** Secondary Data logging (data mover) with statistics if enabled.
** Single line of the most recent Midas message.
** Table of the current applications connected to this experiment.

* Standard Menu Buttons
** Transition the state of the run (stopped/running/paused), allows user running condition parameters to be entered at the start state (see [[Edit-on-start Parameters]]).
** Access to the full [[Online Database]] for data display and/or data content modification.
** Display the [[Message Page]], which shows messages generated by the MIDAS [Message System]] as well as the user using cm_msg() functions.
** Access to [[ELOG Page]] switches to the predefined "electronic logbook".
** Access to the [[Alarms Page]] for monitoring the different type of alarms (evaluated, programs, internals, periodic).
** Access to the [[Programs Page]] for a status or interaction with the current running applications part of the Midas experiment.
** Access to the [[History Page]] for graphical data representation of any ODB variables and acquired data.
** Access to the Midas Slow Control Bus devices [[MSCB Page]] connected to this experiment.
** Access to the [[Sequencer Page]] control/monitoring page for [[Sequencer]] i.e. interactive loading/saving/running of a run sequence based on any ODB parameters.
** Access to the [[Chat Page]] for communication between users on the same experiment.
** Access to the [[Help Page]] with short-cut to the Midas Help documentation resource and other information.
* Links
** links to all the listed equipments invoking a dedicated page for the display and possible control of the equipment parameters.
** link to the logger configuration (if present) for the data recording.
** link to the possible secondary logging configuration parameters (if present).

Other features include a JSON interface and Javascript library used for implementing interactive [[Custom Page|custom pages]] for MIDAS experiments.

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

= HTTPS/SSL server (Mongoose) =

The HTTPS/SSL ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]) server is activated by running {{Utility|name=mhttpd}}, and by default it listens on ports 8080 and 8443 (see [[#Usage]]).

{{Utility|name=mhttpd}} with Mongoose requires an '''SSL Certificate''' and a '''password file'''. Ideally, an SSL Certificate issued by a well-known authority trusted by your browser should be used.

The first time {{Utility|name=mhttpd}} is run, if it does not find an SSL Certificate, it will print instructions on how to [[#Create an SSL certificate|create a self-signed SSL Certificate]]. If it finds no existing password file, it will then print instructions on how to [[#Create a password file|create a password file]] (see below for examples).

== Create an SSL certificate ==
If no [[#HTTPS/SSL server (Mongoose)|more secure]] SSL Certificate is available, then create a self-signed certificate by running {{Utility|name=mhttpd}},
and following the printed instructions :
[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
[mhttpd,ERROR] [mhttpd.cxx:17086:mongoose,ERROR] cannot find SSL certificate file "/home/user/online/test/ssl_cert.pem"
[mhttpd,ERROR] [mhttpd.cxx:17087:mongoose,ERROR] please create SSL certificate file: openssl req -new -nodes -newkey rsa:2048
-sha256 -out ssl_cert.csr -keyout ssl_cert.key; openssl x509 -req -days 365 -sha256 -in ssl_cert.csr -signkey ssl_cert.key
-out ssl_cert.pem; cat ssl_cert.key >> ssl_cert.pem
could not start the mongoose web server, see messages and midas.log, bye!

The certificate and key should be placed in one PEM file called ssl_cert.pem located in either MIDAS environment variables [[MIDAS environment variables#MIDAS_DIR|MIDAS_DIR]] or [[MIDAS environment variables#MIDASSYS|MIDASSYS]], and the permissions on the file should be 600 or only owner read/write.
[user@dasdevpc2 test] chmod 600 ssl_cert.pem

== Create a password file ==
Once a valid certificate is generated, when {{Utility|name=mhttpd}} is restarted, you will need to create a password file.

[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
Web server will use SSL certificate file "/home/user/online/test/ssl_cert.pem"
[mhttpd,ERROR] [mhttpd.cxx:17137:mongoose,ERROR] mongoose web server cannot find password file "/home/user/online/test/htpasswd.txt"
[mhttpd,ERROR] [mhttpd.cxx:17138:mongoose,ERROR] please create password file: htdigest -c /home/user/online/test/htpasswd.txt test midas
could not start the mongoose web server, see messages and midas.log, bye!

Each person who is to have access to the experiment should create their own username and password. The first user (e.g. mary) creates the password file e.g. htpasswd.txt
[user@dasdevpc2 test]$ htdigest -c /home/user/online/test/htpasswd.txt test mary
Adding password for mary in realm test.
New password:
Re-type new password:
[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
Web server will use SSL certificate file "/home/user/online/test/ssl_cert.pem"
Web server will use authentication realm "test", password file "./htpasswd.txt"

Access to the [[#Features|''Midas status page'']] can be obtained by pointing a web browser to
https://myhost.mydomain:8443
The first time you connect you will be asked for a username and password.
Now that the password file has been created, subsequent users may create their own username and password in the same file by omitting "-c" argument in htdigest, e.g.
htdigest /home/user/online/test/htpasswd.txt test john

Web access can be restricted to certain hosts if desired (see [[#Web security]]).

Documentation for the version of mongoose included with MIDAS can be found at [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/mongoose/ Mongoose documentation].

For more information see [https://midas.triumf.ca/elog/Midas/1062 Elog note 1062]

== Older versions ==
Documentation on older versions of mhttpd can be found at [[Old and Obsolete Versions]].

[[Category:Utilities]]
[[Category:Web server mhttpd]]
[[Category:Run control]]

New Custom Pages (2017)

2017-11-15T21:09:55Z

Suz:

{{Pagelinks}}

= Links =
{{mhttpdpages4|[[Custom Page Features]]|[[New Custom Pages (2017)]]|[[/Custom ODB tree]]|[[Mhttpd.js|MIDAS Javascript library]]}}

= Introduction =
A new scheme of custom pages making use of modern HTML5 techniques has been introduced in 2017. This page describes all new elements and gives some example pages.

= Required Elements =

For the new custom pages to work, the following elements in a custom HTML page are required:

* Including <code>midas.js</code>
* Including <code>mhttpd.js</code>
* Including style sheet <code>midas.css</code>
* Setting the class of the HTML body to <code>mcss</code>
* Calling <code>mhttpd_init('name')</code> on page load where <code>name</code> is the name of the page shown on the left menu bar
* Using <code>div</code> elements with various pre-defined id's and names

= modbvalue =

This special HTML div tag (abbreviation stands for Midas ODB VALUE) <code><div name="modbvalue" data-odb-path="/Some/Path"></code> is now automatically replaced by the value in the ODB found at the given path. Updates are once per second by default. This can be changed by passing a second argument to <code>mhttpd_init('name', interval)</code> where interval is in milliseconds. The following options are valid for this tag:

{| class="wikitable"
|+ Table 1: List of valid options for modbvalue tag
|-
! Option !! Example !! Meaning
|-
| name || name="modbvalue" || Tells the framework to replace this tag with an ODB value
|-
| data-odb-path || data-odb-path = "/Runinfo/Run number" || Path to the value in the ODB
|-
| data-odb-editable || data-odb-editable="1" || If set, the value is not only shown, but is also clickable for in-line editing. Hitting return send the new value to the ODB.
|-
| data-format || data-format="f3" || Specify format of data shown. See Table 2 below for options.
|}

Table 2 below lists the format specifiers supported with a modbvalue tag <code>data-format="..."</code>:

{| class="wikitable"
|+ Table 2: Format specifiers for modbvalue tag <code>data-format="..."</code>
|-
! Option !! Example !! Meaning
|-
| d || 1234 || Shows a number in decimal encoding
|-
| x || 0x4D2 || Shows a number in hexadecimal encoding
|-
| b || 10011010010b|| Shows a number in binary encoding. Options d, x, b can be combined, like <code>data-format="dxb"</code>
|-
| f<x> || 1.234 || Shows a floating point number with <x> digits after the decimal. A value of f0 shows only the integer part.
|-
| p<x> || 1.23 || Shows a floating point number with <x> significant digits of precision, independent of the decimal. For example a value of p2 can render a number to 12000 or to 0.00012
|}

= modbbutton =

This tag generates a push-button which can set a certain ODB entry to a specific value. To set the {{Odbpath|path=Run number}} to 100, one can use the following tag:

<code><button name="modbbutton" class="mbutton" data-odb-path="/Runinfo/Run number" data-odb-value="100"></code>

= modbhbar =

The following tag:

<code><div name="modbhbar" style="width: 500px" data-odb-path="/Runinfo/Run number" data-max-value="10" data-color="lightgreen"></div></code>

shows a horizontal bar with a total length of 500px. Depending on the ODB value {{Odbpath|path=Run number}}. If {{Odbpath|path=Run number}} is 10, then the bar is filled all the way to the right, if {{Odbpath|path=Run number}} is 5, the bar is only filled halfway.

= modbvbar =

Same as <code>modbhbar</code>, except the bar grows vertically instead of horizontally.

= Complete Example =

The following code shows an example page (contained in {{Filepath|path=resources/a_example.html}} in the MIDAS distribution) of a custom page implementing most of the new features. You activate this page by putting in the ODB:

<pre>
/Custom
Path /midas/resources
Test a_example.html
</pre>

== Code ==
The file {{File|name=a_example.html}} contains the following code:

<pre>
<!DOCTYPE html>
<html class="mcss">
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="midas.css">
<script src="midas.js"></script>
<script src="mhttpd.js"></script>
<title>Example</title>
</head>

<body class="mcss" onload="mhttpd_init('Example')">


<div id="mheader"></div>
<div id="msidenav"></div>

<div id="mmain">
<table class="mtable">
<tr>
<th colspan="2" class="mtableheader">Status</th>
</tr>
<tr>
<td style="width: 200px;">
Run number:
</td>
<td>
<div name="modbvalue" data-odb-path="/Runinfo/Run number" data-odb-editable="1"></div>
</td>
</tr>
<tr>
<td>
Last run start:
</td>
<td>
<div name="modbvalue" data-odb-path="/Runinfo/Start time"></div>
</td>
</tr>
<tr>
<td>
Last run stop:
</td>
<td>
<div name="modbvalue" data-odb-path="/Runinfo/Stop time"></div>
</td>
</tr>
<tr>
<td>
Indicator:
</td>
<td>
<div name="modbbar" style="width: 500px" data-odb-path="/Runinfo/Run number" data-max-value="10"
data-color="lightgreen"></div>
</td>
</tr>
<tr>
<td colspan="2" style="text-align: center;">
<button name="modbbutton" class="mbutton" data-odb-path="/Runinfo/Run number" data-odb-value="1">Set run
number to 1
</button>
</button>
<button name="modbbutton" class="mbutton" data-odb-path="/Runinfo/Run number" data-odb-value="5">Set run
number to 5
</button>
</button>
<button name="modbbutton" class="mbutton" data-odb-path="/Runinfo/Run number" data-odb-value="10">Set run
number to 10
</button>
</button>
</td>
</tr>
</table>
</div>

</body>
</html>
</pre>

which results in the page shown in Figure 1 below.

== Image ==
The example [[#Code]] results in the image shown below:
;<center>Figure 1 Example custom page using new (2017) features</center>

[[File:Custom17.png]]

[[Category:mhttpd Pages]] [[Category:Custom]]

Template:Mhttpdpages4

2017-11-15T20:13:14Z

Suz: Created page with " <noinclude> Usage: {{mhttpdpages5|link1|link2|link3|link4|link5}} Provide 4 extra links </noinclude> <div style="column-count:5;-moz-column-count:5;-webk..."

<noinclude>
Usage: {{mhttpdpages5|[[link1]]|[[link2]]|[[link3]]|[[link4]]|[[link5]]}}
Provide 4 extra links
</noinclude>
<div style="column-count:5;-moz-column-count:5;-webkit-column-count:5">
* [[mhttpd|mhttpd web server]]
* [[Status Page]]
* [[Start Page]]
* [[ODB Page]]
* [[Message Page]]
* [[Programs Page]]
* [[Alarms Page]]
* [[History Page]]
* [[ELOG Page]]
* [[Chat Page]]
* [[Help Page]]
* [[Config Page]]
* [[Custom Page]]
* [[MSCB Page]]
* [[Sequencer Page]]
* [[odbedit]]
* {{{1|missing link1}}}
* {{{2|missing link2}}}
* {{{3|missing link3}}}
* {{{4|missing link4}}}
</div>
<br>

Sequencer Page

2017-09-29T01:01:34Z

Suz:

{{Pagelinks}}

= Links =
{{mhttpdpages3|[[Sequencer]]|[[/Sequencer ODB tree]]|[[Edit-on-Sequence Parameters]]}}

= Purpose =
The purpose of the [[mhttpd]] Sequencer Web Page to provide a visual display for the [[Sequencer]]. Using the Sequencer Page, [[Sequencer|Sequencer scripts]] can be loaded, edited and run.

= Access to the Sequencer Page =
The Sequencer Page is displayed by clicking on {{Button|name=Sequencer}} button on the mhttpd [[Status Page]] or other [[mhttpd]] web page.

;Note
:If the Sequencer button is not present on the Status Page, it may have been [[Status Page#page-switch-buttons|suppressed]].

= Features of the Sequencer Page =
* The Sequencer Page takes its parameters from the [[/Sequencer ODB tree]].
* Sequencer scripts can be loaded and run from the Sequencer Page.
* A '''visual editor''' is provided to edit scripts.
* If [[Edit-on-Sequence Parameters]] are defined, these will be displayed when a sequence is started.
* A '''progress display''' is provided showing the progress of a running script, and the last few Midas messages are also shown (Figure 5).

= How to input and run a Sequencer Script =
; Note
: A Sequencer Script is written using commands recognized by the Sequencer.''' See [[Sequencer|Sequencer Commands]] for the list of sequencer commands.
<ol>
<li>Press the {{Button|name=Sequencer}} on the [[Status Page]] to display the Sequencer Page.
: The first time the button is pressed, the Sequencer Page will appear as in Figure 1, where no load file has been specified.
<li>Load or create a script file
: A new script file can be created by entering sequencer commands using the [[#Edit or Create a Sequencer Script|visual editor]] on the Sequencer Page, or an existing sequencer script file can be [[#Load an existing Sequencer Script|loaded]].
<li> [[#Start a Sequencer Script|Start]] the sequencer script
</ol>

== Create a Sequencer Script ==
A new sequencer script can be created using the visual editor by typing in [[Sequencer|Sequencer Commands]], or by pasting in an example file (e.g. [[#Sequencer test file]] or one of [[Sequencer#MSL Example|MSL Example file]] or [[Sequencer#XML Example|MSL Example file]] ) as in Figure 2.

The new script is then saved by pressing {{Button|name=Save}}. You will be asked for a file name.

;Note
:The directory path where the sequencer files will be saved is set by the ODB parameter [[/Sequencer ODB tree#Path|/Sequencer/State/Path]].

== Load an existing Sequencer Script ==
An existing sequencer script file can be loaded using {{Button|name=Load Script}} as in Figure 3. If there is no existing file, use the [[#Edit a Sequencer Script|visual editor]] to create one.

;Note
:The directory path where the sequencer looks for saved files is set by the ODB parameter [[/Sequencer ODB tree#Path|/Sequencer/State/Path]].

== Edit a Sequencer Script ==
A sequencer script can be edited on the Sequencer Page by pressing {{Button|name=Edit Script}} (see Fugure 2). The '''visual editor''' allows changes to be made to the script.
The sequencer script must first be [[#Create a Sequencer Script|created]] or [[#Load an existing Sequencer Script|loaded]] from a file.

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
|+ Table 1
|-
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 1: Initial Sequencer page
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 2: Display and/or Edit a Sequencer script
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" |Figure 3: Select a Sequencer file
|-
| rowspan="1" | [[File:sequencer_noscript.png|Figure 1: Initial Sequencer page]]
| rowspan="3"| [[File:sequencer_scripteditor.png|500px|Figure 2: Editing a Sequencer script]]
| rowspan="3"| [[File:sequencer_filelist.png|Figure 3: Select a Sequencer file]]
|-
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 4: Start a Sequencer script
|-
| rowspan="1" | [[File:sequencer_startscript.png|Figure 4: Start a Sequencer script]]
|-
|}

== Start a Sequencer Script ==
After a sequencer script has been [[#Load a Sequencer Script|loaded]], start the script by pressing
the {{Button|name=Start Script}} button.

If there are errors in the script that prevents the script from running, the line(s) in error will be highlighted (Figure 5).
In this case, [[#Edit a Sequencer Script|edit the script]] and fix the errors.

Once all errors are corrected and the script runs, the user will be asked to input any required parameters as in Figure 4 (in this case the number of runs, see [[#Sequencer test file|test_seq.msl]]). If [[Edit-on-Sequence Parameters]] are defined, these will be displayed in addition to any required parameters. Note that [[Edit-on-start Parameters]] will not be displayed (parameters that change between runs should be set by the sequencer script).

When the sequencer is running, a '''visual status''' is displayed in the Progress window, and the '''current position''' in the sequence file is also highlighted (Figure 6).
The sequencer can be paused by pressing {{Button|name=Pause Script}} (Figure 7).
<br>
The progress window will indicate when the sequencer is finished (Figure 8).

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 5: There is an error in the script
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 6: Sequencer is running
|-
| rowspan="1" | [[File:sequencer_error.png|500px|Figure 5: There is an error in the script]]
| rowspan="1" | [[File:sequencer_running.png|500px|Figure 6: Sequencer is running]]
|-
|}

<br clear=all>
{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 7: Sequencer is paused
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" |Figure 8: Sequencer is finished
|-
| rowspan="1" | [[File:sequencer_paused.png|500px|Figure 7: Sequencer is paused]]
| rowspan="1" | [[File:sequencer_finished.png|500px|thumb|Figure 8: Sequencer is finished]]
|-
|}
<br clear=all>

= Sequencer test file =
The following is the contents of the sequence file used for testing ''test_seq.msl'' in the example [[#How to input and run a Sequencer Script|above]].
<pre>
COMMENT "This is a MSL test file"
RUNDESCRIPTION "Test run"
PARAM runs

LOOP $runs
TRANSITION START
WAIT ODBvalue "/Equipment/FIFO_acq/Statistics/Events sent" >= 25
TRANSITION STOP
WAIT seconds 5
ENDLOOP
</pre>

[[Category: mhttpd Pages]] [[Category: Sequencer]]

{{Pagelinks}}

Sequencer Page

2017-09-29T00:53:04Z

Suz:

{{Pagelinks}}

= Links =
{{mhttpdpages3|[[Sequencer]]|[[/Sequencer ODB tree]]|[[Edit-on-Sequence Parameters]]}}

= Purpose =
The purpose of the [[mhttpd]] Sequencer Web Page to provide a visual display for the [[Sequencer]]. Using the Sequencer Page, [[Sequencer|Sequencer scripts]] can be loaded, edited and run.

= Access to the Sequencer Page =
The Sequencer Page is displayed by clicking on {{Button|name=Sequencer}} button on the mhttpd [[Status Page]] or other [[mhttpd]] web page.

;Note
:If the Sequencer button is not present on the Status Page, it may have been [[Status Page#page-switch-buttons|suppressed]].

= Features of the Sequencer Page =
* The Sequencer Page takes its parameters from the [[/Sequencer ODB tree]].
* Sequencer scripts can be loaded and run from the Sequencer Page.
* A '''visual editor''' is provided to edit scripts.
* If [[Edit-on-Sequence Parameters]] are defined, these will be displayed when a sequence is started.
* A '''progress display''' is provided showing the progress of a running script, and the last few Midas messages are also shown (Figure 5).

= How to input and run a Sequencer Script =
; Note
: A Sequencer Script is written using commands recognized by the Sequencer.''' See [[Sequencer|Sequencer Commands]] for the list of sequencer commands.
<ol>
<li>Press the {{Button|name=Sequencer}} on the [[Status Page]] to display the Sequencer Page.
: The first time the button is pressed, the Sequencer Page will appear as in Figure 1, where no load file has been specified.
<li>Load or create a script file
: A new script file can be created by entering sequencer commands using the [[#Edit or Create a Sequencer Script|visual editor]] on the Sequencer Page, or an existing sequencer script file can be [[#To load and existing Sequencer Script|loaded]].
<li> [[#Start a Sequencer Script|Start]] the sequencer script
</ol>

== To Create a Sequencer Script ==
A new sequencer script can be created using the visual editor by typing in [[Sequencer|Sequencer Commands]], or by pasting in an example file (e.g. [[#Sequence test file]] or one of [[Sequencer#MSL Example|MSL Example file]] or [[Sequencer#XML Example|MSL Example file]] ) as in Figure 2.

The new script is then saved by pressing {{Button|name=Save}}. You will be asked for a file name.

;Note
:The directory path where the sequencer files will be saved is set by the ODB parameter [[/Sequencer ODB tree#Path|/Sequencer/State/Path]].

== To Load an existing Sequencer Script ==
An existing sequencer script file can be loaded using {{Button|name=Load Script}} as in Figure 3. If there is no existing file, use the [[#Edit a Sequencer Script|visual editor]] to create one.

;Note
:The directory path where the sequencer looks for saved files is set by the ODB parameter [[/Sequencer ODB tree#Path|/Sequencer/State/Path]].

== To Edit a Sequencer Script ==
A sequencer script can be edited on the Sequencer Page by pressing {{Button|name=Edit Script}} (see Fugure 2). The '''visual editor''' allows changes to be made to the script.
The sequencer script must first be [[#To Create a Sequencer Script|created]] or [[#Load an existing Sequencer Script|loaded]] from a file.

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
|+ Table 1
|-
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 1: Initial Sequencer page
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 2: Display and/or Edit a Sequencer script
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" |Figure 3: Select a Sequencer file
|-
| rowspan="1" | [[File:sequencer_noscript.png|Figure 1: Initial Sequencer page]]
| rowspan="3"| [[File:sequencer_scripteditor.png|500px|Figure 2: Editing a Sequencer script]]
| rowspan="3"| [[File:sequencer_filelist.png|Figure 3: Select a Sequencer file]]
|-
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 4: Start a Sequencer script
|-
| rowspan="1" | [[File:sequencer_startscript.png|Figure 4: Start a Sequencer script]]
|-
|}

== Start a Sequencer Script ==
After a sequencer script has been [[#Load a Sequencer Script|loaded]], start the script by pressing
the {{Button|name=Start Script}} button.

If there are errors in the script that prevents the script from running, the line(s) in error will be highlighted (Figure 5).
In this case, [[#Edit a Sequencer Script|edit the script]] and fix the errors.

Once all errors are corrected and the script runs, the user will be asked to input any required parameters as in Figure 4 (in this case the number of runs, see [[#Sequence test file|test_seq.msl]]). If [[Edit-on-Sequence Parameters]] are defined, these will be displayed in addition to any required parameters. Note that [[Edit-on-start Parameters]] will not be displayed (parameters that change between runs should be set by the sequencer script).

When the sequencer is running, a '''visual status''' is displayed in the Progress window, and the '''current position''' in the sequence file is also highlighted (Figure 6).
The sequencer can be paused by pressing {{Button|name=Pause Script}} (Figure 7).
<br>
The progress window will indicate when the sequencer is finished (Figure 8).

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 5: There is an error in the script
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 6: Sequencer is running
|-
| rowspan="1" | [[File:sequencer_error.png|500px|Figure 5: There is an error in the script]]
| rowspan="1" | [[File:sequencer_running.png|500px|Figure 6: Sequencer is running]]
|-
|}

<br clear=all>
{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 7: Sequencer is paused
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" |Figure 8: Sequencer is finished
|-
| rowspan="1" | [[File:sequencer_paused.png|500px|Figure 7: Sequencer is paused]]
| rowspan="1" | [[File:sequencer_finished.png|500px|thumb|Figure 8: Sequencer is finished]]
|-
|}
<br clear=all>

= Sequence test file =
The following is the contents of the sequence file used for testing ''test_seq.msl'' in the example [[#How to input and run a Sequencer Script|above]].
<pre>
COMMENT "This is a MSL test file"
RUNDESCRIPTION "Test run"
PARAM runs

LOOP $runs
TRANSITION START
WAIT ODBvalue "/Equipment/FIFO_acq/Statistics/Events sent" >= 25
TRANSITION STOP
WAIT seconds 5
ENDLOOP
</pre>

[[Category: mhttpd Pages]] [[Category: Sequencer]]

{{Pagelinks}}

Sequencer Page

2017-09-28T22:55:50Z

Suz:

{{Pagelinks}}

= Links =
{{mhttpdpages3|[[Sequencer]]|[[/Sequencer ODB tree]]|[[Edit-on-Sequence Parameters]]}}

= Purpose =
The purpose of the [[mhttpd]] Sequencer Web Page to provide a visual display for the [[Sequencer]]. Using the Sequencer Page, [[Sequencer|Sequencer scripts]] can be loaded, edited and run.

= Access to the Sequencer Page =
The Sequencer Page is displayed by clicking on {{Button|name=Sequencer}} button on the mhttpd [[Status Page]] or other [[mhttpd]] web page.

;Note
:If the Sequencer button is not present on the Status Page, it may have been [[Status Page#page-switch-buttons|suppressed]].

= Features of the Sequencer Page =
The Sequencer Page takes its parameters from the [[/Sequencer ODB tree]]. Sequencer scripts can be loaded and run from the Sequencer Page. A visual editor is provided to edit scripts. A display is provided showing the progress of a running script, and the last few Midas messages are also shown (Figure 5). If [[Edit-on-Sequence Parameters]] are defined, these will be displayed when a sequence is started.

== How to input and run a Sequencer Script ==
'''A Sequencer Script is written using commands recognized by the Sequencer.''' See [[Sequencer|Sequencer Commands]] for the list of sequencer commands.

=== Load a Sequencer Script ===
<ul>
<li>Press {{Button|name=Sequencer}} on [[Status Page]]. The first time the button is pressed, the Sequencer Page will appear as in Figure 1, where no load file has been specified.</li>

<li>Either</li>
<ul>
<li> Press {{Button|name=Edit Script}} and input a new test sequence
:: i.e. type in [[Sequencer|Sequencer Commands]] or paste in an example file (e.g. [[#Sequence file]] or one of [[Sequencer#MSL Example|MSL Example file]] or [[Sequencer#XML Example|MSL Example file]] ) as in Figure 2.</li>
<li> save the script by pressing {{Button|name=Save}}. You will be asked for a file name. </li>
</ul>
<li>Or </li>
<ul>
<li>load an existing sequencer scriptfile using {{Button|name=Load Script}} as in Figure 3.</li>
</ul>
</ul>

;Note
:The directory path where the sequencer files will be saved is set by the ODB parameter [[/Sequencer ODB tree#Path|/Sequencer/State/Path]].

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
|+ Table 1
|-
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 1: Initial Sequencer page
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 2: Display and/or Edit a Sequencer script
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" |Figure 3: Select a Sequencer file
|-
| rowspan="1" | [[File:sequencer_noscript.png|Figure 1: Initial Sequencer page]]
| rowspan="3"| [[File:sequencer_scripteditor.png|500px|Figure 2: Editing a Sequencer script]]
| rowspan="3"| [[File:sequencer_filelist.png|Figure 3: Select a Sequencer file]]
|-
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 4: Select a Sequencer file
|-
| rowspan="1" | [[File:sequencer_startscript.png|Figure 4: Select a Sequencer file]]
|-
|}

=== Start a Sequencer Script ===
After a sequencer script has been [[#Load a Sequencer Script||loaded]], start the script:
<ul>
<li> Press {{Button|name=Start Script}} button to start the script. </li>
<ul>
<li>You will be asked to input any required parameters as in Figure 4 (in this case the number of runs, see [[#Sequence File|test_seq.msl]]).</li>
<li>If [[Edit-on-Sequence Parameters]] are defined, these will be displayed in addition to any required parameters</li>
<li>In this example, the script contains an error that prevents the script from running (Figure 5)</li>
</ul>
</ul>

=== C. Edit a Sequencer Script ===
<ul>
<li> The script can be edited by pressing {{Button|name=Edit Script}}, and any errors corrected.</li>
<br>
<li> The script will run when {{Button|name=Start Script}} is pressed. A visual status is displayed in the Progress window, and the current position in the sequence file is also highlighted (Figure 6).</li>
<br>
<li> The sequencer can be paused by pressing the {{Button|name=Pause Script}} button (Figure 7).</li>
<br>
<li>The progress window will indicated when the sequencer is finished (Figure 8).</li>
</ul>
</ul>

<br clear=all>

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 5: There is an error in the script
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 6: Sequencer is running
|-
| rowspan="1" | [[File:sequencer_error.png|500px|Figure 5: There is an error in the script]]
| rowspan="1" | [[File:sequencer_running.png|500px|Figure 6: Sequencer is running]]
|-
|}
<br clear=all>
{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="1" cellpadding="2" cellspacing="2"
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" | Figure 7: Sequencer is paused
| rowspan="1" style="background-color:lemonchiffon; font-weight:bold" |Figure 8: Sequencer is finished
|-
| rowspan="1" | [[File:sequencer_paused.png|500px|Figure 7: Sequencer is paused]]
| rowspan="1" | [[File:sequencer_finished.png|500px|thumb|Figure 8: Sequencer is finished]]
|-
|}
<br clear=all>

=== Sequence file ===
The following is the contents of the sequence file used for testing ''test_seq.msl'' in the example [[#How to input and run a Sequencer Script|above]].
<pre>
COMMENT "This is a MSL test file"
RUNDESCRIPTION "Test run"
PARAM runs

LOOP $runs
TRANSITION START
WAIT ODBvalue "/Equipment/FIFO_acq/Statistics/Events sent" >= 25
TRANSITION STOP
WAIT seconds 5
ENDLOOP
</pre>

[[Category: mhttpd Pages]] [[Category: Sequencer]]

{{Pagelinks}}

Sequencer Page

2017-09-28T19:38:40Z

Suz:

Sequencer

2017-09-27T02:03:08Z

Suz:

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[/Sequencer ODB tree]]
* [[Sequencer Page]]
* [[mhttpd]]
</div>

= Introduction =
A Sequencer for starting and stopping runs was implemented in June 2011. Since then development has continued, with more commands being added, and the option of using a Midas Script Language (MSL) for commands, in addition to the XML language.

The sequencer runs inside [[mhttpd]]. The first time the {{Button|name=Sequencer}} button on the [[Status Page]] is pressed, the ODB [[/Sequencer ODB tree|Sequencer Tree]] is created. If the Sequencer button is not present on the [[Status Page]], it may have been [[Status Page#page-switch-buttons|suppressed]].

The sequencer runs scripts in XML or MSL (Midas Script Language) format, which reside on the server (where {{Utility|name=mhttpd}} is running). The sequencer state is completely stored in the ODB, meaning that even if {{Utility|name=mhttpd}} is stopped and restarted, the active sequence operation continues exactly where it has been stopped.

Refer to the [[/Sequencer ODB tree]] for more details on its organization.

For instructions on '''getting started with the sequencer''', see [[Sequencer Page]]

= Sequencer Commands =
The following commands are implemented in the MIDAS Sequencer. The left syntax is for the XML file, the right for the MSL (Midas Script Language).

Variable names are indicated in italic, options are enclosed in [brackets].

{| class="wikitable" style="text-align: left; color: black; tr:nth-child(even) {background-color: #F0F0F0};"
!style="width: 20%;background-color:#C0C0C0;"|XML format
!style="width: 20%;background-color:#C0C0C0;"|MSL format
!style="width: 60%;background-color:#C0C0C0;"|Description
|-
||< !DOCTYPE RunSequence[< !ENTITY ''name'' SYSTEM "''name''.xml" >]> &''name'';
||INCLUDE ''name''
||Include another XML file ''name''.xml
|-
||<Call name="''name''"> a,b,c...</Call>
||CALL ''name'', ''a'', ''b'', ''c'', ...
||Call a subroutine. Optional parameters ''a'',''b'',''c''... are passed to the subroutine, where they can be referenced via $1, $2, $3, etc. The subroutine can either reside in the current file, or in a library file which is included.
|-
||<Cat name="''name''"> ''a'',''b'',''c''... </Set>
||CAT ''name'', ''a'', ''b'', ''c'', ...
||Concatenates the strings ''a'',''b'',''c'',... into a single variable name . Can be referenced with $''name''. If a string must contain a comma, it can be enclosed in quotes such as in '''CAT title $run, ",", $n events'''
|-
||<Comment> ''comment'' </Comment>
||COMMENT ''comment''
||A comment for this XML file, for information only. This comment is shown when one clicks on the XML file in the browser inside the web page and can be used to show some information about an XML file. This can be helpful if one has many XML files and the file name only is not enough to supply enough information.
|-
||<Goto line="''n''" / >
||GOTO ''n''
||Jump to line ''n'' in script
|-
||<If condition="''con''" > <br>
... <br>
<else /> <br>
... <br>
</if>
||IF ''con'' <br>
... <br>
ELSE <br>
... <br>
ENDIF
||Statements between <if> and </if> are only executed if condition con is true, otherwise the statements between the optional <else /> and </if> are executed. The condition can use variables via $name and/or constants together with operators "<", "<=", ">", ">=", "==", "!=", "&" (bitwise AND). Up to four nested IF statements are possible.
|-
||<Library name="''name''" >...</Library>
||LIBRARY ''name''
||Indicates that the current file is a library (which can be included by other files). A library usually consists of a set of subroutines.

|-
||<Loop n="''n''" [var="''name''"]> ... </Loop>
||LOOP [''name'' ,] ''n'' ... ENDLOOP
||To execute a loop ''n'' times. For infinite loops, "infinite" can be specified as ''n''. Optionally, the loop variable running from 1..''n'' can be accessed inside the loop via $''name''.

|-
||<Loop var="''name''" values="''a'',''b'',''c'',..."> ... </Loop>
||LOOP ''name'', ''a'', ''b'', ''c'', ... ... ENDLOOP
||Loop though a list of values. The loop is executed once for each value, which is stored into the variable ''name'' so it can be accessed inside the loop via $''name''.

|-
||<Message [wait="1"]> ''message'' </Message>
||MESSAGE ''message'' [,1]
||Opens a message box in the browser containing the text message. If wait="1", then the sequencer waits until the box is closed by the user before continuing.
|-
||<ODBGet path="''path''" > ''name'' </ODBGet>
||ODBGET ''path'', ''name''
||To get a value from a variable ''name''. The variable can then be referenced with $''name''.
|-
||<ODBInc path="''path''" > delta </ODBInc>
||ODBINC ''path'' [, ''delta'']
||To increment a value in the ODB. ''delta'' can be positive or negative. If no "delta" is given, 1 is used.
|-
||<ODBSet [notify="0|1"] path="''path''" > ''value'' </ODBSet>
||ODBSET ''path'', ''value'' [, 0|1]
||To set a value in the ODB. The notify flag specifies if possible hot-links to this ODB value are notified. This can be useful if a front-end program has many parameters, which must be set for a specific run. The front-end usually has a hot-link to its parameters, so on each modification a callback function in the front-end is called which usually modifies some hardware. If there are many ODBSet statements for all parameters, the callback would be executed on each ODBSet, so the hardware would be reconfigured many times slowing down the startup of a run. In order to prevent this, notify="0" can be specified for all ODBSet statements except the last one which contains notify="1", so the callback function is called only once at the end.
|-
||<ODBSubdir path="''path''" >...</ODBSubdir>
||ODBSUBDIR ''path'' ...ENDODBSUBDIR
||If one wants to se several ODB values in the same directory, the ODBSet commands can be rather long if thepath is long. Using this command, the subdir can be specified for all commands between the opening and ending tags. So instead of writing <br>
<ODBSet path="/Very/long/path/into/the/odb/value1">1</ODBSet><br>
<ODBSet path="/Very/long/path/into/the/odb/value2">1</ODBSet><br>
<ODBSet path="/Very/long/path/into/the/odb/value3">1</ODBSet> <br>
<ODBSet path="/Very/long/path/into/the/odb/value4">1</ODBSet> <br>
one can write <br>
<ODBSubdir path="/Very/long/path/into/the/odb"> <br>
<ODBSet path="value1">1</ODBSet> <br>
<ODBSet path="value2">1</ODBSet> <br>
<ODBSet path="value3">1</ODBSet> <br>
<ODBSet path="value4">1</ODBSet> <br>
</ODBSubdir><br>
|-
||<Param name="''name''" [comment="''comment''"][options="''a'',''b'',''c'',..."] [type="bool"] />
||PARAM ''name'', ''comment'', [''a'',''b'',''c'' | bool]
||When starting a script, a start page is shown where one can enter additional parameters for the script. Parameters can be defined either centrally for all scripts in the ODB under /Experiment/Edit on sequence. This subdirectory in the ODB can contain links to ODB values, which are queried at the start page. In addition, each script can define additional parameters appended to this list. They will be stored under /Sequencer/Variables and can be referenced inside the script via $name, where name can be any variable name specified in the parameter statement. The optional "comment" is shown on the start page below the parameter name. If only certain options are possible for the parameter, they can be defined via the options list. The web page will then contain a drop-down list showing the options. In case of type="bool", a checkbox will be shown.
|-
||<RunDescription> ''description'' </RunDescription>
||RUNDESCRIPTION ''description''
||a run description which is stored under /Experiment/Run Parameters/Run Description .
|-
||<Script [params="''a'',''b'',''c'',..."]> ''script'' </Script>
||SCRIPT ''script'' [, a, b, c, ...]
||To call a script on the server side. Optionally, pass parameters to the script.
|-
||<Set name="''name''"> ''value'' </Set>
||SET ''name'', ''value''
||Sets the variable ''name'' to "value". The variable can then be referenced later in the script by putting a "$" in front of the name like $"name".
|-
||<Subroutine name="''name''">...</Subroutine>
||SUBROUTINE ''name'' ... ENDSUBROUTINE
||Declares a subroutine which can be called via CALL.
|-
||<Transition>Start | Stop</Transition>
||TRANSITION start | stop | pause | resume
||To start, stop, pause or resume a run
|-
||<Wait for="events | ODBvalue | seconds" [path="''ODB path''"] [op=">=/>/<=/</==/!="]> ''value'' </Wait>
||WAIT events | ODBvalue | seconds, [''ODB path''], [''op''], [''value'']
||Wait until a number of events is acquired (testing /Equipment/Trigger/Statistics/Events sent), or until a value in the ODB exceeds value, or wait for ''value'' seconds. If the operand ''op'' is given, the ODB value is compared with value using this operand. So one could wait until an ODB value is equal to value or becomes smaller than value. Here is an example of such a statement which waits until some high voltage is below 100 V.
WAIT ODBvalue, /Equipment/HV/Variables/Measured[3], <, 100
|}

= MSL Example =
The following example is a simple script, which writes a run description to the ODB, asks for a number of runs, then executes the runs, each running for 60 seconds.

<pre>
COMMENT "This is a MSL test file"
RUNDESCRIPTION "Test run"
PARAM runs

LOOP $runs
TRANSITION START
WAIT Seconds 60
TRANSITION STOP
ENDLOOP
</pre>

= XML Example =
The following XML script does exactly the same.
<pre>
<?xml version="1.0" encoding="ISO-8859-1"?>
<RunSequence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="">

<Comment>This is a XML test file</Comment>
<RunDescription>Test run</RunDescription>
<Param name="runs" />

<Loop n="$runs">
<Transition>START</Transition>
<Wait for="events">3000</Wait>
<Transition>STOP</Transition>
</Loop>

</RunSequence>
</pre>

[[Category:Sequencer]]

File:Seq newscript.png

2017-09-27T01:16:40Z

Suz: Sequencer page where the example script has been loaded

Sequencer page where the example script has been loaded

File:Seq noscript.png

2017-09-27T01:15:35Z

Suz: Sequencer page where no script has been loaded

Sequencer page where no script has been loaded

MIDAS environment variables

2017-01-23T23:27:55Z

Suz:

{{Pagelinks}}

= Introduction =
MIDAS uses a several environment variables to facilitate the startup of the different applications. Only [[#MIDASSYS|MIDASSYS]] is required.

The MIDAS environment variables are also discussed in [[Compilation & Build]] and [[QuickStart]].

;NOTE
:Except where noted, the following environment variables are defined on the '''MIDAS experiment host''', i.e. the host on which the MIDAS experiment shared memories are residing.
<br>
---------
<br>
= MIDASSYS =
This environmental variable is required. It should point to the main path of the installed MIDAS package on the experiment host e.g.
;csh : setenv MIDASSYS $HOME/packages/midas
;bash : export MIDASSYS=$HOME/packages/midas
The application [[odbedit]] will generate a warning message unless this variable is defined.

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

= MIDAS_EXPTAB =
This variable specifies the location of the optional [[exptab (Experiment Table)|exptab]] file containing the predefined MIDAS experiment(s), e.g.

;csh : setenv MIDAS_EXPTAB $HOME/online/exptab
;bash : export MIDAS_EXPTAB = $HOME/online/exptab

If '''MIDAS_EXPTAB''' is not defined, the default location will be used (i.e. for OS_UNIX: ''/etc'', / and for OS_WINNT: ''\system32, \system '').

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

= MIDAS_SERVER_HOST =

If all the MIDAS clients run on the '''experiment host''', this variable is NOT defined.

It is needed when a connection to a remote experiment is requested. In that case, this variable is '''defined on the remote host(s)''', and predefines the name of the [[#Introduction|experiment host]]. In this case, the [[mserver]] client must also be started on the experiment host. See [[Quickstart Linux|Quickstart]] for more information.

Defining MIDAS_SERVER_HOST makes adding the "''-h <hostname>''" argument to the application command unnecessary (see [[Common Parameters to MIDAS Utilities]]).

'''MIDAS_SERVER_HOST''' will be superseded by [[#MIDAS_DIR |MIDAS_DIR]] if defined. This variable is valid for Unix as well as Windows OS.

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

= MIDAS_EXPT_NAME =

Where there are multiple experiments available on the MIDAS experiment host, this variable predefines the name of the experiment to which the user wishes to connect. It prevents the requested application from asking for the experiment name. Defining MIDAS_EXPT_NAME makes adding the ''"-e <exptname>"'' argument to the application command unnecessary (see [[Common Parameters to MIDAS Utilities]]).

'''MIDAS_EXPT_NAME''' will be superseded by [[#MIDAS_DIR |MIDAS_DIR]] if defined. This variable is valid for Unix as well as Windows OS.

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

= MIDAS_DIR =
This variable predefines the LOCAL directory path where the shared memories for the experiment are located. Defining this variable results in a single experiment called "Default". Since a given directory path can only refer to a single experiment, '''MIDAS_DIR''' supersedes the ''"-e <exptname>"'' and "''-h <hostname>''" arguments as well as the [[#MIDAS_SERVER_HOST |MIDAS_SERVER_HOST]] and [[#MIDAS_EXPT_NAME|MIDAS_EXPT_NAME]] environment variables.

;Note : If you wish to use the [[exptab]] file to define multiple experiments on a single host, do not define '''MIDAS_DIR'''.

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

= MIDAS_INVALID_STRING_IS_OK =
;Note
: Environment variable MIDAS_INVALID_STRING_IS_OK and UTF-8 key check added Jan 2017.

By default, the ODB keys names are checked to ensure they are UTF-8 compliant (see [[ODB Access and Use#ODB Keys|ODB Keys]] for more information).

Defining environment value '''MIDAS_INVALID_STRING_IS_OK''' (set to any value) disables this key check. The existence of this environment value is only checked for once, when a program starts.

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

= ROOTSYS =
This variable must point to the ROOT package if generating a complete MIDAS/ROOT analyzer application. If not using ROOT, '''ROOTSYS''' should be undefined.

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

= CERNLIB_PACK =
In case of HBOOK/PAW analyzer application, this variable should be pointing to a valid cernpacklib.a library. See [[#HAVE_HBOOK |HAVE_HBOOK]].

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

= MIDAS_FRONTEND_INDEX =
This variable predefines the index assigned to the equipment using the event builder option. Useful if the [[Frontend Application|Frontend Applications]] are started from different hosts. Refer to [[Event Builder#Event Builder and related frontend fragment|Event Builder and related frontend fragment]] for more information.
<br>
---------
<br>

= MCHART_DIR =
This variable is used for the old [[mchart]] utility.

[[Category:Environment variable]] [[Category:Appendices]]

ReadOn Flags

2016-12-12T23:39:58Z

Suz:

{{Pagelinks}}

Read-on flags RO_xxx are used in the [[Equipment List Parameters#ReadOn|Read On]] field of the equipment declaration to specify when the read-out of an event occurs. These flags are defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h.html midas.h].
* Multiple flags can be ORed together, e.g. RO_RUNNING|RO_ODB.
* RO_TRANSITIONS is equivalent to RO_BOR|RO_EOR|RO_PAUSE|RO_RESUME.

{| class="wikitable"
|+ READ_ON Flags
|-
! READ_ON Flag name !! Value !! Readout Occurs
|-
|RO_RUNNING || 1 || While running
|-
|RO_STOPPED || 2|| Before stopping run
|-
|RO_PAUSED || 4 || When run is paused
|-
|RO_BOR || 8|| At the beginning of run
|-
|RO_EOR || 16|| At the end of run
|-
|RO_PAUSE || 32|| Before pausing the run
|-
|RO_RESUME || 64|| Before resuming the run
|-
|RO_TRANSITIONS || 127 || At all transitions
|-
|RO_ALWAYS || 255||Always (independent of the run status)
|-
|RO_ODB || 256 ||Copies the event to the <span style="color: purple; font-style:italic;">/Equipment/<equipment name>/Variables</span> ODB tree. The ODB is updated with a new event approximately every second.<br>Note that this feature is generally used only for testing or monitoring, as writing large amounts of data to the ODB takes time.
|}

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

Edit-on-start Parameters

2016-11-26T00:18:00Z

Suz:

{{Pagelinks}}
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Edit-on-Sequence Parameters]]
* [[/Experiment ODB tree]]
* mhttpd [[Start Page]]
</div>
== Introduction ==
When a run is started, by default only the
[[/Runinfo ODB tree #Run number|run number]] of the upcoming run will be displayed for editing (Figure 1).

{| class="wikitable"
|+ Figure 1: Run start with no edit-on-start parameters defined
|-
! Using [[mhttpd]] !! Using [[odbedit]]
|-
|[[File:Mhstart1.gif|left|border|300px]]
|
<pre>
[local:bnmr:S]/Experiment>start
Run number [30499]:
Are the above parameters correct? ([y]/n/q):
</pre>
<br><br>
|}

== ''edit-on-start'' parameters ==
It is often convenient to display and edit additional parameters prior to the run start. Not surprisingly, these parameters are known as '''''edit-on-start''''' parameters, since they automatically appear every time a run starts, and they are editable by the user.

''Edit-on-start'' parameters are defined by creating ODB keys (or links to existing ODB keys) in a special subtree named <span style="color: purple;">''Edit on start''</span> that the user creates in the
[[/Experiment ODB tree]].

Many users link to the [[Keys in the ODB /Logger tree #/Logger/Write data |Write data key]] (see [[#Creating ''edit-on-start'' parameters|below]]) which enables/disables writing of data. A quick test run can then be made without data logging (see Figure 2).

{| class="wikitable"
|+ Figure 2: Run start with one edit-on-start parameter defined
|-
! Using [[mhttpd]] !! Using [[odbedit]]
|-
| [[File:Mhstart.gif|left|border|400px]]
|
<pre>
[local:test:S]/Experiment>start
Write data : n
Run number [30499]:
Are the above parameters correct? ([y]/n/q):
</pre>
<br><br>
|}

;Note
By using the {{Odbedit cmd|cmd=start now}}, any edit-on-start parameters will ''not'' be displayed; the run will start immediately.

<br><br><br>

== Creating ''edit-on-start'' parameters ==

;Note
: The examples shown here use <span style="color:darkcyan;">''odbedit''</span> for ease of documentation; many users will prefer to use the editing function of the <span style="color:darkcyan;">''mhttpd''</span> [[ODB Page]] to create the ODB keys.
<br>
The first step to setting up the ''edit-on-start'' parameters is to create the subtree <span style="color: purple;">''Edit on start''</span> under <span style="color: purple;">''/Experiment''</span> as follows:

$odbedit
[local:Default:S]/>cd /experiment
[local:Default:S]/Experiment>mkdir "Edit on start"
[local:Default:S]/Experiment>cd "Edit on start"
[local:Default:S]/Edit on start>

Then the user either creates the required parameters, or, if the parameters already exist elsewhere in the ODB, creates '''links''' to the parameters in the <span style="color: purple;">''Edit on start''</span> subtree.

Some users find it convenient to create a subtree of <span style="color: purple;">''/Experiment''</span> named <span style="color: purple;">''Run Parameters''</span> to contain the run parameters. Links to these parameters in the subtree {{Odbpath|path=Run Parameters}} are then created in the <span style="color: purple;">''Edit on start''</span> subtree.

The example below shows the creation of three parameters in the <span style="color: purple;">''Edit on start''</span> subtree.:

* a parameter to contain the title of the run (called <span style="color: purple;">''run_title''</span> )
* a link to the ODB parameter <span style="color: purple;">''/Logger/Write data''</span>
* a link to the ODB parameter <span style="color: purple;">''/Equipment/FIFO_acq/frontend/hardware/num cycles''</span>(previously created by the user)
* a link to the ODB parameter <span style="color: purple;">''/Equipment/Run Parameters/Run Description''</span> (previously created by the user)

[local:Default:S]/Edit on start>
[local:Default:S]/Edit on start>create string run_title
String length [32]:128
[local:Default:S]/Edit on start>ln "/Equipment/FIFO_acq/frontend/hardware/num cycles" "Number of cycles"
[local:Default:S]/Edit on start>ln "/Experiment/Run Parameters/Run Description" "Description"
[local:Default:S]/Edit on start>ln "/Logger/Write data" "write data"
[local:Default:S]Edit on start>ls -lt
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
run_title STRING 1 128 13m 0 RWD
Number of cycles -> /equipment/fifo_acq/frontend/hardware/num cycles
DWORD 1 4 >99d 0 RWD 0
write data -> /logger/Write data
BOOL 1 4 >99d 0 RWD y
Description -> /Experiment/Run Parameters/Run Description

<br><br><br>
== ''edit-on-start'' parameter comments ==

An optional subdirectory <span style="color: purple;">''Parameter Comments''</span> can be created under the [[/Experiment ODB tree]] to display some extra text on the [[mhttpd]] Start page under an [[#edit-on-start parameters|edit-on-start parameter]] where the parameter name may not contain enough information. In this case, a parameter comment can be created by the user.

This "parameter comment" option is visible ONLY when using the MIDAS web server [[mhttpd]]. The [[odbedit]] start command will not display this extra information.

The name of the parameter in the <span style="color: purple;">''Parameter Comments''</span> subtree must match that of the corresponding edit-on-start parameter.

=== Parameter comments when edit-on-start parameter is a link ===
If the edit-on-start parameter is a link ''which is named differently from the actual parameter'', then the parameter name in the <span style="color: purple;">''Parameter Comments''</span> subtree must match the name of the actual parameter, rather than the link-name.

This is illustrated in the below, where the Edit-on-start parameter is a link named "number of cycles", which links to the actual parameter named <span style="color: purple;">''/equipment/fifo_acq/frontend/hardware/num cycles''</span>. The parameter name in the <span style="color: purple;">''Parameter Comments''</span> subtree for this parameter must be '''"num cycles"''' and '''NOT "number of cycles"'''.
<pre>
[local:bnqr:Stopped]Parameter Comments>ls "Edit on start/Number of cycles"
Number of cycles -> /Equipment/FIFO_acq/frontend/hardware/num cycles
0
[local:bnqr:Stopped]/Experiment>ls "Parameter Comments/Num cycles"
Num cycles Stop run after number of cycles is reached. Enter 0 to disable (free running)
</pre>

=== Adding HTML styles to parameter comments ===

HTML styling can be added to the parameter comments using the HTML span tag, as in Figures 3a and 3b.
;Figure 3a Adding HTML styling to the parameter comments Keys in ODB
[[File:Bnqr_parameter_comments.png|border|750px]]
<br clear=all>
<br><br>
'Figure 3b Parameter comments shown with HTML styling
[[File:Bnqr_run_start.png|border]]
<br clear=all>

<br><br><br>
== Example of ''edit-on-start'' parameters ==
The relevant parts of the /Experiment tree are shown below
[local:test:S]/Experiment>ls -lr
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Experiment DIR
Name STRING 1 32 5s 0 RWD test
.........
Run Parameters DIR
Run Description STRING 1 256 2h 0 RWD Test run
edit on start DIR
run_title STRING 1 128 1m 0 RWD test without beam
experiment number STRING 1 32 1m 0 RWD 12345
sample STRING 1 32 1m 0 RWD NA
field STRING 1 32 52s 0 RWD 2500
Number of cycles -> /equipment/fifo_acq/frontend/hardware/num cycles
DWORD 1 4 >99d 0 RWD 0
write data -> /logger/Write data
BOOL 1 4 >99d 0 RWD y
Description -> /Experiment/Run Parameters/Run Description
STRING 1 256 2h 0 RWD Test run
parameter comments DIR
field STRING 1 64 35m 0 RWD <i>Entered in Tesla unit</i>
active STRING 1 64 35m 0 RWD <i>Enter y to save data to disk</i>
Num cycles STRING 1 80 34m 0 RWD <i>Stop run after num cycles is reached. Enter 0 to disable (free running)</i>
.......

Starting a run with edit-on-start parameters set up as above, results in a list of the edit-on-start parameters which the user can change (Figure 4).

<br>

{| class="wikitable"
|+ Figure 4: Run start with many edit-on-start parameters defined
|-
! Using [[mhttpd]] !! Using [[odbedit]]
|-
| [[File:Mhstart2.gif|left|border|700px]]
|
<pre>
[local:test:S]/Experiment>start
run_title : test without beam
experiment number : 12345
sample : NA
field : 2500
Number of cycles : 0
write data : y
Description : Test run
Run number [30499]:
Are the above parameters correct? ([y]/n/q):
Starting run #30499
</pre>
|}

<br><br><br>

== Prevent the run number being edited at Run Start ==
;NOTES
# Most experiments do not use this feature. It was requested for experiments where the run number is strictly controlled, e.g. with a custom run number checking system that assigns the run number automatically based on the type of run.
#This feature is ignored by [[odbedit]]; regardless of whether the key <span style="color: purple; font-style:italic;">Edit run number</span> is present, the run number may be edited when using <span style="color:darkcyan;font-style:italic">odbedit</span> to start the run.

By default, the user has the option to edit the run number at begin of run. To prevent this, the user may add an optional key {{Odbpath|path=Edit run number}} to the {{Odbpath|path=/Experiment/Edit on Start}} subdirectory. If this key is set to "n", the user will not be able to edit the run number on the mhttpd [[Start Page]] at the begin of run.

By creating the key {{Odbpath|path=/Experiment/Edit on Start/Edit run number}} as a Boolean variable, the ability of editing the run number in the {{Utility|name=mhttpd}} [[Start Page]] is enabled or disabled, e.g.

[local:Default:S]Edit on start>create BOOL "Edit run number"
[local:Default:S]Edit on start>set "Edit run number" n

By default, if this key is NOT present, the run number IS editable.

Figure 5 shows edit-on-start parameters with the key "Edit run number" present, using the mhttpd [[ODB Page]] (Figure 5a) or [[odbedit]] (Figure 5b).
{| class="wikitable"
|+ Figure 5: Displaying edit-on-start parameters
|-
! Figure 5a: Using [[mhttpd]] [[ODB Page]] !! Figure 5b: Using odbedit
|-
| [[File:odb_edit_on_start.png|left|border|700px]]
| <pre>
[local:bnqr:Stopped]/Experiment>ls "Edit on start/
run_title MgO, HH=22mT, 300 K, 28 keV 31Mg, SLR
experiment number 9998
experimenter ms cdpl wlk lp gdm
sample MgO
orientation 100
temperature 300 K
field 220 G
run mode -> /Experiment/run parameters/run mode
1
Number of cycles -> /Equipment/FIFO_acq/frontend/hardware/num cycles
0
write data -> /Equipment/FIFO_acq/mdarc/enable mdarc logging
y
Edit run number n
</pre>
|}
<br><br>

The resulting {{Utility|name=mhttpd}} [[Start Page]] is shown below (Figure 6).

'''Figure 6: Start Page where run number cannot be edited'''
[[File:edit-on-start.png|left|border|1000px|Figure 6]]
<br clear=all>

[[Category:Experiment]]

File:Bnqr parameter comments.png

2016-11-25T23:52:33Z

Suz: bnqr parameter comments odb keys showing HTML styling

bnqr parameter comments odb keys showing HTML styling

File:Bnqr run start.png

2016-11-25T23:51:36Z

Suz: Suz uploaded a new version of File:Bnqr run start.png

run start parameters showing styling of parameter comments

File:Bnqr run start.png

2016-11-25T23:44:56Z

Suz: run start parameters showing styling of parameter comments

run start parameters showing styling of parameter comments

/Experiment ODB tree

2016-11-25T22:59:51Z

Suz:

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[odbedit]]
*
*
</div>

== Creating the <span style="color: purple;">''/Experiment''</span> tree ==
The <span style="color: purple;">''/Experiment''</span> ODB tree is created automatically when the '''[[odbedit #Creating the ODB|ODB is first created]]'''.

== Purpose ==
The <span style="color: purple;">''/Experiment''</span> ODB tree contains information relevent to the experiment. Other optional keys are added by '''[[mhttpd]]''' or by
the user to customize their experiment.

== Examples ==
When initially created, the <span style="color: purple;">''/Experiment''</span> tree contains the following keys:
[local:midas:S]/>ls -lrt /experiment
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Experiment DIR
Name STRING 1 32 14s 0 RWD midas
Buffer sizes DIR
SYSMSG DWORD 1 4 11h 0 RWD 100000
Security DIR
Enable non-localhost RPC BOOL 1 4 46s 0 RWD n
RPC ports DIR
ODBEdit DWORD 1 4 38m 0 RWD 0
RPC hosts DIR
Allowed hosts STRING 10 256 38m 3 RWD
[0] localhost
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
Disable RPC hosts check BOOL 1 4 46s 0 RWD n

The following example shows the <span style="color: purple;">''/Experiment''</span> tree for a typical experiment:

[local:midas:R]/>ls -lrt /experiment
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Experiment DIR
Name STRING 1 32 7s 0 RWD midas
<span style="color: purple;">Buffer sizes</span> DIR
SYSMSG DWORD 1 4 23h 0 RWD 100000
SYSTEM DWORD 1 4 23h 0 RWD 640000000
BUF0 DWORD 1 4 23h 0 RWD 80000000
BUF1 DWORD 1 4 23h 0 RWD 80000000
....... <span style="color: green;">''other user-defined buffers not shown ''</span>
<span style="color: purple;">Security</span> DIR
Enable non-localhost RPC BOOL 1 4 38m 0 RWD n
<span style="color: purple;">RPC ports</span> DIR
ODBEdit DWORD 1 4 38m 0 RWD 0
Logger DWORD 1 4 35m 0 RWD 0
mhttpd DWORD 1 4 23m 0 RWD 0
<span style="color: purple;">RPC hosts</span> DIR
Allowed hosts STRING 10 256 38m 3 RWD
[0] localhost
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
Disable RPC hosts check BOOL 1 4 38m 0 RWD n
<span style="color: purple;">mhttpd hosts</span> DIR
Allowed hosts STRING 10 256 5h 0 RWD
[0]
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
midas http port INT 1 4 5h 0 RWD 8080
midas https port INT 1 4 5h 0 RWD 8443
http redirect to https BOOL 1 4 5h 0 RWD y
CSS File STRING 1 1024 9h 0 RWD mhttpd.css
JS File STRING 1 1024 9h 0 RWD mhttpd.js
Menu Buttons STRING 1 1000 9h 0 RWD Status, ODB, Messages, ELog, Alarms, Programs, History, Sequencer, Config, Help
Start-Stop Buttons BOOL 1 4 8h 0 RWD y
Pause-Resume Buttons BOOL 1 4 8h 0 RWD n
<span style="color: purple;">Status items</span> DIR
Experiment Name -> /Experiment/Name
MAX_EVENT_SIZE DWORD 1 4 23h 0 RWD 4194304
Midas server port DWORD 1 4 3m 0 RWD 1175
Transition debug flag INT 1 4 23h 0 RWD 0
Transition connect timeout INT 1 4 23h 0 RWD 10000
Transition timeout INT 1 4 23h 0 RWD 120000
<span style="color: purple;">edit on start</span> DIR
experiment number DWORD 1 4 2h 0 RWD 9499
field STRING 1 32 2h 0 RWD 19000.2(0.0)G
comment-> /Experiment/run parameters/comment
STRING 1 80 2h 0 RWD Testing with low beam
Number of channels -> /Run Parameters/number of channels
DWORD 1 4 2h 0 RWD 20
Write Data -> /Logger/Write data
BOOL 1 4 2h 0 RWD n
Number of cycles -> /Equipment/FIFO_acq/frontend/hardware/num cycles
DWORD 1 4 2h 0 RWD 0
<span style="color: purple;">Parameter Comments</span> DIR
field STRING 1 32 >99d 0 RWD <i>Entered in Tesla unit</i>
Num cycles STRING 1 80 >99d 0 RWD <i>Stop run after num cycles is reached. Enter 0 to disable (free running)</i>
<span style="color: purple;">Run Parameters</span> DIR
Comment STRING 1 80 2h 0 RWD Testing with low beam
Run Description STRING 1 256 7h 0 RWD Sequencer Tests
Number of channels DWORD 1 4 2h 0 RWD 20
<span style="color: purple;">Lock when running</span> DIR
Num channels -> /Run Parameters/number of channels
DWORD 1 4 2h 0 RWD 20
<span style="color: purple;">edit on sequence</span> DIR
title STRING 1 128 2h 0 RWD none
experiment number DWORD 1 4 2h 0 RWD 9438
experimenter STRING 1 32 2h 0 RWD gls
sample STRING 1 36 2h 0 RWD NA
run description -> /Experiment/run parameters/run description
STRING 1 256 7h 0 RWD Sequencer Tests
Write Data -> /Logger/Write data
BOOL 1 4 2h 0 RWD n
Number of cycles -> /Equipment/FIFO_acq/frontend/hardware/num cycles
DWORD 1 4 2h 0 RWD 0
Prevent start on alarms BOOL 1 4 22h 0 RWD n
Prevent start on required BOOL 1 4 22h 0 RWD n
<span style="color: purple;">Status items</span> DIR
Experiment Name -> /Experiment/Name
STRING 1 32 7s 0 RWD midas
Start-Stop Buttons BOOL 1 4 5h 0 RWD y
Pause-Resume Buttons BOOL 1 4 5h 0 RWD n

== Keys in <span style="color: purple;">''/Experiment''</span> tree==

The keys in the ODB <span style="color: purple;">''/Experiment tree''</span>
are described in the following sections.

=== <span style="color: purple;">''Name ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This key in the [[#top|/Experiment tree]]
contains the name of the experiment. It is created by the MIDAS system when the ODB is created.

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

=== <span style="color: purple;">''Buffer Sizes ''</span> subtree ===
* '''Type:''' DIR

This key in the [[#top|/Experiment tree]] is a subtree to contain the sizes of the
Midas Buffers for the experiment. Created by the MIDAS system with default values. The sizes can be changed to optimize the memory usage. See '''[[Event Buffer]]''' Size(s) for details. Other user-defined
buffers may be present (e.g. for '''[[event filtering]]''').
<br>
--------
<br>

==== <span style="color: purple;">''SYSMSG ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 100000 Bytes
</div>
This key in the [[#Buffer Sizes|/Experiment/Buffer Sizes subtree]]
contains the size of SYSMSG buffer. This buffer is used for MIDAS messages.
The default value of this key is defined by MESSAGE_BUFFER_SIZE in $MIDASSYS/include/msystem.h .

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

==== <span style="color: purple;">''SYSTEM ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 32MiBytes
</div>
This key in the [[#Buffer Sizes|/Experiment/Buffer Sizes subtree]]
contains the size of SYSTEM buffer. The default value of this key is
DEFAULT_BUFFER_SIZE = 32 MiB (defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h_source.html midas.h]).
The actual SYSTEM buffer size is set by this key. To increase the SYSTEM buffer size (e.g. for very large events), see [[Event Buffer]].
<br>
--------
<br>

=== <span style="color: purple;">''MAX_EVENT_SIZE ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 4MiBytes
</div>
This key in the [[#top|/Experiment tree]]
specifies the maximum event size that can be acquired. The default value of this key is
DEFAULT_MAX_EVENT_SIZE = 4 MiB (defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h_source.html midas.h]).
The actual maximum event size is set by this key, and can be increased for larger events if needed (see [[Event Buffer]] for more information).

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

=== <span style="color: purple;">''midas http port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 8080
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the listening port for the HTTP server (default 8080). This will be redirected to the secure HTTPS port given by [[#midas https port|midas https port]] if the key [[#http redirect to https|http redirect to https]] is set to "y".

If the http port are supplied with the "--http" option when starting {{Utility|name=mhttpd}}, the port supplied will overwrite the default value stored in this key. See [[mhttpd]] for details.

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''midas https port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 8443
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the listening port (default 8443) for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]).

If the https port is supplied with the "--https" option when starting {{Utility|name=mhttpd}}, the port supplied will overwrite the default value stored in this key. See [[mhttpd]] for details.

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''http redirect to https''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' y
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. If set to "y", connections to the http port (specified by the key [[#midas http port|midas http port]] will be redirected to hte https port (specified by the key [[#midas https port|midas https port]], i.e. the listening port for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]).

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''midas server port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 1175
</div>

This key is created when [[mserver]] is started for the first time. It contains the default value of the port used by [[mserver]]. This is set to MIDAS_TCP_PORT = 1175 ( midas.h). A different port can be used by starting [[mserver]] with the -p argument.

;NOTE
: This key was added in May 2015 (see [[Security]]).

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

=== <span style="color: purple;">''CSS File''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "mhttpd.css"
</div>
This key in the [[#top|/Experiment tree]] contains the name of the [[Custom Page Features#MIDAS stylesheet|MIDAS stylesheet]] file for the use of those writing [[Custom Page|Custom Web Pages]].

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

=== <span style="color: purple;">''JS File''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "mhttpd.js"
</div>
This key in the [[#top|/Experiment tree]] contains the name of the [[mhttpd.js|Javascript library]] file for the use of those writing [[Custom Page|Custom Web Pages]].

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

=== <span style="color: purple;">''Menu Buttons''</span> ===
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* '''Type:''' STRING
* '''Default:''' "Status, ODB, Messages, ELog, Alarms, Programs, History, Sequencer, Chat, Config, Help"
</div>
This key in the [[#top|/Experiment tree]]
is added automatically by '''[[mhttpd]]''' to allow the Menu buttons that appear on the '''[[mhttpd|Main Status Page]]''' to be customized by
removing unnecessary buttons or by changing their order.

The Start/Stop/Pause/Resume buttons are not now included in <span style="color: purple;">''Menu Buttons''</span>.
* To suppress/display the Start/Stop buttons use key [[#Start-Stop Buttons|Start-Stop Buttons]].
* To display/suppress the Pause/Resume buttons, use key [[#Pause-Resume Buttons|Pause-Resume Buttons]].

; Note
:If [[MSCB Page#MIDAS with MSCB support|MSCB support]] is built into MIDAS, the default will also include the MSCB Menu button (see [[MSCB Page]]).

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

=== <span style="color: purple;">''Start-Stop Buttons''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' y
</div>
This key in the [[#top|/Experiment tree]] is added automatically by '''[[mhttpd]]''' to allow the user to suppress the Start or Stop buttons from appearing on the [[Status Page]]. By default, Start/Stop buttons are shown.

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

=== <span style="color: purple;">''Pause-Resume Buttons''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' n
</div>
This key in the [[#top|/Experiment tree]] is added automatically by '''[[mhttpd]]'''.
By default the Pause/Resume menu buttons do not appear on the [[Status Page]]. The user can allow these buttons
to appear during the run by setting this key to "y".

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

=== <span style="color: purple;">''Transition debug flag ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#top|/Experiment tree]] contains a flag that, if set to 1, causes messages reporting transition progress to be output.
<br>
--------
<br>

=== <span style="color: purple;">''Transition connect timeout''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 10000
</div>
This key in the [[#top|/Experiment tree]] contains the
value of timeout for remote rpc connect
<br>
--------
<br>

=== <span style="color: purple;">''Transition timeout''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 120000
</div>
This key in the [[#top|/Experiment tree]] contains the
value of timeout for transition
<br>
--------
<br>

=== <span style="color: purple;">''Prevent start on alarms''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
This key in the [[#top|/Experiment tree]] if set true
will prevent the run from starting if an [[Alarm System|alarm]] is true, i.e.
the run start procedure will fail if an alarm has been [[/Alarms ODB tree#Triggered|Triggered]] for a client, provided a valid [[/Alarms ODB tree#alarms class|alarms class]] has
been entered in the client's [[/Programs ODB tree#Alarm class|Alarm class]] key.

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

=== <span style="color: purple;">''Prevent start on required program''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
This key in the [[#top|/Experiment tree]] if set true ("y")
will prevent the run from starting if one of the '''required''' clients is not running. A client is flagged as "required" by setting the ODB key
[[/Programs ODB tree#Required|Required]] to "y".
<br>
--------
<br>

=== <span style="color: purple;">''Edit on Sequence ''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
This optional subdirectory in the [[#top|/Experiment tree]] may
contain user-defined parameters which will be displayed for editing at the start of each [[Sequencer|Sequence]]. See [[Edit-on-Sequence Parameters]] for details.

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

=== <span style="color: purple;">''Edit on Start ''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
This optional subdirectory in the [[#top|/Experiment tree]] may
contain user-defined parameters which will be displayed for editing at the beginning of each run. See '''[[Edit-on-start Parameters]]''' for details.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] contains user-defined links to ODB parameters to prevent them being changed when the run is in progress. See '''[[Lock when running]]''' for details.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] may contain user-defined parameter comments that give more information about
the '''[[Edit-on-start Parameters]]'''. See [[Edit-on-start Parameters#edit-on-start parameter comments|creating parameter comments]] for details.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] may contain user-defined parameters or parameter(s)
with reserved names (i.e. [[#Run Description|Run Description]]).

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

==== <span style="color: purple;">''Run Description''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This ODB key is used by the [[Sequencer]] [[Sequencer#RUNDESCRIPTION|RUNDESCRIPTION]] command to store the
run description.

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

==== <span style="color: purple;">''<parameter name>''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
The user may define parameters here e.g. for linking as '''[[Edit-on-start Parameters|Edit-on-start]]''' or '''[[Edit-on-Sequence Parameters|Edit-on-Sequence]]''' parameters.

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

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

This key in the [[#top|/Experiment tree]] is a subtree which by default contains a link to the [[#Name|experiment name]]. Any links or keys
created by the user in this optional subdirectory will be displayed on the [[mhttpd]] main status page.
<br>
--------
<br>

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

This optional subtree in the [[#top|/Experiment tree]] is created when the '''[[odbedit]]''' commands <span style="color:saddlebrown; font-style:bold; ">passwd</span> or <span style="color:saddlebrown; font-style:bold; ">webpasswd</span> are issued. It enables a user to set up security features. See '''[[Security]]'''.
<br>
--------
<br>

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

Setting the key to "n" (the default) causes access by unauthorized hosts to be prevented by the system checking the RPC access control list (see [[#RPC hosts subtree|RPC hosts/Allowed hosts]]).

If MIDAS clients have to connect from random hosts (i.e. dynamically assigned random DHCP addresses), one can disable the host name checks by
setting this key to "y". This configuration is insecure and should only be done on a private network behind a firewall. See [https://midas.triumf.ca/elog/Midas/1080 Note 1080].

; NOTE
: This key was added August 2015. Used by [[mserver]] to improve network [[Security]] for the MIDAS experiment.

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

==== <span style="color: purple;">''Enable non-localhost RPC''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
The default value of this key is "n", denying access by external network connections. If running an experiment that requires external network connections, this key must be set to "y" and the key [[#RPC hosts|RPC hosts]] must be filled. See [https://midas.triumf.ca/elog/Midas/1080 Note 1080].

; NOTE
: This key was added August 2015. Used by [[mserver]] to improve network [[Security]] for the MIDAS experiment.

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

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]'''). This subdirectory contains the names of MIDAS clients and their fixed TCP port numbers. When a client is started for the first time, an entry named for the client will be created in this subtree.
<br>
--------
<br>

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

When a MIDAS client is started, a key will be created named for that client. It will contain the fixed TCP port number that the MIDAS client is using.
Clients started on the local host will have TCP port numbers of 0 (default).

Once a remote [[Frontend Operation|frontend]] is bound to a fixed port, appropriate openings can be made in the firewall, etc. Default port number value
will be 0 meaning "use random port", same as now. See [https://midas.triumf.ca/elog/Midas/1079].

;NOTE
: This feature was added August 2015. It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

<div id="Allowed hosts (rpc hosts)"></div> 
===== <span style="color: purple;">''Allowed hosts''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING array
* '''Default:''' "localhost"
</div>
This key in the [[#RPC hosts subtree|/Experiment/Security/RPC hosts subtree]] is new as of August 2015 and is created by the system (i.e. midas.c).

It is part of the improved security features of MIDAS (See '''[[Security]]''') and is used to maintain a Network Access Control list.
The access control list array is self-growing - it will have at least 10 empty entries at the end at all times.

The default value for {{Odbpath|path=Allowed hosts[0]}} is "localhost", which will reject all external connections, even when permitted by [[#Enable external RPC connections|Enable external RPC connections]]. The user will be required to enter the names of all machines that will run midas clients in this array. See [https://midas.triumf.ca/elog/Midas/1090].

All clients' db_watch() routines watch the access control list and automatically reload it when it is changed, so there is no need to restart clients.

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

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

<div id="Allowed hosts (mhttpd hosts)"></div> 
===== <span style="color: purple;">''Allowed hosts''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING array
* '''Default:''' "localhost"
</div>
This key in the [[#RPC hosts subtree|/Experiment/Security/mhttpd hosts subtree]] is new as of August 2015 and is created by the system (i.e. midas.c).

It is part of the improved security features of MIDAS (See '''[[Security]]''') and is used to maintain an access control list for [[mhttpd]]. An empty list means free access from everywhere. Access control is also controlled by the [[mhttpd]] "-a" command line arguments. Hosts supplied by the "-a" command line arguments are not added to the access control list by the system.

The access control list is watched by {{Utility|name=mhttpd}}, therefore there is no need to restart it after updating the list.

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

<div style="background-color:whitesmoke">

=== <span style="font-size:120%; font-style:bold">The following keys are OBSOLESCENT - replaced by the [[Security|security features]] added Aug 2015</span> ===
==== <span style="color: purple;">''Password ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

;Notes
<ol>
<li>This feature pre-dates the improved [[Security]] features (August 2015)</li>
<li> Do not set this key except through the {{Odbedit cmd|cmd=passwd}}. Setting an unencrypted password will lock you out of the ODB unless {{Utility|name=odbedit}} is listed in the [[#Allowed programs subtree|allowed programs subtree]].</li>
<li>This security feature is not proof against malicious access. See [[Security]] for details.</li>
</ol>

This optional key in the [[#Security|/Experiment/Security subtree]]
contains the encrypted password. This Key is created when the {{Odbedit cmd|cmd=passwd}} is issued. See [[Security#Restrict user access|Restrict user access]] for details.

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

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

;Notes
* This subtree pre-dates the improved [[Security]] features (August 2015) and is not to be confused with [[#RPC hosts subtree|RPC hosts/Allowed hosts]] array.
* This security feature is not proof against malicious access. See [[Security]] for details.

This subtree in the [[#Security|/Experiment/Security subtree]] is created when the {{Odbedit cmd|cmd=passwd}} is issued. When created, this subtree is empty.
Optionally, it may contain user-defined names of remote hosts allowed to have free access (i.e. without password) to the current experiment.

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

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

;Notes
* This subtree pre-dates the improved [[Security]] features (August 2015)
* This feature is not proof against malicious access. See [[Security]] for details.

This optional subtree in the [[#Security|/Experiment/Security subtree]] is created when the {{Odbedit cmd|cmd=passwd}} is issued. When created, this subtree is empty.
Optionally, it may contain user-defined names of clients allowed to have free access (i.e. without password) to the current experiment. See [[Security #Allowed programs]].

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

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

;Notes
* This key pre-dates (and has been superceded by) the improved [[Security]] features (August 2015)
* This feature is not proof against malicious access. See [[Security]] for details.

If [[Security#Restrict user access|restriction on user web access]] has been set up, this key in the [[#Security|/Experiment/Security subtree]]
will contain an encrypted password for Web server access. This key is created by using the {{Odbedit cmd|cmd=webpasswd}}.

If this key is present, the user will be requested to provide the "Web Password" when accessing the requested experiment in "Write Access" mode. The "Read Only Access" mode is still available (without a password) to all users.

<br>
--------
<br>
</div> 

<div style="background-color:silver">
== <span style="font-size:120%;">The following keys are OBSOLETE:</span> ==

=== <span style="color: purple;">''Mongoose listening_port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "8080r,8443s"
</div>
<br>
:This key in the [[#top|/Experiment tree]] existed for a short time in midas versions May-August 2015.
: It has been '''replaced by the ODB keys [[#midas http port|midas http port]] and [[#midas https port|midas https port]].'''
<br>
<span style="font-size:80%">
This key in the [[#top|/Experiment tree]] was created when [[mhttpd]] was run for the first time. It contained the listening ports for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]). The ports are the HTTP port (default 8080) which is to be redirected to the secure HTTPS port (default 8443).
If ports were supplied with the "--mg" option when starting {{Utility|name=mhttpd}}, their values will overwrite the default values stored in this key. See [[mhttpd]] for details.
</span>
<br>
--------
<br>

=== <span style="color: purple;">''Mongoose access_control_list''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' ""
</div>
<br>
:This key in the [[#top|/Experiment tree]] existed for a short time in midas versions May-August 2015.
:'''Use the [[#mhttpd hosts subtree|mhttpd hosts/Allowed hosts]] access control list or the [[mhttpd]] "-a hostname" parameter to restrict access.'''
<br>
<span style="font-size:80%">
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the access control list (ACL) for the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server. By default, this key is empty and there is no access control. The format of the ACL is described under access_control_list at [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/Options.md?at=develop Mongoose Configuration Options].
</span>
<br>
--------
<br>

</div> 
[[Category:ODB Tree]] [[Category:Experiment]] [[Category:Security]]

/Lazy ODB tree

2016-11-25T20:18:29Z

Suz:

{{Pagelinks}}

= Links =
<div style="column-count:4;-moz-column-count:4;-webkit-column-count:4">
* [[Data Logger]]
* [[Lazylogger]]
</div>

== Creating the /Lazy tree ==
This tree is created with default parameters on the first activation of the <span style="color:darkcyan;">''lazylogger''</span> utility . This task connects to a defined channel (e.g. Tape, Disk) when started. Multiple instances of the program can run concurrently, connecting to a different channel (see [[lazylogger]]).

The following example shows a <span style="color:purple; font-style:italic">/Lazy</span> tree with a <channel-name> of "Disk". A sub-tree <span style="color:purple; font-style:italic">/Lazy/Disk</span> has been created, containing sub-trees "Settings" and "Statistics". A third sub-tree "List" will be created after the first successful operation of the channel. The contents of these sub-trees is discussed below (see
[[#Explanation of the Keys in the ODB /Lazy/<channel_name>/Settings subtree|Settings]]
[[#The ODB /Lazy/<channel_name>/Statistics subtree|Statistics]] and
[[#The ODB /Lazy/<channel_name>/List subtree|List]] subtrees.)

[local:pol:S]/>ls /lazy/disk
Settings
Statistics
List

== The ODB /Lazy/<channel_name>/Settings subtree ==
=== Example ===
The following example shows a typical <span style="color:purple; font-style:italic">/Lazy</span> ODB tree obtained using the [[odbedit]] "ls" command. See keys in the ODB /Lazy tree for more information on each key.

Settings DIR
Maintain free space(%) INT 1 4 3m 0 RWD 0
Stay behind INT 1 4 3m 0 RWD -3
Alarm Class STRING 1 32 3m 0 RWD
Running condition STRING 1 128 3m 0 RWD ALWAYS
Data dir STRING 1 256 3m 0 RWD /home/midas/online
Data format STRING 1 8 3m 0 RWD MIDAS
Filename format STRING 1 128 3m 0 RWD run%05d.mid
Backup type STRING 1 8 3m 0 RWD Tape
Execute after rewind STRING 1 64 3m 0 RWD
Path STRING 1 128 3m 0 RWD
Capacity (Bytes) FLOAT 1 4 3m 0 RWD 5e+09
List label STRING 1 128 3m 0 RWD
Execute before writing file STRING 1 64 11h 0 RWD lazy_prewrite.csh
Execute after writing file STRING 1 64 11h 0 RWD rundb_addrun.pl
Modulo.Position STRING 1 8 11h 0 RWD 2.1
Tape Data Append BOOL 1 4 11h 0 RWD y

=== Explanation of the Keys in the ODB /Lazy/<channel_name>/Settings subtree ===

An example of the subtree is shown above.

==== <span style="color: purple;">''Maintain free space(%)''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>

As the data Logger (<span style="color:darkcyan;">''mlogger''</span>) runs independently from the <span style="color:darkcyan;">''Lazylogger''</span>, the data logging device (e.g. disk) contains all the recorded data files. Under this condition, Lazylogger can be instructed to "purge" the disk after successful backup of the data onto a "slow device" (e.g. tape).

This parameter <span style="color:purple; font-style:italic">Maintain free space(%)</span> in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree controls the percentage of disk space required to be maintained as free (for "none" set to 0).

* The conditions that must ALL be satisfied before removing a data file are defined as:
#The data file corresponding to the given run number following the format declared under [[#Filename format#Filename format]] IS PRESENT on the Settings/Data Dir path.
#The given run number MUST appear anywhere under the [[#The ODB /Lazy/<channel_name>/List subtree|List]] directory of ALL the Lazy channels having the same
[[#Filename format#Filename format]] as this channel.
#The given run number MUST appear anywhere under the [[#The ODB /Lazy/<channel_name>/List subtree|List]] directory of that channel

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree defines how many consecutive data files should be kept between the current run and the last lazylogger run.

; Example with "Stay behind = -3"
: Current acquisition run number 253 -> run00253.mid is being logged by mlogger.
: Files available on the disk corresponding to runs #248, #249, #250, #251, #252.
: Lazylogger will start backing up run #250 as soon as the new run 254 starts.
: "Stay behind = -3" corresponds to 3 files untouched on the disk (#251, #252, #253).

; If the '''sign''' (+/-) of the "Stay behind" parameter is
: negative: the lazylogger will always scan the entire disk at the "Data Dir" path, from the oldest to the most recent file present for backup.
: positive: lazylogger will backup starting from -x behind the current acquisition run number. Run order will be ignored.

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree defines
specify the [[Alarm class]] to be used in case of an alarm being triggered.

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree
specifies the type of condition for which the lazylogger should be actived. By default the lazylogger is ALWAYS running.

;The choices are
: ALWAYS, NEVER, WHILE_NO_ACQ_RUNNING,
: or a condition based on a single field of the ODB key<=>value

'''Example''' : In the case of high data rate acquisition it could be necessary to activate the lazylogger only

* when the run is either paused or stopped (i.e. WHILE_NO_ACQ_RUNNING)
[[odbedit]] > set "Running condition" WHILE_ACQ_NOT_RUNNING
* or when some external condition is satisfied such as "low beam intensity".
odbedit> set "Running condition" "/alias/max_rate < 200"

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree
specifies the data directory path of the data logging device (e.g. disk). If this key is present, the contents is taken as the path, otherwise the current directory is used (i.e. the path where the lazylogger client was started).

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree
specifies the data format of the data files. See [[Keys in the ODB /Logger/Channels subtree#/Logger/Channels/0/Settings/Format|Format]].

==== <span style="color: purple;">''Filename format''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "run%05d.mid"
</div>

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree
specifies the filename format of the data files on the data logging device (i.e. disk). This should be the same filename format as used by the data logger to save the files
(see [[Keys in the ODB /Logger/Channels subtree#/Logger/Channels/0/Settings/Filename | Filename]]).

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree specifies the type of the "backup device" to be used for the lazylog backup.
It can be "Disk","Tape", "Script" or "Ftp".

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree specifies
an optional script to run after completion of a lazylogger backup set (see below [[#Capacity (Bytes)|Capacity]]).

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree specifies
the [[#Backup type|backup device]] path.

There are three possible types of Path:

* For Tape : e.g. /dev/nst0- (UNIX like).
* For Disk : e.g. /data1/myexpt
* For Script: the path to the script file to run. An example file for copying to dcache is here [[lazy_dcache.perl]].
* For Ftp : host,port,user,password,directory

==== <span style="color: purple;">''Capacity (Bytes)''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' FLOAT
* '''Default:''' 5e9
</div>

This parameter only matters for TAPE backup type. This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree specifies
the maximum [[#Backup type|backup device]] capacity in bytes. When this capacity is reached,the lazylogger will close the backup device and clear the [[#List label|List label]] field to prevent further backup. It will also rewind the stream device if possible.

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree specifies
a label for a set of backed up files to the [[#Backup type|backup device]]. This label is used internally by the lazylogger for creating a new array composed of the backed up runs under the [[#The ODB /Lazy/<channel_name>/List subtree|List]] subdirectory, until the [[#Capacity (Bytes)|Capacity]] value has been reached. Once the backup set is complete, lazylogger will clear the "List label" field and therefore prevent any further backup until a non-empty "List label" is re-entered. However, the list label will remain under the
[[#The ODB /Lazy/<channel_name>/List subtree|List]]key to display all run being backed up until the corresponding files have been removed from the disk.

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree permits a script to be run before the beginning of
the lazy job. The arguments passed to the script are: input file name , output file name, current block number.

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

This parameter in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree permits
a script to be run after the completion of the lazy job. The arguments passed to the scripts are: list label, current job number, source path, file name, file size in MB, current block number.

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

This field in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree
is for multiple instances of the lazylogger where each instance works on a sub-set of run number. By specifying the Modulo.Position you're telling the current lazy instance how many instances are simultaneously running (3.) and the position of which this instance is assigned to (.1) As an example for 3 lazyloggers running simultaneously the field assignment should be :

Channel Field Run#
Lazy_1 3.0 21, 24, 27, ...
Lazy_2 3.1 22, 25, 28, ...
Lazy_3 3.2 23, 26, 29, ...

In the [[#Example of the ODB /Lazy/<channel_name>/Settings subtree|example above]], the Modulo.Position is set to 2.1 , indicating this is instance 1, and two lazyloggers are running.

==== <span style="color: purple;">''Tape Data Append''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "y"
</div>

If this key in the ODB <span style="color:purple; font-style:italic">/Lazy/<channel_name>/Settings</span> subtree
is set to "y", the spooling of the Tape device to the End_of_Device (EOD) before starting the lazy job is enabled. This command is valid only for [[#Backup type|Backup type]] Tape. If this flag is not enabled the lazy job starts at the current tape position.

== The ODB /Lazy/<channel_name>/Statistics subtree ==

The Statistics subtree contains general information about the status of the current lazylogger channel.

An example of the Statistics subtree for a lazylogger channel is shown below:

=== Example ===
[local:pol:S]/>ls /lazy/disk/Statistics/
Backup file 000321.mid
File size (Bytes) 0
KBytes copied 0
Total Bytes copied 0
Copy progress (%) 0
Copy Rate (Bytes per s) 0
Backup status (%) 0
Number of Files 173
Current Lazy run 321

== The ODB /Lazy/<channel_name>/List subtree ==

The List subtree will contain arrays of run number associated with the array name backup-set label (see [[#List label|List label]]) . Any run number appearing in any of the arrays is considered to have been backed up.

=== Example ===
An example of the List subtree for a lazylogger channel is shown below. In this case, the list label was set to "archive".

[local:pol:S]/>ls /lazy/disk/List
archive
230
231
232
233
234
235
236
237

[[Category:ODB Tree]]

/Runinfo ODB tree

2016-11-25T20:17:09Z

Suz:

{{Pagelinks}}

== Creating the /Runinfo tree ==
The <span style="color: purple;">''/Runinfo''</span> tree is created automatically when the [[odbedit #Creating the ODB|ODB is first created]].

== Purpose ==
The <span style="color: purple;">''/Runinfo''</span> ODB tree contains system information
about the state of the current run. Several time fields are available for run time statistics.
This information is displayed on the {{Utility|name=mhttpd}} [[Status Page|Status page]] or can be
viewed with [[odbedit]] as shown [[#Example |below]].

== Example ==
> odb -e expt -h host
[host:expt:Running]/>ls -r -l /runinfo
Key name Type #Val Size Last Opn Mode Value
------------------------------------------------------------------------
Runinfo DIR
State INT 1 4 2h 0 RWD 3
Online Mode INT 1 4 2h 0 RWD 1
Run number INT 1 4 2h 0 RWD 8521
Transition in progress INT 1 4 2h 0 RWD 0
Requested transition INT 1 4 2h 0 RWD 0
Start time STRING 1 32 2h 0 RWD Thu Mar 23 10:03:44 2000
Start time binary DWORD 1 4 2h 0 RWD 953834624
Stop time STRING 1 32 2h 0 RWD Thu Mar 23 10:03:33 2000
Stop time binary DWORD 1 4 2h 0 RWD 0

== Keys in the /Runinfo tree ==
The keys in the ODB <span style="color: purple;">''/Runinfo''</span> tree are described in the following sections.

=== <span style="color: purple;">''State''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 1
</div>
This key in the [[#top|/Runinfo tree]]
specifies the state of the current run (see [[Run States and Transitions #MIDAS State and Transition Codes|MIDAS run states]]) . The possible states are
* 1: STOPPED ( STATE_STOPPED )
* 2: PAUSED ( STATE_PAUSED )
* 3: RUNNING ( STATE_RUNNING )

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

=== <span style="color: purple;">''Online Mode''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 1
</div>
This key in the [[#top|/Runinfo tree]]
specifies the expected acquisition mode. This parameter allows the user to detect if the data are coming from a "real-time" hardware source (the default) or from a data save-set. Note that for analysis replay using "analyzer", this flag will be switched off.

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

=== <span style="color: purple;">''Run number''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#top|/Runinfo tree]]
specifies the current run number. This number is automatically incremented by a successful run start procedure.

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

=== <span style="color: purple;">''Transition in progress''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#top|/Runinfo tree]]
specifies the current internal state of the system. This parameter is used for multiple source of "run start" synchronization. Sometimes when run start or stop fails, <span style="color: purple;">''Transition in progress''</span> is left set to 1, and must be manually set to 0 by the user (e.g. with [[odbedit]]) before the run start/stop command can be retried.
> odb set "/runinfo/transition in progress" 0

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

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

This key in the [[#top|/Runinfo tree]] will be set if run start is aborted. The run start may be aborted if
the saved data file already exists, or on alarm (see [[/Experiment ODB tree#Prevent start on alarms|prevent start on alarm]]) , or if a
[[/Experiment ODB tree#Prevent start on required progs| required program]] is not running.
<br>
--------
<br>

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

This key in the [[#top|/Runinfo tree]]
specifies whether a transition has been requested. It will be set if a [[Run States and Transitions #Deferred Transitions|deferred transition]] is in progress.
<br>
--------
<br>

=== <span style="color: purple;">''Start time''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "Tue Sep 09 15:04:42 1997"
</div>
This key in the [[#top|/Runinfo tree]]
specifies in an ASCII format the time at which the last run has been started.

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

=== <span style="color: purple;">''Start time binary''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 0
</div>
This key in the [[#top|/Runinfo tree]]
specifies in a binary format the time at which the last run has been started. This field is useful for time interval computation.
<br>
--------
<br>

=== <span style="color: purple;">''Stop time''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "Tue Sep 09 15:04:42 1997"
</div>
This key in the [[#top|/Runinfo tree]]
specifies in an ASCII format the time at which the last run was stopped.
<br>
--------
<br>

=== <span style="color: purple;">''Stop time binary''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 0
</div>
This key in the [[#top|/Runinfo tree]]
specifies in a binary format the time at which the last run has been stopped. This field is useful for time interval computation.

[[Category:ODB Tree]]

/System ODB tree

2016-11-25T20:13:54Z

Suz:

{{Pagelinks}}

== Creating the /System tree ==
The <span style="color: purple;">''/System''</span> ODB tree is created automatically when the [[odbedit #Creating the ODB|ODB is first created]].

== Purpose ==
The <span style="color: purple;">''/System''</span> ODB tree contains information
specific to each "MIDAS client" currently connected to the experiment. The sequence number appears in the ODB under the <span style="color: purple;">''/System/Clients''</span> subtrees.

== Example ==

The following example shows a typical <span style="color: purple;">''/System''</span> ODB tree obtained using the
[[odbedit]] ls command.

[local:midas:S]/System>ls -lr
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
System DIR
Clients DIR
11781 DIR
Name STRING 1 32 1h 0 R ODBEdit
Host STRING 1 256 1h 0 R dasdevpc2.triumf.ca
Hardware type INT 1 4 1h 0 R 44
Server Port INT 1 4 1h 0 R 55904
Tmp DIR
Client Notify INT 1 4 1h 0 RWD 0
Prompt STRING 1 256 10h 0 RWD [%h:%e:%s]%p>

== Keys in <span style="color: purple;">''/System''</span> tree==

The keys in the ODB <span style="color: purple;">''/System tree''</span>
are described in the following sections.

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

This subtree in the [[#top|/System ODB tree]] is created and used by the system.
<br>
--------
<br>

=== <span style="color: purple;">''Client Notify''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#top|/System ODB tree]] is used by the system to inform other clients after deleting a client from the system.

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

=== <span style="color: purple;">''Prompt''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "[%h:%e:%s]%p>"
</div>

This key in the [[#top|/System ODB tree]] controls the format of the prompt of the [[odbedit]] utility. The default prompt is
shown below

odbedit
[local:midas:S]/>

The meanings of the prompt symbols are
%h Host name
%e Experiment name
%s Run state symbol (U,S,P,R i.e. unknown, stopped, paused, running)
%p Current ODB path
%t Current time

==== Changing the odbedit prompt ====

To set the [[odbedit]] prompt to show the long-form of the run state :

[local:midas:S]/System>set Prompt "[%h:%e:%S]%p>"
[local:midas:Stopped]/System>

To set the prompt to the word "yes" :

[local:midas:Stopped]/System>set Prompt yes>
yes>

To set the prompt to name the fields (i.e. Host, Expt, State, Path):

yes>set Prompt [Host:%h-Expt:%e:State:%s]Path:%p>
[Host:local-Expt:midas-State:S]Path:/System>

To set the prompt to the current time:

[Host:local-Expt:midas-State:S]Path:/System>set Prompt "%t>"
13:29:08>

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

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

This subtree is in the [[#top|/System ODB tree]].
Each client is listed in this subtree under a <client-number> subtree.
The <span style="color: purple;">''/System/Clients''</span> subtree reflects the system at a given time.

==== Example ====
The following example is of the <span style="color: purple;">''/System/Clients''</span> subtree.
More information has been added in <span style="color:green;"> green</span>.

[local:midas:S]Clients>ls -lr
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Clients DIR
1832 DIR <span style="color:green;"> <------------ Frontend 1</span>
Name STRING 1 32 21h 0 R ebfe01
Host STRING 1 256 21h 0 R pierre2
Hardware type INT 1 4 21h 0 R 42
Server Port INT 1 4 21h 0 R 2582
Transition START INT 1 4 21h 0 R 500
Transition STOP INT 1 4 21h 0 R 500
Transition PAUSE INT 1 4 21h 0 R 500
Transition RESUME INT 1 4 21h 0 R 500
RPC DIR
17000 BOOL 1 4 21h 0 R y
3872 DIR <span style="color:green;"> <------------ Frontend 2 </span>
Name STRING 1 32 21h 0 R ebfe02
Host STRING 1 256 21h 0 R pierre2
Hardware type INT 1 4 21h 0 R 42
Server Port INT 1 4 21h 0 R 2585
Transition START INT 1 4 21h 0 R 500
Transition STOP INT 1 4 21h 0 R 500
Transition PAUSE INT 1 4 21h 0 R 500
Transition RESUME INT 1 4 21h 0 R 500
RPC DIR
17000 BOOL 1 4 21h 0 R y
2220 DIR <span style="color:green;"> <------------ ODBedit doesn't need transition</span>
Name STRING 1 32 42s 0 R ODBEdit
Host STRING 1 256 42s 0 R pierre2
Hardware type INT 1 4 42s 0 R 42
Server Port INT 1 4 42s 0 R 3429
568 DIR <span style="color:green;"> <------------ Event Builder</span>
Name STRING 1 32 26s 0 R Ebuilder
Host STRING 1 256 26s 0 R pierre2
Hardware type INT 1 4 26s 0 R 42
Server Port INT 1 4 26s 0 R 3432
Transition START INT 1 4 26s 0 R 300
Transition STOP INT 1 4 26s 0 R 700
2848 DIR <span style="color:green;"> <------------ Logger</span>
Name STRING 1 32 5s 0 R Logger
Host STRING 1 256 5s 0 R pierre2
Hardware type INT 1 4 5s 0 R 42
Server Port INT 1 4 5s 0 R 3436
Transition START INT 1 4 5s 0 R 200
Transition STOP INT 1 4 5s 0 R 800
Transition PAUSE INT 1 4 5s 0 R 500
Transition RESUME INT 1 4 5s 0 R 500
RPC DIR
14000 BOOL 1 4 5s 0 R y

=== Keys in the <span style="color: purple;">''<client-number> subtree''</span> ===
This subtree is found in the [[#Clients subtree|Clients subtree]]. Each client that has run on the experiment is
listed in a <span style="color: purple;"><client-number></span> subtree.

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

==== <span style="color: purple;">''Name''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This key in the [[#<client-number> subtree|<client-number> subtree]] contains the client name.

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

==== <span style="color: purple;">''Host''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This key in the [[#<client-number> subtree|<client-number> subtree]] contains the
[[Common Parameters to MIDAS Utilities #Midas host |Midas host name]] on which this client is running.

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

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

This key in the [[#<client-number> subtree|<client-number> subtree]] is used by the system to contain a code that describes the hardware architecture of the host.
<br>
--------
<br>

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

This key in the [[#<client-number> subtree|<client-number> subtree]] is used by the system to contain the client's server port.
<br>
--------
<br>

==== <span style="color: purple;">''Transition START''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 500 (depends on client)
</div>
This key in the [[#<client-number> subtree|<client-number> subtree]] is used to contain the
[[Run States and Transitions#Default Transition Sequence Numbers |Client sequence number]] for [[Run States and Transitions |Start Transition]].

If a permanent change of a client sequence number is required, the MIDAS system call
''cm_set_transition_sequence()'' can be used.

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

==== <span style="color: purple;">''Transition STOP''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 500 (depends on client)
</div>
This key in the [[#<client-number> subtree|<client-number> subtree]] is used to contain the
[[Run States and Transitions#Default Transition Sequence Numbers |Client sequence number]] for [[Run States and Transitions |Stop Transition]].

If a permanent change of a client sequence number is required, the MIDAS system call
''cm_set_transition_sequence()'' can be used.

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

==== <span style="color: purple;">''Transition PAUSE''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 500 (depends on client)
</div>
This key in the [[#<client-number> subtree|<client-number> subtree]] is used to contain the
[[Run States and Transitions#Default Transition Sequence Numbers |Client sequence number]] for [[Run States and Transitions |Pause Transition]].

If a permanent change of a client sequence number is required, the MIDAS system call
''cm_set_transition_sequence()'' can be used.

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

==== <span style="color: purple;">''Transition RESUME''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 500 (depends on client)
</div>
This key in the [[#<client-number> subtree|<client-number> subtree]] is used to contain the
[[Run States and Transitions#Default Transition Sequence Numbers |Client sequence number]] for [[Run States and Transitions |Resume Transition]].

If a permanent change of a client sequence number is required, the MIDAS system call
''cm_set_transition_sequence()'' can be used.

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

[[Category:ODB Tree]]

/Customscript ODB tree

2016-11-25T20:05:53Z

Suz:

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Online Database]]
* [[mhttpd]]
* [[Custom Page]]
* [[/Script ODB tree]]
* [[ODB]]
</div>

= Purpose =
The optional <span style="color:purple; font-style:italic">/Customscript</span> ODB tree provides the user with a way to execute a script when a button on a [[mhttpd]] [[Custom Page]] is clicked, including the capability of passing parameters from the ODB to the user-written script. This tree is similar to the [[/Script ODB tree]], except instead of producing [[/Script ODB tree#Script-button|script-buttons]] on the [[Status Page]], it produces [[#Customscript-button|customscript-buttons]] on a user-written [[Custom Page]], provided an HTML <input> tag is provided in the Custom Page code for each custom-script button (see [[Custom Page Features#CustomScript Buttons]]).

= Creating the /Customscript tree =
The <span style="color:purple; font-style:italic">/Customscript</span> ODB tree is [[ODB#Creating ODB keys|created]] by the user. This tree is optional, and the names of any keys in this tree are chosen by the user.

= <span style="color:purple; font-style:italic"><customscript-name></span> key or subtree =
<div id="Customscript-button"></div>
Any key created in the <span style="color:purple; font-style:italic">/Customscript</span> tree will appear as a '''''customscript-button''''' <span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;"><customscript-name></span>
(see [[#Purpose|above]]).

Otherwise, the syntax of the <span style="color:purple; font-style:italic">/Customscript</span> tree is exactly the same as that of the <span style="color:purple; font-style:italic">/Script</span> tree. See [[/Script ODB tree#<script-name> key or subtree|Script tree]] for details.

[[Category:ODB Tree]]

/Script ODB tree

2016-11-25T20:05:16Z

Suz:

{{Pagelinks}}

==== Links ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Online Database]]
* [[mhttpd]] status page
* [[#Script-button|script-button]]
* [[ODB]]
* [[/Customscript ODB tree]]
</div>

= Purpose =
The optional <span style="color:purple; font-style:italic">/Script</span> ODB tree provides the user with a way to execute a script when a button on the [[mhttpd]] [[Status Page]] is clicked, including the capability of passing parameters from the ODB to the user-written script.

= Creating the <span style="color:purple; font-style:italic">/Script</span> tree =
The <span style="color:purple; font-style:italic">/Script</span> ODB tree is [[ODB#Creating ODB keys|created]] by the user. This tree is optional, and the names of any keys in this tree are chosen by the user.

= <span style="color:purple; font-style:italic"><script-name></span> key or subtree =
<div id="Script-button"></div>
Any key created in the <span style="color:purple; font-style:italic">/Script</span> tree will appear as a '''''script-button''''' <span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;"><script-name></span>
on the default [[mhttpd]] [[Status Page]].

;Either
: The key can contain the name and path of the script to be executed when the script-button is pressed, e.g.
[local:midas:S]>ls /script
Stop Now odbedit -c 'stop now'
Tune X40 /home/midas/perl/tunes.sh tune X40
: In this case, two script-buttons would appear on the [[Status Page]], i.e. <span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">Stop Now</span> and <span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">Tune X40</span>,
<br>
; or
: the key may be a '''subtree''', in which case the first key in the subtree must contain the name and path of the script to be
: executed. Any further keys in the subtree contain parameters (which may include links) to be passed as arguments to the script, e.g.
[local:midas:S]>ls "/script/change mode"
cmd /home/midas/online/perl/change_mode.pl
include path /home/midas/online/perl
experiment name -> /experiment/name
test_exp
select mode -> /experiment/edit on start/select mode
1h
mode file tag none
:In this case, one script-button would be created, i.e. <span style="color: #444444; background-color: #CCCCCC; font-style:italic; :font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">change mode</span>. Pressing this button would result in the script "change_mode.pl" executed with the following key contents as parameters, equivalent to the command:
/home/pol/online/perl/change_mode.pl /home/pol/online/perl pol 1h mode

[[Category:ODB Tree]]

Mhttpd

2016-09-14T00:41:47Z

Suz:

{{Pagelinks}}
= Links =
{{mhttpdpages3|[[Mhttpd.js|MIDAS Javascript Library]]|[[odbedit]]|[[Security]]}}

= Purpose =
The {{Utility|name=mhttpd}} utility runs the '''MIDAS Web Server''' which allows the user to communicate with an experiment using any web browser. It is used primarily for run control.

= Web security =
As part of the recent upgrade to MIDAS [[Security]], the MIDAS Web Server {{Utility|name=mhttpd}} is now (May 2015) explicitly linked with OpenSSL to provide secure HTTPS connections via the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server. To connect to an experiment using {{Utility|name=mhttpd}}, a username and password are required.
By default, users can connect from anywhere, providing they know the correct username and password. However, web access can be restricted by using the {{Utility|name=mhttpd}} access control list in the ODB at [[/Experiment ODB tree#mhttpd hosts subtree|Allowed hosts]], and/or by using the "-a" argument to {{Utility|name=mhttpd}}.

For '''maximum security''', it is recommended that {{Utility|name=mhttpd}} be run behind an '''Apache HTTPS proxy''' (see [[Security]] for details). In this case, {{Utility|name=mhttpd}} should be built without OpenSSL (see [https://midas.triumf.ca/elog/Midas/1069]), or the Mongoose/OpenSSL web server should be disabled using the arguments supplied to {{Utility|name=mhttpd}} (see [[#To start the webserver using the oldserver|starting the web server using the oldserver]]).

= Arguments =
-h connect to midas server [[mserver]] on given host
-e experiment to connect to
-v display verbose HTTP communication
-D become a daemon
-E only display ELog system
-H only display history plots
-a only allow access for specific host(s), several [-a Hostname] statements might be given (default list
in ODB at [[/Experiment ODB tree#mhttpd hosts subtree|/Experiment/security/mhttpd hosts/allowed hosts]])
--http port - bind to specified HTTP port (default is ODB [[/Experiment ODB tree#midas http port|/Experiment/midas http port]])
--https port - bind to specified HTTPS port (default is ODB [[/Experiment ODB tree#midas https port|/Experiment/midas https port]])
--nomg use the old mhttpd web server
--oldserver [port] - use the old web server on given port
--nooldserver - do not use the old mhttpd web server
-help display usage information

If using an old version (before May 2015), see [[#Insecure (pre-May 2015) versions|old server]] argument list.

= Usage =
== To start the webserver using HTTPS/SSL (Mongoose) ==
* ''"mhttpd"'' or
* ''"mhttpd -v"'' to get debug information, or
* ''"mhttpd -D"'' to run in the background
* ''"mhttpd -a myHost1 -a myHost2"'' to restrict web access
All are equivalent to
* ''"mhttpd --https 8443 --http 8080"''
Starting {{Utility|name=mhttpd}} like this will redirect the default HTTP port of 8080 to the secure HTTPS port 8443. If the ports are not supplied, the default ports will be read from the ODB keys [[/Experiment ODB tree#midas http port|midas http port]] and [[/Experiment ODB tree#midas https port|midas https port]]. If ports are supplied, their values will overwrite the default values stored in the ODB. When {{Utility|name=mhttpd}} is started with a secure port for the first time, a password file (and optionally an SSL certificate) need to be created. See [[#HTTPS/SSL server (Mongoose)|mhttpd HTTPS/SSL server]] for more information.

If {{Utility|name=mhttpd}} is started on IP host machine "myhost" using the default ports, the [[#Features|''Midas status page'']] can be accessed by pointing a web browser to
* https://myhost.mydomain:8443
* or to http://myhost.mydomain:8080 which will be redirected automatically to https://myhost.mydomain:8443

The automatic redirect may be convenient for users who are used to using {{Utility|name=mhttpd}} with a particular HTTP port (e.g. 8080) for their experiment. The redirect can be disabled by setting the ODB key [[/Experiment ODB tree#http redirect to https|http redirect to https]] to "n". This also bypasses the user authentification.

=== Multiple experiments ===
If [[Exptab|multiple experiments]] run on the same host, a web server for each experiment must be started on a different port, e.g.
* ''"mhttpd -e expt1 -D"'' use default ports
* ''"mhttpd -e expt2 --http 8081 --https 8444 -D"'' use supplied ports

== To start the webserver using the oldserver ==
To run a new version of {{Utility|name=mhttpd}} using the old server (i.e. NOT the Mongoose/HTTPS server)
* ''"mhttpd --oldserver 8087"''

This command is useful for running new versions of {{Utility|name=mhttpd}} using an Apache HTTPS proxy (see [[Security]]) - except that it does not support [[Mjsonrpc]], so on recent versions (Sept 2016) the Programs page does not work when run like this.

= Features =
The Midas web server {{Utility|name=mhttpd}} provides a means for run control including monitoring of the run parameters.
Its main feature is a web page invoked through any web browser accessing the Midas experimental URL at a defined port (see [[#Usage|Usage]]).

The contents of this '''Midas status page''' is composed with minimal information relative to the experiment. It contains a collection of buttons and links to other pages to further describe and control the configuration of the experiment.

* Minimal display on the main [[Status Page]]
** Experiment name, time & date, page refresh rate
** Standard Menu Buttons (see below)
** User defined buttons (e.g. alias links, run scripts, custom pages etc.)
** run comments and condition display section (if enabled)
** Equipment list with current running condition, number of event received, event rate, data rate for each equipment.
** Data logging statistics (number of event recorded, data size recorder, compression factor, usage storage level) if enabled.
** Secondary Data logging (data mover) with statistics if enabled.
** Single line of the most recent Midas message.
** Table of the current applications connected to this experiment.

* Standard Menu Buttons
** Transition the state of the run (stopped/running/paused), allows user running condition parameters to be entered at the start state (see [[Edit-on-start Parameters]]).
** Access to the full [[Online Database]] for data display and/or data content modification.
** Display the [[Message Page]], which shows messages generated by the MIDAS [Message System]] as well as the user using cm_msg() functions.
** Access to [[ELOG Page]] switches to the predefined "electronic logbook".
** Access to the [[Alarms Page]] for monitoring the different type of alarms (evaluated, programs, internals, periodic).
** Access to the [[Programs Page]] for a status or interaction with the current running applications part of the Midas experiment.
** Access to the [[History Page]] for graphical data representation of any ODB variables and acquired data.
** Access to the Midas Slow Control Bus devices [[MSCB Page]] connected to this experiment.
** Access to the [[Sequencer Page]] control/monitoring page for [[Sequencer]] i.e. interactive loading/saving/running of a run sequence based on any ODB parameters.
** Access to the [[Chat Page]] for communication between users on the same experiment.
** Access to the [[Help Page]] with short-cut to the Midas Help documentation resource and other information.
* Links
** links to all the listed equipments invoking a dedicated page for the display and possible control of the equipment parameters.
** link to the logger configuration (if present) for the data recording.
** link to the possible secondary logging configuration parameters (if present).

Other features include a JSON interface and Javascript library used for implementing interactive [[Custom Page|custom pages]] for MIDAS experiments.

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

= HTTPS/SSL server (Mongoose) =

The HTTPS/SSL ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]) server is activated by running {{Utility|name=mhttpd}}, and by default it listens on ports 8080 and 8443 (see [[#Usage]]).

{{Utility|name=mhttpd}} with Mongoose requires an '''SSL Certificate''' and a '''password file'''. Ideally, an SSL Certificate issued by a well-known authority trusted by your browser should be used.

The first time {{Utility|name=mhttpd}} is run, if it does not find an SSL Certificate, it will print instructions on how to [[#Create an SSL certificate|create a self-signed SSL Certificate]]. If it finds no existing password file, it will then print instructions on how to [[#Create a password file|create a password file]] (see below for examples).

== Create an SSL certificate ==
If no [[#HTTPS/SSL server (Mongoose)|more secure]] SSL Certificate is available, then create a self-signed certificate by running {{Utility|name=mhttpd}},
and following the printed instructions :
[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
[mhttpd,ERROR] [mhttpd.cxx:17086:mongoose,ERROR] cannot find SSL certificate file "/home/user/online/test/ssl_cert.pem"
[mhttpd,ERROR] [mhttpd.cxx:17087:mongoose,ERROR] please create SSL certificate file: openssl req -new -nodes -newkey rsa:2048
-sha256 -out ssl_cert.csr -keyout ssl_cert.key; openssl x509 -req -days 365 -sha256 -in ssl_cert.csr -signkey ssl_cert.key
-out ssl_cert.pem; cat ssl_cert.key >> ssl_cert.pem
could not start the mongoose web server, see messages and midas.log, bye!

The certificate and key should be placed in one PEM file called ssl_cert.pem located in either MIDAS environment variables [[MIDAS environment variables#MIDAS_DIR|MIDAS_DIR]] or [[MIDAS environment variables#MIDASSYS|MIDASSYS]], and the permissions on the file should be 600 or only owner read/write.
[user@dasdevpc2 test] chmod 600 ssl_cert.pem

== Create a password file ==
Once a valid certificate is generated, when {{Utility|name=mhttpd}} is restarted, you will need to create a password file.

[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
Web server will use SSL certificate file "/home/user/online/test/ssl_cert.pem"
[mhttpd,ERROR] [mhttpd.cxx:17137:mongoose,ERROR] mongoose web server cannot find password file "/home/user/online/test/htpasswd.txt"
[mhttpd,ERROR] [mhttpd.cxx:17138:mongoose,ERROR] please create password file: htdigest -c /home/user/online/test/htpasswd.txt test midas
could not start the mongoose web server, see messages and midas.log, bye!

Each person who is to have access to the experiment should create their own username and password. The first user (e.g. mary) creates the password file e.g. htpasswd.txt
[user@dasdevpc2 test]$ htdigest -c /home/user/online/test/htpasswd.txt test mary
Adding password for mary in realm test.
New password:
Re-type new password:
[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
Web server will use SSL certificate file "/home/user/online/test/ssl_cert.pem"
Web server will use authentication realm "test", password file "./htpasswd.txt"

Access to the [[#Features|''Midas status page'']] can be obtained by pointing a web browser to
https://myhost.mydomain:8443
The first time you connect you will be asked for a username and password.
Now that the password file has been created, subsequent users may create their own username and password in the same file by omitting "-c" argument in htdigest, e.g.
htdigest /home/user/online/test/htpasswd.txt test john

Web access can be restricted to certain hosts if desired (see [[#Web security]]).

Documentation for the version of mongoose included with MIDAS can be found at [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/mongoose/ Mongoose documentation].

For more information see [https://midas.triumf.ca/elog/Midas/1062 Elog note 1062]

<br>
--------
<br>
<div style="background-color:whitesmoke; font-size:90%">

= HTTP only (pre-May 2015) versions =

;Note
* HTTP-only (pre-May2015) versions of mhttpd should only be used '''behind a firewall'''
* If Web [[Security]] is an issue, update to the latest version of mhttpd which uses HTTPS/OpenSSL.

== Arguments (old version) ==

-p port : port number e.g. 8080 (no default). See [[#Usage|usage]].
[-h hostname ] : see [[Common Parameters to MIDAS Utilities]]
[-e experiment] : see [[Common Parameters to MIDAS Utilities]]
[-v] : display verbose HTTP communication
[-D] : starts program as a daemon
[-E] : only display ELog system
[-H] : only display history plots
[-a hostname] : only allow access for specific host(s). Several [-a Hostname] statements might be given
[-help]

== Usage (old version) ==
The command '''mhttpd -p port''' can be used to start the web server (http version). In this case, the TCP/IP port number is '''required''' as an argument in order to listen to the web-based request.
<br>e.g. if mhttpd is started on IP host machine "myhost" on port 8081 as follows
: mhttpd -p 8081 -D
access to the [[#Features|''Midas status page'']] can be obtained by pointing a web browser to
http://myhost.mydomain:8081

;Note
If [[Exptab|multiple experiments]] run on the same host, a web server for each experiment must be started on a different port, e.g.
mhttpd -e expt1 -p 8081 -D
mhttpd -e expt2 -p 8082 -D

== Improve Security with SSL Proxy ==
Improved security for HTTP is gained by using an SSL (https) proxy. See [[Setup MIDAS experiment#mhttpd with HTTP|Setting up an SSL proxy]].
</div>

[[Category:Utilities]]
[[Category:Web server mhttpd]]
[[Category:Run control]]

AJAX

2016-09-09T23:48:00Z

Suz:

{{Pagelinks}}
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[mhttpd]]
* [[mhttpd.js]] Javascript Library
* [[Custom Page]]
</div>

= About =

This page will document the MIDAS AJAX functions accessible through special mhttpd URLs.

These AJAX functions are typically accessed from browser javascript using the MIDAS [[mhttpd.js]] library.

As originally written, code snippets are taken from mhttpd.cxx git commit db4602dc2ed63674413f92cc92f49f183bd14225, 21 Aug 2013.

mhttpd AJAX functions are invoked using the "cmd" parameter with value equal to the name of the AJAX request, for example, to call "jmsg", do:
<pre>
curl "http://localhost:8080?cmd=jmsg&n=5"
</pre>
or where the webserver is using [[mhttpd#HTTPS/SSL server (Mongoose)|HTTPS/SSL (Mongoose)]]
<pre>
$ curl "https://localhost:8443?cmd=jmsg&n=5" -k -u username:passwd --digest
</pre>

= URL percent-encoding =

All parameter names and parameter values (?name=value) are passed through urlDecode.

Encoding used by urlDecode:

* %HH - decoded as char value 0xHH (hex encoding)
* "+" - decoded as " " ("plus" decoded as "space")
* other chars decoded as themselves



This is consistent with URL encoding rules specified by http://tools.ietf.org/html/rfc3986

On the client side ([[mhttpd.js]]), parameter values should be encoded using the JavaScript encodeURIComponent() function.

* BUG: value of parameter "format" is not passed through urlDecode (git commit db4602dc2ed63674413f92cc92f49f183bd14225, 21 Aug 2013), this is consistent with mhttpd.js which does not urlEncode the values. Values of "format0", etc used by ODBMGet() are decoded as expected.

<pre>
urlDecode(pitem);
if (!equal_ustring(pitem, "format"))
urlDecode(p);
setparam(pitem, p);
</pre>

* BUG: confirm that values of "format0", etc are decoded correctly.

= jset =

* JSONP: no
* parameters:
** ?pnam=<code>xxx</code> - cookie_cpwd to match value of ODB /Custon/Pwd/xxx. How is this supposed to work??? How to use it???
<pre>
if (*getparam("pnam")) {
sprintf(ppath, "/Custom/Pwd/%s", getparam("pnam"));
str[0] = 0;
db_get_value(hDB, 0, ppath, str, &size, TID_STRING, TRUE);
if (!equal_ustring(cookie_cpwd, str)) {
show_text_header();
rsprintf("Invalid password!");
return;
}
}
</pre>
** ?odb=<code>ODB path</code>
** ?value=<code>data</code>
** ?type=<code>integer</code> - if ODB path does not exist, it is created, using "type" as the MIDAS TID_xxx data type
** ?len=<code>integer</code> - when ODB path is created, if "len" is not zero, it is made an array of "len" size, with all values set to "value". Except if "type" is TID_STRING, there is no array created, but "len" is used as the ODB string length.

* ODB path encoding for arrays:
** /path/array[i] - write array element [i]
** /path/array - write array element [0]
** /path/array[*] - write as many array elements as there are comma-separated entries in "value". There is no check against existing array length - db_set_data_index() will grow the array as neeed.

* example: TBW

= jget =

* JSONP: no
* parameters:
** ?odb=<code>ODB path</code>
** ?format=<code>sprintf format</code>
** ?odb0=<code>ODB path</code> - activates the multiple jget function
** ?odb<code>N</code>=<code>ODB path</code>
** ?format<code>N</code>=<code>sprintf format</code>
** ?name=<code>integer</code> - non-zero value enables output of key names
* returns:
** single jget returns the text from output_key()
** multiple jget returns the values of all given ODB paths (?odb0=path?format0=format?odb1=path?format1=format?...) separated by the string "$#----#$\n".
** <DB_NO_KEY> for non-existant ODB paths (db_find_key() != DB_SUCCESS)
** <DB_OUT_OF_RANGE> for out of bounds array elements

* ODB array path encoding:
** /path/array[i] -> index=i
** /path/array[*] -> index=-1
** /path/array -> index=0
** then it is passed to output_key()

* encoding by mhttpd.cxx output_key():
** TID_KEY: all subkeys are enumerated and passed to output_key() with "index" set to "-1". Output for all subkeys is concatenated without any separators.
** arrays or simple variables (index=-1): "v0\nv1\n...", if "name" is "1", then: "key[0]: v0\nkey[1]: v1\n..."
** array elements or simple variables (index!=-1): "value\n", if "name" is "1", then: "key[i]: valuei\n"

* BUG: output_key() has no check against negative array indices - passed directly to db_sprintf()/db_sprintff() which also has no array bounds check
* BUG: output_key() has no check for db_get_data() success or failure, no handling of DB_TRUNCATED.
* BUG: some versions of mhttpd do not percent-encode the value of the "format" parameter (see section about URL encoding). Values of "format0", etc are decoded as expected.
* BUG: output_key() ignores it's "format" argument except when encoding arrays. Instead, for encoding of simple variables the value of URL "format" parameter is used unconditionally. This means that the ODBMGet() format[] arguments are only applied to arrays, simple variables use the default format.

* example: TBW

= jcopy =

* JSONP: yes
* parameters:
** &format=<code>format</code> same as "encoding" but subject to an mhttpd URI percent-encoding bug (it is not URI-decoded)
** &encoding=<code>encoding</code> see below
** &callback=<code>string</code> name of the JSONP callback function
** &odb=<code>ODB path</code> single jcopy function
** &odb0=<code>ODB path</code> multiple jcopy function
** &odb<code>N</code>=<code>ODB path</code> ODB paths for multiple copy

* single jcopy returns:
** data encoded according to "encoding" (see below)
** <DB_NO_KEY> is ODB path does not exist (db_find_key() != DB_SUCCESS)

* multiple jcopy returns:
** each ODB path is encoded same for single jcopy, with following separators:
** encoding="odb", separator is string "$#----#$\n", non existant keys return <DB_NO_KEY>"
** encoding="xml", outer XML element is <jcopy>, each ODB path is wrapped in a <data> element, non existant keys are encoded as <DB_NO_KEY/>
** encoding="json", data is encoded as a JSON array - "[ path0, path1, ... ]", non existant keys are encoded as "{ "/error" : %d }" with the error return value of db_find_key().

* jcopy "encoding" (and "format") parameter:
** encoding="odb" - returns data encoded by db_copy()
** encoding="xml" - returns data encoded by db_copy_xml()
** encoding="json" - returns data encoded by db_copy_json(), with these options:
*** "json-p" - data is wrapped by "callback(data);\n"
*** "json-nofollowlinks" - ODB links are encoded as links not as values pointed to by links
*** "json-nokeys" - only values are encoded, ODB keys are omitted, except for "last_written"
*** "json-nolastwritten" - value of ODB key "last_written" is omitted, too.
*** "json-norecurse" - do not recurse into subdirectories (to implement odb edit "ls -l")

* examples:
** single jcopy in ODB format:

<pre>
$ curl "http://localhost:8080?cmd=jcopy&odb=/runinfo&encoding=odb"
[.]
State = INT : 1
Online Mode = INT : 1
Run number = INT : 0
Transition in progress = INT : 0
Start abort = INT : 0
Requested transition = INT : 0
Start time = STRING : [32] Tue Sep 09 15:04:42 1997
Start time binary = DWORD : 0
Stop time = STRING : [32] Tue Sep 09 15:04:42 1997
Stop time binary = DWORD : 0
</pre>
* single jcopy in XML format:
<pre>
$ curl "http://localhost:8080?cmd=jcopy&odb=/runinfo&encoding=xml"
<?xml version="1.0" encoding="ISO-8859-1"?>

<odb root="/Runinfo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://midas.psi.ch/odb.xsd">
<key name="State" type="INT">1</key>
<key name="Online Mode" type="INT">1</key>
<key name="Run number" type="INT">0</key>
<key name="Transition in progress" type="INT">0</key>
<key name="Start abort" type="INT">0</key>
<key name="Requested transition" type="INT">0</key>
<key name="Start time" type="STRING" size="32">Tue Sep 09 15:04:42 1997</key>
<key name="Start time binary" type="DWORD">0</key>
<key name="Stop time" type="STRING" size="32">Tue Sep 09 15:04:42 1997</key>
<key name="Stop time binary" type="DWORD">0</key>
</odb>
</pre>
* single jcopy on JSON format:
<pre>
$ curl "http://localhost:8080?cmd=jcopy&odb=/runinfo&encoding=json"
{
"State/key" : { "type" : 7, "last_written" : 1377182821 },
"State" : 1,
"Online Mode/key" : { "type" : 7, "last_written" : 1377182821 },
"Online Mode" : 1,
"Run number/key" : { "type" : 7, "last_written" : 1377182821 },
"Run number" : 0,
"Transition in progress/key" : { "type" : 7, "last_written" : 1377182821 },
"Transition in progress" : 0,
"Start abort/key" : { "type" : 7, "last_written" : 1377182821 },
"Start abort" : 0,
"Requested transition/key" : { "type" : 7, "last_written" : 1377182821 },
"Requested transition" : 0,
"Start time/key" : { "type" : 12, "item_size" : 32, "last_written" : 1377182821 },
"Start time" : "Tue Sep 09 15:04:42 1997",
"Start time binary/key" : { "type" : 6, "last_written" : 1377182821 },
"Start time binary" : "0x00000000",
"Stop time/key" : { "type" : 12, "item_size" : 32, "last_written" : 1377182821 },
"Stop time" : "Tue Sep 09 15:04:42 1997",
"Stop time binary/key" : { "type" : 6, "last_written" : 1377182821 },
"Stop time binary" : "0x00000000"
}
</pre>
* multiple jcopy in JSON format:
<pre>
$ curl "http://localhost:8080?cmd=jcopy&odb0=/experiment/name&odb1=/runinfo&encoding=json"
[
{
"Name/key" : { "type" : 12, "item_size" : 32, "last_written" : 1377190203 },
"Name" : "javascript1"
}
,
{
"State/key" : { "type" : 7, "last_written" : 1377182821 },
"State" : 1,
"Online Mode/key" : { "type" : 7, "last_written" : 1377182821 },
"Online Mode" : 1,
"Run number/key" : { "type" : 7, "last_written" : 1377182821 },
"Run number" : 0,
"Transition in progress/key" : { "type" : 7, "last_written" : 1377182821 },
"Transition in progress" : 0,
"Start abort/key" : { "type" : 7, "last_written" : 1377182821 },
"Start abort" : 0,
"Requested transition/key" : { "type" : 7, "last_written" : 1377182821 },
"Requested transition" : 0,
"Start time/key" : { "type" : 12, "item_size" : 32, "last_written" : 1377182821 },
"Start time" : "Tue Sep 09 15:04:42 1997",
"Start time binary/key" : { "type" : 6, "last_written" : 1377182821 },
"Start time binary" : "0x00000000",
"Stop time/key" : { "type" : 12, "item_size" : 32, "last_written" : 1377182821 },
"Stop time" : "Tue Sep 09 15:04:42 1997",
"Stop time binary/key" : { "type" : 6, "last_written" : 1377182821 },
"Stop time binary" : "0x00000000"
}
]
</pre>
* multiple jcopy in condensed JSON encoding with JSONP wrapper:
<pre>
$ curl "http://localhost:8080?cmd=jcopy&odb0=/experiment/name&odb1=/runinfo&encoding=json-p-nokeys&callback=mycallback"
mycallback([
{
"Name/last_written" : 1377190203,
"Name" : "javascript1"
}
,
{
"State/last_written" : 1377182821,
"State" : 1,
"Online Mode/last_written" : 1377182821,
"Online Mode" : 1,
"Run number/last_written" : 1377182821,
"Run number" : 0,
"Transition in progress/last_written" : 1377182821,
"Transition in progress" : 0,
"Start abort/last_written" : 1377182821,
"Start abort" : 0,
"Requested transition/last_written" : 1377182821,
"Requested transition" : 0,
"Start time/last_written" : 1377182821,
"Start time" : "Tue Sep 09 15:04:42 1997",
"Start time binary/last_written" : 1377182821,
"Start time binary" : "0x00000000",
"Stop time/last_written" : 1377182821,
"Stop time" : "Tue Sep 09 15:04:42 1997",
"Stop time binary/last_written" : 1377182821,
"Stop time binary" : "0x00000000"
}
]
);
</pre>
** multiple jcopy in values-only JSON encoding with JSONP wrapper:
<pre>
$ curl "http://localhost:8080?cmd=jcopy&odb0=/experiment/name&odb1=/runinfo&encoding=json-p-nokeys-nolastwritten&callback=mycallback"
mycallback([
"javascript1"
,
{
1,
1,
186,
0,
0,
0,
"Thu Jan 16 11:56:53 2014",
"0x52d83985",
"Thu Jan 16 11:56:58 2014",
"0x52d8398a"
}
]
);
</pre>

= jkey =

* JSONP: no
* parameters:
** &odb=<code>ODB path</code>
* returns:
** "<DB_NO_KEY>" if key does not exist
** MIDAS "KEY" structure (see midas.h)
<pre>
db_get_key(hDB, hkey, &key);
rsprintf("%s\n", key.name);
rsprintf("TID_%s\n", rpc_tid_name(key.type));
rsprintf("%d\n", key.num_values);
rsprintf("%d\n", key.item_size);
rsprintf("%d", key.last_written);
</pre>
* example:
<pre>
$ curl "http://localhost:8080?cmd=jkey&odb=/runinfo/run+number"
Run number
TID_INT
1
4
1377182821
</pre>

* BUG: last entry is not "\n" terminated
* BUG: there is no check for db_get_key() error return

= jcreate =

* git branch: feature/ajax
* JSONP: yes
* parameters:
** &encoding=<code>encoding</code> only JSON is implemented
** &callback=<code>string</code> name of the JSONP callback function
** &odb=<code>ODB path</code> single jcreate function
** &odb0=<code>ODB path</code> multiple jcreate function
** &odb<code>N</code>=<code>ODB path</code> ODB paths for multiple copy
** &type=<code>TID_type</code> single jcreate: integer "type" argument to db_create_key()
** &type<code>N</code>=<code>TID_type</code> same for multiple jcreate
** &strlen=<code>int</code> if "type" is TID_STRING, create string of given length. If absent, zero-length string is created
** &strlen<code>N</code>=<code>int</code> same for multiple jcreate
** &arraylen=<code>int</code> is present, use db_set_num_values() to create an array of specified length
** &arraylen<code>N</code>=<code>int</code> same for multiple jcreate

* single jcreate returns:
** integer status value from db_create_key()

* multiple jcreate returns:
** data encoded as JSON, i.e.: [ 1, 312, 1 ]

* examples:

** single jcreate:
<pre>
$ curl "http://localhost:8080?cmd=jcreate&odb=/test/foo&type=7"
1
</pre>

** multiple jcreate with JSON-P encoding:
(note how /nonexistant is created with an invalid "type")
<pre>
$ curl "http://localhost:8080?cmd=jcreate&odb0=/test/foo&type0=7&odb1=/nonexistant&type1=100&odb2=/test/bar&type2=12&encoding=json&callback=aaa"
aaa([ 1, 309, 1 ]);
</pre>

** create an array of integers:
<pre>
curl "http://localhost:8080?cmd=jcreate&odb=/test/foo70&type=7&arraylen=10"
</pre>

** create an array of strings:
<pre>
curl "http://localhost:8080?cmd=jcreate&odb=/test/foo12s5&type=12&strlen=32&arraylen=5"
</pre>

= jresize =

* git branch: feature/ajax
* JSONP: yes
* parameters:
** &encoding=<code>encoding</code> only JSON is implemented
** &callback=<code>string</code> name of the JSONP callback function
** &odb=<code>ODB path</code> single jresize function
** &odb0=<code>ODB path</code> multiple jresize function
** &odb<code>N</code>=<code>ODB path</code> ODB paths for multiple resize
** &strlen=<code>int</code> change string length, including element length of string arrays
** &strlen<code>N</code>=<code>int</code> same for multiple jcreate
** &arraylen=<code>int</code> change array length, including string arrays
** &arraylen<code>N</code>=<code>int</code> same for multiple jcreate

* single jresize returns:
** integer status value from db_find_key(), db_get_key(), db_get_data(), db_set_data(), db_set_num_values()

* multiple jresize returns:
** data encoded as JSON, i.e.: [ 1, 312, 1 ]

* examples: similar to jcreate:

** resize integer array: curl "http://localhost:8080?cmd=jresize&odb=/test/foo70&arraylen=5"
** resize string array: curl "http://localhost:8080?cmd=jresize&odb=/test/foo12s5&arraylen=5"
** resize element size of string array: curl "http://localhost:8080?cmd=jresize&odb=/test/foo12s5&strlen=16"
** and change array size at the same time: curl "http://localhost:8080?cmd=jresize&odb=/test/foo12s5&strlen=30&arraylen=10"

= jrename =

* git branch: feature/ajax
* JSONP: yes
* parameters:
** &encoding=<code>encoding</code> only JSON is implemented
** &callback=<code>string</code> name of the JSONP callback function
** &odb=<code>ODB path</code> single jrename function
** &odb0=<code>ODB path</code> multiple jrename function
** &odb<code>N</code>=<code>ODB path</code> ODB paths for multiple rename
** &name=<code>string</code> single rename: new key "name" argument to db_rename_key()
** &name<code>N</code>=<code>string</code> same for multiple rename

* single jrename returns:
** integer status value from db_rename_key()

* multiple jrename returns:
** data encoded as JSON, i.e.: [ 1, 312, 1 ]

* examples:

** single jrename:
<pre>
$ curl "http://localhost:8080?cmd=jrename&odb=/test/foo&name=foofoo"
1
</pre>

** multiple jrename:
<pre>
$ curl "http://localhost:8080?cmd=jrename&odb0=/test/foo&name0=foofoo&odb1=/test/bar&name1=barbar"
[ 1, 1 ]
</pre>

= jlink =

* git branch: feature/ajax
* JSONP: yes
* parameters:
** &encoding=<code>encoding</code> only JSON is implemented
** &callback=<code>string</code> name of the JSONP callback function
** &odb=<code>ODB path</code> single jlink function
** &odb0=<code>ODB path</code> multiple jlink function
** &odb<code>N</code>=<code>ODB path</code> ODB paths for multiple link
** &dest=<code>string</code> single link: destination argument to db_create_link()
** &dest<code>N</code>=<code>string</code> same for multiple rename

* single jlink returns:
** integer status value from db_create_link()

* multiple jlink returns:
** data encoded as JSON, i.e.: [ 1, 312, 1 ]

* examples:

** single jlink:
<pre>
$ curl "http://localhost:8080?cmd=jlink&odb=/test/link&dest=/test/foo"
1
</pre>

** multiple jlink:
<pre>
$ curl "http://localhost:8080?cmd=jlink&odb0=/test/link0&dest0=/test/foo&odb1=/test/link1&dest1=/test/foo"
[ 1, 1 ]
</pre>

= jreorder =

* git branch: feature/ajax
* JSONP: yes
* parameters:
** &encoding=<code>encoding</code> only JSON is implemented
** &callback=<code>string</code> name of the JSONP callback function
** &odb=<code>ODB path</code> single jreorder function
** &odb0=<code>ODB path</code> multiple jreorder function
** &odb<code>N</code>=<code>ODB path</code> ODB paths for multiple reorder
** &index=<code>int</code> single link: "index" argument to db_reorder_key(). Special index values are: "0" is top, "-1" is bottom.
** &index<code>N</code>=<code>int</code> same for multiple reorder

* single jreorder returns:
** integer status value from db_reorder_key()

* multiple jreorder returns:
** data encoded as JSON, i.e.: [ 1, 312, 1 ]

* examples:

** single jreorder:
<pre>
$ curl "http://localhost:8080?cmd=jreorder&odb=/test/bar&index=0"
1
</pre>

** multiple jreorder:
<pre>
$ curl "http://localhost:8080?cmd=jreorder&odb0=/test/foo&index0=0&odb1=/test/bar&index1=1"
[ 1, 1 ]
</pre>

= jdelete =

* git branch: feature/ajax
* JSONP: yes
* parameters:
** &encoding=<code>encoding</code> only JSON is implemented
** &callback=<code>string</code> name of the JSONP callback function
** &odb=<code>ODB path</code> single jdelete function
** &odb0=<code>ODB path</code> multiple jdelete function
** &odb<code>N</code>=<code>ODB path</code> ODB paths for multiple jdelete

* single jdelete returns:
** integer status value from db_delete_key()

* multiple jdelete returns:
** data encoded as JSON, i.e.: [ 1, 312, 1 ]

* examples:

** single jdelete:
<pre>
$ curl "http://localhost:8080?cmd=jdelete&odb=/test/foo"
1
</pre>

** multiple jdelete with JSON-P encoding:
<pre>
$ curl "http://localhost:8080?cmd=jdelete&odb0=/test/foo&odb1=/nonexistant&odb2=/test/bar&encoding=json&callback=aaa"
aaa([ 1, 312, 1 ]);
</pre>

= jmsg =

* JSONP: no
* parameters:
** &n=<code>number of messages to return</code> return last n messages
** &t=<code>unix timestamp</code> return all messages since time t
::: Note that parameter '''&n=0 must be specified with parameter &t''' (see example 2 below)
* returns: output of midas.c::cm_msg_retrieve()
* example 1: get last 5 messages
:: in this example the webserver is using http
<pre>
$ curl "http://localhost:8080?cmd=jmsg&n=5"
Thu Aug 22 08:05:10 2013 [Logger,TALK] Warning: This is an example alarm
Thu Aug 22 08:06:13 2013 [mhttpd,TALK] Alarm: Run number became too large
Thu Aug 22 08:06:13 2013 [mhttpd,TALK] Warning: This is an example alarm
Thu Aug 22 08:07:15 2013 [fejrpc,TALK] Alarm: Run number became too large
Thu Aug 22 08:07:15 2013 [fejrpc,TALK] Warning: This is an example alarm
</pre>
* example 2: get all messages since a certain date
:: in this example the webserver is using [[mhttpd#HTTPS/SSL server (Mongoose)|HTTPS/SSL (Mongoose)]]
<pre>
$ date -d "Fri Sep 9 16:10:00 PDT 2016" +%s
1473462600
$ curl "https://localhost:8443?cmd=jmsg&n=0&t=1473462600" -k -u username:passwd --digest
1473462926 16:15:26.119 2016/09/09 [ODBEdit,TALK] Alarm: RF has tripped
1473462863 16:14:23.740 2016/09/09 [autorun,TALK] Alarm: RF has tripped
1473462799 16:13:19.109 2016/09/09 [mheader,TALK] Alarm: RF has tripped
1473462739 16:12:19.078 2016/09/09 [feEpics,TALK] Alarm: RF has tripped
1473462673 16:11:13.003 2016/09/09 [feEpics,TALK] Alarm: RF has tripped
1473462607 16:10:07.101 2016/09/09 [ODBEdit,TALK] Alarm: RF has tripped
</pre>

* BUG: last message is not "\n" terminated (violation of the HTTP protocol?)

= jgenmsg =

* JSONP: no
* parameters:
** &msg=<code>message text</code>
* returns: string "Message successfully created\n"
* example:
<pre>
$ curl "http://localhost:8080?cmd=jgenmsg&msg=test+message"
Message successfully created
</pre>

* BUG: "Message successfully created\n" is returned even if the "msg" parameter is missing and regardless of cm_msg() error return code.

= jalm =

* JSONP: no
* parameters: no
* returns:
** text from alarm.c::al_get_alarms()
** is "\n" separated list of alarms
** alarm format is "class: text", where "class" is the alarm class, "text" is the alarm message from ODB /Alarms/alarms/xxx/
* example:
<pre>
$ curl http://localhost:8080?cmd=jalm
Alarm: Run number became too large
Warning: This is an example alarm
</pre>

* BUG: return text is "\n" terminated, array created by javascript request.responseText.split('\n') will have an extra empty element at the end.

[[Category:Ajax]] [[Category:Javascript library]] [[Category:Custom]]

Custom Page Features

2016-09-01T20:38:31Z

Suz:

{{Pagelinks}}
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Mhttpd|mhttpd MIDAS web server]]
* [[ODB Page]]
* [[Custom Page]]
* [[/Custom ODB tree]]
* [[Mhttpd.js|MIDAS Javascript library (mhttpd.js)]]
* [[mjsonrpc|MIDAS JSON RPC library functions (mjsonrpc)]]
* [[odbedit]]
</div>

= Introduction =
This page describes some of the special features provided for use on a user-created [[Custom Page|Custom Web Page]] running under [[mhttpd]].

<br><br>

= The MIDAS Javascript Library =
The MIDAS Javascript Library [[mhttpd.js]] includes routines written in Javascript and AJAX to provide features useful for writers of [[Custom Page]]s, such as access to the ODB. Recently asynchronous [[mjsonrpc|JSON-RPC functions]] using [[mjsonrpc#Javascript client library|Promises]] has been added (January 2016).
;NOTE
:To use functions in this library, it '''must be [[mhttpd.js#include js lib|included in the HTML code]]'''.

Many of the older routines (ODBGet, ODBSet) use '''synchronous''' RPC requests. With synchronous request, a second RPC request must wait until the first request is complete. This can significantly slow down web pages where many calls to ODBGet are made. For this reason, functions were developed that can be synchronous or '''asynchronous''' (e.g. ODBMCopy) that include a callback mechanism. The data from ODBMCopy can be formatted in [[mjsonrpc#JSON general information|JSON]].

Web developers are moving away from synchronous RPC requests, which are now deprecated [https://midas.triumf.ca/elog/Midas/1128]. Some modern browsers return a warning on a synchronous RPC request.

A new group of JSON-RPC functions using [[mjsonrpc#Javascript client library|Promises]] has been added to the MIDAS Javascript Library (January 2016). These are asynchronous only, and they also provide more functionality and have better error handling than the older AJAX calls, which are also inconsistent in how they handle Booleans. They also have much improved handling of reading/writing arrays to the ODB. It is {{Important|text=recommended that all new Custom Pages are written using these JSON-RPC functions}}. They do require an up-to-date browser that supports Promises (see [https://midas.triumf.ca/elog/Midas/1145]). If using an older browser version, the asynchronous AJAX calls (e.g. ODBMCopy) should be used in order to avoid having to rewrite the web page at a later date to remove all synchronous calls.

<br><br>
== Access the ODB using mjson-rpc asynchronous functions ==

Access to the ODB is provided by the [[Mhttpd.js|MIDAS Javascript Library]], which (since January 2016) includes the [[mjsonrpc]] functions. It is [[#The MIDAS Javascript Library|recommended]] that these functions are used for '''new''' pages rather than the older AJAX calls (see below).

To run these functions you need
# to [[mhttpd.js#include js lib|include the Javascript library in the HTML code]]'''
# to use an up-to-date browser that supports Promises (see [https://midas.triumf.ca/elog/Midas/1145]).

Examples showing how to read and write to the ODB can be found at [[mjsonrpc#examples]]. Also included are examples using arrays.

<br><br>
== Access the ODB using asynchronous AJAX calls ==
;NOTE
: It is recommended that asynchronous MIDAS JSON-RPC functions are used for new pages rather than the older AJAX calls (see [[#Access the ODB using mjson-rpc asynchronous functions|above]]).

[[#Example 2 : Asynchronous calls using Javascript and AJAX|Example 2]] uses the asynchronous call ODBMCopy() with callback to read the data. The data are converted into JSON format. In this case, when accessing the JSON data, ''the ODB Keynames must be in the same case as they are in the ODB'', even though the case is ignored by the ODB. If you find this feature annoying, use [[#Access the ODB using mjson-rpc asynchronous functions|mjson-rpc function db_get_values()]] as all keynames are converted to lower case.

<br><br>
== Access the ODB using synchronous AJAX requests ==
;NOTE
: Synchronous requests are now deprecated (see [[#The MIDAS Javascript Library|above]]). New pages should be written [[#Using mjson-rpc asynchronous functions]].

See [[#Example 3 : Synchronous Calls using Javascript and AJAX]].

<br><br>
= Access the ODB with HTML-style <span style="color:seagreen font-style:italic"><odb></span> tags =

;NOTE
: This method pre-dates the [[Mhttpd.js|MIDAS Javascript Library]]. It is recommended that the [[Mhttpd.js|MIDAS Javascript Library]] be used for ODB access.

If Javascript (JS) is not available, the older HTML-style {{HtmlTag|tag=<odb>}} tags are still available and provide limited functionality.

The HTML-style {{HtmlTag|tag=<odb>}} tag has been defined for read/write access to the ODB under HTML. The {{HtmlTag|tag=<odb>}} tags are declared within enclosing HTML {{HtmlTag|tag=<form...>....</form>}} tags.

{| style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"
|+ Access to ODB from HTML
|-
| colspan="1" rowspan="1" style="text-align: center; vertical-align: top; background-color: rgb(204, 204, 255); font-weight: bold;" | HTML ODB tag
| colspan="1" rowspan="1" style="text-align: center; vertical-align: top; background-color: rgb(204, 204, 255); font-weight: bold;" | Meaning

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path">
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: black" |Display ODB field (read only)

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path" edit=1 pwd="CustomPwd">
| Display an Editable ODB field (inline style). Optional password protection with '''pwd''' .

|-
| colspan="1" rowspan="1" style="text-align: left; vertical-align: top; background-color: rgb(255, 255, 255); color: seagreen; font-style:italic" |<odb src="odb path" edit=2 pwd="CustomPwd">
| Display an Editable ODB field (popup style). Optional password protection with '''pwd''' .
|}

;NOTE
: The Optional password protection with '''pwd''' (documented in the [http://ladd00.triumf.ca/~daqweb/doc/midas-old/html/RC_customize_ODB.html#RC_Access_Control| OldMidas Document]) may not be working.
: Use the [[/Experiment ODB tree#Security subtree|Web Password security]] instead.

{{HtmlTag|tag=<odb>}} tags are included in the HTML code e.g.

{{Html|text= Experiment Name: <odb src="/Experiment/Name"> <br> Run Number: <odb src="/runinfo/run number" edit=1>}}

See also [[Custom Page#How to write a Custom Page|HTML Custom Page example]].

<br><br>
= ODB RPC access =
The [[Mhttpd.js|MIDAS Javascript Library]] function ODBRpc() defined for RPC access.

This permits buttons on MIDAS "custom" web pages to invoke RPC calls directly into user frontend programs, for example to turn hardware modules on or off.

<br><br>
= JSON support =
[[mjsonrpc#JSON general information|JSON]] support is provided with the [[Mhttpd.js|MIDAS Javascript Library]].

<br><br>
= Access to the MIDAS Menu buttons =
Access to the standard MIDAS Menu buttons can be provided with HTML {{HtmlTag|tag=<input...>}} tags of the form:


{{Html|text=<input name="cmd" value=''<button-name>'' type="submit" >}}
Valid values are the standard MIDAS Menu buttons, i.e. (Start, Pause, Resume, Stop, ODB, Elog, Alarms, History, Programs etc). The {{HtmlTag|tag=<input...>}} tags must be declared within enclosing HTML {{HtmlTag|tag=<form...>....</form>}} tags (see above).

The following HTML fragment shows the inclusion of three of the standard buttons, giving access to the Main Status, ODB and Messages pages :

{{Html|text= <form name="form1" method="Get" action="/CS/MyExpt&"> <br> <input name="cmd" value="Status" type="submit"> <br> <input name="cmd" value="ODB" type="submit"> <br> <input name="cmd" value="Messages" type="submit"> <br> ... <br> </form> }}

See also [[#Redirect]].

<br><br>
= Redirect =

When buttons are included on a Custom Page, after pressing a button (e.g. the Start or Stop button) it may be desirable to return to the same custom page, rather than returning to the [[Status Page]].

This can be done by including an HTML {{HtmlTag|tag=<input...>}} tag with the attributes ''type'' set to "hidden" and ''name'' set to "redir". This name ("redir") is detected by [[Mhttpd]], causing a redirect to the specified custom link in the ''value'' attribute.

For example, the following redirects the screen back to the custom page link {{Odbpath|path=/Custom/my_custom_page&}} when buttons are pressed:
{{Html|text=<input type=hidden name="redir" value="my_custom_page&">}}

See also [[#Replace Status Page by a Custom page|Redirect when a Custom Page replaces the Status Page]].
<br><br>

= CustomScript Buttons =

[[/Customscript ODB tree#Customscript-button|CustomScript buttons]] can be provided on [[Custom Page|Custom Pages]]. These buttons are equivalent to optional '''script buttons''' on the [[Status Page]], which call a script to perform a particular action when the button is pressed. See [[/Script ODB tree#Script-button|script buttons]] for details. Customscript buttons can be set up through the [[/Customscript ODB tree]].

Any key <span style="color:purple; font-style:italic">/CustomScript/test</span> will appear as a customscript-button
<span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">test</span> on a custom page whose code includes an HTML {{HtmlTag|tag=<input...>}} tag of the form:
{{Html|text=<input type=submit name=customscript value="test">}}
where the action of the button <span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">test</span> will be found in the <span style="color:purple; font-style:italic">/customscript/test</span> subdirectory.

After pressing a customscript-button, the ''type=submit'' in the HTML {{HtmlTag|tag=<input>}} will cause a page reload. This will result in a switch to the [[Status Page]], unless a [[#redirect]] input tag is included to redirect back to the original custom page.

== Customscript button without a page reload ==
To define a customscript button that does '''not''' cause a page reload, set the ''type'' in the HTML {{HtmlTag|tag=<input>}} to "button", i.e.
{{Html|text=<input name="customscript" value="test" type="button" onClick=cs_button(this.value)> }}
and use ''"onClick"'' to call a function to [[#Send an Ajax Request]] instead. The following function sends an asynchronous request, with an optional callback.
{{HtmlTag|tag=<script>}}
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
function cs_button(cmd, callback)<br>
{ // send a request to execute a custom script
: var url;
: var request = XMLHttpRequestGeneric();
:
: url = ODBUrlBase
: if(document.getElementById("redir") != null)
:: url += '?redir='+document.getElementById('redir').value
: url+='&customscript='+ encodeURIComponent(cmd);
: request.open('GET', url, true); // asynchronous request
: request.send(null);
: if(callback!=undefined) {
:: request.onreadystatechange = function() {
::: if (request.readyState == 4) {
:::: if (request.status == 200)
::::: callback();
:::: else
::::: alert('cs_button: Error after sending request to Custom Script "'+cmd+'" :\nHTTP Status: '+request.status)
::: }
:: }
: }
: else {
:: if (request.status != 200)
::: alert('cs_button: Error after sending request to Custom Script "'+cmd+'" :\nHTTP Status: '+request.status)
: }
}
</div>
{{HtmlTag|tag=</script>}}

<br><br>
= Resource files =
It is often desirable to serve resource files (i.e. '''local files''' such as an external stylesheet, javascript files or images'''<sup>***</sup>''') to a custom page. The following sections describe two alternative ways of serving resource files to a custom page:
* [[#Resource files served WITH /custom/path key defined|with /custom/path key defined]]
* [[#Resource files served WITHOUT /custom/path key defined|without /custom/path key defined]]
See also serving resources to a [[#Replace Status Page by a Custom Status page|Custom Status page]].
;NOTE
: '''<sup>***</sup>''' To superimpose labels, bars or fills onto an image, the image cannot be served as a resource file. See [[#Image insertion]].

== Resource files served WITH <span style="color: purple; font-style:italic;">/custom/path</span> key defined ==
When a number of resource files are required, it is convenient to place them in the same directory on the disk, and create a key {{Odbpath|path=/Custom/Path}} to contain this directory.

$ ls /home/midas/online/custom/
custom_functions.js custom_globals.js custom_page.html custom_stylesheet.css test_image.png
With the {{Odbpath|path=/Custom/Path}} key defined, [[/Custom ODB tree#Custom-Link|custom-links]] for individual resource files need not be created in the {{Odbpath|path=/Custom/Path}} tree. The custom-link {{Odbpath|path=custom_page&}} '''is''' required so that the custom page can be accessed from the [[/Custom ODB tree#Custom-Button|custom-button]] {{Button|name=custom_page}} on the Status Page. The key name ends in the special character "&" so that it will open in the same window as the Status page (see [[/Custom ODB tree#Key names|key names]]).
$ odbedit
[local:exp:S] ls /custom
path /home/midas/online/custom/
custom_page& custom_page.html

A {{HtmlTag|tag=<script>}} tag for each resource file to be served (specifying the file name) is then placed in the header of {{File|name=custom_page.html}}
i.e.
{{Html|text=<script type="text/javascript" src="custom_functions.js"></script>}}
{{Html|text=<script type="text/javascript" src="custom_globals.js"></script>}}
<br> and a {{HtmlTag|tag=<link>}} tag for an external stylesheet
{{Html|text=<link type="text/css" rel="stylesheet" href="custom_stylesheet.css" title="Stylesheet">}}
An image tag is placed in the body of {{File|name=custom_page.html}}
{{Html|text=<img src="test_image.png"> }}
[[mhttpd]] then loads the resource file from the directory indicated by the Path key with the correct MIME type (see [[/Custom ODB tree#Keys in the /Custom tree|Custom tree keys]] for supported MIME types).

== Resource files served WITHOUT <span style="color: purple; font-style:italic;">/custom/path</span> key defined ==
Alternatively, resource files can be served to a [[Custom Page]] by creating a key for every resource file in the [[/Custom ODB tree]]. These keys must contain the full path of the file on the disk, and the key {{Odbpath|path=/Custom/Path}} must NOT be defined. The resource files can be in different directories on the disk. By defining the key names with an appropriate file extension, the resource files are served with the appropriate MIME types. The key names end in the special character "!" so that they will not appear on the Status page as custom-links (see [[/Custom ODB tree#Key names|key names]].

Without the {{Odbpath|path=/Custom/Path}} key, the links for the above example in the {{Odbpath|path=/Custom}} tree might look like
$ odbedit
[local:exp:S] ls /custom
custom_page& /home/midas/online/custom/custom_page.html
custom_functions.js! /home/midas/online/resources/custom_functions.js
globals.js! /home/midas/online/resources/custom_functions.js
stylesheet.css! /home/midas/online/stylesheets/custom_stylesheet.css
image.png! /home/midas/images/test_image.png

assuming the resource files are now in the subdirectories indicated.
The {{HtmlTag|tag=<script>}} tag for each resource file to be served (specifying the custom-link) is then placed in the header of {{File|name=custom_page.html}}
i.e.
{{Html|text=<script type="text/javascript" src="custom_functions.js!"></script>}}
{{Html|text=<script type="text/javascript" src="globals.js!"></script>}}
<br> and a {{HtmlTag|tag=<link>}} tag for an external stylesheet
{{Html|text=<link type="text/css" rel="stylesheet" href="stylesheet.css!" title="Stylesheet">}}
An image tag is placed in the body of {{File|name=custom_page.html}}
{{Html|text=<img src="image.png!"> }}

<br><br>
= MIDAS stylesheet =

The MIDAS package provides a condensed stylesheet
: {{Filepath|path=/home/midas/packages/midas/resources/}}{{File|name=mhttpd.css}}
for users who would like their custom pages to have a similar "look and feel" to that of the standard pages.

To include the MIDAS stylesheet, in the HTML header, add
{{HtmlTag|tag=<link rel="stylesheet" type="text/css" href="mhttpd.css">}}
No ''custom link'' needs to be defined.
<br>

The resulting Demo custom page is shown in Figure 1, which can be compared with Figure 2 (no stylesheet).
{| class="wikitable"
|-
! Figure 1 !! Figure 2
|-
| Demo Custom Page using MIDAS stylesheet || Demo Custom Page
|-

| [[File:Mhxcustom03.jpg|thumb|300px]] || [[File:Mhxcustom02.jpg|thumb|200px]]
|}
<br clear=all>

<br><br>
= Alias-Buttons and Hyperlinks =
Any hyperlink can easily be included on a [[Custom Page]] by using the standard HTML anchor {{HtmlTag|tag=<a...>}} tag, e.g.
{{Html|text=<a href="http://ladd00.triumf.ca/~daqweb/doc/midas/html/">Midas Help</a>}}

Links on a custom page equivalent to [[/Alias ODB tree#Alias-Buttons|alias-buttons]] can also be made e.g.
{{Html|text=<button type="button" onclick="document.location.href='/Alias/alias&';">alias</button>}}
See the [[/Alias ODB tree]] for details.

<br><br>
= Page refresh =
The following {{HtmlTag|tag=<meta...>}} tag included in the HTML header code will cause the whole custom page to refresh in 60 seconds :
{{Html|text=<meta http-equiv="Refresh" content="60">}}
It is also possible to [[#Periodic update of parts of a custom page|periodically update parts]] of a custom page.

<br><br>
= Periodic update of parts of a custom page =

The functionality of [[Mhttpd.js|ODBGet]] together with the window.setInterval() function
can be used to update parts of the web page periodically.
For example the Javascript fragment below contains a function which updates the current run number every 10 seconds in the background:

<div style="background-color:floralwhite; color:steelblue; font-style:italic"> 
window.setInterval("Refresh()", 10000);<br>
function Refresh() {<br>
:document.getElementById("run_number").innerHTML = ODBGet('/Runinfo/Run number');<br>
}
</div>
The custom page has to
* [[Mhttpd.js#include js lib|include the MIDAS JS library]] to access ODBGet
* contain an element with id="run_number", such as
{{Html|text=<td id="run_number"></td>}}

<br><br>
= Display last MIDAS message(s) =

The message log (see [[Message System]]) can be accessed from a custom page using a call to the JavaScript library function [[Mhttpd.js|ODBGetMsg]] (provided the [[Mhttpd.js#include js lib|JS library is included]]).

This allows the inclusion of the "Last Midas message" on a custom page, e.g.
{{JS|text=document.write('Last message:'+ODBGetMsg("midas",0,1))}}
More messages may be displayed by increasing the third parameter to ODBGetMsg.
;Note
: Parameters were changed August 2015. See [[Mhttpd.js|ODBGetMsg]] for older versions.
: Coming soon - a [[mjsonrpc]] function

<br><br>
= Generate a message log entry =

A custom page can generate a message to be sent to the MIDAS message log (see [[Message System]]). A call to mjsonrpc_cm_msg() will generate a message if using the [[mjsonrpc]] functions. Otherwise, use the AJAX function [[Mhttpd.js|ODBGenerateMsg]]. To use these functions, the [[Mhttpd.js#include js lib|JS library must be included]] in the html code.

<br><br>
= Checkboxes =
The function [[Mhttpd.js|ODBSet]] (provided the [[Mhttpd.js#include js lib|JS library is included]]) can be used when one clicks on a checkbox for example:
{{Html|text=<input name="box0" type="checkbox" onClick="ODBSet(my_path, this.checked?'1':'0')">}}
If used as above, the state of the checkbox must be initialized when the page is loaded. This can be done with some JavaScript code called on initialization, e.g.
{{JS|text=document.form1.box0.checked= ODBGet(my_path)); // initialize to the correct value}}

<br><br>
= Replace Status Page by a Custom page =

Click to enlarge thumbnail
[[File:Mhcustom_status.jpg|thumbnail|left|Figure 3: ODB /Custom/Status custom-link to a custom status page]]
<div style="clear: both"></div> 

If a custom-link with the [[/Custom ODB tree#Key names|reserved key name]] '''Status''' (not "Status&" or "Status!") is created in the [[/Custom ODB tree]] (as shown in Figure 3), then that custom page will '''replace the default Status Page'''.

Clicking on the {{Button|name=Status}} button on any of the sub-pages (e.g. [[ODB Page]], [[Programs Page]] etc.) will now return to the Custom Status Page. If there are buttons on the Custom Status page, you '''must''' include a [[#Redirect]] statement of the form
{{Html|text=<input type=hidden name="redir" value="../">}}
or you will see the message
Invalid custom page:NULL path

If the Custom Status page includes [[#Resource files]] served on a regular custom page with a statement such as
{{Html|text=<script type="text/javascript" src="cs_functions!">}}
to serve them in a Custom Status page, the statement would be
{{Html|text=<script type="text/javascript" src="<span style="font-weight:bold">/CS/</span>cs_functions!">}}
In fact, this statement can be used in a regular custom page, as the "/CS/" is ignored in that case.

To return to the default Status Page, delete the <span style="color: purple; font-style:italic;">/Custom/Status</span> key.

<br><br>
= Start, Stop and Check if a program is running =
There are [[mjsonrpc]] functions that implemented all three program management functions - start program,
stop program and "is running?" as JSON-RPC methods.

<br><br>
= Send an Ajax request =
By sending an Ajax request from a custom page, you can make a button perform a specific function.

All functions in midas are controlled through special URLs. So the URL
http://<host:port>/?cmd=Start&value=10
will start run #10.

Although it is easier to use an HTML input statement to [[#Access to the MIDAS Menu buttons]],
to send an Ajax request, you can use the function ''XMLHttpRequestGeneric'' which is in the MIDAS Javascript library [[mhttpd.js]].
Then the HTML code would be

{{Html|text=<input type="button" onclick="start()">}}

and in your JavaScript code add a function ''start()'':

<div style="background-color:floralwhite; color:steelblue; font-style:italic">
function start()
{
: var request = XMLHttpRequestGeneric();

: url = '?cmd=Start&value=10';
: request.open('GET', url, true); // asynchronous request
: request.send(null);
} <br>
</div>
See also [[#Access to the MIDAS Menu buttons]]. Another example with optional callback can be found in [[#Customscript button without a page reload]].

This mechanism can be used for starting a particular program, see for example (see [https://midas.triumf.ca/elog/Midas/1046]). However, this functionality is now provided by [[mjsonrpc]] functions - see [[#Start, Stop and Check if a program is running]].

<br><br>
= Image insertion =
An image can be loaded from the web using an HTML {{HtmlTag|tag=<img...>}}, e.g.
{{Html|text="TRIUMF logo" <img src="https://lixenon.triumf.ca/InternalDocuments/Alice/figures/TRIUMF-logo.jpg/image_preview">}}
or a MIDAS History image can be inserted into a custom page using an HTML {{HtmlTag|tag=<img...>}} tag of the following form:
{{Html|text=blah<img src="http://hostname.domain:port/HS/Meterdis.gif&scale=12h&width=300">}}

If the image file is on the local disk, it can be loaded as a '''resource file'''. The image can be of format .pdf, .jpg, .gif, .png. See loading [[#Resource files]].

If you wish to superimpose features such as '''labels and fills''', the image file cannot be served as a [[#Resource files|resource file]]. Instead, the image file must be in '''gif''' format, and must be included in the {{Odbpath|path=/Custom/images}} subtree (Figure 4). Image insertion into a Custom page will be illustrated using the Demo custom page shown in [[#MIDAS stylesheet|Figure 2]]. All the files required for this demo can be found in the MIDAS package at $MIDASSYS/examples/custom. If you do not wish to create
the keys yourself, proceed to [[#Superimposing Labels, Bars and Fills onto a gif image]].

Make a [[/Custom ODB tree#Custom-Link|custom-link]] to the Demo custom page file ''myexpt.html'' , i.e.
[local:js:S]/>ls /custom
myexpt& /home/test/packages/midas/examples/custom/myexpt.html

To make the image ''myexpt.gif'' visible on the custom page, the path and filename of the image file must be defined in the {{Odbpath|path=/Custom/images}} subtree. To do this,
create the subtrees {{Odbpath|path=/Custom/images/myexpt.gif}} where the subtree name "myexpt.gif" is named for the image file you are going to use. Multiple images can be used, by creating multiple imagefile subtrees.

In the imagefile subtree {{Odbpath|path=myexpt.gif}}, create the STRING key {{Odbpath|path=Background}}, and set it to contain the path and name of the image file. The tree structure should then look similar to Figure 4, minus the labels/bars/fill subtrees which will be added to the ODB later.

The image must also be referenced in the custom HTML file ''myexpt.html'' in the "src" field of an HTML {{HtmlTag|tag=<img...>}} tag, e.g.
{{Html|text=<img '''src="myexpt.gif"'''>}}

Click to enlarge thumbnail
[[File:Mhcustom_images.jpg|thumbnail|left|Figure 4: /Custom/Images ODB Tree]]
<br clear=all>
Once the image is visible, enable [[#HTML mapping]], optionally [[#Display mouse position]] and proceed to [[#Superimposing Labels, Bars and Fills onto a gif image]].

<br><br>
== HTML mapping ==
Note that if additional features such as active clickable areas and labels, bars and fills superimposed on the image are also required, HTML mapping must also be activated with the HTML {{HtmlTag|tag=<map...>}} tag and the "usemap" attribute of the HTML {{HtmlTag|tag=<img>}} tag
{{Html|text= <map '''name="myexpt.map"'''> <br> <img src="myexpt.gif" '''usemap="#myexpt.map"'''> <br>...<br> </map>"}}

<br><br>
== Display mouse position ==
[[File:Cursor.png|thumbnail|left|Figure 5: MEG Gas System Custom Page showing cursor position]]
<div style="clear: both"></div> 

When writing custom pages with large background images and labels and fills placed on that image, it is hard to figure out X and Y coordinates of the labels. This can now be simplified by using the function ''getMouseXY()'' in the development JavaScript built-in library [[develop.js]]. This function supplies the X,Y position of the cursor if an element of ID "'''refimg'''" is present. This JS library '''must be [[develop.js|included in the custom page]]''' in order to use it:

Then, set the "id" attribute of the background HTML {{HtmlTag|tag=<img...>}} tag to "refimg", e.g.

<div style="background-color:floralwhite; color:seagreen; font-style:italic">
: <img '''id="refimg"''' src="ebit_pc.gif" usemap="#Custom1"> 
: <map name="Custom1">
: .....
: </map>
</div>

If the "'''refimg'''" tag is present, the cursor changes into a crosshair, and its absolute and relative locations in respect to the reference image are shown in the status bar (Figure 5).

<br><br>
== Superimposing Labels, Bars and Fills onto a gif image ==
You can enhance your custom page by superimposing multiple features based on ODB variables onto an image (e.g. [[#Display mouse position|Figure 5]]), such as

* labels: "live" ODB values positioned in a particular location of the page
* bars : "bar level" showing graphically ODB values such as levels or rate etc.
* fills : "color level" where colour is used as the level indicator.

Each entry (label/bar/fill) will have an ODB tree associated to it defining the ODB variable path, X/Y position, colour, etc. Each time the page is updated, the latest ODB value/level/rate will be shown based on the ODB parameter to which the label, bar or fill is linked - hence the term "live". The overlay of the requested features is done onto the selected image file.

This powerful new extension brings the [[mhttpd]] capability closer to other experimental web controllers similar to EPICS.

;Note
: Be sure to enable the feature to [[#Display mouse position]] in order to facilitate finding the X,Y positions of the various features.
: [[#HTML mapping]] must be activated for labels/bars/fills to work

A Demo custom page showing labels, bars and fills superimposed on an image is shown in [[#MIDAS stylesheet|Figure 2]].
All the files for this demo can be found in $MIDASSYS/examples/custom/. The file xcustom.odb contains the ODB keys required, including those to insert the image and superimpose the various labels, fills etc. This file can be loaded into the ODB with the {{Odbedit cmd|cmd=load}}.

<br><br>
=== Adding Labels ===

[[File:Mhcustom_label.jpg|thumbnail|left|Figure 6: /Custom/Images/Labels ODB subtree]]

In order to include a readout of ODB values (i.e. labels), on the image, a further ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Labels}} must be created. Creating a subdirectory for a particular label i.e. {{Odbpath|path=<label name>}} in the {{Odbpath|path=Labels}} subtree will, at the next custom web page refresh, cause the complete structure for that label to be created and filled with default values. Once the {{Odbpath|path=<label name>}} subtree is created, the user fills the various keys as desired. See [[/Custom ODB tree#Labels subtree]] for details of the various fields. This procedure is repeated for all the labels required, using a unique {{Odbpath|path=<label name>}} subdirectory for each label. An example of a {{Odbpath|path=<label name>}} subtree is shown in Figure 6.

<div style="clear: both"></div> 

<br><br>
=== Adding Bars ===

[[File:Mhcustom_fill.jpg|thumbnail|left|Figure 7: /Custom/Images/Fills ODB subtree]]

In a similar way, Bars can be superimposed on the image. Create a new ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Bars}}. Create a subdirectory for a particular Bar ({{Odbpath|path=<bar name>}}) in the {{Odbpath|path=Bars}} subdirectory. Refresh the web page and fill the various keys as desired. See [[/Custom ODB tree#Bars subtree]] for details of the various fields. Examples of a <bar-name> subtree is shown in Figure 7.

<div style="clear: both"></div> 

<br><br>
=== Adding Fills ===
[[File:Mhcustom_bar.jpg|thumbnail|left|Figure 8: /Custom/Images/Bars ODB subtree]]

In a similar way, Fills can be superimposed on the image. Create new ODB subdirectory {{Odbpath|path=/Custom/images/<imagefile.gif/Fills}}. Create a subdirectory for a particular Fill ({{Odbpath|path=<fill name>}}) in the {{Odbpath|path=Fills}} subdirectory. Refresh the web page and fill the various keys as desired. See [[/Custom ODB tree#Fills subtree]] for details of the various fields. Examples of a ({{Odbpath|path=<fill name>}} subtree is shown in Figure 8.

<div style="clear: both"></div> 

<br><br>
== Mapping active areas onto the image ==
Provided [[#HTML mapping]] is activated, "clickable" areas can be created on the image.

This can be done now with a new function like this:
{{Html|text= <area shape="rect" coords="40,200,100,300" alt="Main Valve" href="Custom1?cmd=Toggle&odb=/Equipment/Environment/Variables/Output[2]">}}

This defines a clickable map on top of the custom image. The area(s) should match with some area(s) on the image, e.g. the box of a valve. Determining the co-ordinates of this area is simplified by using the Display mouse position feature.

By clicking on this area, the supplied path to the ODB is used (in this case {{Odbpath|path=/Equipment/Environment/Variables/Output[2]}}) and its value is toggled. If the valve value is then used in the image via a [[#Adding Fills|Fill]] statement to change the color of the valve, it can turn green or red depending on its state. This is illustrated in [[#Display mouse position|Figure 5]].

Clicking an active area can also be made to open a new custom page, for example:
{{Html|text=<area shape=rect coords="687,530, 890,648" alt="Pump detail" href = "Pump!" title="Click for Details">}}
{{Html|text=<area shape=rect coords="560,574,775,662" alt="Buffer Tank detail" href = "BufferTank!" title="Click for Details">}}
where ''Pump!'' and ''BufferTank!'' are defined as links to custom pages in the [[/Custom ODB tree]].

<br><br>
== Edit boxes floating on top of a graphic ==

An edit box can be placed on top of a graphic in a particular position by means of an HTML <span style="color:green"><div></span> tag. Using the ODBEdit function from the Midas JS library [[Mhttpd.js]], the custom page code would look like this:

{| style="text-align: left; width: 100%; background-color: floralwhite;" border="0" cellpadding="1" cellspacing="1"
|-
|<pre style="background-color:floralwhite; color:seagreen; font-style:italic">
<div style="position:absolute; top:100px; left:50px;">
<script type="text/javascript"> </pre>
<pre style="background-color:floralwhite; color:steelblue; font-style:italic;">
document.write('Run number: ')
path='/runinfo/run number'
rn = ODBGet(path)
document.write('<a href="#" onclick="ODBEdit(path)" >')
document.write(rn)
document.write('</a>');</pre>
<pre style="background-color:floralwhite; color:seagreen; font-style:italic;">
</script>
</div>
<img src="custom.gif">
</pre>
|}

The same thing could be done with the HTML-style {{HtmlTag|tag=<odb>}} tag :
<pre style="background-color:floralwhite; color:seagreen; font-style:italic">
<div style="position:absolute; top:100px; left:50px;">
Run number: <odb src="/Runinfo/run number" edit=1>
</div>
<img src="custom.gif">
</pre>

<br><br>
= Examples =
For more examples of accessing the ODB with the Javascript library [[mhttpd.js]] look at the example experiment in the MIDAS package $MIDASSYS/examples/javascript1/example.html.

== Example 1 : Asynchronous calls using mjsonrpc functions ==
See [[mjsonrpc#examples]]

== Example 2 : Asynchronous calls using Javascript and AJAX ==

Example 2 shows html code illustrating the use of ODBMCopy(), where innerHTML is used to display the data. On a page with images or a lot of data, innerHTML allows you to update variables without having to reload the whole page. In the example, a timer causes the page to update every 10s (reread the data). Often the ODB data for the whole page can be read by one asynchronous ODBMCopy() call, rather than scattering synchronous ODBGet() calls throughout the page.

Access to the ODB is provided by the [[Mhttpd.js|MIDAS Javascript Library]], included with the line <span style="color:green"><script src='mhttpd.js'></script></span>.

<div style="background-color:floralwhite; color:seagreen; font-style:italic">
<html> <br>
<head> <br>
<title>MyTitle</title> <br>
<script src='mhttpd.js'></script>
<script> </div>
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
var updatePeriod = 10000; // in msec <br>
var updateTimerId = 0; <br>
var counter=0; <br>
function update() { <br>
:clearTimeout(updateTimerId); <br>
: load();
: if (updatePeriod > 0)
: updateTimerId = setTimeout('update()', updatePeriod);
} <br>
function load() { <br>
: document.getElementById('LastUpdated').innerHTML = "Updating..." + new Date;
: var paths = [ "/Runinfo", "/Experiment"];
: var data_odb=ODBMCopy(paths, mcopy_callback, "json")
: counter++;
: document.getElementById('counter').innerHTML = 'Counter: '+ counter
} <br>
function mcopy_callback(data) { <br>
: var obj= JSON.parse(data);
: var runinfo=obj[0];
: document.getElementById('rn').innerHTML = 'Run Number ='+ parseInt(runinfo["Run number"]);
: document.getElementById('state').innerHTML ='Run State= '+ runinfo.State;
: var experiment=obj[1];
: document.getElementById('name').innerHTML='Experiment name = '+ experiment.Name <br>
}<br> </div>
<div style="background-color:floralwhite; color:seagreen; font-style:italic">
</script> <br>
</head> <br>
<body> <br>
<b>Javascript code using ODBMCopy with callback</b> <br>
The data on the page is updated every 10 sec using a timer<br>
<p id="LastUpdated" > Last updated: never</p><br>
<p id="rn"> Run Number : unknown </p><br>
<p id="state"> State : unknown</p><br>
<p id="name"> Experiment name : unknown </p><br>
<p id="counter">Counter: zero </p><br>
<script type="text/javascript"> </div>
<div style="background-color:floralwhite; color:steelblue; font-style:italic">
: if (updatePeriod > 0)
: update(); </div>
<div style="background-color:floralwhite; color:seagreen; font-style:italic">
</script> <br>
</body> </html></div>

<br><br>
== Example 3 : Synchronous Calls using Javascript and AJAX ==
In the following example, JS functions ODBGet and ODBEdit from the [[Mhttpd.js|MIDAS Javascript Library]] are used to access the ODB.
;NOTE
# Synchronous calls are now deprecated (see [[#The MIDAS Javascript Library|above]]).
# The Javascript library '''must be [[mhttpd.js#include js lib|included in the HTML code]]'''.

{{Html|text=<script>}}
{{JS|text=document.write ('Experiment Name: '+ ODBGet("/Experiment/Name")) <br> var alarm_path="/alarms/Alarm system active"; <br> var alarm_active=ODBGet(alarm_path); <br> document.write('<a href="#" onclick="ODBEdit(alarm_path)" >'+alarm_active+'</a>')}}
{{Html|text=</script>}}

[[Category:Custom]]

/Experiment ODB tree

2016-08-26T01:33:27Z

Suz:

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[odbedit]]
*
*
</div>

== Creating the <span style="color: purple;">''/Experiment''</span> tree ==
The <span style="color: purple;">''/Experiment''</span> ODB tree is created automatically when the '''[[odbedit #Creating the ODB|ODB is first created]]'''.

== Purpose ==
The <span style="color: purple;">''/Experiment''</span> ODB tree contains information relevent to the experiment. Other optional keys are added by '''[[mhttpd]]''' or by
the user to customize their experiment.

== Examples ==
When initially created, the <span style="color: purple;">''/Experiment''</span> tree contains the following keys:
[local:midas:S]/>ls -lrt /experiment
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Experiment DIR
Name STRING 1 32 14s 0 RWD midas
Buffer sizes DIR
SYSMSG DWORD 1 4 11h 0 RWD 100000
Security DIR
Enable non-localhost RPC BOOL 1 4 46s 0 RWD n
RPC ports DIR
ODBEdit DWORD 1 4 38m 0 RWD 0
RPC hosts DIR
Allowed hosts STRING 10 256 38m 3 RWD
[0] localhost
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
Disable RPC hosts check BOOL 1 4 46s 0 RWD n

The following example shows the <span style="color: purple;">''/Experiment''</span> tree for a typical experiment:

[local:midas:R]/>ls -lrt /experiment
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Experiment DIR
Name STRING 1 32 7s 0 RWD midas
<span style="color: purple;">Buffer sizes</span> DIR
SYSMSG DWORD 1 4 23h 0 RWD 100000
SYSTEM DWORD 1 4 23h 0 RWD 640000000
BUF0 DWORD 1 4 23h 0 RWD 80000000
BUF1 DWORD 1 4 23h 0 RWD 80000000
....... <span style="color: green;">''other user-defined buffers not shown ''</span>
<span style="color: purple;">Security</span> DIR
Enable non-localhost RPC BOOL 1 4 38m 0 RWD n
<span style="color: purple;">RPC ports</span> DIR
ODBEdit DWORD 1 4 38m 0 RWD 0
Logger DWORD 1 4 35m 0 RWD 0
mhttpd DWORD 1 4 23m 0 RWD 0
<span style="color: purple;">RPC hosts</span> DIR
Allowed hosts STRING 10 256 38m 3 RWD
[0] localhost
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
Disable RPC hosts check BOOL 1 4 38m 0 RWD n
<span style="color: purple;">mhttpd hosts</span> DIR
Allowed hosts STRING 10 256 5h 0 RWD
[0]
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
midas http port INT 1 4 5h 0 RWD 8080
midas https port INT 1 4 5h 0 RWD 8443
http redirect to https BOOL 1 4 5h 0 RWD y
CSS File STRING 1 1024 9h 0 RWD mhttpd.css
JS File STRING 1 1024 9h 0 RWD mhttpd.js
Menu Buttons STRING 1 1000 9h 0 RWD Status, ODB, Messages, ELog, Alarms, Programs, History, Sequencer, Config, Help
Start-Stop Buttons BOOL 1 4 8h 0 RWD y
Pause-Resume Buttons BOOL 1 4 8h 0 RWD n
<span style="color: purple;">Status items</span> DIR
Experiment Name -> /Experiment/Name
MAX_EVENT_SIZE DWORD 1 4 23h 0 RWD 4194304
Midas server port DWORD 1 4 3m 0 RWD 1175
Transition debug flag INT 1 4 23h 0 RWD 0
Transition connect timeout INT 1 4 23h 0 RWD 10000
Transition timeout INT 1 4 23h 0 RWD 120000
<span style="color: purple;">edit on start</span> DIR
experiment number DWORD 1 4 2h 0 RWD 9499
field STRING 1 32 2h 0 RWD 19000.2(0.0)G
comment-> /Experiment/run parameters/comment
STRING 1 80 2h 0 RWD Testing with low beam
Number of channels -> /Run Parameters/number of channels
DWORD 1 4 2h 0 RWD 20
Write Data -> /Logger/Write data
BOOL 1 4 2h 0 RWD n
Number of cycles -> /Equipment/FIFO_acq/frontend/hardware/num cycles
DWORD 1 4 2h 0 RWD 0
<span style="color: purple;">Parameter Comments</span> DIR
field STRING 1 32 >99d 0 RWD <i>Entered in Tesla unit</i>
Num cycles STRING 1 80 >99d 0 RWD <i>Stop run after num cycles is reached. Enter 0 to disable (free running)</i>
<span style="color: purple;">Run Parameters</span> DIR
Comment STRING 1 80 2h 0 RWD Testing with low beam
Run Description STRING 1 256 7h 0 RWD Sequencer Tests
Number of channels DWORD 1 4 2h 0 RWD 20
<span style="color: purple;">Lock when running</span> DIR
Num channels -> /Run Parameters/number of channels
DWORD 1 4 2h 0 RWD 20
<span style="color: purple;">edit on sequence</span> DIR
title STRING 1 128 2h 0 RWD none
experiment number DWORD 1 4 2h 0 RWD 9438
experimenter STRING 1 32 2h 0 RWD gls
sample STRING 1 36 2h 0 RWD NA
run description -> /Experiment/run parameters/run description
STRING 1 256 7h 0 RWD Sequencer Tests
Write Data -> /Logger/Write data
BOOL 1 4 2h 0 RWD n
Number of cycles -> /Equipment/FIFO_acq/frontend/hardware/num cycles
DWORD 1 4 2h 0 RWD 0
Prevent start on alarms BOOL 1 4 22h 0 RWD n
Prevent start on required BOOL 1 4 22h 0 RWD n
<span style="color: purple;">Status items</span> DIR
Experiment Name -> /Experiment/Name
STRING 1 32 7s 0 RWD midas
Start-Stop Buttons BOOL 1 4 5h 0 RWD y
Pause-Resume Buttons BOOL 1 4 5h 0 RWD n

== Keys in <span style="color: purple;">''/Experiment''</span> tree==

The keys in the ODB <span style="color: purple;">''/Experiment tree''</span>
are described in the following sections.

=== <span style="color: purple;">''Name ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This key in the [[#top|/Experiment tree]]
contains the name of the experiment. It is created by the MIDAS system when the ODB is created.

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

=== <span style="color: purple;">''Buffer Sizes ''</span> subtree ===
* '''Type:''' DIR

This key in the [[#top|/Experiment tree]] is a subtree to contain the sizes of the
Midas Buffers for the experiment. Created by the MIDAS system with default values. The sizes can be changed to optimize the memory usage. See '''[[Event Buffer]]''' Size(s) for details. Other user-defined
buffers may be present (e.g. for '''[[event filtering]]''').
<br>
--------
<br>

==== <span style="color: purple;">''SYSMSG ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 100000 Bytes
</div>
This key in the [[#Buffer Sizes|/Experiment/Buffer Sizes subtree]]
contains the size of SYSMSG buffer. This buffer is used for MIDAS messages.
The default value of this key is defined by MESSAGE_BUFFER_SIZE in $MIDASSYS/include/msystem.h .

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

==== <span style="color: purple;">''SYSTEM ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 32MiBytes
</div>
This key in the [[#Buffer Sizes|/Experiment/Buffer Sizes subtree]]
contains the size of SYSTEM buffer. The default value of this key is
DEFAULT_BUFFER_SIZE = 32 MiB (defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h_source.html midas.h]).
The actual SYSTEM buffer size is set by this key. To increase the SYSTEM buffer size (e.g. for very large events), see [[Event Buffer]].
<br>
--------
<br>

=== <span style="color: purple;">''MAX_EVENT_SIZE ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 4MiBytes
</div>
This key in the [[#top|/Experiment tree]]
specifies the maximum event size that can be acquired. The default value of this key is
DEFAULT_MAX_EVENT_SIZE = 4 MiB (defined in [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/html/midas_8h_source.html midas.h]).
The actual maximum event size is set by this key, and can be increased for larger events if needed (see [[Event Buffer]] for more information).

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

=== <span style="color: purple;">''midas http port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 8080
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the listening port for the HTTP server (default 8080). This will be redirected to the secure HTTPS port given by [[#midas https port|midas https port]] if the key [[#http redirect to https|http redirect to https]] is set to "y".

If the http port are supplied with the "--http" option when starting {{Utility|name=mhttpd}}, the port supplied will overwrite the default value stored in this key. See [[mhttpd]] for details.

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''midas https port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 8443
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the listening port (default 8443) for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]).

If the https port is supplied with the "--https" option when starting {{Utility|name=mhttpd}}, the port supplied will overwrite the default value stored in this key. See [[mhttpd]] for details.

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''http redirect to https''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' y
</div>
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. If set to "y", connections to the http port (specified by the key [[#midas http port|midas http port]] will be redirected to hte https port (specified by the key [[#midas https port|midas https port]], i.e. the listening port for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]).

;NOTE
: This [[Security]] feature was added to [[mhttpd]] in August 2015

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

=== <span style="color: purple;">''midas server port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 1175
</div>

This key is created when [[mserver]] is started for the first time. It contains the default value of the port used by [[mserver]]. This is set to MIDAS_TCP_PORT = 1175 ( midas.h). A different port can be used by starting [[mserver]] with the -p argument.

;NOTE
: This key was added in May 2015 (see [[Security]]).

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

=== <span style="color: purple;">''CSS File''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "mhttpd.css"
</div>
This key in the [[#top|/Experiment tree]] contains the name of the [[Custom Page Features#MIDAS stylesheet|MIDAS stylesheet]] file for the use of those writing [[Custom Page|Custom Web Pages]].

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

=== <span style="color: purple;">''JS File''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "mhttpd.js"
</div>
This key in the [[#top|/Experiment tree]] contains the name of the [[mhttpd.js|Javascript library]] file for the use of those writing [[Custom Page|Custom Web Pages]].

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

=== <span style="color: purple;">''Menu Buttons''</span> ===
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* '''Type:''' STRING
* '''Default:''' "Status, ODB, Messages, ELog, Alarms, Programs, History, Sequencer, Chat, Config, Help"
</div>
This key in the [[#top|/Experiment tree]]
is added automatically by '''[[mhttpd]]''' to allow the Menu buttons that appear on the '''[[mhttpd|Main Status Page]]''' to be customized by
removing unnecessary buttons or by changing their order.

The Start/Stop/Pause/Resume buttons are not now included in <span style="color: purple;">''Menu Buttons''</span>.
* To suppress/display the Start/Stop buttons use key [[#Start-Stop Buttons|Start-Stop Buttons]].
* To display/suppress the Pause/Resume buttons, use key [[#Pause-Resume Buttons|Pause-Resume Buttons]].

; Note
:If [[MSCB Page#MIDAS with MSCB support|MSCB support]] is built into MIDAS, the default will also include the MSCB Menu button (see [[MSCB Page]]).

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

=== <span style="color: purple;">''Start-Stop Buttons''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' y
</div>
This key in the [[#top|/Experiment tree]] is added automatically by '''[[mhttpd]]''' to allow the user to suppress the Start or Stop buttons from appearing on the [[Status Page]]. By default, Start/Stop buttons are shown.

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

=== <span style="color: purple;">''Pause-Resume Buttons''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' n
</div>
This key in the [[#top|/Experiment tree]] is added automatically by '''[[mhttpd]]'''.
By default the Pause/Resume menu buttons do not appear on the [[Status Page]]. The user can allow these buttons
to appear during the run by setting this key to "y".

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

=== <span style="color: purple;">''Transition debug flag ''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>
This key in the [[#top|/Experiment tree]] contains a flag that, if set to 1, causes messages reporting transition progress to be output.
<br>
--------
<br>

=== <span style="color: purple;">''Transition connect timeout''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 10000
</div>
This key in the [[#top|/Experiment tree]] contains the
value of timeout for remote rpc connect
<br>
--------
<br>

=== <span style="color: purple;">''Transition timeout''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 120000
</div>
This key in the [[#top|/Experiment tree]] contains the
value of timeout for transition
<br>
--------
<br>

=== <span style="color: purple;">''Prevent start on alarms''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
This key in the [[#top|/Experiment tree]] if set true
will prevent the run from starting if an [[Alarm System|alarm]] is true, i.e.
the run start procedure will fail if an alarm has been [[/Alarms ODB tree#Triggered|Triggered]] for a client, provided a valid [[/Alarms ODB tree#alarms class|alarms class]] has
been entered in the client's [[/Programs ODB tree#Alarm class|Alarm class]] key.

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

=== <span style="color: purple;">''Prevent start on required program''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
This key in the [[#top|/Experiment tree]] if set true ("y")
will prevent the run from starting if one of the '''required''' clients is not running. A client is flagged as "required" by setting the ODB key
[[/Programs ODB tree#Required|Required]] to "y".
<br>
--------
<br>

=== <span style="color: purple;">''Edit on Sequence ''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
This optional subdirectory in the [[#top|/Experiment tree]] may
contain user-defined parameters which will be displayed for editing at the start of each [[Sequencer|Sequence]]. See [[Edit-on-Sequence Parameters]] for details.

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

=== <span style="color: purple;">''Edit on Start ''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>
This optional subdirectory in the [[#top|/Experiment tree]] may
contain user-defined parameters which will be displayed for editing at the beginning of each run. See '''[[Edit-on-start Parameters]]''' for details.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] contains user-defined links to ODB parameters to prevent them being changed when the run is in progress. See '''[[Lock when running]]''' for details.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] may contain user-defined parameter comments that give more information about
the '''[[Edit-on-start Parameters]]'''.

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

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

This optional subdirectory in the [[#top|/Experiment tree]] may contain user-defined parameters or parameter(s)
with reserved names (i.e. [[#Run Description|Run Description]]).

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

==== <span style="color: purple;">''Run Description''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
This ODB key is used by the [[Sequencer]] [[Sequencer#RUNDESCRIPTION|RUNDESCRIPTION]] command to store the
run description.

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

==== <span style="color: purple;">''<parameter name>''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>
The user may define parameters here e.g. for linking as '''[[Edit-on-start Parameters|Edit-on-start]]''' or '''[[Edit-on-Sequence Parameters|Edit-on-Sequence]]''' parameters.

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

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

This key in the [[#top|/Experiment tree]] is a subtree which by default contains a link to the [[#Name|experiment name]]. Any links or keys
created by the user in this optional subdirectory will be displayed on the [[mhttpd]] main status page.
<br>
--------
<br>

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

This optional subtree in the [[#top|/Experiment tree]] is created when the '''[[odbedit]]''' commands <span style="color:saddlebrown; font-style:bold; ">passwd</span> or <span style="color:saddlebrown; font-style:bold; ">webpasswd</span> are issued. It enables a user to set up security features. See '''[[Security]]'''.
<br>
--------
<br>

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

Setting the key to "n" (the default) causes access by unauthorized hosts to be prevented by the system checking the RPC access control list (see [[#RPC hosts subtree|RPC hosts/Allowed hosts]]).

If MIDAS clients have to connect from random hosts (i.e. dynamically assigned random DHCP addresses), one can disable the host name checks by
setting this key to "y". This configuration is insecure and should only be done on a private network behind a firewall. See [https://midas.triumf.ca/elog/Midas/1080 Note 1080].

; NOTE
: This key was added August 2015. Used by [[mserver]] to improve network [[Security]] for the MIDAS experiment.

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

==== <span style="color: purple;">''Enable non-localhost RPC''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>
The default value of this key is "n", denying access by external network connections. If running an experiment that requires external network connections, this key must be set to "y" and the key [[#RPC hosts|RPC hosts]] must be filled. See [https://midas.triumf.ca/elog/Midas/1080 Note 1080].

; NOTE
: This key was added August 2015. Used by [[mserver]] to improve network [[Security]] for the MIDAS experiment.

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

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]'''). This subdirectory contains the names of MIDAS clients and their fixed TCP port numbers. When a client is started for the first time, an entry named for the client will be created in this subtree.
<br>
--------
<br>

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

When a MIDAS client is started, a key will be created named for that client. It will contain the fixed TCP port number that the MIDAS client is using.
Clients started on the local host will have TCP port numbers of 0 (default).

Once a remote [[Frontend Operation|frontend]] is bound to a fixed port, appropriate openings can be made in the firewall, etc. Default port number value
will be 0 meaning "use random port", same as now. See [https://midas.triumf.ca/elog/Midas/1079].

;NOTE
: This feature was added August 2015. It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

<div id="Allowed hosts (rpc hosts)"></div> 
===== <span style="color: purple;">''Allowed hosts''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING array
* '''Default:''' "localhost"
</div>
This key in the [[#RPC hosts subtree|/Experiment/Security/RPC hosts subtree]] is new as of August 2015 and is created by the system (i.e. midas.c).

It is part of the improved security features of MIDAS (See '''[[Security]]''') and is used to maintain a Network Access Control list.
The access control list array is self-growing - it will have at least 10 empty entries at the end at all times.

The default value for {{Odbpath|path=Allowed hosts[0]}} is "localhost", which will reject all external connections, even when permitted by [[#Enable external RPC connections|Enable external RPC connections]]. The user will be required to enter the names of all machines that will run midas clients in this array. See [https://midas.triumf.ca/elog/Midas/1090].

All clients' db_watch() routines watch the access control list and automatically reload it when it is changed, so there is no need to restart clients.

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

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

This subtree in the [[#Security subtree|/Experiment/Security subtree]] is new as of August 2015. It is created by the MIDAS system.
It is part of the improved security features of MIDAS (See '''[[Security]]''').
<br>
--------
<br>

<div id="Allowed hosts (mhttpd hosts)"></div> 
===== <span style="color: purple;">''Allowed hosts''</span> =====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING array
* '''Default:''' "localhost"
</div>
This key in the [[#RPC hosts subtree|/Experiment/Security/mhttpd hosts subtree]] is new as of August 2015 and is created by the system (i.e. midas.c).

It is part of the improved security features of MIDAS (See '''[[Security]]''') and is used to maintain an access control list for [[mhttpd]]. An empty list means free access from everywhere. Access control is also controlled by the [[mhttpd]] "-a" command line arguments. Hosts supplied by the "-a" command line arguments are not added to the access control list by the system.

The access control list is watched by {{Utility|name=mhttpd}}, therefore there is no need to restart it after updating the list.

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

<div style="background-color:whitesmoke">

=== <span style="font-size:120%; font-style:bold">The following keys are OBSOLESCENT - replaced by the [[Security|security features]] added Aug 2015</span> ===
==== <span style="color: purple;">''Password ''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

;Notes
<ol>
<li>This feature pre-dates the improved [[Security]] features (August 2015)</li>
<li> Do not set this key except through the {{Odbedit cmd|cmd=passwd}}. Setting an unencrypted password will lock you out of the ODB unless {{Utility|name=odbedit}} is listed in the [[#Allowed programs subtree|allowed programs subtree]].</li>
<li>This security feature is not proof against malicious access. See [[Security]] for details.</li>
</ol>

This optional key in the [[#Security|/Experiment/Security subtree]]
contains the encrypted password. This Key is created when the {{Odbedit cmd|cmd=passwd}} is issued. See [[Security#Restrict user access|Restrict user access]] for details.

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

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

;Notes
* This subtree pre-dates the improved [[Security]] features (August 2015) and is not to be confused with [[#RPC hosts subtree|RPC hosts/Allowed hosts]] array.
* This security feature is not proof against malicious access. See [[Security]] for details.

This subtree in the [[#Security|/Experiment/Security subtree]] is created when the {{Odbedit cmd|cmd=passwd}} is issued. When created, this subtree is empty.
Optionally, it may contain user-defined names of remote hosts allowed to have free access (i.e. without password) to the current experiment.

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

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

;Notes
* This subtree pre-dates the improved [[Security]] features (August 2015)
* This feature is not proof against malicious access. See [[Security]] for details.

This optional subtree in the [[#Security|/Experiment/Security subtree]] is created when the {{Odbedit cmd|cmd=passwd}} is issued. When created, this subtree is empty.
Optionally, it may contain user-defined names of clients allowed to have free access (i.e. without password) to the current experiment. See [[Security #Allowed programs]].

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

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

;Notes
* This key pre-dates (and has been superceded by) the improved [[Security]] features (August 2015)
* This feature is not proof against malicious access. See [[Security]] for details.

If [[Security#Restrict user access|restriction on user web access]] has been set up, this key in the [[#Security|/Experiment/Security subtree]]
will contain an encrypted password for Web server access. This key is created by using the {{Odbedit cmd|cmd=webpasswd}}.

If this key is present, the user will be requested to provide the "Web Password" when accessing the requested experiment in "Write Access" mode. The "Read Only Access" mode is still available (without a password) to all users.

<br>
--------
<br>
</div> 

<div style="background-color:silver">
== <span style="font-size:120%;">The following keys are OBSOLETE:</span> ==

=== <span style="color: purple;">''Mongoose listening_port''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "8080r,8443s"
</div>
<br>
:This key in the [[#top|/Experiment tree]] existed for a short time in midas versions May-August 2015.
: It has been '''replaced by the ODB keys [[#midas http port|midas http port]] and [[#midas https port|midas https port]].'''
<br>
<span style="font-size:80%">
This key in the [[#top|/Experiment tree]] was created when [[mhttpd]] was run for the first time. It contained the listening ports for the secure
HTTPS/SSL server ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]). The ports are the HTTP port (default 8080) which is to be redirected to the secure HTTPS port (default 8443).
If ports were supplied with the "--mg" option when starting {{Utility|name=mhttpd}}, their values will overwrite the default values stored in this key. See [[mhttpd]] for details.
</span>
<br>
--------
<br>

=== <span style="color: purple;">''Mongoose access_control_list''</span> ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' ""
</div>
<br>
:This key in the [[#top|/Experiment tree]] existed for a short time in midas versions May-August 2015.
:'''Use the [[#mhttpd hosts subtree|mhttpd hosts/Allowed hosts]] access control list or the [[mhttpd]] "-a hostname" parameter to restrict access.'''
<br>
<span style="font-size:80%">
This key in the [[#top|/Experiment tree]] is created when [[mhttpd]] is run for the first time. It contains the access control list (ACL) for the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server. By default, this key is empty and there is no access control. The format of the ACL is described under access_control_list at [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/Options.md?at=develop Mongoose Configuration Options].
</span>
<br>
--------
<br>

</div> 
[[Category:ODB Tree]] [[Category:Experiment]] [[Category:Security]]

Event Buffer

2016-08-26T01:25:32Z

Suz:

{{Pagelinks}}

== Increase size of events ==
In some experiments, the default event size (currently 4MiB) may not be large enough.

To increase the size of events, one must increase:
* the value of ODB [[/Experiment ODB tree #/Experiment/MAX_EVENT_SIZE |/Experiment/MAX_EVENT_SIZE]]
* max_event_size in the [[Frontend Operation#Frontend|Frontend]] and recompile
Actual limits on the bank size and event size are [[#Limits on the bank and event sizes|described below]].

By default the shared memory event buffer (used to contain the data from the event) is named SYSTEM. Its default size is 8MB.

For very large events, it will also be necessary to [[#Increase size of SYSTEM buffer|increase the size]] of the SYSTEM buffer (and any buffers used by the event builder etc).
Ultimately, the maximum event size is limited by the size of the SYSTEM buffer which is limited by the physical memory of your computer. No recompilation of MIDAS necessary.

== Limits on the bank and event sizes ==

;Limitations in order:

# bank32 size is limited to a 32 bit integer size (about 4000 Gbytes)
# bank size is limited by event size
# event size in a [[Frontend Operation#Frontend|Frontend]] based on MIDAS ''mfe.c'' is limited to the value of max_event_size set by the user
# maximum event size that can go through the MIDAS event buffer system is limited to ODB value [[/Experiment ODB tree #/Experiment/MAX_EVENT_SIZE |/Experiment/MAX_EVENT_SIZE]] (Note that MAX_EVENT_SIZE in midas.h is no longer used).
# maximum event size is limited to '''half''' the size of the SYSTEM shared memory event buffer (or any other buffers that the event has to go through)
# default size of the SYSTEM buffer is 8 Mbytes set by ODB /Experiment/Buffer sizes/SYSTEM. This limits maximum event size to about 4 Mbytes.
# size of SYSTEM buffer can be [[#Increase size of SYSTEM buffer|increased]] to arbitrary size, but in practice no bigger than the amount of computer physical memory minus space needed for running the [[Frontend Operation#Frontend|Frontend]] program and [[mlogger]], which also allocate buffer space to hold 1 event of maximum size.

So for a computer with 8 Gbytes of RAM, you can make the SYSTEM buffer size 4
GBytes, set ODB MAX_EVENT_SIZE to 1 Gbyte, and in theory, you should be able to
write 1 Gbyte events from your frontend to disk.

In practice, some of the biggest events to go through a MIDAS system are
non-compressed waveforms in the T2K/ND280 FGD and TPC detectors, about 4 Mbytes of
data per event.

<div id="other considerations"></div>
; Other considerations (rules of thumb):

# the SYSTEM event buffer should be big enough to hold 10-100 events.
# the SYSTEM event buffer should be big enough to hold about 5-10 seconds of data
:: i.e. if the event size is 1 Mbyte and data rate is 1 Hz, 10 seconds of data will be 1Mbyte*1Hz*10sec = 10 Mbytes.

This is because the SYSTEM buffer decouples the real-time activity of the [[Frontend Operation#Frontend|Frontend]]
program from non-real-time activity of writing data to storage devices.

== Increase size of SYSTEM buffer ==
For large events it may be necessary to increase the size of the SYSTEM buffer. See [[#other considerations|note above]].
* shutdown all clients
* set ODB key [[/Experiment ODB tree#SYSTEM|/Experiment/Buffer Sizes/SYSTEM]] to the larger value (a power of 2)
* remove SYSTEM shared memory file .SYSTEM.SHM (located in directory given by [[#Exptab]])
* restart clients

[[Category:Event]] [[Category:Frontend]] [[Category:Buffer]]

Odbedit examples

2016-06-20T21:01:14Z

Suz:

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Mhttpd|mhttpd MIDAS web server]]
* [[ODB Page]]
* [[odbedit]]
* [[ODB|Using the ODB]]
</div>

= Examples of odbedit commands =

* [[ODB#Example|cd]]
* [[ODB#Example|create]], [[ODB#Creating arrays|create arrays]]
* [[Creating Internal Custom Page#odbedit import export|export]]
* [[Creating Internal Custom Page#odbedit import export|import]]
* [[Edit-on-start Parameters#Creating edit-on-start parameters|ln]]
* [[ODB#Example|ls, ls -r]]
* [[ODB#experim.h include file|make]]
* [[ODB#Example|mkdir]]
* [[ODB#Reorder ODB keys|move]]
* [[ODB#Example|set]], [[ODB#Creating arrays|set arrays]]

; For more examples, see [[ODB|Using the ODB]]

[[Category:ODB]]

Setup MIDAS experiment at TRIUMF

2016-06-13T23:07:18Z

Suz: /* Secure MIDAS and ELOG Web access */

{{Pagelinks}}
== Introduction ==
This page describes setting up a MIDAS experiment at TRIUMF. This information can be adapted for other sites.

== Environment variables ==
* '''MIDASSYS''' Base directory of the MIDAS package, midas and mxml should be at the same level.
* '''MIDAS_EXPTAB''' Experiment definition file
* '''MIDAS_SERVER_HOST''' MIDAS host server name for remote midas connections.
* '''MIDAS_EXPT_NAME''' Experiment name

== Standard layout of MIDAS experiment ==
The following shows the directory layout of a standard MIDAS experiment:

/home/exptuser/
packages/
root <---- ROOT
mxml
mscb
midas/ <---- MIDAS
linux/{lib,bin} <---- binaries matching the selected 64-bit/32-bit flavour of ROOT
linux-m32/{lib,bin} <---- limited function 32-bit binaries for 32-bit frontend machines, build by "make linux32"
linux-m64/{lib,bin} <---- limited function 64-bit binaries (only needed if ROOT and linux/bin are 32-bit)
linux-arm/{lib,bin} <---- full function ARM cross-compiled using "make linuxarm"
linux-crosscompile/{lib,bin} <---- cross-compiled limited function binaries for PPC and ARM frontends (see Makefile)
rootana <---- ROOT analyzer
roody <---- graphical online histogram viewer for MIDAS and ROOTANA
online/
exptab <---- experiment definition
{.ODB,.SYSTEM,.SYSMSG,etc}.SHM <---- MIDAS shared memory save files
src <---- experiment frontend sources
bin,scripts
elog <---- MIDAS elog
history <---- MIDAS history
data -> /data/exptname/current <---- symlink to the data directory
/data/exptname/current <---- experiment data directory with ODB save files and MIDAS .mid/.mid.gz data files

== Prepare computers ==

On some operating systems, several MIDAS functions require administrator access:

* on el7 linux (SL7/CC7/CentOS7/RHEL7) - access to mhttpd port 8443 requires special firewall rules, see here: https://www.triumf.info/wiki/DAQwiki/index.php/SLinstall#Enable_firewall_for_MIDAS_.28CentOS7.29
* on el7 linux - access to mserver to run frontends and other programs on some other computer requires special firewall rules, see here: https://www.triumf.info/wiki/DAQwiki/index.php/SLinstall#Enable_firewall_for_MIDAS_.28CentOS7.29
* on el7 linux - on the frontend machines (and other machines that will connect to the mserver, the same firewall rule needs to be created (use the IP address of the machine running the mserver)

== Prepare the user account ==
<div id="NOTES"></div>
;NOTES
* Instructions are given for recent MIDAS versions (August 2015 and later) which have enhanced [[Security]]. Instructions for older versions differ slightly.
** follow the <span style="color:orange">orange</span> instructions for older versions

* The '''Default Ports''' are different between the two versions:
** default ports are mserver (1175), mhttpd (8080 and 8443)
** <span style="color:orange">default ports (older versions) are mserver (7071), mhttpd (8081) </span>

The default port for ROODY is 9091.

* Setup the user account for running this instance of midas. For machines part of the LADD cluster, follow these [http://daq-plone.triumf.ca/SM/docs/local/NewLaddUser] instructions.
* check that the account is using the /bin/bash shell
* make $HOME/.profile look like this:

<pre>
#!/bin/echo You must source

export SVN_EDITOR="emacs -nw"
export GIT_EDITOR="emacs -nw"
export MIDASSYS=$HOME/packages/midas
export ROOTANASYS=$HOME/packages/rootana
export MIDAS_EXPTAB=$HOME/online/exptab
#
# setup the MIDAS mserver
#
case `hostname` in
daq07*)
unset MIDAS_SERVER_HOST
;;
*)
export MIDAS_SERVER_HOST=daq07.triumf.ca:7070
;;
esac
#
# select 64-bit or 32-bit MIDAS and ROOT
#
case `uname -i` in
i386)
source /daq/daqshare/olchansk/root/root_v5.34.01_SL62_32/bin/thisroot.sh
export PATH=.:$MIDASSYS/linux-m32/bin:$PATH
;;
*)
#source /daq/daqshare/olchansk/root/root_v5.34.34_SL67_64/bin/thisroot.sh
source $HOME/packages/root/bin/thisroot.sh
export PATH=.:$MIDASSYS/linux/bin:$PATH
;;
esac
#
export PATH=.:$HOME/online/bin:$HOME/packages/roody/bin:$PATH
#
#end
</pre>

* mkdir $HOME/packages
* Logout and login again, for .cshrc changes to take effect

== Install ROOT ==

* Identify the Linux version: RH9 (Red Hat Linux 9), FC3 (Fedora Core 3), RHEL4/SL4 (Red Hat Enterprise LInux 4/Scientific Linux 4), SL5x, SL6x, (CentOS/CC/SL) el7x: more /etc/redhat-release
* Decide to use 32-bit or 64-bit ROOT ('uname -a')
* cd $HOME/packages
* ls -l /daq/daqshare/olchansk/root/ ### to see all available ROOT packages
* ln -s /daq/daqshare/olchansk/root/root_vNNN_VVV_BB root, where NNN is the latest available version of ROOT ("ls -l /daq/daqshare/olchansk/root"), VVV is the Linux version code (RH9, FC3, SL4, etc) and BB is "_32" or "_64" for 32-bit or 64-bit ROOT. For example: /daq/daqshare/olchansk/root/root_v5.10.00_SL40
* for example: ln -s /daq/daqshare/olchansk/root/root_v5.34.34_el72_64 $HOME/packages/root
* Check that ROOT works: "source $HOME/packages/root/bin/thisroot.sh; root". Type ".q" to exit root.

== Install MIDAS ==

* cd $HOME/packages
* (OBSOLETE) svn co svn+ssh://svn@savannah.psi.ch/repos/meg/midas/trunk midas, password "svn". (password has to be entered twice)
* (OBSOLETE) svn co svn+ssh://svn@savannah.psi.ch/repos/meg/mxml/trunk mxml
* git clone https://bitbucket.org/tmidas/midas
* git clone https://bitbucket.org/tmidas/mxml
* git clone https://bitbucket.org/tmidas/mscb
* (IF BITBUCKET IS DOWN) git clone -v --progress https://daq.triumf.ca/~daqweb/git/mxml.git
* (IF BITBUCKET IS DOWN) git clone -v --progress https://daq.triumf.ca/~daqweb/git/mscb.git
* (IF BITBUCKET IS DOWN) git clone -v --progress https://daq.triumf.ca/~daqweb/git/midas.git
* cd midas
* make
* (only if needed) make linux32 ### build the 32-bit MIDAS libraries
* ls -l linux/bin/odbedit ### check that odbedit has been created (do not run it yet)

You can see a list of other installation problems at [[Common problems & Debugging recipes]].

;NOTE
: Optional features in MIDAS can be explicitly disabled if desired when making MIDAS using the NO_xxx feature (NO_ROOT,NO_MYSQL,NO_ODBC,NO_SQLITE,NO_MSCB), e.g. "make NO_ROOT=1" to disable ROOT. These NO_xxx Makefile variables are only used to control autodetection.

== Install ROOTANA ==

* cd $HOME/packages
* git clone https://bitbucket.org/tmidas/rootana
* cd rootana
* make

== Install ROODY ==

* cd $HOME/packages
* git clone https://bitbucket.org/tmidas/roody
* cd roody
* make
* $HOME/packages/roody/bin/roody, run the program

== Build special versions of MIDAS ==

Build special versions of MIDAS for the case when some MIDAS programs, such as VME frontends, will run on a different computer that may have a different flavour of operating system, i.e. 32-bit linux or an older version of Scientific Linux.

* login to the computer where the frontends will run and:
* if it is a 32-bit linux: cd $HOME/packages/midas; make linux32
* if it is a 64-bit linux: cd $HOME/packages/midas; make linux64

* login to the host computer to cross-compile ARM code:
* if it is an ARM linux: cd $HOME/packages/midas; make linuxarm # may need to install ARM cross compilers

== Prepare VME hardware ==

Hardware check list:
* VME crate
* VME processor (supported are V77xx, V7805, V7865)
* On all VME modules, set the VME address jumpers as described here: http://daq-plone.triumf.ca/SM/docs/local/vme_jumpers
* run vmescan to confirm correct VME addresses
** cd $HOME/packages
** svn checkout https://ladd00.triumf.ca/svn/daqsvn/trunk/vme
** cd vme
** make
** ./vmescan.exe (or _gef.exe, depending on the VME driver in use)

== Install Universe-II VME driver (V7648, V7750, V7805, V7851) ==

* login as root (ssh root@localhost)
* follow instructions: https://www.triumf.info/wiki/DAQwiki/index.php/VME-CPU#V7648.2C_V7750.2C_V7805.2C_V7851_:_Setup_vme_universe_VME_drivers
* cd ~/packages/vme; vmescan.exe

== Install Tsi-148 VME driver (V7865) ==

* login as root (ssh root@localhost)
* follow instructions: https://www.triumf.info/wiki/DAQwiki/index.php/VME-CPU#V7865_and_XVB-602_:_Setup_gefvme.2Ftsi148_VME_drivers
* cd ~/packages/vme; vmescan_gef.exe

== Setup the experiment environment ==

* Decide which computer will host MIDAS (where MIDAS shared memory buffers will reside).
: This computer will run the [[mserver]], [[mlogger]] and [[mhttpd]] applications. (It is usually the machine where the MIDAS,ROOT etc. packages have been downloaded). It will be referred to as the host machine (localhost).

The environment is slightly different depending on whether all programs run on the host machine, or whether some programs run on remote host(s) :
=== ALL programs run on localhost ===
:If all programs run on the host machine (localhost), it is not necessary to run [[mserver]]. [[Environment Variables#MIDAS_SERVER_HOST|MIDAS_SERVER_HOST]] will not be assigned (see example .cshrc [[#Prepare the user account|above]]).

=== Some programs run on REMOTE host(s) ===
: '''IMPORTANT:'''
# Since August 2015 '''you must explicitly allow access for clients running on remote machines'''. To do this, follow the '''[[Security#MIDAS programs on remote machines|instructions here]]'''.
# The example code .cshrc ([[#Prepare the user account|see above]]) should be present on both host and remote machine(s). This will ensure that [[Environment Variables#MIDAS_SERVER_HOST|MIDAS_SERVER_HOST]] will NOT be set for the host machine (localhost), but on a remote machine, MIDAS_SERVER_HOST will be set to the MIDAS host machine.
# The client [[mserver]] must be started on the MIDAS host machine. Note that multiple experiments can run on the same host machine by starting several instances of [[mserver]] (one for each experiment) running with different ports (and .cshrc would be edited so that MIDAS_SERVER_HOST is set to the appropriate port for the experiment).

<br>
On the host machine:
* mkdir $HOME/online
* cd $HOME/online
* create directories for local programs, sources, elog and history: mkdir bin src elog history
* create data directory: mkdir -p /ladd/data1/t2kvme5/data; ln -s /ladd/data1/t2kvme5/data $HOME/online
* create the exptab file "$HOME/online/exptab" following the example below. The first entry (exptname) is the name if the DAQ system (MIDAS experiment name), the second entry (/home/USER/online) is the location of MIDAS shared memory buffers (by convention, $HOME/online), the third entry (kopio03) is your username.
<pre>exptname /home/kopio03/online kopio03</pre>
* logout and login again for all changes to take effect

== Setup experiment startup scripts ==
* login to the experiment host computer
* echo $MIDAS_SERVER_HOST ### to check correct value - should be blank
* create $HOME/online/bin/start_daq.sh, replacing XXX with the hostname of the machine running the experiment (and changing the mserver and mhttpd ports, as needed).

#!/bin/sh
# start_daq.sh
cd $HOME/online
#
case `hostname` in XXX*)
echo "Good, we are on XXX!"
;;
*)
echo "The start_daq script should be executed on XXX"
exit 1
;;
esac
#
odbedit -c clean
# start [[mhttpd]] on default port. (Mongoose https version - see [[mhttpd]] for other options)
mhttpd -D -a localhost -a XXX.triumf.ca # optionally restrict access to specified hosts
#
# start [[mserver]] on default port (use argument -p to use a different port)
mserver -D # access must now be specifically allowed - see [[#Setup the experiment environment|above]]
<span style="color:orange;">
# OR ([[#NOTES|older MIDAS versions]])
# mhttpd -p 8081 -D -a localhost -a XXX.triumf.ca # optionally restrict access to specified hosts
# mserver -p 7071 -D -a localhost -a lxdragon01.triumf.ca -a lxdragon02.triumf.ca -a XXX.triumf.ca # optionally restrict access to specified hosts
</span>
#
mlogger -D
#end file

== Setup experiment database (ODB) ==

* run $HOME/online/bin/start_daq.sh

* odbedit, run these commands: (replace user names and directory names)
<pre>
set "/Logger/Message file" "/home/kopio03/online/midas.log"
set "/Logger/Data Dir" "/home/kopio03/online/data"
create STRING "/Logger/History dir"
set "/Logger/History dir" "/home/kopio03/online/history"
create STRING "/Logger/Elog dir"
set "/Logger/Elog dir" "/home/kopio03/online/elog"
set "/Logger/ODB dump file" "/home/kopio03/online/history/run%05d.xml"
set "/Logger/ODB dump" "y"
set "/Logger/Channels/0/Settings/Filename" "run%05dsub%03d.mid.gz"
set "/Logger/Channels/0/Settings/Subrun byte limit" "1000000000"
set "/Logger/Channels/0/Settings/Compression" 1
set "/Logger/Channels/0/Settings/ODB Dump" "y"
set "/Programs/Logger/Required" y
set "/Programs/Logger/Start command" "mlogger -D"
set "/Programs/fevme/Required" "y"
set "/Programs/fevme/Start command" "ssh -n lxdaq09 $HOME/online/src/fevme_gef.exe -O"
exit
</pre>
* open web browser e.g. firefox.
* go to the midas status page at https://localhost:8443 (default port).
** if running [[mhttpd]] with Mongoose HTTPS/OpenSSL (the default) for the first time, you will need to create a password file. Follow the instructions (see [[mhttpd#HTTPS/SSL server (Mongoose)]] for details).
** For other options (i.e. HTTPS/SSL proxy) see [[#Secure MIDAS and ELOG Web access]]
*<span style="color:orange;">OR open the midas status page at http://localhost:8081 ([[#NOTES|older MIDAS versions]])
* midas status page will show most stuff "red" as nothing is running yet
* DON'T DO THIS YET run ./fevme.exe (on the computer with the VME interface, could be different from computer hosting the experiment), observe that corresponding equipments have been created
* save the url bookmark to the "personal toolbar"
* go to the Programs page, stop mlogger, stop fevme, start mlogger, start fevme
* go to the Status page, start run, stop run
* go back to the Status page, everything should be green
* start a run
* send signals to the ADC gate
* you should be getting events
* to look at data, proceed with setting up the [[ROOTANA|ROOT Analyzer]].

== Start DAQ programs at boot time ==

* add this to /etc/rc.local (replace username and location of the start_daq script)
<pre>
su - alpha -c /home/alpha/online/bin/start_daq.sh
</pre>

== Setup local software version control ==

Version control for experiment source code is setup using "git" (http://git-scm.com/)

* cd $HOME/online
* git init
* git add exptab
* git add bin/start_daq.sh
* git add .gitignore ### contents can be
<pre>
*~
*.o
*.exe
</pre>
* git add src/Makefile src/*.cxx ...
* git commit -a

== Adjust MIDAS buffer sizes ==

Default MIDAS SYSTEM buffer size is 8 Mbytes, fairly small for high-data-rate experiments. The rule of thumb is to have at least a few seconds worth of buffer space available. For example, if event size is 10 Kbytes and the event rate is 1 kHz, data rate is 10*10^3*1*10^3 = 10 Mbytes/sec. To buffer 10 seconds of data we need 100 Mbytes of buffer space.

To resize the MIDAS event buffers (SYSTEM, etc) do this:
* stop all frontends, stop mlogger
* start odbedit:
** cd "/Experiment/Buffer sizes"
** set SYSTEM 100000000
* run "mdump -z SYSTEM"
* if mdump complains about the size of .SYSTEM.SHM, remove it, try again.
* ls -l /dev/shm ### to observe that the size of shared memory is correct

== Secure MIDAS and ELOG Web access ==
In versions prior to May 2015, the default web access to MIDAS and ELOG uses the "http:" protocol which is insecure. In this case, all information is transmitted as clear text meaning that secret, confidential and sensitive information (such as the MIDAS and ELOG passwords and usernames) can be stolen "easily". This means that even "password protected" MIDAS and ELOG pages are not really protected if accessed using the "http" method.

Better security for HTTP is gained by using a password protected '''SSL (https) proxy'''. (It does not provide absolute security because of remaining problems with the security of SSL certificates, security of passwords, etc). Setting up an SSL (https) proxy is described [[#Setting up an HTTP proxy|below]].

Since May 2015, an ''alternative secure option'' to setting up an HTTP proxy is available to users of MIDAS. Recent versions of elogd (ELOG) do support SSL https:// connections, and [[#mhttpd with HTTPS/SSL server (Mongoose)]] is now available. This option is the default, and provides a similar level of security to an HTTP proxy.

See [[Security#Web Access]] for a comparison of these two secure options.

=== mhttpd with HTTPS/SSL server (Mongoose) ===

Since May 2015 the MIDAS web server [[mhttpd]] is explicitly linked with OpenSSL to provide secure HTTPS connections via the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server (see [[mhttpd]]). With this version, default web access to MIDAS uses the "https" protocol. Web access to {{Utility|name=mhttpd}} can be restricted by using the "-a hostname" switch of [[mhttpd]]. The first time {{Utility|name=mhttpd}} is run, a password file must be created. An SSL certificate is also required. See [[mhttpd#HTTPS/SSL server (Mongoose)|HTTPS/SSL server (Mongoose)]] for instructions.

=== mhttpd using an HTTPS/SSL proxy ===
An [[#Setting up an HTTP proxy|HTTP proxy]] must be set up. This is the only way of securing older version of [[mhttpd]] (pre August 2015). Older versions of mhttpd are started using the -p port option e.g.
* <span style="color:orange"> mhttpd -D -p 8080 </span>

To run a new version of mhttpd using an HTTP proxy, use the options provided to run the old (non-Mongoose) webserver on a given port, i.e.
* <span style="color:green"> mhttpd --oldserver 8080 --nomg -D </span>

When using an SSL proxy, only access from the SSL proxy (and maybe some special trusted machines) should be permitted.
This is done using the "-a hostname" switch of [[mhttpd]]. Normally there will be only "-a localhost" switch, enabling access only for the local machine (where the SSL proxy is running). Additional "-a hostname" switches enable access from listed local machines. No "-a xxx" enables access from everywhere (defeating the purpose of the SSL proxy, unless access controls are enforced elsewhere, i.e. by a site firewall or by local firewall rules).

== Setting up an HTTP proxy ==
In this example, we use APACHE HTTPD to password-protect a typical midas/mhttpd and elog installation.

In this configuration, one uses the Linux stock httpd that accepts encrypted https:// connections and forwards them to mhttpd and elogd. Instead of (or in addition to) using mhttpd and elogd passwords, one configures password protection in httpd via the regular apache httpd password mechanisms (htpasswd, etc).

Recent versions of elogd do support SSL https:// connections, but if one is running an SSL proxy for anyway, it is simpler to run both through the same SSL proxy using the same SSL host certificate and the same httpd password file.

=== Restricting http: access to elogd ===
;Note
:Recent versions of elogd do support SSL https:// connections. The following information is for those using an HTTP proxy (see above).

For elogd, this is done using the "-n localhost" switch with enables only access from the same machine if present, or access from anywhere is absent (defeating the purpose of the SSL proxy, unless access controls are enforced elsewhere).

(It is recommended to run elogd from the same user as the main daq user and to keep elogd.cfg and all logbooks in the home directory of this user, where they are captured by the normal site backup system)

== Install standalone elog ==

* login into the user account that will run the elog
* cd $HOME/packages
* git clone https://bitbucket.org/ritt/elog
* cd elog
* make
* create new file start_elogd with this contents:
<pre>
#!/bin/sh

killall elogd
sleep 1
killall -KILL elogd
sleep 1
$HOME/packages/elog/elogd -n localhost -x -c $HOME/packages/elog/elogd.cfg -p 8082 -D

#end
</pre>
* chmod a+x start_elogd
* edit elogd.cfg to read:
<pre>
[global]
port = 8082
SMTP host = smtp.triumf.ca
URL = https://titan00.triumf.ca/elog/

Reverse sort = 1
Display Mode = full

#List Menu commands = New, Find, Admin, Help
#Menu commands = New, Edit, Reply, Find, Duplicate, Help

Entries Per Page = 30
Supress Email on edit = 1
Default encoding = 1
Page title = TITAN ELOG
Resolve host names = 1

Logfile = /home/titan/packages/elog/elogd.log
#Logging level = 3

[midas]

List page Title = T2K M11 MIDAS ELOG
Comment = T2K M11 MIDAS ELOG
Page Title = T2K M11 MIDAS ELOG
RSS Title = [$logbook - $type - $system] $subject, posted by $author

Attributes = Author, Subject, Run, Type, System
Show Attributes Edit = Run, Author, Subject, Type, System
Required Attributes = Author, Type, System, Subject

Options Type = Routine, Reply, Shift Summary, Modification, Question, Info, Problem
Options System = General, DAQ, Beamline

Preset Run = $shell(MIDASSYS=. /home/t2km11/packages/midas/linux/bin/odbedit -d Runinfo -c 'ls -v \"run number\"')

Preset On Reply Type = Reply
Preset On Reply Run = $shell(MIDASSYS=. /home/t2km11/packages/midas/linux/bin/odbedit -d Runinfo -c 'ls -v \"run number\"')

List Display = Date, Subject, Type, System, Author, ID
Quick Filter = Date, Type, ID

Remove on reply = Author
Quote on reply = 1

Use lock = 1

************* Email Functionality ****************

Use Email Subject = [T2KM11 - $System] $Subject
Omit Email To = 1

Email System General = xxx
</pre>
* ./start_elogd &
* firefox http://localhost:8082 # hould show the elog message index

To start elogd automatically when the machine is rebooted, login as root and
* add this text to /etc/rc.local:
<pre>
su - titan -c "/home/titan/packages/elog/start_elogd"
</pre>
* chmod a+x /etc/rc.local
* systemctl start rc-local

To import elog entries from the mhttpd elog, do this:

* cd ~/packages/elog/logbooks
* ln -s /home/t2km11/online/elog midas
* cd midas
* ~/packages/elog/elconv)

== Install https proxy ==

* login as root to the https proxy machine
* cd ~root
* yum install mod_ssl
* yum install crypto-utils # see http://www.triumf.info/wiki/DAQwiki/index.php/SLinstall#Enable_monitoring_of_HTTPS_certificates
* create a certificate request (replace ladd09 with your hostname): openssl req -new -nodes -newkey rsa:2048 -sha256 -out ladd09.csr -keyout ladd09.key (answer: CA, BC, Vancouver, TRIUMF, DAQ, ladd09.triumf.ca, email@email.com
* sign it by TRIUMF:
** mail -s "Certificate request" yourself@email.com < ladd09.csr
** forward this request to Andrew Daviel
** he will email the signed crt file, copy it to this system as ladd09.crt
* sign it yourself: openssl x509 -req -days 365 -sha256 -in ladd09.csr -signkey ladd09.key -out ladd09.crt
* (if the certificate expires, renew it by signing it again)
* Additional commands for working with certificates:
** explore the private key: openssl pkey -in ladd09.key -text -noout
** explore the certificate request: openssl req -in ladd00.csr -text -noout
** explore the certificate: openssl x509 -in ladd09.crt -noout -text
* move certificate files to proper system locations:
* mv ladd09.key /etc/pki/tls/private/
* mv ladd09.crt /etc/pki/tls/certs/
* if selinux is enabled, do this:
** restorecon -Rv /etc/pki/tls/certs/
** restorecon -Rv /etc/pki/tls/private/
** /usr/sbin/setsebool -P httpd_can_network_connect 1
* open /etc/httpd/conf.d/ssl.conf in a text editor, go to the very bottom and right before the "</VirtualHost>" entry, add following text:
<pre>
...
SSLCertificateFile /etc/pki/tls/certs/ladd09.crt
SSLCertificateKeyFile /etc/pki/tls/private/ladd09.key

ProxyPass /elog/ http://localhost:8082/ retry=1
ProxyPass / http://localhost:8080/ retry=1

<Location />

SSLRequireSSL
AuthType Basic
AuthName "password protected site"
Require valid-user

# create password file: touch /etc/httpd/htpasswd
# to add new user or change password: htpasswd /etc/httpd/htpasswd username
AuthUserFile /etc/httpd/htpasswd

</Location>
</VirtualHost>
...
</pre>
* comment out duplicate "SSLCertificateFile" and "SSLCertificateKeyFile" elsewhere in the file
* (optionally) If you got a certificate that is signed by DigiCert or RapidSSL then you'll need to add a line specifying the certificate chain file:
<pre>
...
SSLCertificateChainFile /etc/pki/tls/certs/DigiCertCA.crt
...
</pre>
* touch /etc/httpd/htpasswd
* htpasswd /etc/httpd/htpasswd midas # enter password midas
* chkconfig httpd on
* service httpd restart
* firewall-cmd --add-port=443/tcp --permanent
* firewall-cmd --reload
* firewall-cmd --list-all
* test it
** test the SSL proxy: https://host/ should yield the midas status page, https://host/elog/ should yield the elog message index
* in ODB, set "/Elog/URL" to "https://host/elog/"
* now from the midas status page, the "Elog" button should take us to the https Elog URL

In needed, enable user directories: https://blah/~user in ~user/public_html

* edit /etc/httpd/conf.d/userdir.conf, replace "UserDir disabled" with "UserDir enabled"
* setsebool -P httpd_enable_homedirs true
* systemctl restart httpd

== Setup the history mhttpd for faster access to history plots ==
When running an SSL proxy,
* start the main mhttpd (<span style="color:orange">orange</span> command for old mhttpd, <span style="color:green">green</span> for new mhttpd with Mongoose(post August2015):
** <span style="color:orange">"mhttpd -p 8071 -D" </span> or
** <span style="color:green"> "mhttpd -D --oldserver 8071 --nomg" </span>

* start the history mhttpd
** <span style="color:orange"> "mhttpd -p 8072 -D -H"</span> or
** <span style="color:green"> "mhttpd -D -H --oldserver 8072 --nomg" </span>
* set ODB /History/URL to "http://alphacpc09.cern.ch:8072/HS/"
* open the MIDAS status page
* go to the history section, try to open any history plot, observe that the history plot gif image loads correctly, inspect it's URL (use "copy image URL" or "view source", etc), it should point to port 8072 causing connection to the history mhttpd.
* continue with these instructions to setup history mhttpd access through an SSL proxy:
* setup SSL proxy access (required mod_proxy_html)
** login as root to the SSL proxy machine
** on SL5, install the missing mod_proxy_html httpd module:
** yum install httpd-devel libxml2-devel
** wget http://apache.webthing.com/mod_proxy_html/mod_proxy_html.tar.bz2
** tar xjvf mod_proxy_html.tar.bz2
** cd mod_proxy_html
** apxs -c -I. -I/usr/include/libxml2 -i mod_proxy_html.c
** apxs -c -I. -I/usr/include/libxml2 -i mod_xml2enc.c
** cd /etc/httpd/conf.d, add this to ssl.conf:

;before the ProxyPass statements:
<pre>
# proxy the MIDAS web servers
LoadModule xml2enc_module modules/mod_xml2enc.so
LoadModule proxy_html_module modules/mod_proxy_html.so
ProxyHTMLLinks a href
ProxyHTMLLinks link href
ProxyHTMLLinks img src
#ProxyHTMLEnable On
ProxyRequests off
</pre>
;after the ProxyPass statements:
<pre>
# ALPHA1 history access
ProxyPass /alpha1/history/ http://alphacpc09.cern.ch:8072/HS/ retry=1
ProxyPass /alpha1/ http://alphacpc09.cern.ch:8071/ retry=1

ProxyHTMLEnable On
ProxyHTMLURLMap http://alphacpc09.cern.ch:8072/HS/ /alpha1/history/
</pre>
;adjust:
*"alpha1" is the experiment name
*"alphacpc09.cern.ch" is the machine running mhttpd
*"8071" is the port number of the main mhttpd
** <span style="color:orange">"mhttpd -p 8071 -D" </span> or
** <span style="color:green"> "mhttpd -D --oldserver 8071 --nomg" </span>
* "8072" is the port number of the history mhttpd
** <span style="color:orange">"mhttpd -p 8072 -D -H" </span> or
** <span style="color:green"> "mhttpd -D -H --oldserver 8072 --nomg" </span>

[[Category:Installation]] [[Category:Buffer]] [[Category:Driver]]

Security

2016-06-13T23:04:04Z

Suz:

{{Pagelinks}}
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[mhttpd]] web server
* [[odbedit]]
* [[/Experiment ODB tree #/Experiment/Security |/Experiment/Security]] ODB subtree
* [[mserver]]
</div>
= Access Control to a MIDAS experiment =

Historically, by default there has been no restriction for any user to connect locally or remotely to a given experiment. This has now changed (August 2015).
The Web Server [[mhttpd]] by default now requires an SSL Certificate and a username and password (see [[#Web Access]]).

Other network security issues have also been addressed (see [https://midas.triumf.ca/elog/Midas/1088 Note 1088]). Changes to [[mserver]] (August 2015) make the default behaviour to reject all external network connections ([https://midas.triumf.ca/elog/Midas/1090 Note 1090]), so that only programs running on the localhost will be allowed. To allow access from remote machines, the user will have to take action as described [[#MIDAS programs on remote machines|below]].

== Web Access ==
In versions prior to May 2015, the default web access to MIDAS and ELOG uses the "http:" protocol which is insecure. In this case, all information is transmitted as clear text meaning that secret, confidential and sensitive information (such as the MIDAS and ELOG passwords and usernames) can be stolen "easily". This means that even "password protected" MIDAS and ELOG pages are not adequately protected if accessed using the "http" method. Until now, an SSL (https) proxy had to be set up to provide reasonable security for experiments.

Recent versions of elogd (ELOG) do support SSL https:// connections, and
the Web Server [[mhttpd]] has recently (May 2015) been updated to use OpenSSL to provide secure HTTPS connections via the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server. This limits access by default, by requiring a username and password - see [[mhttpd#HTTPS/SSL server (Mongoose)|HTTPS/SSL server (Mongoose)]] for more information. This option provides a similar level of security to an HTTP proxy.

=== Which security option to choose? ===

For a small operation that does not require root access to the host computer, mhttpd with mongoose is a good light weight solution. It is ideal for small experiments that until now have been using the "http:" protocol for mhttpd.

For a more elaborate setup with private networks etc., APACHE https proxy is probably better. For big experiments, resources like webcams,ganglia, couchdb, etc. also need password protection and APACHE https can provide all this.

=== Which one is easier to setup? ===

* mhttpd with mongoose is fairly simple - you have to create a password file and provide a properly signed https certificate - see [[mhttpd#HTTPS/SSL server (Mongoose)|HTTPS/SSL server (Mongoose)]]
* apache httpd is fairly straightforward if you follow well written instructions (such as we provide for using it with midas), but you do need root access and you do have to edit a good number of config files. Note that mhttpd with mongoose can be run with an SSL proxy - see [[Setup MIDAS experiment#using an HTTPS/SSL proxy]]

== MIDAS programs running on localhost ==

Out-of-the-box MIDAS is now secure (August 2015). By default, connections from the outside are not possible. MIDAS RPC TCP ports are bound to the localhost interface.
This configuration is suitable for testing MIDAS on a laptop and for running a simple experiment where all programs run on one machine.
MIDAS ports (except for the mhttpd web ports) do not show up on network port scans.

The change in binding UDP ports is generally incompatible with previous versions of MIDAS, so all MIDAS programs should be rebuild and restarted. If rebuilding all MIDAS programs is
impossible see [https://midas.triumf.ca/elog/Midas/1090 Note 1090]).

[[mserver]] will still work in this localhost-restricted configuration - one should use "[[odbedit]] -h localhost" to connect. Multiple mserver instances on
the same machine - using different TCP ports via "-p" and ODB [[/Experiment ODB tree#midas server port|/Experiment/midas server port]] - are still supported.

== MIDAS programs on remote machines ==

To run MIDAS programs on remote machines the following is now required:
# change the ODB setting [[/Experiment ODB tree#Enable non-localhost RPC|/Experiment/Security/Enable non-localhost RPC]] to "yes" and restart [[mserver]]
# add the hostnames of all remote machines that will run MIDAS programs to the MIDAS RPC access control list in ODB key [[/Experiment ODB tree#Allowed hosts|/Experiment/Security/RPC hosts/Allowed hosts]].

To avoid "guessing" the host names expected by MIDAS, follow the following procedure:
* On the local machine ("daq06") set ODB key "enable non-localhost rpc" to "yes" and restart the [[mserver]] (step 1 above)
* go to the remote machine ("ladd21") and try to start the MIDAS program, i.e. "[[odbedit]] -h daq06". This will bomb and there will be a message in the [[Message System#midas.log|Midas log file]] rejecting the connection from unallowed host 'ladd21.triumf.ca'.
* Add this host to <span style="color: purple; font-style:italic;">/Experiment/Security/RPC hosts/Allowed hosts</span>.
* After you add this hostname to <span style="color: purple; font-style:italic;">RPC hosts</span>, you should see messages in the [[Message System#midas.log|Midas log file]] about reloading the access control list
* try connecting again, it should work now.

;NOTE
If MIDAS clients have to connect from random hosts (i.e. dynamically assigned random DHCP addresses), one can disable the host name checks by setting ODB key [[/Experiment ODB tree#Disable RPC hosts check|/experiment/security/Disable RPC hosts check]] to "yes". This configuration is insecure and should only be done on a private network behind a firewall.

= ODB access control =
Note that '''other forms of ODB access control''' independent of these security features is also available which can protect the experiment from accidental access by authorized users:
* Write access can be restricted while a run is in progress (see [[Lock when running]] )
* Individual keys or subtrees in the experiment's ODB can be set "read only" with the [[odbedit]] command chmod.
* [[Custom Page|Custom web pages]] can provide experimenters with access to a subset of ODB keys necessary for the experiment. By [[Status Page#suppressed|hiding]] the [[ODB Page]] access button, the ODB can be protected from non-expert access via the web server.

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

<div style="background-color:whitesmoke">

= Security on OLDER (pre-August 2015) versions of MIDAS =

Versions of MIDAS older than August 2015 are vulnerable to malicious/unauthorized access. Network security on old versions can be enhanced by implementing a '''firewall''' and/or restrictions on off-site access. This kind of security can be provided by [[Setup MIDAS experiment#Setting up an HTTP proxy|setting up an HTTP proxy]] to [[mhttpd]] .

== Protect experiment from accidental access (old MIDAS versions) ==

The MIDAS system provides a means to setup access restrictions using the ODB in order to protect the experiment from accidental or unauthorized access. '''This will not stop malicious or determined hackers''' but may prevent mistakes by authorized users. These security features are still available, but their usefulness has largely been superceded by the improved security features implemented August 2015 (see [[#Access Control to a MIDAS experiment]]);

There are two levels of access restriction available each of which can be enabled independently:

* To restrict write access via the web by requiring a password before any parameter can be changed.
* To require a password before MIDAS clients can start running on the host.

The user can select either or both of these security features.

== Restrict user access (old MIDAS versions) ==

'''NOTE: this is not proof against malicious access.''' See [[#Access Control to a MIDAS experiment]].

The ODB [[/Experiment ODB tree #/Experiment/Security |/Experiment/Security]] subtree can also be used to restrict access to the experiment via the Web. This subtree is automatically created (if not already present) when the {{Odbedit cmd|cmd=webpasswd}} is issued as follows:

C:\online>odbedit
[local:Default:S]/>cd Experiment/
[local]/>webpasswd
Password:<xxxx>
Retype password:<xxxx>

After running the {{Odbedit cmd|cmd=webpasswd}}, a new ODB key i.e. [[/Experiment ODB tree #/Experiment/Security/Web Password |/Experiment/Security/Web Password]] will
be present containing the encrypted web password.

If this web access restriction is set up, the user will be requested to provide the "Web Password" when accessing the requested experiment in "Write Access" mode. The "Read Only Access" mode is still available to all users of older versions of [[mhttpd]], or those who supply the username and password now required by [[mhttpd]] (May 2015).

[local:bnqr:S]/Experiment>ls Security/
Web Password pon4@#@%SSDF2

== Restrict client access (old MIDAS versions) ==
'''NOTE: this is not proof against malicious access.''' See [[#Access Control to a MIDAS experiment]].

In order to restrict accidental access to the experiment, a password mechanism can to be defined. This is provided by the [[/Experiment ODB tree #/Experiment/Security |/Experiment/Security]] subtree in odb. This subtree is automatically created (if not already present) when the [[odbedit]] command passwd is issued as follows:

C:\online>odbedit
[local:Default:S]/>cd Experiment/
[local]/>passwd
Password:<xxxx>
Retype password:<xxxx>

After running the {{Odbedit cmd|cmd=passwd}}, the {{Odbpath|path=/Experiment/Security}} subtree will be present.

=== Allowing access without password (old MIDAS versions) ===
NOTE: This feature has been superceded by [[#Access Control to a MIDAS experiment]] for [[mhttpd]] versions May 2015 or later.

While [[#Restrict client access|restricting access]] can make sense to deny access to outsider to a given experiment, it can be annoying for the people working directly at the back-end computer or for an automatic frontend reloading mechanism. To address this problem, specific hosts and clients can be exempt from having to supply a password before being granted full access.

==== Allowed hosts (old MIDAS versions) ====
NOTE: This feature has been superceded by [[#Access Control to a MIDAS experiment]] for [[mhttpd]] versions May 2015 or later.

Hostnames to be allowed full access to the ODB are listed in the [[/Experiment ODB tree #/Experiment/Security/Allowed hosts subtree |/Experiment/Security/Allowed hosts]] subtree, e.g.

[local]/>cd "/Experiment/Security/Allowed hosts"
[local]rhosts>create int myhost.domain
[local]rhosts>

where <myHost.domain> is to be replaced by the full IP address of the host requesting full clearance, e.g "pierre.triumf.ca".

==== Allowed programs (old MIDAS versions) ====
NOTE: This feature has been superceded by [[#Access Control to a MIDAS experiment]] for [[mhttpd]] versions May 2015 or later.

Programs (i.e. clients) to be allowed full access to the ODB (regardless of the node on which they are running) can be listed in the
[[/Experiment ODB tree #/Experiment/Security/Allowed programs subtree |/Experiment/Security/Allowed programs]] subtree,

[local]/>cd "/Experiment/Security/Allowed programs"
[local]:S>create int mstat
[local]:S>

</div> 

[[Category:Security]] [[Category:Experiment]]

Mhttpd

2016-06-13T22:58:17Z

Suz:

{{Pagelinks}}
= Links =
{{mhttpdpages3|[[Mhttpd.js|MIDAS Javascript Library]]|[[odbedit]]|[[Security]]}}

= Purpose =
The {{Utility|name=mhttpd}} utility runs the '''MIDAS Web Server''' which allows the user to communicate with an experiment using any web browser. It is used primarily for run control.

= Web security =
As part of the recent upgrade to MIDAS [[Security]], the MIDAS Web Server {{Utility|name=mhttpd}} is now (May 2015) explicitly linked with OpenSSL to provide secure HTTPS connections via the [https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose] web server. To connect to an experiment using {{Utility|name=mhttpd}}, a username and password are required.
By default, users can connect from anywhere, providing they know the correct username and password. However, '''web access can be restricted''' by using the {{Utility|name=mhttpd}} access control list in the ODB at [[/Experiment ODB tree#mhttpd hosts subtree|Allowed hosts]], and/or by using the "-a" argument to {{Utility|name=mhttpd}}.

Alternatively, {{Utility|name=mhttpd}} can be run securely behind an Apache HTTPS proxy (see [[Security]] for details). In this case, the Mongoose/OpenSSL web server should be disabled using the arguments supplied to {{Utility|name=mhttpd}} - see [[#To start the webserver using the oldserver|starting the web server using the oldserver]].

The option of building {{Utility|name=mhttpd}} without OpenSSL is also supported (see [https://midas.triumf.ca/elog/Midas/1069]).

= Arguments =
-h connect to midas server [[mserver]] on given host
-e experiment to connect to
-v display verbose HTTP communication
-D become a daemon
-E only display ELog system
-H only display history plots
-a only allow access for specific host(s), several [-a Hostname] statements might be given (default list
in ODB at [[/Experiment ODB tree#mhttpd hosts subtree|/Experiment/security/mhttpd hosts/allowed hosts]])
--http port - bind to specified HTTP port (default is ODB [[/Experiment ODB tree#midas http port|/Experiment/midas http port]])
--https port - bind to specified HTTPS port (default is ODB [[/Experiment ODB tree#midas https port|/Experiment/midas https port]])
--nomg use the old mhttpd web server
--oldserver [port] - use the old web server on given port
--nooldserver - do not use the old mhttpd web server
-help display usage information

If using an old version (before May 2015), see [[#Insecure (pre-May 2015) versions|old server]] argument list.

= Usage =
== To start the webserver using HTTPS/SSL (Mongoose) ==
* ''"mhttpd"'' or
* ''"mhttpd -v"'' to get debug information, or
* ''"mhttpd -D"'' to run in the background
* ''"mhttpd -a myHost1 -a myHost2"'' to restrict web access
All are equivalent to
* ''"mhttpd --https 8443 --http 8080"''
Starting {{Utility|name=mhttpd}} like this will redirect the default HTTP port of 8080 to the secure HTTPS port 8443. If the ports are not supplied, the default ports will be read from the ODB keys [[/Experiment ODB tree#midas http port|midas http port]] and [[/Experiment ODB tree#midas https port|midas https port]]. If ports are supplied, their values will overwrite the default values stored in the ODB. When {{Utility|name=mhttpd}} is started with a secure port for the first time, a password file (and optionally an SSL certificate) need to be created. See [[#HTTPS/SSL server (Mongoose)|mhttpd HTTPS/SSL server]] for more information.

If {{Utility|name=mhttpd}} is started on IP host machine "myhost" using the default ports, the [[#Features|''Midas status page'']] can be accessed by pointing a web browser to
* https://myhost.mydomain:8443
* or to http://myhost.mydomain:8080 which will be redirected automatically to https://myhost.mydomain:8443

The automatic redirect may be convenient for users who are used to using {{Utility|name=mhttpd}} with a particular HTTP port (e.g. 8080) for their experiment. The redirect can be disabled by setting the ODB key [[/Experiment ODB tree#http redirect to https|http redirect to https]] to "n".

=== Multiple experiments ===
If [[Exptab|multiple experiments]] run on the same host, a web server for each experiment must be started on a different port, e.g.
* ''"mhttpd -e expt1 -D"'' use default ports
* ''"mhttpd -e expt2 --http 8081 --https 8444 -D"'' use supplied ports

== To start the webserver using the oldserver ==
To run a new version of {{Utility|name=mhttpd}} using the old server (i.e. NOT the Mongoose/HTTPS server)
* ''"mhttpd --oldserver 8081 --nomg"''

This command is useful for running new versions of {{Utility|name=mhttpd}} using an Apache HTTPS proxy (see [[Security]]).

= Features =
The Midas web server {{Utility|name=mhttpd}} provides a means for run control including monitoring of the run parameters.
Its main feature is a web page invoked through any web browser accessing the Midas experimental URL at a defined port (see [[#Usage|Usage]]).

The contents of this '''Midas status page''' is composed with minimal information relative to the experiment. It contains a collection of buttons and links to other pages to further describe and control the configuration of the experiment.

* Minimal display on the main [[Status Page]]
** Experiment name, time & date, page refresh rate
** Standard Menu Buttons (see below)
** User defined buttons (e.g. alias links, run scripts, custom pages etc.)
** run comments and condition display section (if enabled)
** Equipment list with current running condition, number of event received, event rate, data rate for each equipment.
** Data logging statistics (number of event recorded, data size recorder, compression factor, usage storage level) if enabled.
** Secondary Data logging (data mover) with statistics if enabled.
** Single line of the most recent Midas message.
** Table of the current applications connected to this experiment.

* Standard Menu Buttons
** Transition the state of the run (stopped/running/paused), allows user running condition parameters to be entered at the start state (see [[Edit-on-start Parameters]]).
** Access to the full [[Online Database]] for data display and/or data content modification.
** Display the [[Message Page]], which shows messages generated by the MIDAS [Message System]] as well as the user using cm_msg() functions.
** Access to [[ELOG Page]] switches to the predefined "electronic logbook".
** Access to the [[Alarms Page]] for monitoring the different type of alarms (evaluated, programs, internals, periodic).
** Access to the [[Programs Page]] for a status or interaction with the current running applications part of the Midas experiment.
** Access to the [[History Page]] for graphical data representation of any ODB variables and acquired data.
** Access to the Midas Slow Control Bus devices [[MSCB Page]] connected to this experiment.
** Access to the [[Sequencer Page]] control/monitoring page for [[Sequencer]] i.e. interactive loading/saving/running of a run sequence based on any ODB parameters.
** Access to the [[Chat Page]] for communication between users on the same experiment.
** Access to the [[Help Page]] with short-cut to the Midas Help documentation resource and other information.
* Links
** links to all the listed equipments invoking a dedicated page for the display and possible control of the equipment parameters.
** link to the logger configuration (if present) for the data recording.
** link to the possible secondary logging configuration parameters (if present).

Other features include a JSON interface and Javascript library used for implementing interactive [[Custom Page|custom pages]] for MIDAS experiments.

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

= HTTPS/SSL server (Mongoose) =

The HTTPS/SSL ([https://bitbucket.org/tmidas/midas/src/ecb9a8537448a8a43f7f9a2bfdb82e578208cde3/doc/mongoose/?at=develop Mongoose]) server is activated by running {{Utility|name=mhttpd}}, and by default it listens on ports 8080 and 8443 (see [[#Usage]]).

{{Utility|name=mhttpd}} with Mongoose requires an '''SSL Certificate''' and a '''password file'''. Ideally, an SSL Certificate issued by a well-known authority trusted by your browser should be used.

The first time {{Utility|name=mhttpd}} is run, if it does not find an SSL Certificate, it will print instructions on how to [[#Create an SSL certificate|create a self-signed SSL Certificate]]. If it finds no existing password file, it will then print instructions on how to [[#Create a password file|create a password file]] (see below for examples).

== Create an SSL certificate ==
If no [[#HTTPS/SSL server (Mongoose)|more secure]] SSL Certificate is available, then create a self-signed certificate by running {{Utility|name=mhttpd}},
and following the printed instructions :
[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
[mhttpd,ERROR] [mhttpd.cxx:17086:mongoose,ERROR] cannot find SSL certificate file "/home/user/online/test/ssl_cert.pem"
[mhttpd,ERROR] [mhttpd.cxx:17087:mongoose,ERROR] please create SSL certificate file: openssl req -new -nodes -newkey rsa:2048
-sha256 -out ssl_cert.csr -keyout ssl_cert.key; openssl x509 -req -days 365 -sha256 -in ssl_cert.csr -signkey ssl_cert.key
-out ssl_cert.pem; cat ssl_cert.key >> ssl_cert.pem
could not start the mongoose web server, see messages and midas.log, bye!

The certificate and key should be placed in one PEM file called ssl_cert.pem located in either MIDAS environment variables [[MIDAS environment variables#MIDAS_DIR|MIDAS_DIR]] or [[MIDAS environment variables#MIDASSYS|MIDASSYS]], and the permissions on the file should be 600 or only owner read/write.
[user@dasdevpc2 test] chmod 600 ssl_cert.pem

== Create a password file ==
Once a valid certificate is generated, when {{Utility|name=mhttpd}} is restarted, you will need to create a password file.

[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
Web server will use SSL certificate file "/home/user/online/test/ssl_cert.pem"
[mhttpd,ERROR] [mhttpd.cxx:17137:mongoose,ERROR] mongoose web server cannot find password file "/home/user/online/test/htpasswd.txt"
[mhttpd,ERROR] [mhttpd.cxx:17138:mongoose,ERROR] please create password file: htdigest -c /home/user/online/test/htpasswd.txt test midas
could not start the mongoose web server, see messages and midas.log, bye!

Each person who is to have access to the experiment should create their own username and password. The first user (e.g. mary) creates the password file e.g. htpasswd.txt
[user@dasdevpc2 test]$ htdigest -c /home/user/online/test/htpasswd.txt test mary
Adding password for mary in realm test.
New password:
Re-type new password:
[user@dasdevpc2 test]$ mhttpd
Web server will listen on ports "8080r,8443s"
Web server will use SSL certificate file "/home/user/online/test/ssl_cert.pem"
Web server will use authentication realm "test", password file "./htpasswd.txt"

Access to the [[#Features|''Midas status page'']] can be obtained by pointing a web browser to
https://myhost.mydomain:8443
The first time you connect you will be asked for a username and password.
Now that the password file has been created, subsequent users may create their own username and password in the same file by omitting "-c" argument in htdigest, e.g.
htdigest /home/user/online/test/htpasswd.txt test john

Web access can be restricted to certain hosts if desired (see [[#Web security]]).

Documentation for the version of mongoose included with MIDAS can be found at [http://ladd00.triumf.ca/~daqweb/doc/midas-devel/doc/mongoose/ Mongoose documentation].

For more information see [https://midas.triumf.ca/elog/Midas/1062 Elog note 1062]

<br>
--------
<br>
<div style="background-color:whitesmoke; font-size:90%">

= HTTP only (pre-May 2015) versions =

;Note
* HTTP-only (pre-May2015) versions of mhttpd should only be used '''behind a firewall'''
* If Web [[Security]] is an issue, update to the latest version of mhttpd which uses HTTPS/OpenSSL.

== Arguments (old version) ==

-p port : port number e.g. 8080 (no default). See [[#Usage|usage]].
[-h hostname ] : see [[Common Parameters to MIDAS Utilities]]
[-e experiment] : see [[Common Parameters to MIDAS Utilities]]
[-v] : display verbose HTTP communication
[-D] : starts program as a daemon
[-E] : only display ELog system
[-H] : only display history plots
[-a hostname] : only allow access for specific host(s). Several [-a Hostname] statements might be given
[-help]

== Usage (old version) ==
The command '''mhttpd -p port''' can be used to start the web server (http version). In this case, the TCP/IP port number is '''required''' as an argument in order to listen to the web-based request.
<br>e.g. if mhttpd is started on IP host machine "myhost" on port 8081 as follows
: mhttpd -p 8081 -D
access to the [[#Features|''Midas status page'']] can be obtained by pointing a web browser to
http://myhost.mydomain:8081

;Note
If [[Exptab|multiple experiments]] run on the same host, a web server for each experiment must be started on a different port, e.g.
mhttpd -e expt1 -p 8081 -D
mhttpd -e expt2 -p 8082 -D

== Improve Security with SSL Proxy ==
Improved security for HTTP is gained by using an SSL (https) proxy. See [[Setup MIDAS experiment#mhttpd with HTTP|Setting up an SSL proxy]].
</div>

[[Category:Utilities]]
[[Category:Web server mhttpd]]
[[Category:Run control]]

Common Parameters to MIDAS Utilities

2016-06-09T02:36:25Z

Suz:

{{Pagelinks}}

= Common Input Parameters =
Each of the [[Application listing|MIDAS utilities]] define a number of input parameters. The following parameters are common to many :

; [-e <exptname> ] :specifies the [[MIDAS Experiment Name|MIDAS Experiment]] to connect to (where multiple experiments are defined on the MIDAS host (see [[exptab]]).
* This option supersedes the default experiment name given by the environment variable [[Environment Variables#MIDAS_EXPT_NAME|MIDAS_EXPT_NAME]] , if defined.
* If multiple experiments are defined, unless [[Environment Variables#MIDAS_EXPT_NAME|MIDAS_EXPT_NAME]] is defined or this argument is supplied, the application will request the experiment name.
* If the environment variable [[Environment Variables#MIDAS_DIR|MIDAS_DIR]] is defined (i.e. single default experiment), both the ''exptname'' input parameter and environment variable [[Environment Variables#MIDAS_EXPT_NAME|MIDAS_EXPT_NAME]] will be superseded.

; [-h <hostname> ] : connect to midas server [[mserver]] on given host ''hostname'', i.e. specifies the [[MIDAS Host Name |MIDAS Host]] to connect to when connecting to an experiment running on a '''remote''' host. If the experiment is running on the '''local''' host, this argument need not be supplied.

* If ''hostname'' '''is''' supplied :
** ''hostname'' must be a valid IP host name.
** ''hostname'' supersedes the default hostname given by the environment variable [[Environment Variables#MIDAS_SERVER_HOST|MIDAS_SERVER_HOST]] , if defined.
** the [[mserver]] utility '''must''' be running on the remote host.
* If more than one copy of <span style="color:darkcyan;font-style:italic">mserver</span> is running, the <span style="color:darkcyan;font-style:italic">mserver</span> portname must be specified, e.g.
odbedit -h myhost:1173 -e myexpt -c "ls /Experiment"

* If the environment variable [[Environment Variables#MIDAS_DIR|MIDAS_DIR]] is defined (i.e. single default experiment), both the ''hostname'' input parameter and environment variable [[Environment Variables#MIDAS_SERVER_HOST|MIDAS_SERVER_HOST]] will be superseded.

[[Category:Utilities]] [[Category:Appendices]]

Start Page

2016-03-10T02:01:55Z

Suz:

{{Pagelinks}}

= Links =
{{mhttpdpages1|[[Message System]]}}

= Purpose =
The purpose of the [[mhttpd]] Start page is to
display the run number ''and any defined [[Edit-on-start Parameters]]'' for the user to optionally edit, prior to the run starting.

= Access the Start page =
The Start Page is accessed from the [[Status Page]] (or one of the other Pages) by clicking on the menu-button
<span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;
padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">Start</span> i.e. by '''starting a run'''.

;Note
:If "Start" button is not present on the Status Page, it may have been [[Status Page#page-switch-buttons|suppressed]].

= Examples =

Figure 1 shows examples of the Start page with and without [[Edit-on-start Parameters]] defined. Note that in Figure 1c the edit-on-start parameter "number of cycles" has a '''parameter comment''' associated with it (see [[Edit-on-start Parameters#edit-on-start parameter comments|defining parameter comments]]).

{| class="wikitable" cellpadding="50" cellspacing="50"
|+ Figure 1 Start Page
|-
!Figure 1a No edit-on-start parameters defined !! Figure 1b One edit-on-start parameters defined
|-
| [[File:Mhstart1.gif|border|400px|Figure 1a: No edit-on-start parameters defined ]]|| [[File:Mhstart.gif|border|400px|Figure 1b: One edit-on-start parameter defined ]]
|-
!colspan=2|Figure 1c: Many edit-on-start parameters defined
|-
|colspan="2"|[[File:Mhstart2.gif|left|border|1000px|Figure 1c: Many edit-on-start parameters defined]]
|}

<br clear=all>

[[Category:mhttpd Pages]]

Template:Mhttpdpages

2016-03-10T02:00:35Z

Suz:

<noinclude>
Usage: {{mhttpdpages}}
</noinclude>
<div style="column-count:5;-moz-column-count:5;-webkit-column-count:5">
* [[mhttpd|mhttpd web server]]
* [[Status Page]]
* [[Start Page]]
* [[ODB Page]]
* [[Message Page]]
* [[Programs Page]]
* [[Alarms Page]]
* [[History Page]]
* [[ELOG Page]]
* [[Chat Page]]
* [[Help Page]]
* [[Config Page]]
* [[Custom Page]]
* [[MSCB Page]]
* [[Sequencer Page]]
* [[odbedit]]
</div>
<br>