Using Variables and Properties

You can create and use variables and properties and monitor the values of the variables and properties.

You can define the following types of variables to share data among steps of a sequence or among several sequences:

• Local variables store data relevant to only the current sequence. Only steps within the sequence that defines the local variable can access these variables.
• Sequence file global variables store data relevant to the entire sequence file. Each sequence and step in the sequence file can directly access these global variables.
• Station global variables persist across different executions. The TestStand Engine maintains the value of station global variables in a file on the computer on which TestStand is running.

In the sequence editor, the Variables pane displays all the variables and properties the selected sequence can access at run time. In the Execution window, the Variables pane displays the sequence context for the sequence invocation currently selected on the Call Stack pane. The sequence context contains all the variables and properties the steps in the selected sequence invocation can access. Use the Variables pane to examine and modify the values of these variables and properties when the sequence is in a suspended state, such as when paused at a breakpoint.

Creating Local Variables

Complete the following steps to create and use local variables. You can apply the concepts you learn in this tutorial to sequence file global and station global variables.

1. Open <TestStand Public>\Tutorial\Computer2.seq, which you created in Editing Steps in a Sequence.
2. Select File»Save <filename> As and save the sequence file as Computer4.seq in the <TestStand Public>\Tutorial directory.
3. Click the Variables pane in the Sequence File window. Expand the Locals item to view the local variables currently defined for MainSequence. Each sequence includes a ResultList local variable, which is an empty array of container properties. TestStand uses this variable to store step results for result processing.
4. On the Variables pane, right-click Locals, select Insert Local»Number from the context menu to insert a new numeric local variable, and rename the local variable LoopIndex.
5. Complete the following steps to insert and configure a For step.
   1. Click the Steps pane in the Sequence File window and insert a Flow Control»For step below the Retry Power On step. Notice that TestStand also adds an End step below the For step.
   2. Drag the End step below the RAM step. TestStand automatically indents the Retry Power On, CPU Test, ROM, and RAM steps between the For and End steps.
   3. Click the For step and click the For Loop tab of the Step Settings pane.
   4. Enter 5 in the Number of Loops control.
   5. For the Loop Variable control, click the Expression Browser button to launch the Expression Browser dialog box, in which you can interactively build an expression by selecting from lists of variables, properties, operators, functions, and the TestStand API. TestStand supports all applicable expression operators and syntax you can use in C, C++, Java, and Visual Basic .NET. You can also call the TestStand API directly from within expressions. All TestStand controls that accept expressions provide context-sensitive editing features, such as drop-down lists, syntax checking, and expression coloring to help you create expressions. At any point while editing an expression, you can press <Ctrl-Space> to show a drop-down list of valid expression elements.
   6. Expand the Locals item on the Variables/Properties tab of the Expression Browser dialog box. Each item in the top section of the Variables/Properties tab is a property or variable of TestStand.
   7. Select the LoopIndex variable under the Locals property and click the Insert button. The Expression Browser enters Locals.LoopIndex in the Expression control.
      Note To refer to a subproperty, use a period to separate the name of the property from the name of the subproperty. For example, reference the LoopIndex subproperty of the Locals property as Locals.LoopIndex.
   8. Click the Check Expression for Errors button to verify that the expression contains valid syntax.
   9. In the Expression Browser dialog box, click OK to return to the For Loop tab of the Step Settings pane. The Loop Variable control now contains the Locals.LoopIndex expression. Notice that the Custom Loop section shows the expressions TestStand uses when executing the For step when using a fixed number of loops.
6. Select Execute»Break on First Step to remove the checkmark that appears to the left of the menu item and disable this option, which you enabled in the Step Mode Execution section of Debugging Sequences.
7. Save the changes and select Execute»Single Pass.
8. Click Done in the Test Simulator dialog box.
9. After the sequence executes, review the test report, which shows that TestStand executed the steps within the loop (Retry Power On, CPU Test, ROM, and RAM) five times.
10. Close the Execution window. Leave the sequence file open for the next tutorial.

Using the Execution Window Variables Pane

Before executing the steps in a sequence, TestStand creates a run-time copy of the sequence to maintain separate local variable and step property values for each sequence invocation. When an execution completes, TestStand discards the run-time sequence copy.

For each active sequence, TestStand maintains a sequence context that contains references to the run-time copy of the sequence so you can access all the objects, variables, and properties that relate to the execution of the sequence.

