MidasWiki - User contributions [en]

Sequencer

2021-06-30T10:47:27Z

Marco.francesconi: added ODBLoad sequencer command

{{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 is part of the MIDAS distribution. It uses a simple Midas Script Language (MSL) for commands.

The sequencer runs as a separate process and must be started before running a sequence via the command '''msequencer'''. 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 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}} or the sequencer 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;"|MSL format
!style="width: 60%;background-color:#C0C0C0;"|Description
|-
||INCLUDE ''name''
||Include another XML file ''name''.xml
|-
||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'', ''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''
||A comment for this XML file, for information only. This comment is shown in the title bar next to the file name if one runs a script. This can be helpful if one has many XML files and the file name only is not enough to supply enough information.
|-
||GOTO ''n''
||Jump to line ''n'' in script
|-
||IF ''con'' 
... 
ELSE 
... 
ENDIF
||Statements between "IF" and "ENDIF" are only executed if condition "con" is true, otherwise the statements between the optional "ELSE" and "ENDIF" 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''
||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 [''name'' ,] ''n'' ... ENDLOOP
||To execute a loop ''n'' times. For infinite loops, "infinite" can be specified as ''n''. Optionally, the loop variable running from 0...''(n-1)'' can be accessed inside the loop via $''name''.

|-
||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 ''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'', ''name''
||To get a value from a variable ''name''. The variable can then be referenced with $''name''.
|-
||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 ''path'', ''value'' [, 0|1]
||To set a value in the ODB. 
The path value can match multiple keys using the '?' and '*' wildcard (one or any number of characters respectively). This is useful to set the same sub-path on multiple folders: 
<pre>
ODBSET "/Path/to/somewhere/folder0/value", "1"
ODBSET "/Path/to/somewhere/folder1/value", "1"
ODBSET "/Path/to/somewhere/folder2/value", "1"
</pre>
can be shortened as: 
<pre>
ODBSET "/Path/to/somewhere/folder*/value", "1"
</pre>
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.
|-
||ODBLOAD ''file'' [, ''path'']
||Load an external file into the ODB. 
JSON, XML and ODB file format are supported with the value inferred by the content of the file.
The optional path marks the position where to load the given file into the ODB, if no position is given the file is loaded from ODB root. 
For the input file few options are supported: if the filename starts with "/" is is assumed as an absolute path, if it starts with a "$" the path starts from the Sequncer root folder stored in the ODB by /Sequencer/Path. In all other cases it is intended as a relative path to the local MSL file.
|-
||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 
<pre>
<ODBSet path="/Very/long/path/into/the/odb/value1">1</ODBSet>
<ODBSet path="/Very/long/path/into/the/odb/value2">1</ODBSet>
<ODBSet path="/Very/long/path/into/the/odb/value3">1</ODBSet>
<ODBSet path="/Very/long/path/into/the/odb/value4">1</ODBSet>
</pre>
one can write 
<pre>
<ODBSubdir path="/Very/long/path/into/the/odb">
<ODBSet path="value1">1</ODBSet>
<ODBSet path="value2">1</ODBSet>
<ODBSet path="value3">1</ODBSet>
<ODBSet path="value4">1</ODBSet>
</ODBSubdir>
</pre>
|-
||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''
||a run description which is stored under /Experiment/Run Parameters/Run Description .
|-
||SCRIPT ''script'' [, a, b, c, ...]
||To call a script on the server side. Optionally, pass parameters to the script.
|-
||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'' ... ENDSUBROUTINE
||Declares a subroutine which can be called via CALL.
|-
||TRANSITION start | stop | pause | resume
||To start, stop, pause or resume a run
|-
||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.
<pre>
WAIT ODBvalue, /Equipment/HV/Variables/Measured[3], <, 100
</pre>
|}

= 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>

[[Category:Sequencer]]

ODB Access and Use

2020-04-06T10:25:12Z

Marco.francesconi:

{{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.

 

= 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 (/Custom) 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 # show current directory (tree) 
/
[local:midas:S]/>mkdir custom/images # make directory "custom" and subdirectory "images"
[local:midas:S]/>ls # list all keys
System
Programs
Experiment
Runinfo
Alarms
Custom
[local:midas:S]/>cd custom # change directory to "/custom" 
[local:midas:S]/custom>ls
images
[local:midas:S]/custom>create string "custom page&" # Create a key of type STRING. Note use of quotes as key name contains a space 
String length [32]: 128
[local:midas:S]/custom>set "custom page&" /home/midas/custom/custom.html # Set key to a value.
# Could type instead "set cus" followed by tab to demonstrate tab-completion 
[local:midas:S]/custom>ls -r # list recursively 
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"

== Setting multiple keys at once ==
There are occasions where multiple keys of different subfolder need to be modified; an Equipment may have multiple boards each one with its own configuration.
For this reason the set command can expand paths to match multiple keys with a single command. An example using the standard ODB:

[local:test:S]set /Alarms/Alarms/*/Active n

will deactivate all alarms.

== 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 /Experiment, /Analyzer/Parameters, and /Equipment/<equipment-name>/Settings 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 /<Analyzer-name>/Parameters 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 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]]

Sequencer

2020-04-06T10:04:54Z

Marco.francesconi:

{{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 is part of the MIDAS distribution. It uses a simple Midas Script Language (MSL) for commands.

The sequencer runs as a separate process and must be started before running a sequence via the command '''msequencer'''. 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 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}} or the sequencer 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;"|MSL format
!style="width: 60%;background-color:#C0C0C0;"|Description
|-
||INCLUDE ''name''
||Include another XML file ''name''.xml
|-
||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'', ''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''
||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 ''n''
||Jump to line ''n'' in script
|-
||IF ''con'' 
... 
ELSE 
... 
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''
||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 [''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 ''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 ''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'', ''name''
||To get a value from a variable ''name''. The variable can then be referenced with $''name''.
|-
||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 ''path'', ''value'' [, 0|1]
||To set a value in the ODB. 
The path value can match multiple keys using the '?' and '*' wildcard (one or any number of characters respectively). This is useful to set the same sub-path on multiple folders: 
<pre>
ODBSET "/Path/to/somewhere/folder0/value", "1"
ODBSET "/Path/to/somewhere/folder1/value", "1"
ODBSET "/Path/to/somewhere/folder2/value", "1"
</pre>
can be shortened as: 
<pre>
ODBSET "/Path/to/somewhere/folder*/value", "1"
</pre>
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'' ...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 
<pre>
<ODBSet path="/Very/long/path/into/the/odb/value1">1</ODBSet>
<ODBSet path="/Very/long/path/into/the/odb/value2">1</ODBSet>
<ODBSet path="/Very/long/path/into/the/odb/value3">1</ODBSet>
<ODBSet path="/Very/long/path/into/the/odb/value4">1</ODBSet>
</pre>
one can write 
<pre>
<ODBSubdir path="/Very/long/path/into/the/odb">
<ODBSet path="value1">1</ODBSet>
<ODBSet path="value2">1</ODBSet>
<ODBSet path="value3">1</ODBSet>
<ODBSet path="value4">1</ODBSet>
</ODBSubdir>
</pre>
|-
||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''
||a run description which is stored under /Experiment/Run Parameters/Run Description .
|-
||SCRIPT ''script'' [, a, b, c, ...]
||To call a script on the server side. Optionally, pass parameters to the script.
|-
||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'' ... ENDSUBROUTINE
||Declares a subroutine which can be called via CALL.
|-
||TRANSITION start | stop | pause | resume
||To start, stop, pause or resume a run
|-
||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.
<pre>
WAIT ODBvalue, /Equipment/HV/Variables/Measured[3], <, 100
</pre>
|}

= 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>

[[Category:Sequencer]]