The Macro Language

DM84 macros are simply a series of instructions - expressed using the DM84 macro language. The macro language is a set of building blocks from which different types of instructions can be formed. These building blocks, or language elements, are:

Commands - These are the familiar native commands of the DM84, as documented in the "Command Set" in the reference manual or under the Control Panel Help menu. Ultimately, the purpose of the macro will be to issue one or more commands to the DM84 in order to "do" something.
Variables - These are user defined global storage, used pass data within a macro, or between macros. Variables make it possible for macros to have a "memory" of past actions, or to capture data for use within another macro, at some other time. Arithmetic, comparsion, and logical operations can be performed with variables.
Loops - These are "while-do" statements of the sort seen in many other programming languages. Loops make it possible for a particular instruction to be run multiple times as long as the current state of some device property or value of some user defined variable meets a specified condition.
Conditionals - These are "if-then-else" statements of the sort seen in many other programming languages. Conditionals make it possible for a macro to choose between alternative actions on the basis of the current state of some device property or the value of some user defined variable.

Macros may contain up to 64 "lines", each containing one or more instructions. Multiple instructions MUST be separated by a ';' (semicolon) character. Loop and conditional instructions may be combined. These maximum length of a line is 115 characters.

Macros are "run" in response to some triggering event, such as a serial command or the pressing of a pushbutton connected to a programmable logic input pin. Applications such as room combining, courtroom sound systems, and teleconferencing rely on macros to make system setup changes "on the fly" in response to button panel activity or serial commands from 3rd party control systems.

Commands

DM84 commands consist of:

A target - this identifies a property of the DM84 like "input gain", or an action to be performed, like "run a macro".
An address - this modifies the target of the command, by identifying a particular member of a set of things - which input gain, or which macro to run. The documentation for a command specifies whether or not an address a required, and the form it should take.
An operator - an operator, if present, modifies the meaning or intent of the command. The query operator ('?') signals that the command is a query for the value of some device property. The update (assignment) operator ('=') signals that the command includes data (the argument) which is to be assigned to some device property. If no operator is present then the command is for a some action to be performed. The documentation for a command will specify which operators, if any, may be used.
An optional argument - this is the value or data payload needed for "update" commands. The documentation for a command will specify what kind of argument is required for the "update" case.

For example:

outgn(3)?
The target "outgn" means output gain value, the address "3" means channel 3, the '?' operator means it's a query for the value of the target property.
outgn(3)=2
The target "outgn" means output gain value, the address "3" means channel 3, the '= ' operator means it's an update of the target property, the argument "2" is the new value.
run(3)
The target "run" means "run a macro", the address 3 means macro number 3, the absence of an operator means it's an order to perform the target action.

The built-in command set of the DM84 is extensive, so the documentation is broken up into sections:

General Commands	Audio Input	Matrix Crosspoints	Audio Output	Input Compressor	Output Compressor
Output Limiter	Programmable I/O	Front Panel Control	Rear Panel Control	ADFE System

Special built-in commands for use in macros: Two built-in commands are of special interest:

sleep - this command puts the macro processor to "sleep" for a given number of milliseconds in order to insert a delay between two instructions. For example: sleep=50
exit - this command forces the macro processor to stop executing the macro. It's normally used within an conditional or loop instruction. For example: if(@foo@<10)then`ingn(*)=@bar@`else`exit`

Verbose mode commands in macros: If a "verbose mode" command is executed within a macro, the response will be sent back on the RS232 serial port, rather than suppressed. This can be useful for 3rd party control panel applications that rely on command responses to update their visual controls - they can stay synchronized with the device state when a macro is run. Verbose mode commands are those prefixed with the '!' (bang) character, for example: !ingn(3)=0

Variables

Variables are user defined, and consist of a variable "name" enclosed within a pair of '@' characters. The name may include any of the printable characters except '@'. The maximum length allowed for variable names is 15 characters (not including the enclosing '@' characters). Examples: @stage2@ or @mic_muted@. Variable names are case sensitive! For example, @foo@ is not the same variable as @Foo@ or @FOO@.

Variable types: Variables can store the following LecNet2 data "types":

integer such as 42
array of integer such as {1,2,3,4}
string such as "East hallway"
boolean really an integer, interpreted as "false" when the integer value is 0 and as "true" for any other value
array of boolean really an array of integer, with values of either 1 or 0, such as {1,0,1,0}

