grandMA3 User Manual » Macros » Variables

Version 2.0

It is possible to create variables that can be used in macros or command line entries.

Variables are containers that can contain different kinds of content. The variable has a user-defined name that is written instead of the variable content. When the command is executed, the variable name is replaced with the variable content.

A variable can contain three different types of data:

• Integer: A signed whole number.
• Double: A signed fixed-point number with six decimals.
• Text: Any text string.

Signed numbers can be negative numbers, for instance, -7.

Variables are not strong-typed but typeless. This means an existing variable can be changed to contain a different type.

The name of a variable can be composed of any character. Variable names are case-sensitive.

	Hint:
	It is not a requirement, but avoiding spaces in variables is a good idea. Instead, consider using camelCase or PascalCase for variable names.

There are two different variable scopes. A scope defines who and where a variable can be used.

Variables can be scoped for the user, or they can be global variables.

User variables can only be seen and used by the user profile that creates them. Global variables can be seen and used by all users in the session.

---

SetGlobalVariable and SetUserVariable

Creating a variable is the same whether it is a user or global variable, but we use two different keywords to set one or the other: SetGlobalVariable or SetUserVariable.

This is the syntax:

SetGlobalVariable ["Variable_Name"] ["Content text with or without spaces"]

SetGlobalVariable ["Variable_Name"] [Integer or Double]

SetUserVariable ["Variable_Name"] ["Content text with or without spaces"]

SetUserVariable ["Variable_Name"] [Integer or Double]

	Important:
	The quotation marks are very important if the variable name contains spaces. If the name does not contain spaces, then they can be omitted. The same is true for text strings as the variable content. Variable content must be in quotation marks to ensure the software stores a text string.

Examples

User name[Fixture]>SetUserVariable MyFavoriteNumber 9

User name[Fixture]>SetUserVariable MyFavoriteText "9"

These two commands create two different variables that might seem to have the same content, but the first is a number, and the second is a text. So it is not because of the names but the quotation marks in the second example.

Single and Double Quotation Marks

It might be needed to store a variable with a text string that includes something in quotation marks. This presents an issue with how the software interprets the input and how it is interpreted when the variable is called during runtime.

The variable system supports single and double quote pairs.

This means that text strings can contain quoted text as long as the other quotation marks are used. 

Examples

Working with a specifically named group ("Spots Grid") in different contexts is necessary. A variable with "Group" and the name can be stored as a variable:

User name[Fixture]>SetUserVariable MySpecialGroup "Group 'Spots Grid' "

Notice the single quotes around the group name and the double quotes around the variable text string. These two pairs can be reversed for the same result.

Now the variable can be used to address the group:

User name[Fixture]>$MySpecialGroup At 80

Notice the $ sign before the variable name when using it. In this example, we placed the $ in front of the command so we can recall the variable. 

	Hint:
	To recall variables, place the $ in front of the command.

This is the software's reply:

The dollar sign and the variable name are replaced with the content of the variable.

GetGlobalVariable and GetUserVariable

The variables' content and type can be listed using the GetGlobalVariable or GetUserVariable keywords.

These keywords need to know what variable to show. The syntax is:

GetGlobalVariable ["Variable_Name"]

GetUserVariable ["Variable_Name"]

These commands show information about the variable name, content type, and content in the Command Line Feedback window.

They only show the variables in their scope. This means that the global version only shows global variables, and the user version only shows the user variables.

This assumes that the variable names are known.

The asterisk (*) wildcard can show all variables or a filtered list where a part of the name is known.

Examples

The current content of the variable called "MySpecialGroup" can be shown using this command:

User name[Fixture]>GetUserVariable MySpecialGroup

This is the feedback in the command line window:

The following example shows a list of all the global variables where the name contains the word "Our":

User name[Fixture]>GetUserVariable *ur*

The "O" is replaced with the asterisk to ensure the variables beginning with "Our" are also shown. The asterisk wildcard at the beginning defines that there must be additional letters in front of the letters we specify. In reality, the example will also show variables beginning with "Hour" or, in fact, anything with "ur" somewhere in the name. To specify variables starting with "Our," use the following example:

User name[Fixture]>GetUserVariable Our*

This example shows all the user variables:

User name[Fixture]>GetUserVariable *

Use Variables

Variables are used where the content of the variable is needed. 

	Important:
	To recall a variable, use $ in front of the command. To define the variable, use $ at the end of the command.

A $ (dollar sign) is placed in front of the name of the variable to instruct the software that the following is the name of a variable and that it should replace the sign and the name of the variable with the content of the variable.

If this result is not valid in the command, an error message will be shown in the command line feedback window.

The following variable was used in a previous example:

User name[Fixture]>$MySpecialGroup At 80

The variable's text string ("Group 'Spots Grid' ") replaces the $MySpecialGroup. This works because the variable contains a text string with commands.

	Important:
	Using quotation marks when using variables is essential and makes a difference.

If the variable is used with quotation marks:

