NVGate Macro

Tutorial

A macro is a powerful automation tool of NVGate allowing to create your own programs from a simple graphic interface, and don't require any software development skills.

In this section, we will create a macro that automatically restart the recording as soon as the measurement is stopped. To do so, add the channels into the recorder.

Creating a new Macro

Go in the "Tools" tab of the NVGate ribbon, and select "New" in the Macro section :

File:NewMacro.png

Add a parameter

This will open the Macro editor :

Our macro need to restart the recording as soon as it had been stopped. The macro need to loop as long as necessary, and the user must be able to stop the loop when needed. To do so, we will create a boolean parameter to control the loop. The loop will then iterate as long as this parameter is "True", and the user can change it to "False" to stop the loop and the Macro.

To create this parameter, right click on the name of the macro and select "Properties":

Then click on "Add", and define the Boolean parameter "EnableMacro" as follow:

Affectation

In order to control the Macro, we will must be able to change the value of "EnableMacro" from "True" to "False".

This can be done with an "affectation" on the Macro editor. An affectation being an Algorithmic command, it must be add from the "add an Algorithmic command" icon .

To create an affectation, select "End of Macro" and click on the icon. You need to select "End of Macro" because the affectation will come just before this line.
Select "Affectation" in the list and set it up as follow :

You can now change the value of "EnableMacro" by double-clicking on the Affectation command.

While Loop

In order to loop as long as needed, we will use a "while" loop that iterate as long as "EnableMacro" is set on "True".

The while loop is an Algorithmic command, and will be add the same way than the Affectation command. Click on "End of Macro", click on the icon and select "while loop. Than set the loop as follow :

If instruction

Inside the while loop, we need to test if the measurement has been stopped. An IF instruction can be used to perform such logical test. The IF instruction allow you to chose between two different actions to take regarding the current state of an event, or the value of parameter. Here, we will test if the event "Measurement is stopped" occurred.

To add the IF instruction inside the loop, select the "End while", open the Algorithmic list and select "If... Then...". Setup the If test as follow :

Add the Run Command

Now that the If test is setup, we only need to add the "Run" instruction inside the If test to have the macro re-starting the measurement as soon as it have been stopped. However, the "Run" command is not an Algorithmic, but an NVGate command.

To add NVGate command into the Macro, we will need to use "record off line" or "record on line" options. These icons will allow you to add one or serveral NVGate command in the macro by simply clicking on it. Once you added all the NVGate commands you want, you need to re-click on the "record on line" or "record off line" icon to stop the recording and validate the sequence.

The "record on line" command will add the NVGate command in the macro and execute it at the same time. By example, clicking on and then will add the "Run" command in the macro and start the acquisition in NVGate. Clicking on and then will add the "Run" command in the macro, but will not start the acquisition in NVGate.

To add the NVgate "Run" command into our macro, we don't need to actually start the acquisition in NVGate. To add it, select the "End if" line in the macro (because we wanr to ass the "Run" command before this line), click on [Image:RecrodOffLine.png]]. Then click on and re-click on to stop the recording of the command :

The complete Macro

Parameters of the Macros

Macros Tab

The macro Tab is used to create/manage macros that perform automatically recurrent operations...

Manage

Open the macro manager. Display the macro list and the associated hot-keys. A hot-key is a shortcut to run the macro.

Note that the three first hot keys are automatically assigned in the "Macro" menu from the OR38/OR36 Front Panel, labeled as "0", "1" and "2".

• Edit: Edits the macro selected. Available if no macro is being edited, recorded, or executed.
• New: Creates a new macro. The new macro is opened in the editor. Available if no macro is being edited, recorded, or executed.
• Delete: Deletes the macro selected.
• Run: Runs the macro selected. Available if no macro is being executed.
• Properties: Edits macro properties (name, read-only flag, and assigned hot-key). Available if no macro is being edited, recorded, or executed.

• Name: Changes the name of the macro.
• Read-only: If the macro is read-only, the macro can be loaded to the macro editor but can’t be modified.
• Hot key: Defines a hot-key to run the macro.
• Assigned macro: Macro associated with the hot-key selected in "Hot-key" combo-box. If hot-key selected is already assigned, a message is generated when the window is closed, requesting confirmation of the new assignment.

New