Initializing variables: A variable is "initialized" the first time (after powerup) that the macro command processor encounters an instruction assigning a value to it. For instance, running a macro containing the instruction @foo@=42 will cause the variable @foo@ to be created if it doesn't already exist. The variable @foo@ is said to be "initialized" at this point with integer value 42. The instruction @bar@={1,2,3,4,5}, on the other hand, would initialize @bar@ with an array of integer value with 5 elements.Important: variables are "volatile", which means that they are lost when power is removed from the DM84. When the DM84 is powered back up, the variables will be initialized all over again as described above.

Array variable size: The maximum size of an array variable is 32 elements.

Accessing elements in array variables: Individual elements of a variable of type array of integer or array of boolean can be accessed using a "subscript" notation. For example, @foo@[2] accesses the 2nd element in the array. The location of the element MUST be a an integer value between 1 and 32 enclosed within a pair of '[' and ']' characters. The location may also be specified as a variable with an integer value, or even by an arithmetic expression. For example:

@foo@[2]
@foo@[%bar@]
@foo@[@bar@[3]]
@foo@[@bar@+1]

Important: It is an error to address array elements that don't exist, such as in @foo@[5], when @foo@ has only 4 elements. It is also an error to use the subscript notation with any variable whose type is not an array of integer or array of boolean (e.g. strings, simple integers).

Arithmetic with variables: Basic integer arithmetic operations may be performed using variables. Addition ('+'), subtraction ('-'), multiplication ('*'), division ('/') and modulo division ('%') operations are supported, but remember that the variable needs to hold an integer value for the result to make sense. Use pairs of parentheses, '(' and ')', to group terms in complicated expressions to get the proper result. The value of an arithmetic expression is the integer result of the operations. For example:

@foo@+2
Value is the sum of 2 and @foo@
(2+@foo@[2])*4
Value is the sum of 2 and the 2nd element of array @foo@, multiplied by 4
@foo@-2+@bar@
Value is @bar@ added to the difference between @foo@ and 2
@foo@/(@bar@+1)
Value is @foo@ divided by the sum of @bar@ and 1
@foo@*@foo@
Value is the square of @foo@
@foo@=@foo@+1
Value is @foo@ incremented by 1

Comparison with variables: An integer variable can be compared to a literal integer value or another integer variable. A string variable can be compared to a another string variable, or tested for equality with a string literal. Equality ('== '), inequality ('!= '), less than ('<'), greater than('>'), less than or equal ('<= ') and greater thanor equal ('>= ') comparisons are supported. For string types the comparisons are"lexical" in nature - they are compared character by character, and characters are judged by their ASCII code value. So "aaa" is equal to "aaa" but not equal to "aaaa", and "abc" is "less than" "bbc" because 'a' comes before 'b' in the ASCII table. The value of a comparison expression is a boolean type: "true" if the condition is met or "false" if the condition is not met. For example:

@foo@<10
True if @foo@ is less than 10
@foo@[2]<10
True if the 2nd element of array @foo@ is less than 10
@foo@>@bar@
True if @foo@ is greater than @bar@ (works for integer or string values)
"test"==@foo@
True if @foo@ contains the string value "test"
@foo@ != 17
True if @foo@ is not equal to 17
@foo@==@bar@
True if @foo@ is identical to @bar@ (works for string, integer AND array of integer types)
@foo@[2]==@bar@
True if the 2nd element of array @foo@ is identical to @bar@ (works only if @foo@ is an array of integer (or boolean) type and @bar@ is an integer (or boolean) type.)
@foo@!=@bar@
True if @foo@ is not identical to @bar@ (works for string, integer AND array of integer types)

Since an arithmetic expression has an integer value, it can substitute for an integer within a comparison expression. For example:

@foo@<(@bar@+10)
True if @foo@ is less than the sum of @bar@ and 10
((@foo@*2)+1)==@bar@
True if 1 added to the product of @foo@ and 2 is equal to @bar@

Note that the arithmetic expression MUST be enclosed with parentheses for this to work properly.

Logic with variables: Any variable with an integer value can be treated as a boolean type, either "true" or "false". The convention is that the integer value zero (0) means "false" and any nonzero value means "true". Variables that are used in this way can then be compared using the "logical" operations "AND" ('&&'), "OR" ('||') and "NOT" ('!'). The value of a logical expression is also a "boolean" type. For example:

@foo@
True if @foo@ is nonzero
!@foo@
True if NOT @foo@ is nonzero (that is, @foo@ is zero)
@foo@&&@bar@
True if both @foo@ and @bar@ are nonzero
@foo@||@bar@
True if either @foo@ or @bar@ are nonzero (or both)
!@foo@&&!@bar@&&@sam@
True if NOT @foo@ is nonzero and NOT @bar@ is nonzero and @sam@ is nonzero (that is, @foo@ and @bar@ are zero, and @sam@ is nonzero)

Going further, more complicated expressions can be formed by grouping terms using parentheses to get the proper result. Also, since a comparison expression has a boolean value, it can substitute for a boolean variable within a logical expression. For example:

@foo@&&(@bar@||@sam@)
True if @foo@ is nonzero and either @bar@ or @sam@ are nonzero
(@foo@||@bar@)&&(@sam@<50)
True if @foo@ or @bar@ are nonzero and @sam@ is less than 50.
(@foo@!="stop")&&!@bar@
True if @foo@ does not contain the string value "stop" and @bar@ is zero

Note that the comparison expression MUST be enclosed with parentheses for this to work properly.

Assigning a value to a variable: A value can be assigned to a variable in several ways. Whatever the method, the assignment instruction begins with the variable name followed by the assignment operator '=', like this: @foo@=. Next comes the expression for the value to be stored in the variable. The possibilities are:

Literal value: A "literal" integer or string value can be assigned. The value is expressed using the normal LecNet2 syntax. For example:
- @foo@=142
- @foo@={4,4,4,4}
- @foo@="hello"
Query output: The value of some DM84 "property" can be assigned to a variable by capturing the output of the appropriate "query" command. The command is expressed using the normal LecNet2 syntax, enclosed within a pair of '`' (backtick) characters. Don't forget the '?' at the end of the query! For example:
- @foo@=`outmt(*)?`
- @foo@=`prgin(3)?`
- @foo@[2]=`prgin(3)?`
- @foo@=`serial?`
Another variable: The value of another variable can be assigned. For example:
- @foo@=@bar@
Comparison expression: The value of a comparison can be assigned. For example:
- @foo@=(@bar@!="stop")
- @foo@=(@bar@<(@sam@/2))
Since the value of a comparison expression is a boolean type @foo@ will hold either the integer value 1 (true) or 0 (false). Note: the overall comparison expression MUST be enclosed in parentheses as shown for the assignment to work.
Logical expression: The value of a logical expression can be assigned. For example:
- @foo@=(@bar@&&!@sam@)
- @foo@=(@bar@&&(@sam@||(@scene@<5)))
Since the value of a logical expression is a boolean type @foo@ will hold either the integer value 1 (true) or 0 (false). Note: the overall logical expression MUST be enclosed in parentheses as shown for the assignment to work.

Variables as command arguments: Once variables are initialized, they can be directly assigned to some device property. For example:

First, initialize the variable in a macro:

@foo@={0,0,0,0}

and then somewhere else in the same macro, or in another macro...

outgn(*)=@foo@

The "argument" to the outgn command is now a variable name, rather than a literal integer array, such as {0,0,0,0}. Now the value of @foo@ can be controlled by one macro, and used by one or more other macros when setting the output gains. Variables can also be used within an integer array. For example:

First, initialize the variable in a macro:

@foo@=-3

and then somewhere else in the same macro, or in another macro...

outgn(*)={0,@foo@,0,0}

In this case the 2nd array element takes on the value of variable @foo@. Any or all of the array members may be represented by a variable.

Variables in command addresses: The value of a variable can be assigned to one or all of the "address" elements of command. For example:

First, initialize the variable in a macro:

@foo@=2

and then somewhere else in the same macro, or in another macro...

outgn(@foo@)=0

In this case the value of variable @foo@ determines which output channel is assigned a gain of 0. This is a powerful device control technique. Here's another example:

outgn(@foo@[2])=0

More on variable initialization: To prevent trouble with "uninitialized" variables shared between multiple macros, it is often a good idea to initialize them all at once in a macro that is guaranteed to run before any other macro. This is one of the purposes of the Run on Powerup macro, which provides a handy place for one-time variable initializations. It will be run exactly once, at powerup. For preset specific intializations, a Preset Run on Recall macro can be designated for each preset in the DM84. This macro will be run every time the preset is recalled.

Number of variables: The maximum number of variables that may be initialized in the DM84 is 32 .

Loops