The contents of the sequence context vary depending on the currently executing sequence and step, the location of the active sequence in the call stack, and the identity of the execution in which the active sequence resides. Depending on the current state of execution, sequence context subproperties might not exist. When a property exists, the contents of the property can vary.

The Variables pane displays the sequence context for the sequence invocation currently selected on the Call Stack pane. The sequence context contains all the variables and properties the steps in the selected sequence invocation can access. Use the Variables pane to examine and modify the values of these variables and properties when the sequence is in a suspended state, such as when paused at a breakpoint.

Complete the following steps to use the Variables pane of the Execution window to examine the value of the LoopIndex variable while TestStand executes the Computer4.seq sequence file you created in the previous tutorial.

1. Insert a breakpoint at the End step associated with the For loop you created in the previous tutorial.
2. Select Execute»Single Pass.
3. Click Done in the Test Simulator dialog box. The execution suspends on the End step.
4. Click the tab for the Variables pane of the Execution window and expand the Locals section.
5. Select the LoopIndex property. The numeric value of LoopIndex is 0.
6. Click the tab for the Steps pane of the Execution window and click the Resume button on the Debug toolbar. The execution resumes and suspends at the End step again.
7. Click the tab for the Variables pane again. The value of Locals.LoopIndex is now 1. Leave the execution in the suspended state for the next tutorial.

Docking the Variables Pane

The sequence editor contains tabbed windows and panes you can float, dock, resize, and hide. Some panes, such as the Variables pane, must stay attached to the associated Sequence File or Execution window.

Complete the following steps to display the Steps and Variables panes at the same time.

1. In the Execution window, click the tab for the Variables pane and drag it to the right using the tab, not the title bar. As you drag the pane from the current location, the sequence editor detaches the pane and displays docking guides. The docking guides show you where you can place the pane. As you move the mouse over a docking guide, the sequence editor highlights where the pane will relocate when dropped.
2. Drop the pane on the right-most docking guide, so the pane appears to the right of the Steps panes.
3. Click the tab for the Steps pane and click the Resume button on the Debug toolbar. The execution resumes and suspends at the End step again. The value of Locals.LoopIndex on the Variables pane is now 2.
4. Drag the title bar of the Variables pane and drop it on the center docking guide, to return the Variables pane to the previous location. Notice that the tab for the Variables pane now appears to the left of the tab for the Steps pane instead of to the right.
5. Click the tab for the Variables pane, drag it to the right, and drop it on the Steps pane tab to adjust the order of the tabs. Leave the execution in the suspended state for the next tutorial.
   Note Select View»Reset UI Configuration at any time to restore the panes to the original state.

Using the Watch View Pane

The Watch View pane of the Execution window displays the values of watch expressions you enter. The values in the Watch View pane update when execution suspends at a breakpoint. When you enable tracing, the sequence editor also updates the values after each step executes. The Watch View pane highlights viewed and changed watch expression values in red text.

Enter watch expressions to monitor values of variables and properties as you trace or step through a sequence. You can drag individual variables or properties from the Variables pane to the Watch View pane. When you specify a container property, array property, or a PropertyObject reference as a watch expression, you can use the Watch View pane to expand the subproperties to view the values.

Complete the following steps to create a watch expression that uses the LoopIndex property.

1. Select the LoopIndex property on the Variables pane of the Execution window and drag the property to the Watch View pane. The value of the LoopIndexwatch expression is 2.
2. Edit the LoopIndex watch expression directly in the Watch Expression column on the Watch View pane to change the expression to the following:

   Str (Locals.LoopIndex * 20) + "%"

3. Click the tab for the Steps pane of the Execution window and click the Resume button on the Debug toolbar. The execution resumes and suspends at the End step again. The value of the watch expression changes from 40% to 60%.
   Note The watch expression pane might display an Error in argument message before displaying 60% because the watch expression is not valid during a subsequence execution.
4. Click the breakpoint icon to the left of the End step in the Execution window to remove the breakpoint.
5. Resume and complete the execution.
6. Close the Execution window.
7. Select Debug»Breakpoints/Watches to launch the Edit Breakpoints/Watch Expressions dialog box, in which you can review and edit the breakpoints and watch expressions associated with the current workspace. TestStand saves and reloads breakpoints and watch expressions using an options file associated with the current workspace or a default options file when no workspace is loaded.
8. Review the contents of the Breakpoints and Watch Expressions tabs in the Edit Breakpoints/Watch Expressions dialog box, delete the breakpoint and expression you created for this tutorial, and click Done to close the dialog box.
9. Close the sequence file.