Creates a new macro and loads it in the macro editor. This menu is disabled if another macro is being edited.

• Properties : Opens a dialog box intended to edit macro properties. Macro properties consist of a set of parameters of different types, which can be used to define macro command properties.

This command is enabled if the macro item is selected in the macro tree.

• Add: Defines a new parameter.

• Name: name of the parameter
• Type: type of the parameter. The different types available are

Type	Description
Boolean	Parameter that can take only 2 values: True or False. This type of parameter is necessary for the MessageBox command to store the answer of the user. The parameter can then be tested in a "If...Then" command.
File name	Not used
Float	Parameter that can contain a decimal value (1.2, 1.12e6, -0.025, 5,-12387...). It is useful to store constant value that will be used in the macro for test condition ( If...then, While) or for other command (Wait, SetParamerValue ).
Integer	Parameter that contains an integer value (5, -1024, 6401). Behavior similar to the float parameter, it can be also used in loop commands ( For loop, periodic loop)
String	Parameter that contains a string of character. This type of parameter is useful to store constant string and to create string used by NVGate (Measurement name, Report template) or by commands (MessageBox, Trace). Several commands are dedicated to this string parameters ( MakeString, GetCurrentTime...)

• Value: default value of parameter
• Edit: Opens the "Parameter properties" dialog box, which is used to edit the parameter selected in parameters list. It is possible to change the name, the type, or the default value of the parameter. If the parameter is used by one or more macro commands, the type can’t be edited (the "Type" combo-box is disabled).
• Remove: Removes the selected parameter. If the parameter is used by one or more macro commands, the parameter is not removed and an error message is generated.

• Delete : Deletes the selected command in the macro tree. If the macro selected contains a set of commands (for example a loop command), a dialog box appears in order to confirm command removal. If removal is confirmed, the command and all commands it contains are deleted.

This command is enabled if the macro is not running and it is not read-only.

• Run : Runs the macro from the current command (indicated by execution pointer) to the next breakpoint. If no breakpoint follows, the execution goes to the end of the macro.

Enable if the macro is not running.

• Pause : Stops macro execution. The command running is completed, and then execution stops.

This command is enabled when the macro is running only.

• Step next : Runs current command (indicated by execution pointer).

This command is enabled when the macro is not running.

• Reset : If the macro is running, stops the execution, and then sets the execution pointer to the first command of the macro.
• Record on-line

Records commands in the macro. The record on-line mode applies the user actions. The commands corresponding to actions are recorded and inserted in the macro before the selected command.

This command is enabled if the macro is not running and it is not read-only.

• Record off-line : Records commands in the macro. The record off line mode applies the user actions only when the macro will start. The commands corresponding to actions are recorded and inserted in the macro before the selected command.

This command is enabled if the macro is not running and it is not read-only.

• Insert an algorithmic command : Inserts an algorithmic command before the selected command.

This command is enabled if the macro is not running and it is not read-only.

• Save : Saves the macro.

Save

Saves the macro currently edited. Only available if a macro is being edited.

Save As

Saves the macro currently edited with a new name. Only available if a macro is being edited.

Record

Start recording the user action on the software. Each recorded action is appended to the Macro and will be visible ine line in the macro editor.

Prior to start the macro recording user must enter the macro name and the recording mode:

• Macro name: Name of the macro.
• Recording mode:

Mode	Description
On-line	Commands corresponding to user actions are recorded in the macro.
Off-line	User actions have no effect. Commands corresponding to user actions are recorded in the macro.

Note: Click on the records button to stop recording the macro. The macro is saved with the name specified in the "Record" dialog.

Pause record

Pause the ongoing macro record. User actions are not yet recorded. Available if macro is being recorded.

Useful to prepare the system for an action to be recorded without fulfilling the editor with unwanted lines.

Stop run

Stops the execution of the running macro. Available if macro is running

Algorithmic commands

Affectation

File:Reports Tools Ribbons 80.png

Sets a value to a parameter. The new value can be defined by a parameter.

Break

File:Reports Tools Ribbons 81.png

Used to exit a loop. It can be used inside a "for" loop to stop before the end of the iteration, inside a "while" loop to exit the loop without fulfilling the condition. It is the only way to exit a "Periodic loop".

Call Macro

Calls another macro.

File:Reports Tools Ribbons 82.png