User name[Fixture]>$"MySpecialGroup" At 80

It will fail because the content of the variable is explicitly called as a string, and the resulting feedback is:

The software tries to use the variable content as a text string and does not interpret it as a command.

This might be useful in other cases. The variable name must be in quotation marks when the variable contains a text string that should be used as text. See the example below.

Examples

This example uses a variable that contains a name of a group:

User name[Fixture]>SetUserVariable MyGroupName "Spots Grid"

Now this variable can be used where the text would be used otherwise as:

User name[Fixture]>Group $"MyGroupName" At 80

This command works. If the quotation marks are omitted, this will fail:

User name[Fixture]>Group $MyGroupName At 80

The text string is interpreted as a command.

DeleteGlobalVariable and DeleteUserVariable

Variables can be deleted using the DeleteGlobalVariable and DeleteUserVariable keywords.

This is the syntax:

DeleteGlobalVariable ["Variable_Name"]

DeleteUserVariable ["Variable_Name"]

	Important:
	Deleting a variable cannot be oopsed. There is not much else to say about deleting variables. When deleted, they do not exist anymore.

The name is needed to delete a specific variable, but the asterisk (*) wildcard can be used to delete a selection of variables.

Concatenate Variables

Variables can be concatenated by storing them into a new variable.

The desired result of the concatenation is to create a compound text string containing the concatenated variables. The output is always a text string. See below for the mathematical addition of number variables.

This is the syntax:

SetGlobalVariable [MyConcatResult] $[VariableName]$[VariableName]

SetUserVariable [MyConcatResult] $[VariableName]$[VariableName]

There must be no space between the variables that need to be concatenated or between any extra text that needs to be part of the concatenation.

Text can be added to the variable in quotation marks with no space between the end and start of quotation marks. However, there can be spaces inside the quotation marks. See the example below.

Examples

These examples use three variables:

Variable Name	Content Type	Content
MyInteger	Integer	9
MyKeyword	Text	Group
MyGroupName	Text	Perfect Macro

The goal is to concatenate these into a command string that can be used to store a group.

It can be done with one command but is split up to look at different functions here.

First, the keyword is combined with the integer into a new variable:

User name[Fixture]>SetUserVariable MyCommandString $"MyKeyword" "$"MyInteger"

There are a lot of quotation marks in this command. Setting the variable names in quotation marks ensures the variable content is interpreted as text. This also means that the integer variable is converted to a text string.

Furthermore, there is a " " between the two variables to add a space between them.

Show results using this command:

User name[Fixture]>GetUserVariable MyCommandString

Next add the macro name to the string:

User name[Fixture]>SetUserVariable MyCommandString $"MyCommandString" "$"MyGroupName"" "

Again, it can be hard to see what is happening. The two names of the variable are in quotation marks. Between the two are a space and a single quotation mark in double quotation marks. After the last variable name, there is another single quotation mark inside the double quotation marks.

The command looks like this without the double quotations:  SetUserVariable MyCommandString $MyCommandString '$MyGroupName'

The existing content of MyCommandString is added to MyCommandString, plus the content of MyGroupName in single quotations.

The result is that MyCommandString is Group 9 'Perfect Macro' as a text string.

Now some fixtures can be selected, and this command can be executed:

User name[Fixture]>Store $MyCommandString

And then, a group is stored at group 9 with the name. Quotation marks must not be used in the command above.

Variable Addition

Concatenating variables with integer and/or double types does a mathematical addition instead of an actual concatenation. Here there is no use of quotation marks.

The result needs to be stored in a variable.

Examples

This example uses three variables:

Variable Name	Content Type	Content
MyInteger	Integer	9
MySignedInteger	Integer	-2
MyDouble	Double	6.500000

The first two variables can be added to each other with this command:

User name[Fixture]>SetUserVar MyResult $MyInteger$MySignedInteger

The result can be seen by looking at the command line feedback. It shows that the variable is stored with a value of 7.

The double can be added with an integer. The result will be a double to avoid data loss.

User name[Fixture]>SetUserVar MyResult $MyInteger$MyDouble

This stores the value of 15.500000 in MyResult.

Type Conversion

Type conversion has been happening in the examples above.

An integer or double can be converted to text by putting the variable name in quotation marks. They will be converted when the command is executed.

Variables containing text that can be converted to an integer can be converted by setting the variable without quotation marks.

An integer can be converted to a double by adding it to a double with the value of 0.000000.

A double cannot be converted to an integer.

Examples

These examples use the following variables:

Variable Name:	Content Type:	Content:
MyInteger	Integer	9
MyEmptyDouble	Double	0.000000
MyText	Text	Hello

This example converts the integer to text:

User name[Fixture]>SetUserVariable MyInteger $"MyInteger"

Converting this back to an integer can be done with the following command:

User name[Fixture]>SetUserVariable MyInteger $MyInteger

Converting an integer to a double can be done using this command:

User name[Fixture]>SetUserVariable MyResultr $MyInteger"MyEmptyDouble