Create a TestStand Array Programmatically

There are few methods to programmatically create an array in TestStand. In this article, we will look into the methods in detail.

There are three main ways to programmatically create a TestStand array.

1. Cloning an Existing Array
2. Creating a new Array Object
3. Using PropertyObject.NewSubProperty

All of them require using the TestStand API to insert the array as a TestStand variable (i.e. Local, Parameter, FileGlobal, StationGlobal) or as a property (e.g. step property).
 

1. Cloning an Existing Array
   If you have an existing array, you can clone it and then insert the clone as a Property Object. The new array will be identical to the original array (i.e. same type, size and values). You can then modify the contents of the new array if needed. Use the following TestStand API methods to accomplish this:
   
   a) PropertyObject.Clone
   This method creates a copy of the property that you specify in the lookupString parameter. The return value is a PropertyObject object which you will use in the PropertyObject.SetPropertyObject() method, described below, to insert your new array.
   
   b) PropertyObject.SetPropertyObject
   Use this method with its Options parameter set to 1 (InsertIfMissing) and pass the PropertyObject reference you got with the PropertyObject.Clone() method, described above, as the newValue parameter. The name of your new array can be set in the lookupString parameter.
   
   Example:
   Locals.SetPropertyObject("myNewArray", 1, Locals.myCurrentArray.Clone("", 0))

 

2. Creating a new Array Object
   This method creates a brand new array object that you can then insert as a regular array. The new array will be empty (zero elements) but you can then resize it and modify its contents as you would do with any array. Use the following TestStand API methods to accomplish this:
   
   a) Engine.NewPropertyObject
   This method creates and returns a new PropertyObject object which you will use in the PropertyObject.SetPropertyObject method, described below, to insert your new array. The method has the following prototype:
   
   Engine.NewPropertyObject(valueType, asArray, typeName, options)
   
   Notice that the second parameter is a Boolean flag that allows you to specify that the Property Object you just created is an array. You can specify the type of the new array in the valueType parameter.
   
   b) PropertyObject.SetPropertyObject
   Use this method with its options parameter set to 1 (InsertIfMissing) and pass the PropertyObject reference you got with the Engine.NewPropertyObject method, described above, as the newValue parameter. The name of your new array can be set in the lookupString parameter.
   
   Example:
   Locals.SetPropertyObject("myNewArray", 1, RunState.Engine.NewPropertyObject(PropValType_Number, True, "", 0))

 

3. Using PropertyObject.NewSubProperty

This TestStand API method creates a new subproperty with the name specified by the lookupString parameter. The method has the following prototype:

PropertyObject.NewSubProperty(lookupString, valueType, asArray, typeName, options) 

Notice that the third parameter is a Boolean flag that allows you to specify that the subproperty you are creating will be an array. You can specify the type of the new array in the valueType parameter and its name in the lookupString parameter. The new array will be empty (zero elements) but you can then resize it and modify its contents as you would do with any array. 

One way to specify the size of the array is to use the SetNumElements() method. This method has the following prototype:
PropertyObject.SetNumElements(numElements, options)
 
Example:
Locals.NewSubProperty("myNewArray", PropValType_Number, True, "", 0), #NoValidation(Locals.myNewArray.SetNumElements(10, 0))
 
Dynamically creating a zero-initialized two-dimensional array can be done by adding the SetArrayBounds() method:

Locals.SetPropertyObject("newArray", 1, RunState.Engine.NewPropertyObject(3, True, "", 0)), SetArrayBounds(#NoValidation(Locals.newArray), "[0][0]", "[2][2]")

Additional Information

For detailed information about these TestStand API methods, please refer to the Teststand Help. To access the help, open the TestStand Sequence Editor and select Help»TestStand Help. All of the TestStand API methods are available to any programming language that supports ActiveX programming.

You can also check the Example program linked below for the implementation of these methods.