TestStand API Reference

TestStand 2019 Help

Edition Date: May 2019

Part Number: 370052AA-01

»View Product Info
Download Help (Windows Only)
Object and Description
Adapter
Use Adapter objects to configure and obtain information about the module adapters. Typically, you use this class only when you write a user interface application or sequence editor.
Note  If you are considering writing a user interface application, National Instruments recommends using the TestStand User Interface (UI) Controls instead of writing the application using the TestStand Engine API.
To obtain an Adapter object, call the Engine.GetAdapter method. Pass a zero-based index to specify the Adapter object for which you want to obtain a reference. To find out the number of available adapters, obtain the value of the Engine.NumAdapters property.
AdditionalResult
An AdditionalResult specifies additional data to add to the result list when a step executes. An AdditionalResult can be an arbitrary piece of data or the value of a module parameter. An AdditionalResult is a member of the Step.AdditionalResults.ParameterResults collection, the Step.AdditionalResults.CustomResults collection, or the AdditionalResult.Elements collection.
AdditionalResults
This class represents a collection of AdditionalResult objects. Use the Step.AdditionalResults.ParameterResults, Step.AdditionalResults.CustomResults, or AdditionalResult.Elements properties to obtain an AdditionalResults collection.
ArrayDimensions
Use the ArrayDimensions class to obtain and set array bounds information for a PropertyObject. Use the PropertyObjectType.ArrayDimensions property to obtain an instance of this class.
CodeTemplate
Use this interface to obtain information about a code template. Code templates are associated with adapters and represent the default code that modules use when creating code for an instance of a step type. Use the StepType.CodeTemplates property to obtain a collection of CodeTemplate objects associated with a step type.
CodeTemplates
A collection of CodeTemplate objects. Code templates are associated with adapters and represent the default code that modules use when creating code for an instance of a step type. Use the StepType.CodeTemplates property to obtain a collection of CodeTemplate objects associated with a step type.
CsvFileInputRecordStream
CsvFileOutputRecordStream
EditArgs
Use objects of the EditArgs class to pass information about the current state of the user interface to methods such as Engine.NewExecution, Sequence.EvalEntryPointNameExpressionEx, Engine.GetEditTimeToolMenuItems, and Engine.GetRunTimeToolMenuItems. Objects of this class contain information about currently selected sequences, steps, sequence files, and executions. This selection information appears in the RunState.InitialSelection property of the sequence context. Create objects of this class using the Engine.NewEditArgs method. Typically, you use this class only when you are writing a user interface or sequence editor.
EditTimeMenuItem
Objects of the EditTimeMenuItem class represent menu items in the sequence editor or user interface. A menu item is a command, a call to a sequence, a submenu, or a submenu of calls to sequences in a sequence file. EditTimeMenuItem objects specify the menu item type, which includes paths and arguments for commands, paths for sequence files, and names of sequences. Each object specifies an expression for evaluating item text at run time, and expressions that determine whether the item is enabled or visible at run time. Use the Engine.GetEditTimeToolMenuItems method to obtain a reference to a collection of EditTimeMenuItem objects for the TestStand Tools menu. Use this collection to customize the contents of the Tools menu. Use the Engine.GetRunTimeToolMenuItems method to obtain a reference to a collection of RunTimeMenuItem objects, which represent an evaluated version of the Tools menu. Use this collection to determine what is displayed in the Tools menu at run time.
EditTimeMenuItems
The EditTimeMenuItems class specifies a collection of EditTimeMenuItem objects. An EditTimeMenuItem object represents a menu item such as a command, a call to a sequence, a submenu, or a submenu of calls to sequence in a sequence file. Each object in the collection specifies the menu item type and the expressions which determine the item text, hidden state, and enabled state. A submenu item specifies a collection of menu items in the submenu. Use the Engine.GetEditTimeToolMenuItems method to obtain a reference to a collection of this class for the Tools menu. Use this collection to customize the contents of the Tools menu.
Engine
Use the Engine class to create and access objects of other classes, control executions, launch built-in dialog boxes, implement a Tools menu, find files and directories, and invoke various utilities. Create the Engine object directly using ActiveX. To access the Engine object from a step, use the TestStand API to obtain the value of the Engine property from the SequenceContext or pass the SequenceContext property RunState.Engine as an object parameter to the step. The following are examples of creating the initial Engine object:

LabWindows/CVI
CAObjHandle engineObj = 0;
TS_NewEngine(NULL, &engineObj);

Visual Basic
'Place the TestStand Engine ActiveX control on the main form.

Visual C/C++
#import "C:\TestStand\Bin\teapi.dll"
TS::IEnginePtr engine;
HRESULT hr = engine.CreateInstance(__uuidof(TS::Engine));
EngineEnvironment
EngineInitializationSettings
EngineInitializer
EvaluationTypes
This interface specifies expected types for evaluating an expression. Obtain an EvaluationTypes object by calling the Engine.NewEvaluationTypes method or through a property of a parameter for a module call such as the LabVIEWParameter.ValidEvaluationTypes property. Pass an instance of EvaluationTypes to the Expression.ValidateEvaluationType method to perform type checking on an expression.
Execution
An execution is an object TestStand creates to contain all the information it uses to run the sequences and subsequences it calls. Use objects of this class to control and get information about executions. For example, you can use methods to suspend, resume, or terminate execution, and you can use properties to determine whether the execution is an interactive execution or whether the execution is in the process of terminating.
ExecutionOutputRecordStream
ExecutionOutputRecordStreams
Expression
An Expression object holds an expression string. You can check the validity of the expression string or you can evaluate the expression string to obtain the result of the expression. The Expression object provides the same functionality as the PropertyObject.EvaluateEx, Engine.CheckExpression, and Engine.CheckExprSyntax methods. However, if you are repeatedly evaluating the same expression, it is more efficient to use an Expression object because it only parses the expression string when you first evaluate the expression. Because the Expression object retains the parsed form of the expression, it does not re-parse the expression when you reevaluate the same string. The Expression object also provides the NumTokens property and the Tokenize and GetToken methods, which you can use to identify the operators, identifiers, and constants that comprise an expression. The capability to parse the expression into component tokens is useful for specialized purposes, such as implementing expression syntax coloring. Because TestStand provides an ActiveX Expression control that features syntax coloring, you typically do not need to identify the tokens in an expression.
ExternalReportViewer
An ExternalReportViewer represents relationships between a specific report format and the application used to open it. TestStand keeps a list of report viewers. If you do not specify an external viewer for a format, the file opens in the application Microsoft Windows associates with the file extension of the report file.
Note  You must have a minimum supported version of Microsoft Internet Explorer or later to view TestStand reports. Refer to the NI TestStand Readme for more information about supported versions of Internet Explorer.
ExternalReportViewers
Collection that contains elements using the ExternalReportViewer type. Represents the list of external report viewers used to open the different report file types TestStand supports.
Note  You must have a minimum supported version of Microsoft Internet Explorer or later to view TestStand reports. Refer to the NI TestStand Readme for more information about supported versions of Internet Explorer.
FileInformation
Use FileInformation objects to obtain file information, such as file version, file format version, and file type, on files TestStand recognizes without fully loading the files into memory. When you call methods and properties on a FileInformation object, TestStand can cache the information. For changes made to a file on disk to be reflected in a FileInformation object, you must release the object and use the Engine.GetFileInformation method to obtain a new FileInformation object.
Images
This collection class contains objects of the Picture data type. Use the Engine.Images property to acquire the collection object. The collection specifies the images TestStand loads from the <TestStand>\Components\Icons and <TestStand Public>\Components\Icons directories and images you add using the Engine.AddImage method. Use the Images.FindImage method to find an image using an image name. Use the Images collection as an alternative to using the Engine.LargeImageListEx and Engine.SmallImageListEx properties.
InputRecordStream
InputStream
Objects of the InputStream class represent an abstract stream of data. In a sequence file translator, this stream reads the content of a user file. The InputStream class allows the translators to read, seek, and query the size of a file. You cannot create an InputStream object externally, and you can obtain a reference only in the DLL interface exposed to a sequence file translator. The TestStand Engine creates an InputStream object and passes the object to various callbacks in the DLL interface.
InteractiveArgs
When you call the Engine.NewExecution or Thread.DoInteractiveExecution methods to create an interactive execution, use an object of this class to pass information about the current state of the user interface. These methods use the object to determine which steps are currently selected in the user interface. Create objects for this class using the Engine.NewInteractiveArgs method.
InteractiveContext
Use objects of this class to obtain additional information about a currently executing interactive execution. Obtain objects of this class using the SequenceContext.InteractiveContext property of the sequence context in which the interactive execution began.
Location
The properties of a Location object contain enough information for a user interface to find a specific piece of data the user interface displays.
Locations
Locations is a collection of Location objects. Use Locations to instruct the user interface to update the selection. Follow these steps to set the selection in a user interface:
Module
Use objects from the module class to specify and obtain information about code modules that steps or step type substeps execute. Typically, you use this class only when you write a sequence editor. To obtain a Module object, use the Step.Module property. To access the properties and methods of an adapter-specific module class, query the Module object for the interface of the adapter-specific module interface you want.
OutputMessage
An OutputMessage object specifies the details about an output message. The object lets you specify the message text, timestamp, category, severity, color, icon, and location. When you call the OutputMessage.Post method, TestStand copies the OutputMessage object and adds the copy to the collection TestStand maintains. You can access the collection using the reference the Engine.GetOutputMessages method returns.
OutputMessages
This collection class contains elements of the OutputMessage type. You can post an output message to TestStand by calling the Engine.NewOutputMessage method to create a new message object and by calling the OutputMessage.Post method on the object. You can also call the OutputMessage expression function. When the number of items in the collection changes from zero to one, TestStand sends a UIMsg_OutputMessages message to the TestStand application. TestStand adds only messages to the collection and sends a UIMsg_OutputMessages message if you enable the Engine.OutputMessagesEnabled property. An application can retrieve the latest output messages by transferring messages from the collection TestStand maintains to a new collection the application creates, as shown in the following pseudocode:
// C# example
if (uiMsg.Event == UIMessageCodes.UIMsg_OutputMessages)
{
     OutputMessages outputMessages = uiMsg.ActiveXData as OutputMessages;
     OutputMessages appOutputMessages = engine.NewOutputMessages();
     outputMessages.CopyMessagesToCollection(appOutputMessages);
     for(i = 0; i < appOutputMessages.Count; i++)
     {
          uiControl.Add(appOutputMessages[i].Message);
     }
}
// C++ example
if (uiMsg->Event == UIMsg_OutputMessages)
{
     TS::OutputMessagesPtr outputMessages = uiMsg->ActiveXData;
     TS::OutputMessagesPtr appOutputMessages = engine->NewOutputMessages();
     outputMessages->CopyMessagesToCollection(appOutputMessages);
     for(i = 0; i < appOutputMessages->Count; i++)
     {
          uiControl.Add(appOutputMessages->Item[i]->Message);
     }
}

