Chapter 5. Macros

A '!' as the first letter disables the action. It can later on be enabled from the macros menu.

RePros are specified by the optional keyword repro and their name (identifier). In case, RePros from different plugin sets have the same name, a RePro can be uniquely identified by appending the name of the plugin set in '[]' to the RePro's name. Optionally, the RePro name is followed by a colon and a list of parameter that are separated by semicolons or new lines. The values of the parameter are passed to the RePro's options.

Example:

repro ResearchProgram1[pluginsA]: parameter11=10ms; parameter12=20; 
ResearchProgram2
parameter21=10ms
parameter22=20; 

You can use the Macro's variables for defining values of the RePro's options like this:

ResearchProgram1: parameter1=$duration

where duration is a macro variable.

You can define a whole range of values for a parameter in parenthesis. For example

ResearchProgram1: parameter1=(4..10)ms;

results in seven calls of the RePro "ResearchProgram1" with parameter1 getting the values 4, 5, 6, 7, 8, 9, and 10 ms. In order to obtain the values 4, 6, 8, and 10 ms, an increment different from one can be specified like this:

ResearchProgram1: parameter1=(4..10..2)ms;

An arbitrary sequence of values is separated by commas and can be intermixed with ranges: (4,6..8,10) is expanded to 4,6,7,8,10.

You can specify in which order you want the sequence to be generated. The default is 'up'. Alternatively you can specify 'down', 'alternate', or 'random' like this:

ResearchProgram1: parameter1=(4..10..2,down)ms;

generates 10, 8, 6, 4, 2.

Finally, you can specify an initial resolution. The default resolution is one. For example, defining an initial resolution of two

ResearchProgram1: parameter1=(4..10..2,down,r:2)ms;

produces the sequence 10, 6, 2, 8, 4.

Two functions of a filter or detector can be accessed from a macro: auto-configure the parameter of a filter or detector, or save some data.

A filter can be auto-configured by writing

filter LocalField-1: autoconf 0.5

and similarly for a detector

detector Spikes-1: autoconf 0.5

This executes the autoConfigure() function of the filter/event detector for the trace/events with name "LocalField-1"/"Spikes-1" for the last 0.5 seconds of available data. If the time is omitted, 1 second is assumed. If the name of a specific filter/event detector is omitted, then autoConfigure() is called for all filter and event detectors. See the documentation of the Filter for more details.

Data of a filter can be saved by writing

filter LocalField-1: save some-parameter

and similarly for a detector

detector Spikes-1: save some-parameter

This executes the save() function of the filter/event detector for the trace/events with name "LocalField-1"/"Spikes-1" and passes the string "some-parameter" to this function. This is ment to write some usefull information of the performance of the filter or event detection into a file. The parameter string may span multiple lines as long as each line contains a '='. See the documentation of the Filter for more details.

A control command sets one or more parameter of a control widget.

For example

control Histogram: intrace=Interval

sets the "intrace" parameter of the control "Histogram" to "Interval".

It depends on the implementation of the control widget how it reacts to a changed parameter.

Messages are simple popup windows that display a text. They are specified by the message keyword. You can define an optional timeout (in seconds) after which the window is closed automatically. An optional caption is displayed in the windows title bar.

For example

message 5 Hello: This is the message text.

opens a window with "Hello" in the title bar, displaying "This is amessage text.". The window is closed after 5 seconds.

Any text enclosed by '$(' and ')' is interpreted as a command. The command is executed in a shell and its standard output replaces the command text. See also Shell. The message text may extend over several lines, provided each new line starts with at least one character of white space.

For example

message The time is $(date).

date is executed and $(date) is replaced by its output. As a result, the following text is displayed in the window:

The time is Wed Aug 10 13:59:06 CEST 2005.

If the message text is empty, then no window is opened.

The following example macro displays a message after a session is stopped only if the free disk space is less than 1000MB:

 
$DISKSPACE stopsession nobutton
message $(DS=$(df -B 1M . | tail -n 1 | awk '{ print $4 }'); 
[ $DS -lt 1000 ] && echo "<h1>! Warning !</h1><h2>Less than <b>${DS}MB</b> of free disk space left!</h2>
Please make backups and clean up to make room for the next recording!")

A text browser displays text from a file in a simple html capable browser. The text browser is specified by the browse keyword. An optional caption is displayed in the windows title bar.

For example

browse RELACS Macros: doc/html/macros.html

opens a text browser with "RELACS Macros" in the title bar, displaying the content of the file doc/html/macros.html.

Any text enclosed by '$(' and ')' is interpreted as a command. The command is executed in a shell and its standard output replaces the command text. See also Shell.

	Note
	browse takes a file name as argument and not the text it should display as message does.

Shell comands are introduced by the shell keyword.

Example:

shell cp foo.dat foo.dat.bak

The following environment variables can be used from within a shell command:

The shell command may span several lines provided each new line starts with at least one character of white space.

You can call another macro from within a macro. Just give the name of the macro you want to call after the keyword macro.

For example

macro SAMs

calls the macro "SAMs".

If the macro that is called has variables you can set the values of those variables like this:

macro SAMs: duration=42s

Like for a RePro, several line can be used for the variables.

A different set of macros can be loaded from a file. Write the name of the file behind the keyword switch.

For example

switch newmacros.cfg

loads the macros defined in the file newmacros.cfg.

By default, all current macros are removed when loading / switiching to a new macro configuration file. However, individual macros can be excluded from being removed by marking them with keep (see A Macro and the overwrite keyword as well).

An action containing simply the keyword

startsession

starts a new session, but without calling the startsession - macro (see A Macro).

An action containing simply the keyword

stopsession

stops a running session, but without calling the stopsession - macro (see A Macro). The metadata dialog is not launched and the preset values for the metadata are used for saving a session.

An action containing simply the keyword

shutdown

quits relacs. A running session is stopped without calling the stopsession - macro (see A Macro) and without launching the metadata dialog. The preset values for the metadata are used for saving a session.