Importing and Exporting Arrays in TestStand

With the introduction of TestStand 2.0, and the ability to export Local variables, new features were added to the Import/Export Properties Tool allowing it to store advanced data types like containers and arrays. Using the Import/Export Properties Tool to export an array to a file or using the Property Loader step type with an external file can be a powerful programming asset, but is not always as intuitive as exporting Numeric or String properties.

Implementation: Creating Variables of Complex Types

In order to export an array to a file, begin as you would with any property by opening the sequence with the values you need and select Tools>>Import/Export Properties Tool from the menu bar.

The following illustration is a view of the local variables defined for our example sequence. There are a variety of types shown, ranging from the String (Locals.Day); to an Array of Strings (Locals.DaysOfWeek); to an Array of Type Fruit (Locals.FruitOnSale), which is an array of containers; and an Array of Type Store (Locals.TwoDayStock), which is also an array of arrays of containers. All of these items and more can be exported using the Import/Export Properties Tool in TestStand 2.0 or later.


[+] Enlarge Image

Implementation: Navigating the Properties Tab

Use the Source/Destination tab of the Import/Export Properties dialog box to specify the file to which you will write your property values. You can also select various formatting options. The Properties tab determines which properties are sent. Here, you will populate your text file with values to be loaded at run-time.

In the previous image, note how data types, such as the String type of Locals.Day, are displayed and how you can select them from the Available list. Arrays of containers are pre-flattened to their sub-elements by the Import/Export Properties Tool, so they too are easy to interpret and select. Notice how Locals.FruitOnSale, which is an array of containers, has been broken down so that it lists each element of the container per-array index.


[+] Enlarge Image

Since you select each element of a container individually, there is no way to select an entire array or container at once in just one property selection. When exporting the container variable Locals.TodaysFruit, you must pass each of the sub-elements in turn. When exporting the array variable Locals.DaysOfWeek you must select each array index individually.


[+] Enlarge Image

Implementation: Selecting Arrays

To specify which index you would like to export, select the array as if it were a simple data type. Once you have added it to the Selected list by clicking the > or >> button, it has a ? placeholder where its index should be. Highlighting the array will activate the Property Name field beneath the property list and allow you to replace the question mark with a relevant numeric value. Remember that arrays in TestStand are indexed starting from zero by default.

Since the Import/Export Properties Tool is used while the sequence is inactive, it cannot anticipate how many elements will be in your array. You may choose to enter each array index using this screen or to manually adjust the text file after you successfully export. Continue to add new indexes to your text file by completing the following:

1. Reselect your array from the Available list.
2. Add the selected array to the Selected list.
3. Specify a set index in the Property Name editing field.

Your end results should resemble the following illustration:

[+] Enlarge Image

Implementation: Working with Your Exported File

Once you have selected all the properties you wish to have TestStand export, click Export to generate the file. If you choose to generate a basic tab-delimited text file it may look something like the following illustration:



Notice that if we were to reload this file at run-time using a Property Loader step, it would only overwrite the container at position zero of the Locals.FruitOnSale array. The rest of the indexes would remain unchanged. If you need to edit other indexes, you could edit this text file to include three more lines per array index to specify the new values of Color, Name, and Price for each of the containers.

When you configure your Property Loader step in the sequence, carefully apply the same logic when you specify properties for your destination arrays as you did for the export fields. Each index will have to be specified in order to receive the correct values from the file.

As an additional note, you cannot export any array or container that is flagged as empty. If your array has zero elements, or your container has no fields, it is not considered export-ready and will be ignored by the Import/Export Properties Tool.

Reader Comments | Submit a comment »