Universal Device Driver Reference Manual

1.344 Macro-Player

The Macro-Player logical device lets you play a macro automatically if a parameter changes or id another device send a message to the macro player device. Several operation modes are available which allow different types of sources which trigger the macro replay.

The Macro-Player is intended to be used in a M&C environment only. It expects the macro to play in the './macros' directory locally on the VLC/M&C. NMS systems store macro files centrally on the NMS server where they not accessible to Macro-Player device.

Macro execution modes

The Macro-Player device may be operated in a number of different modes, selected by the 'execMode' configuration parameter (see 'Configuration parameters' below). The operation mode is used to adapt the device to the type of event it shall use as a trigger for the macro replay:

EXEC-CONFIGURED --- In this mode the device plays the macro with the name given in the configuration parameter 'macroName' whenever it receives a value for 'execute' variable, regardless of the value received with this message. This mode may be used to make the device respond to a button press from the GUI.
EXEC-BY-NAME --- In this mode the device plays a macro with the value received with a message to the 'execute' variable. The same device may play multiple macros this way, for instance acting as a common backend for multiple buttons starting one macro each.
EXEC-IF-EQUAL --- In this mode the device watches a parameter of another device, addressed by the configuration variable 'parameterId'. If the value of the parameter changes to the value as defined in the 'referenceValue' configuration parameter, the macro with the name given in the configuration parameter 'macroName' is played.
EXEC-IF-NOT-EQUAL --- In this mode the device watches a parameter of another device, addressed by the configuration variable 'parameterId'. If the value of the parameter changes to a value different to the value in the 'referenceValue' configuration parameter, the macro with the name given in the configuration parameter 'macroName' is played.
EXEC-BY-PARAMETER --- The last mode also watches the variable addressed by the 'parameterId' configuration variable. Any time this variable changes to a new value, this value is treated as a macro name and the macro is played.
EXEC-BY-TIMER --- Like with EXEC-CONFIGURED, the device plays the macro with the name given in the configuration parameter 'macroName'. In EXEC-BY-TIMER mode the macro plays automatically every 'interval' seconds, as long as 'timer mode' is set to RUNNING. If 'max count' is set to a non zero value, automatic playing stops after the given number of executions.Using macros with %wait directives together with short interval times may cause the Macro-Player device to start a new instance of the macro before the previous one has finished. While this causes no trouble for the software (the macros will play autonomously in parallel), the result might not be as you expect.

Macros are played in a separate software threads, hence %wait directives in macros may be used freely without delaying other parts of the software. If a macro to be played does not exist, this is silently ignored, also lines within a macro definition which cannot be parsed also are skipped without notice. This is the same behaviour as with macros played from the GUI.

In the modes EXEC-IF-EQUAL, EXEC-IF-NOT-EQUAL and EXEC-BY-PARAMETER the initial value of the watches parameter never starts a macro play. A three cycles startup delay inhibits macro plays during the initialization phase.

In the modes EXEC-IF-EQUAL and EXEC-IF-NOT-EQUAL the 'execute' parameter behaves like in EXEC-CONFIGURED. This means, the configured macro may be triggered by setting 'execute' to an arbitrary value in addition to the configured parameter comparison.

The modes EXEC-IF-EQUAL and EXEC-IF-NOT-EQUAL do a string-based comparison of the unformatted value of the watched parameter. For this reason you should not use FLOAT type parameters for this, because it's very likely that the comparison fails due to rounding inaccuracies. TEXT, CHOICE and INTEGER parameters are safe to use, BOOL or ALARM type parameters can be compared to true/false (all lower case letters).

Device window pages

The following table shows which device window pages are available with this individual device type. Tool-bar functions not mentioned here are described at the general description of device windows .

--- The device info page.
--- The maintenance page. The configuration parameters from this page are described below.

Configuration parameters

At the maintenance page of the device window there are a couple of configuration parameters which configure the behaviour of the device.

parameter	description
execMode	The general operation mode of the device as explained above.
macroName	The name of the macro to be played in the modes EXEC-CONFIGURED, EXEC-IF-EQUAL and EXEC-IF-NOT-EQUAL
parameterId	The message ID of the parameter to be watched in the modes EXEC-IF-EQUAL, EXEC-IF-NOT-EQUAL and EXEC-BY-PARAMETER
referenceValue	The reference used for the value comparison in the modes EXEC-IF-EQUAL and EXEC-IF-NOT-EQUAL.

Variables defined by this device driver

name	type	flags	range
info.driver	TEXT	R/O	StringRange R/O
info.type	TEXT	R/O	StringRange R/O
info.frame	TEXT	R/O	StringRange R/O
info.state	TEXT	R/O	StringRange R/O
info.nextExecution	TEXT	R/O	StringRange R/O
info.executionCount	TEXT	R/O	StringRange R/O
config.execMode	CHOICE	SAVE SETUP	EnumRange (EXEC-CONFIGURED EXEC-BY-NAME EXEC-IF-EQUAL EXEC-IF-NOT-EQUAL EXEC-BY-PARAMETER EXEC-BY-TIMER)
config.macroName	TEXT	SAVE SETUP	StringRange
config.parameterId	TEXT	SAVE SETUP	StringRange
config.referenceValue	TEXT	SAVE SETUP	StringRange
execute	TEXT		StringRange
interval	INTEGER	SAVE	IntegerRange (0 .. 0)
maxCount	INTEGER	SAVE	IntegerRange (0 .. 0)
timerMode	CHOICE	SAVE	EnumRange (STOPPED RUNNING)