TestStand always sends output messages to a debugger if you enable the DebugOptions_SendOutputMessagesToDebugger option of the StationOptions.DebugOptions property.
OutputRecordStream
PropertyObject
Use the PropertyObject class to manipulate and access the values of variables and custom step properties. You can also use the PropertyObject to add, copy, or delete subproperties of variables and custom step properties. You can create new objects of this class using the Engine.NewPropertyObject method. You can obtain existing objects of this class as return values from numerous functions. You can obtain the underlying PropertyObject for objects of every class except the Engine class by using the AsPropertyObject method of the respective class.
PropertyObjectFile
Use the PropertyObjectFile class to read and write PropertyObjects to disk. All TestStand files, including sequence files, type palette files, workspace files, configuration files, users file, and globals file, are stored as PropertyObjectFiles. Create new PropertyObjectFiles with the Engine.NewPropertyObjectFile method.
PropertyObjectType
Use the PropertyObjectType class to obtain type information for a PropertyObject. Use the PropertyObject.Type property or the Engine.NewPropertyObjectType method to obtain an instance of this class.
Report
Use objects of the Report class to modify, save, load, retrieve, and view reports. To obtain the Report object for an execution, retrieve the value of the Execution.Report property. Usually, the process model updates the Report object associated with the execution, and the sequence editor or user interface displays it.
Note  You must have a minimum supported version of Microsoft Internet Explorer or later to view TestStand reports. Refer to the NI TestStand Readme for more information about supported versions of Internet Explorer.
Reports
This class is a collection of Report objects.
ReportSection
Use objects of this class to store, update, and transfer reports. You typically use ReportSection objects to avoid creating copies of a report as the report is transferred between the report generator, process models, Report object, and ReportView control. You can create a new ReportSection object by calling the Report.NewReportSection method. ReportSection objects can contain other ReportSection objects. Typically, a process model creates and updates the ReportSection object and assigns it to the Report object by setting the Report.ReportSection property.
ReportSections
This class is a collection of ReportSection objects. The collection contains a list of ReportSection objects that are children of the ReportSection object from which the ReportSections object was obtained.
ResultLog
ResultLog objects read TestStand results from a file that a ResultLogger object creates.
ResultLogger
ResultLogger objects write TestStand results to a file. Use a ResultLog object to read the results from the file.
RunTimeMenuItem
Objects of the RunTimeMenuItem class represent an evaluated version of a EditTimeMenuItem object. The properties of the RunTimeMenuItem object specify the item text, if the menu item is disabled, and if a separator appears before it. You can use the RunTimeMenuItem.InvokeItem method to execute the item, which launches a sequence in a new execution or an executable. Use the Engine.GetRunTimeToolMenuItems method to obtain a reference to a collection of this class for the Tools menu. Use this collection to determine what to display in the Tools menu at run time.
RunTimeMenuItems
The RunTimeMenuItems class specifies a collection of RunTimeMenuItem objects, which represent an evaluated version of a EditTimeMenuItem object. The properties of the RunTimeMenuItem object specify the item text and if the menu item is disabled. You can use the RunTimeMenuItem.InvokeItem method to execute the item, which launches an executable or a sequence in a new execution. Use this collection to determine what to display in the Tools menu at run time. Use the Engine.GetRunTimeToolMenuItems method to obtain a reference to a collection of this class for the Tools menu.
SearchDirectories
This collection class contains elements using the SearchDirectory type. The collection specifies the directories TestStand searches for finding files. The directories listed first in the collection take precedence over those listed later in the collection. When you run TestStand for the first time, the collection contains a default set of search directory paths.
SearchDirectory
A SearchDirectory object specifies a directory in which TestStand searches for finding files. An object of this class specifies a path to an explicit directory or specifies a predefined directory, such as the TestStand directory or the Microsoft Windows directory. An object specifies any file extension restrictions and whether to search subdirectories.
SearchMatch
The SearchResults object return objects of the SearchMatch class. SearchResults objects contain details about a match found as a result of a call to the PropertyObject.Search or Engine.SearchFiles methods.
SearchResults
Objects in the SearchResult class are both a handle to a search in progress and a container for the results of that search. When you call the PropertyObject.Search or Engine.SearchFiles method, TestStand returns a SearchResults object. The search runs asynchronously, which means you obtain the SearchResults object before the search finishes. To wait for the search to complete, call the SearchResults.IsComplete method. Alternatively, you can access the results as they accumulate asynchronously by using the SearchResults.NumMatches property to obtain the number of matches and then accessing only the SearchMatch objects up to that number. TestStand always appends new SearchMatch objects to the end of the result list.
SelectedBreakpointItem
A SelectedBreakpointItem object specifies a breakpoint in a sequence file. Use this object for the selectedItemParam parameter of the Engine.DisplayEditBreakAndWatchDialog method, which returns the last selected item on the Breakpoints tab of the Edit Breakpoints/Watch Expressions dialog box when the user clicks the Goto button. The selected item can be a sequence file, sequence, or step.
Sequence
Objects of the Sequence class represent a sequence that can contain steps. Use the Sequence class to examine or modify sequence settings and the list of steps in the sequence. Sequences have three groups of steps. The StepGroups enumeration contains a value for each of the step groups. SequenceTypes constants define several types of sequences. You can obtain a reference to the Sequence objects a sequence file contains by calling the SequenceFile.GetSequence method. You can create new sequences by calling the Engine.NewSequence or SequenceFile.CreateCallbackOverrideSequence methods.
Note  Built-in properties of sequences are flagged to be shared at run time. Any changes to built-in properties within the run-time copy of the sequence also edit the original Sequence object in the sequence file.
SequenceContext
A SequenceContext object contains complete information about an execution at a particular point during the execution. You can use the sequence context to access all the objects, variables, and properties in the execution. From the sequence context, you also can obtain references to all the steps in the current sequence, the sequence contexts for the calling sequences, the Process Model entry point sequence, and the MainSequence in the client sequence file. You can pass the current sequence context or subproperties to code modules you call from steps.
SequenceFile
Objects of the SequenceFile class represent a sequence file that can contain sequences. You can obtain a reference to a SequenceFile object by using the Engine.GetSequenceFileEx or Engine.NewSequenceFile methods. Use the reference to examine or modify sequence file settings and to examine or modify the list of sequences in the sequence file.
StationOptions
Use the StationOptions class to set preferences for TestStand. The settings affect all sequence editor and user interface sessions. Use the Engine.DisplayOptionsDialog method to launch the Station Options dialog box.
Step
Objects of the Step class represent steps in TestStand sequences. A step can perform many tasks, such as initializing an instrument, performing a complex test, or making a decision that affects the flow of execution in a sequence. You can obtain a reference to a step in a sequence by calling the Sequence.GetStep method. Create new steps with the Engine.NewStep method.
Note  Built-in properties of steps are flagged to be shared at run-time. Any changes to built-in properties within the run-time copy of the step edits the original step object in the sequence file.
StepAdditionalResults
Use the Step.AdditionalResults property to obtain an instance of this class, which contains collections for the parameter additional results and custom additional results of a step.
StepType
Objects of the StepType class represent step types in TestStand files. Every step is an instance of a step type. You create new step types with the Engine.NewStepType method.
Thread
Threads are elements of an Execution. Each thread maintains a call stack that contains a SequenceContext object for each active sequence invocation. You can obtain a thread of an execution by calling the Execution.GetThread method.
TypeUsageList
The TypeUsageList contains a list of types a PropertyObjectFile object uses. Use this class to insert or delete types from a file.
Note  When you edit a PropertyObjectFile object by inserting named data types or step types in to the file, add any new types to the TypeUsageList object for the file so the types immediately appear in the Types view in the sequence editor for the file. Use the TypeUsageList.AddUsedTypes or TypeUsageList.Union method to add new types.
UIMessage
TestStand uses UIMessage objects to pass information about the state of the engine and the current executions to the user interface or sequence editor. You can obtain UIMessage objects in a user interface program by providing a callback to the engine. The engine calls the callback when it has a UIMessage object to pass. If you do not provide a callback, you can set the Engine.UIMessagePollingEnabled property to True and call the Engine.GetUIMessage method to poll for UIMessage objects.
UndoItem
A user interface receives objects that implement the UndoItem interface through the UIMessage.ActiveXData property of a UIMsg_PushUndoItem UI Message. A user interface uses the UndoItem.EditedFile property to find an appropriate UndoStack to push the undo item onto. You can also use the UndoItem interface to make an edit to a TestStand file undoable if the UndoItemCreator does not provide enough functionality to undo an edit. To do this, create a COM object that implements the UndoItem interface and send an instance of the object to the sequence editor using a UIMsg_PushUndoItem UI Message.
Note  LabVIEW and LabWindows/CVI do not support implementing custom objects for this interface.
UndoItem2
The UndoItem2 class inherits from the UndoItem class and supports all the UndoItem properties and methods. An object that supports UndoItem might not necessarily support UndoItem2. You can also use the UndoItem2 interface to make an edit to a TestStand file undoable if the UndoItemCreator does not provide enough functionality to undo an edit. To do this, create a COM object that implements the UndoItem2 interface and send an instance of the object to the sequence editor using a UIMsg_PushUndoItem UI Message.
Note  LabVIEW and LabWindows/CVI do not support implementing custom objects for this interface.
UndoItemCreator
Use UndoItemCreator to make edits to TestStand files undoable. To use UndoItemCreator, first create an UndoItemCreator object using the Engine.NewUndoItemCreator method. Then call the BeginEdit method, make an edit to a TestStand object, and call the EndEdit method. You can call BeginEdit and EndEdit more than once to edit more than one TestStand object. Then call the CreateAndPostUndoItem method to create an undo item for all the edits you made.
UndoItems
You can obtain a collection of UndoItem objects from the UndoStack.UndoItems property.
UndoStack
An UndoStack manages a stack of undo items and a stack of redo items. Normally, you create an UndoStack for every document in a sequence editor in which you can undo edits to a TestStand file. You receive undo items to push onto an undo stack through the UIMessage.ActiveXData property of a UIMsg_PushUndoItem UI Message. You use the UndoItem.EditedFile property of the undo item to determine onto which document undo stack to push the undo item. Use the Engine.NewUndoStack method to create an UndoStack object. You typically use UndoStack objects with the ApplicationMgr.UndoStack and SequenceFileViewMgr.UndoStack properties.
UnmappedArgumentValue
Use objects from the UnmappedArgumentValue class to obtain specific information for an item in the UnmappedArgumentValues collection class.
UnmappedArgumentValues
Use objects from the UnmappedArgumentValues class to obtain a list of the current arguments not used as inputs and outputs of the corresponding module. Use the Module.UnmappedArgumentValues and DotNetCall.UnmappedArgumentValues properties to obtain the collection of unmapped argument values for a module. When a module prototype changes, TestStand attempts to map the current module arguments to the new prototype by looking for matching argument names and data types, and by matching argument positions and data types. If TestStand fails to assign an argument to the new prototype, the argument is added to this collection. TestStand does not clear the collection when you load a new prototype. Use the UnmappedArgumentValues.Clear method to clear the collection before calling the Module.LoadPrototype or DotNetCall.LoadPrototypeFromSignature method.
User
Objects of the User class represent the data and privileges TestStand associates with a TestStand user or user group. Call the Engine.GetUser or Engine.NewUser method to obtain a User object for a particular user or user group. Obtain the object for the currently logged-in user from the Engine.CurrentUser property. You can obtain an array of users or user groups using the UsersFile.UserList and UsersFile.UserGroupList properties. Use the PropertyObject class methods to add or remove objects from the array to change the TestStand user or user group list. You can use the PropertyObject class to access the subproperties of an object from the User class. Refer to User Data Type Subproperties for the default subproperties TestStand defines.
UsersFile
The UsersFile class represents the file that contains a list of TestStand users and user profiles. Use this class to add or delete users and user profiles. You can obtain a reference to the users file TestStand loads at startup with the Engine.UsersFile property. To perform read or write operations for objects from the UsersFile class, obtain a reference to the PropertyObjectFile interface by using the AsPropertyObjectFile methods, then use the PropertyObjectFile.ReadFile and PropertyObjectFile.WriteFile methods.
Utility
Use this class to perform utility functions. Use the Engine.Utility property to obtain an instance of this class.
WatchExpression
Use objects of the WatchExpression class to monitor the values of properties and variables using expressions. Typically, you use WatchExpression objects to display run-time values in a Watch View pane in a user interface. A WatchExpression object defines an expression TestStand evaluates during sequence execution. You can configure a conditional breakpoint on a watch expression. The breakpoint suspends execution when a value of the watch expression changes, or whenever the coerced value of the watch expression evaluates to True. The TestStand Engine maintains a list of watch expressions and evaluates conditional breakpoints during execution. You can also specify the scope of the watch expression, which specifies whether the expression applies to all executions of the client sequence file or only the current execution, and whether to evaluate the watch expression only when executing within a specific sequence file or sequence. Use the collection object the Engine.GetWatchExpressions method returns to manage a watch expression list. You can create new watch expressions by using the WatchExpressions.Insert method, which adds a new watch expression to the collection and returns the new object. To add a watch expression to the list the engine maintains and monitors, pass True for the insertInEngine parameter.
WatchExpressions
Objects of the WatchExpressions class are collections of objects of the WatchExpression class.
WorkspaceFile
Objects of the WorkspaceFile class represent workspace files that can contain projects. A workspace file contains a list of project files and source code control provider information. Each project file contains lists of sequence files, code modules, and other files required by a particular test system. To perform read or write operations for objects from the WorkspaceFile class, obtain a reference to the PropertyObjectFile interface by using the WorkspaceFile.AsPropertyObjectFile method, then use the PropertyObjectFile.ReadFile and PropertyObjectFile.WriteFile methods, respectively.
WorkspaceObject
Objects of the WorkspaceObject class represent nodes for workspace and project files on the Workspace pane. Workspace objects handle all source code control operations on files.

WAS THIS ARTICLE HELPFUL?

Not Helpful