A loop is the familiar "while-do" statement used to execute one or more instructions - based on the current value of a comparison, a logical expression, or a combination of both. This expression is the "condition" and MUST be enclosed in parentheses. The value of the condition is a boolean type, and whether or not the loop continues or terminates depends on whether the condition is "true" or "false". The "actions" are one or more DM84 simple commands or update commands, enclosed in '`' (backtick) characters. Multiple instructions MUST be separated by a ';' (semicolon) character. The special keywords "while" and "do" MUST be lowercase. For example:

while(@foo@<=10)do`ingn(@foo@)=0;@foo@=@foo@+1`
While @foo@ is less than or equal to 10, set the gain of input channel @foo@ to zero, then increment @foo@ and repeat. Terminate when the value of @foo@ is 11. The starting value of @foo@ has been set somewhere else.
@foo@=1;while(@foo@<=10)do`ingn(@foo@)=0;@foo@=@foo@+1`
Same as above except @foo@ is initialized on the same macro line as the loop instruction. Note the separating semicolon.
@foo@=ingn(@bar@);while (@foo@<0)do`@foo@=ingn(@bar@);@foo@=@foo@+1;ingn(@bar@)=@foo@`
Initalize @foo@ to the gain value for some input channel specified by @bar@. While this gain is less than zero, increment it by one. Terminate when the gain is zero.
@foo@=ingn(@bar@);while (@foo@<0&&@x@!=1)do`@foo@=ingn(@bar@);@foo@=@foo@+1;ingn(@bar@)=@foo@;@x@=prgin(3)`
Same as above - except that the loop terminates if programmable input 3 is asserted.

And so on. The maximum length of a DM84 command(s) supplied as the "action" is 63 characters. Commands given as an "action" of the loop MUST be enclosed within backtick characters - this is the character usually found on the same key as the tilde ('~'), in the upper left corner of your keyboard.

The use of loops allows device properties and variables that are arrays of values to be conveniently and efficiently accessed - a single loop instruction can replace many individual instructions.

Conditionals

A conditional is the familiar "if-then-else" statement used to control what happens - based on the current value of a comparison, a logical expression, or a combination of both. This expression is the "condition" and MUST be enclosed in parentheses. The value of the condition is a boolean type, and the action (if any) to be taken depends on whether the condition is "true" or "false". The "actions" are one or more DM84 simple commands or update commands, enclosed in '`' (backtick) characters. Multiple instructions MUST be separated by a ';' (semicolon) character. The special keywords "if", "then" and "else" MUST be lowercase. For example:

if (@foo@) then `run(3)`
If @foo@ is nonzero then run macro 3, otherwise do nothing.
@foo@=`actpre?`;if (@foo@ == 5) then `ingn(3)=0` else `ingn(3)=@bar@`
If preset 5 is active, then set channel 3 input gain to 0, otherwise set it to the value of @bar@. Variable @foo@ is initialized with the active preset number first.
if (@foo@||@bar) then `run(3)` else `outgn(*)={0,0,0,0}`
If @foo@ is nonzero or @bar@ is nonzero then run macro 3, otherwise set all output gains to 0.

And so on. The maximum length of a DM84 command(s) supplied as an "action" is 63 characters. Commands given as an "action" of the conditional MUST be enclosed within backtick characters - this is the character usually found on the same key as the tilde ('~'), in the upper left corner of your keyboard.

The use of conditional logic gives the macro language its power. Variables shared between macros can drive behavior that is adapted to current circumstances - which preset is active, the state of some programmable input, or the current value of a device setting like output gain or mute status.

Loops and Conditionals combined

Loops and conditionals may be combined (nested) in certain ways:

Conditional inside a loop instruction - for example:
while(@foo@<5)do`if(@bar@)then\`inmt(@foo@)=1\`else\`inmt(@foo@)=0\`;@foo@=@foo@+1;`
Loop inside a conditional instruction - for example:
if(@bar@)then`while(@foo@<5)do\`inmt(@foo@)=1;@foo@=@foo@+1\`else`exit`

Important: note that in both cases the "action" part of the "inner" instruction is treated specially - the backtick characters ('`') which enclose it need to be "escaped" with a backslash character ('\') since they are nested within another pair of backticks. This also applies to variable assignments made by invoking a built-in command - do this:

if(@foo@)then`@bar@=\`ingn(*)\``

NOT this:

if(@foo@)then`@bar@=`ingn(*)``.

Otherwise the macro processor will get confused about which backtick character goes with which.

No other combination is possible - loops may not be contained within another loop instruction, nor may a conditional be contained within another conditional instruction.