The only parameter is the name of the macro that is called. The body of the command is divided into three steps in order to exchange parameters between the calling macro and the called macro.

Comment

The purpose of this command is to facilitate understanding of the macro. It used to add a comment line to the body of the macro.

File:Reports Tools Ribbons 83.png

The only parameter is the comment

"For" loop

File:Reports Tools Ribbons 84.png

Runs a set of commands several times. The number of iterations can be defined by an integer value or by an integer parameter.

Get Current Time

This command retrieves the time and stores it in a string parameter. This string may be use to send a trace, to create a measurement name...

File:Reports Tools Ribbons 85.png

The "Time format" specifies the way in which the time should be written. "Date", "Time" and "Date and Time" use the regional settings of the host computer while the three other formats are fixed formats.

Get Macro Parameter

Gets the value of a parameter of a called macro. This command must be inserted between the "Exit macro" and the "Execute macro" commands, inside the body of the "Call Macro" command.

File:Reports Tools Ribbons 86.png

"Macro parameter" is the parameter of the calling macro that will receive the value of the parameter of the called macro.

"Parameter name" is the name of the parameter in the called macro.

In this example, the command gets the value of the parameter nNumberOfLoop of the macro CheckInput and sets this value to the parameter nCount of the calling macro.

Group

The purpose of this command is to facilitate understanding of the macro. It creates a branch that contains a set of instructions. It has no effect during execution, but it helps to organize the macro and facilitates copying and pasting, since all commands are copied at once.

File:Reports Tools Ribbons 88.png

If…Then…

File:Reports Tools Ribbons 90.png

Runs a set of commands according to a condition. The condition can depend on an event, status value or parameter. The event condition can be "event x occurred" or "event x not occurred".

There are five types of conditions:

• Event: The event can be "Measurement stopped", meaning that the analyzer went from "Running" to "Stopped" or "Measurement started", meaning the analyzer went from "Stopped" to "Running". This condition is used to wait for the end of a measurement, for instance.

• Status: All analyzer statuses can be used for this condition. Depending on the type of status, it is possible to compare its value to a list of possible values or perform a logical test ( ’=’, ’!=’,’<=’,’>=’) with a constant or a parameter.

• Parameter: The macro parameter of can be compared to a constant or to another parameter.

• Simple alarm: This condition is available only when at least one alarm on a simple template result has been declared.

• Alarm results

• Advanced alarm: This condition is available only when at least one alarm on a double template result has been declared.

• Advanced Alarm results

Operator	Test	Condition value for 1	Condition value for 2	Condition value for 3
=	Above max	False	False	False
!=	Above max	True	True	True
=	Cross max	False	False	True
!=	Cross max	True	True	False
=	Between min & max	False	False	False
!=	Between min & max	True	True	True
=	Cross min	True	False	False
!=	Cross min	False	True	True
=	Below min	False	False	False
!=	Below min	True	True	True
=	Cross min & max	False	True	False
!=	Cross min & max	True	False	True

Operator	Test	Condition value for 1	Condition value for 2	Condition value for 3
=	Above max	False	False	True
!=	Above max	True	True	False
=	Cross max	False	False	False
!=	Cross max	True	True	True
=	Between min & max	False	True	False
!=	Between min & max	True	False	True
=	Cross min	False	False	False
!=	Cross min	True	True	True
=	Below min	True	False	False
!=	Below min	False	True	True
=	Cross min & max	False	False	False
!=	Cross min & max	True	True	True

Incrementation

File:Reports Tools Ribbons 100.png

The increment command is used to increment the value of a macro parameter with a given offset.

The "Value" group-box allows defining the offset. The offset can be defined by a value or by a parameter of the same type as the parameter incremented.

Available if one or more integer or float parameter is defined.

Make String

Command used to create a string.

File:Reports Tools Ribbons 101.png

"Macro parameter" is the string that is modified. It can only be a String parameter.

"String to add" is the string that is added to the first parameter. It can be a constant or a parameter

"Add to existing string" is a Boolean parameter that indicates if the second parameter replaces or is added to first one. If the value is false, the command behaves like the Affectation command

Message box

File:Reports Tools Ribbons 102.png

Displays a dialog box, which is used to change the value of a Boolean parameter. The box is made up of a message and two buttons ("true" and "false"). It is possible to define the box caption, the message content and the button captions. A click on the "true" button sets the Boolean parameter to "true". A click on the "false" button sets the value to "false".

When the command is executed, the box is displayed. A click on one of the buttons closes the message box and sets the Boolean parameter value.

Periodic loop

File:Reports Tools Ribbons 103.png

Runs a set of commands at each interval of time specified in the "Time lap" parameter. The time lap is specified in seconds, the "Break" command must be used to exit the loop.

Set Macro parameter

Sets the parameter value of a called macro. This command must be inserted between the "Open macro" and the "Execute macro" commands, inside the body of the "Call Macro" command.

File:Reports Tools Ribbons 104.png

"Parameter name" is the name of the parameter in the called macro.

"Parameter value" is the value the parameter must take.

In this example, the command sets the value of the parameter InputNumber of the macro CheckInput to 4.

When the macro is running, a dialog box is displayed, which is used to change the value of a parameter.

File:Reports Tools Ribbons 107.png

The message generated in the top of the dialog box can be defined in the "command properties". A control is used to edit the parameter value. A click on the OK button changes the parameter value, and closes the dialog box. A click on the Cancel button closes the dialog box without changing parameter value.

Set Parameter Value

File:Reports Tools Ribbons 108.png

Trace

Command used to send a message in the log window.

File:Reports Tools Ribbons 109.png

"Message" is the text that is displayed in the log window.

"Play sound" is used to play a sound when the message is sent. The host computer must have speakers connected.

Wait

File:Reports Tools Ribbons 110.png

Waits for a given time. The wait time is specified in seconds.

"While" loop

File:Reports Tools Ribbons 111.png

Runs a set of commands several times until the condition is false. The condition can depend on an event, status value or parameter. The event condition can be "event x occurred" or "event x not occurred".

There are five types of conditions:

• Event: The event can be "Measurement stopped", meaning that the analyzer went from "Running" to "Stopped" or "Measurement started", meaning the analyzer went from "Stopped" to "Running". This condition is used to wait for the end of a measurement, for instance.

• Status: All analyzer statuses can be used for this condition. Depending on the type of status, it is possible to compare its value to a list of possible values or perform a logical test ( ’=’, ’!=’,’<=’,’>=’) with a constant or a parameter.

• Parameter: The macro parameter of can be compared to a constant or to another parameter.

• Simple alarm: This condition is available only when at least one alarm on a simple template result has been declared.

• Advanced alarm: This condition is available only when at least one alarm on a double template result has been declared.

	Operator Test Condition value for 1 Condition value for 2 Condition value for 3 = Above max False False False != Above max True True True = Cross max False False True != Cross max True True False = Between min & max False False False != Between min & max True True True = Cross min True False False != Cross min False True True = Below min False False False != Below min True True True = Cross min & max False True False != Cross min & max True False True
	Operator Test Condition value for 1 Condition value for 2 Condition value for 3 = Above max False False True != Above max True True False = Cross max False False False != Cross max True True True = Between min & max False True False != Between min & max True False True = Cross min False False False != Cross min True True True = Below min True False False != Below min False True True = Cross min & max False False False != Cross min & max True True True

Editor contextual menu

Setting properties

• Cut: Removes the command selected and copies it to the clipboard.
• Copy: Copies the command selected in the clipboard.
• Paste: Inserts the command stored in the clipboard into the macro. The command will be inserted before the command selected.

If the item selected in the macro tree is an "end of loop" item, the command will be inserted at the end of the loop body.

If the item selected in the macro tree is the "end of macro" item, the command will be inserted at the end of the macro.

• Delete: Deletes the command selected. Available if the item selected in the macro tree is a command item (not "end of loop" or "end of macro item).
• Toggle break point

If a breakpoint is put on the command selected, this command removes it. Otherwise, it sets a breakpoint for this command. Only available if the item selected is a command item.

Breakpoint has been set. This command is not executed.

During macro execution (see Run button), the execution stops on the first command where a toggle break point is placed.

• Run to: Runs the macro from the current command (indicated by execution pointer) to the selected command, ignoring breakpoints. The selected command is not executed. If the current command is after the selected command, execution goes to the end of the macro, ignoring breakpoints.
• Jump to: Sets execution pointer to the selected command.
• Properties

Edits command properties.