You are on page 1of 350

NI TestStand

Reference Manual

NI TestStand Reference Manual

April 2007
373435B-01

TM

Support
Worldwide Technical Support and Product Information
ni.com
National Instruments Corporate Headquarters
11500 North Mopac Expressway

Austin, Texas 78759-3504 USA Tel: 512 683 0100

Worldwide Offices
Australia 1800 300 800, Austria 43 662 457990-0, Belgium 32 (0) 2 757 0020, Brazil 55 11 3262 3599,
Canada 800 433 3488, China 86 21 5050 9800, Czech Republic 420 224 235 774, Denmark 45 45 76 26 00,
Finland 385 (0) 9 725 72511, France 33 (0) 1 48 14 24 24, Germany 49 89 7413130, India 91 80 41190000,
Israel 972 3 6393737, Italy 39 02 413091, Japan 81 3 5472 2970, Korea 82 02 3451 3400,
Lebanon 961 (0) 1 33 28 28, Malaysia 1800 887710, Mexico 01 800 010 0793, Netherlands 31 (0) 348 433 466,
New Zealand 0800 553 322, Norway 47 (0) 66 90 76 60, Poland 48 22 3390150, Portugal 351 210 311 210,
Russia 7 495 783 6851, Singapore 1800 226 5886, Slovenia 386 3 425 42 00, South Africa 27 0 11 805 8197,
Spain 34 91 640 0085, Sweden 46 (0) 8 587 895 00, Switzerland 41 56 2005151, Taiwan 886 02 2377 2222,
Thailand 662 278 6777, Turkey 90 212 279 3031, United Kingdom 44 (0) 1635 523545
For further support information, refer to the Technical Support and Professional Services appendix. To comment
on National Instruments documentation, refer to the National Instruments Web site at ni.com/info and enter
the info code feedback.
20032007 National Instruments Corporation. All rights reserved.

Important Information
Warranty
The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects
in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National
Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives
notice of such defects during the warranty period. National Instruments does not warrant that the operation of the software shall be
uninterrupted or error free.
A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside of the package before any
equipment will be accepted for warranty work. National Instruments will pay the shipping costs of returning to the owner parts which are covered by
warranty.
National Instruments believes that the information in this document is accurate. The document has been carefully reviewed for technical accuracy. In
the event that technical or typographical errors exist, National Instruments reserves the right to make changes to subsequent editions of this document
without prior notice to holders of this edition. The reader should consult National Instruments if errors are suspected. In no event shall National
Instruments be liable for any damages arising out of or related to this document or the information contained in it.
EXCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. CUSTOMERS RIGHT TO RECOVER DAMAGES CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF NATIONAL
INSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID BY THE CUSTOMER. NATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR DAMAGES RESULTING
FROM LOSS OF DATA, PROFITS, USE OF PRODUCTS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This limitation of
the liability of National Instruments will apply regardless of the form of action, whether in contract or tort, including negligence. Any action against
National Instruments must be brought within one year after the cause of action accrues. National Instruments shall not be liable for any delay in
performance due to causes beyond its reasonable control. The warranty provided herein does not cover damages, defects, malfunctions, or service
failures caused by owners failure to follow the National Instruments installation, operation, or maintenance instructions; owners modification of the
product; owners abuse, misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties, or other events outside
reasonable control.

Copyright
Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying,
recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of National
Instruments Corporation.
National Instruments respects the intellectual property of others, and we ask our users to do the same. NI software is protected by copyright and other
intellectual property laws. Where NI software may be used to reproduce software or other materials belonging to others, you may use NI software only
to reproduce materials that you may reproduce in accordance with the terms of any applicable license or other legal restriction.

Trademarks
National Instruments, NI, ni.com, NI TestStand, and LabVIEW are trademarks of National Instruments Corporation. Refer to the Terms of Use
section on ni.com/legal for more information about National Instruments trademarks.
Other product and company names mentioned herein are trademarks or trade names of their respective companies.
Members of the National Instruments Alliance Partner Program are business entities independent from National Instruments and have no agency,
partnership, or joint-venture relationship with National Instruments.

Patents
For patents covering National Instruments products, refer to the appropriate location: HelpPatents in your software, the patents.txt file
on your CD, or ni.com/patents.

WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS


(1) NATIONAL INSTRUMENTS PRODUCTS ARE NOT DESIGNED WITH COMPONENTS AND TESTING FOR A LEVEL OF
RELIABILITY SUITABLE FOR USE IN OR IN CONNECTION WITH SURGICAL IMPLANTS OR AS CRITICAL COMPONENTS IN
ANY LIFE SUPPORT SYSTEMS WHOSE FAILURE TO PERFORM CAN REASONABLY BE EXPECTED TO CAUSE SIGNIFICANT
INJURY TO A HUMAN.
(2) IN ANY APPLICATION, INCLUDING THE ABOVE, RELIABILITY OF OPERATION OF THE SOFTWARE PRODUCTS CAN BE
IMPAIRED BY ADVERSE FACTORS, INCLUDING BUT NOT LIMITED TO FLUCTUATIONS IN ELECTRICAL POWER SUPPLY,
COMPUTER HARDWARE MALFUNCTIONS, COMPUTER OPERATING SYSTEM SOFTWARE FITNESS, FITNESS OF COMPILERS
AND DEVELOPMENT SOFTWARE USED TO DEVELOP AN APPLICATION, INSTALLATION ERRORS, SOFTWARE AND HARDWARE
COMPATIBILITY PROBLEMS, MALFUNCTIONS OR FAILURES OF ELECTRONIC MONITORING OR CONTROL DEVICES,
TRANSIENT FAILURES OF ELECTRONIC SYSTEMS (HARDWARE AND/OR SOFTWARE), UNANTICIPATED USES OR MISUSES, OR
ERRORS ON THE PART OF THE USER OR APPLICATIONS DESIGNER (ADVERSE FACTORS SUCH AS THESE ARE HEREAFTER
COLLECTIVELY TERMED SYSTEM FAILURES). ANY APPLICATION WHERE A SYSTEM FAILURE WOULD CREATE A RISK OF
HARM TO PROPERTY OR PERSONS (INCLUDING THE RISK OF BODILY INJURY AND DEATH) SHOULD NOT BE RELIANT SOLELY
UPON ONE FORM OF ELECTRONIC SYSTEM DUE TO THE RISK OF SYSTEM FAILURE. TO AVOID DAMAGE, INJURY, OR DEATH,
THE USER OR APPLICATION DESIGNER MUST TAKE REASONABLY PRUDENT STEPS TO PROTECT AGAINST SYSTEM FAILURES,
INCLUDING BUT NOT LIMITED TO BACK-UP OR SHUT DOWN MECHANISMS. BECAUSE EACH END-USER SYSTEM IS
CUSTOMIZED AND DIFFERS FROM NATIONAL INSTRUMENTS' TESTING PLATFORMS AND BECAUSE A USER OR APPLICATION
DESIGNER MAY USE NATIONAL INSTRUMENTS PRODUCTS IN COMBINATION WITH OTHER PRODUCTS IN A MANNER NOT
EVALUATED OR CONTEMPLATED BY NATIONAL INSTRUMENTS, THE USER OR APPLICATION DESIGNER IS ULTIMATELY
RESPONSIBLE FOR VERIFYING AND VALIDATING THE SUITABILITY OF NATIONAL INSTRUMENTS PRODUCTS WHENEVER
NATIONAL INSTRUMENTS PRODUCTS ARE INCORPORATED IN A SYSTEM OR APPLICATION, INCLUDING, WITHOUT
LIMITATION, THE APPROPRIATE DESIGN, PROCESS AND SAFETY LEVEL OF SUCH SYSTEM OR APPLICATION.

Contents
About This Manual
Conventions ...................................................................................................................xv

Chapter 1
TestStand Architecture
General Test Executive Concepts ..................................................................................1-1
Major Software Components of TestStand....................................................................1-2
TestStand Sequence Editor..............................................................................1-2
TestStand User Interfaces................................................................................1-3
Features Comparison: Sequence Editor and User Interfaces ............1-4
TestStand User Interface Controls...................................................................1-6
TestStand Engine.............................................................................................1-6
Module Adapters .............................................................................................1-6
TestStand Building Blocks ............................................................................................1-7
Variables and Properties..................................................................................1-7
Expressions .......................................................................................1-8
Categories of Properties ....................................................................1-9
Steps ................................................................................................................1-10
Step Types.........................................................................................1-11
Sequences ........................................................................................................1-11
Step Groups.......................................................................................1-11
Sequence Local Variables .................................................................1-12
Sequence Parameters.........................................................................1-12
Built-in Sequence Properties.............................................................1-13
Sequence Files .................................................................................................1-13
Process Models................................................................................................1-13
Station Model....................................................................................1-14
Main Sequence and Client Sequence File.........................................1-14
Entry Points.......................................................................................1-15
Automatic Result Collection ...........................................................................1-15
Callback Sequences .........................................................................................1-15
Sequence Executions .......................................................................................1-16

Chapter 2
Sequence Files and Workspaces
Sequence Files ...............................................................................................................2-1
Types of Sequence Files..................................................................................2-1
Sequence File Callbacks..................................................................................2-1

National Instruments Corporation

NI TestStand Reference Manual

Contents

Sequence File Globals..................................................................................... 2-2


Sequence File Type Definitions ...................................................................... 2-2
Comparing and Merging Sequence Files ........................................................ 2-2
Sequences ...................................................................................................................... 2-3
Step Groups..................................................................................................... 2-3
Parameters ....................................................................................................... 2-3
Local Variables ............................................................................................... 2-4
Sequence File Window and Views................................................................................ 2-4
Workspaces.................................................................................................................... 2-5
Source Code Control ....................................................................................... 2-6
System Deployment ........................................................................................ 2-6

Chapter 3
Executions
Sequence Context .......................................................................................................... 3-1
Using the Sequence Context ........................................................................... 3-2
Lifetime of Local Variables, Parameters, and
Custom Step Properties.................................................................. 3-3
Sequence Editor Execution Window .............................................................. 3-3
Starting an Execution .................................................................................................... 3-4
Execution Entry Points.................................................................................... 3-4
Executing a Sequence Directly ....................................................................... 3-4
Interactively Executing Steps.......................................................................... 3-5
Terminating and Aborting Executions ............................................................ 3-5
Execution Debugging Panes ........................................................................... 3-6
Result Collection ........................................................................................................... 3-7
Custom Result Properties................................................................................ 3-8
Standard Result Properties .............................................................................. 3-10
Subsequence Results ....................................................................................... 3-11
Loop Results ................................................................................................... 3-12
Report Generation ........................................................................................... 3-13
Engine Callbacks ........................................................................................................... 3-13
Step Execution............................................................................................................... 3-13
Step Status ..................................................................................................................... 3-16
Failures............................................................................................................ 3-17
Terminations ................................................................................................... 3-17
Run-Time Errors............................................................................................................ 3-17

NI TestStand Reference Manual

vi

ni.com

Contents

Chapter 4
Built-In Step Types
Overview........................................................................................................................4-1
Using Step Types.............................................................................................4-1
Built-In Step Properties.....................................................................4-3
Custom Properties That All Built-In Step Types Share ..................................4-5
Error Occurred Flag, Step Status, and Run-Time Errors.................................4-6
Step Types That You Can Use with Any Module Adapter ...........................................4-7
Pass/Fail Test...................................................................................................4-8
Numeric Limit Test .........................................................................................4-9
Multiple Numeric Limit Test...........................................................................4-11
String Value Test.............................................................................................4-13
Action ..............................................................................................................4-15
Step Types That Work With a Specific Module Adapter ..............................................4-15
Sequence Call ..................................................................................................4-15
Step Types That Do Not Use Module Adapters ............................................................4-16
Flow Control....................................................................................................4-16
If ........................................................................................................4-16
Else....................................................................................................4-17
Else If ................................................................................................4-17
For .....................................................................................................4-17
For Each ............................................................................................4-18
While .................................................................................................4-18
Do While ...........................................................................................4-18
Break .................................................................................................4-18
Continue ............................................................................................4-19
Select .................................................................................................4-19
Case...................................................................................................4-19
Goto...................................................................................................4-19
End ....................................................................................................4-19
Statement .........................................................................................................4-20
Label ................................................................................................................4-20
Message Popup................................................................................................4-20
Call Executable................................................................................................4-22
Property Loader ...............................................................................................4-23
FTP Files .........................................................................................................4-24
Synchronization Step Types ............................................................................4-24
Database Step Types........................................................................................4-24
IVI-C Step Types.............................................................................................4-24
LabVIEW Utility Step Types ..........................................................................4-24

National Instruments Corporation

vii

NI TestStand Reference Manual

Contents

Chapter 5
Adapters
Module Adapters ........................................................................................................... 5-1
Configuring Adapters...................................................................................... 5-1
Source Code Templates .................................................................................. 5-2
LabVIEW Adapter......................................................................................................... 5-2
LabWindows/CVI Adapter............................................................................................ 5-2
C/C++ DLL Adapter ..................................................................................................... 5-3
Using and Debugging DLLs.......................................................................................... 5-3
Calling LabVIEW DLLs................................................................................. 5-5
Using ActiveX Controls ................................................................... 5-5
Debugging LabVIEW 8 or Later Shared Libraries (DLLs).............. 5-5
Debugging LabVIEW 7.1.1 Shared Libraries (DLLs) ..................... 5-6
Using MFC in a DLL ...................................................................................... 5-6
Loading Subordinate DLLs............................................................................. 5-6
Reading Parameter Information ...................................................................... 5-7
.NET Adapter ................................................................................................................ 5-7
Debugging .NET Assemblies.......................................................................... 5-8
Using the .NET Framework ............................................................................ 5-10
Accessing the TestStand API in Visual Studio .NET 2003 and
Visual Studio 2005 ....................................................................................... 5-11
Configuring the .NET Adapter........................................................................ 5-11
ActiveX/COM Adapter ................................................................................................. 5-12
Running and Debugging ActiveX Automation Servers.................................. 5-12
Configuring the ActiveX/COM Adapter......................................................... 5-12
Registering and Unregistering ActiveX/COM Servers................................... 5-13
Server Compatibility Options for Visual Basic .............................................. 5-13
HTBasic Adapter ........................................................................................................... 5-15
Specifying the HTBasic Adapter .................................................................... 5-15
Debugging an HTBasic Adapter ..................................................................... 5-15
Passing Data To and Returning Data From a Subroutine ............................... 5-16
Sequence Adapter .......................................................................................................... 5-16
Specifying the Sequence Adapter ................................................................... 5-17
Remote Sequence Execution ............................................................ 5-17
Setting up TestStand as a Server for Remote Sequence Execution ................ 5-18
Windows XP Service Pack 2 ............................................................ 5-19
Windows XP SP2 Firewall Settings ................................................. 5-21
Windows 2000 Service Pack 4 ......................................................... 5-21

NI TestStand Reference Manual

viii

ni.com

Contents

Chapter 6
Database Logging and Report Generation
Database Concepts .........................................................................................................6-1
Databases and Tables ......................................................................................6-1
Database Sessions............................................................................................6-3
Microsoft ADO, OLE DB, and ODBC Database Technologies .....................6-3
Data Links .......................................................................................................6-5
Database Logging Implementation..................................................................6-6
Using Database Logging................................................................................................6-7
Logging Property in the Sequence Context.....................................................6-8
TestStand Database Result Tables .................................................................................6-9
Default TestStand Table Schema ....................................................................6-9
Creating the Default Result Tables..................................................................6-10
Adding Support for Other Database Management Systems............................6-10
Database Viewer..............................................................................................6-12
On-the-Fly Database Logging .........................................................................6-12
Using Data Links ...........................................................................................................6-13
Using the ODBC Administrator ......................................................................6-13
Example Data Link and Result Table Setup for Microsoft Access.................6-13
Database OptionsSpecifying a Data Link and Schema.................6-13
Database ViewerCreating Result Tables.......................................6-14
Implementation of the Test Report Capability ..............................................................6-15
Using Test Reports.........................................................................................................6-16
Failure Chain in Reports..................................................................................6-16
Batch Reports ..................................................................................................6-16
Property Flags that Affect Reports ..................................................................6-17
On-the-Fly Report Generation.........................................................................6-17
XML Report Schema.......................................................................................6-18

Chapter 7
User Management
Privileges .......................................................................................................................7-2
Accessing Privilege Settings for the Current User ..........................................7-2
Accessing Privilege Settings for Any User .....................................................7-3
Defining Custom Privileges in TestStand .......................................................7-3

Chapter 8
Customizing and Configuring TestStand
Customizing TestStand ..................................................................................................8-1
User Interfaces.................................................................................................8-1
Process Models................................................................................................8-1

National Instruments Corporation

ix

NI TestStand Reference Manual

Contents

Callbacks ......................................................................................................... 8-2


Data Types ...................................................................................................... 8-2
Step Types....................................................................................................... 8-2
Tools Menu ..................................................................................................... 8-2
TestStand Directory Structure......................................................................... 8-3
NI and User Subdirectories............................................................... 8-4
Components Directory...................................................................... 8-4
Creating String Resource Files ....................................................................... 8-6
String Resource File Format............................................................. 8-7
Configuring TestStand................................................................................................... 8-8
Sequence Editor and User Interface Startup Options...................................... 8-8
Configure Menu .............................................................................................. 8-11

Chapter 9
Creating Custom User Interfaces
Example User Interfaces................................................................................................ 9-2
TestStand User Interface Controls................................................................................. 9-2
Deploying a User Interface............................................................................................ 9-3
Writing an Application with the TestStand UI Controls ............................................... 9-3
Manager Controls............................................................................................ 9-3
Application Manager ........................................................................ 9-3
SequenceFileView Manager............................................................. 9-4
ExecutionView Manager .................................................................. 9-4
Visible TestStand UI Controls ........................................................................ 9-5
Connecting Manager Controls to Visible Controls......................................... 9-6
View Connections ........................................................................................... 9-7
List Connections ............................................................................................. 9-7
Command Connections ................................................................................... 9-9
Information Source Connections .................................................................... 9-10
Caption Connections......................................................................... 9-10
Image Connections ........................................................................... 9-11
Numeric Value Connections............................................................. 9-12
Specifying and Changing Control Connections.............................................. 9-12
Editor Versus Operator Interface Applications ............................................................. 9-12
Creating Editor Applications .......................................................................... 9-13
License Checking .......................................................................................................... 9-13
Using TestStand UI Controls in Different Environments ............................................. 9-14
LabVIEW ........................................................................................................ 9-14
LabWindows/CVI ........................................................................................... 9-14
Microsoft Visual Studio .................................................................................. 9-15
Visual C++ ...................................................................................................... 9-15
Obtaining an Interface Pointer and CWnd for an ActiveX Control................ 9-16
Using GetDlgItem............................................................................. 9-16

NI TestStand Reference Manual

ni.com

Contents

Handling Events.............................................................................................................9-17
Creating Event Handlers in Your ADE ...........................................................9-17
Events Handled by Typical Applications ........................................................9-18
ExitApplication .................................................................................9-18
Wait...................................................................................................9-18
ReportError .......................................................................................9-18
DisplaySequenceFile.........................................................................9-18
DisplayExecution ..............................................................................9-19
Startup and Shut Down ..................................................................................................9-19
TestStand Utility Functions Library ..............................................................................9-20
Menus and Menu Items..................................................................................................9-23
Updating Menus ..............................................................................................9-23
Localization ...................................................................................................................9-25
User Interface Application Styles ..................................................................................9-26
Single Window ................................................................................................9-26
Multiple Window.............................................................................................9-27
No Visible Window.........................................................................................9-28
Command-Line Arguments ...........................................................................................9-29
Persistence of Application Settings ...............................................................................9-29
Configuration File Location ............................................................................9-30
Adding Custom Application Settings..............................................................9-30
Using the TestStand API with TestStand UI Controls ..................................................9-31
Documenting Custom User Interfaces ...........................................................................9-32

Chapter 10
Customizing Process Models and Callbacks
Process Models ..............................................................................................................10-1
Station Model ..................................................................................................10-2
Specifying a Specific Process Model for a Sequence File ..............................10-2
Modifying the Process Model .........................................................................10-2
Process Model Callbacks.................................................................................10-3
Normal Sequences.............................................................................10-4
Callback Sequences...........................................................................10-5
Entry Point Sequences ......................................................................10-5
Callbacks........................................................................................................................10-6
Engine Callbacks .............................................................................................10-6
Front-End Callbacks........................................................................................10-10

Chapter 11
Type Concepts
Storing Types in Files and Memory ..............................................................................11-1
Modifying Types............................................................................................................11-1

National Instruments Corporation

xi

NI TestStand Reference Manual

Contents

Type Versioning ............................................................................................................ 11-2


Resolving Type Conflicts................................................................................ 11-2
Types Window............................................................................................................... 11-3
Sequence Files................................................................................................. 11-3
Station Globals ................................................................................................ 11-4
User Manager .................................................................................................. 11-4
Type Palette Files............................................................................................ 11-4

Chapter 12
Standard and Custom Data Types
Using Data Types .......................................................................................................... 12-1
Specifying Array Sizes.................................................................................... 12-2
Empty Arrays.................................................................................... 12-3
Display of Data Types..................................................................................... 12-3
Modifying Data Types and Values ................................................................. 12-5
Single Values .................................................................................... 12-5
Arrays ............................................................................................... 12-6
Using Standard Named Data Types ................................................................ 12-7
Path ................................................................................................... 12-7
Error and CommonResults ............................................................... 12-7
Creating and Modifying Custom Data Types................................................................ 12-8
Creating a New Custom Data Type ................................................................ 12-8
Customizing Built-In Data Types ................................................................... 12-9
Properties Common to All Data Types ........................................................... 12-9
General Tab ...................................................................................... 12-9
Bounds Tab....................................................................................... 12-10
Version Tab ...................................................................................... 12-10
Cluster Passing Tab .......................................................................... 12-10
C Struct Passing Tab......................................................................... 12-10
.NET Struct Passing Tab .................................................................. 12-10
Custom Properties of Data Types ................................................................... 12-10

Chapter 13
Creating Custom Step Types
Creating and Modifying Custom Step Types ................................................................ 13-1
Creating a New Custom Step Type................................................................. 13-2
Customizing Built-In Step Types.................................................................... 13-2
Properties Common to All Step Types ........................................................... 13-3
General Tab ...................................................................................... 13-4
Menu Tab.......................................................................................... 13-4
Substeps Tab..................................................................................... 13-5

NI TestStand Reference Manual

xii

ni.com

Contents

Disable Properties Tab ......................................................................13-6


Code Templates Tab .........................................................................13-7
Version Tab.......................................................................................13-10
Custom Properties of Step Types ....................................................................13-10

Chapter 14
Deploying TestStand Systems
TestStand System Components .....................................................................................14-1
TestStand Deployment Utility .......................................................................................14-1
Setting Up the TestStand Deployment Utility.................................................14-2
Identifying Components for Deployment .........................................14-2
Determining Whether to Create an Installer
with the TestStand Deployment Utility..........................................14-2
Creating a System Workspace File ...................................................14-3
Configuring and Building the Deployment.......................................14-3
Using the TestStand Deployment Utility.......................................................................14-3
File Collection .................................................................................................14-3
VI Processing...................................................................................................14-4
Sequence File Processing ................................................................................14-5
Installing National Instruments Components ..................................................14-5
Guidelines for Successful Deployment..........................................................................14-6
Common Deployment Scenarios ...................................................................................14-7
Deploying the TestStand Engine .....................................................................14-7
Distributing Tests from a Workspace..............................................................14-8
Adding Dynamically Called Files to a Workspace .........................................14-10
Distributing a User Interface ...........................................................................14-11

Chapter 15
Sequence File Translators
Custom Sequence File Translators ................................................................................15-1
Using a Sequence File Translator ..................................................................................15-1
Creating a Translator DLL.............................................................................................15-2
Required Callback Functions.........................................................................................15-3
Error Handling.................................................................................................15-13
Example Sequence File Translators...............................................................................15-13
Versioning Translators and Custom Sequence Files .....................................................15-14
Deploying Translators and Custom Sequence Files ......................................................15-15
Deploying Custom Sequence File Translators..................................15-15
Deploying Custom Sequence Files ...................................................15-16

National Instruments Corporation

xiii

NI TestStand Reference Manual

Contents

Appendix A
Process Model Architecture
Appendix B
Synchronization Step Types
Appendix C
Database Step Types
Appendix D
IVI-C Step Types
Appendix E
LabVIEW Utility Step Types
Appendix F
Instrument Drivers
Appendix G
Technical Support and Professional Services
Index

NI TestStand Reference Manual

xiv

ni.com

About This Manual


Use this manual to learn about TestStand concepts and features. Refer to the
NI TestStand System and Architecture Overview Card for information about
how to use the entire TestStand documentation set.

Conventions
The following conventions appear in this manual

The symbol leads you through nested menu items and dialog box options
to a final action. The sequence FilePage SetupOptions directs you to
pull down the File menu, select the Page Setup item, and select Options
from the last dialog box.
This icon denotes a tip, which alerts you to advisory information.
This icon denotes a note, which alerts you to important information.
This icon denotes a caution, which advises you of precautions to take to
avoid injury, data loss, or a system crash.

bold

Bold text denotes items that you must select or click in the software, such
as menu items and dialog box options. Bold text also denotes parameter
names, controls and buttons on the front panel, dialog boxes, sections of
dialog boxes, menu names, and palette names.

italic

Italic text denotes variables, emphasis, a cross-reference, or an introduction


to a key concept. Italic font also denotes text that is a placeholder for a word
or value that you must supply.

monospace

Text in this font denotes text or characters that you should enter from the
keyboard, sections of code, programming examples, and syntax examples.
This font is also used for the proper names of disk drives, paths, directories,
programs, subprograms, subroutines, device names, functions, operations,
variables, filenames, and extensions.

monospace italic

Italic text in this font denotes text that is a placeholder for a word or value
that you must supply.

National Instruments Corporation

xv

NI TestStand Reference Manual

TestStand Architecture

This chapter describes the NI TestStand architecture and provides an


overview of important TestStand concepts and components. It is useful
to read Using TestStand and the NI TestStand System and Architecture
Overview Card before reading this manual.
National Instruments also recommends that you become familiar with the
concepts of this chapter before proceeding through this manual.

General Test Executive Concepts


A test executive is a program in which you organize and execute sequences
of reusable code modules. Ideally, a test executive allows you to create the
modules in a variety of programming environments.
This document uses a number of concepts that are applicable to test
executives in general and some that are unique to TestStand. The following
concepts are applicable to test executives in general.

Code moduleA program module, such as a Windows dynamic


link library (.dll) or National Instruments LabVIEW VI (.vi),
containing one or more functions that perform a specific test or other
action.

StepAn individual element of a test sequence. A step can call


code modules or perform other operations.

SequenceA series of steps you specify to execute in a particular


order. Whether and when a step executes depends on the results of
previous steps.

SubsequenceA sequence that another sequence calls. You specify a


subsequence call as a step in the calling sequence.

Sequence fileA file that contains the definition of one or more


sequences.

Sequence editorA program that provides a graphical user interface


(GUI) for creating, editing, and debugging sequences.

User interfaceA program that provides a GUI for executing


sequences on a production station. A sequence editor and user

National Instruments Corporation

1-1

NI TestStand Reference Manual

Chapter 1

TestStand Architecture

interface can be separate application programs or different aspects of


the same program.

Test executive engineA module or set of modules that provide


an Application Programming Interface (API) for creating, editing,
executing, and debugging sequences. A sequence editor or user
interface uses the services of a test executive engine.

Application Development Environment (ADE)A programming


environment, such as LabVIEW, National Instruments
LabWindows/CVI, or Microsoft Visual Studio, in which you create
code modules and user interfaces.

Unit Under Test (UUT)The device or component you are testing.

Major Software Components of TestStand


This section provides an overview of the major software components of
TestStand. For a visual representation of how these components interact,
refer to the NI TestStand System and Architecture Overview Card, which is
included in your TestStand package. You can also refer to the NI TestStand
Help for more information about each of these components.
Note If you are opening help files from the <TestStand>\Doc\Help directory, National
Instruments recommends that you open TSHelp.chm. This file is a collection of all the
TestStand help files and provides a complete table of contents and index.

TestStand Sequence Editor


The TestStand Sequence Editor is a development environment in which
you develop your test station, and create, edit, execute, and debug
sequences and the tests sequences call. The sequence editor gives you
access to all TestStand features, such as step types and process models,
and includes the debugging tools you are familiar with in ADEs such as
LabVIEW, LabWindows/CVI (ANSI), and Microsoft Visual Studio.
These debugging tools include setting breakpoints; stepping into, out of, or
over steps; tracing through program executions; displaying variables; and
monitoring variables, expressions, and output messages during executions.
The TestStand Sequence Editor allows you to start multiple concurrent
executionsyou can execute multiple instances of the same sequence,
or you can execute different sequences at the same time. Each execution
instance has its own Execution window. In trace mode, the Execution
window displays the steps in the currently executing sequence. If the

NI TestStand Reference Manual

1-2

ni.com

Chapter 1

TestStand Architecture

execution is suspended, the Execution window displays the next step to


execute and provides debugging options.
The TestStand Sequence Editor contains the following advanced editing
features:

Panes that you can dock, float, or hide

Multiple step editing

Workspace pane to manage sequence files and test source code

Source code integration

Type editing

Undo and redo edits (except for types)

Forward and backward navigation between sequences

Find and replace

Integrated sequence file differ

User management window

In the TestStand Sequence Editor, you can fully customize the pane and tab
layout to optimize your development and debugging tasks. You can also
interactively customize the menus, toolbars, and their keyboard shortcuts.
You can save your custom layouts and reset the user interface layout to the
default. Refer to the NI TestStand Help for more information about working
with panes in the sequence editor.

TestStand User Interfaces


A TestStand User Interface is a program that provides a graphical user
interface (GUI) for executing sequences on a production station. User
interfaces are intended for use with deployed custom sequence editors or
test systems and are designed to protect the integrity of test sequences.
TestStand includes separate user interface applications developed in
LabVIEW, LabWindows/CVI, Microsoft Visual Basic .NET, C#, and C++
(MFC). Because TestStand includes the source code for each user interface,
you can fully customize the user interfaces. You can also create your own
user interface using any programming language that can host ActiveX
controls or control ActiveX Automation servers.
With the user interfaces in operator mode, you can start multiple concurrent
executions, set breakpoints, and single step through sequences. In editor
mode, you can modify sequences and display sequence variables, sequence
parameters, step properties, and so on.

National Instruments Corporation

1-3

NI TestStand Reference Manual

Chapter 1

TestStand Architecture

Refer to the NI TestStand System and Architecture Overview Card and the
NI TestStand User Interface Controls Reference Poster for more
information about user interfaces. Refer to Chapter 9, Creating Custom
User Interfaces, for more information about the user interfaces that are
included in TestStand.

Features Comparison: Sequence Editor and User


Interfaces
Table 1-1 illustrates the feature differences between the TestStand
Sequence Editor and the TestStand User Interfaces.
Table 1-1. TestStand Sequence Editor vs. TestStand User Interfaces

Application
TestStand
Sequence Editor

User Interface
Editor Mode

User Interface
Operator Mode

Docking, Hiding, & Floating


Panes

Configurable Menus and


Toolbars

Navigation Between Sequences

User Management
Configuration

Observes User Privileges

Configurable Step List

Dockable Pane

Modal Dialog

Modal Dialog

Source Code Control Support

Integrated

Modal Dialog

Configure Report Generation

Configure Database Logging

Configure Station Options

Edit Sequence Files

Insertion Palette

Features
Environment

Workspace Support

Editing

NI TestStand Reference Manual

1-4

ni.com

Chapter 1

TestStand Architecture

Table 1-1. TestStand Sequence Editor vs. TestStand User Interfaces (Continued)

Application
TestStand
Sequence Editor

User Interface
Editor Mode

User Interface
Operator Mode

Dockable Panes

Modal Dialogs

Integration with ADEs

Edit Variables/Station Globals

Edit Types

Edit Process Models

Multiple Step Editing

Undo/Redo

Find and Replace

Integrated File Differ

Multithreaded Execution

Single Step Debugging

Conditional Breakpoints

Call Stack and Thread Lists

Variables View

Watch View

Output Messages View

Can Include in Deployment

Source Code Available

TestStand
Development
System License

TestStand Custom
Sequence Editor
License

TestStand Base
Deployment Engine
License

Features
Edit Steps/Modules

Running

Other

Minimum License Required

Note Source code is available for the TestStand User Interface examples, so you can

customize the user interfaces to add features that are not available by default.

National Instruments Corporation

1-5

NI TestStand Reference Manual

Chapter 1

TestStand Architecture

TestStand User Interface Controls


The user interfaces use the TestStand User Interface (UI) Controls,
a collection of ActiveX controls for creating custom operator interfaces
and sequence editors in TestStand. These controls simplify common user
interface tasks, such as displaying sequences and executions. You can use
these controls in any programming environment that can host ActiveX
controls.
Refer to the NI TestStand Help and to Chapter 9, Creating Custom User
Interfaces, for more information about the TestStand UI Controls. You can
also refer to the NI TestStand User Interface Controls Reference Poster,
which is included in your TestStand package, for an illustrated overview of
the controls and API.

TestStand Engine
The TestStand Engine is a set of DLLs that export an ActiveX Automation
API. The TestStand Sequence Editor and User Interface Controls use the
TestStand API, which you can call from any programming environment
that supports access to ActiveX automation servers, including code
modules you write in LabVIEW and LabWindows/CVI.
For more information about the TestStand API, refer to the NI TestStand
Help.

Module Adapters
Most steps in a TestStand sequence invoke code in another sequence or in
a code module. When invoking code in a code module, TestStand must
know the type of code module, how to call it, and how to pass parameters
to it. The different types of code modules include LabVIEW VIs;
C functions in source, object, or library modules created in
LabWindows/CVI; C/C++ functions in DLLs; objects in .NET assemblies;
objects in ActiveX automation servers; and subroutines in HTBasic.
TestStand must also know the list of parameters required by the code
module. TestStand uses a module adapter to obtain this knowledge.
TestStand includes the following module adapters:

NI TestStand Reference Manual

LabVIEW AdapterCalls LabVIEW VIs with a variety of


connector panes.

LabWindows/CVI AdapterCalls C functions with a variety of


parameter types. The functions can be in object files, library files,
or DLLs. They can also be in source files that are in the project you
are currently using in LabWindows/CVI.
1-6

ni.com

Chapter 1

TestStand Architecture

C/C++ DLL AdapterCalls functions or methods in a DLL with


a variety of parameter types, including National Instruments
Measurement Studio classes.

.NET AdapterCalls methods and accesses the properties of objects


in a .NET assembly.

ActiveX/COM AdapterCalls methods and accesses the properties


of objects in an ActiveX server.

HTBasic AdapterCalls HTBasic subroutines.

Sequence AdapterCalls other TestStand sequences with


parameters.

The module adapters contain other important information in addition to the


calling convention and parameter lists. If the module adapter is specific to
an ADE, the adapter knows how to open the ADE, how to create source
code for a new code module in the ADE, and how to display the source for
an existing code module in the ADE.
Refer to Chapter 5, Adapters, for more information about the module
adapters included in TestStand.

TestStand Building Blocks


This section provides an overview of the TestStand features that you use to
create test sequences and entire test systems.

Variables and Properties


TestStand stores data values in variables and properties. Variables are
properties you can freely create in certain contexts. You can have variables
that are global to a sequence file or local to a particular sequence. You can
also have station global variables, which have values that are persistent
across different executions and even across different invocations of the
sequence editor or user interfaces. The TestStand Engine maintains the
value of station global variables in a file on the computer on which it is
installed.
You can use TestStand variables to share data among tests written in
different programming languages, even if they do not have compatible data
representations. You can pass values you store in variables and properties
to code modules. You can also use the TestStand API to access variable and
property values directly from code modules.

National Instruments Corporation

1-7

NI TestStand Reference Manual

Chapter 1

TestStand Architecture

Each step in a sequence can have properties. For example, a step might have
a floating-point measurement property. The type of step determines its
set of properties. Refer to the Step Types section of this chapter for more
information about types of steps.
When executing sequences, TestStand maintains a SequenceContext object
that contains references to all global variables, all local variables, and all
step properties in active sequences. The contents of the SequenceContext
object change according to the currently executing sequence and step. If
you pass a SequenceContext object reference to a code module, you can use
it to access information stored within the SequenceContext object.

Expressions
In TestStand, you can use the values of variables and properties in
numerous ways, such as passing a variable to a code module or using a
property value to determine whether to execute a step. For these same
purposes, you may also want to use an expression, which is a formula that
calculates a new value from the values of multiple variables or properties.
In expressions, you can access all variables and properties in the sequence
context that are active when TestStand evaluates the expression.
The following is an example of an expression:
Locals.MidBandFrequency = (Step.HighFrequency +
Step.LowFrequency) / 2

You can use an expression wherever you would use a simple variable or
property value. TestStand supports all applicable expression operators and
syntax that you would use in C, C++, Java, and Visual Basic .NET. You can
also call the TestStand API directly from within expressions.
Note Accessing the TestStand API from within expressions is slightly slower than using
multiple ActiveX/COM Adapter steps to perform similar operations.

Additionally, all controls that accept expressions provide context-sensitive


editing features such as drop-down lists, syntax checking, and expression
coloring to help you create expressions.
Refer to the NI TestStand Help for more information about TestStand
expressions.

NI TestStand Reference Manual

1-8

ni.com

Chapter 1

TestStand Architecture

Categories of Properties
A property is a storage space for information. A property can store a single
value or an array of values of the same data type. Each property has a name.
A value can be a number, string, Boolean, .NET object reference, or
an ActiveX object reference. TestStand stores numbers as 64-bit,
floating-point values in the IEEE 754 format. Values are not containers and
thus cannot contain subproperties. Arrays of values can have multiple
dimensions.
The following major categories of properties are defined according to the
kinds of values they contain:

Single-valued propertyContains a single value. The four types


of single-valued propertiesnumber, string, Boolean, and object
referencecorrespond to the four value types TestStand supports.

Array propertyContains an array of values. TestStand supports the


following array properties: number, string, Boolean, and object
reference.

Property-array propertyContains a value that is an array of


subproperties of a single type.

Container propertyContains no values and can contain multiple


subproperties. Container properties are analogous to structures in
C/C++ and to clusters in LabVIEW.

Standard and Custom Data Types


When you create a variable or property, you specify its data type. In some
cases, you use a simple data type, such as a number or a Boolean. In other
cases, you may want to define your own data type by adding subproperties
to a container to create an arbitrarily complex data structure. Define your
own data type by creating a named data type. When you create a named
data type, you can reuse it with variables or properties. Although each
variable or property you create with a named data type has the same data
structure, they can contain different values.
When you create a variable or property, you can use both built-in property
types and the named data types.
TestStand defines certain standard named data types. You can add
subproperties to some standard named data types, but you cannot delete any
of their built-in subproperties. The standard named data types include
Waveform, Path, Error, Expression, and CommonResults.

National Instruments Corporation

1-9

NI TestStand Reference Manual

Chapter 1

TestStand Architecture

Note Modifying the standard named data types may result in type conflicts when you

open other sequence files that reference these types. Refer to Chapter 12, Standard and
Custom Data Types, for more information about the standard named data types.
You can also define your own named data types. These data types must use
a unique name, and you can add or delete subproperties in each named data
type without restriction. For example, you might create a Transmitter data
type that contains subproperties such as NumChannels and PowerLevel.

Built-In and Custom Properties


TestStand defines a number of properties that are always present for
objects, such as steps and sequences. An example is the run mode property
for steps. The TestStand sequence editor normally hides these properties,
called built-in properties, although it lets you modify their values through
panes and dialog boxes. You can also access these properties through the
TestStand API.
You can define new properties in addition to the built-in properties.
Examples are high- and low-limit properties in a step or local variables
in a sequence. These properties are called custom properties.

Steps
A sequence consists of a series of steps. In TestStand, a step can perform
many actions, such as initializing an instrument, performing a complex test,
or making a decision that affects the flow of execution in a sequence. Steps
perform these actions through several types of mechanisms, including
jumping to another step, executing an expression, calling a subsequence, or
calling an external code module.
Steps can also have custom properties. For steps that call code modules,
custom step properties are useful for storing parameters to pass to the code
module for the step. They also serve as a place for the code module to store
its results. You can also use the TestStand API to access the values of
custom step properties from within code modules.
Not all steps call code modules. Some steps perform standard actions you
configure using panes and dialog boxes. In this case, custom step properties
are useful for storing the configuration settings you specify.

NI TestStand Reference Manual

1-10

ni.com

Chapter 1

TestStand Architecture

Step Types
Just as each variable or property has a data type, each step has a step type.
A step type can contain any number of custom properties. Each step of that
type includes the custom step properties in addition to the built-in step
properties. While all steps of the same type have the same properties, the
values of those properties can differ. The step type specifies the initial
values of all the step properties. TestStand includes a number of predefined
step types. For a description of these step types, refer to Chapter 4, Built-In
Step Types.
Although you can create a test application using only the predefined step
types in TestStand, you can also create your own custom step types.
Creating custom step types allows you to define standard, reusable classes
of steps that apply specifically to your application. Refer to Chapter 13,
Creating Custom Step Types, for more information about creating your own
step types.

Source Code Templates


TestStand also allows you to define a source code template for a new step
type. When you create a new step of a particular type, you can use a source
code template to generate source code for the code module of the step. You
can specify different source code templates for the different module
adapters.

Sequences
A TestStand sequence consists of the following components:

A group of setup steps (Setup step group)

A main group of steps (Main step group)

A group of cleanup steps (Cleanup step group)

Sequence local variables

Parameters

Built-in sequence properties

Step Groups
A sequence contains the following groups of steps: Setup, Main, and
Cleanup. TestStand executes the steps in the Setup step group first, the
Main step group second, and the Cleanup step group last. The Setup step
group typically contains steps that initialize instruments, fixtures, or a Unit

National Instruments Corporation

1-11

NI TestStand Reference Manual

Chapter 1

TestStand Architecture

Under Test (UUT). The Main step group typically contains the bulk of the
steps in a sequence, including the steps that test the UUT. The Cleanup step
group typically contains steps that power down or restore the initial state of
instruments, fixtures, and the UUT.
Use separate step groups to ensure that the steps in the Cleanup step group
execute regardless of whether the sequence completes successfully or a
run-time error occurs in the sequence. If a step in the Setup or Main step
group generates a run-time error, the flow of execution jumps to the
Cleanup step group. The cleanup steps always run even if some of the setup
steps do not run. If a cleanup step causes a run-time error, execution
continues to the next cleanup step.
If a run-time error occurs in a sequence, TestStand reports the run-time
error to the calling sequence. Execution in the calling sequence then jumps
to the Cleanup step group in that calling sequence. This process continues
up the call stack to the top-level sequence. Thus, when a run-time error
occurs, TestStand terminates execution after running all the cleanup steps
of all the sequences in the sequence call stack.

Sequence Local Variables


You can create an unlimited number of local variables in a sequence.
Use local variables to store data relevant to the execution of the sequence.
You can pass local variables by value or by reference to any step in
the sequence that calls a subsequence or a code module that uses the
LabVIEW, LabWindows/CVI, C/C++ DLL, .NET, or ActiveX/COM
Adapter. You can also access local variables from code modules of steps
in the sequence using the TestStand API.
Note TestStand can pass data to LabVIEW VIs only by value. LabVIEW does not support

passing data by reference. You can return a value as an indicator, which TestStand treats as
a separate parameter.

Sequence Parameters
Each sequence has its own list of parameters. Use these parameters to pass
data to a sequence when you call that sequence as a subsequence. Using
parameters in this way is analogous to wiring data to terminals when
you call a subVI in LabVIEW or to passing arguments to a function call
in LabWindows/CVI. You can also specify a default value for each
parameter.
You can specify the number of parameters and the data type of each
parameter. You can select a value to pass to the parameter or use the default

NI TestStand Reference Manual

1-12

ni.com

Chapter 1

TestStand Architecture

value specified by the parameter. You can pass sequence parameters by


value or by reference to any step in the sequence that calls a subsequence
or any step that calls a code module that uses the LabVIEW,
LabWindows/CVI, C/C++ DLL, .NET, or ActiveX/COM Adapter. You can
also access parameters from code modules of steps in the sequence by using
the TestStand API.
Note TestStand can pass data to LabVIEW VIs only by value. LabVIEW does not support

passing data by reference. You can return a value as an indicator, which TestStand treats as
a separate parameter.

Built-in Sequence Properties


Sequences have built-in properties that you can specify using the Sequence
Properties dialog box. For example, you can specify that the flow of
execution jumps to the Cleanup step group whenever a step sets the status
of the sequence to Failed.
Refer to the NI TestStand Help for more information about the Sequence
Properties dialog box.

Sequence Files
Sequence files can contain one or more sequences. Sequence files can also
contain global variables that all sequences in the sequence file can access.
Sequence files have built-in properties that you can specify using the
Sequence File Properties dialog box. For example, you can specify Load
and Unload Options that override the Load and Unload Options of all the
steps in all of the sequences in the file.
Refer to the NI TestStand Help for more information about the Sequence
File Properties dialog box.

Process Models
Testing a UUT requires more than just executing a set of tests. Usually, the
test system must perform a series of operations before and after it executes
the sequence that performs the tests. Common operations include
identifying the UUT, notifying the operator of pass/fail status, logging
results, and generating a test report. These operations define the testing
process. The set of such operations and their flow of execution is called a
process model.

National Instruments Corporation

1-13

NI TestStand Reference Manual

Chapter 1

TestStand Architecture

Some commercial test executives implement their process model internally


and do not allow you to modify them. Other test executives do not come
with a process model at all. TestStand comes with three predefined process
models that you can modify or replace: the Sequential model, the Parallel
model, and the Batch model. You can use the Sequential model to run a test
sequence on one UUT at a time. The Parallel and Batch models allow you
to run the same test sequence on multiple UUTs at the same time.
TestStand provides a mechanism for defining your own process model,
which is a sequence file that enables you to write different test sequences
without repeating standard testing operations in each sequence. This
modification is essential since the testing process can vary according to
your production line, your production site, or the systems and practices of
your company. You can edit a process model in the same way that you edit
your other sequence files.

Station Model
You can specify a process model file to use for all sequence files. This
process model file is called the station model file. The Sequential model is
the default station model file. You can use the Station Options dialog box
to select a different station model or to allow individual sequence files to
specify their own process model file.
Refer to the NI TestStand Help for more information about the Station
Options dialog box.

Main Sequence and Client Sequence File


In TestStand, the sequence that initiates the tests on a UUT is called the
Main sequence. While the process model defines what is constant about
your testing process, Main sequences define the steps that are unique to the
different types of tests you run. When you create a new sequence file,
TestStand automatically inserts a Main sequence in that file. The process
model invokes the Main sequence as part of the overall testing process.
You must name each Main sequence MainSequence.
You begin an execution from a Main sequence in one of your sequence
files. TestStand determines which process model file to use with the Main
sequence. TestStand uses the station model file unless the sequence file
specifies a different process model file and you have enabled the Allow
Other Models option in the Station Options dialog box to allow sequence
files to override your station model setting.

NI TestStand Reference Manual

1-14

ni.com

Chapter 1

TestStand Architecture

After TestStand identifies the process model to use with the Main sequence,
the file containing the Main sequence becomes a client sequence file of the
process model.

Entry Points
A process model defines a set of entry points. Each entry point is a
sequence in the process model file. By defining multiple entry points in a
process model, you give the test station operator different ways to invoke a
Main sequence or configure the process model.
The sequence for a Process Model entry point can contain calls to DLLs,
subsequences, Goto steps, and so on. You can specify two types of entry
pointsExecution entry points and Configuration entry points.
Refer to Chapter 3, Executions, for more information about entry points.

Automatic Result Collection


TestStand can automatically collect the results of each step. You can enable
or disable result collection for a step, a sequence, an execution, or for the
entire test station.
Each sequence has a local array that stores the results of each step. The
contents in the results for each step can vary depending on the step type.
When TestStand stores the results for a step into the array, it adds
information, such as the name of the step and its position in the sequence.
For a step that calls a sequence, TestStand also adds the result array from
the subsequence.
Refer to the Result Collection section of Chapter 3, Executions, for more
information about how TestStand collects results. Refer to Chapter 6,
Database Logging and Report Generation, for information about report
generation and database logging features for processing the collected test
results.

Callback Sequences
Callbacks are sequences that TestStand calls under specific circumstances.
You can create new callback sequences or you can override existing
callbacks to customize the operation of the test station. To add a callback
sequence to a sequence file, use the Sequence File Callbacks dialog box.
Refer to the NI TestStand Help for more information about the Sequence
File Callbacks dialog box.

National Instruments Corporation

1-15

NI TestStand Reference Manual

Chapter 1

TestStand Architecture

TestStand defines three categories of callbacks: Model callbacks, Engine


callbacks, and Front-End callbacks. The categories are based on the entity
that invokes the callback and the location in which you define the callback.
Model callbacks allow you to customize the behavior of a process model
for each Main sequence that uses it. Engine callbacks are defined by the
TestStand Engine and are invoked at specific points during execution.
Front-End callbacks are called by user interface programs to allow multiple
user interfaces to share the same behavior for a specific operation.
Table 1-2 illustrates the different types of callbacks.
Table 1-2. Callback Types

Callback Type

Where You Define the Callback

What Calls the Callback

Model Callbacks

The process model file defines Model


callbacks and the client sequence file or
StationCallbacks.seq can override
the callback

Sequences in the process


model file

Engine Callbacks

StationCallbacks.seq for Station


Engine callbacks, the process model file
for Process Model Engine callbacks, or a
regular sequence file for Sequence File
Engine callbacks

Engine

Front-End Callbacks

FrontEndCallbacks.seq

User interface application

Sequence Executions
When you run a sequence, TestStand creates an Execution object that
contains all of the information that TestStand needs to run your sequence
and the subsequences it calls. While an execution is active, you can start
another execution by running the same sequence again or by running a
different one. TestStand does not limit the number of executions that you
can run concurrently. An Execution object initially starts with a single
execution thread. You can use sequence call multithreading options to
create additional threads within an execution or to launch new executions.
An execution groups related threads so that setting a breakpoint suspends
all threads in the execution. In the same way, terminating an execution also
terminates all threads in that execution.

NI TestStand Reference Manual

1-16

ni.com

Sequence Files and Workspaces

This chapter describes TestStand sequence files and workspaces.

Sequence Files
A TestStand sequence file (.seq) is a file that contains any number of
sequences, a set of types used in the sequence file, and any global variables
shared by steps and sequences in the file.

Types of Sequence Files


TestStand contains the following types of sequence files:

NormalContains sequences that test UUTs

ModelContains process model sequences

Station CallbackContains Station callback sequences

Front-End CallbackContains Front-End callback sequences

Most sequence files you create are normal sequence files. Usually, your
computer has one Station callback sequence file and one Front-End
callback sequence file.
Normal sequence files can specify that they always use the station process
model, a specific process model, or no process model.
From within the TestStand Sequence Editor, use the Sequence File
Properties dialog box to set the type of sequence, the sequence file process
model settings, and other sequence file properties.
Refer to the NI TestStand Help for more information about the Sequence
File Properties dialog box.

Sequence File Callbacks


Callbacks are sequences that TestStand calls under specific circumstances.
Sequence files can contain sequences that override these callback
sequences. Use the Sequence File Callbacks dialog box to specify these
sequences.

National Instruments Corporation

2-1

NI TestStand Reference Manual

Chapter 2

Sequence Files and Workspaces

Refer to the NI TestStand Help for more information about the Sequence
File Callbacks dialog box. Refer to Chapter 10, Customizing Process
Models and Callbacks, for more information about callbacks and
overriding callback sequences.

Sequence File Globals


Each sequence file can contain any number of global variables. These
variables are accessible from any step or sequence within the sequence file
in which they are defined. View and edit the global variables in the
Variables pane. Use the Value column in the Variables pane to modify
string, numeric, and Boolean values.
Refer to the NI TestStand Help for more information about the Variables
pane.

Sequence File Type Definitions


Sequence files contain the type definitions for every step, property, and
variable that the sequence file contains. View and edit the types that a
sequence file contains in the Types pane.
Refer to the NI TestStand Help for more information about the Types pane.
Refer to Chapter 11, Type Concepts, for more information about types and
type editing.

Comparing and Merging Sequence Files


The Sequence File Differ is a tool that is available as a stand-alone
application and within the sequence editor that enables you to compare and
merge differences between two sequence files. The Sequence File Differ
compares the sequence files and presents the differences in a separate,
two-pane window.
Refer to the NI TestStand Help for more information about the Differ
window and Differ application.

NI TestStand Reference Manual

2-2

ni.com

Chapter 2

Sequence Files and Workspaces

Sequences
Each sequence can contain steps, parameters, and local variables. View and
edit the list of sequences in the Sequences pane of the Sequence File
window. View and edit the contents of a selected sequence in the Steps
pane of the Sequence File window.
Sequences have properties that you can view and edit from the Sequence
Properties dialog box. For more information about the Sequence Properties
dialog box, refer to the NI TestStand Help.

Step Groups
Sequences contain steps in three groups: Setup, Main, and Cleanup. You
can view and edit the step groups in the Steps pane of the Sequence File
window.
Use the Setup step group for steps that initialize or configure your
instruments, fixtures, and UUTs. Use the Main step group for steps that test
your UUTs. Use the Cleanup step group for steps that power down or
release handles to your instruments, fixtures, and UUTs.
Refer to the NI TestStand Help for more information about the Steps pane.

Parameters
Each sequence has its own list of parameters. Use these parameters to pass
data to and from a sequence when you call that sequence as a subsequence.
You can view and edit the parameters for a sequence in the Variables pane
of the Sequence File window. Use the Value column in the Variables pane
to modify string, numeric, and Boolean values.
Refer to the NI TestStand Help for more information about the Variables
pane.

National Instruments Corporation

2-3

NI TestStand Reference Manual

Chapter 2

Sequence Files and Workspaces

Local Variables
Use local variables to store data relevant to the execution of the sequence.
You can access local variables from within steps and code modules. You
can also use local variables for maintaining counts, holding intermediate
values, or any other purpose. View and edit the local variables for a
sequence on the Variables pane of the Sequence File window. Use the
Value column in the Variables pane to modify string, numeric, and Boolean
values.
Refer to the NI TestStand Help for more information about the Variables
pane.

Sequence File Window and Views


Within the TestStand Sequence Editor, you can view and edit sequence
files in the Sequence File window, which is illustrated in Figure 2-1.

Figure 2-1. Sequence File Window and Insertion Palette

NI TestStand Reference Manual

2-4

ni.com

Chapter 2

Sequence Files and Workspaces

To open an existing sequence file in the Sequence File window, select File
Open Sequence File. To create a new Sequence File window, select File
New Sequence File.
The Sequence File window contains the following panes:

SequencesDisplays a list of sequences in a file. Use this pane to


create new sequences and to cut, copy, and paste sequences.

StepsDisplays the steps in a specific sequence. The Steps pane has


three groups: Setup, Main, and Cleanup. Expand the Setup, Main, or
Cleanup group to view its contents.

VariablesDisplays the variables that the selected steps in the Steps


pane can access at run time. The variables include locals, parameters,
file globals, station globals, and runstate information that is accessible
when TestStand executes the sequence.

Refer to the NI TestStand Help for more information about the Sequence
File window and its panes.

Workspaces
In TestStand, you can create a workspace to organize and access your
development files. A TestStand workspace file (.tsw) contains references
to any number of TestStand project files. A TestStand project file (.tpj)
contains references to any number of other files of any type.
Use TestStand project files to organize related files in your test system. You
can insert any number of files into a project. You can also insert folders in
a project to contain files or other folders.
In the sequence editor, you use the Workspace pane to view and edit a
workspace file and the project files it references. You can have only one
workspace file open at a time. To open an existing workspace file, select
FileOpen Workspace File. To create a new workspace file, select File
New Workspace File.
The TestStand Deployment Utility also uses a workspace to specify the
files to include in the deployment image or installer that the utility creates.
Refer to the NI TestStand Help for more information about the Workspace
pane.

National Instruments Corporation

2-5

NI TestStand Reference Manual

Chapter 2

Sequence Files and Workspaces

Source Code Control


You can use workspace files in TestStand to access your files in a source
code control (SCC) system. To perform SCC operations on your files from
within TestStand, select a SCC provider on the Source Control tab on
the Station Options dialog box, and configure the SCC settings for the
workspace on the Source Control tab of the Workspace Object Properties
dialog box.
Note National Instruments has tested TestStand with Microsoft Visual SourceSafe,

Perforce, MKS Source Integrity, Rational ClearCase, and Merant PVCS.


Refer to the NI TestStand Help for more information about using SCC tools
with TestStand.

System Deployment
The TestStand Deployment Utility uses workspace and project files to
collect all of the files required to successfully distribute your test system to
a target computer. The deployment utility also creates an installer for your
test system.
Refer to Chapter 14, Deploying TestStand Systems, for more information
about system deployment and the TestStand Deployment Utility.

NI TestStand Reference Manual

2-6

ni.com

Executions

An execution is an object that contains all of the information that TestStand


uses to run your sequence and subsequences. When an execution is active,
you can start other executions by running the same sequence again or by
running different sequences. TestStand does not limit the number of
executions you can run concurrently. An execution may start with a single
thread and then launch additional threads. When you suspend, terminate, or
abort an execution, you stop all threads in that execution.
Whenever TestStand begins executing a sequence, it makes a run-time copy
of the sequence local variables and the custom properties of the steps in
a sequence. If the sequence calls itself recursively, TestStand creates a
separate run-time copy of the local variables and custom step properties for
each running instance of the sequence. Modifications to the values of local
variables and custom step properties apply only to the run-time copy and
do not affect the sequence file in memory or on disk.
Note Built-in properties of steps and sequences are flagged to be shared at run time.

For these shared properties, TestStand does not create a unique run-time copy, but instead
references the edit-time copy. Any changes to the run-time reference of these built-in
properties edits the original Step or Sequence object in the sequence file.
For each execution thread, TestStand maintains an execution pointer
that points to the current step, a call stack, and a run-time copy of the
local variables and custom properties for all sequences and steps on the
call stack.
The Execution tab on the Station Options dialog box provides a number of
execution options that control tracing, breakpoints, and result collection.
Refer to the NI TestStand Help for more information about the Execution
tab on the Station Options dialog box.

Sequence Context
Before executing the steps in a sequence, TestStand creates a run-time copy
of the sequence. This allows TestStand to maintain separate local variable
and step property values for each sequence invocation.

National Instruments Corporation

3-1

NI TestStand Reference Manual

Chapter 3

Executions

TestStand maintains a sequence context that contains references to the


run-time copy of the sequence, to all global variables, and to step properties
in the active sequence. The contents of a sequence context can vary
depending on the currently executing step. For more information about the
contents of the sequence context, refer to the NI TestStand Help.

Using the Sequence Context


In expressions, you can access the value of a variable or property by
specifying a path from the sequence context to the particular variable or
property. For example, you can set the status of a step using the following
expression:
Step.Result.Status = "Passed"

During an execution, you can view and modify the values of the properties
in the sequence context from the Variables pane on the Execution window.
The Variables pane displays the sequence context for the sequence
invocation that is currently selected in the Call Stack pane. You can also
monitor individual variables or properties from the Watch View pane. Refer
to the NI TestStand Help for more information about using the Variables
pane, Watch View pane, and Call Stack pane of the Execution window.
You can pass a reference to a SequenceContext object to a code module.
In code modules, you access the value of a variable or property by using
PropertyObject methods in the TestStand API with the sequence context.
As with expressions, you must specify a path from the sequence context to
the particular property or variable. Refer to Chapter 5, Adapters, for more
information about passing the SequenceContext object to a code module
for each adapter. Refer to the NI TestStand Help for more information about
accessing the properties in the sequence context from code modules.
Select ViewSequence FileVariables or ViewExecutionVariables in
the sequence editor to open the Variables pane, which contains the names
of variables, properties, and sequence parameters that you can access from
expressions and code modules. Refer to the NI TestStand Help for more
information about the Variables pane.
Note Some properties are not populated until run time.

NI TestStand Reference Manual

3-2

ni.com

Chapter 3

Executions

Lifetime of Local Variables, Parameters, and


Custom Step Properties
Multiple instances of a sequence can run at the same time, such as when
you call a sequence recursively or when a sequence runs in multiple
concurrent threads. Each instance of the sequence has its own copy of
the sequence parameters, local variables, and custom properties of each
step. When a sequence completes, TestStand discards the values of the
parameters, local variables, and custom properties.

Sequence Editor Execution Window


The sequence editor displays each execution in a separate Execution
window. Figure 3-1 illustrates the Execution window.

Figure 3-1. Sequence Editor Execution Window

Refer to the NI TestStand Help for more information about the Execution
window.

National Instruments Corporation

3-3

NI TestStand Reference Manual

Chapter 3

Executions

Starting an Execution
You can initiate an execution by launching a sequence through an
Execution entry point, by launching a sequence directly, or by executing
a group of steps interactively.

Execution Entry Points


You can start an execution through an Execution entry point only when
a sequence file that contains a sequence with the name MainSequence
occupies the active window. A list of Execution entry points appears in the
Execute menu of the sequence editor.
Each Execution entry point in the menu represents a separate entry point
sequence in the process model that applies to the active sequence file. When
you select an Execution entry point from the Execute menu, you are
actually running an entry point sequence in a process model file. The
Execution entry point sequence, in turn, invokes the Main sequence
one time or multiple times.
Execution entry points in a process model give the test station operator
different ways to invoke a Main sequence. Execution entry points handle
common operations, such as UUT identification and test report generation.
For example, the default TestStand process model provides two Execution
entry points: Test UUTs and Single Pass. The Test UUTs Execution entry
point initiates a loop that repeatedly identifies and tests UUTs. The Single
Pass Execution entry point tests a single UUT without identifying it.
Refer to Chapter 10, Customizing Process Models and Callbacks, and
Appendix A, Process Model Architecture, for more information about
using process models in TestStand.

Executing a Sequence Directly


To execute a sequence without using a process model, select
Run <Sequence Name> from the Execute menu, where <Sequence
Name> is the name of the sequence you are currently viewing. This
command executes the sequence directly, skipping the process model
operations, such as UUT identification and test report generation. You can
use this method to execute any sequence.
Tip

Executing a sequence directly is best for performing unit testing or debugging.

NI TestStand Reference Manual

3-4

ni.com

Chapter 3

Executions

Interactively Executing Steps


To interactively execute selected steps in a sequence, select
Run Selected Steps or Loop On Selected Steps from the context menu
or from the Execute menu in the sequence editor or user interfaces.
There are two ways that you can run steps in interactive mode:

Run steps interactively from a Sequence File window. This creates a


new execution called a root interactive execution. You can set station
options to control whether the Setup and Cleanup step groups of the
sequence run as part of a root interactive execution.

Run steps interactively from an existing Execution window for a


normal execution that is suspended at a breakpoint by selecting
Run Selected Steps or Loop On Selected Steps. The selected steps run
within the context of the normal execution. This is called a nested
interactive execution.
The steps that you run interactively can access the variable values of
the normal execution and add to its results. If you used the process
model for the original execution, these results are included in the test
report. When the selected steps complete, the execution returns to the
step at which it was originally suspended. A configurable station
option specifies whether step failures and errors propagate to the
original execution.

In interactive mode, the selected steps run in the order in which they appear
in the sequence. A configurable station option specifies whether a branch
operation is allowed to a specific step or a non-selected step, or whether
only the selected steps in a sequence execute, regardless of any branching
logic that the sequence contains.
To configure whether TestStand evaluates preconditions when executing
interactively, select ConfigureStation Options and enable the Evaluate
Preconditions option in the Interactive Executions section of the
Execution tab on the Station Options dialog box. You can also use this
dialog box to configure whether interactive executions branch to unselected
steps in the Branching Mode control. Refer to the NI TestStand Help for
more information about the Station Options dialog box.

Terminating and Aborting Executions


The menus in the sequence editor and user interfaces include commands
that allow you to stop execution before the execution has completed
normally. The TestStand API has corresponding methods that allow you to
stop execution from inside of a code module or to determine whether the

National Instruments Corporation

3-5

NI TestStand Reference Manual

Chapter 3

Executions

execution has been stopped. You can stop one execution or all executions
by issuing a stop request at any time. Stop requests do not take effect in
each execution until the currently executing code module returns control.
You can stop executions in two ways:

When you terminate an execution, all the cleanup steps in the


sequences on the call stack run before execution ends. Also, if you
terminate an execution while the client sequence file is still running,
the process model will continue to run, possibly testing the next UUT
or generating a test report.

When you abort an execution, the cleanup steps do not run, and the
process model does not continue. Abort an execution in cases when
you want an execution to completely stop as soon as possible. In
general, it is better to terminate execution so that the cleanup steps can
return your system to a known state.

Note You should only abort an execution when you are debugging and when you are sure

that it is safe to skip the cleanup steps for a sequence.

Execution Debugging Panes


Use the following panes to help you gather information while single
stepping through an execution.

Threads and Call Stack panesThe Threads pane displays the


threads running in the execution and selects the active thread to view.
The Call Stack pane displays the sequence invocations for the active
thread and selects the active sequence invocation to view.
Refer to the NI TestStand Help for more information about the Threads
and Call Stack panes.

Variables paneDisplays the sequence context for the sequence


invocation that is currently selected in the Call Stack pane. The
sequence context contains all the variables and properties that the steps
in the selected sequence invocation can access. Use the Variables pane
to examine and modify the values of these variables and properties.
Refer to the NI TestStand Help for more information about the
Variables pane.

NI TestStand Reference Manual

3-6

ni.com

Chapter 3

Executions

Watch View paneDisplays the values of watch expressions that you


enter. The sequence editor updates the values in the Watch View pane
when execution suspends at a breakpoint. If tracing is enabled, the
sequence editor also updates the values after executing each step and
highlights values that change in red.
Refer to the NI TestStand Help for more information about the Watch
View pane.

Output paneDisplays generic messages, warnings, and error


messages that the OutputMessage expression function and the
OutputMessage.Post method generate. Each message specifies a
severity and a timestamp. The message can also specify an icon,
a category, and additional execution information. By default, the
sequence editor generates output messages for any information that
a SCC provider generates.
Refer to the NI TestStand Help for more information about the
Output pane.

Result Collection
TestStand can automatically collect the results of each step. You can
configure this feature for each step on the Run Options panel of the Step
Settings pane. You can disable result collection for an entire sequence in
the Sequence Properties dialog box or completely disable result collection
on your computer in the Station Options dialog box.
Each sequence has a ResultList local variable, which is an empty array of
container properties. TestStand appends a new container property, the step
result, to the end of the ResultList array before a step executes. After the
step executes, TestStand automatically copies the contents of the Result
subproperty for the step into the step result.
Each step type can define different contents for its Result subproperty, and
TestStand can append step results that contain Result properties from
different step types to the same ResultList array. When TestStand copies the
Result property for a step to its step result, it also adds the name of the step,
its position in the sequence, and other identifying information. For a step
that calls a subsequence, TestStand also adds the ResultList array variable
from the subsequence.
Through the TestStand API, a process model can request that TestStand
insert additional step properties in the step results for all steps
automatically. A code module can also use the TestStand API to insert
additional step result information for a particular step.

National Instruments Corporation

3-7

NI TestStand Reference Manual

Chapter 3

Executions

Refer to the NI TestStand Help for more information about the Step
Settings pane, Sequence Properties dialog box, and the Station Options
dialog box.

Custom Result Properties


Because each step type can have a different set of subproperties under
its Result property, the step result varies according to the step type.
Table 3-1 lists the custom properties that the step result can contain for
steps that use one of the built-in step types.
Table 3-1. Custom Properties in the Step Results for Steps that
Use the Built-In Step Types

Custom Step Property

NI TestStand Reference Manual

Step Types that Use the Property

Error.Code

All

Error.Msg

All

Error.Occurred

All

Status

All

Common

All

Numeric

Numeric Limit Test,


Multiple Numeric Limit Test

PassFail

Pass Fail Test

Limits.String

String Value Test

ButtonHit

Message Popup

Response

Message Popup

ExitCode

Call Executable

NumPropertiesRead

Property Loader

NumPropertiesApplied

Property Loader

ReportText

All

Limits.Low

Numeric Limit Test,


Multiple Numeric Limit Test,
String Value Test

Limits.High

Numeric Limit Test,


Multiple Numeric Limit Test

3-8

ni.com

Chapter 3

Executions

Table 3-1. Custom Properties in the Step Results for Steps that
Use the Built-In Step Types (Continued)

Custom Step Property

Step Types that Use the Property

Comp

Numeric Limit Test,


Multiple Numeric Limit Test

Measurement

Multiple Numeric Limit Test

AsyncID

Sequence Call

AsyncMode

Sequence Call

Note Table 3-1 does not include the result properties for Synchronization, IVI, Database,

or LabVIEW utility step types. For more information about these step types, refer to
Appendix B, Synchronization Step Types; Appendix C, Database Step Types;
Appendix D, IVI-C Step Types; and Appendix E, LabVIEW Utility Step Types.
In the case of the Numeric Limit Test and the String Value Test, the
Limits.Low, Limits.High, Limits.String, and Comp properties are not
subproperties of the Result property. Therefore, TestStand does not
automatically include these properties in the step result. Depending
on options you set during the step configuration, the default process
model uses the TestStand API to include the Limits.Low, Limits.High,
Limits.String, and Comp properties in the step results for Numeric Limit
Test and String Value Test steps that contain these properties.
For the Sequence Call step type, the AsyncID and AsyncMode properties
are not subproperties of the Result property. TestStand adds these
properties to the step results for Sequence Call steps that call subsequences
asynchronously.
The Common result subproperty uses the CommonResults custom data
type. The Common property is a subproperty of the Result property for
every built-in step type. Consequently, you can add a subproperty to the
result of every step type by adding a subproperty to the definition of the
CommonResults custom data type.
Be aware that if you modify CommonResults without incrementing the
type version number, you may see a type conflict when you open other
sequence files. These conflicts can include FrontEndCallbacks.seq
when you are logging in or out. TestStand will automatically prompt you to
increment the version number when saving changes to any data type or
step type.

National Instruments Corporation

3-9

NI TestStand Reference Manual

Chapter 3

Executions

Standard Result Properties


In addition to copying step properties to step results, TestStand also adds
a set of standard properties to each step result as subproperties of the TS
property. Table 3-2 lists the standard step result properties.
Table 3-2. Standard Step Result Properties

Standard Result Property

Description

TS.StartTime

Time at which the step began executing, specifically, the


number of seconds since the TestStand Engine initialized.

TS.TotalTime

Number of seconds the step took to execute. This time includes


the time for all step options, including preconditions,
expressions, post actions, module loading, and module
execution.

TS.ModuleTime

Number of seconds that the code module took to execute.

TS.Index

Zero-based position of the step in the step group.

TS.StepName

Name of the step.

TS.StepGroup

Step group that contains the step. The values are Main, Setup,
or Cleanup.

TS.StepId

Unique Step Id, which is a GUID that TestStand represents as


a string. The strings begin with "ID#:", contain 26 characters,
only alphanumeric characters and the special characters: ''#'',
'':'', ''+'' and ''/''.
TestStand attempts to maintain globally unique step Ids,
however, copying files on disk does not prevent duplicate Ids.

TS.Id

A number that TestStand assigns to the step result. The number


is unique with respect to all other step results in the current
TestStand session.

TS.InteractiveExeNum

A number that TestStand assigns to an interactive execution.


The number is unique with respect to all other interactive
executions in the current TestStand session. TestStand adds
this property only if you run the step interactively.

TS.StepType

Name of the step type.

TS.Server

This property contains the name of the server machine on which


the step runs the subsequence it calls. This result property exists
only for Sequence Call steps that run subsequences on a remote
machine.

NI TestStand Reference Manual

3-10

ni.com

Chapter 3

Executions

Table 3-2. Standard Step Result Properties (Continued)

Standard Result Property

Description

TS.StepCausedSequenceFailure

This property exists only if the step fails. The value is True if
the step failure causes the sequence to fail. The value is False
if the step failure does not cause the sequence to fail or if the
sequence has already failed.

TS.BlockLevel

Indicates the number of blocks that encloses the step, such as If


and For steps. The value is zero for top-level steps.

Subsequence Results
If a step calls a subsequence or generates a call to a callback sequence,
TestStand creates a special step result subproperty to store the result of the
subsequence unless the callback or sequence disables results. Table 3-3
lists the name of the subproperty for each type of subsequence call.
Table 3-3. Property Names for Subsequence Results

Result Subproperty Name

Type of Subsequence Call

TS.SequenceCall

Sequence Call

TS.PostAction

Post Action Callback

TS.SequenceFilePreStep

SequenceFilePreStep Callback

TS.SequenceFilePostStep

SequenceFilePostStep Callback

TS.ProcessModelPreStep

ProcessModelPreStep Callback

TS.ProcessModelPostStep

ProcessModelPostStep Callback

TS.StationPreStep

StationPreStep Callback

TS.StationPostStep

StationPostStep Callback

TS.SequenceFilePreInteractive

SequenceFilePreInteractive Callback

TS.SequenceFilePostInteractive

SequenceFilePostInteractive Callback

TS.ProcessModelPreInteractive

ProcessModelPreInteractive Callback

TS.ProcessModelPostInteractive

ProcessModelPostInteractive Callback

TS.StationPreInteractive

StationPreInteractive Callback

TS.StationPostInteractive

StationPostInteractive Callback

TS.SequenceFilePostResultListEntry

SequenceFilePostResultListEntry Callback

National Instruments Corporation

3-11

NI TestStand Reference Manual

Chapter 3

Executions

Table 3-3. Property Names for Subsequence Results (Continued)

Result Subproperty Name

Type of Subsequence Call

TS.ProcessModelPostResultListEntry

ProcessModelPostResultListEntry Callback

TS.StationPostResultListEntry

StationPostResultListEntry Callback

TS.SequenceFilePostStepRuntimeError

SequenceFilePostStepRuntimeError Callback

TS.ProcessModelPostStepRuntimeError

ProcessModelPostStepRuntimeError Callback

TS.StationPostStepRuntimeError

StationPostStepRuntimeError Callback

TS.SequenceFilePostStepFailure

SequenceFilePostFailure Callback

TS.ProcessModelPostStepFailure

ProcessModelPostFailure Callback

TS.StationPostStepFailure

StationFilePostFailure Callback

TestStand adds the following properties to the subproperty for each


subsequence:

SequenceFileAbsolute path of the sequence file that contains the


subsequence.

SequenceName of the subsequence called by the step.

StatusStatus of the subsequence called by the step.

ResultListValue of Locals.ResultList for the subsequence that the


step called. This property contains the results for the steps in the
subsequence.

Loop Results
When you configure a step to loop, you can use the Record Result of Each
Iteration option on the Looping panel of the Step Settings pane to direct
TestStand to store a separate result for each loop iteration in the result list.
In the result list, the results for the loop iterations come immediately after
the result for the step as a whole.
TestStand adds a TS.LoopIndex numeric property to each loop iteration
result to record the value of the loop index for that iteration. TestStand also
adds the following special loop result properties to the main result for the
step.

NI TestStand Reference Manual

TS.EndingLoopIndexValue of the loop index when looping


completes.

TS.NumLoopsNumber of times the step loops.

3-12

ni.com

Chapter 3

Executions

TS.NumPassedNumber of loops for which the step status is


Passed or Done.

TS.NumFailedNumber of loops for which the step status is


Failed.

Report Generation
When you run a sequence using the Test UUTs or Single Pass Execution
entry point, the default process model generates the test report by traversing
the results for the Main sequence in the client sequence file and all of the
subsequences it calls.
Refer to the Process Models section of Chapter 1, TestStand Architecture;
Chapter 10, Customizing Process Models and Callbacks; and Appendix A,
Process Model Architecture, for more information about process models.
Refer to Chapter 6, Database Logging and Report Generation, for more
information about report generation.

Engine Callbacks
TestStand specifies a set of callback sequences that it invokes at specific
points during execution. These callbacks are called Engine callbacks.
Engine callbacks are a way for you to tell TestStand to call certain
sequences before and after the execution of individual steps, before and
after interactive executions, after loading a sequence file, and before
unloading a sequence file. Because the TestStand Engine controls the
execution of steps and the loading and unloading of sequence files,
TestStand defines the set of Engine callbacks and their names.
Refer to Chapter 10, Customizing Process Models and Callbacks, for more
information about Engine callbacks.

Step Execution
Depending on the options you set during step configuration, a step
performs a number of actions as it executes. Table 3-4 lists the most
common actions that a step can take, in the order that the step performs
them.

National Instruments Corporation

3-13

NI TestStand Reference Manual

Chapter 3

Executions

Table 3-4. Order of Actions that a Step Performs

Action Number

Description

Remarks

Allocate step result

Enter batch synchronization


section

Evaluate precondition

Acquire step lock

If option is set

Check run mode

Load module if not already loaded

Step switching executes

Evaluate Loop Initialization


expression

Only if looping

Evaluate Loop While expression,


skip to Action Number 23
if False

Only if looping

10

Allocate loop iteration result

Only if looping

11

Call Pre-Step Engine callbacks

12

Evaluate Pre-Expression

13

Call Pre-Step substeps for


step type

14

Call module

15

Call Post-Step substeps for


step type

TestStand calls Post-Step substeps


even if the user code module
generates a run-time error. This
enables Post-Step substeps to
perform error handling,
if appropriate.

16

Evaluate Post-Expression

17

Evaluate Status expression

18

Call Post-Step Engine callbacks

NI TestStand Reference Manual

3-14

If option is set
If False, perform Action
Number 25, then proceed to Action
Number 29

ni.com

Chapter 3

Executions

Table 3-4. Order of Actions that a Step Performs (Continued)

Action Number

Description

Remarks

19

Call PostStepFailure Engine


callback

Only if loop iteration fails

20

Fill out loop iteration result

Only if looping

21

Call PostResultListEntry Engine


callback

Only if looping

22

Evaluate Loop Increment


expression, return to Action
Number 9

Only if looping

23

Evaluate Loop Status expression

Only if looping

24

Switching routes with step lifetime


disconnected

25

Unload module if required

26

Update sequence failed state

27

Call PostStepFailure Engine


callback

28

Execute post action

29

Release step lock

If option is set

30

Exit batch synchronization section

If option is set

31

Fill out step result

32

Call PostResultListEntry Engine


callback

Only if step fails

Usually, a step performs only a subset of these actions, depending on the


configuration of the step and the test station. When TestStand detects a
run-time error, it calls the PostStepRuntimeError callbacks. If these
callbacks are not defined or if they do not reset the error state for the step,
TestStand performs Action Number 25 and then proceeds to Action
Number 29. If a run-time error occurs in a loop iteration, TestStand
performs Action Number 20 before performing Action Numbers 25 and 29.

National Instruments Corporation

3-15

NI TestStand Reference Manual

Chapter 3

Executions

Step Status
Every step in TestStand has a Result.Status property. The status property is
a string that indicates the result of the step execution. Although TestStand
imposes no restrictions on the values to which the step or its code module
can set the status property, TestStand and the built-in step types use and
recognize the values that appear in Table 3-5.
Table 3-5. Standard Values for the Status Property

String Value

Meaning

Source of the
Status Value

Passed

Indicates that the step performed a test that passed.

Step or code module

Failed

Indicates that the step performed a test that failed.

Step or code module

Error

Indicates that a run-time error occurred.

TestStand

Done

Indicates that the step completed without setting its


status.

TestStand

Terminated

Indicates that the step did not set the status and a
request to terminate the execution occurred while
executing the step. When a status of terminated
is returned to a calling sequence and the Ignore
Termination option on the Run Options panel of the
Step Settings pane for a Sequence Call step is enabled,
the request to terminate the execution is not returned
and the step status is set to terminated. If in this
scenario, the Ignore Termination option is not enabled,
the Sequence Call step status is set to a non-terminating
status and the request for termination is returned to the
calling sequence invocation.

TestStand

Note: The status of the execution is set to Terminated if


the request to terminate the execution is returned to the
root sequence invocation.
Skipped

Indicates that the step did not execute because the run
mode for the step is Skip.

TestStand

Running

Indicates that the step is currently running.

TestStand

Looping

Indicates that the step is currently running in loop


mode.

TestStand

NI TestStand Reference Manual

3-16

ni.com

Chapter 3

Executions

Failures
TestStand considers a step to have failed if the step executes and the step
status is Failed. If you enable the Step Failure Causes Sequence Failure
option on the Run Options panel of the Step Settings pane, TestStand sets
the sequence status to Failed when the step fails. When the sequence
returns as Failed, the Sequence Call step also fails. In this way, a step
failure in a subsequence can propagate up through the chain of Sequence
Call steps.
Note For most step types, the Step Failure Causes Sequence Failure option is enabled by

default.
You can also control how execution proceeds after a step failure causes a
sequence to fail. To configure an execution to jump to the Cleanup step
group upon failure, enable the Immediately Goto Cleanup on Sequence
Failure option in the Sequence Properties dialog box. By default, this
option is disabled.

Terminations
When you request to terminate an execution, the currently executing
sequence invocation for each thread immediately calls the Cleanup step
group. When a terminating subsequence returns to a calling sequence, the
calling sequence continues the termination process down the call stack
unless the Ignore Termination option on the Run Options panel of the Step
Settings pane is enabled for the Sequence Call step. If enabled, the
termination of the execution is ignored for that thread and the thread
execution continues normally. If the request to terminate the execution is
returned to the root sequence invocation, TestStand sets the result status for
the execution to Terminated.

Run-Time Errors
TestStand generates a run-time error if it encounters a condition that
prevents a sequence from executing. If, for example, a precondition refers
to the status of a step that does not exist, TestStand generates a run-time
error when it attempts to evaluate the precondition. TestStand also
generates a run-time error when a code module causes an access
violation or any other exception.

National Instruments Corporation

3-17

NI TestStand Reference Manual

Chapter 3

Executions

TestStand does not use run-time errors to indicate UUT test failures.
Instead, a run-time error indicates that a problem exists with the testing
process itself and that testing cannot continue. Usually, a code module
reports a run-time error if it detects an error in a hardware or software
resource that it uses to perform a test.
TestStand allows you to decide interactively how to handle a run-time error.
To interactively handle a run-time error, configure TestStand to launch the
Run-Time Error dialog box in the event of an error by selecting Show
Dialog from the On Run-Time Error ring control on the Execution tab on
the Station Options dialog box. Refer to the NI TestStand Help for more
information about the Station Options and Run-Time Error dialog boxes.
TestStand also allows you to invoke a PostStepRunTimeError callback
when a run-time error occurs. Refer to Chapter 10, Customizing Process
Models and Callbacks, for more information about Engine callbacks.

NI TestStand Reference Manual

3-18

ni.com

Built-In Step Types

This chapter describes the core set of built-in step types that TestStand
provides and groups them into the following categories:

Step types that you can use with any module adapter. Step types such
as the Numeric Limit Test and the String Value Test call any code
module you specify. They also might perform additional actions, such
as comparing a value the code module returns with limits you specify.

Step types that always use a specific module adapter to call code
modules. Sequence Call is the only step type in this category.

Step types that perform a specific action and do not require you to
specify a code module. Step types such as Message Popup, Statement,
and Flow Control perform actions that you configure in an edit tab or
edit dialog box that is specific to the step type.

Note TestStand also includes sets of application-specific step types. For example,

TestStand provides sets of step types that make it easier to synchronize multiple threads,
access databases, control IVI instruments, and access VIs and remote systems. For more
information about these step types, refer to Appendix B, Synchronization Step Types;
Appendix C, Database Step Types; Appendix D, IVI-C Step Types; and Appendix E,
LabVIEW Utility Step Types.

Overview
This section describes general features of built-in step types.

Using Step Types


Use step types when you insert steps in the Setup, Main, and Cleanup
groups of the Steps pane in the Sequence File window. You can insert a step
using the Step Types list in the Insertion Palette or the Insert Step item in
the context menu for the Steps pane. The Insertion Palette and the Insert
Step item in the context menu list all of the available step types. Refer to
the NI TestStand Help for more information about the Insertion Palette.
Figure 4-1 shows the Insertion Palette.

National Instruments Corporation

4-1

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

Figure 4-1. Insertion Palette

When you insert a step type from the Insertion Palette or the context menu,
TestStand creates a step using the step type and the currently selected
module adapter indicated in the Insertion Palette or toolbar. After you insert
the step, select Specify Module from the context menu to specify the code
module or sequence, if any, that the step calls. The Specify Module
command displays a Module tab on the Step Settings pane that is different
for each adapter. Refer to Chapter 5, Adapters, and the NI TestStand Help
for information about the Module tab for each adapter.
For each step type, other items can appear in the context menu above the
Specify Module item. For example, the Edit Limits item appears in the

NI TestStand Reference Manual

4-2

ni.com

Chapter 4

Built-In Step Types

context menu for Numeric Limit Test steps, and the Edit Data Source item
appears in the context menu for Pass/Fail Test steps. Select the menu item
to display a step-type-specific pane or launch a step-type-specific dialog
box, in which you can modify step properties that are specific to the step
type. Refer to the NI TestStand Help for information about the menu item
for each of the built-in step types.
To modify step properties that are common to all step types, select the
Properties tab on the Step Settings pane. Refer to the NI TestStand Help for
more information about the Step Settings pane.
Note The Insertion Palette also contains a Templates list which you use to hold copies of

sequences, steps, and variables that you reuse during the development of sequence files.
Refer to the NI TestStand Help for more information about the Templates list of the
Insertion Palette.

Built-In Step Properties


TestStand steps feature a number of built-in properties that you can specify
using the various panels on the Properties tab of the Step Settings pane. The
following list explains the capabilities of each built-in step property:

General Panel

NameSpecifies the name of the step.

TypeSpecifies the type the step is an instance of.

AdapterSpecifies the adapter that the step uses to call a code


module.

IconSpecifies the icon to display for the step.

CommentSpecifies the comment of the step.

Run Options Panel

Load/Unload OptionsSpecifies how TestStand loads and unloads


the code modules or subsequences that are invoked by each step.

Run ModeSpecifies whether TestStand skips a step or forces the


step to pass or fail without executing the code module of the step.

Precondition Evaluation in Interactive ModeSpecifies whether


TestStand evaluates the step precondition when you run the step
interactively.

TestStand Window ActivationSpecifies whether the TestStand


application activates its window when the step completes.

National Instruments Corporation

4-3

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

Sequence Call Trace SettingSpecifies whether TestStand traces


the steps in the subsequence that the step calls. This property exists
only for Sequence Call steps.

Record ResultsSpecifies whether TestStand collects the results for


this step. Refer to the Result Collection section of Chapter 3,
Executions, for more information.

Step Failure Causes Sequence FailureSpecifies whether


TestStand sets the status of the sequence to Failed when the status of
the step is Failed.

Ignore Run-Time ErrorsSpecifies whether TestStand continues


execution normally after the step even though a run-time error occurs
in the step.

Some run-time errors can place your system in a bad state and continuing with
the execution can result in an undefined behavior.

Caution

Ignore TerminationSpecifies whether a Sequence Call step ignores


the request to terminate execution.

Looping Panel

LoopSpecifies whether the step executes once or multiple times


before executing the next step. You can specify the conditions under
which to terminate the loop. You can also specify whether to collect
results for each loop iteration, for the loop as a whole, or for both.

Post Actions Panel

Post ActionsSpecifies whether TestStand executes a specific


sequence or jumps to other steps after executing the step, depending on
the pass/fail status of the step or any custom condition.

Switching Panel

SwitchingSpecifies whether TestStand performs any switching


operations when the step executes.

Synchronization Panel

NI TestStand Reference Manual

SynchronizationSpecifies whether a step should block another


instance of the step from executing at the same time in a different
thread.

4-4

ni.com

Chapter 4

Built-In Step Types

Expressions Panel

Pre-ExpressionsSpecifies an expression to evaluate before


executing the code module of the step.

Post-ExpressionsSpecifies an expression to evaluate after


executing the code module of the step.

Status ExpressionSpecifies an expression that determines the value


of the status property of the step.

Preconditions Panel
Specifies the conditions that must be True for TestStand to execute the step
during the normal flow of execution in a sequence.

Requirements Panel
Notates product and unit requirements that a step covers.

Property Browser Panel


Displays the built-in and custom properties for a step.
Use the Properties tab on the Step Settings pane to modify the values of the
built-in step properties. You can usually modify the values of custom step
properties using the tabs on the Step Settings pane. If the step type does not
have a tab for the custom properties, select the Property Browser panel to
view the custom properties for that step. Although code modules usually do
not modify the values of the built-in step properties at run time, they often
modify and read the values of the custom step properties when determining
the pass/fail status.
Refer to the NI TestStand Help for more information about the Properties
tab on the Step Settings pane.

Custom Properties That All Built-In Step Types Share


Each step type defines its own set of custom properties. All steps that use
the same step type have the same set of custom properties.
All built-in step types contain the following custom properties:

Step.Result.Error.CodeCode that describes the error that


occurred.

Step.Result.Error.MsgMessage string that describes the error that


occurred.

National Instruments Corporation

4-5

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

Step.Result.Error.OccurredBoolean flag that indicates whether a


run-time error occurred in the step. TestStand documentation refers to
this property as the error occurred flag.

Step.Result.StatusSpecifies the status of the last execution of the


step, such as Done, Passed, Failed, Skipped, or Error. TestStand
documentation refers to this property as the step status.

Step.Result.ReportTextContains a message string that TestStand


includes in the report.

Step.Result.CommonPlaceholder container that you can


customize. To customize the container, modify the CommonResults
standard data type. Refer to the Using Data Types section of
Chapter 12, Standard and Custom Data Types, for more information
about standard TestStand data types.

Error Occurred Flag, Step Status, and Run-Time Errors


The error occurred flag can become True in the following situations:

A run-time error condition occurs and the code module or module


adapter sets the value to True.

An exception occurs in the code module or at any other time during


step execution.

When a step finishes execution and the error occurred flag is True, the
TestStand Engine responds as follows:

Makes no evaluation of status and post-expressions for a step. Instead,


TestStand sets the step status to Error.

Evaluates the Ignore Run-Time Errors step property.

If False, TestStand reports the run-time error to the sequence.

If True, TestStand continues execution normally after the step.

Before TestStand executes a step, it sets the step status to Running or


Looping. When a step finishes execution and the error occurred flag is
False, the TestStand Engine responds as follows: when the step status is
still Looping or Running, TestStand changes the step status to Done.
The step status becomes Passed or Failed only when a code module,
module adapter, or step type explicitly sets the step status to Passed or
Failed.
Refer to Chapter 5, Adapters, for more information about the assignments
that module adapters make to and from step properties.

NI TestStand Reference Manual

4-6

ni.com

Chapter 4

Built-In Step Types

Step Types That You Can Use with Any Module Adapter
TestStand comes with five built-in step types that you can use with any
module adapter: Pass/Fail Test, Numeric Limit Test, Multiple Numeric
Limit Test, String Value Test, and Action. When you insert a step in a
sequence, you must select a module adapter in the Step Types list of the
Insertion Palette or from the Adapter ring control, which is located on the
sequence editor toolbar. TestStand then assigns the adapter you selected
when you insert the step.
The icon for the adapter appears as the icon for the step. The icons for the
different adapters are as follows:
LabVIEW Adapter
LabWindows/CVI Adapter
C/C++ DLL Adapter
.NET Adapter
ActiveX/COM Adapter
HTBasic Adapter
Sequence Adapter
<None>
If you choose the <None> adapter, the step does not call a code module.
Note Once you add a step, you can change the adapter associated with the selected step

on the General panel in the Step Settings pane.


To specify the code module that the step calls, select Specify Module from
the step context menu or click the Module tab on the Step Settings pane.
Each step has a Module tab that corresponds to its module adapter. Refer to
the NI TestStand Help for more information about the Module tab for each
module adapter.

National Instruments Corporation

4-7

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

Pass/Fail Test
Use a Pass/Fail Test step to call a code module that makes its own pass/fail
determination.
After the code module executes, the Pass/Fail Test step type evaluates the
Step.Result.PassFail property. If Step.Result.PassFail is True, the step type
sets the step status to Passed. If Step.Result.PassFail is False, the step
type sets the step status to Failed.
The following are the different ways that a code module can set the value
of Step.Result.PassFail:

LabVIEW AdapterSpecify Step.Result.PassFail as the


Value expression for a Boolean output of a VI on the LabVIEW
Module tab.

LabWindows/CVI, C/C++ DLL, .NET, ActiveX/COM, or


Sequence AdapterPass Step.Result.PassFail as a reference
parameter to a subsequence or code module.

LabVIEW or LabWindows/CVI AdapterThe LabVIEW and


LabWindows/CVI Adapters update the value of Step.Result.PassFail
automatically after calling legacy code modules. The LabVIEW
Adapter updates the value of Step.Result.PassFail based on the value
of the Pass/Fail Flag element of the Test Data cluster that the VI
returns. The LabWindows/CVI Adapter updates the value of
Step.Result.PassFail based on the value of the result field of the
tTestData parameter that it passes to the C function.
Refer to the Using LabVIEW with TestStand manual and the Using
LabWindows/CVI with TestStand manual for more information about
the assignments that the module adapters automatically make to and
from step properties for legacy code modules in LabVIEW and
LabWindows/CVI.

All AdaptersUse the TestStand API to set the value of


Step.Result.PassFail directly in a code module.

By default, the step type uses the value of the Step.Result.PassFail Boolean
property to determine whether the step passes or fails. To customize
the Boolean expression that determines whether the step passes, select
Edit Data Source from the context menu for the step or click the Data
Source tab on the Step Settings pane.

NI TestStand Reference Manual

4-8

ni.com

Chapter 4

Built-In Step Types

In addition to the common custom properties, the Pass/Fail Test step type
defines the following step properties:

Step.Result.PassFailSpecifies the Boolean pass/fail flag. Pass is


True, fail is False. Usually, you set this value in the code module or
with a custom pass/fail source expression.

Step.InBufSpecifies an arbitrary string that the LabVIEW and


LabWindows/CVI Adapters pass to the test in the Input Buffer
control or tTestData structure of legacy code modules.
This property exists to maintain compatibility with previous test
executives. Usually, code modules you develop for TestStand receive
data as input parameters or access data as properties using the
TestStand API.

Step.DataSourceSpecifies the Boolean expression that the step


uses to set the value of Step.Result.PassFail. The default value of the
expression is "Step.Result.PassFail", which has the effect of
using the value that the code module sets.
You can customize this expression if you do not want to set the value
of Step.Result.PassFail in the code module. For example, you can set
the data source expression to refer to multiple variables and properties,
such as, RunState.PreviousStep.Result.Numeric *
Locals.Attenuation > 12.

Numeric Limit Test


Use a Numeric Limit Test step to call a code module that returns a single
measurement value. After the code module executes, the Numeric Limit
Test step type compares the measurement value to predefined limits. If the
measurement value is within the bounds of the limits, the step type sets the
step status to Passed. Otherwise, it sets the step status to Failed.
A Numeric Limit Test step uses the Step.Result.Numeric property to store
the measurement value. A code module can set the value of
Step.Result.Numeric in the following ways:

LabVIEW AdapterSpecify Step.Result.Numeric as the Value


expression for a Numeric output of a VI on the LabVIEW Module tab.

LabWindows/CVI, C/C++ DLL, .NET, ActiveX/COM, or


Sequence AdapterPass Step.Result.Numeric as a reference
parameter to a code module.

LabVIEW or LabWindows/CVI AdapterThe LabVIEW and


LabWindows/CVI Adapters update the value of Step.Result.Numeric
automatically after calling legacy code modules. The LabVIEW
Adapter updates the value of Step.Result.Numeric based on the value

National Instruments Corporation

4-9

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

of the Numeric Measurement element of the Test Data cluster that


the VI returns. The LabWindows/CVI Adapter updates the value of
Step.Result.Numeric based on the value of the measurement field of
the tTestData parameter that it passes to the C function.
Refer to the Using LabVIEW with TestStand manual and the Using
LabWindows/CVI with TestStand manual for more information about
the assignments that the module adapters automatically make to and
from step properties for legacy code modules in LabVIEW and
LabWindows/CVI.

All AdaptersUse the TestStand API to set the value of


Step.Result.Numeric directly in a code module.

By default, the step type uses the value of the Step.Result.Numeric property
as the numeric measurement to compare the limits against.
The Numeric Limit Test step type defines the following step properties in
addition to the common custom properties:

Step.Result.NumericSpecifies the numeric measurement value.


Usually, you set this value in the code module.

Step.Result.UnitsSpecifies a label that indicates the unit of


measurement.

Step.Limits.Low, High, LowExpr, HighExpr, UseLowExpr, and


UseHighExprSpecify the limits for the comparison expression.

Step.CompSpecifies the type of comparison, such as EQ.

Step.CompExprSpecifies the comparison operation using an


expression.

Step.UseCompExprSpecifies to use the expression to compare the


measurement values.

Step.InBufSpecifies an arbitrary string that the LabVIEW and


LabWindows/CVI Adapters pass to the test in the Input Buffer
control or tTestData structure of legacy code modules.
This property exists to maintain compatibility with previous test
executives. Usually, code modules you develop for TestStand receive
data as input parameters or access data as properties using the
TestStand API.

NI TestStand Reference Manual

4-10

ni.com

Chapter 4

Built-In Step Types

Step.DataSourceSpecifies a numeric expression that the step type


uses to set the value of Step.Result.Numeric. The default value of the
expression is "Step.Result.Numeric", which has the effect of
using the value that the code module sets. You can customize this
expression if you do not want to set the value of Step.Result.Numeric
in the code module.

You can use a Numeric Limit Test step without a code module. This
practice is useful when you want to limit-check a value that you already
have acquired. To set up this limit-check, select <None> as the module
adapter before you insert the step in the sequence and configure
Step.DataSource to specify the value that you have already acquired.
For more information about the Numeric Limit Test edit tabs, refer to the
NI TestStand Help.

Multiple Numeric Limit Test


Use the Multiple Numeric Limit Test step to limit check a set of related
measurements. Although you can use several Numeric Limit Test steps to
limit test a set of related measurements, it can be easier to use the Multiple
Numeric Limit Test step type to check limits for multiple measurements in
a single step.
The Multiple Numeric Limit Test step allows you to test limits for any
number of measurements. Each measurement can have independent limits,
units, display formats, data sources, and comparison types. A Multiple
Numeric Limit Test step passes if all of its measurements pass. Configure
each measurement the same way you configure an individual Numeric
Limit Test step. Refer to the NI TestStand Help for more information about
the Multiple Numeric Limit Test edit tabs.
The Multiple Numeric Limit Test step type defines the following step
properties in addition to the common custom properties:

National Instruments Corporation

Step.Result.MeasurementAn array that stores the measurements


you configure for the step. Each element of the measurement array
is an instance of the NI_LimitMeasurement data type. The
NI_LimitMeasurement type defines the following fields:

Limits.Low, High, LowExpr, HighExpr, UseLowExpr, and


UseHighExprSpecify the limits to which the step compares the
measurement value.

UnitsSpecifies a label that describes the measurement units for


the limits and the measurement value.

4-11

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

NI TestStand Reference Manual

CompSpecifies the type of comparison, such as EQ.

CompExprSpecifies the comparison operation using an


expression.

UseCompExprSpecifies to use the expression to compare the


measurement values.

DataStores the numeric measurement value. The step obtains


this value from the corresponding element in Step.NumericArray
or from the data source you specify.

StatusStores the result of the comparison of the measurement


value with the limits. The result is either Passed or Failed.

Step.DataSourceSpecifies an expression that identifies the numeric


array that provides the data values for all measurements when you do
not use a separate data source for each measurement.

Step.NumericArrayProvides a numeric array that is the default


data source that Step.DataSource specifies.

Step.UseIndividualDataSourcesSpecifies whether the step stores


separate data source expressions for each measurement in the
Step.DataSourceArray. If this property is False, the step obtains the
data values for each measurement from the numeric array that the
Step.DataSource property specifies.

Step.DataSourceArraySpecifies a data source for each


measurement element in the measurement array.

Step.ExpectedNumMeasureSpecifies the number of


measurements for the step.

Step.ExtraDataActionSpecifies how the step processes data


if the numeric array contains more elements than the number of
measurements. The step can apply a specific measurement to extra
data, repeat the measurement set again, generate a run-time error, or
ignore the extra data.

Step.MeasToRepeatSpecifies a measurement to repeat when the


Step.ExtraDataAction is set to RepeatOne.

Step.ExtraMeasActionSpecifies whether the step ignores, takes no


action, or generates a run-time error when the numeric array contains
fewer elements than the expected number of measurements.

4-12

ni.com

Chapter 4

Built-In Step Types

String Value Test


Use a String Value Test step to call a code module that returns a string
value. After the code module executes, the String Value Test step type
compares the string that the step obtains to the string that the step expects
to receive. If the string that the step obtains matches the string that it
expects, the step type sets the step status to Passed. Otherwise, it sets
the step status to Failed.
A String Value Test step always uses the Step.Result.String property
to store the string value. A code module can directly set the value of
Step.Result.String in the following ways:

LabVIEW AdapterSpecify Step.Result.String as the Value


expression for a Numeric output of a VI on the LabVIEW Module tab.

LabWindows/CVI, C/C++ DLL, .NET, ActiveX/COM, or


Sequence AdapterPass Step.Result.String as a reference
parameter to a code module.

LabVIEW or LabWindows/CVI AdapterThe LabVIEW and


LabWindows/CVI Adapters update the value of Step.Result.String
automatically, after calling legacy code modules. The LabVIEW
Adapter updates the value of Step.Result.String, based on the value
of the String Measurement element of the Test Data cluster that
the VI returns. The LabWindows/CVI Adapter updates the value of
Step.Result.String, based on the value of the stringMeasurement field
of the tTestData parameter that it passes to the C function.
Refer to Using LabVIEW with TestStand and Using LabWindows/CVI
with TestStand for more information about the assignments that the
module adapters automatically make to and from step properties for
legacy code modules in LabVIEW and LabWindows/CVI.

All AdaptersUse the TestStand API to set the value of


Step.Result.String directly in a code module.

By default, the step type uses the value of the Step.Result.String property
as the string value to compare the limits against.
Refer to the NI TestStand Help for more information about the String Value
Test edit tabs.

National Instruments Corporation

4-13

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

In addition to the common custom properties, the String Value Test step
type defines the following step properties:

Step.Result.StringSpecifies the string value. Usually, you set this


value in the code module.

Step.Limits.String, StringExpr, and UseStringExprSpecifies the


expected string for the string comparison.

Step.CompSpecifies the type of comparison, such as Ignore Case.

Step.CompExprSpecifies the comparison operation using an


expression.

Step.UseCompExprSpecifies to use the expression to compare the


measurement values.

Step.InBufSpecifies an arbitrary string that the LabVIEW and


LabWindows/CVI Adapters pass to the test in the Input Buffer control
or tTestData structure of legacy code modules.

This property exists to maintain compatibility with previous test


executives. Usually, code modules you develop for TestStand receive
data as input parameters or access data as properties using the
TestStand API.

Step.DataSourceSpecifies a string expression that the step type


uses to set the value of Step.Result.String. The default value of the
expression is Step.Result.String, which has the effect of using the
value that the code module sets. You can customize this expression
if you do not want to set the value of Step.Result.String in the code
module.

You can use a String Value Test step without a code module. This is useful
to test a string that you have already acquired. To set up this test, select
<None> as the module adapter before you insert the step in the sequence
and configure Step.DataSource to specify the string you already have
acquired.

NI TestStand Reference Manual

4-14

ni.com

Chapter 4

Built-In Step Types

Action
Use Action steps to call code modules that do not perform tests but, instead,
perform actions necessary for testing, such as initializing an instrument.
By default, Action steps do not pass or fail. The step type does not modify
the step status. Therefore, the status for an Action step is Done or Error
unless your code module specifically sets another status for the step or the
step calls a subsequence that fails. When an action uses the Sequence
Adapter to call a subsequence and the subsequence fails, the Sequence
Adapter sets the status of the step to Failed.
The Action step type does not define any additional step properties other
than the custom properties that all steps contain.

Step Types That Work With a Specific Module Adapter


This section describes step types that work with a specific module adapter.

Sequence Call
Use a Sequence Call step to call another sequence in the current sequence
file or in another sequence file. A Sequence Call step always uses the
Sequence Adapter.
You can use the Sequence Adapter with other step types, such as the
Pass/Fail Test or the Numeric Limit Test. Using a Sequence Call step is the
same as using an Action step with the Sequence Adapter, except that the
Sequence Call step type sets the step status to Passed rather than Done
when the subsequence succeeds. If the sequence fails, the Sequence
Adapter sets the Sequence Call step status to Failed. A sequence fails if
the status for a step in the sequence is Failed and you have enabled the
Step Failure Causes Sequence Failure option on the Run Options panel of
the Step Settings pane. If a run-time error occurs in the subsequence, the
Sequence Adapter sets the step status to Error.
Note You can enable or disable the Step Failure Causes Sequence Failure option on the

Run Options panel of the Step Settings pane.


Refer to the NI TestStand Help for more information about using the Step
Settings pane and the Edit Sequence Call dialog box.
The Sequence Call step type does not define any additional step properties
other than the custom properties that are common to all steps.

National Instruments Corporation

4-15

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

TestStand adds the following properties to the results for Sequence Call
steps that are configured to run the sequence in a new thread or execution.
These properties are not subproperties of the Result property for the
Sequence Call step type.

AsyncModeSet to True if the Sequence Call step ran the sequence


in a new thread. It is set to False if the Sequence Call step ran the
sequence in a new execution.

AsyncIDContains the value of the ID property of the thread or


execution running the sequence.

Note By default, the Sequence Adapter is hidden in the Adapter ring control. To enable it,

select ConfigureAdapters from the TestStand menu bar and remove the checkmark from
the checkbox in the Hidden column.

Step Types That Do Not Use Module Adapters


This section describes step types that do not use module adapters. When
you create an instance of one of these step types, you only use the edit tabs
or dialog boxes, which you access through the context menu of the step or
the Step Settings pane, to configure the step. You do not specify a code
module.

Flow Control
Use Flow Control steps to control execution flow within a sequence. The
Steps pane automatically inserts steps that complete the flow control block,
such as inserting a Case and End step when you insert a Select step. The
Steps pane also indents flow control blocks and highlights errors in flow
control. Refer to the NI TestStand Help for more information about the edit
tabs for the Flow Control step types.

If
Use If steps to define a block of steps that execute if a condition is met.
In addition to the common custom properties, the If step type defines the
following step property:

NI TestStand Reference Manual

Step.ConditionExprSpecifies the expression that must evaluate to


True for the steps within the If block to execute.

4-16

ni.com

Chapter 4

Built-In Step Types

Else
Use Else steps to define a block of steps that execute if the condition
defined by the preceding If or Else If step is not met.

Else If
Use Else If steps to define a block of steps that execute if a condition is met
and the conditions defined by the preceding If step and any preceding Else
If step are not met.
In addition to the common custom properties, the Else If step type defines
the following step property:

Step.ConditionExprSpecifies the expression that must evaluate to


True for the steps within the Else If block to execute.

For
Use For steps to define a block of steps that execute repeatedly for a
number of iterations.
In addition to the common custom properties, the For step type defines the
following step properties:

Step.InitializationExprSpecifies the expression that the step


evaluates before executing the steps within the block the first time. The
expression typically initializes a count variable.

Step.ConditionExprSpecifies the expression that must evaluate to


True for the steps within the For block to execute.

Step.IncrementExprSpecifies the expression that the step


evaluates after each execution of the steps within the block. The
expression typically increments a count variable.

Step.CustomLoopSpecifies whether the step uses custom


expressions to define the looping behavior for the steps within the For
block.

National Instruments Corporation

4-17

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

For Each
Use For Each steps to define a block of steps that execute once for each
element in an array.
In addition to the common custom properties, the For Each step type
defines the following step properties:

Step.ArrayExprSpecifies the expression that determines the array


over which the loop iterates.

Step.ArrayElementExprSpecifies the expression that determines


the variable into which to store the current element of the array during
each iteration of the loop.

Step.OffsetExprSpecifies the expression that determines that


variable into which to store the current offset of the array during each
iteration of the loop.

Step.SubscriptExprSpecifies the expression that determines the


variable into which to store the subscript of the current element in the
array during each iteration of the loop.

While
Use While steps to define a block of steps that execute while a condition
is True.
In addition to the common custom properties, the While step type defines
the following step property:

Step.CustomExprSpecifies the expression that the step evaluates


before executing the steps within the block.

Do While
Use Do While steps to define a block of steps that execute once and then
repeatedly while a condition is True.
In addition to the common custom properties, the Do While step type
defines the following step property:

Step.CustomExprSpecifies the expression that the step evaluates


before executing the steps within the block.

Break
Use a Break step to cause a For, For Each, While, or Do While loop block
or a Case block to exit before completing.

NI TestStand Reference Manual

4-18

ni.com

Chapter 4

Built-In Step Types

Continue
Use a Continue step to cause the next iteration of an enclosing For, For
Each, While, or Do While loop block to begin.

Select
Use a Select step to define a block of steps that encloses sub-blocks defined
by Case steps. The Select step specifies an expression that determines
which Case block executes.
In addition to the common custom properties, the Select step type defines
the following step property:

Step.ItemExprSpecifies the expression that determines which Case


block within the Select block executes.

Case
Use a Case step to define a block of steps within a Select block that
executes if the expression specified by the Select step evaluates to a certain
value.
In addition to the common custom properties, the Case step type defines the
following step properties:

Step.ItemExprSpecifies the expression that determines which Case


block within the Select block executes.

Step.IsDefaultSpecifies that this step defines the default case for


the surrounding Select block.

Goto
Use Goto steps to set the next step that the TestStand Engine executes. You
usually use a Label step as the target of a Goto step, which allows you to
rearrange or delete other steps in a sequence without having to change the
specification of targets in Goto steps.
Refer to the NI TestStand Help for more information about the Destination
edit tab.

End
Use an End step to define the end of any block of steps.

National Instruments Corporation

4-19

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

Statement
Use Statement steps to execute expressions. For example, you can use a
Statement step to increment the value of a local variable in a sequence.
By default, Statement steps do not pass or fail. If the step cannot evaluate
the expression or if the expression sets Step.Result.Error.Occurred to True,
TestStand sets the step status to Error. Otherwise, it sets the step status
to Done.
Refer to the NI TestStand Help for more information about the Expression
edit tab.
The Statement step type does not define any additional step properties other
than the custom properties that are common to all steps.

Label
Use a Label step as the target for a Goto step. Label steps allows you to
rearrange or delete other steps in a sequence without having to change the
specification of targets in Goto steps.
Label steps do not pass or fail and by default do not record results. After a
Label step executes, the TestStand Engine sets the step status to Done or
Error. You can edit a Label step to specify a description that appears next
to the Label step name in the sequence editor.
In addition to the common custom properties, the Label step type defines
one step property:

Step.DescriptionSpecifies a string that appears next to the step


name in the sequence editor.

Refer to the NI TestStand Help for more information about the Label edit
tab.

Message Popup
Use Message Popup steps to display messages to the operator and to
receive response strings from the operator. For example, you can use a
Message Popup step to warn the operator when a calibration routine fails.
By default, Message Popup steps do not pass or fail. After a step executes,
TestStand sets the step status to Done or Error.
Refer to the NI TestStand Help for more information about the Message
Popup step edit tab.

NI TestStand Reference Manual

4-20

ni.com

Chapter 4

Built-In Step Types

In addition to the common custom properties, the Message Popup step type
defines the following step properties:

Step.Result.ButtonHitContains the one-based index of the button


that you select.

Step.Result.ResponseContains the response text that the user


entered.

Step.TitleExprContains the expression for the string that appears as


the title of the message popup dialog box.

Step.MessageExprContains the expression for the string that


appears as the text message in the message popup dialog box.

Step.MessageFontDataSpecifies the font for the text message in


the message popup dialog box.

Step.Button1Label, Button2Label, Button3Label, Button4Label,


Button5Label, and Button6LabelSpecify the expression for the
label text for each button.

Step.ButtonFontDataSpecifies the font for the label text for


buttons in the message popup dialog box.

Step.ShowResponseEnables the response text box control in the


message popup dialog box.

Step.NumberLinesSpecifies the number of visible text lines in the


response text box.

Step.MaxResponseLengthSpecifies the maximum number of


characters that the operator can enter in the response text box control.

Step.RespFontDataSpecifies the font for the response text box


control in the message popup dialog box.

Step.DefaultResponseExprContains the initial text string that the


step displays in the response text box control.

Step.FileDataSpecifies whether to display a graphic or Web page in


the message popup dialog box.

Step.ActiveCtrlIdentifies one of the six buttons or the input string


as the active control.

Step.DefaultButtonSpecifies which button, if any, uses <Enter> as


a shortcut key.

Step.CancelButtonSpecifies which button, if any, uses <Esc> as a


shortcut key.

Step.TimerButtonSpecifies the index of the button that activates


automatically after a timeout elapses. A value of zero indicates that no
timeout occurs.

National Instruments Corporation

4-21

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

Step.TimeToWaitSpecifies the number of seconds before the


button that Step.TimerButton specifies activates.

Step.Position.Top and Step.Position.LeftSpecify the location of


the message popup dialog box when CenterDialog is False.

Step.CenterDialogSpecifies that the message popup dialog box


appears in the center of the screen.

Step.ModalSpecifies whether the message popup dialog box is


modal to the TestStand application.

Step.FloatingSpecifies whether the message popup dialog box


stays on top of the TestStand application.

Step.CtrlArrangementSpecifies the order for the controls on the


message popup dialog box.

Step.ButtonLocationSpecifies whether to display the buttons on


the bottom or side of the message popup dialog box.

Step.ButtonAlignmentSpecifies whether to align the buttons in the


center, left, right, top, or bottom of the message popup dialog box.

Step.ResizeDialogSpecifies whether the message popup dialog box


is resizable.

Call Executable
Use Call Executable steps to launch an application or run a system
command. For example, you can use a Call Executable step to call a system
command to copy files to a network drive.
The final status of a Call Executable step depends on whether the step waits
for the executable to exit. If the step does not wait for the executable to exit,
the step type always sets the step status to Done. If a timeout occurs while
the step is waiting for the executable to exit, the step type sets the status to
Error. If the step waits for the executable to exit and a timeout does not
occur, the step type sets the step status to Done, Passed, or Failed,
depending on the status action you specify in the Exit Code Status Action
ring control on the Call Executable edit tab for that step. If you set the Exit
Code Status Action ring control to No Action, the step type always sets the
step status to Done. Otherwise, you can choose to set the step status to
Failed based on whether the exit code is less than zero, greater than zero,
equal to zero, or not equal to zero.
Refer to the NI TestStand Help for more information about the Call
Executable edit tab.

NI TestStand Reference Manual

4-22

ni.com

Chapter 4

Built-In Step Types

In addition to the common custom properties, the Call Executable step type
defines the following step properties:

Step.Result.ExitCodeContains the exit code that the executable


returns.

Step.ExecutableSpecifies the pathname of the executable to


launch.

Step.ArgumentsSpecifies the expression for the argument string


that the step passes to the executable.

Step.WaitConditionSpecifies whether the step waits for the


executable to exit before completing.

Step.TimeToWaitSpecifies the number of seconds to wait for the


executable to exit.

Step.InitialWindowStateSpecifies whether the executable is


initially active, not active, hidden, normal, minimized, or maximized.

Step.TerminateOnAbortSpecifies whether to terminate the


executable process when the execution terminates or aborts.

Step.ProcessHandleContains the Windows process handle for the


executable.

Step.ExitCodeStatusActionSpecifies whether to set the step status


using the exit code that the executable returns.

Step.RemoteSettingsContains settings for calling the executable on


a remote computer.

EnabledSpecifies to call the executable on a remote computer.

HostSpecifies the computer name or IP address of the remote


computer.

HostByExprSpecifies whether to allow the remote host field to


be entered by expression.

PortSpecifies the port number the remote host server


application uses.

PasswordSpecifies the password that is configured on the


remote host server application.

PasswordByExprSpecifies whether to allow the password


field to be entered by expression.

Property Loader
Refer to Appendix C, Database Step Types, for more information about the
Property Loader step. Refer to the NI TestStand Help for more information
about the Edit Property Loader dialog box.

National Instruments Corporation

4-23

NI TestStand Reference Manual

Chapter 4

Built-In Step Types

FTP Files
Use a FTP Files step to transfer files between the local system and an FTP
server.
In addition to the common custom properties, the FTP Files step type
defines the following step properties:

Step.RemoteHostSpecifies the computer name or IP address of the


remote computer.

Step.RemoteHostByExprSpecifies whether to allow the remote


host field to be entered by expression.

Step.FTPUsernameSpecifies the login name to use when


connecting to the server.

Step.FTPPasswordSpecifies the password to use when connecting


to the server.

Step.FilesToFTPSpecifies the local and remote file paths, the


direction to transfer the file, and whether to overwrite a file if it exists.

Refer to the NI TestStand Help for more information about the FTP Files
edit tab.

Synchronization Step Types


Refer to Appendix B, Synchronization Step Types, for more information
about the Synchronization steps. Refer to the NI TestStand Help for more
information about the Synchronization step edit dialog boxes.

Database Step Types


Refer to Appendix C, Database Step Types, for more information about the
Database steps. Refer to the NI TestStand Help for more information about
the Database step edit dialog boxes.

IVI-C Step Types


Refer to Appendix D, IVI-C Step Types, for more information about the
IVI-C steps. Refer to the NI TestStand Help for more information about the
IVI-C step edit dialog boxes.

LabVIEW Utility Step Types


Refer to Appendix E, LabVIEW Utility Step Types, for more information
about the LabVIEW steps. Refer to the NI TestStand Help for more
information about the LabVIEW step edit dialog boxes.

NI TestStand Reference Manual

4-24

ni.com

Adapters

This chapter describes the module adapters available in TestStand and how
to use them.

Module Adapters
The TestStand Engine uses a module adapter to invoke the code in a code
module, which is called from a TestStand sequence. Each module adapter
supports one or more specific types of code modules, which include
LabVIEW VIs; LabWindows/CVI functions in source files, object files, or
library modules that you create in LabWindows/CVI or other compilers;
C/C++ functions in DLLs; .NET assemblies; ActiveX automation servers;
and HTBasic subroutines. A module adapter knows how to load and call a
code module, how to pass parameters to a code module, and how to return
values and status from a code module.
When you edit a step that uses a module adapter, TestStand relies on the
adapter to display the Module tab of the Step Settings pane, in which you
specify the code module for the step and also specify any parameters to pass
when you invoke the code module.
TestStand stores the name and location of the code module, the parameter
list, and any additional options as properties of the step. TestStand hides
most of these adapter-specific step properties.
In some cases, if the module adapter is specific to an application
development environment (ADE), the adapter knows how to open the ADE,
how to create source code for a new code module in the ADE, and how to
display the source for an existing code module in the ADE. Some adapters
support stepping into the source code in the ADE while you execute the
step from the TestStand Sequence Editor or user interfaces.

Configuring Adapters
You can configure most of the module adapters by selecting Configure
Adapters from the sequence editor menu. Refer to the NI TestStand Help
for more information about configuring adapters.

National Instruments Corporation

5-1

NI TestStand Reference Manual

Chapter 5

Adapters

Source Code Templates


If you are using the LabVIEW, LabWindows/CVI, C/C++ DLL, .NET, or
HTBasic Adapters, you can use a code template to generate the source code
shell for a code module. The code template files are different for each step
type and each module adapter. A step type can define multiple code
templates for a particular adapter/step combination.
TestStand includes default code templates for each of the built-in step
types. You can also create additional code templates for built-in step types
when you create a new step type. Refer to Chapter 13, Creating Custom
Step Types, for more information about creating code templates for step
types.

LabVIEW Adapter
The LabVIEW Adapter allows you to call LabVIEW VIs with a variety of
connector panes. Refer to the NI TestStand Help for more information
about the LabVIEW Module tab and passing parameters between
TestStand and VIs. Refer to the Using LabVIEW with TestStand manual for
additional information about using the LabVIEW Adapter, supported data
types, and tutorials that use the adapter.

LabWindows/CVI Adapter
The LabWindows/CVI Adapter allows you to call C functions with a
variety of parameter types. The function can exist in an object file, library
file, or DLL. The function can also exist in a source file that is located in the
project that you are currently using in the LabWindows/CVI development
environment.
Refer to the Using and Debugging DLLs section of this chapter for more
information about debugging DLLs built with LabWindows/CVI. Refer to
the NI TestStand Help for more information about the LabWindows/CVI
Module tab and about passing parameters between TestStand and code
modules. Refer to the Using LabWindows/CVI with TestStand manual for
additional information about the LabWindows/CVI Adapter and tutorials
that use the adapter.

NI TestStand Reference Manual

5-2

ni.com

Chapter 5

Adapters

C/C++ DLL Adapter


The C/C++ DLL Adapter allows you to call C functions and C++ methods
in a DLL with a variety of parameter types. In C++ DLLs, the methods can
be either global static methods or static class methods. You can create the
DLL code module with Microsoft Visual Studio, LabWindows/CVI or any
other ADE that creates a C/C++ DLL you can call.
You can create and edit C/C++ code modules directly from TestStand. If
you are using Visual Studio, you must have one of the following software
application combinations installed:

National Instruments Measurement Studio 8.0.1 (or later) Enterprise


Edition and Visual Studio 2005 or later

National Instruments Measurement Studio 7.1 (or later) Enterprise


Edition and Visual Studio .NET 2003

For DLLs built by LabWindows/CVI, you must use the LabWindows/CVI


Adapter to create and edit code modules directly from TestStand. In
addition, the LabWindows/CVI Adapter provides full integration with
the LabWindows/CVI ADE for debugging.
If you do not have Visual Studio, you can create and edit code directly from
TestStand using the default text editor that the system opens for source files.
Use the C/C++ DLL Module tab on the Step Settings pane to specify a
C/C++ DLL Adapter module call, to specify the source code associated
with the module call, and to create and edit code the source code directly
from TestStand. Refer to the NI TestStand Help for more information about
the C/C++ DLL Adapter, the C/C++ DLL Module tab, and passing
parameters between TestStand and code modules.

Using and Debugging DLLs


To debug a DLL that TestStand calls, first create the DLL with debugging
enabled in your ADE, such as LabWindows/CVI or Visual Studio. Then,
launch the sequence editor or user interface executable from the ADE,
or attach to the executable process from your ADE, if supported. For
LabWindows/CVI, select RunSelect External Process in the Project
window to identify the executable for the sequence editor or user interface.
Then, select RunDebug <executable name> to start debugging the
executable. For Visual Studio, you must ensure that you enable native code
debugging.

National Instruments Corporation

5-3

NI TestStand Reference Manual

Chapter 5

Adapters

Note Be sure to save your sequence files before you stop debugging. If you stop

debugging, most ADEs will terminate the TestStand process without prompting you
to save modified files in TestStand.
If you suspend a sequence on a step that calls a DLL that you can debug,
you can click Step Into in TestStand on the step to suspend at the first
statement in the DLL function within LabWindows/CVI or Visual
Studio 2005.
To step into a code module with LabWindows/CVI, you must configure the
step to use the LabWindows/CVI Adapter. You can step into a code module
when the LabWindows Adapter is configured to execute steps in-process or
in an external instance of LabWindows/CVI.
To step into a DLL with Visual Studio 2005, you must configure the step
to use the C/C++ DLL Adapter and you must have installed National
Instruments Measurement Studio 8.0.1 (or later) Enterprise Edition. If
you attempt to step into a DLL while Visual Studio is not attached to the
TestStand process, TestStand launches Visual Studio and automatically
attaches to the TestStand process using native debugging.
Note TestStand does not support step into when debugging the process with

Visual Studio .NET 2003, or when the process loads the .NET Framework 1.1 and you are
debugging with Visual Studio 2005.
Table 5-1 describes your options for stepping out of a LabWindows/CVI
or Visual Studio DLL function that you are debugging.
Table 5-1. Options for Stepping Out of DLL Functions

ADE Command for


Stepping Out
Finish Function or Step Out

NI TestStand Reference Manual

Result in TestStand
Execution of the function. When you use this command on the
last function in the call stack, TestStand suspends execution on
the next step in the sequence.

5-4

ni.com

Chapter 5

Adapters

Table 5-1. Options for Stepping Out of DLL Functions (Continued)

ADE Command for


Stepping Out
Step Into or Step Over

Result in TestStand
When you use this command on the last executable statement of
the function, TestStand suspends execution on the next step in
the sequence.
If the Step Over command executes on an END step in a
Pre-Step callback, TestStand attempts to step into the code
module.

Continue

TestStand does not suspend execution when the function call


returns.
Refer to your LabWindows/CVI and Visual Studio documentation for more
information about debugging DLLs in an external process.

Calling LabVIEW DLLs


Use the C/C++ DLL Adapter to call functions exported from LabVIEW
shared libraries (DLLs).

Using ActiveX Controls


LabVIEW DLLs that use ActiveX controls must load in a thread initialized
as single-threaded apartment (STA) for the controls to function correctly.
If the TestStand step that calls the DLL preloads the DLL, TestStand
ensures that the DLL is loaded in an STA thread. However, if you
dynamically load a step that calls such a DLL, you must ensure that the
loading sequence is executing in an STA thread. You can use the Run
Sequence in a New Thread or Run Sequence in a New Execution found in
the Multithreading and Remote Execution section of the Edit Sequence
Call dialog box to choose an STA thread. Click the Settings button to
launch the Thread Settings dialog box, which contains the STA thread
options.

Debugging LabVIEW 8 or Later Shared Libraries


(DLLs)
LabVIEW 8 and later allows you to enable debugging in shared libraries
that you build with Application Builder. Using the LabVIEW development
environment, you can target the shared library to debug and connect to
the TestStand application process. Refer to the LabVIEW Help for more
information about debugging applications and shared libraries.

National Instruments Corporation

5-5

NI TestStand Reference Manual

Chapter 5

Adapters

Debugging LabVIEW 7.1.1 Shared Libraries (DLLs)


You must use a TestStand User Interface built with LabVIEW to debug any
VIs that you build into a shared library using LabVIEW 7.1.1. First, open
the user interface in the LabVIEW development environment. Before
executing the user interface, open the VI that represents the DLL function
to debug and place a breakpoint in the block diagram of this VI. Next, use
the TestStand User Interface to load and execute the sequence file that calls
the LabVIEW shared library. When LabVIEW loads the shared library that
the step calls, LabVIEW uses the VI in memory instead of the VI in the
DLL. Then, when the step calls the DLL function, LabVIEW suspends at
the breakpoint that you set in the VI.

Using MFC in a DLL


The Microsoft Foundation Class (MFC) Library places several
requirements on DLLs that use the DLL version of the MFC run-time
library. If you call any of these DLLs, verify that the DLL meets these
requirements. Also, if the DLL uses resources such as dialog boxes, verify
that the AFX_MANAGE_STATE macro appears at the beginning of the
function body of each function that you call. Refer to your MFC
documentation for more information about calling DLLs.

Loading Subordinate DLLs


TestStand directly loads and runs the DLLs that you specify on the
C/C++ DLL Module tab for the C/C++ DLL Adapter. Because your code
modules most likely call subsidiary DLLs, such as instrument drivers, you
must ensure that the operating system can find and load any DLLs.
The C/C++ DLL Adapter first attempts to load subordinate DLLs using an
alternate search directory precedence, which includes the directory of the
DLL as follows:

NI TestStand Reference Manual

1.

The directory that contains the DLL that the adapter is calling directly

2.

The current working directory of the application. (Windows 2000 and


Windows XP SP1 and earlier)

3.

The Windows\System32 and Windows\System directories

4.

The Windows directory

5.

The current working directory of the application. (Windows XP SP2


and later)

6.

The directories listed in the PATH environment variable

5-6

ni.com

Chapter 5

Adapters

For backwards compatibility, when the C/C++ DLL Adapter fails to load a
DLL, the adapter temporarily sets the current working directory to be the
directory of the DLL and attempts to load subordinate DLLs using the
following deprecated search directory precedence:
1.

The directory that contains the application that loaded the adapter

2.

The current working directory of the application, which the adapter


has set to the directory that contains the DLL it is calling directly
(Windows 2000 and Windows XP SP1 and earlier)

3.

The Windows\System32 and Windows\System directories

4.

The Windows directory

5.

The current working directory of the application, which the adapter has
set to the directory that contains the DLL it is calling directly
(Windows XP SP2 and later)

6.

The directories listed in the PATH environment variable

Note National Instruments does not recommend placing subordinate DLLs in the
directory containing the application that loaded the adapter, and may not support loading
DLLs from this location in future versions.

Reading Parameter Information


If a DLL contains export information or if a DLL file contains a type
library, the LabWindows/CVI and C/C++ DLL Adapters automatically
populate the Function control on the Module tab with all of the function
names exported from the DLL. In addition, when you select a function in
the DLL, the adapter queries the export information or the type library for
the parameter list information and displays it in the Parameter Table control
on the Module tab. If the adapter cannot determine parameter information,
you must enter the parameter information manually.
Refer to the Using LabWindows/CVI with TestStand manual for more
information about including a type library in a DLL. Refer to the
NI Developer Zone at ni.com/zone for additional information about
building type libraries.

.NET Adapter
The .NET Adapter allows you to call .NET assemblies written in any
.NET-compliant language, such as C# or Visual Basic .NET. You must
have the .NET Framework 2.0 or later installed to use the .NET Adapter.

National Instruments Corporation

5-7

NI TestStand Reference Manual

Chapter 5

Adapters

With the .NET Adapter, you can create instances of classes and structs, and
you can call methods and access properties or fields on classes and structs.
With an instance of a class that was either previously created and stored in
an object reference variable or created in the calling step, you can call or
access all non-static public members. An instance is not required to call or
access static public members. When you call a struct, the definition can also
be stored in a variable of a data type that is mapped to the struct members
or initialized in the calling step.
The .NET Adapter does not support creating or calling methods on generic
classes.
You can create and edit .NET code modules in Visual Studio directly from
TestStand if you install National Instruments Measurement Studio 8.0.1
(or later) Enterprise Edition.
Refer to the NI TestStand Help for more information about using the .NET
Module tab to configure calls to .NET assemblies.

Debugging .NET Assemblies


To debug a .NET assembly, first create the assembly with debugging
enabled in your ADE. Then, launch the sequence editor or user interface
from Visual Studio or attach to the sequence editor or user interface process
from Visual Studio.
Note When you debug an assembly in a TestStand process and you stop debugging, Visual

Studio may terminate the TestStand process without prompting you to save modified files
in TestStand. Save your sequence files and workspace before you stop debugging and
terminate the process.
If you are debugging a .NET assembly in the TestStand process using
Visual Studio 2005 or later and you have Measurement Studio 8.0.1
(or later) Enterprise Edition installed, you can click Step Into in TestStand
on a step that calls into the assembly to suspend Visual Studio at the first
statement in the assembly method or property.If you attempt to step into an
assembly while the Visual Studio is not attached to the TestStand process,
TestStand launches Visual Studio and automatically attaches to the
TestStand process using managed debugging.
Note When you debug managed code in a TestStand process with Visual Studio,

TestStand will not unload assemblies when you select FileUnload All Modules.

NI TestStand Reference Manual

5-8

ni.com

Chapter 5

Adapters

Note You cannot debug managed code that the .NET Adapter calls using Visual Studio

.NET 2003 or using Visual Studio 2005 when the process loads the .NET Framework 1.1.
Table 5-2 describes your options for stepping out of a Visual Studio
assembly that you are debugging.
Table 5-2. Options for Stepping Out of Assemblies in Visual Studio

Visual Studio Command


for Stepping Out

Result in TestStand

Step Out

Executes the function. When you use this command on the last
function in the call stack, TestStand suspends execution on the
next step in the sequence.

Step Into or Step Over

Suspends execution on the next step in the sequence when you


use this command on the last executable statement of the
function.

Continue

Does not suspend execution when the function call returns.


Refer to your Visual Studio documentation for more information about
debugging managed code in an external process.
Note If you are using LabWindows/CVI to debug a DLL in the TestStand process, you

cannot debug a .NET assembly at the same time. If you are using Visual Studio to debug
an assembly in TestStand and you want to use LabWindows/CVI to debug code modules
at the same time, you must configure the LabWindows/CVI Adapter to execute the steps
out-of-process.
Note When you debug a TestStand process with Visual Studio, TestStand will not unload

assemblies when you select FileUnload All Modules.


Note You cannot attach to a TestStand process when the process loads Microsoft .NET

Framework 1.1 and you are debugging with Visual Studio 2005, or when the process loads
Microsoft .NET Framework 2.0 and you are debugging with Visual Studio .NET 2003.

National Instruments Corporation

5-9

NI TestStand Reference Manual

Chapter 5

Adapters

Using the .NET Framework


When more than one version of the .NET Framework is installed on a
computer, an application can load only one version of the .NET run-time
into memory. For unmanaged applications, such as a LabVIEW user
interface, the .NET Adapter uses the latest version of the .NET run-time.
For managed applications such as the TestStand Sequence Editor and the
C# and Visual Basic .NET user interfaces, the .NET Adapter uses the
run-time you specified when you created the application.
You can call .NET 1.1 assemblies in TestStand if the .NET 2.0 run-time
is loaded in memory. However, when the .NET 1.1 run-time is loaded in
memory, the .NET 1.1 run-time returns an error if you attempt to call a
.NET 2.0 assembly from TestStand. In addition, when you use Microsoft
Visual Studio .NET 2003, attempts to debug the Common Run-time
Language fail if the .NET 2.0 run-time is loaded in memory.
You can force an application to use a specific version of the .NET
Framework by creating a configuration file in the same directory as the
executable. For example, to force an unmanaged user interface to use .NET
Framework 1.1, create a file called testexec.exe.config with the following
contents:
<?xml version="1.0"?>
<configuration>
<runtime>
<assemblyBinding
xmlns="urn:schemas-microsoft-com:asm.v1">
</assemblyBinding>
</runtime>
<startup>
<supportedRuntime version="v1.1.4322" />
</startup>
</configuration>

NI TestStand Reference Manual

5-10

ni.com

Chapter 5

Adapters

Accessing the TestStand API in Visual Studio .NET 2003 and


Visual Studio 2005
TestStand 4.0 installs .NET interop assemblies for the TestStand API
into the <TestStand>\API\DotNet\Assemblies directory and adds
references to the assemblies to the Global Assembly Cache (GAC). The
interop assemblies support the current version of the TestStand API and
earlier versions of the API. The TestStand 4.0 assemblies require .NET 2.0
run-time, and the TestStand 3.5 and earlier assemblies require .NET 1.1 or
later run-time.
To add a reference to the TestStand 4.0 API assembly in
Visual Studio 2005, select the project in the Solution Explorer. Select Add
Reference from the Project menu to launch the Add Reference dialog box.
Next, select the .NET tab and select the TestStand <APIName>
Interop Assembly component from the list. Click OK to close the Add
Reference dialog box.
To add a reference to the TestStand API assembly in
Visual Studio .NET 2003, you must use an assembly that is compatible
with .NET 1.1, such as TestStand 3.5 or earlier. Select the project in the
Solution Explorer. Select Add Reference from the Project menu to launch
the Add Reference dialog box. Next, select the .NET tab and click the
File Browse button to launch the Select Components dialog box. Then,
navigate to the <TestStand>\API\DotNet\Assemblies\
PreviousVersion\3.5 directory. Select
NationalInstruments.TestStand.Interop.<APIName>.dll, and
click Open. Click OK to close the Add Reference dialog box.

Configuring the .NET Adapter


Use the .NET Adapter Configuration dialog box to configure the
.NET Adapter. Refer to the NI TestStand Help for more information about
the .NET Adapter Configuration dialog box.
The struct mapping of a TestStand variable is automatically refreshed
before it is used. If there is no mapping for a struct element, the argument
for the struct element has a question mark (?) on the .NET Module tab. You
must edit the named data type to map the struct element to a property of
the type.

National Instruments Corporation

5-11

NI TestStand Reference Manual

Chapter 5

Adapters

ActiveX/COM Adapter
The ActiveX/COM Adapter allows you to create objects, call methods, and
access properties of ActiveX/COM objects. When you create an object, you
can assign the object reference to a variable or property for later use in other
ActiveX/COM Adapter steps. When you call methods and access
properties, you can specify an expression for each input and output
parameter.
Refer to the NI TestStand Help for more information about configuring
calls to ActiveX/COM servers.

Running and Debugging ActiveX Automation Servers


TestStand does not step into your ActiveX/COM server. To debug an
out-of-process executable server, launch the server in the ADE in which
it was created and then independently launch the sequence editor or user
interface. If you want to debug an in-process DLL server, launch the
sequence editor or user interface from the ADE.
When you work in Microsoft Visual Basic, place breakpoints in your
automation server source code and select RunStart with Full Compile.
In TestStand, run the sequence that calls into your automation server to
cause the execution to automatically suspend at the breakpoint that you set
in Visual Basic. Refer to your ADE documentation for more information
about debugging ActiveX automation servers.
Note The Windows operating system can prevent a development environment from

rebuilding a DLL ActiveX server after a TestStand step uses the server. When TestStand
requests that the operating system unload the ActiveX server, the operating system ignores
the request and keeps the ActiveX server in memory, which prevents the development
environment from rebuilding the DLL. You must exit the TestStand application to release
the ActiveX DLL server.

Configuring the ActiveX/COM Adapter


Use the ActiveX/COM Adapter Configuration dialog box to configure the
ActiveX/COM Adapter. Refer to the NI TestStand Help for more
information about the ActiveX/COM Adapter Configuration dialog box.

NI TestStand Reference Manual

5-12

ni.com

Chapter 5

Adapters

Registering and Unregistering ActiveX/COM Servers


To register an ActiveX/COM server DLL, call the Windows executable
regsvr32.exe, using the DLL pathname as the command-line argument.
To unregister the DLL server, call regsvr32.exe using /u and the
DLL pathname as the command-line argument.
To register an ActiveX/COM server executable, run the server executable
with the /RegServer command-line argument. To unregister an
executable server, call the executable with the /UnregServer
command-line argument.
Visual Basic does not automatically register a server when you build the
server DLL or executable. You must manually register the server as
outlined previously in this section. Visual Basic temporarily registers a
server when you run the server project inside the Visual Basic ADE. When
you complete the debugging session, Visual Basic unregisters that server.

Server Compatibility Options for Visual Basic


If you are developing an automation server in an ADE that does not give
you direct control over IDs, you must ensure that the ActiveX/COM
Adapter can find the server identifiers or the names defined in the
TestStand step. When you rebuild an ActiveX/COM server in Visual Basic,
you can select one of three compatibility options. Depending on the level
of compatibility and the changes you make to a project, Visual Basic
compiles an appropriate new server, which can contain new identifiers.
To specify the level of compatibility, select Project Properties from the
Project menu in Visual Basic. In the Project Properties dialog box, use the
radio buttons in the Version Compatibility section on the Components tab
to select the level of compatibility.
Visual Basic offers the following compatibility options:

No compatibilityMaintains no compatibility between the new


server and a previously compiled server. Visual Basic generates new
unique identifiers for the server, which prevents any previously
compiled client application that uses early binding from working
properly with the server.
Because Visual Basic changes the IDs that it uses to uniquely identify
the type information of the server, TestStand cannot properly update an
ActiveX/COM Adapter step, regardless of whether you configure the
ActiveX/COM Adapter for early or late binding.

National Instruments Corporation

5-13

NI TestStand Reference Manual

Chapter 5

Adapters

Note National Instruments does not recommend the use of the No compatibility setting

with your TestStand projects.

Project compatibilityCauses Visual Basic to maintain the


ID assignments that it uses to uniquely identify the type information
for the server. Use this option when you have multiple projects under
development within Visual Basic. The setting is not meant to assure
compatibility with client applications that were not compiled in Visual
Basic or projects that use early binding.
When you use this option to rebuild a server, TestStand can then use
the type information to determine the IDs associated with the names
stored in the step.

Note Use the Project compatibility option only after you have built the server DLL or

executable.
Note National Instruments recommends that you configure the ActiveX/COM Adapter to

use late binding when you create a server using the Project compatibility option.

Binary compatibilityInstructs Visual Basic to maintain the current


ID assignments that it uses to identify objects and methods. When you
use this option, Visual Basic attempts to maintain compatibility with
compiled client applications that use early binding. If you remove a
member from the server, Visual Basic can no longer maintain binary
compatibility.

Note Use the Binary compatibility option only after you have built the server DLL or

executable for the first time.


When you use this option to rebuild a server, TestStand can use the IDs
stored in the step without accessing the type information at run time.
Note National Instruments recommends that you configure the ActiveX/COM Adapter to

use early binding when you create a server with this option.
National Instruments makes the following additional recommendations
regarding the use of the Visual Basic ActiveX/COM server in conjunction
with development of sequences within TestStand. These approaches ensure
that the ActiveX/COM Adapter can properly find and invoke the server
after you recompile the server.

NI TestStand Reference Manual

5-14

ni.com

Chapter 5

Adapters

Use the following approach while you develop and debug sequences:

Use the Project compatibility option to rebuild your server in


Visual Basic.

Configure the ActiveX/COM Adapter to use late binding.

Use the following approach when the interface for the server is
completely developed and debugged:

Use the Binary compatibility option to rebuild your server in


Visual Basic.

Select ToolsUpdate Automation Identifiers in the TestStand


Sequence Editor to assign the new server identifiers to the steps.

After you properly assign the new server identifiers to the steps,
you can enable the ActiveX/COM Adapter to use early binding.

For more information about creating and debugging Visual Basic


ActiveX/COM servers, refer to your Visual Basic documentation and to the
following Internet document:
Ivo Salmre, Building, Versioning, and Maintaining Visual Basic
Components, Microsoft Developer Network, Microsoft Corporation,
February 1998.

HTBasic Adapter
The HTBasic Adapter allows you to call HTBasic subroutines without
passing parameters directly to a subroutine. Instead, the subroutine
exchanges data by calling get or set subroutines contained in an HTBasic
CSUB. These subroutines use the TestStand API to get data from and set
data in TestStand. For more information about using these subroutines,
refer to the Passing Data To and Returning Data From a Subroutine
section of this chapter.

Specifying the HTBasic Adapter


Use the HTBasic Module tab on the Step Settings pane to specify the
subroutine file path, subroutine name, and other options. Refer to the
NI TestStand Help for more information about the HTBasic Module tab.

Debugging an HTBasic Adapter


To debug an HTBasic subroutine while executing the subroutine from
TestStand, you must configure the adapter to use the HTBasic development
environment as the HTBasic server.

National Instruments Corporation

5-15

NI TestStand Reference Manual

Chapter 5

Adapters

If you select DebugStep Into in TestStand when an execution is currently


suspended on a step that calls an HTBasic subroutine, HTBasic displays the
HTBasic server window and pauses at the call of the subroutine. When
the execution is suspended, press <Alt-F1> to single-step through the
subroutine. When you have finished debugging a particular subroutine,
click Continue to resume execution and return control to TestStand. After
you step out of the subroutine, TestStand suspends execution on the next
step in the sequence.
For more information about debugging HTBasic programs, refer to your
HTBasic documentation.

Passing Data To and Returning Data From a Subroutine


TestStand provides a library of CSUB routines that use the TestStand API
to access TestStand variables and properties from an HTBasic subroutine.
For more information about these subroutines, refer to the NI TestStand
Help.

Sequence Adapter
The Sequence Adapter allows you to pass parameters when you make a call
to a subsequence. You can call a subsequence in the current sequence file
or in another sequence file, and you can make recursive sequence calls.
For subsequence parameters, you can specify a literal value, pass a variable
or property by reference or by value, or use the default value that the
subsequence defines for the parameter.
You can use the Sequence Adapter from any step type that can use module
adapters, such as the Pass/Fail Test or the Numeric Limit Test. This is
similar to using the Sequence Call built-in step type, except that the
Sequence Call step sets the step status to Passed instead of Done if no
failure or error occurs.
After the Sequence Call step executes, the Sequence Adapter may set the
step status. If the sequence that the step calls fails, the adapter sets the step
status to Failed. If no run-time error occurs, the adapter does not set the
step status. The resulting status is Done or Passed, depending on the type
of step. If a run-time error occurs in the sequence, the adapter sets the step
status to Error and sets the Result.Error.Occurred property to True. The
adapter also sets the Result.Error.Code and Result.Error.Msg properties to
the values of the same properties in the subsequence step that generated the
run-time error.

NI TestStand Reference Manual

5-16

ni.com

Chapter 5

Adapters

You can define the parameters for a sequence on the Variables pane in the
Sequence File window. The Variables pane defines each parameter name,
its TestStand data type, its default value, and whether you pass the
argument by value or by reference. For more information about sequence
file parameters, refer to the NI TestStand Help.

Specifying the Sequence Adapter


Use the Sequence Module tab on the Step Settings pane to specify a
Sequence Adapter module call. Refer to the NI TestStand Help for more
information about the Sequence Module tab.

Remote Sequence Execution


There are three types of sequence file paths available when you use remote
sequence execution relative, absolute, and network. Table 5-3 describes
these options.
Table 5-3. Path Resolution of Sequence Pathnames for Remotely Executed Steps

Type
of Path

Where Found
When You Edit

Where Found
When You Execute

Example

Relative

In the TestStand
search paths that
you configure on
the client (local)
machine.

In the TestStand
search paths that you
configure on the server
(remote) machine.

Transmit.seq

Absolute

On the client
(local) machine.

On the server (remote)


machine.

C:\Projects\Transmit.seq

Network

On the machine
specified in the
network path.

On the machine
specified in the
network path.

\\Remote\Transmit.seq

When you specify a sequence file pathname in the Sequence Module tab
and specify Use Remote Computer in the Execution Options section,
TestStand locates the sequence file according to the type of path, as
described in Table 5-3.
When you edit a step in a sequence file on a client machine and you specify
an absolute or relative path for the sequence file the step calls, TestStand
resolves the path for the sequence file on the client machine. When you run
the step on the client machine, TestStand resolves the path for the sequence
file on the server system.

National Instruments Corporation

5-17

NI TestStand Reference Manual

Chapter 5

Adapters

Choose one of the following three ways to manage your remote sequence
files for remote execution:

Add a common pathname to the search paths for the client and the
server so that each resolves to the same relative pathname.

Duplicate the files on your client and server machine so that the client
edits an identical file to the file that the server runs.

Use absolute paths that specify a mapped network drive or full network
path so that the file that the client machine edits and the file the server
runs are the same sequence file.

When you execute a remote sequence, you cannot single-step or set


breakpoints in the remote sequence. If you enable tracing, TestStand
updates the status bar with tracing information for the remote sequence.
When a remote sequence executes on a server, the sequence context and
call stack include only the sequences that run on the remote system. If you
want to access properties from the client sequence context, you must pass
the PropertyObjects or their values as parameters to the remote sequence.
You can use the TestStand API to access properties within a property
object.

Setting up TestStand as a Server for Remote Sequence Execution


You must properly configure a remote system and the TestStand server
application on the remote system if you want a client TestStand system
to invoke a sequence on the remote system. These configuration settings
include enabling the TestStand server on the remote system to accept
remote execution requests and configuring Windows system security
to allow users to access and launch the TestStand server remotely, and
configuring a Windows Firewall on the remote system.
To allow the TestStand server to accept remote execution requests from a
client machine, enable the Allow Sequence Calls from Remote Machines
to Run on this Machine option, which is located on the Remote Execution
tab on the Station Options dialog box.
A TestStand server is active while the TestStand application
<TestStand>\bin\REngine.exe runs on a remote system. Each
TestStand client communicates with a dedicated version of the TestStand
server. The TestStand server launches automatically when a TestStand
client uses the server.

NI TestStand Reference Manual

5-18

ni.com

Chapter 5

Adapters

You can close remote engine applications from your system tray by
enabling the Show the System Tray Icon While the TestStand Remote
System is Active on this Machine option on the Station Options dialog
box for the remote system. This option makes the TestStand icon visible in
the system tray for each instance of the remote engine application. The
tooltip for the icon indicates which computer is connected to the remote
engine. Right-click the TestStand icon to display when the engine was
created or to force the remote engine application to close.
TestStand automatically registers the server during installation. To
manually register or unregister the server, invoke the executable with
the /RegServer or /UnregServer command-line arguments.
Before a client can communicate with a server, you must configure
the security permissions of the Windows system for the server. For
Windows XP SP2, you must also configure the Windows Firewall.
Tip To minimize the configuration of security permissions, enable the Allow All Users
Access From Remote Machines option on the Station Options dialog box. When you
enable this option, TestStand configures the security permissions for you by adding the
name Everyone for Windows 2000 SP4 and the name ANONYMOUS LOGON for
Windows XP SP2 to the list of users who have permission to access and launch the
TestStand remote server. When you disable this option, TestStand removes the names from
the list.

Windows XP Service Pack 2


For Windows XP SP2, complete the following steps to configure the
security permissions for the server on a remote system:
1.

Log in as a user with administrator privileges.

2.

Launch the Component Services window by selecting Start


All ProgramsAdministrative ToolsComponent Services or by
running dcomcnfg from the command line.

3.

In the left pane of the Component Services window, expand the tree
view to show Component ServicesComputersMy Computer.

4.

Right-click My Computer and select Properties to launch the


My Computer Properties dialog box.

5.

On the Default Properties tab on the My Computer Properties dialog


box, verify that the Enable Distributed COM on this computer
option is enabled.

National Instruments Corporation

5-19

NI TestStand Reference Manual

Chapter 5

Adapters

Note Changing the value of the Enable Distributed COM on this computer option
requires you to reboot your computer.

6.

Click the COM Security tab of the My Computer Properties


dialog box.
a.

Click Edit Limits in the Access Permissions section to launch the


Access Permission dialog box. Click the Add button to add the
users you want to give remote access to. Click OK to close the
Select Users, Computer, Groups dialog box. Select the user you
added and enable Remote Access in the Permissions section.
Click OK to close the Access Permission dialog box.

b.

Click Edit Limits in the Launch and Activation Permissions


section to launch the Launch Permission dialog box. Click the
Add button to the users you want to give remote access to. Click
OK to close the Select Users, Computer, Groups dialog box.
Select the user you added and enable Remote Launch and
Remote Activation in the Permissions section. Click OK to
close the Launch permission dialog box.

7.

Click OK to close the My Computer Properties dialog box.

8.

In the left pane of the Component Services window, select


My ComputerDCOM Config to display a list of applications in the
right pane.

9.

Right-click NI TestStand Remote Engine and select Properties from


the context menu to launch the NI TestStand Remote Engine Properties
dialog box.

10. On the Identity tab on the NI TestStand Remote Engine Properties


dialog box, verify that The interactive user is selected. Click OK to
close the dialog box.
You must give permission to the appropriate users so that they can access
the remote server. You should give access to everyone, but give launch
permission only to appropriate users because users who have launch
permission are able to access the server. You can set these permissions
in one of the following ways:

NI TestStand Reference Manual

Specify the default security on the Default COM Security tab on the
My Computer Properties dialog box.

Give individual users access to the server. Use the Security tab on the
NI TestStand Remote Engine Properties dialog box to configure the
permissions for a specific server.

5-20

ni.com

Chapter 5

Adapters

Windows XP SP2 Firewall Settings


For Windows XP SP2, complete the following steps to configure Windows
Firewall to allow the REngine.exe application to communicate to the
TestStand client.
1.

Log in as a user with administrator privileges.

2.

Launch the Windows Firewall by selecting StartSettingsControl


Panel. Open Windows Firewall.

3.

You have the option of disabling the firewall if you click Off, or you
can add exceptions for the REngine.exe application. If you enable the
firewall, complete the following steps to add the necessary exceptions:
a.

Click the Exception tab.

b.

Click the Add Program button to launch the Add a Program


dialog box. Click the Browse button and select <TestStand>\
bin\REngine.exe. Click OK to close the Add a Program
dialog box.

c.

Click the Add Port button to launch the Add a Port dialog box. In
the Name control, type DCOM. In the Port Number control, type
135. Select the TCP radio button and click OK to close the Add
a Port dialog box.

Windows 2000 Service Pack 4


For Windows 2000 SP4, complete the following steps to configure the
security permissions for the server:
1.

Log in as a user with administrator privileges.

2.

Run dcomcnfg from the command line, which launches the


Distributed COM Configuration Properties dialog box.

3.

On the Default Properties tab, verify that the Enable Distributed


COM on this computer option is enabled.

Note Changing the value of the Enable Distributed COM on this computer option
requires you to reboot your computer.

4.

On the Applications tab, select NI TestStand Remote Engine and


then click Properties.

5.

On the Identity tab on the NI TestStand Remote Engine Properties


dialog box, verify that the Interactive User option is selected.

National Instruments Corporation

5-21

NI TestStand Reference Manual

Chapter 5

Adapters

You must give permission to the appropriate users so that they can access
the remote server. You should give access permissions to everyone, but give
launch permission only to users who should be able to launch the server.
You can set these permissions in one of the following ways:

NI TestStand Reference Manual

Specify the default security on the Default Security tab on the


Distributed COM Configuration Properties dialog box.

Give individual users access to the server. On the Applications tab,


select NI TestStand Remote Engine and then click Properties. Use
the Security tab on the TestStand Remote Engine Properties dialog
box to configure the permissions for a specific server.

5-22

ni.com

Database Logging and Report


Generation

This chapter describes the database and report generation features of


TestStand. This chapter assumes that you have a basic understanding of
database concepts, SQL, and your Database Management System (DBMS)
client software.

Database Concepts
This section summarizes key database concepts that are important for using
databases with TestStand. It also summarizes the key Windows features
TestStand uses to communicate with a DBMS.

Databases and Tables


A database is an organized collection of data. You can store data in and
retrieve data from a database. Although databases vary in how they store
their internal data, most modern DBMSs, also known as database servers,
store data in table form.
Tables contain records, also known as rows. Each row consists of fields,
also known as columns. Every table in a database must have a unique name,
and every column within a table must have a unique name. Each column in
a table has a data type. The available data types vary depending on
the DBMS.

National Instruments Corporation

6-1

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

You can use database tables to store many different types of data. Table 6-1
contains columns for the UUT number, a step name, a step result, and a
measurement. The order of the data in the table is not important. Ordering,
grouping, and other manipulations of the data occur when you retrieve the
data from the table.
Table 6-1. Example Database Table

UUT_NUM

STEP_NAME

RESULT

MEAS

20860B456

TEST1

PASS

0.5

20860B456

TEST2

PASS

(NULL)

20860B123

TEST1

FAIL

0.1

20860B789

TEST1

PASS

0.3

20860B789

TEST2

PASS

(NULL)

A row can contain an empty column value, which means that the specific
cell contains a NULL value, also referred to as a SQL Null value.
Use an SQL SELECT command, or query, to retrieve records from a
database. The result of a query is called a record set or SQL Statement data.
The data you receive does not necessarily reflect the entire contents of any
particular table in the database. For instance, you can retrieve only selected
columns and rows from one table, or you can retrieve data that is a
combination of the contents of multiple tables. The query defines the
contents and order of the data. You can refer to each column you retrieve
by the name of the column or by a one-based number that refers to the order
of the column in the query.

NI TestStand Reference Manual

6-2

ni.com

Chapter 6

Database Logging and Report Generation

Database Sessions
Database operations occur within a database session. A simple session
follows this order:
1.

Connect to the database.

2.

Open database tables.

3.

Fetch data from and store data to the open database tables.

4.

Close the database tables.

5.

Disconnect from the database.

Microsoft ADO, OLE DB, and ODBC Database Technologies


TestStand uses Microsoft ActiveX Data Objects (ADO) as its database
client technology. ADO, which is built on top of the Object Linking and
Embedding Database (OLE DB), is one of several database interface
technologies that Microsoft has integrated into its operating systems.
Applications that use ADO, such as TestStand, use the OLE DB interfaces
indirectly. The OLE DB layer interfaces to databases directly through
a specific OLE DB provider for the DBMS or through a generic Open
Database Connectivity (ODBC) provider, which interfaces to a specific
ODBC driver for the DBMS. Figure 6-1 shows the high-level relationships
between TestStand and components of the Windows database technologies.

National Instruments Corporation

6-3

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

TestStand
Engine

Process Model
Sequence
Database
Logger

Main
Sequences
Database
Steps

ADO

OLE DB

OLE DB Providers

Access
Provider

SQL Server
Provider

Oracle Server
Provider

ODBC
Provider

Future
Providers

ODBC
Drivers

Access
MDB Files

SQL
Server

Oracle
Server

Flat File
Database

???

Figure 6-1. Microsoft Windows Database Technologies

Refer to the Microsoft Web site, www.microsoft.com/data, for more


information about database technologies for Windows operating systems.

NI TestStand Reference Manual

6-4

ni.com

Chapter 6

Database Logging and Report Generation

Data Links
Before you can access data from a database within TestStand, you must
provide specific connection information called a data link. In a data link,
you can specify the server on which the data resides, the database or file
that contains the data, the user ID, and the permissions to request when
connecting to the data source.
For example, to connect to a Microsoft SQL Server database, specify the
OLE DB provider for an SQL Server, a server name, a database name,
a user ID, and a password. To connect to a Microsoft Access database,
specify Microsoft Jet, or specify the OLE DB provider for ODBC and an
ODBC data source name. The ODBC data source name specifies which
ODBC driver to use, the database file (.mdb), and an optional user ID
and password. You can define ODBC data source names in the
ODBC Administrator in the Windows Control Panel.
Refer to the Using the ODBC Administrator section of this chapter for more
information about the ODBC Administrator.
A connection string is a string version of the connection information
required to open a session to a database. TestStand allows you to build
a connection string using the Data Link dialog box.
The Data Link dialog box and the information contained in the connection
string vary according to the OLE DB provider. For example, a connection
string for a Microsoft SQL Server database might contain the following:
Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist
Security Info=True;User ID=guest;Initial
Catalog=pubs;Data Source=SERVERCOMPUTER

Complete the following steps to store the contents of a connection string in


a Microsoft Data Link file (.udl):
1.

Create a Data Link file by right-clicking in Windows Explorer and


selecting NewText Document.

2.

Change the file extension to .udl.

3.

Right-click the new file and select Open to launch the Data Link
Properties dialog box.

Refer to the Using Data Links section of this chapter for more information
about specifying data links. You can also refer to the NI TestStand Help for
more information about the Data Link Properties dialog box.

National Instruments Corporation

6-5

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

Database Logging Implementation


The database logging capability in TestStand is not native to the TestStand
Engine or the TestStand Sequence Editor. The default process model
included with TestStand contains customizable sequences that implement
the logging features. You can also customize or replace any portion of
the database logging sequences. Refer to Appendix A, Process Model
Architecture, for more information about customizing the default process
model.
The default process model relies on the automatic result collection
capability of the TestStand Engine to accumulate the raw data that is logged
to a database for each UUT. The engine can automatically collect the
results of each step into a result list for an entire sequence, which contains
the result of each step it runs and the result list of each subsequence call it
makes. The default process model calls the Main sequence in the client
sequence file to test a UUT, so that the result list for the Main sequence
contains the raw data to log to a database for the UUT. Refer to the Result
Collection section of Chapter 3, Executions, for more information about
automatic result collection.
The Test UUTs and Single Pass Execution entry points in the TestStand
process models log the raw results to a database. By default, the Test UUTs
entry point logs results after each pass through the UUT loop.
Select ConfigureDatabase Options to launch the Database Options
dialog box, which you can use to specify the following options:

The data link to which TestStand logs results.

The database schema that TestStand uses. A schema contains the


SQL statements, table definitions, and TestStand expressions that
instruct TestStand on how to log results to a database. TestStand
includes a set of predefined schemas, which contains at least one
schema for each supported DBMS. You can also create new schemas
that log results to tables you define.

Various filtering options to limit the amount of data that TestStand


logs.

Whether the process models log data after each step is executed or after
each pass through the UUT loop.

For more information about the Database Options dialog box, refer to the
NI TestStand Help.

NI TestStand Reference Manual

6-6

ni.com

Chapter 6

Database Logging and Report Generation

Using Database Logging


Complete the following steps before using the default process model to log
results to a database:
1.

Decide which DBMS you want TestStand to log the results to. By
default, TestStand supports Microsoft SQL Server, Oracle, Microsoft
Access, Sybase, and MySQL. If you decide to use another DBMS,
refer to the Adding Support for Other Database Management Systems
section of this chapter.

2.

Make sure that you have installed the appropriate client DBMS
software that is required to communicate with the DBMS.
You must decide whether to use an ODBC driver or a specific OLE DB
provider for your DBMS. Use the OLE DB providers for Microsoft
Access and Microsoft SQL Server. Most Oracle ODBC drivers and
OLE DB providers require that you install Oracle Client also.
Refer to the <TestStand>\Doc\Readme.html for more information
about suggested providers, versions of ODBC drivers, client DBMS
software, and any known issues.

3.

Create the default database tables in a database in your DBMS.


TestStand comes with SQL script files for creating and deleting the
default database tables that the default schemas require. For example,
the Access Create Generic Recordset Result Tables.sql
file contains SQL commands to create the default tables for Access.
The Access Drop Result Tables.sql file contains SQL
commands to delete the default tables. These script files are located in
the <TestStand>\Components\NI\Models\TestStandModels\
Database directory.
TestStand installs an example Microsoft Access database, TestStand
Results.mdb, in the <TestStand>\Components\NI\Models\
TestStandModels\Database directory.
For more information about creating the default database tables using
an SQL script file, refer to the Using Data Links section of this chapter.
Refer to the Creating the Default Result Tables section of this chapter
for more information about the default table schema used by the
process model.

4.

National Instruments Corporation

Use the Database Options dialog box to enable database logging and
to define a data link and schema for the default process model to use.

6-7

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

Refer to the NI TestStand Help for more information about the Database
Options dialog box. Refer to the Using Data Links section of this chapter
for more information about defining data links.

Logging Property in the Sequence Context


When the database logger starts, it creates a temporary property named
Logging in the sequence context in which the database logger evaluates
expressions. The Logging property contains subproperties that provide
information about database settings, process model data structures, and the
results that the logger processes. As the Logging property processes the
result list, the logger updates subproperties of Logging to refer to the
UUT result, step result, and the step result subproperty the logger
is processing. You can reference the Logging subproperties in the
precondition and value expressions that you specify for statement
and column values.
The Logging property has the following subproperties:

NI TestStand Reference Manual

UUTResultContains the UUT result that the logger is processing.


If the logger is processing a step or a subproperty, this property holds
the UUT result that contains the step result or subproperty.

StepResultContains the step result that the logger is processing.


If the logger is processing a subproperty, this property holds the step
result that contains the subproperty. If the logger is processing a
UUT result, this property contains the result of the sequence call in
the process model that calls the Main sequence in the client file.

StepResultPropertyContains the subproperty of the step result that


the logger is processing. If the logger is not processing a subproperty,
this property does not exist.

ExecutionOrderContains a numeric value that the logger


increments after it processes each step result.

StartDateSpecifies the date on which the UUT test began. This


property is an instance of the DateDetails custom data type.

StartTimeSpecifies the time at which the UUT test began. This


property is an instance of the TimeDetails custom data type.

UUTSpecifies the serial number, test socket index, and other


information about the UUT. This property is an instance of the
UUT custom data type.

6-8

ni.com

Chapter 6

Database Logging and Report Generation

DatabaseOptionsContains the process model database settings you


configure in the Database Options dialog box. This property is an
instance of the DatabaseOptions custom data type.

StationInfoSpecifies the station ID and the user name. This


property is an instance of the StationInfo custom data type.

The TestStand process model files define the structure of the DateDetails,
TimeDetails, UUT, DatabaseOptions, and StationInfo custom data types.

TestStand Database Result Tables


This section describes the default table schemas that TestStand uses. This
section also outlines how to modify existing schemas or create new
schemas.

Default TestStand Table Schema


The default TestStand database schema requires the following tables in
your database:

UUT_RESULT

STEP_RESULT

STEP_SEQCALL

STEP_PASSFAIL

STEP_CALLEXE

STEP_MSGPOPUP

STEP_PROPERTYLOADER

STEP_STRINGVALUE

MEAS_NUMERICLIMIT

MEAS_IVI_WAVE

MEAS_IVI_WAVEPAIR

MEAS_IVI_SINGLEPOINT

The UUT_RESULT table contains information about each UUT that


TestStand tests. The STEP_RESULT table contains information about each
step that TestStand executes while testing each UUT. The other table names
with the STEP prefix contain information for each specific step type. The
table names with the MEAS prefix contain information about sub results
that TestStand logs for a step type.

National Instruments Corporation

6-9

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

Each table contains a primary key column ID. The data type of the column
is Number, String, or GUID, depending on the selected schema. Each table
might contain foreign key columns. The data types of the columns must
match the primary key that the data types reference.
Refer to the NI TestStand Help for complete information about the default
TestStand table schemas.

Creating the Default Result Tables


The TestStand logging feature requires that you create the database tables
in a database for your DBMS. You can use the Database Viewer in
TestStand to create the default result tables that the schema requires.
Note To use the Database Viewer application, you must have previously set up the DBMS

server and any required DBMS client software.


For more information about creating the default database tables using an
SQL script file, refer to the Database ViewerCreating Result Tables
section of this chapter. Refer to the NI TestStand Help and the Using Data
Links section of this chapter for more information about configuring your
system to access your DBMS.

Adding Support for Other Database Management Systems


TestStand supports Microsoft SQL Server, Oracle, Microsoft Access,
Sybase, and MySQL. You can add support for another DBMS in the
following ways:

Review the default schemas in the Database Options dialog box.


TestStand includes schemas for each DBMS, and each schema
conforms to the default database tables.

Create result tables for the default table schema for each DBMS by
using the SQL script files located in the <TestStand>\
Components\NI\Models\TestStandModels\Database

directory, and modifying them for the new DBMS.


If you want to add support for another DBMS, you must create a new
schema in the Database Options dialog box. Use the Duplicate button
on the Schemas tab to copy an existing schema and then customize its
statement, column, and parameter settings to work with the new DBMS.

NI TestStand Reference Manual

6-10

ni.com

Chapter 6

Database Logging and Report Generation

You can also follow these steps to create new script files for your
new DBMS:
1.

Tip

Create new script files in the <TestStand>\Components\User\


Models\TestStandModels\Database directory.

National Instruments recommends including the name of the DBMS in the filename.
2.

Enter the SQL commands for creating and deleting your DBMS tables
to the new script files. Refer to any of the SQL database script files that
TestStand provides for an example.
For example, the SQL database syntax file for Oracle result tables
might contain the following commands:
CREATE TABLE UUT_RESULT
(
ID
NUMBER PRIMARY KEY,
UUT_SERIAL_NUMBER
CHAR (255),
USER_LOGIN_NAME
CHAR (255),
START_DATE_TIME
DATE,
EXECUTION_TIME
NUMBER,
UUT_STATUS
CHAR (255),
UUT_ERROR_CODE
NUMBER,
UUT_ERROR_MESSAGE
CHAR (255)
)
/
CREATE SEQUENCE SEQ_UUT_RESULT START WITH 1
/
CREATE FUNCTION UUT_RESULT_NEXT_ID RETURN NUMBER IS
X NUMBER;
BEGIN
SELECT SEQ_UUT_RESULT.NextVal INTO X FROM DUAL;
RETURN X;
END;
/

Note Notice that TestStand uses three separate commands, each separated by the " / "

character, to create the UUT_RESULT table in Oracle.

National Instruments Corporation

6-11

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

Use a similar syntax for deleting tables. For example, the SQL script
file for Oracle might contain the following commands for deleting
result tables:
DROP TABLE STEP_RESULT
/
DROP SEQUENCE SEQ_STEP_RESULT
/
DROP FUNCTION STEP_RESULT_NEXT_ID
/

Database Viewer
TestStand includes the Database Viewer application for viewing data in a
database, editing table information, and executing SQL commands. The
Database Viewer application, DatabaseView.exe, is located in the
<TestStand>\Components\NI\Tools\DatabaseView directory.
For more information about the Database Viewer, refer to the NI TestStand
Help.

On-the-Fly Database Logging


When you enable the Use On-The-Fly Logging option on the Database
Options dialog box, the process models progressively log result data
concurrent with the execution instead of waiting until the execution
or testing of the UUT is complete. Database logging uses the
ProcessModelPostResultListEntry and SequenceFilePostResultListEntry
callbacks to process the step results. The final data logged is essentially
identical to the data generated by the process model at the end of execution.
When you use this option, you can use the Database Viewer application to
view the data in the database tables while the sequence is executing. Use
the Discard Results or Disable Results When Not Required by Model
option on the Model Options dialog box to instruct TestStand to discard
step results after logging each result.
If you use on-the-fly database logging with a schema that uses either a
stored procedure or command statements that do not use the INSERT
command, you cannot define constraints for foreign keys in step result
statements that reference primary keys in UUT results. Defining constraints
for these types of foreign keys will generate an error, since the on-the-fly
database logger cannot execute the statement to create the record
containing the primary key before executing the statement to create the
record containing the foreign key.

NI TestStand Reference Manual

6-12

ni.com

Chapter 6

Database Logging and Report Generation

Using Data Links


TestStand requires you to define a data link when you specify the database
where TestStand logs results or when you use the Database step types.
TestStand uses the Data Link Properties dialog box to create or edit a data
link connection string. Use the Data Link Properties dialog box to specify
initialization properties for your OLE DB provider.
Refer to the NI TestStand Help for more information about the Data Link
Properties dialog box.

Using the ODBC Administrator


To access databases through the ODBC standard, you must have an ODBC
driver for each database system you use. Each ODBC driver must register
itself with the operating system when you install it. You must also define
and name data sources in the ODBC Administrator in the Windows Control
Panel. This typically requires information such as a server, database, and
additional database-specific options. You can define one or more data
sources for each ODBC driver. To access the OBDC Administrator in
Windows 2000 SP4 or Windows XP SP2, select StartAll Programs
Administrative ToolsData Sources (ODBC).
Note Because the database features of TestStand comply with the ODBC standard, you

can use any ODBC-compliant database drivers. TestStand does not install any ODBC
database drivers. DBMS vendors and third-party developers offer their own drivers. Refer
to your vendor documentation for information about registering your specific database
drivers with the ODBC Administrator.
For more information about the ODBC Data Source Administrator dialog
box, refer to the NI TestStand Help.

Example Data Link and Result Table Setup for Microsoft Access
This section outlines an example of how to link a TestStand data link to
a Microsoft Access database file (.mdb) using the Microsoft Jet OLE DB
provider to log results using the default process model.

Database OptionsSpecifying a Data Link and


Schema
To configure the database logging options complete the following steps:
1.

National Instruments Corporation

Launch the sequence editor and log in as Administrator.

6-13

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

2.

Select ConfigureDatabase Options to launch the Database Options


dialog box. The Logging Options tab is active.

3.

Enable database logging by clicking the checkbox next to the Disable


Database Logging option.

4.

Click the Data Link tab on the Database Options dialog box and select
Access from the Database Management System ring control.

5.

Click Build to launch the Data Link Properties dialog box.

6.

Select Microsoft Jet 4.0 OLE DB Provider on the Provider tab on


the Data Link Properties dialog box.

7.

Click Next. The Connection tab is now active.

8.

On the Connection tab, click Browse to launch the Select Access


Database dialog box.

9.

Using the Select Access Database dialog box, locate your Microsoft
Access database file (.mdb) and click Open to select the file.

10. On the Data Link Properties dialog box, click Test Connection to
verify that you properly entered the required information.
11. Click OK to close the Data Link Properties dialog box.
Notice that the Connection String control on the Database Options dialog
box now contains a literal string expression version of the data link
connection string.

Database ViewerCreating Result Tables


Complete the following steps to create the default result tables in your
database:
1.

2.

If you are continuing from the steps in the previous section, skip to
step 2. Otherwise, complete the following steps:
a.

Launch the sequence editor and log in as Administrator.

b.

Select ConfigureDatabase Options to launch the Database


Options dialog box. The Logging Options tab is active.

c.

Enable database logging by clicking the checkbox next to the


Disable Database Logging option.

d.

Click the Data Link tab on the Database Options dialog box.

Select View Data to launch the Database Viewer application and open
the data link.

Note Step 2 requires that the Connection String control contains a valid expression.

NI TestStand Reference Manual

6-14

ni.com

Chapter 6

Database Logging and Report Generation

3.

In the Database Viewer application, select FileNew Execute SQL


Window to open an Execute SQL window.

4.

Select SQLLoad From File and select the Access Create


Generic Recordset Result Tables.sql file in the
<TestStand>\Components\NI\Models\TestStandModels\
Database directory.

Note Notice that the SQL Command control contains a set of SQL commands for creating

the default result tables.


5.

Select SQLExecute to create the default result tables. Review the


results of the SQL commands in the SQL History control to ensure that
the tables were created successfully.

6.

Click the Data Link window and select WindowRefresh to view the
tables.

After you have completed these steps, any execution you launch with
the Test UUTs or Single Pass entry point automatically logs its results
to the database.
The remainder of this chapter describes how to manage and use test reports
in TestStand.

Implementation of the Test Report Capability


Most of the test report capabilities described in this chapter are not native
to the TestStand Engine or the TestStand Sequence Editor. Instead, the
default process model that comes with TestStand implements the test report
capabilities. This approach allows you to customize all aspects of test
reporting. Refer to Appendix A, Process Model Architecture, for more
information about the default process model.
Even if you do not modify or replace the test report implementation in the
process model, you can still customize the contents of test reports using the
Report Options dialog box provided in the default process model. Refer to
the NI TestStand Help for more information about the Report Options
dialog box.
The default process model, which calls the Main sequence in the client
sequence file to test a UUT, relies on the automatic result collection
capabilities of the TestStand Engine to accumulate the raw data for each
UUT test report. The engine can automatically compile the result of each
step into a result list for an entire sequence, which contains the result of

National Instruments Corporation

6-15

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

each step and the result list of each subsequence call it makes. Refer to the
Result Collection section of Chapter 3, Executions, for information about
automatic result collection.

Using Test Reports


The Test UUTs and Single Pass entry points in the TestStand process
models generate UUT test reports. The Test UUTs entry point generates a
test report and writes it to disk after each pass through the UUT loop. Select
ConfigureReport Options to launch the Report Options dialog box, in
which you can set options that determine the contents and format of the test
report and the names and locations of test report files.
In the TestStand Sequence Editor, the Report tab on the Execution window
displays the report for the current execution. Usually, the Report tab is
empty until execution completes. The default process model can generate
reports in XML, HTML, or ASCII-text formats.
You can also use an external application to view reports in these or other
formats by selecting the Viewer button on the Report pane when an
Execution window is active. Select ConfigureExternal Viewers to
specify the external application that TestStand launches to display a
particular report format.
Refer to the NI TestStand Help for more information about the Report pane,
Report Options dialog box, and the Configure External Viewers dialog box.

Failure Chain in Reports


For UUTs that fail, XML, HTML, and ASCII-text reports include a failure
chain section in the report header. The first item in the failure chain table
shows the step whose failure causes the UUT to fail. The remaining items
show the Sequence Call steps through which the execution reaches the
failing step. In XML and HTML reports, each step name in the failure chain
is a hyperlink to the section of the report that displays the result for the step.

Batch Reports
When you use the Batch process model, the model generates a Batch report
in addition to a report for each UUT. The batch report summarizes the
results for all the UUTs in the batch. When the report format is XML
or HTML, the batch report provides hyperlinks to each UUT report.

NI TestStand Reference Manual

6-16

ni.com

Chapter 6

Database Logging and Report Generation

Property Flags that Affect Reports


TestStand includes three flags that you can set to identify the result
properties that should be automatically displayed in the report:

PropFlags_IncludeInReport

PropFlags_IsLimit

PropFlags_IsMeasurementValue

The IncludeInReport flag specifies that a subset of the result properties


should automatically appear in the report. For properties that hold output
values or limit values, use the IsLimit and IsMeasurementValue flags to
selectively exclude limits or output values according to the option you
select in the Report Options dialog box. If an array or container property
sets a reporting flag, the report generator also considers the flag to be set
for all array elements or subproperties within the containing object.
Tip When you use the IncludeInReport, IsLimit, and IsMeasurementValue flags on result
properties for your custom step types, the report generator will format those properties into
the report. If you require specific formatting for your report, use these flags to achieve the
report output you want without altering the report generator settings.

On-the-Fly Report Generation


When you enable the On-The-Fly Reporting option, which is located on the
Contents tab on the Report Options dialog box, the process models will
progressively generate the test report concurrent with the execution instead
of waiting until the execution or the testing of UUTs is complete. The final
test report generated by the On-The-Fly Report Generator is identical to
that generated by the process models at the end of execution.
When you use on-the-fly reporting, you can select the Report tab in the
Execution window to view the test report during the execution. If the
Report tab is the active view of the Execution window while a sequence
is executing, the test report will periodically update as step results are
processed.
In addition to generating the test report concurrently with execution, the
On-The-Fly Report Generator periodically persists the current test report to
a temporary file. The persistence interval is specified in the process model
sequences. The temporary file is deleted, and the final test report is saved
to file at the end of a UUT loop execution. For more information about
process model sequences, refer to Appendix A, Process Model
Architecture.

National Instruments Corporation

6-17

NI TestStand Reference Manual

Chapter 6

Database Logging and Report Generation

If the Conserve Memory and Only Display Latest Results report option is
enabled, the On-The-Fly Report Generator periodically purges internal
data structures. As a result, the test report that is displayed in the Report
view of the Execution window will only show the results for those steps that
have not yet been purged. The persisted temporary and final test report files,
however, will contain all of the step results. For these files, the step
results for Sequence Call and Loop Result steps will appear after their
corresponding Sequence Call and Loop Index step results, respectively.
Use the Discard Results or Disable Results When Not Required By
Model option on the Model Options dialog box to instruct TestStand to
conserve memory by discarding results after reporting each result.

XML Report Schema


XML Test Reports are described according to the XML W3C Schema.
The XML Schema Definition (XSD) file is stored in the following location:
<TestStand>\Components\NI\Models\TestStandModels\
Report.xsd.

NI TestStand Reference Manual

6-18

ni.com

User Management

The TestStand Engine features a user manager. The user manager is a list
of users, their user names, passwords, and privileges and a list of groups,
their privileges, and user members. TestStand defines a set of privileges
and TestStand can limit the functionality of the sequence editor and user
interfaces depending on the privilege settings that have been defined
in the user manager for the current user and the groups that the user is a
member of.
When you launch the TestStand Sequence Editor or any of the TestStand
User Interfaces, they display the Login dialog box by calling the
LoginLogout Front-End callback sequence. The LoginLogout sequence
calls the DisplayLoginDialog method of the Engine class, which launches
the actual Login dialog box.
The User Manager tab on the Station Options dialog box specifies whether
TestStand enforces user privileges and specifies the location of the user
manager configuration file. Refer to the NI TestStand Help for more
information about the User Manager tab on the Station Options dialog box.
Note The TestStand User Manager is designed to help you implement policies and

procedures concerning the use of your test station. It is not a security system and it does
not inhibit or control the operating system or third-party applications. You must use the
system-level security features that are available with your operating system to secure your
test station computer against unauthorized use.
For information about the User Manager window, adding groups and users,
and setting their privileges, refer to the NI TestStand Help.

National Instruments Corporation

7-1

NI TestStand Reference Manual

Chapter 7

User Management

Privileges
The TestStand User Manager stores privileges as Boolean properties and
organizes the privileges in categories. Each user and group in the user
manager lists the following categories and their containing privileges:

OperateContains privileges for executing sequences and for


terminating and aborting executions.

DebugContains privileges for controlling execution flow, executing


manual and interactive executions, and for editing station globals and
runtime variables.

DevelopContains privileges for editing and saving sequence files,


editing workspace files, and using source code control.

ConfigureContains privileges for configuring station options, user


management, adapter configuration, application settings, report,
database logging and model options, and editing process model files.

CustomContains custom privileges that you define. You can add


new privileges by customizing the NI_UserCustomPrivileges data type.

For each user or group in the user manager, you can grant specific
privileges and grant all privileges for a specific category. In addition, you
can add a user as a member of a group and the user is granted all the
privileges of that group. A user or group has a privilege if the property value
for the privilege is True or if the value of the Grant All property in any
enclosing parent privilege category is True. For example, a user has the
privilege to terminate an execution if one of the following are True:

<User>.Privileges.Operate.Terminate

<User>.Privileges.Operate.GrantAll

<User>.Privileges.GrantAll

<Group>.Privileges.Operate.Terminate

<Group>.Privileges.Operate.GrantAll

<Group>.Privileges.GrantAll

Note A user is also granted all privileges if you have disabled privilege checking on the
User manager tab of the Station Options dialog box.

Accessing Privilege Settings for the Current User


To verify in an expression that the current user has a specific privilege,
call the CurrentUserHasPrivilege expression function. Use the
Engine.CurrentUserHasPrivilege method in the TestStand API

NI TestStand Reference Manual

7-2

ni.com

Chapter 7

User Management

to verify the privilege in a code module. The CurrentUserHasPrivilege


method behaves identically to the expression function.
When you call CurrentUserHasPrivilege, you must specify the property
name of the privilege as a string argument. You can pass any subset of the
property name tree structure to CurrentUserHasPrivilege. For example, you
can use either of the following expressions to determine whether the current
user has the privilege to terminate an execution:

CurrentUserHasPrivilege("Terminate")

CurrentUserHasPrivilege("Operate.Terminate")

You can pass "*" as the string argument to CurrentUserHasPrivilege to


determine whether a user is currently logged in. Refer to Chapter 1,
TestStand Architecture, for more information about using expressions.
For more information about Engine.CurrentUserHasPrivilege, refer to the
NI TestStand Help.

Accessing Privilege Settings for Any User


The TestStand API includes methods that give you access to the
privileges of any user or group. Use Engine.GetUser and
Engine. GetUserGroup to return a User object. You can then use
User.HasPrivilege which returns True if the user or any group that the
user is a member of has the privilege you specify by name. This method
behaves identically to CurrentUserHasPrivilege when called on a User
object returned from Engine.GetUser. Refer to the NI TestStand Help for
more information about the User object and its methods.

Defining Custom Privileges in TestStand


All users and groups have a Privileges.Custom category that is empty by
default. You can define new privileges in the category by adding Boolean
properties to the NI_UserCustomPrivileges standard data type in the User
Manager file in the Types window. When you add new properties to the
data type, you should increment the version of the type to remove the
modified flag and to ensure that the type upgrades properly on future
systems.
The TestStand Sequence Editor and user interfaces that use the TestStand
UI Controls do not recognize new custom privileges that you define. You
must add code to user interfaces that behave differently depending on
whether the current user has the custom privilege.

National Instruments Corporation

7-3

NI TestStand Reference Manual

Customizing and Configuring


TestStand

This chapter describes how to configure and customize a TestStand station.

Customizing TestStand
This section describes the various TestStand components that you can
customize to meet your specific needs.

User Interfaces
The TestStand User Interfaces are application programs that you use to
execute and debug test sequences on a test station or custom sequence
editors you use to edit sequence files. The user interfaces are available in
several different programming languages and include full source code,
allowing you to modify them to meet your specific needs.
Refer to Chapter 9, Creating Custom User Interfaces, for more information
about how to create and modify TestStand User Interfaces.

Process Models
The TestStand process models define the set of operations that occur for all
test sequences, such as identifying the UUT, notifying the operator of
pass/fail status, generating a test report, and logging results. TestStand
includes three fully customizable process models to meet your specific
testing needs: Sequential, Parallel, and Batch.
Refer to Chapter 10, Customizing Process Models and Callbacks, to learn
how to modify the TestStand process models.

National Instruments Corporation

8-1

NI TestStand Reference Manual

Chapter 8

Customizing and Configuring TestStand

Callbacks
TestStand calls callback sequences at specific points during sequence
execution and test station operation. You can modify these callbacks to
customize the operation of your test station.
Refer to Chapter 10, Customizing Process Models and Callbacks, to learn
how to modify TestStand callback sequences.

Data Types
Data types define station global variables, sequence file global variables,
sequence local variables, and properties of steps and step types. You can
create and modify your own data types in TestStand, as well as copy the
standard TestStand data types, and customize the copies.
Refer to Chapter 11, Type Concepts, and Chapter 12, Standard and Custom
Data Types, to learn how to create and modify TestStand data types.

Step Types
Steps that you add to TestStand sequences are instances of step types.
A step type defines the behavior and properties of a step. You can create
and modify your own step types in TestStand, as well as copy the standard
TestStand step types, and customize the copies.
Refer to Chapter 11, Type Concepts, and Chapter 13, Creating Custom Step
Types, to learn how to create and modify TestStand step types.

Tools Menu
The TestStand Sequence Editor and User Interfaces each include a Tools
menu that contains common tools for use with TestStand. These tools
include documentation generators, a Database Viewer application, and the
TestStand Deployment Utility. You can modify the Tools menu to contain
the exact tools you need. You can also add new items to the Tools menu.
Refer to the NI TestStand Help for more information about how to add your
own commands to the Tools menu using the Customize Tools Menu
dialog box.

NI TestStand Reference Manual

8-2

ni.com

Chapter 8

Customizing and Configuring TestStand

TestStand Directory Structure


The TestStand installation program installs the TestStand Engine,
the TestStand Sequence Editor, the module adapters, and additional
components on your system. Table 8-1 shows the names and contents
of each subdirectory of the TestStand installation.
Table 8-1. TestStand Subdirectories

Directory Name

Contents

AdapterSupport

Support files for the LabVIEW, LabWindows/CVI, .NET, and


HTBasic Adapters.

API

TestStand ActiveX automation server libraries and utility libraries


for several programming languages.

Bin

TestStand Sequence Editor executable, TestStand Engine DLLs,


and support files.

Cfg

Configuration files for TestStand Engine and TestStand Sequence


Editor options.

CodeTemplates

Source code templates for step types.

Components

Components that are installed with TestStand and components that


you develop. This includes callback files, converters, icons, language
files, process model files, step types, source files, compatibility files,
and utility files.

Doc

Documentation files.

Examples

Example sequences and tests. Most example sequences that use


LabVIEW VIs call subVIs from the <LabVIEW>\vi.lib directory,
which you can access after you install the LabVIEW Development
System.

Setup

Support files for the TestStand installer.

Tutorial

Sequences and code modules that you use in tutorial sessions in this
manual, as well as the Using TestStand, Using LabVIEW with
TestStand manual, the Using LabWindows/CVI with TestStand
manual, and the NI TestStand Evaluation Guide.

UserInterfaces

LabVIEW, LabWindows/CVI, Microsoft Visual Basic, C#,


and C++ (MFC) user interfaces with source code.

National Instruments Corporation

8-3

NI TestStand Reference Manual

Chapter 8

Customizing and Configuring TestStand

NI and User Subdirectories


Three of the TestStand directories contain source files that you can modify
or replace: CodeTemplates, Components, UserInterfaces. These
directories contain NI and User subdirectories.
By default, TestStand installs its files into the NI subdirectory. Use the
User subdirectory to store your modified files to ensure that newer
installations of the same version of TestStand do not overwrite your
customizations, or that uninstalling TestStand does not remove the files
you customize. The User subdirectory also acts as the staging area for
the components that you include in your own run-time deployment of
TestStand.

Components Directory
TestStand installs the sequences, executables, project files, and source
files for TestStand components in the <TestStand>\Components\NI
directory. Most of the subdirectories in the <TestStand>\
Components\NI directory have the name of a type of TestStand
component. For example, the <TestStand>\Components\NI\
StepTypes subdirectory contains support files for the TestStand
built-in step types.
If you want to create a new component or customize a TestStand
component, copy the component files from the NI subdirectory to the User
subdirectory before customizing. This ensures that newer installations of
the same version of TestStand do not overwrite your customizations, or that
uninstalling TestStand does not remove the files you customize. If you copy
the component files as the basis for creating a new component, be sure to
rename the files so that your customizations do not conflict with the default
TestStand components.
The TestStand Engine searches for sequences and code modules using
the TestStand search directory path. The default search precedence
places the <TestStand>\Components\User directory tree before
the <TestStand>\Components\NI directory tree. This ensures that
TestStand loads the sequences and code modules that you customize
instead of loading the default TestStand versions of the files. To modify the
precedence of the TestStand search directory paths, select Configure
Search Directories from the sequence editor menu bar.

NI TestStand Reference Manual

8-4

ni.com

Chapter 8

Customizing and Configuring TestStand

When you deploy a run-time version of the TestStand Engine, you can
bundle your components in the User directory with the TestStand run-time
deployment. Refer to Chapter 14, Deploying TestStand Systems, for more
information about how to deploy the TestStand Engine and your custom
components.
Table 8-2 lists each subdirectory found in the NI and User directory trees
of the <TestStand>\Components directory.
Table 8-2. TestStand Component Subdirectories

Directory Name

Contents

Callbacks

The Callbacks directory contains the sequence files in which


TestStand stores Station Engine callbacks and Front-End callbacks.
TestStand installs the Station Engine and Front-End callback files into
the <TestStand>\Components\NI\Callbacks directory tree. Refer
to Chapter 10, Customizing Process Models and Callbacks, for more
information about customizing the Station Engine and Front-End
callbacks.

Compatibility

The Compatibility directory contains type palette files that TestStand


uses to save sequence files that are compatible with earlier versions of
TestStand.

Icons

The Icons directory contains icon files for module adapters and step
types. TestStand installs the icon files for module adapters and built-in
step types into the <TestStand>\Components\NI\Icons directory.
Refer to Chapter 13, Creating Custom Step Types, for more information
about creating your own icons for your custom step types.

Language

The Language directory contains string resource files. It has one


subdirectory per language. Refer to the Creating String Resource Files
section of this chapter for more information about creating string
resource files in the Language directory tree.

Models

The Models directory contains the default process model sequence files
and supporting code modules. Refer to Chapter 10, Customizing
Process Models and Callbacks, for more information about customizing
the process model.

Obsolete

The Obsolete directory contains components that TestStand no longer


uses but installs to maintain backwards compatibility.

National Instruments Corporation

8-5

NI TestStand Reference Manual

Chapter 8

Customizing and Configuring TestStand

Table 8-2. TestStand Component Subdirectories (Continued)

Directory Name

Contents

RuntimeServers

The RuntimeServers directory contains a LabVIEW 7.1.1 run-time


application for executing LabVIEW 7.1.1-based code modules without
the LabVIEW Development System. Refer to Chapter 5, Configuring
the LabVIEW Adapter, of the Using LabVIEW with TestStand manual
for more information about using LabVIEW run-time servers.

StepTypes

The StepTypes directory contains support files for step types.


TestStand installs the support files for the built-in step types into the
<TestStand>\Components\NI\StepTypes directory tree. Refer to
Chapter 13, Creating Custom Step Types, for more information about
customizing your own step types.

Tools

The Tools directory contains sequences and supporting files for the
Tools menu commands. Refer to the Tools Menu section of this chapter
for more information about customizing the Tools menu.

TypePalettes

The TypePalettes directory contains the default type palette files that
TestStand installs. Refer to Chapter 4, Built-In Step Types, for more
information about the default step types that TestStand installs. Refer to
Chapter 11, Type Concepts, for more information about step types and
data types.

Creating String Resource Files


TestStand installs the default resource string files in the <TestStand>\
Components\NI\Language directory. TestStand uses the
GetResourceString Engine method to obtain the string messages
that it displays in windows and dialog boxes in the sequence editor and user
interfaces. GetResourceString works with string resource files that are
stored in the .ini format. GetResourceString takes a string category and a
tag name as arguments and then searches for the string resource in all string
resource files that are in a predefined set of directories.
The directory search follows this order:

NI TestStand Reference Manual

1.

<TestStand>\Components\User\Language\<current
language>

2.

<TestStand>\Components\User\Language\English

3.

<TestStand>\Components\User\Language

4.

<TestStand>\Components\NI\Language\<current
language>

8-6

ni.com

Chapter 8

Customizing and Configuring TestStand

5.

<TestStand>\Components\NI\Language\English

6.

<TestStand>\Components\NI\Language

To change the current language setting, select ConfigureStation


Options.
If you want to customize a string resource file for a different language, you
must copy an existing language file from the NI directory, place it in the
User directory in a Language subdirectory, and modify it. If you want to
create a resource string file that applies to all languages, place the resource
file in the base <TestStand>\Components\User\Language directory.
If you want to create your own resource string file for your custom
components, ensure that the category names inside the resource file are
unique so that they do not conflict with any names that TestStand uses.
Note The TestStand Engine loads resource files when you start TestStand. If you make

changes to the resource files, you must restart TestStand for the changes to take effect, or
call the Engine.ReloadStringResourceFiles method.

String Resource File Format


Each string resource file must have the .ini file extension. String resource
files use the following format:
[category1]
tag1 = "string value 1"
tag2 = "string value 2"
[category2]
tag1 = "string value 1"
tag2 = "string value 2"
Note When you create new entries in a string resource file, begin your category name with
a unique ID such as a company prefix. Using a unique ID will prevent name collision. For
example, NI_SUBSTEPS uses NI as a unique ID.

National Instruments Corporation

8-7

NI TestStand Reference Manual

Chapter 8

Customizing and Configuring TestStand

When you specify custom resource strings, you create the category and
tag names. The number of categories and tags is unlimited. A string can be
of unlimited size. However, if a string has more than 512 characters, you
must break it into multiple lines. Each line has a tag suffix of lineNNNN,
where NNNN is the line number with zero padding. The following is an
example of a multiple-line string:
[category1]
tag1 line0001 = "This is the first line of a very long"
tag1 line0002 = "paragraph. This is the second line."

You can use escape codes to insert unprintable characters. Table 8-3 lists
the available escape codes.
Table 8-3. Resource String File Escape Codes

Escape Code

Description

\n

Embedded linefeed character.

\r

Carriage return character.

\t

Tab character.

\xnn

Hexadecimal value. For example, \x1B represents


the ASCII ESC character, which has a decimal
value of 27.

\\

Backslash character.

\"

DoubleQuote character.

The following string shows how to use \n, the embedded linefeed
character:
tag1 = "This is line one.\nThis is line two."

Configuring TestStand
This section outlines the configuration options in TestStand.

Sequence Editor and User Interface Startup Options


You can append certain options to the sequence editor and user interface
command line, separating various parameters by spaces. The sequence
editor and all user interface applications support command-line options for
opening and running sequences. Table 8-4 shows the valid startup options.

NI TestStand Reference Manual

8-8

ni.com

Chapter 8

Customizing and Configuring TestStand

Table 8-4. Sequence Editor or User Interface Startup Options

Option
sequencefile
{sequencefile2}...

Purpose
Instructs the application to automatically load the sequence files at
startup.
For example:
SeqEdit.exe "c:\MySeqs\seq1.seq" "c:\MySeqs\seq2.seq"

/run sequence
sequencefile

Instructs the application to automatically load and run the sequence in


the sequence file at startup.
For example:
SeqEdit.exe /run MainSequence "c:\MySeqs\test.seq"

/runEntryPoint
entrypointname
sequence file

Instructs the application to automatically load and execute the sequence


file at startup using the specified Execution entry point.
For example:
SeqEdit.exe /runEntryPoint "Test UUTs"
"c:\MySeqs\test.seq"

/editor

Instructs the application to open in editing mode if the application


supports editing.
For example:
testexec.exe /editor

/operatorInterface

Instructs the application to open in run-only mode.


For example:
testexec.exe /operatorInterface

/quit

Instructs the application to exit after the specified automatically run


executions complete.
For example:
SeqEdit.exe /run MainSequence "c:\MySeqs\test\seq"
/quit

The /quit command is ignored if the execution fails to launch.


/useExisting

Instructs the application to use the existing instance of the application


if one is already running instead of opening a new instance.
For example:
SeqEdit.exe /useExisting

The application ignores this option if the /quit option is specified.

National Instruments Corporation

8-9

NI TestStand Reference Manual

Chapter 8

Customizing and Configuring TestStand

Table 8-4. Sequence Editor or User Interface Startup Options (Continued)

Option
/setCurrentDir

Purpose
Instructs the application to set the current directory to the first directory
in the file dialog directory history list. The current directory is the
directory that the File dialog box initially displays when you open or
save a file. This option allows you to set the directory displayed by the
File dialog box to the directory that was displayed in the File dialog box
the last time that you ran the application. TestStand sets the current
directory after processing the other command-line options.
For example:
SeqEdit.exe /setCurrentDir

Instructs the application to launch a help dialog box that contains a list
of valid command-line arguments, and then to close immediately.

/?

For example:
SeqEdit.exe /?

All other options are ignored if the "/?" option is specified.


Note Both "/" and "-" are valid command prefixes.
Note Quotes are required for arguments that contain spaces, such as "Test UUTs" and
"C:\My Documents\MySeq.seq".
Note Refer to the ApplicationMgr.ProcessUserCommandLineArguments event for more

information on processing user command-line arguments in a user interface. If there is an


error in the command-line argument, the Application Manager control generates a
ReportError() event.

NI TestStand Reference Manual

8-10

ni.com

Chapter 8

Customizing and Configuring TestStand

Configure Menu
The Configure menu in the sequence editor and user interfaces contains
commands that control the operation of the TestStand station. The
following section provides a brief overview of the items in the Configure
menu. Refer to the NI TestStand Help for more information about the
dialog boxes that each menu item launches.

Sequence Editor OptionsLaunches the Sequence Editor Options


dialog box, in which you can set preferences for the sequence editor.

Station OptionsLaunches the Station Options dialog box, in which


you can set preferences for your TestStand station. These settings
affect all sequence editor and user interface sessions that you run on
your computer.

Search DirectoriesLaunches the Search Directories dialog box, in


which you can customize the search paths for finding files. The Search
Directories dialog box also displays a list of paths. The paths that
appear first in the list take precedence over the paths that appear later.
When you first run TestStand, the list contains a default set of directory
paths.

External ViewersLaunches the Configure External Viewers dialog


box, in which you can specify the external viewer to use for each report
format.

AdaptersLaunches the Adapter Configuration dialog box, in which


you can configure a specific module adapter, specify the active module
adapter, or configure whether the adapter is hidden in the Adapter ring
control in the sequence editor.

Report OptionsLaunches the Report Options dialog box, in which


you can customize the generation of report files.

Database OptionsLaunches the Database Options dialog box, in


which you can customize the logging of test result data.

Model OptionsLaunches the Model Options dialog box, in which


you can specify process model specific options, such as the number of
test sockets in the system.

National Instruments Corporation

8-11

NI TestStand Reference Manual

Creating Custom User Interfaces

This chapter outlines how to create or customize a user interface


application. User interfaces include applications that can only run
sequences and custom sequence editors. It also describes the various
example user interface applications that TestStand provides.
Refer to the following documents and examples in preparation for creating
a custom user interface application:

The Writing an Application with the TestStand UI Controls section of


this chapter.

The following sections of the NI TestStand Help:

TestStand ActiveX API OverviewContains an overview of the


TestStand ActiveX Server functionality and discusses how to call
the API from different programming languages.

Core UI Classes, Properties, Methods, and EventsLists the core


classes in the TestStand UI Controls.

Core API Classes, Properties, and MethodsLists the core


classes in the TestStand API.

The NI TestStand User Interface Controls Reference Poster, which is


included in your TestStand package.

The information in Chapter 6, Creating Custom User Interfaces in


LabVIEW, of the Using LabVIEW with TestStand manual and in
Chapter 6, Creating Custom User Interfaces in LabWindows/CVI,
of the Using LabWindows/CVI with TestStand manual.
If you are using an environment other than LabVIEW or
LabWindows/CVI, you can still refer to one of these sources for
general instructions on how to construct a user interface application.

National Instruments Corporation

The example projects and source code located in the <TestStand>\


UserInterfaces\NI directory. Start with these examples and
customize them to meet your requirements.

9-1

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Example User Interfaces


TestStand installs the executable, project, and source files for each example
user interface in the <TestStand>\UserInterfaces\NI directory. This
directory contains the Full-Featured and Simple subdirectories. The
Full-Featured subdirectory contains user interfaces that allow you to
load, view, edit, save, execute, and debug sequence files. The Simple
subdirectory contains similar user interfaces that are more limited than
those in the Full-Featured subdirectory in that they have no menus and
fewer commands and options. Also, the simple examples do not display
steps for sequences you load, but they do display the steps for executions
you run.
Both subdirectories contain examples with source code for LabVIEW,
LabWindows/CVI, C#, Microsoft Visual Basic .NET, and C++ (MFC).
To customize one of these user interfaces, copy the user interface project
and source files from the NI subdirectory to the <TestStand>\
UserInterfaces\User subdirectory before customizing them to ensure
that a newer installation of the same version TestStand does not overwrite
your customizations, or that uninstalling TestStand does not remove the
files you customize.
National Instruments recommends that you track the changes you make to the user
interface source so that you can integrate your changes with any enhancements from future
versions of the TestStand User Interfaces.

Tip

TestStand User Interface Controls


All user interface examples use the TestStand User Interface (UI) Controls.
The TestStand UI Controls are a set of ActiveX controls that implement the
common functionality that applications need in order to display, execute,
edit, save, and debug test sequences. These ActiveX controls greatly reduce
the amount of source code a user interface application requires.
National Instruments strongly recommends that you use these controls to
develop your user interface applications. However, you can also create an
application by directly calling the TestStand API.
For more information about writing an application by directly calling
the TestStand Engine API, refer to the Writing an Application with the
TestStand Engine API section of the NI TestStand Help.

NI TestStand Reference Manual

9-2

ni.com

Chapter 9

Creating Custom User Interfaces

Deploying a User Interface


Refer to Chapter 14, Deploying TestStand Systems, for more information
about deploying a TestStand User Interface application.

Writing an Application with the TestStand UI Controls


TestStand provides a number of controls that work together to simplify
programming a user interface. These controls fall into two
categoriesmanager controls and visible controls.

Manager Controls
Manager controls call the TestStand API to perform tasks such as loading
files, launching executions, and retrieving sequence information. Manager
controls also notify you when application events occur, such as when a user
logs in, an execution reaches a breakpoint, or a user changes the file or
sequence that they are viewing. These controls are visible at design time
but invisible at run time.
Connect the manager controls to visible TestStand UI Controls to
automatically display information or allow the user to select items to view.
The following sections describe the specific functionality of the three types
of manager controlsApplication Manager, SequenceFileView Manager,
and ExecutionView Manager.

Application Manager
The Application Manager control performs the following basic operations,
which are necessary to use the TestStand Engine in an application:

Processes command-line arguments.

Maintains an application configuration file.

Initializes and shuts down the TestStand Engine.

Logs users in and out.

Loads and unloads files.

Launches executions.

Tracks existing sequence files and executions.

Your application must have a single Application Manager control that


exists for the duration of the application.

National Instruments Corporation

9-3

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

SequenceFileView Manager
A SequenceFileView Manager control performs the following tasks to
manage how other visible TestStand UI Controls view and interact with
a selected sequence file:

Designates a sequence file as the selected sequence file.

Tracks which sequence, step group, and steps are selected in the
selected file.

Tracks which variables or properties are selected in the selected file.

Displays aspects of the selected file in the visible TestStand UI


Controls to which it connects.

Enables visible TestStand UI Controls to which it connects to change


the selected file, sequence, step group, and steps.

Provides editing and saving commands.

Provides methods for executing the selected sequence file.

Your application needs one SequenceFileView Manager control for each


location, such as a window, form, or panel, in which you either display a
sequence file or let the user select a current sequence file.

ExecutionView Manager
An ExecutionView Manager control performs the following tasks to
manage how other visible TestStand UI Controls view and interact with
a selected TestStand execution:

NI TestStand Reference Manual

Designates an execution as the selected execution.

Tracks which thread, stack frame, sequence, step group, and steps are
selected in the selected execution.

Tracks which variables or properties are selected in the selected


execution.

Displays aspects of the selected execution in the visible TestStand UI


Controls to which it connects.

Enables visible TestStand UI Controls to which it connects to change


the selected thread, stack frame, sequence, step group, and steps.

Sends events to notify your application of the progress and state of the
selected execution.

Provides debugging commands.

Updates the ReportView control to show the current report for the
selected execution.

9-4

ni.com

Chapter 9

Creating Custom User Interfaces

Your application needs one ExecutionView Manager control for each


location, such as a window, form, or panel, in which you either display
an execution or let the user select a current execution.

Visible TestStand UI Controls


Visible TestStand UI Controls are visible at both design time and run time.
These controls are similar to common Windows UI controls, but they
connect to manager controls to automatically display information or to
enable the user to select items to view. Table 9-1 describes the visible
TestStand UI Controls.
Table 9-1. Visible TestStand UI Controls

Control Name

Description

Button

Connect a manager control to a Button control to specify that the button


performs a common user interface command, such as "Open Sequence File".
The Button control automatically enables or disables according to the
application state. The Button control displays a localized caption.

ComboBox

Connect a SequenceFileView Manager control or an ExecutionView Manager


control to a ComboBox control to view or select a list of files, sequences, step
groups, executions, threads, or stack frames.

CheckBox

Connect a manager control to a CheckBox control to enable the user to toggle


the state of a common user interface command, such as "Break on Step
Failure".

ExpressionEdit

An ExpressionEdit control enables the user to edit a TestStand expression with


the convenience of syntax coloring, popup help, and statement completion.
Although you do not typically need to edit expressions in a user interface
application, you can connect a manager control to a read-only ExpressionEdit
control to automatically display text information about the application state,
such as the pathname of the selected sequence file or the name of the current
user.
You can also use ExpressionEdit controls on dialog boxes for step types and
tools in which you prompt the user to enter a TestStand expression.

InsertionPalette

Connect a SequenceFileView Manager control to an InsertionPalette control to


enable the user to insert steps and template items into a sequence file with only
a drag or a double-click.

Label

Connect a manager control to a Label control to automatically display text


information about the application state in the label, such as the name of the
current user or the status of the current UUT.

National Instruments Corporation

9-5

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Table 9-1. Visible TestStand UI Controls (Continued)

Control Name

Description

ListBar

A ListBar control displays multiple pages where each page contains a list
of items. You can view and select items from the selected page. Connect a
SequenceFileView Manager control or an ExecutionView Manager control to
a ListBar page to view and select from a list of files, sequences, step groups,
executions, threads, or stack frames.

ListBox

Connect a SequenceFileView Manager control or an ExecutionView Manager


control to a ListBox control to view or select from a list of files, sequences, step
groups, executions, threads, or stack frames.

ReportView

Connect an ExecutionView Manager control to a ReportView control to display


the report for the selected execution.

SequenceView

Connect a SequenceFileView Manager control or an ExecutionView Manager


control to a SequenceView control to display the steps of a sequence from a
selected file or execution. The SequenceView control displays the steps in a list
with columns whose contents you specify when you configure the control.

StatusBar

Connect a manager control to panes of a StatusBar control to display textual,


image, or progress information about the application state. You can also
programmatically control individual StatusBar panes to display custom
information.

VariablesView

Connect a SequenceFileView Manager control or an ExecutionView Manager


control to a VariablesView control to display the variables and properties in a
sequence file or an execution.

Connecting Manager Controls to Visible Controls


Connect a manager control to a visible control to automatically display
sequences or reports, present a list of items to the user, invoke an
application command, or display information about the current state of the
application. When you connect controls, your application does not need the
majority of the source code you would usually write to update the user
interface and respond to user input.
The specific connections you can make depend on the type of manager
control and visible control that you are connecting. The following kinds of
connections are available: view connections, list connections, command
connections, and information source connections.
Refer to the NI TestStand User Interface Controls Reference Poster for an
illustration of control connections in a sample user interface.

NI TestStand Reference Manual

9-6

ni.com

Chapter 9

Creating Custom User Interfaces

View Connections
You can connect manager controls to specific UI controls to display the
steps in a file or an execution, the report for an execution, the sequence
context for a file or execution, and the set of step types and templates the
user can insert into sequence files.
Connect a SequenceFileView Manager control to a SequenceView control
to display the steps in the selected sequence in the selected file.
Connect an ExecutionView Manager control to a SequenceView control
to display the steps in the currently executing sequence of the selected
execution. You can also connect an ExecutionView Manager control to a
ReportView control to display the report for the selected execution.
Connect a SequenceFileView Manager or ExecutionView Manager control
to a VariablesView control to display the sequence context for a sequence
file or execution.
Connect a SequenceFileView Manager control to an InsertionPalette
control to display the steps and templates that the user can insert into
sequence files.
Call the following methods to connect to view controls:

SequenceFileViewMgr.ConnectSequenceView

SequenceFileViewMgr.ConnectVariables

SequenceFileViewMgr.ConnectInsertionPalette

ExecutionViewMgr.ConnectExecutionView

ExecutionViewMgr.ConnectReportView

ExecutionViewMgr.ConnectVariables

List Connections
You can connect a TestStand ComboBox control, ListBox control, or a
ListBar page to a list provided by a manager control. Table 9-2 specifies the
available list connections.
Table 9-2. Available List Connections

National Instruments Corporation

List

Manager Control

Adapters

Application Manager

Sequence Files

SequenceFileView Manager

9-7

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Table 9-2. Available List Connections (Continued)

List

Manager Control

Sequences

SequenceFileView Manager

Step Groups

SequenceFileView Manager

Executions

ExecutionView Manager

Threads

ExecutionView Manager

Stack Frames

ExecutionView Manager

A manager control designates one item in each list as the selected item.
A visible control that you connect to a list displays the list and indicates the
selected item. The visible control also allows you to change the selected
item, unless the application state or control configuration prohibits
changing the selection. When you change the selected item, other controls
that display the list or the selected list item update to display the new
selection. For example, you can connect a SequenceFileView Manager
control to a SequenceView control and connect its sequence file list to a
combo box. When you change the selected file in the combo box, the
SequenceView control updates to show the steps in the newly selected
sequence file.
Call the following methods to connect a list to a ComboBox control,
ListBox control, or a ListBar page:

NI TestStand Reference Manual

ApplicationMgr.ConnectAdapterList

SequenceFileViewMgr.ConnectSequenceFileList

SequenceFileViewMgr.ConnectSequenceList

SequenceFileViewMgr.ConnectStepGroupList

ExecutionViewMgr.ConnectExecutionList

ExecutionViewMgr.ConnectCallStack

ExecutionViewMgr.ConnectThreadList

9-8

ni.com

Chapter 9

Creating Custom User Interfaces

Command Connections
TestStand applications typically provide commands to the user through
menus, buttons, or other controls. Many commands are common to
most applications, such as OpenSequenceFile, ExecuteEntryPoint,
RunSelectedSteps, Break, Resume, Terminate, and Exit. The TestStand UI
Controls Library provides a set of common commands you can add to your
application. You can connect these commands to TestStand buttons or
application menu items. When you connect a command to a button or menu
item, the button or menu item automatically executes the command. You
do not need an event handler to implement the command.
The commands also determine the menu item or button text to display
according to the current language and automatically dim or enable buttons
or menu items according to the state of the application. Because the
TestStand UI Controls Library implements many common application
commands, connecting commands to buttons and menu items significantly
reduces the amount of source code your application requires.
The CommandKinds enumeration defines the set of available commands. Refer to the
NI TestStand Help for more information about this enumeration before adding commands
to your application so that you do not unnecessarily re-implement an existing command.

Tip

Some commands apply to the selected item in the manager control to which
you connect. For example, the Break command suspends the current
execution that an ExecutionView Manager control selects. Other
commands, such as Exit, function the same regardless of the manager
control you use to connect them.
Refer to the NI TestStand Help for information about each CommandKinds
enumeration constant and the manager controls with which the command
functions.
Call the following methods to connect a command to a Button or CheckBox
control:

ApplicationMgr.ConnectCommand

SequenceFileViewMgr.ConnectCommand

ExecutionViewMgr.ConnectCommand

Refer to the Menus and Menu Items section of this chapter for information
about how to connect commands to menu items.

National Instruments Corporation

9-9

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

To invoke a command without connecting it to a control, obtain a


Command object from one of the following methods:

ApplicationMgr.GetCommand

ApplicationMgr.NewCommands

SequenceFileViewMgr.GetCommand

ExecutionViewMgr.GetCommand

After you obtain a Command object, call the Command.Execute method


to invoke the command.

Information Source Connections


Manager controls can connect information sources to Label and
ExpressionEdit controls and StatusBar panes to display information about
the state of the application. The types of information connections you can
establish are caption connections, image connections, and numeric value
connections.

Caption Connections
Caption connections display text that describes the status of the application.
For example, you can use the Application Manager control to connect a
caption to a Label control so that the Label control automatically displays
the name of the currently logged in user.
The CaptionSources enumeration defines the set of captions to which you
can connect. Some captions apply to the selected item in the manager
control with which you connect them. For example, the UUTSerialNumber
caption displays the serial number of the current UUT for the execution
that an ExecutionView Manager control selects. Other captions, such as
UserName, function the same regardless of which manager control you use
to connect them.
Refer to the NI TestStand Help for information about each CaptionSources
enumeration constant and the manager controls with which the caption
source functions.
Call the following methods to connect a caption to a Label control,
ExpressionEdit control, or StatusBar pane:

NI TestStand Reference Manual

ApplicationMgr.ConnectCaption

SequenceFileViewMgr.ConnectCaption

ExecutionViewMgr.ConnectCaption

9-10

ni.com

Chapter 9

Creating Custom User Interfaces

Call the following methods to obtain the text of a caption without


connecting it to a control:

ApplicationMgr.GetCaptionText

SequenceFileViewMgr.GetCaptionText

ExecutionViewMgr.GetCaptionText

Image Connections
Image connections display icons that illustrate the status of the application.
For example, you can use the ExecutionView Manager control to connect
an image to a Button control or a StatusBar pane so that the pane
automatically displays an image that indicates the execution state of
the selected execution.
The ImageSources enumeration defines the set of images to which you can
connect. Images may depend on the selected item in the manager control
with which you connect them. For example, the CurrentStepGroup
enumeration constant displays an image for the currently selected step
group when you connect it to a SequenceFileView Manager control, or it
displays an image for the currently executing step group when you connect
it to an ExecutionView Manager control.
Refer to the NI TestStand Help for information about each ImageSources
enumeration constant and the manager controls with which the image
source functions.
Call the following methods to connect an image to a Button control or a
StatusBar pane:

ApplicationMgr.ConnectImage

SequenceFileViewMgr.ConnectImage

ExecutionViewMgr.ConnectImage

To obtain an image without connecting it to a control, call the following


methods:

ApplicationMgr.GetImageName

SequenceFileViewMgr.GetImageName

ExecutionViewMgr.GetImageName

Note To obtain an image from an image name, you must use properties from the
TestStand API such as Engine.SmallImageList, Engine.LargeImageList, and
Engine.Images.

National Instruments Corporation

9-11

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Numeric Value Connections


A numeric value connection graphically displays a numeric value that
illustrates the status of the application. For example, you can use the
ExecutionView Manager control to connect a numeric value to a StatusBar
pane so that the StatusBar pane automatically displays a progress bar that
indicates the percentage of progress made in the current execution.
The NumericSources enumeration defines the set of values to which you
can connect. Refer to the NI TestStand Help for information about each
NumericSources enumeration constant and the manager controls with
which the command functions.
To connect a numeric source to a StatusBar pane, call
ExecutionViewMgr.ConnectNumeric. To obtain a numeric value
without connecting it to a control, call
ExecutionViewMgr.GetNumeric.

Specifying and Changing Control Connections


An application typically establishes control connections after loading
the window that contains the controls to be connected. However, the
application can establish or change control connections at any time.
Connections from manager controls to visible controls are many-to-one.
Therefore, you can make the same connection from a manager control to
multiple visible controls. For example, if you connect two combo boxes to
the sequence list of a SequenceFileView Manager control, both combo
boxes display the selected sequence in the current file. If you change the
selection in one combo box, the other combo box updates to show the new
selection. However, a visible control or a connectable element of a visible
control, such as a ListBar page or a StatusBar pane, can have only one
connection of a particular type. When you connect a manager control to
a visible control that is already connected, the new connection replaces the
existing connection to the visible control.

Editor Versus Operator Interface Applications


A TestStand application that permits the user to create, edit, and save
sequence files is referred to as an Editor application. A TestStand
application that only allows the user to run sequences is referred to
as an OperatorTestStand UI Controls Interface application.

NI TestStand Reference Manual

9-12

ni.com

Chapter 9

Creating Custom User Interfaces

You can use the TestStand UI Controls to create Editor applications,


Operator Interface applications, or applications that can switch between
Editor and Operator Interface modes.

Creating Editor Applications


To create an Editor application, you must put the TestStand UI Controls in
Editor mode.
To specify whether Editor mode is on or off by default, set the IsEditor
property of the Application Manager control at design time. Alternatively,
you can set the IsEditor property in your application source code before you
call ApplicationMgr.Start.
You can override the default editing mode for your application by passing
a command-line argument. Pass /editor to set the IsEditor property or
pass /operatorInterface to clear the IsEditor property. To prevent the
user from changing the IsEditor property from the command line, set
ApplicationMgr.CommandLineCanChangeEditMode to False.
The full-featured, user interface examples enable the user to toggle the
editing mode by pressing <Ctrl-Alt-Shift-Insert>. To change or disable
this keystroke in an application based on a full-featured example, set the
ApplicationMgr.EditModeShortcutKey and
ApplicationMgr.EditModeShortcutModifier properties in the
designer or in the user interface source code.
Note To toggle the editing mode with a keystroke, the current user must have permission

to edit sequence files.

License Checking
The Start method on the Application Manager control verifies that a license
is available to run the application. If there is no license available, the Start
method throws an error which the application displays before it exits. If an
unactivated license or an evaluation license is available, Start prompts the
user to activate a license.
If ApplicationMgr.IsEditor is True, Start requires a license that permits
editing. If you call Start when IsEditor is False and later set IsEditor to
True, the property set throws an error if it cannot obtain a license that
permits editing.

National Instruments Corporation

9-13

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Using TestStand UI Controls in Different Environments


The following sections describe how to use the TestStand UI Controls in
different environments.

LabVIEW
To use the TestStand UI Controls in LabVIEW, use the VIs, functions, and
UI Controls on the TestStand Functions and Controls palettes. Refer to
Chapter 6, Creating Custom User Interfaces in LabVIEW, of the Using
LabVIEW with TestStand manual for more information about using the
TestStand UI Controls in LabVIEW.

LabWindows/CVI
To use the TestStand UI Controls with LabWindows/CVI, add the
following files to your project from the <TestStand>\API\CVI
directory:

tsui.fpActiveX API for the TestStand UI Controls

tsuisupp.fpActiveX API for use with less commonly used


interfaces provided by the TestStand UI Controls

tsutil.fpFunctions that facilitate using the TestStand API and the


TestStand UI Controls with LabWindows/CVI

tsapicvi.fpActiveX API for the TestStand Engine

Include the following header files, located in the <TestStand>\API\CVI


directory, in your source files as needed:

tsui.h

tsuisupp.h

tsutil.h

tsapicvi.h.

To add a TestStand UI Control to a panel in the LabWindows/CVI UIR


editor, select ActiveX from the Create menu and select a control that has
a name beginning with TestStand UI.
Refer to Chapter 6, Creating Custom User Interfaces in LabWindows/CVI,
of the Using LabWindows/CVI with TestStand manual for more
information about using the TestStand UI Controls in LabWindows/CVI.

NI TestStand Reference Manual

9-14

ni.com

Chapter 9

Creating Custom User Interfaces

Microsoft Visual Studio


To use the TestStand UI Controls with Microsoft Visual Studio, drag the
TestStand UI Controls from the TestStand tab on the Visual Studio
Toolbox onto your form.
Note When you create a new project in Visual Studio 2005, you must set Project

PropertiesBuildPlatform Target to x86 so that your project can access the TestStand
API and UI controls on 64-bit versions of Windows.
Note If the TestStand tab is not visible in the Visual Studio Toolbox window when you

edit your form or if the TestStand Interop assemblies do not appear in the Add References
dialog box, follow these steps to install them. First, exit all running copies of
Visual Studio. Then, run the TestStand Version Switcher utility. Select the current version
of TestStand and click Make Active.
You must also add references to the TestStand Interop assemblies and
TSUtil assembly to your project. Refer to Accessing the TestStand API in
Visual Studio .NET 2003 and Visual Studio 2005 section of Chapter 5,
Adapters, for information about adding references to .NET interop
assemblies for the TestStand API. Refer to the TestStand Utility Functions
Library section of this chapter for information about adding a reference to
the TSUtil Library for .NET.
Note If you plan to create a MDI application with TestStand UI Controls on a MDI child

form, the properties that you programmatically set on the UI controls will be reset to
default values when you set the MdiParent property on the child form. These properties
are reset because the .NET framework destroys and recreates ActiveX controls on a form
when you set the property on that form. To avoid this issue, select one of the following
options:

Set the control properties after setting the MdiParent property on the form.

Place all TestStand UI Controls and other ActiveX controls on a Panel control instead
of directly on the form.

Visual C++
To use the TestStand UI Controls with Visual C++, add the TestStand
Utility (TSUtil) Functions Library to your project as described in
the TestStand Utility Functions Library section of this chapter. The
TSUtilCPP.cpp and TSUtilCPP.h files automatically import the type
libraries for the TestStand API and the TestStand UI Controls.

National Instruments Corporation

9-15

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

You can view the header files that the #import directive generates for the
TestStand API type libraries by opening the tsui.tlh, tsuisupp.tlh,
and tsapi.tlh files that Visual C++ creates in your Debug or Release
directory. These header files define a C++ class for each object class in the
TestStand API. The letter I is used as a prefix in class names for ActiveX
controls and objects that you can create without calling another class.
The header files use macros to define a corresponding smart pointer
class for each object class. Each smart pointer class uses the name of its
corresponding class and adds a Ptr suffix. Typically, you only use smart
pointer classes in your application. For example, instead of using the
SequenceFile class, use the SequenceFilePtr class.
Note National Instruments recommends that you use the classes that the #import directive

generates to call the TestStand ActiveX API instead of generating MFC wrapper class files
using the Class Wizard tool.
To add a TestStand UI Control to a dialog box as a resource, select Insert
ActiveX Control from the dialog box context menu and select a control
whose name begins with TestStand UI.
Note If you programmatically create a TestStand UI Control in an MFC container, you

must remove the WS_CLIPSIBLINGS style from the control window for the TestStand UI
Control to be visible inside an MFC Group Box control. If you do not remove the
WS_CLIPSIBLINGS style, a native MFC control always obscures the TestStand UI
Control, even if the MFC control comes after the TestStand UI Control in the tab order.

Obtaining an Interface Pointer and CWnd for an ActiveX Control


You can use the following steps to obtain an interface pointer to an ActiveX
control, such as a TestStand UI control, that you insert into an MFC dialog
resource.

Using GetDlgItem
1.

Add a CWnd member to the dialog class for the control as follows:
CWnd mExprEditCWnd;

2.

Insert the following code into the OnInitDialog method of the dialog
class:
mExprEditCWnd.Attach(GetDlgItem
(IDC_MYEXPRESSIONEDIT)->m_hWnd);

NI TestStand Reference Manual

9-16

ni.com

Chapter 9

3.

Creating Custom User Interfaces

Obtain the interface pointer from the CWnd member as follows:


TSUI::IExpressionEditPtr myExprEdit =
mExprEditCWnd.GetControlUnknown();

Note National Instruments does not recommend using DoDataExchange to obtain an


interface pointer and CWnd for a TestStand ActiveX User Interface Control. You should
only use DoDataExchange when controls are windowless or do not recreate their internal
windows. TestStand 3.5 incorrectly listed this as a method to obtain an interface pointer.

Handling Events
TestStand UI Controls send events to notify your application of user input
and of application events, such as an execution completing. The visible
controls send user input events such as KeyDown or MouseDown.
The manager controls send application state events such as
SequenceFileOpened or UserChanged. You can choose to handle
any number of events according to the needs of your application.

Creating Event Handlers in Your ADE


Table 9-3 describes how to create an event handler in your specific ADE.
Table 9-3. Creating an Event Handler in Your ADE

ADE
LabVIEW

Description
Register event handler VIs with the Register Event Callback function.
Refer to Chapter 6, Creating Custom User Interfaces in LabVIEW, of
the Using LabVIEW with TestStand manual for information about
handling events from the TestStand UI Controls in LabVIEW.

LabWindows/CVI

Install ActiveX event callback functions by calling the


TSUI_<object class>EventsRegOn<event name> functions

in tsui.fp.
Refer to Chapter 6, Creating Custom User Interfaces in
LabWindows/CVI, of the Using LabWindows/CVI with TestStand
manual for information about handling events from the TestStand UI
Controls in LabWindows/CVI.
.NET

Create .NET control event handlers from the form designer.

C++ (MFC)

Create ActiveX event handlers from the Message Maps page of the
Class Wizard dialog box.

National Instruments Corporation

9-17

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Events Handled by Typical Applications


When you create your application, you can direct your application to
handle any subset of the available TestStand UI Control events. However,
an application typically handles the following eventsExitApplication,
Wait, ReportError, DisplaySequenceFile, and DisplayExecution.

ExitApplication
The Application Manager control generates this event to request that your
application exit. Handle this event by directing your application to exit
normally. For more information about shutting down your application,
refer to the Startup and Shut Down section of this chapter.

Wait
The Application Manager control generates this event to request that your
application either display or remove a busy indicator. Handle this event by
displaying or removing a wait cursor according to the value of the
showWait event parameter.

ReportError
The Application Manager control generates this event to request that the
user interface displays to the user an error that occurs during user input or
during an asynchronous operation. Handle this event by displaying the
error code and description in a dialog box or by appending the error code
and description to an error log.
Note This event indicates an application error, not a sequence execution error. The

BreakOnRunTimeError event indicates a sequence execution error.

DisplaySequenceFile
The Application Manager control generates this event to request that
the application display a particular sequence file. For example, the
Application Manager control generates this event when the user opens
a sequence file. To handle this event, display the file by setting the
SequenceFileViewMgr.SequenceFile property. If your application
has only a single window, set this property on the SequenceFileView
Manager control that resides on that window.
If your application displays each file in a separate window
using separate SequenceFileView Manager controls, call
ApplicationMgr.GetSequenceFileViewMgr to find the

NI TestStand Reference Manual

9-18

ni.com

Chapter 9

Creating Custom User Interfaces

SequenceFileView Manager control that currently displays the file so that


you can activate the window that contains it. If no SequenceFileView
Manager control currently displays the file, a multiple window
application can create a new window that contains a SequenceFileView
Manager control. The application can then set the
SequenceFileViewMgr.SequenceFile property of the control to display the
file in the new window.

DisplayExecution
The Application Manager control generates this event to request that the
application display a particular execution. For example, the Application
Manager control generates this event when the user starts a new
execution. To handle this event, display the execution by setting the
ExecutionViewMgr.Execution property. If your application has only
a single window, call this method on the ExecutionView Manager control
that resides on that window.
If your application displays each execution in a separate window using
separate ExecutionView Manager controls, call the
ApplicationMgr.GetExecutionViewMgr method to find the
ExecutionView Manager control that currently displays the execution so
that you can activate the window that contains it. If no ExecutionView
Manager control currently displays the execution, a multiple
window application can create a new window that contains an
ExecutionView Manager control. The application can then set the
ExecutionViewMgr.Execution property of the ExecutionView Manager
control to display the execution in the new window.

Startup and Shut Down


As a final step in the initialization of your application, call the
ApplicationMgr.Start method. This method initializes the
Application Manager control and launches the LoginLogout Front-End
callback if you have not set the ApplicationMgr.LoginOnStart
property to False.
Complete the following steps to shut down your application:
1.

National Instruments Corporation

If your application holds any references to TestStand objects,


such as sequence files or executions, handle the
ApplicationMgr.QueryShutDown event. To respond to the event,
cancel the shut down process or release the TestStand object references
your application holds.

9-19

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

2.

3.

Call ApplicationMgr.ShutDown. If this method returns True,


exit your application. If the method returns False, do not exit the
application. Leaving the application running allows the method to shut
down any running executions and unload sequence files. If the shut
down process completes, the Application Manager control generates
the ExitApplication event to notify you that you can now exit the
application. If the shut down process is cancelled, the Application
Manager control generates the ShutDownCancelled event. This occurs
if the user chooses not to terminate a busy execution.
Exit the application in the event handler you create for the
ApplicationMgr.ExitApplication event. The window in which

the Application Manager control resides must exist until you receive
the ExitApplication event.
Note When you use the TestStand UI Controls to create an Exit button or an Exit menu
item that invokes the Exit command, the button or menu item automatically calls
ApplicationMgr.ShutDown for you.

TestStand Utility Functions Library


The TestStand Utility (TSUtil) Functions Library is a set of functions
that help you to use certain aspects of the TestStand API in particular
programming environments. Many TSUtil functions operate on
environment-specific objects, such as menus, that the environment-neutral
TestStand API cannot access. The functions available in TSUtil vary
according to your programming environment.
To assist user interface developers, the TSUtil library contains functions to
insert menu items that automatically execute commands that the TestStand
UI Controls library provides. The TSUtil library also provides functions
that help you localize the strings on your user interface.
Refer to the Menus and Menu Items section of this chapter for information
about using TSUtil functions to create menu items that perform common
TestStand commands. Refer to the Localization section of this chapter for
information about how to display application user interface strings in a
selected language.

NI TestStand Reference Manual

9-20

ni.com

Chapter 9

Creating Custom User Interfaces

The following tables describe how to use the TSUtil library in each
programming environment:
Table 9-4. Using the TSUtil Library in LabVIEW

Library Format

VIs on the FunctionsTestStand palette.

Help Location

VI help inside each VI.

How to Use

Place VIs on the block diagram as needed. Refer to the Using LabVIEW with
TestStand manual for more information about using the TSUtil library in
LabVIEW.

Table 9-5. Using the TSUtil Library in LabWindows/CVI

Library Format

Instrument Driver.

Help Location

Function panels (TSUtil.fp).

Files

TSUtil.c, TSUtil.h, TSUtil.fp, and TSUtil.obj (located in the


<TestStand>\ API\CVI directory).

How to Use

Insert TSUtil.fp into your LabWindows/CVI project. Include TSUtil.h in


your source files as needed. The names of TestStand-related functions in this
library begin with a TS_ prefix.

Table 9-6. Using the TSUtil Library in .NET Languages

Library Format

Assembly.

Help Location

In the Object Browser and in the source window using Intellisense.

Location

<TestStand>\API\DotNet\Assemblies\
CurrentVersion.

National Instruments Corporation

9-21

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Table 9-6. Using the TSUtil Library in .NET Languages (Continued)

File

NationalInstruments.TestStand.Utility.dll.

How to Use

Add a reference to the assembly to your project. The classes in this assembly
reside in the National Instruments.TestStand.Utility namespace.
To add a reference to the assembly in Visual Studio 2005, select the project in
the Solution Explorer. Select Add Reference from the Project menu to launch
the Add Reference dialog box. Next, select the .NET tab and select
NationalInstruments.TestStand.Utility from the list of components.
Click OK to close the Add Reference dialog box.
To add a reference to the assembly in Visual Studio .NET 2003, you must use
an assembly that is compatible with TestStand 3.5 or earlier. Select the project
in the Solution Explorer. Select Add Reference from the Project menu to
launch the Add Reference dialog box. Next, select the .NET tab and click the
File Browse button to launch the Select Components dialog box. Then,
navigate to the <TestStand>\API\DotNet\Assemblies\
PreviousVersion\3.5 directory. Select
NationalInstruments.TestStand.Utility.dll and click Open. Click
OK to close the Add Reference dialog box.
Table 9-7. Using the TSUtil Library in C++ (MFC)

Library Format

C++ source code.

Help Location

Comments in the C++ header file, TSUtilCPP.h.

Files

TSUtilCPP.cpp and TSUtilCPP.h (located in the <TestStand>\API\VC

directory).
How to Use

Add TSUtilCPP.cpp to your project once. Include TSUtilCPP.h in your


source files as needed. The classes in this library reside in the TSUtil
namespace.
If your programming environment is not described in this section, there is
not a version of TSUtil for your environment. In this case, you can write
your own code that performs equivalently to any functions you need from
the TSUtil library. You can use the source code for one of the existing
TSUtil libraries as a guide.

NI TestStand Reference Manual

9-22

ni.com

Chapter 9

Creating Custom User Interfaces

Menus and Menu Items


TestStand applications that provide non-trivial menus can require a large
amount of source code to build and update the state of menus and to handle
events for menu items. You can greatly reduce the amount of code required
to implement menus in your application by calling TSUtil functions to
create menu items that invoke TestStand commands. These menu items are
automatically dimmed or enabled according to the application state and set
their captions according to the selected language. The menu items execute
their commands automatically so that your application does not need to
handle menu events or provide command implementations.
Your application can also insert sets of dynamic menu items, such as a set
of menu items to open files from the most recently used file list or a set of
menu items that run the current sequence with each available Process
Model entry point. To create TestStand menu items, you must first add
TSUtil to your project as described in the TestStand Utility Functions
Library section of this chapter.
Note The TSUtil .NET menu functions support using the MainMenu control available in

Visual Studio .NET 2003, and do not support using the MenuStrip control available in
Visual Studio 2005. To access the .NET MainMenu control in the Visual Studio 2005
Toolbox, select Choose Items from context menu in the Toolbox pane, enable
MainMenu 2.0 on the .NET Framework Components tab of the Choose Toolbox Items
dialog box, and select OK to close the dialog box. The full-featured .NET example user
interface applications use MainMenu to display menus.

Updating Menus
The contents of a menu can vary, depending on the current selection or
other user input, or due to asynchronous execution state changes. Instead of
updating a menu in response to any event or change that may affect it, it is
simpler to update the state of a menu just before it displays when the user
opens it. Programming environments provide an event that notifies you
when a menu is about to open. Table 9-8 describes the notification method
for each environment.

National Instruments Corporation

9-23

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Table 9-8. Menu Open Notification Methods by ADE

Environment

Menu Open Notification Method


<This VI>:Menu Activation? event

LabVIEW

Refer to the Using LabVIEW with TestStand


manual for information about how to determine
when a menu is about to open in LabVIEW.
LabWindows/CVI

InstallMenuDimmerCallback

Refer to the Using LabWindows/CVI with


TestStand manual for information about how to
determine when a menu is about to open in
LabWindows/CVI.
.NET

Form.MenuStart

The TSUtil .NET menu functions support


using the MainMenu control available in
Visual Studio .NET 2003, and do not support
using the MenuStrip control available in Visual
Studio 2005.
C++ (MFC)

CWnd::OnInitMenuPopup

To handle this notification, use the following TSUtil functions to remove


and reinsert all TestStand menu items from your menus:
RemoveMenuCommands, InsertCommandsInMenu, and CleanupMenu.
InsertCommandsInMenu takes an array of CommandKinds enumeration
constants. Depending on the element value and the application state, each
array element can create a single menu item, a set of several menu items, or
no menu items. The CommandKinds enumeration also provides constants
that expand into the full set of items commonly found in test application
top-level menus, such as the File menu, Debug menu, or Configure menu.
Note You can insert and remove TestStand commands in menus that also contain

non-TestStand menu items.


Refer to the TestStand Utility Functions Library section of this chapter
for the full set of menu support functions specific to your environment
and descriptions of how to use them. Refer to the examples in the
<TestStand>\UserInterfaces\NI\Full-Featured directory for
sample code that handles open notification events for menus.

NI TestStand Reference Manual

9-24

ni.com

Chapter 9

Creating Custom User Interfaces

Localization
The Engine.StationOptions.Language property specifies the
current language. Localized TestStand applications use the
Engine.GetResourceString method to obtain text in the current system
language from language resource files. Refer to the Creating String
Resource Files section of Chapter 8, Customizing and Configuring
TestStand, for information about creating your own string resource files.
To localize all of the user-visible TestStand UI Control
strings that you configure at design time, call
ApplicationMgr.LocalizeAllControls. This reduces the number of
strings you must explicitly localize using Engine.GetResourceString by
localizing items such as list column headers in the SequenceView control,
text in the StatusBar pane, captions in the Button control, and captions in
the ListBar page.
Note Buttons and menu items that you connect to commands automatically localize

their caption text. Refer to the Command Connections section of this chapter for more
information about connecting buttons and menu items to commands.
The LocalizeAllControls method operates on TestStand UI Controls only.
For other controls and user interface elements, your application must set
each item of localized text. However, the TSUtil library provides functions
to assist in localizing these other controls and menu items. These functions
are described in Table 9-9.
Table 9-9. TSUtil Library Localization Functions by Environment

Environment
LabVIEW

TSUtil Library Localization Function


TestStand - Localize Front Panel.vi
TestStand - Localize Menu.vi
TestStand - Get Resource String.vi

LabWindows/CVI

TS_LoadPanelResourceStrings
TS_LoadMenuBarResourceStrings
TS_SetAttrFromResourceString
TS_GetResourceString

National Instruments Corporation

9-25

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Table 9-9. TSUtil Library Localization Functions by Environment (Continued)

Environment
.NET

TSUtil Library Localization Function


Localizer.LocalizeForm
Localizer.LocalizeMenu

C++ (MFC)

Localizer.LocalizeWindow
Localizer.LocalizeMenu
Localizer.LocalizeString

For more information about the TSUtil library, refer to the TestStand Utility
Functions Library section of this chapter.

User Interface Application Styles


Although you can use the TestStand UI Controls to create any type of
application, the following application formats are the most common: single
window, multiple window, or no visible window. Applications of a
particular style tend to share a similar implementation strategy, particularly
with respect to their use of the TestStand manager controls. The following
sections describe implementation strategies for these common application
styles.
Note Because the structure of your application may not exactly match one of the

described applications, use these descriptions only as a guide. You should implement
the approach that best suits your application.

Single Window
A single window application typically displays one execution and/or
sequence file at a time. The user can select the execution and sequence file
to display from a ListBar, ComboBox, or ListBox control. The examples
in the <TestStand>\UserInterfaces\NI\Full-Featured and
<TestStand>\UserInterfaces\NI\Simple directories are single
window applications.
The single window application contains one Application Manager control,
one SequenceFileView Manager control, and one ExecutionView Manager
control. To display sequences, you can connect the SequenceFileView
Manager and ExecutionView Manager controls to separate SequenceView
controls, alternate a connection from each manager control to a single
SequenceView control, or leave one or both manager controls unconnected
to a SequenceView control.

NI TestStand Reference Manual

9-26

ni.com

Chapter 9

Creating Custom User Interfaces

In the examples in the Full-Featured directory, the SequenceFileView


Manager control and the ExecutionView Manager control connect to
separate SequenceView controls, but only one SequenceView control is
visible at a time. Visibility is based on whether you select to view sequence
files or executions in the list bar.
In the examples in the Simple directory, the ExecutionView Manager
control connects to the SequenceView control. Because the
SequenceFileView Manager control does not connect to a SequenceView
control, these examples only display sequences for the current execution
and do not display sequences from the selected sequence file.

Multiple Window
A multiple window application has at least one window that always exists
in order to contain the Application Manager control. Although this window
may be visible or invisible, it is typically visible and contains controls that
enable the user to open sequence files.
For each sequence file that you open, the application creates a Sequence
File window that contains a SequenceFileView Manager control and a
SequenceView control to which it connects. The application sets the
SequenceFileViewMgr.UserData property to attach a handle, reference,
or pointer that represents the window. When the application receives the
ApplicationMgr.DisplaySequenceFile event, it calls
ApplicationMgr.GetSequenceFileViewMgr to determine whether a
SequenceFileView Manager control is currently displaying the sequence
file. If so, the application retrieves the window from the
SequenceFileViewMgr.UserData property and activates the window.
If there is no window currently displaying the file, the application creates a
new window and sets the SequenceFileViewMgr.SequenceFile property to
display the specified file. Because the window only displays this file,
the application also sets the
SequenceFileViewMgr.ReplaceSequenceFileOnClose property to False.
If a Sequence File window attempts to close and the
SequenceFileViewMgr.SequenceFile property is NULL, the
application allows the window to close immediately. If the
SequenceFileViewMgr.Sequence File property is not NULL, the application
does not close the window. Instead, the application passes the file to the
ApplicationMgr.CloseSequenceFile method. When the application
receives the SequenceFileViewMgr.SequenceFileChanged event with a
NULL sequence file event parameter, it closes the window that holds the
SequenceFileView Manager control.

National Instruments Corporation

9-27

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

The Sequence File window contains controls that allow you to execute the
displayed file. For each execution that you start, the application creates an
Execution window that contains an ExecutionView Manager control and a
SequenceView control to which it connects. The application sets the
ExecutionViewMgr.UserData property to attach a handle, reference, or
pointer that represents the window. When the application receives the
ApplicationMgr.DisplayExecution event, it calls
ApplicationMgr.GetExecutionViewMgr to determine whether an
ExecutionView Manager control is currently displaying the execution.
If so, the application retrieves the window from the
ExecutionViewMgr.UserData property and activates the window. If there is
no window currently displaying the execution, the application creates a new
window and sets the ExecutionViewMgr.Execution property to display the
specified execution. Because the window only displays this execution, the
application also sets the ExecutionViewMgr.ReplaceExecutionOnClose
property to False.
If an Execution window attempts to close and the
ExecutionViewMgr.Execution property is NULL, the application allows
the window to close immediately. If the ExecutionViewMgr.Execution
property is not NULL, the application does not close the window and instead
passes the execution to the ApplicationMgr.CloseExecution method. The
application does not immediately close the Execution window to ensure
that it exists until the execution it displays completes. When the application
receives the ExecutionViewMgr.ExecutionChanged event with a NULL
execution event parameter, it closes the window that holds the
ExecutionView Manager control.
A multiple window application can display multiple child windows instead
of displaying sequence files and executions in separate top-level windows.
Child windows can be simultaneously visible or reside in tab control pages
or similar locations that allow you to easily select which child window
to view.

No Visible Window
An application without a visible window is similar to a single window
application except that it does not display its window. The application can
allow its command-line arguments to execute and then exit, or it might
have a different mechanism to determine which files to load and execute.
Although an invisible application does not require an ExecutionView
Manager control, it may use a SequenceFileView Manager control to

NI TestStand Reference Manual

9-28

ni.com

Chapter 9

Creating Custom User Interfaces

provide methods to launch an execution for a selected file. Use the


following SequenceFileView Manager control properties and methods
to launch executions:

ExecutionEntryPoints

Run

RunSelectedSteps

LoopOnSelectedSteps

GetCommand

Command-Line Arguments
The Application Manager control automatically processes the command
line that invokes your application when you call ApplicationMgr.Start.
To disable command-line processing, set the
ApplicationMgr.ProcessCommandLine property to False before
calling ApplicationMgr.Start. Refer to the Configuring TestStand
section of Chapter 8, Customizing and Configuring TestStand, for a
description of the command-line arguments that are processed by the
Application Manager control.
You can also handle the ProcessUserCommandLineArguments event
from the Application Manager to support additional command-line
arguments. The ProcessUserCommandLineArguments event occurs when
the Application Manager control parses and processes a command-line flag
that is unrecognized. Refer to the NI TestStand Help for more information
about how to use the ProcessUserCommandLineArguments event to
support user command-line flags in a user interface.

Persistence of Application Settings


The TestStand Engine stores Station Options dialog box settings and other
settings that apply to all TestStand applications. However, each user
interface also stores additional custom settings. These settings include
items such as whether to break on the first step of execution, whether to
break when a step fails, and the list of most recently used sequence files.
The Application Manager control stores these settings in the configuration
file specified by the ApplicationMgr.ConfigFilePath property.

National Instruments Corporation

9-29

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

The following list of Application Manager control properties persist to the


configuration file:

BreakOnFirstStep

PromptForOverwrite

EditReadOnlyFiles

MakeStepNamesUnique

SaveOnClose

When you set the value of one of these properties on the Application
Manager control in a designer, you are setting the default value for the
property. The Application Manager control stores the default value in the
configuration file it creates if a configuration file does not already exist. If
the configuration file already exists, the Application Manager control loads
the values of these properties from the file.

Configuration File Location


The default value of the ApplicationMgr.ConfigFilePath property is
%UserProfile%\Local Settings\Application Data\National
Instruments\TestStand %TSVer%\UserInterface.xml. This path

specifies a directory to which the Windows user who is currently logged in


has permission to write files. To change the configuration file location,
set the ApplicationMgr.ConfigFilePath property before your
application calls ApplicationMgr.Start.
If you specify a relative file path or just a file name, the file location is
relative to the directory that contains your application. If other users who
do not have Windows administrator privileges can run your application,
you must ensure that your configuration file is stored in a location to which
your users have permission to write files.

Adding Custom Application Settings


After your application calls the ApplicationMgr.Start method, complete the
following steps to add your own setting to persist in the configuration file:

NI TestStand Reference Manual

1.

Access the ApplicationMgr.ConfigFile property to obtain the


PropertyObjectFile that holds the contents of the configuration file.

2.

Access the Data property of this property object file to obtain the
PropertyObject that holds the application settings.

9-30

ni.com

Chapter 9

3.

Creating Custom User Interfaces

Ensure your custom setting exists in this PropertyObject by setting a


default value.
To set the default value of your setting, call a method such as
PropertyObject.SetValBoolean with a lookup string such as
"CustomSettings.MyExampleBooleanSetting" and an options
parameter of PropOption_SetOnlyIfDoesNotExist.

4.

Call a method such as PropertyObject.SetValBoolean with an


options parameter of PropOption_NoOptions to set your custom
option in response to user input.

5.

Call a method such as PropertyObject.GetValBoolean to obtain


the current value of your custom option.

When you call ApplicationMgr.ShutDown or change any Application


Manager control setting, the Application Manager control persists the
application settings to the configuration file. You can also persist the
settings at any time by calling PropertyObjectFile.WriteFile.

Using the TestStand API with TestStand UI Controls


The TestStand UI Controls greatly reduce the need for an application to
directly call the TestStand API. However, you can still call the TestStand
API directly on objects you create or obtain from the TestStand UI Controls
methods, properties, or events. Note the following guidelines when you call
the TestStand API in a user interface that uses the TestStand UI Controls:

You do not need to create the TestStand Engine. Instead, you can
obtain the Engine object using the ApplicationMgr.GetEngine
method.

If you create an execution by calling Engine.NewExecution, the


TestStand UI Controls recognize the new execution.

If you load a sequence file by calling Engine.GetSequenceFileEx,


the TestStand UI Controls are not aware of the file you load. To open
and display a file in the user interface, you must call
ApplicationMgr.OpenSequenceFile.

You can obtain sequence file and execution references from events or
from the SequenceFiles and Executions collections.

If you hold references to TestStand objects, release them in the handler


for the ApplicationMgr.QueryShutdown event if your event
handler does not cancel the shut down process.

National Instruments Corporation

9-31

NI TestStand Reference Manual

Chapter 9

Creating Custom User Interfaces

Documenting Custom User Interfaces


TestStand installs the Using the TestStand User Interfaces
manual, located in the <TestStand>\Doc directory, that you can use as a
starting point for creating a custom manual for user interface applications
that you customize based on the TestStand full-featured user interface
examples.
In addition, the menus for the TestStand full-featured user interface
examples include CommandKind_DefaultHelpMenu_Set, which contains
a set of commands that corresponds to the typical items in the Help menu
of a TestStand application, including support for displaying help for the
currently active TestStand UI control, the <F1> key.

NI TestStand Reference Manual

9-32

ni.com

Customizing Process Models


and Callbacks

10

This chapter describes how to customize the TestStand process models and
callbacks. For detailed information about the TestStand process models,
refer to Appendix A, Process Model Architecture.

Process Models
All process models that TestStand provides identify UUTs, generate test
reports, log results to databases, and display UUT status. These process
models also allow client sequence files to customize various model
operations by overriding model-defined callback sequences.
Process models provide Configuration and Execution entry points that you
use to configure model settings and to run client files under the model.
These entry points are sequences in the process model sequence file and are
typically listed in the Configure and Execute menus of an application.
The models that TestStand providesSequential, Parallel, and
Batchcontain the following Execution entry points:

Test UUTsTests and identifies multiple UUTs or UUT batches


in a loop.

Single PassTests one UUT or a single batch of UUTs without


identifying them.

The TestStand process models also contain the following Configuration


entry points:

Report OptionsLaunches the Report Options dialog box, in which


you can enable UUT report generation and configure the report type
and contents of the report files.

Database OptionsLaunches the Database Options dialog box, in


which you can enable UUT result logging to database and configure
the schema for mapping TestStand results to database tables and
columns.

National Instruments Corporation

10-1

NI TestStand Reference Manual

Chapter 10

Customizing Process Models and Callbacks

Model OptionsLaunches the Model Options dialog box, in which


you can configure the number of test sockets and other options related
to process models.

Station Model
You can specify a process model file to use for all sequence files. This
process model file is called the station model file. The Sequential model is
the default station model file. You can use the Station Options dialog box
to select a different station model or to allow individual sequence files to
specify their own process model file.
Refer to the NI TestStand Help for more information about the Station
Options dialog box.

Specifying a Specific Process Model for a Sequence File


If TestStand is configured to allow individual sequence files to specify their
own process model files, you can set the process model file of a sequence
file in the Sequence File Properties dialog box. You can also specify that a
sequence file does not use a process model.
Refer to the NI TestStand Help for more information about the Sequence
File Properties dialog box.

Modifying the Process Model


To make changes to the process model that apply wherever the process
model is used, you must modify the process model directly.
TestStand installs the process model sequence
filesSequentialModel.seq, ParallelModel.seq, and
BatchModel.seqand their supporting files in the <TestStand>\
Components\NI\Models\TestStandModels directory.
If you want to change or enhance the process model files, copy the
entire contents of the <TestStand>\Components\NI\Models\
TestStandModels directory to <TestStand>\Components\User\
Models and make changes to this copy. This practice ensures that newer
installations of the same version of TestStand do not overwrite your
customizations, or that uninstalling TestStand does not remove the files
you customize.

NI TestStand Reference Manual

10-2

ni.com

Chapter 10

Customizing Process Models and Callbacks

Remember that process models are TestStand sequence files. To modify the behavior
of process models, edit them for desired functionality as you would any other sequence
files. For example, if you want to change the HTML report output for all sequences, copy
reportgen_html.seq from the NI directory to the User directory and then make
changes to that copy.
Tip

Process Model Callbacks


Model callbacks allow you to customize the behavior of a process model
for each client sequence file that uses it. By defining one or more Model
callbacks in a process model, you can specify the process model operations
that you can customize from your client sequence file.
Define a Model callback by adding a sequence to the process model file,
marking it as a callback in the Sequence Properties dialog box, and then
calling it from the process model. You can override the callback in the
model sequence file by using the Sequence File Callbacks dialog box
to create a sequence of the same name in the client sequence file.
For example, the default TestStand process model defines a TestReport
callback that generates the test report for each UUT. Normally, the
TestReport callback in the default process model file is sufficient because
it handles many types of test results. You can, however, override the default
TestReport callback by defining a different TestReport callback in a
particular client sequence file using the Sequence File Callbacks
dialog box.
Refer to the NI TestStand Help for more information about the Sequence
File Callbacks dialog box.

Special Editing Capabilities for Process Model


Sequence Files
The TestStand Sequence Editor has specific features for creating or
modifying process model sequence files.
If you want TestStand to treat a sequence file as a process model, you must
mark it as a process model file. To do so, select EditSequence File
Properties. In the Sequence File Properties dialog box, select the
Advanced tab, and then select Model from the Type ring control.

National Instruments Corporation

10-3

NI TestStand Reference Manual

Chapter 10

Customizing Process Models and Callbacks

Figure 10-1 shows the settings on the Advanced tab on the Sequence File
Properties dialog box.

Figure 10-1. Sequence File Type Setting on the Advanced Tab


on the Sequence File Properties Dialog Box

Although you edit a process model sequence file in a regular Sequence File
window, the file has special contents. In particular, some of the sequences
in process model files are Model entry points, and some are Model
callbacks. TestStand maintains special properties for entry point and
callback sequences. You can specify the values of these properties when
you edit the sequences in a process model file. When you access the
Sequence Properties dialog box for any sequence in a model file, it contains
a Model tab that allows you to specify whether the sequence is a normal
sequence, callback sequence, or an entry point sequence.

Normal Sequences
A normal sequence is any sequence other than a callback or entry point. In
a process model file, you use normal sequences as Utility subsequences that
the entry points or callbacks call. When you select Normal from the Type
ring control, nothing else is listed on the Model tab.

NI TestStand Reference Manual

10-4

ni.com

Chapter 10

Customizing Process Models and Callbacks

Callback Sequences
Model callbacks are sequences that entry point sequences call and that the
client sequence file can override. By marking sequences as callbacks in a
process model file, you specify the set of process model operations that you
can customize. When editing the client file, select EditSequence File
Callbacks to override the callback. Refer to the NI TestStand Help for
more information about using the Sequence File Callbacks dialog box.
Some Model callbacks, such as the TestReport callback in the default
process model, have implementations sufficient for handling most types of
test results. Other Model callbacks act as placeholders that you can override
with sequences in the client sequence file. For example, the MainSequence
callback in the model file is a placeholder for the MainSequence callback
in the client sequence file.

Entry Point Sequences


Entry point sequences are sequences that you can invoke from the menus
in the TestStand Sequence Editor or user interfaces. You can specify two
different types of entry points: Execution entry points and Configuration
entry points.

Execution entry pointRuns test programs. Execution entry points


typically call the MainSequence callback in the client sequence file.
The default process model contains two Execution entry points: Test
UUTs and Single Pass. By default, Execution entry points are listed
in the Execute menu. Execution entry points are only listed in the
menu when the active window contains a sequence file that has a
MainSequence callback.

Configuration entry pointConfigures a feature of the process


model. Configuration entry points usually save the configuration
information in a .ini file in the <TestStand>\Cfg directory. By
default, Configuration entry points are listed in the Configure menu.
The default process model contains the Configuration entry point,
Configure Report Options. The Configure Report Options entry point
is listed as Report Options in the Configure menu.

National Instruments Corporation

10-5

NI TestStand Reference Manual

Chapter 10

Customizing Process Models and Callbacks

Callbacks
In addition to the Model callbacks, TestStand includes many other callback
sequences that you can customize to meet your specific needs. These
callbacks are divided into two groupsEngine callbacks and Front-End
callbacks.

Engine Callbacks
The TestStand Engine defines a set of Engine callbacks that it invokes at
specific points during execution.
Engine callbacks allow you to configure TestStand to call certain sequences
at various points during your test, including before and after the execution
of individual steps, before and after interactive executions, after loading a
sequence file, or before unloading a sequence file. TestStand defines the set
of Engine callbacks and their names because the TestStand Engine controls
the execution of steps and the loading and unloading of sequence files.
The Engine callbacks are categorized according to the file in which the
callback sequence appears. You can define Engine callbacks in sequence
files, process model files, and the StationCallbacks.seq file.
TestStand invokes Engine callbacks in a normal sequence file only when
executing steps in the sequence file or loading/unloading the sequence file.
TestStand invokes Engine callbacks in process model files when executing
steps in the model file, steps in sequences that the model calls, and steps in
any nested calls to subsequences. TestStand invokes Engine callbacks in the
StationCallbacks.seq file whenever TestStand executes steps on the
test station.
Note TestStand does not predefine any Station Engine callbacks in the
StationCallbacks.seq file in the <TestStand>\Components\NI\Callbacks\
Station directory, but may in a future version of TestStand. Add your own Station Engine
callbacks in the StationCallbacks.seq file in the <TestStand>\Components\
User\Callbacks\Station directory.

Table 10-1 lists the engine callbacks that TestStand defines, indicates
where you must create the callback sequence, and specifies when the
engine calls the callback.

NI TestStand Reference Manual

10-6

ni.com

Chapter 10

Customizing Process Models and Callbacks

Table 10-1. Engine Callbacks

Engine Callback

Where You Define


the Callback

When the Engine


Calls the Callback

SequenceFilePreStep

Any sequence file

Before the engine executes


each step in the sequence
file.

SequenceFilePostStep

Any sequence file

After the engine executes


each step in the sequence
file.

SequenceFilePreInteractive

Any sequence file

Before the engine begins an


interactive execution of
steps in the sequence file.

SequenceFilePostInteractive

Any sequence file

After the engine completes


an interactive execution of
steps in the sequence file.

SequenceFileLoad

Any sequence file

When the engine loads the


sequence file into memory.

SequenceFileUnload

Any sequence file

When the engine unloads


the sequence file from
memory.

SequenceFilePostResultList
Entry

Any sequence file

After the engine fills out


the step result for a step in
the sequence file.

SequenceFilePostStepRuntimeError

Any sequence file

After a step in the sequence


file generates a run-time
error.

SequenceFilePostStepFailure

Any sequence file

After a step in the sequence


fails.

ProcessModelPreStep

Process model file

Before the engine executes


each step in any client
sequence file that the
process model calls and
each step in any resulting
subsequence calls.

National Instruments Corporation

10-7

NI TestStand Reference Manual

Chapter 10

Customizing Process Models and Callbacks

Table 10-1. Engine Callbacks (Continued)

Engine Callback

Where You Define


the Callback

When the Engine


Calls the Callback

ProcessModelPostStep

Process model file

After the engine executes


each step in any client
sequence file that the
process model calls and
each step in any resulting
subsequence calls.

ProcessModelPreInteractive

Process model file

Before the engine begins


interactive execution of
steps in a client sequence
file.

ProcessModelPostInteractive

Process model file

After the engine begins


interactive execution of
steps in a client sequence
file.

ProcessModelPostResultList
Entry

Process model file

After the engine fills out


the step result for a step in
any client sequence file that
the process model calls
or in any resulting
subsequence calls.

ProcessModelPostStepRuntimeError

Process model file

After a step generates a


run-time error when the
step is in a client sequence
file that the process model
calls or in any resulting
subsequence calls.

ProcessModelPostStepFailure

Process model file

After a step fails when the


step is in a client sequence
file that the process model
calls or in any resulting
subsequence calls.

StationPreStep

StationCallbacks.seq

Before the engine executes


each step in any sequence
file.

NI TestStand Reference Manual

10-8

ni.com

Chapter 10

Customizing Process Models and Callbacks

Table 10-1. Engine Callbacks (Continued)

Engine Callback

Where You Define


the Callback

When the Engine


Calls the Callback

StationPostStep

StationCallbacks.seq

After the engine executes


each step in any sequence
file.

StationPreInteractive

StationCallbacks.seq

Before the engine begins


any interactive execution.

StationPostInteractive

StationCallbacks.seq

After the engine completes


any interactive execution.

StationPostResultListEntry

StationCallbacks.seq

After the engine fills out


the step result for a step in
any sequence file.

StationPostStepRuntimeError

StationCallbacks.seq

After any step generates a


run-time error.

StationPostStepFailure

StationCallbacks.seq

After any step fails.

The following are examples of how you can use Engine callbacks:

Use the SequenceFileLoad callback to ensure that the configuration for


external resources that the sequence file uses occurs only once prior to
executing. Usually, you initialize the devices that a sequence requires
by creating steps in the Setup step group for the sequence. However, if
you call the sequence repeatedly, you can move the Setup steps into a
SequenceFileLoad callback for the subsequence file so that they run
only when the sequence file loads.

Use the StationPreStep and StationPostStep callbacks to accumulate


statistics on all steps that execute on the test station. You can inspect
the name and types of steps that accumulate data on specific steps.

Note If you define a SequenceFilePreStep, SequenceFilePostStep,

SequenceFilePreInteractive, or SequenceFilePostInteractive callback in a model file,


the callback applies only to the steps in the model file.
Note Do not define a SequenceFileLoad or SequenceFileUnload callback in the
StationCallbacks.seq sequence file. TestStand does not call these callbacks.

National Instruments Corporation

10-9

NI TestStand Reference Manual

Chapter 10

Customizing Process Models and Callbacks

Note If a callback sequence is empty, TestStand does not invoke the Engine callback.

Also, the process model uses the Execution.EnableCallback method to disable the
ProcessModelPostResultListEntry and SequenceFilePostResultListEntry callbacks when
the model does not need to process results on-the-fly to generate a report or log to a
database.
Note TestStand only calls other Engine callbacks when executing the SequenceFileLoad

and SequenceFileUnload Engine callbacks. TestStand does not call Engine callbacks when
executing the other Engine callbacks.

Front-End Callbacks
Front-End callbacks are sequences in the FrontEndCallbacks.seq file
that are called by user interface applications. Front-End callbacks allow
multiple user interfaces to share the same implementation for a specific
operation. The version of FrontEndCallback.seq that TestStand
installs contains one Front-End callback sequence, LoginLogout. The
sequence editor and all user interfaces included with TestStand call
LoginLogout.
When you implement operations as Front-End callbacks, you write them
as sequences. This allows you to modify a Front-End callback without
modifying the source code for the user interfaces or rebuilding the
executables for them. For example, to change how the various user
interfaces perform the login procedure, you only have to modify the
LoginLogout sequence in FrontEndCallbacks.seq.
You can create new Front-End callbacks by adding a sequence to the
FrontEndCallbacks.seq file. You can then invoke this sequence from

each of your user interface applications using functions in the TestStand


API. However, you cannot edit the source for the TestStand Sequence
Editor and therefore cannot make the sequence editor call new Front-End
callbacks that you create.
Note TestStand installs predefined Front-End callbacks in the
FrontEndCallbacks.seq file in the <TestStand>\Components\NI\Callbacks\
FrontEnd directory. You can add your own Front-End callbacks or override a predefined
callback in the FrontEndCallbacks.seq file in the <TestStand>\Components\
User\Callbacks\FrontEnd directory.

NI TestStand Reference Manual

10-10

ni.com

11

Type Concepts

This chapter discusses concepts that apply to step types, custom data types,
and standard data types in TestStand. This chapter also describes the Types
window, in which you can create, modify, or examine data types and step
types.
For an overview of the categories of types, refer to the Step Types and
Standard and Custom Data Types sections of Chapter 1, TestStand
Architecture, of this manual.

Storing Types in Files and Memory


For each type that a TestStand file uses, TestStand stores the definition
of the type in the file. You can also specify that a file always saves the
definition for a type, even if it does not currently use the type. Because
many files can use the same type, many files can contain definitions for
the same type. All your sequence files, for example, might contain the
definitions for the Pass/Fail Test step type and the Error standard data type.
TestStand allows only one definition for each uniquely named type in
memory. Although the type can appear in multiple files, only one
underlying definition of the type exists in memory. If you modify the type
in one file, it updates in all files. Refer to the Types Window section of this
chapter for more information about viewing the types in memory and the
files that reference them.

Modifying Types
TestStand allows you to modify the built-in and custom properties of step
types and the custom data types that you create; however, you cannot
modify the built-in step types and the standard data types that TestStand
installs unless you create a new copy of the type and modify the copy.
When you modify a type, TestStand enables the Modified built-in property
for the type. TestStand cannot automatically resolve type conflicts unless
the Modified property is disabled. To disable the Modified property, you
typically increment the version of the type on the Step Type Properties

National Instruments Corporation

11-1

NI TestStand Reference Manual

Chapter 11

Type Concepts

dialog box or the Type Properties dialog box when you have completed all
the modification to the type.

Type Versioning
When you edit a type, you can increment the version number for the type.
TestStand uses the version number to determine whether to load a type
from a file when the type is already in memory and which version of a type
to use when the version numbers are different.
You can also set the earliest TestStand version that can use a type. This
prevents a TestStand Engine from using this type if the version of the
engine is less than the version specified. If you enable this option and an
older version of the engine attempts to load this type, the type is ignored,
and TestStand only continues to load the file if an older version of this type
is already loaded in memory.

Resolving Type Conflicts


If you load a file that contains a type definition and another type definition
of the same name already exists in memory, TestStand verifies that the
two type definitions are identical. When TestStand compares two types
with the same name, TestStand also compares all the built-in and custom
subproperties in the types.
If they are not identical, TestStand attempts to resolve this conflict.
TestStand automatically selects the type with the greater version number if
the modified property for both types is disabled and each type definition
does not require a prompt to resolve the type conflict.
If TestStand cannot automatically determine which of the two types to use,
or if an execution is running and the type that TestStand wants to use is
located in the file being loaded, TestStand informs you of the conflict
through the Type Conflict in File dialog box, which allows you to resolve
the conflict. Refer to the NI TestStand Help for more information about the
Types Window and the Type Conflict In File dialog box.
Note Type conflicts can occur if you save a current TestStand sequence file as a earlier

version of TestStand sequence file and the sequence file contains custom step types and
data types that also existed in the earlier version of TestStand. Newer versions of TestStand
can add new subproperties and alter some flags in types. When you open files saved from
a newer version of TestStand and a type conflict occurs, select to use the current TestStand
versions of the types instead of the types from the file. To prevent the altered version of a
type in TestStand from being used in or accidentally propagated to earlier TestStand

NI TestStand Reference Manual

11-2

ni.com

Chapter 11

Type Concepts

sequence files, enable the Set Earliest TestStand Version that can Use this Type setting
on the Step Type Properties dialog box and set the earliest version to the current version of
TestStand.
In addition, when TestStand saves a TestStand sequence file as an earlier version of a
TestStand sequence file, the TestStand Engine uses types from any of the type palette files
located in the <TestStand>\Components\NI\Compatibility\<Version> and
<TestStand>\Components\User\Compatibility\<Version> directories. You can
place your type palette files from earlier versions of TestStand in a <TestStand>\
Components\User\Compatibility\<Version> directory to ensure that the correct
version of your types are saved with the sequence file.

Types Window
Use the Types window in the sequence editor to view and edit the step
types, custom data types, and standards data types.
The Types window contains two panes, The View Types For pane and the
Types pane. The View Types For pane contains three file sections: Type
Palettes, Sequence Files, and Other. The Types pane displays the types
associated with the selected item in the View Types For pane. When you
select a file, the Types pane lists the step types, custom data types, and the
standard data types used by or attached to the selected file. You can also
display types for all loaded files when you select All Types in the Other
section.
When you select FileSave in the Types window, TestStand saves the
selected file in the Types pane.
Refer to the NI TestStand Help for more information about the Types
window.

Sequence Files
Sequence files contain step types, custom data types, and standard data
types that the variables and steps in the file use. When you save the contents
of the Sequence File window, TestStand writes the definitions of the types
used in the sequence file to the sequence file.
When you create a new type in the Types pane for a sequence file, the type
does not appear in the Insert Local, Insert Global, Insert Parameter, Insert
Field, and Insert Step submenus in other Sequence File windows. Refer to
the NI TestStand Help for more information about the Sequence File
window.

National Instruments Corporation

11-3

NI TestStand Reference Manual

Chapter 11

Type Concepts

To use a type in other sequence files, you can manually copy or drag the
new type from one sequence file to another. National Instruments strongly
recommends that you copy or drag the new type to a type palette file so that
each type in a type palette file appears in the appropriate Insert submenu for
all windows.

Station Globals
Station globals contain custom data types and standard data types that the
station global variables use. When you save the contents of the Station
Globals window, TestStand writes the definitions of the types used in
station global variables to the StationGlobals.ini file in the
<TestStand>\Cfg directory. Refer to the NI TestStand Help for
more information about the Station Globals window.

User Manager
All users and user profiles use the User standard data type. To add
new privileges for all users and groups, add the privileges to the
NI_UserCustomPrivileges type. Refer to Chapter 7, User Management,
for more information about using the TestStand User Manager.
When you save the contents of the User Manager window, TestStand writes
the definitions of the types used to define users to the Users.ini file in
the <TestStand>\Cfg directory. Refer to the NI TestStand Help for more
information about the User Manager window.

Type Palette Files


Type palette files contain step types, custom data types, and standard data
types that you want to have available in the sequence editor at all times. By
dragging a type into a type palette file in the Types window, you ensure that
the type is always available even when it is not used by the user manager,
station globals, or any of the open sequence files. Typically, type palette
files reside in the <TestStand>\Components\NI\TypePalettes
directory.
Typically, you create new types in the MyTypes.ini type palette file in the
<TestStand>\Components\User\TypePalettes directory or in a
new type palette file that you create. Refer to the NI TestStand Help for
more information about the Types window.
You can distribute step types and the data types you create to other
machines by installing your type palette file to the <TestStand>\
Components\User\TypePalettes directory. You must prefix the file

NI TestStand Reference Manual

11-4

ni.com

Chapter 11

Type Concepts

names of the type palettes you install with Install_. At startup, TestStand
searches the TypePalettes directory for type palette files with the
Install_ prefix. When TestStand finds a type palette file to install whose
base file name is not the same as any existing type palette, TestStand
removes the Install_ prefix and adds the type palette to the type palette
list. When TestStand finds a type palette file to install whose base file name
is the same as an existing type palette, TestStand merges the types from the
install file into the existing type palette file and then deletes the install file.

National Instruments Corporation

11-5

NI TestStand Reference Manual

12

Standard and Custom Data


Types

This chapter describes how to use data types in TestStand and how to create
and modify custom data types to meet the needs of your application.

Using Data Types


You use data types when you insert variables, parameters, or step
properties. Each window or pane in which you can insert a variable,
parameter, or property features a context menu that contains an Insert item.
You can use the context menu items in the Types pane or windows that are
listed in Table 12-1.
Table 12-1. Creating Data Type Instances from Context Menus

Context
Menu Item

Location of Context Menu

Item Inserted

Insert File Global

File Globals section of the Variables


pane in the Sequence File window

Sequence file global variable

Insert Parameter

Parameters section of the Variables


pane in the Sequence File window

Sequence parameter

Insert Local

Locals section of the Variables pane in


the Sequence File window

Sequence local variable

Insert Station
Global

Station Globals window

Station global variable

Insert User
Insert Group

User Manager window

New object with the User data


type

Insert Field

Types window

New element in an existing


data type

National Instruments Corporation

12-1

NI TestStand Reference Manual

Chapter 12

Standard and Custom Data Types

With the exception of the Insert User and Insert Group items, all of the
context menu items in Table 12-1 provide a submenu from which you can
select a data type. The submenu includes the following categories of types:

One of the simple data types that TestStand defines, including the
number, Boolean, string, and object reference data types.

A named data type. This submenu includes all of the custom named
data types that are currently in type palette files or in the files you
are currently editing. The submenu also includes standard named
data types that come with TestStand, such as Error, Path, and
CommonResults. Refer to the Using Standard Named Data Types
section of this chapter for more information about the standard named
data types.

An array of elements that all have the same data type.

In the submenu for Insert Parameter, you can select the Container type.
Creating a parameter with the Container type is only useful if you want to
pass an object of any type to the sequence. To do so, you must also turn off
type checking for the parameter.
To create a parameter with a complex data type, you should create the data
type in the Types window. Then select the data type from the Types
submenu in the Insert Parameter submenu.
If the submenu does not contain the data type you require, you must create
the data type in the Types window. If the data type already exists in another
window or pane, drag or copy the data type you are editing from one file to
the other or to a type palette file.

Specifying Array Sizes


When you select an item from the Array of submenu in an Insert submenu,
the Array Bounds dialog box launches. Figure 12-1 shows the Array
Bounds dialog box with settings for a three-dimensional array.

NI TestStand Reference Manual

12-2

ni.com

Chapter 12

Standard and Custom Data Types

Figure 12-1. Array Bounds Dialog Box

The first and outermost dimension has five elements, with 0 as the
minimum index and 4 as the maximum index. The second dimension has
10 elements, with 1 as the minimum index and 10 as the maximum index.
The third and innermost dimension has three elements, with 1 as the
minimum index and 1 as the maximum index.
After you create a variable, parameter, or property as an array, you can
modify the array bounds by clicking the resize array button for the variable,
parameter, or property in the list view. Select the Bounds tab that is visible
in the Properties dialog box to modify the array bounds.

Empty Arrays
If you want the array to be empty when you start the execution, enable the
Empty option. When you enable this option, the Upper Bounds control for
each dimension dims. Defining an array as initially empty is useful if you
do not know the maximum array size the sequence requires during
execution or if you want to save memory during the periods of execution
when the sequence does not use the array.

Display of Data Types


The data type of each variable or property you create is listed in the Type
column of the Variables pane. If the data type is an array, the words Array
of appear in the Type column, followed by the data type of the array
elements and the range of each dimension. If the data type is a named data
type, the data type name is listed in the Type column, followed by the
underlying type.

National Instruments Corporation

12-3

NI TestStand Reference Manual

Chapter 12

Standard and Custom Data Types

Figure 12-2 shows variables with different data types on the Variables pane
in the Sequence File window. Table 12-2 describes the data type of each
variable in Figure 12-2.

Figure 12-2. Variables with Various Data Types


Table 12-2. Data Types of the Variables

Local Variable

Data Type

Description

Count

Number

Predefined by TestStand.

Name

String

Predefined by TestStand.

IsOk

Boolean

Predefined by TestStand.

MaxVolts

Volts

Custom data type.

DeviceEnabled

Boolean

One-dimensional array of Booleans, with


indexes from 1 to 8.

Impedances

ImpedanceTable

Custom data type that represents a


two-dimensional array of numbers.

FixtureA

Fixture

Represents a container that contains multiple


fields with different data types.

NI TestStand Reference Manual

12-4

ni.com

Chapter 12

Standard and Custom Data Types

Table 12-2. Data Types of the Variables (Continued)

Local Variable

Data Type

Description

ParamsList

TestParamList

Represents a one-dimensional array of elements


with the TestParamList data type. The
TestParamList data type represents a container
that contains multiple fields with different data
types.

TestClass

ObjectReference

Predefined by TestStand.

Modifying Data Types and Values


With the exception of resizing arrays, you cannot change the internal
structure of a variable, parameter, or property after you create it from a data
type. You cannot change its data type setting, nor can you deviate from the
data type. You can, however, change the contents of the data type itself.
Changing the contents of a data type affects all variables, parameters, and
properties that use the data type.
You can modify the value of a variable, parameter, or property in the view
or pane in which you create it. For variables and properties, this value is the
initial value when you start execution or call the sequence. For parameters,
this value is the default value if you do not pass an argument value
explicitly. If the data type is a single-valued data type, such as number
or Boolean, the value appears in the Value column of the list view.
You can also rearrange variables, parameters, and properties in the
Variables pane using drag and drop or cut, copy, and paste. The order of the
variables and properties does not matter; however, the order of parameters
for sequences does affect how you configure a Sequence Call step that
invokes the sequence.

Single Values
You can modify the value of a single-valued data type by selecting
Properties from the context menu for the variable, parameter, or property
in the list view. This launches the Type Properties dialog box. Refer to
the NI TestStand Help for more information about using the Type
Properties dialog box.

Object References
Object reference properties can contain references to .NET or
ActiveX/COM objects. They are primarily used by the .NET Adapter and

National Instruments Corporation

12-5

NI TestStand Reference Manual

Chapter 12

Standard and Custom Data Types

the ActiveX/COM Adapter. If the variable, parameter, or property is an


object reference, you can use the Release Object button in the Value
column of the Variables pane to release the reference.
You can only set the reference value from within an expression, a code
module using the TestStand API, or by calling the TestStand API directly
using the ActiveX/COM Adapter. TestStand stores ActiveX references as
an IDispatch pointer or IUnknown pointer.
The value you assign to the object reference must be a valid object pointer.
Whenever you assign a non-zero value to an object reference, TestStand
adds a reference to the object for as long as the variable, parameter, or
property contains that value. To release the reference to the object, assign
the variable, parameter, or property a new value or the constant Nothing.
In addition, TestStand automatically releases the reference to the object
when the variable, parameter, or property loses its scope. For example, if a
sequence local variable contains a reference to an object, TestStand releases
the reference when the call to the sequence completes. When you release
all references to a .NET object, the object is marked for garbage collection.
When you release all references to an ActiveX/COM object, the object is
destroyed.
If you have two references, an equality comparison performs a comparison
of the objects IUnknown pointers for ActiveX and the pointer values
for .NET.
Do not release an object variable by assigning it a value of 0. Instead, assign the
constant Nothing to the variable.

Tip

Arrays
If the variable, parameter, or property is an array that contains values, you
access the elements of the array in the pane by clicking the Resize Array
button. You can use the Value column in the Variables pane to modify the
initial value for each element.

Dynamic Array Sizing


TestStand allows you to resize an array during execution. In an expression,
you can use the GetNumElements and SetNumElements expression
functions to obtain and modify the upper and lower bounds for a
one-dimensional array. For multi-dimensional arrays or to change the
number of dimensions in the array, you must use the GetArrayBounds and
SetArrayBounds expression functions. You can find the documentation for
these functions on the Operators/Functions tab on the Expression Browser

NI TestStand Reference Manual

12-6

ni.com

Chapter 12

Standard and Custom Data Types

dialog box. Refer to the NI TestStand Help for more information about the
Expression Browser dialog box.
In a code module, use the GetDimensions and SetDimensions methods of
the PropertyObject class to obtain or set the upper and lower bounds of an
array or to change the number of dimensions. Refer to the NI TestStand
Help for more information about the GetDimensions and SetDimensions
methods.

Using Standard Named Data Types


TestStand defines standard named data types, such as Path, Error, and
CommonResults. You typically cannot modify standard data types, with
the exception of the CommonResults and NI_UserCustomPrivileges types.
For example, with the CommonResults standard data type, you can add
subproperties to the standard data types, but you cannot delete any of its
built-in subproperties.
The following sections describe some of the more generally applicable
standard data types.

Path
Use the Path standard data type to store a pathname as a string, so that
TestStand can locate path values saved in variables and step properties
when processing sequence files for deployment.

Error and CommonResults


TestStand inserts a Results property in every step you create, regardless of
whether you use a built-in step type or a custom step type. The Results
property has at least three subproperties: Error, Status, and
CommonResults.
The Error subproperty uses the Error standard data type. Steps in TestStand
use the Error subproperty to indicate run-time errors. The Error standard
data type is a container that contains three subproperties: Code, Msg, and
Occurred. When a run-time error occurs in a step, the step sets the Occurred
subproperty to True, the Code subproperty to a value that indicates that
source of the error, and the Msg subproperty to a string that describes the
error.
The CommonResults standard data type is an object that is initially empty.
By adding subproperties to it, you can add extra result information to all

National Instruments Corporation

12-7

NI TestStand Reference Manual

Chapter 12

Standard and Custom Data Types

steps in a standard way. If you choose to add more subproperties to


CommonResults, newer versions of TestStand will not overwrite them.
Be aware that if you modify CommonResults without incrementing the
type version number, you may see a type conflict when you open other
sequence files. These conflicts can include FrontEndCallbacks.seq
when you are logging in or out. TestStand will automatically prompt you
to increment the version number when saving changes to any data type or
step type.

Creating and Modifying Custom Data Types


You can create and modify data types in the Types window which contains
two panes: the View Types For pane and the Type pane. The View Types
For pane contains three file sections: Type Palettes, Sequence Files, and
Other. The Type For pane displays the types associated with the selected
item in the View Types For pane. When you select a file, the Types pane
lists the step types, custom data types, and the standard data types used by
or attached to the selected file. Use the Custom Data Types section to
create and modify custom data types. Use the Standard Data Types
section to examine subproperties of the standard data types.
Note The remainder of this section discusses creating and modifying custom data types in

the Types Window. The same information applies to the Standard Data Types section.

Creating a New Custom Data Type


To create a new custom data type, expand the Custom Data Types node in
the tree view so that the existing custom data types appear in the list view.
Right-click below the list view and select Insert Custom Data Type from
the context menu.The submenu gives you a set of data types from which
you can select any of the simple data types that TestStand defines,
including an array of any type, a container, or a custom or standard named
data type.
Selecting an array type from the submenu launches the Array Bounds
dialog box. Use this dialog box to specify the array bounds that TestStand
applies initially to each variable, parameter, or property that you create with
the data type. After you create the variable, parameter, or property, you can
change its array bounds by clicking the Resize Array button in the Name
column of the list view. Refer to the Modifying Data Types and Values
section of this chapter for more information about dynamically setting the
size of an array.

NI TestStand Reference Manual

12-8

ni.com

Chapter 12

Standard and Custom Data Types

If you select the Container type from the submenu, TestStand creates the
data type without any fields.
When you create new data types, begin your types with a unique ID, such as a
company prefix. Using a unique ID helps to prevent name collisions. For example,
NI_InstrumentConfigurationOptions uses NI as a unique ID.
Tip

Customizing Built-In Data Types


You cannot modify NI-installed data types. To create a customized version
of an NI-installed type, copy and rename the type in the sequence editor.

Properties Common to All Data Types


TestStand defines many properties that are common to all data types. These
are called built-in data type properties. To examine and modify the values
of the built-in data type properties, select Properties from the context
menu for a data type. This launches the Data Type Properties dialog box.
The Data Type Properties dialog box contains the following tabs: General,
Bounds, Version, Cluster Passing, C Struct Passing, and .NET Struct
Passing.
The following sections provide an overview of each tab. Refer to the
NI TestStand Help for detailed information about the Data Type Properties
dialog box.

General Tab
Use the General tab to specify an initial value and comment for the
data type.

Property Flags
TestStand includes a set of property flags that you can modify. Access the
Edit Flags dialog box by clicking Advanced in the General tab on the Data
Type Properties dialog box. For more information about the Edit Flags
dialog box, refer to the NI TestStand Help.
For a description of each of the property flag constants in the TestStand
API, refer to the PropertyFlags Constants and the PropertyObjTypeFlags
Constants topics in the NI TestStand Help.

National Instruments Corporation

12-9

NI TestStand Reference Manual

Chapter 12

Standard and Custom Data Types

Bounds Tab
Use the Bounds tab to define the bounds for array data types. This tab is
visible only for array data types.

Version Tab
Use the Version tab to edit the version information for the data type, to
determine if the data type is modified, to specify how TestStand must
resolve data type conflicts, and to specify the earliest version of TestStand
that can use the type when the file is saved as an earlier version.

Cluster Passing Tab


Use the Cluster Passing tab to define how TestStand passes instances of
the data type as a cluster to LabVIEW VIs.

C Struct Passing Tab


Use the C Struct Passing tab to define how TestStand passes instances of
the data type as a structure to functions and methods in C/C++ DLLs.

.NET Struct Passing Tab


Use the .NET Struct Passing tab to define how TestStand passes instances
of the data type as a structure to methods and properties in .NET
assemblies.

Custom Properties of Data Types


You can add any number of fields to a data type or data type subproperty
that you create as a container. To add fields to a container property in a new
or existing data type, expand the root node for the data type or a data type
subproperty in the tree view and right-click to insert a field from the context
menu. For a new data type, the tree view is empty. For an existing data type,
the list view displays the fields currently in the data type. Right-click the
root node of the data type and select Insert Field from the context menu.
The submenu gives you a set of data types from which you can select any
of the simple data types that TestStand defines, including an array of any
type, a container, or a custom or standard named data type.
To cut, copy, paste, or rename fields, use the context menu that becomes
visible when you right-click the field in the tree view.

NI TestStand Reference Manual

12-10

ni.com

13

Creating Custom Step Types

This chapter describes how to create custom step types. For more
information about types, refer to Chapter 11, Type Concepts. For more
information about the built-in step types included in TestStand, refer to
Chapter 4, Built-In Step Types.

Creating and Modifying Custom Step Types


TestStand gives you the flexibility to create a custom step type to fit
the specific needs of your application. You can do this by modifying
an existing TestStand built-in step type or creating a new step type.
If you want to change or enhance a TestStand built-in step type, copy and
rename the built-in step type, copy and rename its supporting modules and
place the files in the User subdirectory, and make the changes to the new
type and its files. This practice ensures that a newer installation of the same
version of TestStand does not overwrite your customizations, or that
uninstalling TestStand does not remove the files you customize. It also
makes it easier for you to distribute your customizations to other users.
To insert a new step type in the Types pane of the Types window, select a
file in the View Types For pane. The Step Types section in the Types pane
shows all the step types in the selected file. Right- click the root node, Step
Types, and select Insert Step Type from the context menu. Use the Copy
and Paste items from the context menu to copy an existing step type.
When you create new step types, begin your type names with a unique ID, such
as a company prefix. Using a unique ID helps prevent name collisions. For example,
NI_PropertyLoader uses NI as a unique ID.
Tip

The Types pane in the Sequence File window only shows the step types that
the steps in the sequence file use. Figure 13-1 shows the Step Types section
of the Types pane in the Types window.

National Instruments Corporation

13-1

NI TestStand Reference Manual

Chapter 13

Creating Custom Step Types

Figure 13-1. Step Types Section of the Types Pane in the Types Window

Creating a New Custom Step Type


Complete the following steps when you initially create new step types in
the Types pane:
1.

Select Properties from the context menu for the step type in the list
view.

2.

Specify the menu item name for a step type on the Menu tab on the
Step Type Properties dialog box.

3.

Specify the default name for new steps you create from your type and
the description expression for those steps in the General tab on the
Step Type Properties dialog box.

4.

Specify the menu item name (and button name) that invoke the editing
dialog box you (optionally) define for your step type in the Edit Step
section of the Substeps tab on the Step Type Properties dialog box.

Customizing Built-In Step Types


Source code is available for the code modules that the built-in step
types use as substeps. The source code project files are located in the
<TestStand>\Components\NI\StepTypes subdirectory. If you use
these source files as a starting point for step types you create, make your
own copies of these files in the <TestStand>\Components\User\
StepTypes subdirectory and rename them.

NI TestStand Reference Manual

13-2

ni.com

Chapter 13

Creating Custom Step Types

Note You cannot modify NI-installed types. To create a customized version of an

NI-installed type, copy and rename the type in the sequence editor. You must also copy and
rename any supporting modules from the <TestStand>\Components\NI\StepTypes
directory to the <TestStand>\Components\User\StepTypes directory. Make any
changes to the copy to ensure that newer installations of the same version of TestStand do
not overwrite your customizations, or that uninstalling TestStand does not remove the files
you customize.

Properties Common to All Step Types


TestStand defines many properties that are common to all step types.
These are called the built-in step type properties. Some built-in step type
properties only exist in the step type itself. These are called class step type
properties. TestStand uses the class step type properties to define how the
step type works for all step instances. Step instances do not contain their
own copies of the class step type properties.
Other built-in step type properties exist in each step instance. These are
called instance step type properties. Each step you create with the step type
has its own copy of the instance step type properties. TestStand uses the
value you specify for an instance step type property in the step type as the
initial value of the property in each new step you create.
Normally, after you create a step, you can change the values of the steps
instance step type properties. However, when you create a custom step type,
you can prevent users from changing the values of specific instance step
type properties in the steps they create. For example, you can use the Edit
substep of a step type to set the Status Expression for the step. In that case,
you do not want the user to explicitly change the Status Expression value.
TestStand uses this capability in some of the built-in step types, such as the
Numeric Limit Test and String Value Test. To examine and modify the
values of the built-in properties, select Properties from the context menu
for a step type in the list view.
The Default Run Options, Default Post Actions, Default Loop Options,
Default Expressions, Default Switching, and Default Synchronization tabs
display instance properties. These tabs have the same appearance and
behavior as the Run Options, Post Actions, Loop Options, Expressions, and
Synchronization tabs of the Step Properties dialog box for a step instance.
Refer to the NI TestStand Help for more information about these tabs.
Most of the properties in the other tabs are class properties. The following
sections discuss each of these tabs in detail.

National Instruments Corporation

13-3

NI TestStand Reference Manual

Chapter 13

Creating Custom Step Types

General Tab
Use the General tab to specify a name, description, and comment for the
step type.
You can also specify the default module adapter and the default code
module the step type calls; however, a sequence developer can change the
adapter and code module after creating the step using the Properties tab of
the Step Settings pane or the Step Properties dialog box of a user interface.
If you want a step type to specify a call to a code module and you do not
want the sequence developer to change or edit the module call, National
Instruments recommends that you create a Post-Step substep and call your
code module from this substep instead of specifying a default adapter and
code module. Refer to the NI TestStand Help for more information about
the Substeps tab of the Step Type Properties dialog box.

Property Flags
TestStand includes a set of property flags that you can modify. Access the
Edit Flags dialog box by clicking Advanced on the General tab on the Step
Type Properties dialog box and selecting Flags from the menu. Typically,
you only need to configure property flags when you develop a relatively
sophisticated custom step type. For more information about the Edit Flags
dialog box, refer to the NI TestStand Help.
For a description of each of the property flag constants in the TestStand
API, refer to the PropertyFlags and the PropertyObjTypeFlags topics of
the NI TestStand Help.

Block Structure
TestStand allows a step type to specify whether a step of this type affects
the indentation of steps in a sequence. The Flow Control step types
included with TestStand, such as If, ElseIf, and End, use these built-in
properties. Access the Block Structure dialog box by clicking Advanced
on the General tab of the Step Type Properties dialog box and selecting
Block Structure from the menu. For more information about the Block
Structure dialog box, refer to the NI TestStand Help.

Menu Tab
Use the Menu tab to specify the menu item name that appears for the step
type in the Insert Step submenu. The Insert Step submenu appears in the
context menu of individual sequence views in the Sequence File window.

NI TestStand Reference Manual

13-4

ni.com

Chapter 13

Creating Custom Step Types

Use the Step Type Menu Editor to configure the organization of the Insert
Step submenu. Refer to the NI TestStand Help for a description of the Step
Type Menu Editor.

Substeps Tab
Use the Substeps tab to specify substeps for the step type. You use substeps
to define standard actions, other than calling the code module, that
TestStand performs for all instances of the step type. You implement a
substep through a call to a code module. The code module you call from a
substep is called a substep module. The substeps for a step type define the
editing and run-time behavior for all step instances of that type. For each
step that uses the step type, TestStand calls the same substep modules
with the same arguments.
You cannot add or remove substeps or otherwise alter the module call the
substep performs when configuring a particular step instance. Although
you can specify any number of substeps for a step type, the list of substeps
is not a sequence, and substeps do not have preconditions, post actions, or
other execution options. The order in which Pre- and Post-Step substeps
execute is the only execution option you specify. You can specify four
categories of substeps for a step type:

Pre-Step substeps

Post-Step substeps

Edit substeps

Custom substeps

You can specify an adapter and a module to invoke in a substep on the


Substeps tab of the Step Type Properties dialog box for the step type. Click
the Add button and select the type of substep from the menu, then use the
Specify Module button to configure the module call for the new substep.
TestStand calls the Pre-Step substep before calling the code module. For
example, a Pre-Step substep might call a code module that retrieves
measurement configuration parameters and stores those parameters in step
properties for use by the code module.
TestStand calls the Post-Step substep after calling the code module.
A Post-Step substep might call a code module that compares the values
the code module stored in step properties against limit values that the Edit
substep stored in other step properties.
TestStand calls an Edit substep when you select the menu item for the
substep from the Steps pane context menu.The step type specifies the name
National Instruments Corporation

13-5

NI TestStand Reference Manual

Chapter 13

Creating Custom Step Types

of the menu item and the caption of the button. The Edit substep typically
calls a code module that launches a dialog box in which you can edit the
values of the custom step properties. For example, an Edit substep might
display a dialog box in which you specify the high and low limits for a test.
The Edit substep might then store the high and low limit values as step
properties.
Dialog boxes displayed by the specified Edit substep code must be
modal. For example, all dialog boxes except MFC dialog boxes
use the Engine.NotifyStartOfModalDialogEx and
Engine.NotifyEndOfModalDialogEx methods of the TestStand API. Refer
to the modal examples in the <TestStand>\Examples\ModalDialogs
directory.
Typically, TestStand does not call Custom substeps. However, if you add a
Custom substep named OnNewStep to a step type, the TestStand Sequence
Editor and User Interfaces call the substep each time you create a new step
of that type. For example, the If step type uses an OnNewStep substep to
insert an End step. You can use the TestStand API to invoke a Custom
substep from a code module or a user interface.
Source code is available for many of the substep modules that the
built-in step types use. You can find the source code project files in the
<TestStand>\Components\NI\StepTypes directory. If you want to
use existing step type source code as a starting point for your own step type,
copy the files into the <TestStand>\Components\User\StepTypes
directory and use unique filenames to rename the copies.
Note Threads within TestStand executions can be initialized to use either the

single-threaded apartment model or the multi-threaded apartment model. TestStand


executes Edit substeps in threads initialized using the single-threaded apartment model
to allow the substep to open windows that contain ActiveX controls.

Disable Properties Tab


Use the Disable Properties tab to prevent users from modifying the
settings of built-in instance step type properties in individual steps. In this
way, you make the default settings you specify in the Step Type Properties
dialog box non-editable for all step instances.
The Disable Properties tab contains a list of options, in which each option
represents one built-in instance property or a group of built-in instance
properties. When you enable an option, you prevent users from modifying
the value of the corresponding property or group of properties.

NI TestStand Reference Manual

13-6

ni.com

Chapter 13

Creating Custom Step Types

Note Value changes that you make to default built-in step types properties do not change

the values of properties in existing step instances of its type, even when you prevent users
from modifying the properties.

Code Templates Tab


Use the Code Templates tab to associate one or more code templates with
the step type. A code template is a set of source files that contains skeleton
code. The skeleton code serves as a starting point for the development of
code modules for steps that use the step type. TestStand uses the code
template when you click the Create Code button on the Module tab of the
Step Settings pane for a step.
TestStand comes with default code templates that you can use for any
step type. You can customize code templates for individual step types. For
the Numeric Limit Test step type, for instance, you might want to include
example code for accessing the high- and low-limit properties in a step.

Template Files for Different Development Environments


Because different module adapters require different types of code modules,
code templates typically correspond to a particular programming language
in a specific development environment. For example, templates for the
Numeric Limit step type illustrate how a VI or function in a DLL return a
measurement value.
In versions of TestStand prior to TestStand 4.0, code templates that were
designed for use with the LabVIEW and LabWindows/CVI Adapters
contained multiple source files for use in those environments. For
example, a previous default code template included one .c file for the
LabWindows/CVI Adapter and eight VIs for the LabVIEW Adapter, where
the multiple VIs corresponded to the different combinations of parameter
options you can set in the Edit LabVIEW VI Call dialog box. TestStand
refers to these code templates as legacy code templates. They are included
to provide backward compatibility with previous versions of TestStand.
TestStand uses the name of a directory within the <TestStand>\
CodeTemplates\NI or <TestStand>\CodeTemplates\User
directory as the code template name. TestStand stores the source file for
the module adapter in the directory. TestStand also stores a .ini file in
each subdirectory that contains parameter information and a description
string that TestStand displays for the code template. Table 13-1 lists the
subdirectories that contain the default code templates for each development
environment.

National Instruments Corporation

13-7

NI TestStand Reference Manual

Chapter 13

Creating Custom Step Types

Table 13-1. Locations of Default Code Templates

Subdirectory Name

Template Description

Default_Template

Legacy default template

DefaultC++.NET

Default template for C++ in


Visual Studio .NET 2003 or
Visual Studio 2005

DefaultCSharp.NET

Default template for C# in Microsoft


Visual Studio

DefaultCVI

Default template for C in


LabWindows/CVI

DefaultHTB72_Template

Default template for HTBasic 7.2

DefaultHTB80_Template

Default template for HTBasic 8.0

DefaultLabVIEW

Default template for LabVIEW

DefaultVB.NET

Default template for Microsoft Visual


Basic .NET

DefaultVC++_Template

Default template for C++ in Microsoft


Visual Studio

Code templates for the LabVIEW, LabWindows/CVI, and C/C++ DLL


Adapters can have any number of parameters that are compatible with the
data types you can specify on the Module tab for those adapters.
Legacy code templates for the LabVIEW Adapter always specify Test
Data and error out clusters as parameters. The eight different VIs for each
LabVIEW Adapter legacy code template specify various combinations of
the Input Buffer, Invocation Info, and SequenceContext parameters. When
TestStand uses a legacy LabVIEW template VI to create skeleton code, it
chooses the correct VI to use according to the current settings in the
Optional Parameters dialog box.
Legacy code templates for the LabWindows/CVI Adapter always specify
two parameters: a pointer to a tTestData structure and a pointer to a
tTestError structure. When TestStand uses a legacy LabWindows/CVI
template module to create skeleton code, it validates the function prototype
in the template module against this requirement. TestStand reports an error
if the prototype is incorrect.

NI TestStand Reference Manual

13-8

ni.com

Chapter 13

Creating Custom Step Types

When TestStand uses a code template for a DLL to create skeleton


code, it compares the parameter list in the source file to the parameter
information on the Module tab. If these sets of information do not match,
TestStand prompts you to select which prototype to use for the skeleton
code. If you choose to use the prototype from the template source file,
you can also request that TestStand update the Module tab to match the
source file. However, the template source file does not contain sufficient
information for TestStand to update the Value controls for the parameters
on the Module tab.
You can specify entries for TestStand to place in the Value controls, as
described in the NI TestStand Help. TestStand stores this information in
the .ini file in the template subdirectory.

Creating and Customizing Code Template Files


Use the Code Templates tab to create a new code template. TestStand
prompts you to specify a subdirectory name and an existing code template
as a starting point. TestStand copies the files for the existing code template
into the new subdirectory in the <TestStand>\CodeTemplates\User
directory and changes the names. Then, you must modify the code template
files in order to customize them.
You can customize the code template files to include example code that
helps the test developer learn how to access the important custom properties
of the step. For most environments, you can add a value parameter to pass
the information from TestStand. For example, to show how to obtain the
high- and low-limit properties in a LabVIEW or LabWindows/CVI code
template for a Numeric Limit Test step, you may customize the prototype
for the code module by specifying the high and low limits as value
parameters.
As another example, you might want to show how to return a measurement
value from a code module. For the LabVIEW, LabWindows/CVI, and
C/C++ DLL Adapters, you can customize the prototype in the code
template by specifying the measurement as a reference parameter.

Multiple Code Templates per Step Type


You can specify more than one code template for a step type. For example,
you might want to have code templates that contain example code for
conducting the same type of tests with different types of instruments or data
acquisition boards. When a step type has multiple code templates and you
click Create Code on the Module tab, TestStand either prompts you to

National Instruments Corporation

13-9

NI TestStand Reference Manual

Chapter 13

Creating Custom Step Types

choose from a list of templates, or uses the selected template on the Module
tab if it exists.

Version Tab
The Version tab for a Step Type Properties dialog box is identical to the
Version tab you use on the Type Properties dialog box for a custom data
type. Refer to the NI TestStand Help for more information about the
Version tab.

Custom Properties of Step Types


You can define any number of custom properties in a step type so that each
step you create with that step type uses those custom properties.
Open the nodes in the tree view of the Step Types section to display all step
types and their custom properties for the selected file. To display the
custom properties of a step type and its subproperties in the tree view,
expand the node for the step type and the custom property, respectively,
in the tree view.
Figure 13-2 shows the custom properties for the Message Popup step.

Figure 13-2. Custom Properties of a Step Type

NI TestStand Reference Manual

13-10

ni.com

Deploying TestStand Systems

14

This chapter describes the TestStand Deployment Utility and the steps
necessary to successfully deploy a TestStand system from a development
computer to one or more target computers.

TestStand System Components


TestStand systems are composed of a variety of components that work
together to create the entire system. These components can include the
following:

TestStand Engine and its supporting files

LabVIEW and LabWindows/CVI Run-Time Engines

Process models and their supporting files

Step types and their supporting files

Configuration files

User interface applications

Workspace files

Sequence files

Code modules and their supporting files

Hardware drivers

When deploying a TestStand system from a development computer to a


target computer, you must ensure that all of the components that your
system uses are deployed to the target computer. TestStand provides the
TestStand Deployment Utility to assist you with this process.

TestStand Deployment Utility


The TestStand Deployment Utility simplifies the complex process of
deploying a TestStand system by automating many of the steps involved
in deployment, including collecting sequence files, code modules, and
support files for your test system and then creating an installer for
these files.

National Instruments Corporation

14-1

NI TestStand Reference Manual

Chapter 14

Deploying TestStand Systems

Setting Up the TestStand Deployment Utility


Complete the following steps to deploy a TestStand test system using the
TestStand Deployment Utility:
1.

Identify the components to deploy.

2.

Determine whether to create an installer for your system.

3.

Create a system workspace file, if necessary.

4.

Configure and build the deployment.

The following sections discuss each of these steps.

Identifying Components for Deployment


The TestStand Deployment Utility can create installable images, which are
directories of files to be installed to the target computer, of the following
TestStand components:

Components located in the <TestStand>\...\User subdirectories.

A TestStand workspace file and its dependent files, including sequence


files, code modules, and so on.

Additionally, the deployment utility can create an installer that installs


these components with the TestStand Engine, hardware drivers, plus
components in the <TestStand>\...\NI subdirectories.

Determining Whether to Create an Installer


with the TestStand Deployment Utility
If you plan to deploy the TestStand Engine and the TestStand components
located in the <TestStand>\...\NI subdirectories, you must use the
TestStand Deployment Utility to create an installer.
You do not need to use the deployment utility to create an installer if you
plan to deploy your TestStand test system using a third-party installer
development tool, such as Wise or InstallShield, or by using a source code
or revision control system to deploy your system files to target computers.

NI TestStand Reference Manual

14-2

ni.com

Chapter 14

Deploying TestStand Systems

Creating a System Workspace File


Before deploying your sequence files and code modules, you must create a
workspace file that contains all of the sequence files that your test system
could execute. The deployment utility analyzes those sequence files to
determine which files they reference, such as code module files. Also, add
any files that are not stored in a <TestStand>\...\User subdirectory or
files that are not referenced by your sequence files to your workspace file,
such as the support files required by code module DLLs.
If you are using the TestStand Deployment Utility to deploy only the
TestStand Engine or the components located in the <TestStand>\...\
User subdirectories, you do not need to create a workspace file for your test
system.
Refer to Chapter 2, Sequence Files and Workspaces, for more information
about TestStand workspace files.

Configuring and Building the Deployment


Within the sequence editor, select ToolsDeploy TestStand System to
launch the TestStand Deployment Utility. This launches the TestStand
Deployment Utility window, in which you can configure the settings for
deploying your test system, including the components to install and
installer settings.
Refer to the NI TestStand Help for more information about TestStand
Deployment Utility.

Using the TestStand Deployment Utility


This section describes how the TestStand Deployment Utility builds a
deployable test system.

File Collection
When deploying a workspace file, the deployment utility analyzes the
workspace for any dependent files. For example, if your workspace
contains a sequence file, the deployment utility searches the steps in every
sequence of the file to find the referenced code modules. This analysis
continues recursively until all files in the workspace hierarchy are
analyzed.
Because automatically distributing every file used by your sequences could
be problematic, the deployment utility includes a filtering function that

National Instruments Corporation

14-3

NI TestStand Reference Manual

Chapter 14

Deploying TestStand Systems

removes potentially unwanted files. For example, if you have steps in your
sequences that call functions in Windows system DLLs, the deployment
utility will not deploy those DLLs to the target computer.
The Filter.ini file, located in the <TestStand>\Cfg directory, defines
those files that the deployment utility automatically excludes from any
deployment package it creates. By default, the deployment utility does not
deploy any files located in the <TestStand>\Bin or <TestStand>\
...\NI directories. Additionally, it does not deploy any .exe or .dll files
located in the <Windows> or <Windows>\System32 directories.
You may add automatically excluded files to your workspace file, but do
so with caution to prevent incompatibility issues. For example, if your
development computer operates on Windows XP, and you deploy a
Windows system DLL from that computer to a target computer running
Windows 2000, you will likely experience DLL version incompatibility
issues.
Note The TestStand Deployment Utility does not deploy .NET or ActiveX/COM code

modules. You must manually add these code modules and their supporting files to the
system workspace or install them separately on the target computer.

VI Processing
The deployment utility analyzes all of the LabVIEW VIs that it deploys to
determine their complete hierarchies, including all subVIs, DLLs, external
subroutines, run-time menus, LabVIEW Express configurations, and help
files that your VIs may reference. It then packages these VIs and their
hierarchies to ensure that they will execute on systems that do not have
the LabVIEW Development System installed.
Note You must have the LabVIEW Development System installed on your development

computer in order for the TestStand Deployment Utility to perform VI processing.


Note If your VIs call other VIs dynamically using VI Server, you must add those VIs

manually to your system workspace file.


Refer to Appendix A, Calling LabVIEW VIs on Remote Systems, in Using
LabVIEW with TestStand for more information about any restrictions that
exist when deploying LabVIEW 8.0 VIs.

NI TestStand Reference Manual

14-4

ni.com

Chapter 14

Deploying TestStand Systems

Sequence File Processing


The TestStand Deployment Utility also performs processing on sequence
files in order to remove absolute paths. Absolute paths that are functional
on your development computer may be invalid on the target computer,
especially if the base installation directories are different.
For example, if you have installed TestStand to c:\TestStand on
your development system and to c:\Program Files\National
Instruments\TestStand on your target computer, the absolute path
c:\TestStand\test.dll will be valid on your development computer
but invalid on your target computer.
The deployment utility corrects this potential problem by changing
absolute path references in sequence files to relative paths that initiate from
one of the following search directories:

Current sequence file directory

TestStand installation directory

Windows\System32 directory

Windows directory

If the target file is located outside of these directories, TestStand uses a path
that is relative to the installation directory and then adds the installation
directory to the list of default search paths during the installation.

Installing National Instruments Components


The TestStand Deployment Utility allows you to package National
Instruments hardware drivers and other components, such as run-time
engines, in deployment installers. You can configure the additional
components included in the deployment using the Drivers and Components
dialog box.
To launch the Drivers and Components dialog box, click Drivers and
Components on the Installer Options tab of the TestStand Deployment
Utility. Refer to the NI TestStand Help for more information about the
Drivers and Components dialog box.
The Drivers and Components dialog box only lists components that are
installed on your computer and were installed from the NI Device Driver
CD that ships with TestStand or a later version of the driver CD. The
components you select contain only the features currently installed on your
computer and, therefore, may not be complete copies of the original
product(s).

National Instruments Corporation

14-5

NI TestStand Reference Manual

Chapter 14

Deploying TestStand Systems

Guidelines for Successful Deployment


Follow these guidelines to ensure that your deployment process is
successful:

Use unique file namesAlways use unique file names, even if you
are working with a revision of an existing file. Ambiguous file names
can cause the deployment utility to locate incorrect files, which can
result in incorrect behavior.

Note If you are using LabVIEW 8.0 or later, you cannot create deployments that contain

duplicate VIs or subcomponents, such as DLLs. You must ensure that all sequences
included in the deployment image reference the same VI and DLL files.

NI TestStand Reference Manual

Use relative paths and search pathsRelative paths allow TestStand


to find files even if they were installed in a different location on the
target computer than they were on the development computer. For
example, you can locate a file that was saved in c:\Program Files\
National Instruments\<TestStand>\Reports on the
development computer and in c:\TestStand\Reports on the target
computer using the relative path Reports because the TestStand
installation directory is included in the default search path.

Manually add any additional search paths to the list of default


search paths on the target computerYou must manually add
search paths to the list of default search paths. The TestStand
Deployment Utility will not copy additional search paths because the
new directories may not exist on the target computer. Also, ambiguous
file names in these search paths can cause TestStand to locate the
wrong file.

Manually add dynamically referenced files to your


workspaceDynamically referenced files include any sequences
specified by an expression, property loader files specified by
expressions, LabVIEW VIs called using VI Server, and dynamically
loaded DLLs.

Manually add any supporting DLLs required by your code


modules to your workspaceDo not add any DLLs that are part
of TestStand or your operating system.

Redeployed edited filesIf you edit any of your deployed system


files, the deployed system may no longer function, and you must
redeploy the system.

Use Drivers from the NI Device Driver CDInstall drivers from the
NI Device Driver CD for development systems where you intend to use

14-6

ni.com

Chapter 14

Deploying TestStand Systems

the TestStand Deployment Utility. This ensures that any deployments


that you build on the development system can access the most
complete version of the driver software. You should not use a
deployment created by the TestStand Deployment Utility to install
drivers on the development system for redeployment.
Refer to Appendix A, Calling LabVIEW VIs on Remote Systems, in Using
LabVIEW with TestStand for more information about any restrictions that
exist when deploying LabVIEW 8.0 or later VIs.

Common Deployment Scenarios


The following examples describe how to use the TestStand Deployment
Utility in common deployment scenarios. To complete the examples, you
will need one development computer containing a complete installation of
TestStand and one target computer.
Note To run the TestStand Sequence Editor or User Interface application on the target

computer, you must activate an appropriate license or run the application in evaluation
mode. Refer to the TestStand 4.0 Quick Start Guide for more information about the
available TestStand license options.

Deploying the TestStand Engine


1.

Launch the TestStand Deployment Utility by selecting ToolsDeploy


TestStand System from within the sequence editor.

2.

On the System Source tab, enable the Deploy Files in TestStand


User Directories option.
This option collects files from the <TestStand>\...\User
directories, so that any customizations that you have made to process
models, step types, language strings, and so on, will be distributed to
the target computer.

3.

National Instruments Corporation

On the Installer Options tab, complete the following:


a.

Enable the Install TestStand Engine option.

b.

Click Engine Options to launch the TestStand Engine Options


dialog box, which you use to select the TestStand components that
should be present in the installer.

14-7

NI TestStand Reference Manual

Chapter 14

Deploying TestStand Systems

4.

In the TestStand Engine Options dialog box, expand TestStand


Development Components in the tree view.
a.

Click the X next to TestStand Sequence Editor to include


the application in the engine installation, so that you can use the
engine on the deployed system. Refer to the Distributing a User
Interface section of this chapter for information about including a
custom user interface in a deployment.

b.

Click OK to accept the new settings and close the dialog box.

5.

Click Save and save this build as EngineInstaller.tsd.

6.

Click Build to create the installer.

7.

To use the installer, copy all of the files from the <My Documents>\
TestStand\Deployment\Installer directory to a CD or to a
shared directory on your network.

8.

Go to your target computer and insert the CD or connect to the


network, and then run the setup.exe application to start the installer.

9.

Select the target directory in which to install the TestStand Engine.


Click Next to begin the installation.

10. Once the installation is complete, run the LabWindows/CVI user


interface by selecting StartAll ProgramsNational Instruments
<TestStand>\Sequence Editor. If the sequence editor prompts you to
activate a license, you can select Evaluate, if available.Verify that the
TestStand Engine was installed correctly.

Distributing Tests from a Workspace


1.

Launch the TestStand Deployment Utility by selecting ToolsDeploy


TestStand System from within the sequence editor.

2.

On the System Source tab, enable the Deploy Files from TestStand
Workspace File option.

3.

Click the File Browse button, which is located next to the Workspace
File Path control.

4.

Browse to the <TestStand>\Examples\Deployment directory and


select the test.tsw workspace file. Click Open.

5.

Select the Distributed Files tab. A dialog box launches to request


permission to analyze the source files. Click Yes.
The deployment utility analyzes the workspace file and its dependent
files.

NI TestStand Reference Manual

14-8

ni.com

Chapter 14

Deploying TestStand Systems

6.

Locate unused.dll in the tree view. This DLL is not used by the test
system. Click the checkmark located next to the file in the tree view to
remove it from the distribution.

7.

On the Installer Options tab, complete the following:

8.

9.

a.

Enable the Install TestStand Engine option.

b.

Click Engine Options to launch the TestStand Engine Options


dialog box, which you use to select the TestStand components that
should be present in the installer.

In the TestStand Engine Options dialog box, expand TestStand


Development Components in the tree view.
a.

Click the X next to TestStand Sequence Editor to include


the application in the engine installation, so that you can run
sequences on the deployed system. Refer to the Distributing a
User Interface section of this chapter for information about
including a custom user interface in a deployment.

b.

Click OK to accept the new settings and close the dialog box.

Click Save to save this build as test.tsd.

10. Click Build to create an installer.


11. To use the installer, copy all of the files from the <My Documents>\
TestStand\Deployment\Installer directory to a CD or to a
shared directory on your network.
12. Go to your target computer and insert the CD or connect to the
network, and then run the setup.exe application to start the installer.
13. Select a target directory in which to install the tests, and click Next to
begin the installation.
14. Once the installation is complete, launch the LabVIEW user interface
by selecting StartAll ProgramsNational Instruments
<TestStand>\Sequence Editor. If the sequence editor prompts you to
activate a license, you can select Evaluate, if available.
15. Load and run <TestStand>\Examples\Deployment\test.seq
to verify the installation.

National Instruments Corporation

14-9

NI TestStand Reference Manual

Chapter 14

Deploying TestStand Systems

Adding Dynamically Called Files to a Workspace


1.

Launch the TestStand Deployment Utility by selecting ToolsDeploy


TestStand System from within the sequence editor.

2.

On the System Source tab, enable the Deploy Files from TestStand
Workspace File option.

3.

Click the File Browse button, which is located next to the Workspace
File Path control.

4.

Browse to the <TestStand>\Examples\Deployment directory and


select the Dynamically_called_sequence.tsw workspace file.
Click Open.

5.

Select the Distributed Files tab. A dialog box launches to request


permission to analyze the source files. Click Yes.
The deployment utility analyzes the workspace file and its dependent
files.

Note You should receive a warning in the Status Log on the Build Status tab stating that

the sequence was called using an expression.


The deployment utility processes the workspace and updates the
deployed files list. Notice that dynamic.seq is not included in the list.
6.

From within the sequence editor, load the following workspace file:
<TestStand>\Examples\Deployment\Dynamically_
called_sequence.tsw.

7.

Add <TestStand>\Examples\Deployment\dynamic.seq to this


workspace file and then save the changes to the workspace.

8.

On the Distributed Files tab on the TestStand Deployment Utility,


click Analyze Source Files to analyze the modified workspace file.
The deployment utility analyzes the workspace file and its dependent
files.

Note You will receive another warning in the Status Log of the Build Status tab stating

that the sequence was called using an expression. You can ignore this second warning
because you have just added the sequence to the workspace.
9.

Notice that dynamic.seq is now included in the distributed file list.

10. On the Installer Options tab, enable the Install TestStand Engine
option.

NI TestStand Reference Manual

14-10

ni.com

Chapter 14

Deploying TestStand Systems

11. In the TestStand Engine Options dialog box, expand TestStand


Development Components in the tree view.
a.

Click the X next to TestStand Sequence Editor to include


the application in the engine installation, so that you can run
sequences on the deployed system. Refer to the Distributing a
User Interface section of this chapter for information about
including a custom user interface in a deployment.

b.

Click OK to accept the new settings and close the dialog box.

12. Click Save to save the build as Dynamic.tsd.


13. Click Build to create an installer.
14. To use the installer, copy all of the files from the <My Documents>\
TestStand\Deployment\Installer directory to a CD or to a
shared directory on your network.
15. Go to your target computer and insert the CD or connect to the
network, and then run the setup.exe application to start the installer.
16. Select the target directory where you want to install the tests, and click
Next to begin the installation.
17. Once the installation is complete, launch the C++ (MFC) user interface
by selecting StartAll ProgramsNational Instruments
<TestStand>\Sequence Editor. If the sequence editor prompts you to
activate a license, you can select Evaluate, if available.
18. Load and run <TestStand>\Examples\Deployment\
Call_sequence_dynamically.seq to verify the installation.

Distributing a User Interface


Before you complete this exercise, copy the files in <TestStand>\
UserInterfaces\NI\Simple\CVI to <TestStand>\
UserInterfaces\User\Simple\CVI.
Note The TestStand Engine installs a specific version of the LabWindows/CVI Run-Time
Engine which is used in this example. Refer to the <TestStand>\Doc\readme.html file

for the version of the LabWindows/CVI Run-Time Engine that TestStand installs. If you
are using a later version of LabWindows/CVI to create your user interfaces, you must
install that version of the LabWindows/CVI Run-Time Engine where you deploy the user
interface.

National Instruments Corporation

14-11

NI TestStand Reference Manual

Chapter 14

Deploying TestStand Systems

1.

Within the sequence editor, select FileNew Workspace File to create


a new workspace file. Save this workspace as Deploy User
Interface.tsw.

2.

In the Workspace window, right-click the Workspace icon and select


Insert New Project into Workspace from the context menu. Save this
project as User Interface.tpj.

3.

In the Workspace window, right-click the Project icon and select


Add Files to Project from the context menu.

4.

In the file browse dialog box, browse to <TestStand>\


UserInterfaces\User\Simple\CVI\ and change the Files of
Type setting to All Files (*.*).

5.

Select both TestExec.exe and TestExec.uir and click Add.

Note If you are prompted to resolve the path, select Use a relative path for the file you

selected. Enable the Apply to All option, and then click OK twice to close the open dialog
boxes.
6.

Select FileSave Workspace File to save the workspace file.

7.

Start the TestStand Deployment Utility by selecting ToolsDeploy


TestStand System from within the sequence editor.

8.

On the System Source tab, enable the Deploy Files From TestStand
Workspace File option.

9.

Browse to the workspace file you saved in Step 6. Click Open.

10. Select the Distributed Files tab and click Yes in the dialog box
requesting permission to analyze the workspace files.
The deployment utility analyzes the workspace file and its dependent
files.
11. Locate TestExec.exe in the tree view and click on the file. The File
Properties section to the right of the tree view should update to reflect
this selection.
12. Enable the Create Program Item option and type Simple CVI UI
into the neighboring string field to add a shortcut menu item for
TestExec.exe.
13. On the Installer Options tab, enable the Install TestStand Engine
option.
14. Click Save to save the build as SimpleCVIUI.tsd.
15. Click Build to create an installer.

NI TestStand Reference Manual

14-12

ni.com

Chapter 14

Deploying TestStand Systems

16. To use the installer, copy all of the files from the <My Documents>\
TestStand\Deployment\Installer directory to a CD or to a
shared directory on your network.
17. Go to your target computer and insert the CD or connect to the
network, and then run the setup.exe application to start the installer.
18. Select the target directory where you want to install the tests, and click
Next to begin the installation.
19. Once the installation is complete, load and run the Simple CVI user
interface from the StartAll ProgramsMy TestStand System
Simple CVI program group to verify the installation.
You have completed this example. For more information about the
TestStand Deployment Utility, refer to the NI TestStand Help.

National Instruments Corporation

14-13

NI TestStand Reference Manual

Sequence File Translators

15

This chapter describes how TestStand uses sequence file translators and
how you can create and install sequence file translators.

Custom Sequence File Translators


You can create custom sequence file translators that TestStand uses to
load sequence files with your own custom file formats. You can create
translators in various development environments, use versioning schemes
with custom files, and deploy translators with TestStand. Refer to
<TestStand>\Examples\SequenceFileTranslators for example
custom sequence files and translators.
A custom sequence file translator allows TestStand to load test description
files saved in a custom format, such as text or XML. The translator reads
the contents of the custom sequence file, translates the contents to a
TestStand sequence file, and opens the TestStand sequence file in the
sequence editor or a user interface. A custom sequence file translator can
use predefined step types to simplify the mapping of common operations
defined in the custom file format to TestStand steps in sequence files.
Within the sequence editor or user interface, you can perform all typical
operations supported in the TestStand sequence files, such as executing
and debugging sequences, diffing files, adding custom sequence files to
workspaces, and deploying custom sequence files. However, you cannot
automatically save changes you make to the TestStand sequence file back
to a custom sequence file format. You must make all changes to the custom
sequence file directly.

Using a Sequence File Translator


TestStand can load custom sequence files if an existing translator can read
and convert the file into a TestStand SequenceFile object. Translators are
Windows DLLs that export callback functions that TestStand uses to
translate files. Refer to the Creating a Translator DLL section of this
chapter for more information about creating translators and for a complete
list of callback functions the DLL must implement.

National Instruments Corporation

15-1

NI TestStand Reference Manual

Chapter 15

Sequence File Translators

You can use a translator DLL by creating a Translators directory in


<TestStand>\Components\User\ and copying the DLL into the new
directory. When an application loads the TestStand Engine, TestStand
loads any DLLs located in the <TestStand>\Components\User\
Translators\ or <TestStand>\Components\NI\Translators\
directories that export the required callback functions.
A translator DLL can contain one or more translators. When TestStand
loads a translator DLL, TestStand uses the callback functions of the DLL
to obtain information about its translators. TestStand calls the CanTranslate
callback function to determine if the DLL contains a translator that
recognizes a file. The callback returns the index of the translator that
recognizes the file after examining the extension of the file and the contents
of the file, typically the file header. Most of the callback functions that the
DLL implements contain an index parameter, which references a specific
translator in the DLL that must operate on a file.

Creating a Translator DLL


You can create custom sequence file translators in any development
environment that can create a Windows DLL with the required C callback
functions.
NI recommends that you use the translator examples written in
NI LabVIEW, LabWindows/CVI, and Microsoft Visual C++ as a guide.
Each example contains a template project, which contains source code with
empty callback functions that you must export from the translator DLL.
You must add the necessary code to the required callbacks to ensure that the
translator properly integrates with TestStand.
Refer to the following documents and examples in preparation for creating
a custom sequence file translator:

NI TestStand Reference Manual

TestStand ActiveX API Overview section of the TestStand API


Reference Help section of the NI TestStand HelpContains an
overview of the TestStand ActiveX Server functionality and discusses
how to call the API from different programming languages.

Core API Classes, Properties, and Methods section of the TestStand


API Reference Help section of the NI TestStand HelpLists the core
classes in the TestStand API.

15-2

ni.com

Chapter 15

Sequence File Translators

Appendix B, Using the TestStand ActiveX APIs in LabVIEW, of the


Using LabVIEW with TestStand manualDescribes how to call the
TestStand API using LabVIEW.

Appendix B, Using the TestStand ActiveX APIs in LabWindows/CVI,


of the Using LabWindows/CVI with TestStand manualDescribes
how to call the TestStand API using LabWindows/CVI.

Required Callback Functions


A TestStand sequence file translator DLL must export and implement the
following C callback functions. If a translator DLL does not export all of
the callback functions, TestStand does not load the DLL.

CanTranslate
long CanTranslate(const char *fileExtension, IDispatch *readStream, long
*translatorIndex, TS::TSError *error, char
*errorMsg, long errorMsgLength)

Purpose
Returns whether a translator in the DLL can translate the file specified by the file extension
and file stream into a sequence file. Also returns the index of the translator that can translate
the file.
Note If CanTranslate returns a non-zero value for the error parameter, TestStand reports

an error and does not attempt to call CanTranslate for other sequence file translator DLLs
on the system. National Instruments recommends that translators do not return a non-zero
value for the error parameter if an error occurs while attempting to determine whether the
translator can load a file. Instead, translators should typically catch such errors and return
0 from CanTranslate.
Note TestStand supports the use of multi-byte characters. Therefore, when you compare

TestStand strings like Path and Extension, National Instruments recommends that you
use multi-byte safe functions. Using regular string functions may lead to unpredictable
behavior.

Return Value
Returns whether a translator in the DLL can translate the file. A value of 0 indicates that the
translator cannot translate the file. A value other than 0 indicates that the translator can
translate the file.

National Instruments Corporation

15-3

NI TestStand Reference Manual

Chapter 15

Sequence File Translators

Parameters
Parameter Name

Type

Description

fileExtension

string

Specifies the extension of the file that


TestStand is attempting to open. The
fileExtension parameter does not include the
leading period (".") character in the extension
string.

readStream

InputStream

Specifies a reference to an InputStream object


that contains the contents of the file that
TestStand is attempting to open.

translatorIndex

long

Returns the zero-based index of the translator


that can translate the file.

error

TSError

Returns the error code if an error occurs in the


callback.

errorMsg

string

Returns the error message if an error occurs


in the callback. The callback must copy a
string value to the existing buffer, including
the NUL terminating character. Use the
errorMsgLength parameter to determine
the size of the buffer.

errorMsgLength

long

Specifies the maximum number of characters


the DLL can copy to the errorMsg parameter.

GetDescription
void GetDescription(long translatorIndex, char *description, long
descriptionLength, TSError *error, char
*errorMsg, long errorMsgLength)

Purpose
Returns the description of the file extension that the translator supports. TestStand uses the
description in the Open File dialog box.

NI TestStand Reference Manual

15-4

ni.com

Chapter 15

Sequence File Translators

Parameters
Parameter Name

Type

Description

translatorIndex

long

Specifies the zero-based index of the translator


in the DLL that must process the callback.

description

string

Returns the description of the file extension


that the translator supports. The callback must
copy a string value to the existing buffer,
including the NUL terminating character. Use
the descriptionLength parameter to determine
the size of the buffer.

descriptionLength

long

Specifies the maximum number of characters


you can copy to the description parameter.

error

TSError

Returns the error code if an error occurs in the


callback.

errorMsg

string

Returns the error message if an error occurs


in the callback. The callback must copy a
string value to the existing buffer, including
the NUL terminating character. Use the
errorMsgLength parameter to determine
the size of the buffer.

errorMsgLength

long

Specifies the maximum number of characters


you can copy to the errorMsg parameter.

GetExtension
void GetExtension(long translatorIndex, char *fileExtension, long
fileExtensionLength, TSError *error, char
*errorMsg, long errorMsgLength)

Purpose
Returns the file extension that the translator supports. Implement the callback to copy the
extension string to the fileExtension parameter without a leading period character, for
example, "txt" not ".txt".

National Instruments Corporation

15-5

NI TestStand Reference Manual

Chapter 15

Sequence File Translators

Parameters
Parameter Name

Type

Description

translatorIndex

long

Specifies the zero-based index of the translator


in the DLL that must process the callback.

fileExtension

string

Returns the file extension for the files that the


translator supports. The callback must copy a
string value to the existing buffer, including
the NUL terminating character. Use the
fileExtensionLength parameter to determine
the size of the buffer.

fileExtensionLength

long

Specifies the maximum number of characters


you can copy to the fileExtension parameter.

error

TSError

Returns the error code if an error occurs in the


callback.

errorMsg

string

Returns the error message if an error occurs in


the callback. The callback must copy a string
value to the existing buffer, including the NUL
terminating character. Use the errorMsgLength
parameter to determine the size of the buffer.

errorMsgLength

long

Specifies the maximum number of characters


you can copy to the errorMsg parameter.

GetFileFormatVersion
void GetFileFormatVersion(long translatorIndex, const char *path, IDispatch
*readStream, char *fileFormatVersion, long
fileFormatVersionLength, TSError *error, char
*errorMsg, long errorMsgLength)

Purpose
Returns the file format version for the file specified by the path and read stream. Implement
the callback to assign the file format version to the fileFormatVersion parameter. If the
translator does not support reading file format version information from the file, assign
an empty string. TestStand calls this callback to return a version string for the
FileInformation.GetFileFormatVersion method in the TestStand API.

NI TestStand Reference Manual

15-6

ni.com

Chapter 15

Sequence File Translators

Note TestStand supports the use of multi-byte characters. Therefore, when you compare

TestStand strings like Path and Extension, National Instruments recommends that you use
multi-byte safe functions. Using regular string functions may lead to unpredictable
behavior.

Parameters
Parameter Name

Type

Description

translatorIndex

long

Specifies the zero-based index of the


translator in the DLL that must process
the callback.

path

long

Specifies the path to the file.

readStream

InputStream

Specifies a reference to an InputStream


object that contains the contents of the
file.

fileFormatVersion

string

Returns the file format version of the


file. The callback must copy a string
value to the existing buffer, including
the NUL terminating character. Use the
fileFormatVersionLength parameter to
determine the size of the buffer. If the
translator does not support reading file
format version information from the
file, assign an empty string to the
buffer.

fileFormatVersionLength

long

Specifies the maximum number of


characters you can copy to the
fileFormatVersion parameter.

error

TSError

Returns the error code if an error


occurs in the callback.

National Instruments Corporation

15-7

NI TestStand Reference Manual

Chapter 15

Sequence File Translators

Parameter Name

Type

Description

errorMsg

string

Returns the error message if an error


occurs in the callback. The callback
must copy a string value to the existing
buffer, including the NUL terminating
character. Use the errorMsgLength
parameter to determine the size of the
buffer.

errorMsgLength

long

Specifies the maximum number


of characters you can copy to the
errorMsg parameter.

GetFileVersion
void GetFileVersion(long translatorIndex, const char *path, IDispatch
*readStream, char *fileVersion, long
fileVersionLength, TSError *error, char
*errorMsg, long errorMsgLength)

Purpose
Returns the file version string for the file specified by the path and file stream.
National Instruments recommends that the file version uses the format of
"major.minor.revision.build". Implement the callback to assign the file version to
the fileVersion parameter. If the translator does not support reading file version information
from the file, assign an empty string. TestStand calls this callback to return a version for the
FileInformation.GetFileVersion method in the TestStand API.
Note If a translator supports obtaining the file version from a file, the

TranslateToSequenceFile callback in the translator must assign the file version to the
PropertyObjectFile.Version property of the translated sequence file. Otherwise, the version
property is "0.0.0.0".
Note TestStand supports the use of multi-byte characters. Therefore, when you compare

TestStand strings like Path and Extension, National Instruments recommends that you use
multi-byte safe functions. Using regular string functions may lead to unpredictable
behavior.

NI TestStand Reference Manual

15-8

ni.com

Chapter 15

Sequence File Translators

Parameters
Parameter Name

Type

Description

translatorIndex

long

Specifies the zero-based index of the


translator in the DLL that must process the
callback.

path

long

Specifies the path to the file.

readStream

InputStream

Specifies a reference to an InputStream


object that contains the contents of the file.

fileVersion

string

Returns the file version of the file.


The callback must copy a string value
to the existing buffer, including
the NUL terminating character. Use the
fileVersionLength parameter to determine
the size of the buffer. If the translator does
not support reading file version information
from the file, assign an empty string to the
buffer.

fileVersionLength

long

Specifies the maximum number of


characters you can copy to the fileVersion
parameter.

error

TSError

Returns the error code if an error occurs in


the callback.

errorMsg

string

Returns the error message if an error occurs


in the callback. The callback must copy a
string value to the existing buffer, including
the NUL terminating character. Use the
errorMsgLength parameter to determine the
size of the buffer.

errorMsgLength

long

Specifies the maximum number of


characters you can copy to the errorMsg
parameter.

National Instruments Corporation

15-9

NI TestStand Reference Manual

Chapter 15

Sequence File Translators

GetTranslatorCount
long GetTranslatorCount()

Purpose
Returns the number of valid translators the DLL implements. Each translator supports a single
custom file format. If a DLL implements more than one translator, the DLL must maintain
indexes of the translators to support the required callback functions.

Return Value
Returns the number of translators in the DLL.

IsCurrentFileVersion
long IsCurrentFileVersion(long translatorIndex, const char *path, IDispatch
*readStream, TSError *error, char *errorMsg,
long errorMsgLength)

Purpose
Returns whether the version of the file specified by the path and file stream matches
the current version of the translator, an older version of the translator, or a newer
version of the translator. TestStand calls this callback to return a value for the
Engine.IsCurrentSequenceFileVersion method in the TestStand API.
Note TestStand supports the use of multi-byte characters. Therefore, when you compare

TestStand strings like Path and Extension, National Instruments recommends that you use
multi-byte safe functions. Using regular string functions may lead to unpredictable
behavior.

Return Value
Returns one of the following values:
Value

Description

The file is compatible with an older version of the translator.

The file is compatible with the current version of the translator.

The file is compatible with a newer version of the translator.

If the translator does not support reading file version information from the file, return a value
of zero.

NI TestStand Reference Manual

15-10

ni.com

Chapter 15

Sequence File Translators

Parameters
Parameter Name

Type

Description

translatorIndex

long

Specifies the zero-based index of the


translator in the DLL that must process the
callback.

path

long

Specifies the path to the file.

readStream

InputStream

Specifies a reference to an InputStream


object that contains the contents of the file.

error

TSError

Returns the error code if an error occurs in


the callback.

errorMsg

string

Returns the error message if an error occurs


in the callback. The callback must copy a
string value to the existing buffer, including
the NUL terminating character. Use the
errorMsgLength parameter to determine the
size of the buffer.

errorMsgLength

long

Specifies the maximum number of


characters you can copy to the errorMsg
parameter.

TranslateToSequenceFile
void TranslateToSequenceFile(long translatorIndex, IDispatch *engine,
IDispatch *readStream, IDispatch *seqFile,
TSError *error, char *errorMsg, long
errorMsgLength)

Purpose
Translates the file represented by the file stream and returns a SequenceFile object to
TestStand. Implement the callback to create the SequenceFile object using the engine
parameter, add sequences and steps that correspond to the content of the file stream, and
assign the reference to the seqFile parameter. Set the seqFile parameter to NULL and set
the error parameter to a non-zero value if the translator cannot translate the file stream.

National Instruments Corporation

15-11

NI TestStand Reference Manual

Chapter 15

Sequence File Translators

Parameters
Parameter Name

Type

Description

translatorIndex

long

Specifies the zero-based index of the


translator that the DLL implements.

engine

Engine

Specifies a reference to the TestStand Engine.


Use the Engine object to create a new
SequenceFile object.

readStream

InputStream

Specifies a reference to an InputStream object


that contains the contents of the file.

seqFile

SequenceFile

Returns a reference to a new SequenceFile


object that represents the translated file.

error

TSError

Returns the error code if an error occurs in the


callback.

errorMsg

string

Returns the error message if an error occurs in


the callback. The callback must copy a string
value to the existing buffer, including the NUL
terminating character. Use the
errorMsgLength parameter to determine the
size of the buffer.

errorMsgLength

long

Specifies the maximum number of characters


you can copy to the errorMsg parameter.

NI TestStand Reference Manual

15-12

ni.com

Chapter 15

Sequence File Translators

Error Handling
Each callback function contains three parameters that take care of error
handling: an error code, an error string, and the maximum length for the
error string. When an error occurs within a callback function, set the error
code to a non-zero value. If the assigned value is a TestStand error code,
TestStand uses the standard description for the TestStand error code. If you
want to include additional error details, the callback function can copy the
error details to the error message string. However, the callback must not
exceed the number of characters specified by the maximum length for the
error message. TestStand uses the error message string the callback
function specifies.
Note Avoid throwing exceptions from C callback functions that the TestStand Engine

calls. Exceptions returned to TestStand might be lost or not handled properly. Refer to the
example translator projects included with TestStand for examples of how to return errors
from within callback functions.

Example Sequence File Translators


TestStand includes example translator projects for the LabVIEW,
LabWindows/CVI, and Microsoft Visual C++ development environments.
The example projects demonstrate how to build translator DLLs and
provide guidance for developing translators. The examples illustrate two
simple translators for each development environment that convert sample
test descriptions in XML and ASCII text formats into TestStand sequence
files. The example translators for each file format produce the same
TestStand sequence file.
The sample test descriptions specify steps that perform a calculation,
display the result of the calculation in a graph, compare the result with
an expected value, and display a message that indicates if the test passed
or failed. The translation from the example format into a sequence file
involves adding steps and local variables to a sequence in a new sequence
file object and configuring the steps to perform the required operations. The
translators also use a custom step type that TestStand loads from a type
palette file that you must place in the <TestStand>\Components\
User\TypePalettes directory. The translators demonstrate how to use
the TestStand API to perform the file translation.

National Instruments Corporation

15-13

NI TestStand Reference Manual

Chapter 15

Sequence File Translators

Complete the following steps to use an example:


1.

Open the TextTranslator or XMLTranslator directory for


one of the examples located in the <TestStand>\Examples\
SequenceFileTranslators directory.

2.

Open the project in the development environment for the example.

3.

If you made any changes to the project, rebuild the project to re-create
the translator DLL.

4.

Create a Translators directory in <TestStand>\Components\


User\ and copy the translator DLL into the new directory.

5.

Copy the type NI_ExampleTranslatorTypes.ini file located in


the <TestStand>\Examples\SequenceFileTranslators
directory to the <TestStand>\Components\User\TypePalettes
directory.

6.

Launch the TestStand Sequence Editor or a TestStand User Interface.

7.

Select FileOpen and select SampleTestFile.xml or


SampleTestFile.lvtf text version for LabVIEW or
SampleTestFile.cvitf text version for LabWindows/CVI in the
example translator directory.

8.

Review the contents of the translated sequence file.

9.

Launch an execution using the MainSequence in the sequence file.

Versioning Translators and Custom Sequence Files


Custom sequence file translators provide support for versioning the custom
sequence file format and the sequences contents. The file format version
identifies the structure and syntax of the file. The file version identifies the
revision of the contents of the file.
If the contents of a custom sequence file include a file format version,
a translator can support reading files with the current file format and files
with an earlier file format. In addition, the translator can identify newer file
formats that the translator does not support. When a translator callback
accesses the contents of the file, the translator ensures that the file format
version is supported. For example, the CanTranslate callback can use the
version to determine if the translator can load a file. In addition, TestStand
displays the return value from the GetFileFormatVersion callback in reports
the Workspace Documentation tool creates.

NI TestStand Reference Manual

15-14

ni.com

Chapter 15

Sequence File Translators

If the contents of a custom sequence file include a file version


or revision, implement the translator to assign the version to the
PropertyObjectFile.Version property in the TranslateSequenceFile callback
and return the version in the GetFileVersion callback. This ensures that
the Sequence File Properties dialog box displays the file version and the
Sequence File Documentation and Workspace Documentation tools
display the file version in reports that you create.
If the file formats between versions differ significantly, you should consider
creating two translators in a single DLL or a separate translator in two
DLLs. This can simplify the code necessary to translate each file format. If
files contain header fields that identify the file format and the CanTranslate
callback utilizes these fields, using two translators should not impact the
performance of opening files in TestStand.
Even if a translator does not support versioning, the translator
must implement the GetFileFormatVersion, GetFileVersion, and
IsCurrentVersion callbacks. Refer to the documentation on these callbacks
for the default value to return.

Deploying Translators and Custom Sequence Files


You can add translator files and custom sequence files to a workspace for
deployment using the TestStand Deployment Utility.

Deploying Custom Sequence File Translators


If you install the custom sequence file translator DLL and its support files
in the <TestStand>\Components\User\Translator directory on
the system that you use to build the deployment, the deployment utility
automatically includes these files if you enable the Deploy Files in
TestStand User Directories option on the System Source tab of the
TestStand Deployment Utility. Alternatively, you can add the translator
files to the workspace and set the target destination directory for the files to
<TestStand>\Components\User\Translator.

National Instruments Corporation

15-15

NI TestStand Reference Manual

Chapter 15

Sequence File Translators

Deploying Custom Sequence Files


You can add custom sequence files to the workspace that the deployment
utility uses to build a deployment. When the deployment utility analyzes a
TestStand sequence file, the utility locates the code modules that the steps
in the sequence file call and adds the code module files to the deployment.
If the deployment utility relocates a code module file, the utility might
modify the code module path in the TestStand sequence file to ensure that
TestStand can locate the code module on the deployed system.
For custom sequence files, the deployment utility must load and translate
the file to locate the code modules that the steps in the sequence file call.
However, the utility cannot modify the paths in the custom sequence file.
The deployment utility returns a warning if the utility cannot ensure that
TestStand can locate the code module on the deployed system. You must fix
the paths on the system that you are attempting to deploy or you must fix
the paths on the target system after deployment.
Refer to the Chapter 14, Deploying TestStand Systems, and the
NI TestStand Help for more information about creating and deploying
TestStand files using the deployment utility.

NI TestStand Reference Manual

15-16

ni.com

Process Model Architecture

This appendix discusses the purpose and usage of the process models that
come with TestStand. It also describes the directory structure that TestStand
uses for process model files and the special capabilities that the TestStand
Sequence Editor has for editing process model sequence files.
To better understand the information in this appendix, review the Process
Models section of Chapter 1, TestStand Architecture, which discusses the
purpose of process models, entry points, and the relationship between a
process model and a client sequence file.

TestStand Process Model Architecture


The Sequential, Parallel, and Batch process models all have the same basic
structure for running a test sequence. Using the Test UUTs or Single Pass
entry point, the process models run test sequences, generate reports, and
log UUT results to a database according to your configuration settings.
Figure A-1 illustrates the basic processes that these models follow.

National Instruments Corporation

A-1

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Test UUTs Process

Single Pass Process

Initialization

Initialization

Get Current Report Options,


Database Options, and
Model Options

Get Current Report Options,


Database Options, and
Model Options

Get UUT Serial Number

No

Continue
Testing?
Yes
Call the Test Sequence

Call the Test Sequence

Display the UUT Results

Generate a Report

Generate a Report

Log Results to a Database

Log Results to a Database

Cleanup

Cleanup

Figure A-1. Process Flow

The main differences between the process models are the number of UUTs
that each process model runs for the Test UTTs or Single Pass entry points
and the way each process model relates to and synchronizes with UUTs.

NI TestStand Reference Manual

A-2

ni.com

Appendix A

Process Model Architecture

TestStand Process Models


Table A-1 lists the TestStand process models and their respective sequence
files.
Table A-1. TestStand Process Models

Process Model

Process Model Sequence File

Sequential Model

<TestStand>\Components\NI\Models\
TestStandModels\SequentialModel.seq

Parallel Model

<TestStand>\Components\NI\Models\
TestStandModels\ParallelModel.seq

Batch Model

<TestStand>\Components\NI\Models\
TestStandModels\BatchModel.seq

The Sequential model is the default TestStand process model. The Parallel
and Batch models have features to help you implement test stations that test
multiple UUTs at the same time.
You can create your own process models or modify a copy of a process
model that TestStand provides.

Features Common to all TestStand Process Models


All TestStand process models identify UUTs, generate test reports, log
results to databases, and display UUT status information. These process
models also allow client sequence files to customize various model
operations by overriding model-defined callback sequences.
Process models provide Configuration and Execution entry points that
you can use to configure model settings and to run client files under the
model. Model entry points are typically listed in an application under the
Configure and Execute menus.
TestStand process models have the following Execution entry points:

Test UUTsTests and identifies multiple UUTs or UUT batches in


a loop.

Single PassTests one UUT or a single batch of UUTs without


identifying them.

National Instruments Corporation

A-3

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Note When you select the Test UUTs entry point to start an execution that continuously

tests UUTs, any configuration changes that you make to the Report, Database, or Model
Options entry points will not affect UUTs tested in that execution.
TestStand process models have the following Configuration entry points:

Report OptionsLaunches the Report Options dialog box, in which


you can configure the location and contents of report files.

Database OptionsLaunches the Database Options dialog box, in


which you can configure the logging of results to database tables.

Model OptionsLaunches the Model Options dialog box, in which


you can configure the number of test sockets and other options related
to process models.

For more information about the dialog boxes associated with the
Configuration entry points, refer to the NI TestStand Help.

Sequential Model
The most basic process model is the Sequential process model. The
Sequential process model tests one UUT at a time.

Parallel and Batch Models


The Parallel and Batch models have features that make it easier to
simultaneously test groups of similar UUTs. Use these models to run
the same test sequence on multiple UUTs at the same time.
For both the Parallel and Batch models, specify the number of test sockets
in your system in the Model Options dialog box, which you can access by
selecting ConfigureModel Options.

Parallel Model
Use the Parallel model to control multiple independent test sockets. The
Parallel model allows you to start and stop testing on any test socket at any
time. For example, if you have five test sockets for testing radios, the
Parallel model allows you to load a new radio into an open test socket while
the other test sockets are testing other radios.
When you select the Single Pass entry point, the Parallel model launches a
separate execution for each test socket without prompting for UUT serial
numbers.

NI TestStand Reference Manual

A-4

ni.com

Appendix A

Process Model Architecture

Batch Model
Use the Batch model to control a set of test sockets that test multiple UUTs
as a group. For example, if you have a set of circuit boards attached to
a common carrier, the Batch model ensures that you start and finish
testing all boards at the same time. The Batch model also provides batch
synchronization features that allow you to specify that a step that applies to
the batch as a whole should run only once per batch instead of once for each
UUT. The Batch model also allows you to specify that certain steps or
groups of steps cannot run on more than one UUT at a time or that certain
steps must run on all UUTs at the same time. The Batch model can generate
batch reports that summarize the test results for the UUTs in the batch.
When you select the Single Pass entry point, the Batch model launches a
separate execution for each test socket without prompting for UUT serial
numbers.

Selecting the Default Process Model


To change your default process model, select ConfigureStation Options
and click the Model tab. Select a model from the from the Station Model
ring control or click Browse to select a process model sequence file. You
can also use the Sequence File Properties dialog box to specify that a
sequence file always uses a particular process model.

Directory Structure for Process Model Files


The TestStand installer places process model files in the <TestStand>\
Components\NI\Models\TestStandModels directory.
If you want to modify a TestStand process model, copy the
TestStandModels directory to a new subdirectory under the
<TestStand>\Components\User\Models directory. In the new
directory, rename the process model sequence files and any code module
files. Next, update the process model sequence file you are customizing
to call the modules with the new file names you select. By placing your
modifications under <TestStand>\Components\User, you ensure that a
newer installation of the same version of TestStand does not overwrite your
customizations, or that uninstalling TestStand does not remove the files you
customize.

National Instruments Corporation

A-5

NI TestStand Reference Manual

Appendix A

Process Model Architecture

The list of search paths in TestStand includes the subdirectories in


<TestStand>\Components\User. The <TestStand>\Components\
User directory protects your customized components and serves as the
staging area for the components that you include in your own run-time
distribution of TestStand.
When you create a custom process model, you must first establish your
custom process model sequence file as the process model for the station.
Make this assignment on the Model tab on the Station Options dialog box.

Sequential Process Model


Sequences
Figure A-2 shows a list of all the sequences found in the Sequential process
model, SequentialModel.seq. The sequences are divided into five
categories: Execution entry points, Configuration entry points, Model
callbacks, Utility subsequences, and Engine callbacks.

NI TestStand Reference Manual

A-6

ni.com

Appendix A

Process Model Architecture

1
2

Execution Entry Points


Configuration Entry Points

3
4

Model Callbacks
Utility Subsequences

Engine Callbacks

Figure A-2. Sequences in the Sequential Process Model

National Instruments Corporation

A-7

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Execution Entry Points


The following sequences are Execution entry points in the Sequential
process model:

Test UUTsInitiates a loop that repeatedly identifies and tests UUTs.


When a window for a client sequence file is active, the Test UUTs item
is listed in the Execute menu. For more information about the Test
UUTs entry point, refer to Test UUTs in the Sequential Process Model
section of this appendix.

Single PassTests a single UUT without identifying it. In essence, the


Single Pass entry point performs a single iteration of the loop that the
Test UUTs entry point performs. When a window for a client sequence
file is active, the Single Pass item is listed in the Execute menu. For
more information about the Single Pass entry point, refer to Single
Pass in the Sequential Process Model section of this appendix.

Configuration Entry Points


The following sequences are Configuration entry points in the Sequential
process model:

NI TestStand Reference Manual

Configure Report OptionsLaunches the Report Options dialog


box, in which you can specify the contents, format, and pathname of
the test report. The settings in the Report Options dialog box apply to
the test station as a whole. The entry point saves the station report
options to disk. The entry point item is listed as Report Options in the
Configure menu. For more information about report options, refer to
Chapter 6, Database Logging and Report Generation.

Configure Database OptionsLaunches the Database Options


dialog box, in which you can specify the database logging options. The
settings in the Database Options dialog box apply to the test station as
a whole. The entry point saves the station database options to disk. The
entry point item is listed as Database Options in the Configure menu.
For more information about database options, refer to Chapter 6,
Database Logging and Report Generation.

Configure Model OptionsLaunches the Model Options dialog box,


in which you can specify model options other than database or report
options. The settings in the Model Options dialog box apply to the test
station as a whole. The entry point saves the station model options to
disk. The entry point item is listed as Model Options in the Configure
menu.

A-8

ni.com

Appendix A

Process Model Architecture

Model Callbacks
The following sequences are Model callbacks in the Sequential process
model, which you can override in a client sequence file:

MainSequenceTest UUTs and Single Pass call this callback to test


a UUT. The MainSequence callback is empty in the process model file.
The client sequence file must contain a MainSequence callback that
performs the tests on a UUT.

PreUUTLaunches the UUT Information dialog box, which the


operator uses to enter the UUT serial number. The Test UUTs entry
point calls the PreUUT callback at the beginning of each iteration of
the UUT loop. If the operator indicates through the dialog box that
no more UUTs are available for testing, the UUT loop terminates. If
the operator chooses to stop testing, the IdentifyUUT step sets the
ContinueTesting parameter to False.
The ContinueTesting parameter is a local variable that the Test UUTs
sequence passes to the PreUUT Callback sequence. If the operator
enters a UUT serial number, the IdentifyUUT step stores the serial
number in the UUT.SerialNumber parameter, which is a local variable
that the Test UUTs sequence passes to the PreUUT Callback sequence.

PostUUTDisplays a banner indicating the status of the test that the


MainSequence callback in the client sequence file performs on the
UUT. The Test UUTs entry point calls the PostUUT callback at the end
of each iteration of the UUT loop.

PreUUTLoopThe Test UUTs entry point calls this callback before


the UUT loop begins. The PreUUTLoop callback in the process model
file is empty.

PostUUTLoopThe Test UUTs entry point calls this callback after


the UUT loop terminates. The PostUUTLoop callback in the process
model file is empty.

ReportOptionsExecution entry points call this callback through the


GetReportOptions subsequence. After reading the test station report
options from disk, GetReportOptions calls the ReportOptions callback
to give the client sequence file an opportunity to modify the report
options. For example, you might want to force the report format to be
ASCII-text for a particular client sequence file. The ReportOptions
callback in the process model file is empty.

DatabaseOptionsExecution entry points call this callback through


the GetDatabaseOptions subsequence. After reading the test
station database options from disk, GetDatabaseOptions calls the
DatabaseOptions callback to give the client sequence file an

National Instruments Corporation

A-9

NI TestStand Reference Manual

Appendix A

Process Model Architecture

opportunity to modify the database options. The DatabaseOptions


callback in the process model file is empty.

ModelOptionsExecution entry points call this callback through the


GetModelOptions subsequence. After reading the test station model
options from disk, GetModelOptions calls the ModelOptions callback
to give the client sequence file an opportunity to modify the model
options. The ModelOptions callback in the process model file is empty.

TestReportExecution entry points call this callback to generate the


contents of the test report for one UUT. Execution entry points do not
call this callback if the On-The-Fly Reporting option is enabled on the
Report Options dialog box. You can override the TestReport callback
in the client sequence file if you want to change its behavior entirely.
The default process model defines a test report for a single UUT as a
header, an entry for each step result, and a footer. If you do not override
the TestReport callback, you can override the ModifyReportHeader,
ModifyReportEntry, and ModifyReportFooter callbacks to customize
the test report.
Depending on the settings in the Report Options dialog box, the
TestReport callback determines whether TestStand builds the report
body using sequences or a DLL. If you select the Sequence option,
the TestReport callback calls the AddReportBody sequence
in reportgen_xml.seq, reportgen_html.seq, or
reportgen_txt.seq to build the report body. The sequence report
generator uses a series of sequences with steps that recursively process
the result list for the execution. If you select the DLL option, the
TestReport callback calls a single function in modelsupport2.dll
to build the entire report body before returning. You can access the
project and source code for the DLL built in LabWindows/CVI from
the <TestStand>\Components\NI\Models\TestStandModels
directory.

NI TestStand Reference Manual

ModifyReportHeaderThe TestReport callback calls this callback


in order to modify the report header using the client sequence file.
ModifyReportHeader receives the following parameters: the
UUT, the tentative report header text, and the report options. The
ModifyReportHeader callback in the process model file is empty.

ModifyReportEntryThe TestReport callback calls this callback


in order to modify the entry point for each step result using the client
sequence file. Using subsequences, the TestReport callback calls
ModifyReportEntry for each result in the result list for the UUT.
ModifyReportEntry receives the following parameters: an entry from
the result list, the UUT, the tentative report entry text, the report
options, and a level number that indicates the call stack depth at the

A-10

ni.com

Appendix A

Process Model Architecture

time the step executed. The ModifyReportEntry callback in the process


model file is empty.
Note In the Report Options dialog box, you can choose to use sequences or a DLL to

produce the report body. If you select the DLL option, TestStand generates reports more
efficiently. However, TestStand will not call ModifyReportEntry callbacks if the DLL
option is enabled.

ModifyReportFooterThe TestReport callback calls this callback


in order to modify the report footer using the client sequence file.
ModifyReportFooter receives the following parameters: the
UUT, the tentative report footer text, and the report options. The
ModifyReportFooter callback in the process model file is empty.

LogToDatabaseExecution entry points call this callback to


populate a database with the results for one UUT. Execution entry
points do not call this callback if the Use On-The-Fly Logging option
is enabled on the Database Options dialog box. You can override the
LogToDatabase callback in the client sequence file if you want to
change its behavior entirely. LogToDatabase receives the following
parameters: the UUT, the result list for the UUT, and the database
options.

Process SetupExecution entry points call this callback from the


Setup step groups to give the client sequence file an opportunity to
execute any setup steps that must run only once during the execution
of the process model. The Process Setup callback in the process model
file is empty.

Process CleanupExecution entry points call this callback from the


Cleanup step groups to give the client sequence file an opportunity to
execute any cleanup steps that must run only once during the execution
of the process model. The Process Cleanup callback in the process
model file is empty.

Utility Subsequences
The following sequences are Utility subsequences that are called by the
other sequences in the Sequential process model:

National Instruments Corporation

Get Report OptionsExecution entry points call this sequence at the


beginning of an execution. Get Report Options reads the report options
and then calls the ReportOptions callback to give you an opportunity
to modify the report options in the client sequence file.

A-11

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Get Station InfoExecution entry points call this sequence at the


beginning of an execution. Get Station Info identifies the test station
name and the current user.

Get Database OptionsExecution entry points call this sequence


at the beginning of an execution. Get Database Options reads the
database options and then calls the DatabaseOptions callback to
give you an opportunity to modify the database options in the client
sequence file.

Get Model OptionsExecution entry points call this sequence at the


beginning of an execution. Get Model Options reads the model options
and then calls the ModelOptions callback to give you an opportunity
to modify the model options in the client sequence file.

Engine Callbacks
The following callbacks are Engine callbacks that are in the Sequential
process model:

ProcessModelPostResultListEntryThe process model enables this


callback if you enable the On-The-Fly Reporting option of the Report
Options dialog box or if you enable the On-The-Fly Logging option of
the Database Options dialog box. TestStand calls the Engine callback
after each step that tests a UUT and generates a step result.

SequenceFilePostResultListEntryThe process model enables this


callback if you enable the On-The-Fly Reporting option of the Report
Options dialog box or if you enable the On-The-Fly Logging option of
the Database Options dialog box. TestStand calls this Engine callback
after any step in the process model generates a step result. The
MainSequence model callback steps in the process model sequences
are the only steps that enable the generation of step results.

Test UUTs
Table A-2 lists the most significant steps of the Test UUTs entry point in
the Sequential process model, in the order that the Test UUTs entry point
performs them.
Table A-2. Order of Actions the Sequential Process Model Test UUTs Entry Point Performs

Action
Number

Description

Remarks

Call ProcessSetupCallback

The default callback is empty.

Call PreUUTLoop callback.

Callback in the process model file is empty.

NI TestStand Reference Manual

A-12

ni.com

Appendix A

Process Model Architecture

Table A-2. Order of Actions the Sequential Process Model Test UUTs Entry Point Performs (Continued)

Action
Number

Description

Remarks

Call Get Model Options Utility


subsequence.

Reads model options from disk. Calls the


ModelOptions callback to give the client
sequence file an opportunity to modify the
model options.

Call Get Station Info Utility


subsequence.

Identifies the test station name and the


current user.

Call Get Report Options Utility


subsequence.

Reads report options from disk. Calls the


ReportOptions callback to give the client
sequence file an opportunity to modify the
report options.

Call Configure Post Result Callbacks


Utility subsequence

Enables ProcessModelPostResultListEntry
and SequenceFilePostResultListEntry
callbacks if on-the-fly report generation
or database logging is enabled.

Call Get Database Options Utility


subsequence.

Reads database options from disk. Calls the


DatabaseOptions callback to give the client
sequence file an opportunity to modify the
database options.

Increment the UUT index.

Call PreUUT callback.

10

If no more UUTs, go to
Action Number 20.

11

Setup report.

Determines the report file pathname, setup


display settings, reset the report, and set the
report location.

12

Clear information from previous loop


iteration.

Discards the previous results and clears the


report.

13

New UUT for report generation and


database logging.

Starts on-the-fly report generation and


database logging, if enabled.

14

Call MainSequence callback.

MainSequence callback in the client


sequence file performs tests on the UUT.

National Instruments Corporation

Obtains the UUT serial number from the


operator.

A-13

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-2. Order of Actions the Sequential Process Model Test UUTs Entry Point Performs (Continued)

Action
Number

Description

Remarks

15

Call PostUUT callback.

Displays a pass, fail, error, or terminate


banner.

16

Call TestReport callback.

Generates a test report for the UUT, if


on-the-fly report generation is disabled.

17

Write the UUT report to disk.

Appends an existing file or creates a new


file. Also adjusts the root tags if the report
format is XML.

18

Call LogToDatabase callback.

Logs test results to a database for the UUT.

19

Loop back to Action Number 8.

20

Call PostUUTLoop callback.

Callback in the process model file is empty.

21

Call ProcessCleanup callback

The default callback is empty.

Single Pass
Table A-3 lists the most significant steps of the Single Pass entry point in
the Sequential process model, in the order that the Single Pass entry point
performs them.
Table A-3. Order of Actions the Sequential Process Model Single Pass Entry Point Performs

Action
Number

Description

Remarks

Call ProcessSetup callback

The default callback is empty.

Call Get Model Options Utility


subsequence.

Reads model options from disk. Calls the


ModelOptions callback to give the client
sequence file an opportunity to modify the
model options.

Call Get Station Info Utility


subsequence.

Identifies the test station name and the


current user.

Call Get Report Options Utility


subsequence.

Reads report options from disk. Calls the


ReportOptions callback to give the client
sequence file an opportunity to modify the
report options.

NI TestStand Reference Manual

A-14

ni.com

Appendix A

Process Model Architecture

Table A-3. Order of Actions the Sequential Process Model Single Pass Entry Point Performs (Continued)

Action
Number

Description

Remarks

Call Get Database Options Utility


subsequence.

Reads database options from disk. Calls the


DatabaseOptions callback to give the client
sequence file an opportunity to modify the
database options.

Call Configure Post Result Callbacks


Utility subsequence.

Enables ProcessModelPostResultListEntry
and SequenceFilePostResultListEntry
callbacks if on-the-fly report generation or
database logging is enabled.

Setup report.

Determines the report file pathname, setup


display settings, reset the report, and set the
report location.

New UUT for report generation and


database logging.

Starts on-the-fly report generation and


database logging, if enabled.

Call MainSequence callback.

MainSequence callback in the client


sequence file performs tests on the UUT.

10

Call TestReport callback.

Generates a test report for the UUT, if


on-the-fly report generation is disabled.

11

Write the UUT report to disk.

Appends to an existing file or creates a


new file.Also adjust the root tags if the
report format is XML.

12

Call LogToDatabase callback.

Logs test results to a database for the UUT.

13

Call ProcessCleanup callback.

The default callback is empty.

National Instruments Corporation

A-15

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Parallel Process Model


Sequences
Figure A-3 shows a list of all the sequences found in the Parallel process
model, ParallelModel.seq. These sequences are divided into seven
categories: Execution entry points, Utility sequences, hidden Execution
entry points, Configuration entry points, Model callbacks, Utility
subsequences, and Engine callbacks.

5
2

4
7

1
2
3

Main Execution Entry Points


Utility Sequences
Hidden Execution Entry Points

4
5

Configuration Entry Points


Model Callbacks

7
6

Engine Callbacks
Utility Subsequences

Figure A-3. Sequences in the Parallel Process Model

NI TestStand Reference Manual

A-16

ni.com

Appendix A

Process Model Architecture

Execution Entry Points


The following sequences are the main Execution entry points in the Parallel
process model:

Test UUTsControls the test socket executions it creates using the


Test UUTs Test Socket Entry Point sequence. When a window for
a client sequence file is active, the Test UUTs item is listed in the
Execute menu. For more information about the Test UUTs entry point,
refer to Test UUTs in the Parallel Process Model section of this
appendix.

Single PassControls the test socket executions it creates using the


Single Pass Test Socket Entry Point sequence. When a window for
a client sequence file is active, the Single Pass item is listed in the
Execute menu. For more information about the Single Pass entry point,
refer to Single Pass in the Parallel Process Model section of this
appendix.

Utility Sequences
The following sequences are Utility sequences in the Parallel process
model that are used by the main Execution entry points:

Initialize TestSocketThe controlling execution calls this sequence


to initialize the data for and create the test socket executions.

Tile Execution WindowsThe controlling execution calls this


sequence to tile the test socket Execution windows by building a list
of executions and posting a UIMessage to the user interface requesting
it to tile the Execution windows.

Monitor ThreadsThe ProcessDialogRequests sequence calls this


sequence periodically from the controlling execution to poll to see
whether any of the test socket executions have been terminated or
aborted. If any have, it updates the ModelData for that test socket to
indicate its new state and tells the dialog box to update its display for
that test socket.

ProcessDialogRequestsThe controlling execution calls this


sequence from the Test UUTs sequence. The sequence loops,
waiting for requests that the dialog box enqueues into
ModelData.DialogRequestQueue. The requests are the names of the
sequences to call. When the ProcessDialogRequests sequence receives
such a request, it calls the requested sequence. Additionally, this
sequence periodically calls the Monitor Threads sequence to verify
that the test socket executions are still running and update information
about them if they are not.

National Instruments Corporation

A-17

NI TestStand Reference Manual

Appendix A

Process Model Architecture

NI TestStand Reference Manual

Run UUT Info DialogThe controlling execution calls this sequence


from a new thread. This sequence initializes and runs the modeless
dialog box that the Test UUTs entry point uses to allow the user to
control the test socket executions.

Continue TestSocketDialog box request callback that the


ProcessRequests sequence calls. This sequence sets a notification
for the test socket that the request specifies allowing the test socket
execution to continue. The test socket execution waits on this
notification in its default implementation of the PreUUT and PostUUT
callbacks.

Terminate TestSocketDialog box request callback that the


ProcessDialogRequests sequence calls. The Terminate TestSocket
sequence terminates the execution for the test socket that the request
specifies.

Abort TestSocketDialog box request callback that the


ProcessDialogRequests sequence calls. The Abort TestSocket
sequence aborts the execution for the test socket that the request
specifies.

Restart TestSocketDialog box request callback that the


ProcessDialogRequests sequence calls. The Restart TestSocket
sequence restarts the execution for the test socket that the request
specifies. After the sequence restarts the execution, the sequence
re-tiles the Execution windows to include the one it restarts.

Terminate All TestSocketsDialog box request callback that


the ProcessDialogRequests sequence calls. The Terminate All Test
Sockets sequence terminates all of the test socket executions.

Abort All TestSocketsDialog box request callback that the


ProcessDialogRequests sequence calls. The Abort All TestSockets
sequence aborts all of the test socket executions.

Stop All TestSocketsDialog box request callback that the


ProcessDialogRequests sequence calls. The Stop All TestSockets
sequence sets a flag for each test socket execution telling them to stop
after they complete their current UUT test sequence. The sequence
also sets a notification to allow them to execute to that point without
interruption.

View TestSocket ReportDialog box request callback that the


ProcessDialogRequests sequence calls. The View TestSocket Report
sequence launches a report viewer on the report file for the test socket
that the request specifies.

View TestSocket Report Current OnlyDialog box request


callback that the ProcessDialogRequests sequence calls. The View

A-18

ni.com

Appendix A

Process Model Architecture

TestSocket Report Current Only sequence launches a report viewer


for the report last generated for the test socket that the request
specifies. This sequence differs from the View TestSocket Report
sequence in that it shows only the last report rather than the whole
report file.

Hidden Execution Entry Points


The following sequences are hidden Execution entry points in the Parallel
process model, which are used by the main Execution entry points to
initiate test socket executions but are never displayed:

Test UUTs Test Socket Entry PointThe controlling execution


uses this entry point to create the test socket executions. If you insert a
step into this sequence, disable the Record Results option for the step.
The Test UUTs Test Socket Entry Point sequence implements
the Test UUTs process for the test socket executions. For more
information about this entry point, refer to Test UUTs Test Socket
Entry Point in the Parallel Process Model section of this appendix.

Single Pass Test Socket Entry PointThe controlling execution


uses this entry point to create the test socket executions. If you insert a
step into this sequence, disable the Record Results option for the step.
The Single Pass Test Socket Entry Point sequence implements
the Single Pass process for the test socket executions. For more
information about this entry point, refer to Single Pass Test Socket
Entry Point in the Parallel Process Model section of this appendix.

Configuration Entry Points


The following sequences are Configuration entry points in the Parallel
process model:

National Instruments Corporation

Configure Report Options, Configure Database Options, and


Configure Model OptionsFor more information about these
sequences, refer to Configuration Entry Points in the Sequential
Process Model section of this appendix.

A-19

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Model Callbacks
The following sequences are Model callbacks in the Parallel process model,
which you can override with a client sequence file:

NI TestStand Reference Manual

MainSequenceThe Test UUTs Test Socket Entry Point and


Single Pass Test Socket Entry Point sequences call this callback to
test a UUT. The client sequence file must contain a MainSequence
callback that performs the tests on a UUT. The MainSequence callback
is empty in the process model file.

PreUUTCalls into the modeless dialog box that the controlling


execution creates, which the operator uses to enter UUT serial
numbers for the test sockets. The Test UUTs Test Socket Entry Point
sequence calls the PreUUT callback at the beginning of each iteration
of the UUT loop. If the operator indicates through the dialog box that
no more UUTs are available for testing, the UUT loop terminates.
If the operator chooses to stop testing, the code for the dialog box sets
the TestSocket.ContinueTesting parameter to False. If the operator
enters a serial number, the code for the dialog box stores the serial
number in the TestSocket.UUT.SerialNumber parameter.

PostUUTCalls into the modeless dialog box that the controlling


execution creates to tell it to display a banner indicating the result of
the test that the MainSequence callback in the client sequence file
performs on the UUT. The Test UUTs Test Socket Entry Point
sequence calls the PostUUT callback at the end of each iteration of the
UUT loop.

PreUUTLoopThe Test UUTs Test Socket Entry Point sequence


calls this callback before the UUT loop begins. The PreUUTLoop
callback in the process model file is empty.

PostUUTLoopThe Test UUTs Test Socket Entry Point sequence


calls this callback after the UUT loop terminates. The PostUUTLoop
callback in the process model file is empty.

ReportOptions, DatabaseOptions, ModelOptions, TestReport,


ModifyReportHeader, ModifyReportEntry, ModifyReportFooter,
and LogToDatabaseFor more information about these sequences,
refer to Model Callbacks in the Sequential Process Model section of
this appendix.

Process SetupThe Test UUTs and Single Pass entry points call this
callback from the Setup step group to give the client sequence file an
opportunity to execute any setup steps that must run only once during
the execution of the process model. These setup steps are only run from
the controlling execution. The test socket executions do not call this
callback.

A-20

ni.com

Appendix A

Process Model Architecture

Process CleanupThe Test UUTs and Single Pass entry points call
this callback from the Cleanup step group to give the client sequence
file an opportunity to execute any cleanup steps that must run only
once during the execution of the process model. These cleanup steps
are only run from the controlling execution. The test socket executions
do not call this callback.

Utility Subsequences
The following sequences are Utility subsequences in the Parallel process
model, which are called by the other sequences in the Parallel process
model:

Get Station Info, Get Report Options, Get Database Options, and
Get Model OptionsFor more information about these sequences,
refer to Utility Subsequences in the Sequential Process Model section
of this appendix.

Engine Callbacks
The following callbacks are Engine callbacks that are in the Parallel
process model:

ProcessModelPostResultListEntryThe process model enables this


callback if you enable the On-The-Fly Reporting option of the Report
Options dialog box or if you enable the On-The-Fly Logging option of
the Database Options dialog box. TestStand calls the Engine callback
after each step that tests a UUT and generates a step result.

SequenceFilePostResultListEntryThe process model enables this


callback if you enable the On-The-Fly Reporting option of the Report
Options dialog box or if you enable the On-The-Fly Logging option of
the Database Options dialog box. TestStand calls this Engine callback
after any step in the process model generates a step result. The
MainSequence model callback steps in the process model sequences
are the only steps that enable the generation of step results.

National Instruments Corporation

A-21

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Test UUTs
The Test UUTs entry point is the sequence that the controlling execution
runs. Table A-4 lists the most significant steps of the Test UUTs entry point
in the order that they are performed.
Table A-4. Order of Actions the Parallel Process Model Test UUTs Entry Point Performs

Action
Number

Description

Remarks

Call ProcessSetup callback

The default callback is empty.

Call Get Model Options Utility


subsequence.

Reads model options from disk. Calls the


ModelOptions callback to give the client
sequence file an opportunity to modify the
model options.

Call Get Station Info Utility


subsequence.

Identifies the test station name and the


current user.

Call Get Report Options Utility


subsequence.

Reads report options from disk. Calls the


ReportOptions callback to give the client
sequence file an opportunity to modify the
report options.

Call Get Database Options Utility


subsequence.

Reads database options from disk. Calls the


DatabaseOptions callback to give the client
sequence file an opportunity to modify the
database options.

Call Run UUT Info Dialog Utility


subsequence.

Creates a modeless dialog box that displays


information and gathers serial numbers for
the test socket executions.

Determine the report file pathname.

Determines the report file pathname to use


if the report options are configured so that
all UUT results for the model are written to
the same file.

Create and initialize test socket


executions.

For more information about the


Test UUTs Test Socket Entry Point
sequence and what test executions do, refer
to Table A-5.

Call ProcessDialogRequests.

Waits for dialog box requests in a loop until


the model is ready to be shut down.

10

Call ProcessCleanup callback.

The default callback is empty.

NI TestStand Reference Manual

A-22

ni.com

Appendix A

Process Model Architecture

Test UUTs Test Socket Entry Point


The Test UUTs Test Socket entry point is the sequence that the test socket
executions run. The controlling execution creates the test socket executions
in the Test UUTs entry point sequence. Table A-5 lists the most significant
steps of the Test UUTs Test Socket entry point in the order that they are
performed.
Table A-5. Order of Actions the Parallel Process Model Test UUTs Test Socket Entry Point Performs

Action
Number

Description

Remarks

Call PreUUTLoop callback.

Callback in the process model file is empty.

Call Configure Post Result Callbacks


Utility subsequence

Enable ProcessModelPostResultListEntry
and SequenceFilePostResultListEntry
callbacks if on-the-fly report generation
or database logging is enabled.

Increment the UUT index.

Clear information from previous loop


iteration.

Discards the previous results and clears the


report and failure stacks.

Call PreUUT callback.

Obtains the UUT serial number from the


operator.

If no more UUTs, go to
Action Number 14.

Setup report.

Determine the report file pathname, setup


display settings, reset the report, and set the
report location.

Call MainSequence callback.

MainSequence callback in the client


sequence file performs the tests on the UUT.

Call PostUUT callback.

Tells the modeless dialog box that the


controlling execution creates to display a
pass, fail, error, or terminate banner for this
test socket.

10

Call TestReport callback.

Generates a test report for the UUT, if


on-the-fly report generation is enabled.

11

Call LogToDatabase callback.

Logs test results to a database for the UUT.

National Instruments Corporation

A-23

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-5. Order of Actions the Parallel Process Model Test UUTs Test Socket Entry Point Performs (Continued)

Action
Number

Description

12

Write the UUT report to disk.

13

Loop back to Action Number 3.

14

Call PostUUTLoop callback.

Remarks
Appends to an existing file or creates a
new file.Also adjusts the root tags if the
report format is XML.

Callback in the process model file is empty.

Single Pass
The Single Pass entry point is the sequence that the controlling execution
runs. Table A-6 lists the most significant steps of the Single Pass entry point
in the order that they are performed.
Table A-6. Order of Actions the Parallel Process Model Single Pass Entry Point Performs

Action
Number

Description

Remarks

Call ProcessSetup callback.

The default callback is empty.

Call Get Model Options Utility


subsequence.

Reads model options from disk. Calls the


ModelOptions callback to give the client
sequence file an opportunity to modify the
model options.

Call Get Station Info Utility


subsequence.

Identifies the test station name and the


current user.

Call Get Report Options Utility


subsequence.

Reads report options from disk. Calls the


ReportOptions callback to give the client
sequence file an opportunity to modify the
report options.

Call Get Database Options Utility


subsequence.

Reads database options from disk. Calls the


DatabaseOptions callback to give the client
sequence file an opportunity to modify the
database options.

Determine the report file pathname.

Determines the report file pathname to use


if the report options are configured so that
all UUT results for the model are written to
the same file.

NI TestStand Reference Manual

A-24

ni.com

Appendix A

Process Model Architecture

Table A-6. Order of Actions the Parallel Process Model Single Pass Entry Point Performs (Continued)

Action
Number

Description

Create and initialize test socket


executions.

Wait for test socket executions to


complete.

Call ProcessCleanup callback.

Remarks
For more information about the
Single Pass Test Socket Entry Point
sequence and what test executions do, refer
to Table A-7.

The default callback is empty.

Single Pass Test Socket Entry Point


The Single Pass Test Socket entry point is the sequence that the test
socket executions run. The controlling execution creates the test socket
executions in the Single Pass entry point sequence. Table A-7 lists the most
significant steps of the Single Pass Test Socket entry point in the order
that they are performed.
Table A-7. Order of Actions the Parallel Process Model Single Pass Test Socket Entry Point Performs

Action
Number

Description

Remarks

Call Configure Post Result Callbacks


Utility subsequence.

Enables ProcessModelPostResultListEntry
and SequenceFilePostResultLIstEntry
callbacks if on-the-fly report generation and
database logging if enabled.

Setup report.

Determines the report file pathname, setup


the display settings, reset the report, and set
the report location.

New UUT for report generation and


database logging.

Starts on-the-fly report generation and


database logging, if enabled.

Call MainSequence callback.

MainSequence callback in the client


sequence file performs the tests on the UUT.

Call TestReport callback.

Generates a test report for the UUT, if


on-the-fly report generation is disabled.

National Instruments Corporation

A-25

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-7. Order of Actions the Parallel Process Model Single Pass Test Socket Entry Point Performs

Action
Number

Description

Remarks

Call LogToDatabase callback.

Logs test results to a database for the UUT.

Write the UUT report to disk.

Appends to an existing file or creates a


new file.Also adjusts the root tags if the
report format is XML.

Batch Process Model


Sequences
Figure A-4 shows a list of all the sequences found in the Batch process
model, BatchModel.seq. These sequences are divided into the following
categories: main Execution entry points, Utility sequences, hidden
Execution entry points, Configuration entry points, Model callbacks,
Utility subsequences, and Engine callbacks.

NI TestStand Reference Manual

A-26

ni.com

Appendix A

Process Model Architecture

7
3
4

5
8

1
2
3

Main Execution Entry Points


Utility Sequences
Hidden Execution Entry Points

4
5
6

Utility Sequence
Configuration Entry Points
Model Callbacks

7
8
9

Utility Subsequences
Model Callbacks
Engine Callbacks

Figure A-4. Sequences in the Batch Process Model

National Instruments Corporation

A-27

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Main Execution Entry Points


The following sequences are the main Execution entry points in the Batch
process model:

Test UUTsRuns in the controlling execution of the process model.


TestUUTs creates a separate execution for each test socket using the
Test UUTs Test Socket Entry Point sequence, adds the main threads
of those executions to a Batch Synchronization object, and controls the
flow of execution using queues and notifications so that all test socket
executions execute the Main sequence of the client sequence file
together as a group. After a group of UUTs executes, this sequence
generates a batch report, loops back around to run the client sequence
file on the next group of UUTs, and controls the subsidiary test socket
executions to keep them synchronized. When a window for a client
sequence file is active, the Test UUTs item is listed in the Execute
menu. For more information about the Test UUTs entry point, refer to
Test UUTs in the Batch Process Model section of this appendix.

Single PassRuns in the controlling execution of the process model.


Singe Pass creates a separate execution for each test socket using the
Single PassTest Socket Entry Point sequence, adds the main threads
of those executions to a Batch Synchronization object, and controls the
flow of execution using queues and notifications so that all test socket
executions execute the Main sequence of the client sequence file
together as a group. After the group of UUTs executes, this sequence
generates a batch report and waits for all subsidiary executions to
complete. When a window for a client sequence file is active, the
Single Pass item is listed in the Execute menu. For more information
about the Single Pass entry point, refer to Single Pass in the Batch
Process Model section of this appendix.

Utility Sequences
The following Utility sequences are used by the main Execution entry
points in the Batch process model:

NI TestStand Reference Manual

Restart TestSocketDialog box request callback that the


ProcessDialogRequests sequence calls. This callback restarts
the execution for the test socket that the request specifies.

Initialize TestSocketCalled by the controlling execution, initializes


the data for and creates the test socket executions.

Monitor Batch ThreadsProcessDialogRequests,


ProcessTestSocketRequests, and WaitForTestSocket call this sequence
periodically from the controlling execution to poll whether any of the
test socket executions have been terminated or aborted. If any have,

A-28

ni.com

Appendix A

Process Model Architecture

Monitor Batch Threads updates the ModelData parameter for that test
socket to indicate its new state and tells the dialog box to update its
display for that test socket.

Tile Execution WindowsCalled by the controlling execution, tiles


the test socket Execution windows by building a list of executions and
posting a UIMessage to the user interface, requesting that the user
interface tile the Execution windows. This sequence only tiles running,
non-disabled test socket executions.

Add TestSocket Threads to BatchThe Test UUTs and Single Pass


entry points call this sequence from the controlling execution to add
the main threads of the test socket executions to a Batch
Synchronization object. The threads remove themselves from the
batch after running the Main sequence of the client sequence file.
Removal from the batch is done in the Test UUTs Test Socket Entry
Point and the Single Pass Test Socket Entry Point sequences.

Notify TestSocket ThreadsThe controlling execution calls this


sequence to tell the running test socket execution threads to continue
executing from their last call to SendControllerRequest in which they
block. This sequence optionally waits for each test socket to get to its
next callSendControllerRequest, which is the next synchronization
pointbefore telling the next test socket to go. This ensures serial
execution of the test socket executions for the sections of their
sequences following the location at which they currently block.

All TestSockets Waiting?Returns True if all running test sockets


are waiting for the WaitingForRequest parameter or if all test sockets
are stopped.

ProcessTestSocketRequestsThe controlling execution calls this


sequence to wait for the test socket executions to synchronize at the
appropriate point in the execution. When all running test sockets are
at the appropriate point in their executions, the sequence returns,
allowing the controlling execution to continue. While waiting for the
test sockets, this sequence monitors the test socket threads to make
sure they are still running. If all test sockets stop running, this sequence
will return to allow the controlling sequence to continue.

WaitForTestSocketThe controlling execution calls this sequence


from the Notify TestSocket Threads sequence to wait for a test
socket execution to receive its next controller request, such as a
synchronization point, before the next test socket execution continues.
This guarantees that the controlling execution allows only one test
socket to run particular sections of its sequence at a time. This

National Instruments Corporation

A-29

NI TestStand Reference Manual

Appendix A

Process Model Architecture

sequence is used to write the test socket reports to a file in test socket
index order when the configuration of report options specifies that they
are to write reports to the same file.

NI TestStand Reference Manual

ProcessDialogRequestsCalled by the controlling execution from


the Test UUTs sequence. ProcessDialogRequest loops while waiting
for requests that the dialog box enqueues into the
ModelData.DialogRequestQueue. These requests are the names of the
sequences to call. When the ProcessDialogRequests sequence receives
a request, it calls the requested sequence. Additionally, this sequence
periodically calls the Monitor Batch Threads sequence to make sure
that the test socket executions are still running and to update
information about them if they are not.

Run Batch Info DialogThe controlling execution calls this


sequence from a new thread in the Test UUTs entry point. The Run
Batch Info Dialog sequence initializes and runs the dialog box that
allows you to enter serial numbers and view the results for a particular
run of the batch.

View TestSocket ReportDialog box request callback that the


ProcessDialogRequests sequence calls. The View TestSocket Report
sequence launches a report viewer on the report file for the test socket
that the request specifies.

View TestSocket Report Current OnlyDialog box request


callback that the ProcessDialogRequests sequence calls. This
sequence launches a report viewer for the last report generated for
the test socket that the request specifies. The View TestSocket
Report Current Only sequence differs from the View TestSocket
Report sequence in that it shows only the last report rather than the
whole report file.

View Batch ReportDialog box request callback that the


ProcessDialogRequests sequence calls. This sequence launches
a report viewer on the report file for the batch report.

View Batch Report Current OnlyDialog box request callback


that the ProcessDialogRequests sequence calls. This callback launches
a report viewer for the last batch report generated. The View Batch
Report Current Only sequence differs from the View Batch Report
sequence in that it shows only the last report rather than the whole
batch report file.

A-30

ni.com

Appendix A

Process Model Architecture

Hidden Execution Entry Points


The following hidden Execution entry points in the Batch process model
are used by the main Execution entry points to start the test socket
executions. The hidden Execution entry points are never displayed.

Test UUTs Test Socket Entry PointThe controlling execution


uses the entry point to create the test socket executions. If you insert a
step into this sequence, disable the Record Results option for the step.
This sequence implements the Test UUTs entry point for the test
socket executions. For more information about this entry point, refer to
Test UUTs Test Socket Entry Point in the Batch Process Model
section of this appendix.

Single Pass Test Socket Entry PointThe controlling execution


uses the entry point to create the test socket executions. If you insert a
step into this sequence, disable the Record Results option for the step.
This sequence implements the Single Pass entry point for the test
socket executions. For more information about this entry point, refer to
Single Pass Test Socket Entry Point in the Batch Process Model
section of this appendix.

Utility Sequence
This Utility sequence in the Batch process model is used by the hidden test
socket Execution entry points:

SendControllerRequestThe test socket executions call this


sequence to synchronize the controlling execution at various locations
in their sequences. The test socket executions pass string parameters
that indicate the reason and location at which they are attempting to
synchronize with the other executions. When all of the test socket
executions that are running synchronize with the controlling sequence
at the same location by calling the SendControllerRequest sequence,
the controlling executions sequence then performs operations and tells
the test socket execution when to continue.

Configuration Entry Points


The following sequences in the Batch process model are the Configuration
entry points in the Batch process model:

National Instruments Corporation

Configure Report Options, Configure Database Options, and


Configure Model OptionsFor more information about these
sequences, refer to Configuration Entry Points in the Sequential
Process Model section of this appendix.

A-31

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Model Callbacks
The following sequences in the Batch process model are Model callbacks,
which you can use to override in a client sequence file:

NI TestStand Reference Manual

MainSequenceThe Test UUTs Test Socket Entry Point and


Single Pass Test Socket Entry Point sequences call this callback to
test a UUT. The client sequence file must contain a MainSequence
callback that performs the tests on a UUT. The MainSequence callback
is empty in the process model file.

PreUUTThe test socket executions call this callback. The


implementation of this sequence is empty in the Batch process model.
You can override this callback in the client sequence file to get the
serial number for the UUT. If you choose to do this, you should also
override the PreBatch callback. In the Batch model, the PreBatch
callback displays a dialog box to get the serial numbers for all of the
UUTs in the batch. You can find an example illustrating how to
override these callbacks in the <TestStand>\Examples\
ProcessModels\BatchModel directory.

PostUUTThe test socket executions call this callback. The


implementation of this sequence is empty in the Batch process model.
You can override this callback in the client sequence file to display the
result status for a UUT. If you choose to do this, you should also
override the PostBatch callback. In the Batch model, the PostBatch
callback displays a dialog box to show the result status for all of the
UUTs in the batch. You can find an example illustrating how to
override these callbacks in the <TestStand>\Examples\
ProcessModels\BatchModel directory.

PreUUTLoopThe Test UUTs Test Socket Entry Point sequence


calls this callback before the UUT loop begins. The PreUUTLoop
callback in the process model file is empty.

PostUUTLoopThe Test UUTs Test Socket Entry Point sequence


calls this callback after the UUT loop terminates. The PostUUTLoop
callback in the process model file is empty.

ReportOptions, DatabaseOptions, ModelOptions, TestReport,


ModifyReportHeader, ModifyReportEntry,
ModifyReportFooter, and LogToDatabaseFor more information
about these sequences, refer to Model Callbacks in the Sequential
Process Model section of this appendix.

Process SetupThe Test UUTs and Single Pass entry points call this
callback from the Setup step group to give the client sequence file an
opportunity to execute any setup steps that must run only once during

A-32

ni.com

Appendix A

Process Model Architecture

the execution of the process model. These setup steps are run from the
controlling execution only. The test socket executions do not call this
callback.

Process CleanupThe Test UUTs and Single Pass entry points call
this callback from the Cleanup step groups to give the client sequence
file an opportunity to execute any cleanup steps that must run only
once during the execution of the process model. These cleanup steps
are run from the controlling execution only. The test socket executions
do not call this callback.

Utility Subsequences
The following Utility subsequences in the Batch process model are called
by other sequences within the Batch process model:

Get Station Info, Get Report Options, Get Database Options, and
Get Model OptionsFor more information about these sequences,
refer to Utility Subsequences in the Sequential Process Model section
of this appendix.

Model Callbacks
The following sequences are Model callbacks in the Batch process model
that are unique to the model and called by the main Execution entry points:

PreBatchDisplays a dialog box in which the operator enters the


batch and UUT serial numbers. You can override this in the client
sequence file to change or replace this action. You can find an example
illustrating how to override this callback in the <TestStand>\
Examples\ProcessModels\BatchModel directory.

PostBatchDisplays a pass, fail, error, or terminated banner for each


test socket and allows viewing of batch and UUT reports. You can
override this callback in the client sequence file to change or replace
this action. You can find an example illustrating how to override this
callback in the <TestStand>\Examples\ProcessModels\
BatchModel directory.

PreBatchLoopThe process model calls this callback before looping


on a batch of UUTs. This callback is empty in the process model file.
You can override this callback in the client sequence file to perform an
action before the batch is tested.

PostBatchLoopThe process model calls this callback after looping


on a batch of UUTs. This callback is empty in the process model file.
Override this callback in the client sequence file to perform an action
after all batches of UUTs are tested.

National Instruments Corporation

A-33

NI TestStand Reference Manual

Appendix A

Process Model Architecture

BatchReportThe Test UUTs and Single Pass entry points call this
callback to generate the contents of the batch report for the UUTs that
ran in the last batch. You can override the BatchReport callback in the
client sequence file if you want to change its behavior entirely. The
Batch process model defines a batch report for a single group of UUTs
as a header, an entry for each UUT result, and a footer. If you do not
override the BatchReport callback, you can override the
ModifyBatchReportHeader, ModifyBatchReportEntry, and
ModifyBatchReportFooter callbacks to customize the batch report.

ModifyBatchReportHeaderThe BatchReport callback calls this


callback so that the client sequence file can modify the batch report
header. ModifyBatchReportHeader receives the following parameters:
the batch serial number, the tentative report header text, and the report
options. The ModifyBatchReportHeader callback in the process model
file is empty.

ModifyBatchReportEntryThe BatchReport callback calls this


callback so that the client sequence file can modify the entry for each
test sockets UUT result in the batch report. Using subsequences, the
BatchReport callback calls the ModifyBatchReportEntry callback for
each test socket. The ModifyBatchReportEntry callback receives the
following parameters: the test socket data, the tentative report entry
text, and the report options. The ModifyBatchReportEntry callback in
the process model file is empty.

ModifyBatchReportFooterThe BatchReport callback calls this


callback so that the client sequence file can modify the batch report
footer. The ModifyBatchReportFooter callback receives the following
parameters: the tentative report footer text and the report options. The
ModifyBatchReportFooter callback in the process model file is empty.

Engine Callbacks
The following callbacks are Engine callbacks that are in the Batch process
model:

NI TestStand Reference Manual

ProcessModelPostResultListEntryThe process model enables this


callback if you enable the On-The-Fly Reporting option of the Report
Options dialog box or if you enable the On-The-Fly Logging option of
the Database Options dialog box. TestStand calls the Engine callback
after each step that tests a UUT and generates a step result.

SequenceFilePostResultListEntryThe process model enables this


callback if you enable the On-The-Fly Reporting option of the Report
Options dialog box or if you enable the On-The-Fly Logging option of
the Database Options dialog box. TestStand calls this Engine callback

A-34

ni.com

Appendix A

Process Model Architecture

after any step in the process model generates a step result. The
MainSequence model callback steps in the process model sequences
are the only steps that enable the generation of step results.

Test UUTs
The Test UUTs entry point is the sequence that the controlling execution
runs. Table A-8 lists the most significant steps of the Test UUTs entry point
in the order that they are performed.
Table A-8. Order of Actions the Batch Process Model Test UUTs Entry Point Performs

Action
Number

Description

Remarks

Call ProcessSetup callback.

The default callback is empty.

Call Get Model Options Utility


subsequence.

Reads model options from disk. Calls the


ModelOptions callback to give the client
sequence file an opportunity to modify the
model options.

Call PreBatchLoop callback.

Callback in the process model file is empty.

Call Get Station Info Utility


subsequence.

Identifies the test station name and the


current user.

Call Get Report Options Utility


subsequence.

Reads report options from disk. Calls the


ReportOptions callback to give the client
sequence file an opportunity to modify the
report options.

Call Get Database Options Utility


subsequence.

Reads database options from disk. Calls the


DatabaseOptions model callback to give
the client sequence file an opportunity to
modify the database options.

Create and initialize test socket


executions.

For more information about the


Test UUTs Test Socket Entry Point
sequence and what test executions do,
refer to Table A-9.

Call Run Batch Info Dialog.

Calls the Run Batch Info Dialog sequence


in a new thread and waits for it to initialize
the dialog box code.

National Instruments Corporation

A-35

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-8. Order of Actions the Batch Process Model Test UUTs Entry Point Performs (Continued)

Action
Number

Description

Remarks

Wait for test sockets to get to the


Initialize synchronization point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

10

Call Add TestSocket Threads to Batch.

Adds test socket execution threads to the


Batch Synchronization object. This allows
the users test sequence to use batch
synchronization.

11

Allow test socket executions that are


waiting at the Initialize
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence.

12

Increment the Batch index.

13

Wait for test sockets to get to


the GetUUTSerialNumber
synchronization point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

14

Call PreBatch callback.

Obtains the batch and UUT serial numbers


from the operator.

15

If no more UUTs, set test socket data


to tell test sockets to stop running their
UUT loops.

Sets the ContinueTesting test socket data


variable to False for all of the test sockets
and marks them all as enabled so that they
will be added to the batch and exit normally.

16

Remove disabled test socket threads


from the batch and add enabled test
socket threads.

Disabled test sockets need to be removed


from the batch so that they do not block the
threads that are running.

17

Allow test socket executions that are


waiting at the GetUUTSerialNumber
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence.

18

If no more UUTs, go to
Action Number 35.

19

Wait for test sockets to get to the


ReadyToRun synchronization point.

NI TestStand Reference Manual

A-36

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

ni.com

Appendix A

Process Model Architecture

Table A-8. Order of Actions the Batch Process Model Test UUTs Entry Point Performs (Continued)

Action
Number

Description

Remarks

20

Determine the report file pathname for


Batch and UUT report files.

Determines the report file pathname to use


if the report options are configured so that
all UUT results for the model are written to
the same file or are written to the same file
as the batch reports.

21

Allow test socket executions that


are waiting at the ReadyToRun
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence.

22

Wait for test sockets to get to the


ShowStatus synchronization point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

23

Call Add TestSocket Threads to Batch.

The test socket executions remove


themselves from the batch after executing
MainSequence in order to cleanup the state
of the batch in case the sequence was
terminated or the user did not match enters
and exits properly. This is where the test
socket execution threads are added to the
batch again.

24

Call PostBatch callback.

Displays a pass, fail, error, or terminate


banner for all of the test sockets in the batch.

25

Allow test socket executions that


are waiting at the ShowStatus
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence.

26

Wait for test sockets to get to the


WriteReport synchronization point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

27

Call BatchReport callback.

Generates a batch report for the last run of


the batch of UUTs.

28

Write the batch report to disk.

Appends to an existing file or creates a new


file.

National Instruments Corporation

A-37

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-8. Order of Actions the Batch Process Model Test UUTs Entry Point Performs (Continued)

Action
Number

Description

Remarks

29

Allow test socket executions that


are waiting at the WriteReport
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence passing True for the
ReleaseThreadsSequentially parameter so
that only one UUT report is written at a time
in the test socket index order.

30

Wait for test sockets to get to the


UUTDone synchronization point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

31

Tell the Status dialog box that report


generation is complete.

Enables the View Report button so that you


can view the reports from the dialog box.

32

Wait for Status dialog box.

If the PostBatch callback Status dialog box


displays the PostBatch callback, then the
sequence waits for you to dismiss the dialog
box, if you have not already done so.

33

Allow test socket executions that


are waiting at the UUTDone
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence.

34

Loop back to Action Number 12.

35

Wait for test socket executions to


complete.

36

Call PostBatchLoop callback.

Callback in the process model file is empty.

37

Call ProcessCleanup callback.

The default callback is empty.

Test UUTs Test Socket Entry Point


The Test UUTs Test Socket entry point is the sequence that the test socket
executions run. The controlling execution creates the test socket executions
in the Test UUTs entry point sequence. Table A-9 lists the most significant
steps of the Test UUTs Test Socket entry point in the order that they are
performed.

NI TestStand Reference Manual

A-38

ni.com

Appendix A

Process Model Architecture

Table A-9. Order of Actions the Batch Process Model Test UUTs Test Socket Entry Point Performs

Action
Number

Description

Remarks

Synchronize with the controlling


execution for the Initialize
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
sockets notification.

Call PreUUTLoop callback.

Callback in the process model file is empty.

Call Configure Post Result Callbacks


Utility subsequence.

Enables ProcessModelPostResultListEntry
and SequenceFilePostResultLIstEntry
callbacks if in-the-fly report generation
and database logging is enabled.

Increment the UUT index.

Clear information from previous loop


iteration.

Discards the previous results and clears the


report and failure stack.

Synchronize with the


controlling execution for
the GetUUTSerialNumber
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
sockets notification.

Call PreUUT callback.

Callback in the process model file is empty.

If no more UUTs, go to
Action Number 22.

Synchronize with the controlling


execution for the ReadyToRun
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
sockets notification.

10

Setup the report.

Determines the report file pathname, setup


the display settings, reset the report, and set
the report location.

11

New UUT for report generation and


database logging.

Starts on-the-fly report generation and


database logging, if enabled.

12

Call MainSequence callback.

MainSequence callback in the client


sequence file performs the tests on the UUT.

National Instruments Corporation

A-39

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-9. Order of Actions the Batch Process Model Test UUTs Test Socket Entry Point Performs (Continued)

Action
Number

Description

Remarks

13

Remove the test socket thread from


batch synchronization.

Cleans the state of the batch in case the


MainSequence was terminated or you did
not match enters and exits properly. The
controlling execution adds the thread to
batch synchronization before continuing
past the next synchronization point.
Disabled test sockets are not added to the
batch.

14

Synchronize with the controlling


execution for the ShowStatus
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
socket notification.

15

Call PostUUT callback.

Callback in the process model file is empty.

16

Call TestReport callback.

Generates a test report for the UUT, if


on-the-fly report generation is disabled.

17

Call LogToDatabase callback.

Logs test results to a database for the UUT.

18

Synchronize with controlling


execution for the WriteReport
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
socket notification.

19

Write the UUT report to disk.

Appends to an existing file or creates a


new file. Also adjusts the root tags if the
report format is XML.

20

Synchronize with controlling


execution for the UUTDone
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
socket notification.

21

Loop back to Action Number 4.

22

Call PostUUTLoop callback.

NI TestStand Reference Manual

Callback in the process model file is empty.

A-40

ni.com

Appendix A

Process Model Architecture

Single Pass
The Single Pass entry point is the sequence that the controlling execution
runs. Table A-10 lists the most significant steps of the Single Pass entry
point in the order that they are performed.
Table A-10. Order of Actions the Batch Process Model Single Pass Entry Point Performs

Action
Number

Description

Remarks

Call ProcessSetup callback.

The default callback is empty.

Call Get Model Options Utility


subsequence.

Reads model options from disk. Calls the


ModelOptions callback to give the client
sequence file an opportunity to modify the
model options.

Call Get Station Info Utility


subsequence.

Identifies the test station name and the


current user.

Call Get Report Options Utility


subsequence.

Reads report options from disk. Calls the


ReportOptions callback to give the client
sequence file an opportunity to modify the
report options.

Call Get Database Options Utility


subsequence.

Reads database options from disk. Calls the


DatabaseOptions callback to give the client
sequence file an opportunity to modify the
database options.

Create and initialize test socket


executions.

For more information about the


Single Pass Test Socket Entry Point
sequence and what test executions do,
refer to Table A-11.

Wait for test sockets to get to the


ReadyToRun synchronization point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

Call Add TestSocket Threads to Batch.

Adds test socket execution threads to the


batch Synchronization object. This allows
the test sequence to use batch
synchronization.

National Instruments Corporation

A-41

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-10. Order of Actions the Batch Process Model Single Pass Entry Point Performs (Continued)

Action
Number

Description

Remarks

Determine the report file pathname for


batch and UUT report files.

Determines the report file pathname to use


if the report options are configured so that
all UUT results for the model are written to
the same file or if they are written to the
same file as the batch reports.

10

Allow test socket executions that


are waiting at the ReadyToRun
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence.

11

Wait for test sockets to get to the


PostMainSequence synchronization
point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

12

Call Add TestSocket Threads to Batch.

The test socket executions remove


themselves from the batch after executing
MainSequence in order to clean up the state
of the batch in case the sequence was
terminated or you did not match enters and
exits properly. This is where the test socket
execution threads are added to the batch
again.

13

Allow test socket executions that are


waiting at the PostMainSequence
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence.

14

Wait for test sockets to get to the


WriteReport synchronization point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

15

Call BatchReport callback.

Generates a batch report for the last batch of


UUTs run.

16

Write the batch report to disk.

Appends to an existing file or creates a


new file.

17

Allow test socket executions that


are waiting at the WriteReport
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence passing True for the
ReleaseThreadsSequentially parameter so
that only one UUT report is written at a time
in test socket index order.

NI TestStand Reference Manual

A-42

ni.com

Appendix A

Process Model Architecture

Table A-10. Order of Actions the Batch Process Model Single Pass Entry Point Performs (Continued)

Action
Number

Description

Remarks

18

Wait for test sockets to get to the


UUTDone synchronization point.

Calls the ProcessTestSocketRequests


sequence to wait for and monitor test socket
executions.

19

Allow test socket executions that


are waiting at the UUTDone
synchronization point to continue.

Calls the Notify TestSocket Threads


sequence.

20

Wait for test socket executions to


complete.

21

Call ProcessCleanup callback.

The default callback is empty.

Single Pass Test Socket Entry Point


The Single Pass Test Socket entry point is the sequence that the test
socket executions run. The controlling execution creates the test socket
executions in the Single Pass entry point sequence. Table A-11 lists the
most significant steps of the Single Pass Test Socket entry point in the
order that they are performed.
Table A-11. Order of Actions the Batch Process Model Single Pass Test Socket Entry Point Performs

Action
Number

Description

Remarks

Call Configure Post Result Callback


Utility subsequence.

Enables ProcessModelPostResultLIstEntry
and SequenceFilePostResultListEntry
callbacks if on-the-fly report generation
and database logging is enabled.

Sync with controlling execution for the


ReadyToRun synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
sockets notification.

Setup the report.

Determines the report file pathname, setup


the display settings, reset the report, and set
the report location.

New UUT for report generation and


database logging.

Starts on-the-fly report generation and


database logging, if enabled.

National Instruments Corporation

A-43

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-11. Order of Actions the Batch Process Model Single Pass Test Socket Entry Point Performs (Continued)

Action
Number

Description

Remarks

Call MainSequence callback.

MainSequence callback in the client


sequence file performs the tests on the UUT.

Remove the test socket thread from


batch synchronization.

Allows other test socket threads to do batch


synchronization without counting this
thread anymore. The controlling execution
adds the thread to batch synchronization
before the thread runs the Main sequence
again. Disabled test sockets are not added to
the batch.

Synchronize with controlling


execution for the PostMainSequence
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
sockets notification.

Call TestReport callback.

Generates a test report for the UUT, if


on-the-fly report generation is disabled.

Call LogToDatabase callback.

Logs test results to a database for the UUT.

10

Synchronize with controlling


execution for the WriteReport
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
socket notification.

11

Write the UUT report to disk.

Appends to an existing file or creates a


new file. Adjusts the root tags if the report
format is XML.

12

Synchronize with controlling


execution for the UUTDone
synchronization point.

Calls SendControllerRequest and blocks


until the controlling execution sets the test
sockets notification.

Support Files for the TestStand Process Models


Many sequences in the TestStand process model files call functions in
DLLs and subsequences in other sequence files. TestStand installs these
supporting files and the DLL source files in the same directory that it
installs the process model sequence files.
Table A-12 lists the supporting files that TestStand installs for the
TestStand process models in the <TestStand>\Components\NI\
Models\TestStandModels directory.

NI TestStand Reference Manual

A-44

ni.com

Appendix A

Process Model Architecture

Table A-12. Installed Support Files for the Process Model Files

File Name

Description

ATMLsupport.dll

DLL containing C functions that the process model sequences


call to generate ATML reports.

ATMLSupport.lib

Import library for ATMLsupport.dll.

banners.c

C source for functions that display status banners.

SequentialModel.seq,
ParallelModel.seq, and
BatchModel.seq

Entry point and Model callback sequences for the TestStand


process models.

batchuutdlg.c and
paralleluutdlg.c

C source for the functions that launch the UUT identification


dialog boxes for the Batch and Parallel process models. The files
are part of modelsupport2.dll, but the default process model,
SequentialModel.seq, does not call them.

c_report.c

C source for generating HTML, XML, and ASCII-text reports for


the DLL option in the Report Options dialog box.

ColorselectPopup.c

C source for the functions that display a dialog box in which you
can select a color.

ColorselectPopup.h

C header file containing declarations for the function in


ColorselectPopup.c.

main.c

C source for utility functions.

ModelOptions.c

C source for the functions that launch the Model Options dialog
box and read and write the model options from disk.

modelpanels.h

C header file containing declarations for the panels in


modelpanels.uir.

modelpanels.uir

LabWindows/CVI user interface resource file containing panels


that the functions in modelsupport2.dll use.

modelsupport2.dll

DLL containing C functions that the process model sequences


call. Includes functions that launch the Report Options and Model
Options dialog boxes, read and write those options from disk,
determine the report file pathname, obtain the UUT serial number
from the operator, and display status banners.

modelsupport2.fp

LabWindows/CVI function panels for the functions in


modelsupport2.dll.

National Instruments Corporation

A-45

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-12. Installed Support Files for the Process Model Files (Continued)

File Name

Description

modelsupport2.h

C header file that contains declarations for the functions in


modelsupport2.dll.

modelsupport2.lib

Import library in Visual C/C++ format for


modelsupport2.dll.

modelsupport2.prj

LabWindows/CVI project that builds modelsupport2.dll.

ModelSupport.seq

Subsequences that all process models use for report generation.

PropertyObject.xsd

XML schema that defines the content of the XML that


PropertyObject.GetXML generates and PropertyObject.SetXML
requires. This schema is also used in XML reports as defined by
Report.xsd.

report.c

C source for functions that launch the Report Options dialog box,
read and write the report options from disk, and determine the
report file pathname.

report.h

C header file that contains declarations for the functions in


report.c.

Report.xsd

XML schema that defines the content of TestStand XML reports.

reportgen_atml.seq

Subsequences that add the header, result entries, and footer for a
UUT into an ATML test report.

reportgen_html.seq

Subsequences that add the header, result entries, and footer for a
UUT into an HTML test report.

reportgen_txt.seq

Subsequences that add the header, result entries, and footer for a
UUT into an ASCII-text test report.

reportgen_xml.seq

Subsequences that add the header, result entries, and footer for a
UUT into an XML test report.

uutdlg.c

C source for the function that obtains the UUT serial number
from the operator.
You can view the contents of the reportgen_atml.seq,
reportgen_html.seq, reportgen_txt.seq, and
reportgen_xml.seq sequence files in the sequence editor. These files
are model sequence files and contain an empty ModifyReportEntry
callback. Each file has a PutOneResultInReport sequence that calls
ModifyReportEntry. The client sequence file can override the
ModifyReportEntry callback. TestStand requires that all sequence files

NI TestStand Reference Manual

A-46

ni.com

Appendix A

Process Model Architecture

that contain direct calls to Model callbacks must also contain a definition
of the callback sequence and must be model files.
The TestStand process model sequence files also contain an empty
ModifyReportEntry callback, even though no sequences in those files call
ModifyReportEntry directly. They contain a ModifyReportEntry callback
so that ModifyReportEntry appears in the Sequence File Callbacks dialog
box for the client sequence file.

Report Generation Functions and Sequences


When you customize report generation for your test station, create your
own process model, or modify the default TestStand process model files,
always copy the default process model files to the <TestStand>\
Components\User directory and then make your modifications to that
copy. This practice ensures that newer installations of the same version of
TestStand will not overwrite your customizations, or that uninstalling
TestStand does not remove the files you customize.
Tables A-13 and A-14 list the process model sequences and C functions
that generate the report and the locations of the files that contain
them. Table A-13 lists the default process model sequences in the
<TestStand>\Components\NI\Models\TestStandModels directory
that generate the report header and footer.
Table A-13. Sequences that Generate the Report Header and Footer

Report Header or Footer


Report Format

Header

Footer

ATML

The header is generated when the


Report Body is generated.

The footer is generated when the


Report Body is generated.

HTML

AddReportHeader sequence in

AddReportFooter sequence in

reportgen_html.seq

reportgen_html.seq

AddReportHeader sequence in

AddReportFooter sequence in

reportgen_txt.seq

reportgen_txt.seq

AddReportHeader sequence in

AddReportFooter sequence in

reportgen_xml.seq

reportgen_xml.seq

Text
XML

National Instruments Corporation

A-47

NI TestStand Reference Manual

Appendix A

Process Model Architecture

Table A-14 lists the default process model sequences and C functions in
<TestStand>\Components\NI\Models\TestStandModels that
generate the report body for each step result.
Table A-14. Sequences or C Functions that Generate the Report Body

Report Body Generator Selected in the Report Options Dialog Box


Report Format
ATML

Sequence

DLL

Not supported

Get_Atml_Report function in
ATML_Report.c in the
ATMLSupport.prj

LabWindows/CVI project.
HTML

PutOneResultInReport sequence in
reportgen_html.seq

PutOneResultInReport_Html
function in c_report.c in the
modelsupport2.prj

LabWindows/CVI project.
Text

PutOneResultInReport sequence in
reportgen_txt.seq

PutOneResultInReport_Txt function
in c_report.c in the
modelsupport2.prj

LabWindows/CVI project.
XML

AddReportBody sequence in
reportgen_xml.seq

AddSequenceCallResult_XML
function in the
modelsupport2.prj

LabWindows/CVI project.

NI TestStand Reference Manual

A-48

ni.com

Appendix A

Process Model Architecture

You can also alter the report generation for each client sequence file that
you run. To alter report generation, you override the report generation
Model callbacks in the client sequence file. Table A-15 lists the report
generation Model callbacks.
Table A-15. Report Generation Model Callbacks

Section of the Report to Alter

Model Callback Sequence to Override

Report Header

ModifyReportHeader

Report Footer

ModifyReportFooter

Each Step Result

ModifyReportEntry
(TestStand does not call this callback if you select DLL in the
Select a Report Generator for Producing the Report Body section
of the Contents tab on the Report Options dialog box.)

Entire Report

TestReport
In addition, each step in the sequence can add text to its corresponding
result in the report. To make these additions, the step stores the text to add
to the report in its Step.Result.ReportText property.

National Instruments Corporation

A-49

NI TestStand Reference Manual

Synchronization Step Types

This appendix describes step types that you use to synchronize, pass data
between, and perform other operations in multiple threads of an execution,
multiple running executions in the same process, or executions running in
different processes or on separate machines.
To configure these steps, right-click the step and select Configure
<step type> from the context menu, or click the Configure <step type>
button on the edit tab of the Step Settings pane of the sequence editor. You
do not write code modules for these steps.
For more information about the Configuration dialog boxes for
Synchronization step types, refer to the NI TestStand Help. You can
view examples for Synchronization step types in the <TestStand>\
Examples\Synchronization directory.

Synchronization Objects
Most Synchronization step types create and control a particular type of
Synchronization object. Following is a list of the types of Synchronization
objects:

LockUse a Lock object to guarantee exclusive access to a resource.


For example, if several execution threads write to a device that does not
have a thread-safe driver, you can use a Lock object to make sure that
only one thread accesses the device at a time.

RendezvousUse a Rendezvous object to make a specific number of


threads wait for each other before they proceed past a location you
specify. For example, if different threads configure different aspects of
a testing environment, you can use a Rendezvous object to ensure that
none of the threads proceed beyond the configuration process until all
threads have completed their configuration tasks.

QueueUse a Queue object to pass data from the thread that produces
it to a thread that processes it. For example, a thread that performs tests
asynchronously with respect to the Main sequence might use a queue
to receive commands from the Main sequence.

National Instruments Corporation

B-1

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

NotificationUse a Notification object to notify one or more threads


when a particular event or condition occurs. For example, if you
display a dialog box in a separate thread, you can use a Notification
object to signal another thread when the user dismisses the dialog box.

BatchUse a Batch object to define and synchronize a group of


threads. This is useful when you want to test a group of similar UUTs
simultaneously. You can configure a synchronized section so that only
one UUT enters the section at a time, no UUTs enter the section until
all are ready, and no UUTs proceed beyond the section until all are
done. This is useful when, for a particular test, you have only one
test resource that you must apply to each UUT in turn. You can also
configure a synchronized section to guarantee that only one thread
executes the steps in the section. This is useful for an action that
applies to the entire batch, such as raising the temperature in an
environmental chamber. Having a separate thread for each UUT
allows you to exploit parallelism while enforcing serialization when
necessary. It also allows you to use preconditions and other branching
options so that each UUT has its own flow of execution.
Normally, you are not required to create a Batch object. The TestStand
Batch process model does this for you. The model uses Batch
Specification steps to group test socket execution threads together so
that you can use Batch Synchronization steps to synchronize them in
your sequence file. If you want to create a synchronized section around
a single step, use the Synchronization panel on the Properties tab of the
Step Settings pane instead of using explicit Batch Synchronization
steps.
For more information about the Batch process model, refer to the
Batch Process Model section of Appendix A, Process Model
Architecture. For more information about Batch Synchronization,
refer to the Batch Synchronization section of this appendix. For more
information about the Synchronization panel on the Properties tab of
the Step Settings pane, refer to the NI TestStand Help.

NI TestStand Reference Manual

SemaphoreUse a Semaphore object to limit access to a resource to


a specific number of threads. A Semaphore object is similar to a Lock
object, except that it restricts access to the number of threads that you
specify rather than to just one thread. For example, you can use a
Semaphore object to restrict access to a communications channel to a
limited number of threads so that each thread has sufficient bandwidth.
Typically, you limit access to a shared resource to only one thread at a
time. Therefore, a typical application uses Lock objects rather than
Semaphore objects.

B-2

ni.com

Appendix B

Synchronization Step Types

Common Attributes of Synchronization Objects


You can use the <Step Type> Step Configuration dialog box for each step
type to configure the following common settings for all Synchronization
objects.

Name
When you create a Synchronization object, you can specify a unique name
with a literal string or an expression that evaluates to a string. If an object
with the same name and type already exists, you create a reference to the
existing object. Otherwise, you create a reference to a new Synchronization
object. By creating a reference to an existing object, you can access the
same Synchronization object from multiple threads or executions.
If you specify an empty string as the name for a Synchronization object,
TestStand creates an unnamed Synchronization object that you can access
only through an object reference variable. To associate an unnamed
Synchronization object with an object reference variable, select Use
Object Reference as the object reference lifetime in the <StepType> Step
Configuration dialog box for each step type.
By default, a Synchronization object is accessible only from the operating
system process in which you create it. However, you can make a
Synchronization object accessible from other processes, such as multiple
instances of a user interface, by using an asterisk (*) as the first character
in the name. In addition, you can create a Synchronization object on a
specific machine by beginning the name with the machine name, such
as "\\\\machinename\\syncobjectname". You can then use this
name to access the Synchronization object from any machine on your
network.
To access Synchronization objects on other machines, you must configure
DCOM for the TSAutoMgr.exe server, which is located in the
<TestStand>\Bin directory. Refer to the Setting up TestStand as a Server
for Remote Sequence Execution section of Chapter 5, Adapters, for
information about configuring DCOM and setting up a server for remote
access. Follow the instructions given for the REngine.exe server but
apply them to the TSAutoMgr.exe server.
Note When you specify an object on a remote machine using a string constant in a dialog

box expression control, be sure to escape the backslashes and surround the name in quotes.
For example, use "\\\\machinename\\syncobjname" instead of \\machinename\
syncobjname.

National Instruments Corporation

B-3

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

All named TestStand Synchronization objects share the same name space.
Therefore, you cannot have Synchronization objects with the same name.
Synchronization object names are not case-sensitive.

Lifetime
When you create a Synchronization object, you must specify a lifetime
for the reference you create. The object exists for at least as long as the
reference exists but can exist longer if another reference to it has a different
lifetime.
The object reference lifetime choices are Same as Sequence, Same as
Thread, Same as Execution, and Use Object Reference. If you refer to your
object by name only, then you typically set its reference lifetime to Same as
Sequence, Same as Thread, or Same as Execution. This guarantees that the
object lives as long as the sequence, thread, or execution in which you
create the reference. If you want to explicitly control the lifetime of the
object reference or if you wish to refer to the object using an object
reference variable, select Use Object Reference from the <Step> Reference
Lifetime ring control in the <Step Type> Step Configuration dialog box.
You can use the object reference in place of its name when performing
operations on the object.
You can also use the reference from other threads without performing a
Create operation in each thread. An object reference releases its object
when you set the variable equal to Nothing, when you reuse the variable
to store a different reference, or when the variable goes out of scope. When
the last object reference to a Synchronization object releases, TestStand
disposes of the object.
Some Synchronization objects have an operation, such as Lock or Acquire,
for which you can also specify a lifetime. In this case, the lifetime
determines the duration of the operation.

Timeout
Most Synchronization objects can perform one or more operations that
timeout if they do not complete within the number of seconds you specify.
You can specify that TestStand treats a timeout as an error condition, or you
can explicitly check for the occurrence of a timeout by checking the value
of the Step.Result.TimeoutOccurred property.

NI TestStand Reference Manual

B-4

ni.com

Appendix B

Synchronization Step Types

Synchronization Step Types


Each type of Synchronization object has a step type to create and control
the object. The Batch Synchronization object has two step types, Batch
Specification and Batch Synchronization. For all other Synchronization
objects, the name of the step type is the same as the name of the
Synchronization object type it controls. The following additional
Synchronization step types exist:

WaitUse the Wait step to wait for an execution or thread to complete


or for a time interval to elapse.

Thread PriorityUse the Thread Priority step to adjust the operating


system priority of a TestStand thread.

To use any Synchronization step type, insert a step of that type and select
Configure <Step Type> from the context menu to launch the <Step Type>
Step Configuration dialog box. Use this dialog box to select an operation
for the step to perform. You can then specify settings for the operation you
select. Some operations store output values to variables you specify. If the
control for an output value is labeled as an optional output, you can leave
the control empty.
The following sections describe the functionality and custom properties of
each Synchronization step type.

Lock
Use a Lock step to ensure that only one thread can access a particular
resource or data item at a time. For example, if you examine and update the
value of a global variable from multiple threads or executions, you can use
a lock to ensure that only one thread examines and updates the variable at
a time. If multiple threads are waiting to lock a lock, they do so in first in
first out (FIFO) order as the lock becomes available.
A thread can lock the same lock an unlimited number of times without
unlocking it. To release the lock, the thread must balance each Lock
operation with an Unlock operation.
Locks in TestStand have deadlock detection. If all of the threads that are
using a set of locks reside on the same machine, and all of the locks in that
set reside on that machine as well, TestStand will detect and report a
run-time error if deadlock occurs as a result of those locks and threads. To
avoid deadlock, you must always lock a set of locks in the same order in
every thread or lock all of the locks required by a thread in one Lock
operation by specifying an array of lock names or references.
National Instruments Corporation

B-5

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

Note You can also create a lock around a single step using the Synchronization panel on

the Properties tab of the Step Settings pane.


Note Accessing TestStand variables and properties is thread safe.

Step Properties
In addition to the common custom properties, the Lock step type defines the
following step properties:

NI TestStand Reference Manual

Step.Result.TimeoutOccurredSet to True if the Lock operation


times out. This property exists only if the step is configured for the
Lock operation.

Step.NameOrRefExprContains the Lock Name expression for the


Create operation and the Lock Name or Reference expression for all
other Lock operations. In the case of the Lock operation, this
expression can also specify an array of names or references.

Step.LifetimeRefExprContains the object reference expression for


the Lock Reference Lifetime or Lock Operation Lifetime when you set
either lifetime to Use Object Reference.

Step.TimeoutEnabledContains the Timeout Enabled setting for the


Lock operation.

Step.TimeoutExprContains the Timeout expression, in seconds,


for the Lock operation.

Step.ErrorOnTimeoutContains the Timeout Causes Run-Time


Error setting for the Lock operation.

Step.AlreadyExistsExprContains the Already Exists expression


for the Create operation or the Lock Exists expression for the Get
Status operation.

Step.NumThreadsWaitingExprContains the Number of Threads


Waiting to Lock the Lock expression for the Get Status operation.

Step.OperationContains a value that specifies the operation the


step is configured to perform. The valid values are 0 = Create,
1 = Lock, 2 = Early Unlock, and 3 = Get Status.

Step.LifetimeContains a value that specifies the lifetime setting


to use for the Create operation. The valid values are 0 = Same as
Sequence, 1 = Same as Thread, 2 = Use Object Reference, and
3 = Same as Execution.

B-6

ni.com

Appendix B

Synchronization Step Types

Step.LockLifetimeContains a value that specifies the lifetime


setting to use for the Lock operation. The valid values are 0 = Same
as Sequence, 1 = Same as Thread, 2 = Use Object Reference.

Step.CreateIfDoesNotExistContains the Create If Does Not Exist


setting for the Lock operation.

Rendezvous
Use a Rendezvous step to make threads wait for each other before
proceeding past a specified location. Each thread blocks as it performs the
Rendezvous operation. When the number of blocked threads reaches the
total that you specified when you created the rendezvous, the rendezvous
unblocks all its waiting threads and they resume execution.

Step Properties
In addition to the common custom properties, the Rendezvous step type
defines the following step properties:

Step.Result.TimeoutOccurredSet to True if the Rendezvous


operation times out. This property exists only if the step is configured
for the Rendezvous operation.

Step.NameOrRefExprContains the Rendezvous Name expression


for the Create operation and the Rendezvous Name or Reference
expression for other Rendezvous operations.

Step.LifetimeRefExprContains the object reference expression for


the Rendezvous Reference lifetime when you set the lifetime to Use
Object Reference.

Step.TimeoutEnabledContains the Timeout Enabled setting for the


Rendezvous operation.

Step.TimeoutExprContains the Timeout expression, in seconds,


for the Rendezvous operation.

Step.ErrorOnTimeoutContains the Timeout Causes Run-Time


Error setting for the Rendezvous operation.

Step.AlreadyExistsExprContains the Already Exists expression


for the Create operation or the Rendezvous Exists expression for the
Get Status operation.

Step.RendezvousCountExprContains the Number of Threads Per


Rendezvous expression for the Create operation.

Step.NumThreadsWaitingExprContains the Number of Threads


Waiting for Rendezvous expression for the Get Status operation.

National Instruments Corporation

B-7

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

Step.OperationContains a value that specifies the operation the


step is configured to perform. The valid values are 0 = Create,
1 = Rendezvous, and 2 = Get Status.

Step.LifetimeContains a value that specifies the lifetime setting to


use for the Create operation. The valid values are 0 = Same as
Sequence, 1 = Same as Thread, 2 = Use Object Reference, and
3 = Same as Execution.

Step.RendezvousCountOutExprContains the Number of Threads


Per Rendezvous expression for the Get Status operation.

Queue
Use Queue steps to synchronize the production and consumption of data
among your threads. A queue has two primary operationsenqueue and
dequeue. Enqueue places a data item on the queue, and dequeue removes
an item from the queue. The Enqueue operation blocks when the queue is
full, and the Dequeue operation blocks when the queue is empty. If multiple
threads block on the same Queue operation, the threads unblock in first in
first out (FIFO) order.

Step Properties
In addition to the common custom properties, the Queue step type defines
the following step properties:

NI TestStand Reference Manual

Step.Result.TimeoutOccurredSet to True if an Enqueue or


Dequeue operation times out. This property only exists if the step
is configured for the Enqueue or Dequeue operation.

Step.NameOrRefExprContains the Queue Name expression for


the Create operation and the Queue Name or Reference expression for
all other queue operations. In the case of the Dequeue operation, this
expression can also specify an array of names or references.

Step.LifetimeRefExprContains the object reference expression for


the queue lifetime when you set the lifetime to Use Object Reference.

Step.TimeoutEnabledContains the Timeout Enabled setting for the


Enqueue or Dequeue operation.

Step.TimeoutExprContains the Timeout expression, in seconds,


for the Enqueue or Dequeue operation.

Step.ErrorOnTimeoutContains the Timeout Causes Run-Time


Error setting for the Enqueue or Dequeue operation.

B-8

ni.com

Appendix B

Synchronization Step Types

Step.AlreadyExistsExprContains the Already Exists expression


for the Create operation or the Queue Exists expression for the Get
Status operation.

Step.MaxNumElementsExprContains the expression that


specifies the maximum number of elements of the queue for the Create
operation.

Step.MaxNumElementsOutExprContains the expression that


specifies where to store the maximum number of elements of the queue
for the Get Status operation.

Step.NumThreadsWaitingEnqueueExprContains the expression


that specifies where to store the number of threads that are waiting to
enqueue for the Get Status operation.

Step.NumThreadsWaitingDequeueExprContains the expression


that specifies where to store the number of threads that are waiting to
dequeue for the Get Status operation.

Step.OperationContains a value that specifies the operation the


step is configured to perform. The valid values are 0 = Create,
1 = Enqueue, 2 = Dequeue, 3 = Flush, and 4 = Get Status.

Step.LifetimeContains a value that specifies the lifetime setting


to use for the Create operation. The valid values are 0 = Same as
Sequence, 1 = Same as Thread, 2 = Use Object Reference, and
3 = Same as Execution.

Step.NumElementsExprContains the expression that specifies


where to store the current number of elements in the queue for the
Get Status operation.

Step.DataExprContains the New Element to Enqueue expression


when you configure the step for the Enqueue operation, the Location
to Store Element expression when you configure the step for the
Dequeue operation, and the Location to Store Array of Queue
Elements expression when you configure the step for the Flush or
Get Status operation.

Step.ByRefContains the Boolean value that specifies whether the


step stores a queue element by object reference instead of by value for
the Enqueue operation.

Step.EnqueueLocationContains a value that specifies the location


to store the queue element for the Enqueue operation. The valid values
are 0 = Front of Queue, 1 = Back of Queue.

Step.DequeueLocationContains a value that specifies the location


from which to remove the queue element for the Dequeue operation.
The valid values are 0 = Front of Queue and 1 = Back of Queue.

National Instruments Corporation

B-9

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

Step.FullQueueOptionContains a value that specifies the options


for the If the Queue is Full setting of the Enqueue operation. The valid
values are 0 = Wait, 1 = Discard Front Element, 2 = Discard Back
Element, and 3 = Do Not Enqueue.

Step.RemoveElementContains a Boolean value that specifies


whether the step removes the element from the queue when it performs
the Dequeue operation.

Step.WhichQueueExprContains the expression that specifies


where to store the array offset of the queue on which the Dequeue
operation occurs.

Notification
Use Notification steps to notify one or more threads when a particular event
or condition has been met. You can also pass data to the threads you notify.

Step Properties
In addition to the common custom properties, the Notification step type
defines the following step properties:

NI TestStand Reference Manual

Step.Result.TimeoutOccurredSet to True if a Wait operation


times out. This property only exists if the step is configured for the
Wait operation.

Step.NameOrRefExprContains the Notification Name expression


for the Create operation and the Notification Name or Reference
expression for all other operations. In the case of the Wait operation,
this expression can also specify an array of names or references.

Step.LifetimeRefExprContains the object reference expression


for the notification lifetime when you set the lifetime to Use Object
Reference.

Step.TimeoutEnabledContains the Timeout Enabled setting for the


Wait operation.

Step.TimeoutExprContains the Timeout expression, in seconds,


for the Wait operation.

Step.ErrorOnTimeoutContains the Timeout Causes Run-Time


Error setting for the Wait operation.

Step.AlreadyExistsExprContains the Already Exists expression


for the Create operation or the Notification Exists expression for the
Get Status operation.

B-10

ni.com

Appendix B

Synchronization Step Types

Step.NumThreadsWaitingExprContains the expression that


specifies where to store the number of threads that are waiting on
the notification for the Get Status operation.

Step.OperationContains a value that specifies the operation the


step is configured to perform. The valid values are 0 = Create, 1 = Set,
2 = Clear, 3 = Pulse, 4 = Wait, and 5 = Get Status.

Step.LifetimeContains a value that specifies the lifetime setting


to use for the Create operation. The valid values are 0 = Same as
Sequence, 1 = Same as Thread, 2 = Use Object Reference, and
3 = Same as Execution.

Step.DataExprContains the Data Value expression for the Set or


Pulse operation or the Location to Store Data expression for the Wait
or Get Status operation.

Step.ByRefContains the Boolean value that specifies whether to


store the data by object reference instead of by value for a Set or Pulse
operation.

Step.WhichNotificationExprContains the expression that


specifies where to store the array offset of the notification to which the
Wait operation responds.

Step.IsSetExprContains the expression that specifies where the


step stores the Boolean value that indicates whether the notification is
in a Set state. The Get Status operation uses this expression.

Step.IsAutoClearExprContains the expression that specifies


where to store the Boolean value that indicates whether the notification
is configured to AutoClear. The Get Status operation uses this
expression.

Step.AutoClearContains the AutoClear setting for the Set


operation.

Step.PulseNotifyOptContains the setting for the Pulse operation


that indicates the threads to which a pulse notification is sent. The valid
values are 0 = Notify First Waiting Thread and 1 = Notify All Waiting
Threads.

Wait
Use Wait steps to wait for an execution or thread to complete or for a time
interval to elapse.

National Instruments Corporation

B-11

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

Waiting for Execution Threads to Complete


When the thread or execution completes, the Wait step copies the result
status and error information for the thread or execution to its own status and
error properties. Therefore, if a Wait step waits on a sequence that fails, the
status of the Wait step is Failed.
The result list entry for a Wait step contains a TS.SequenceCall.ResultList
property which is the result list for the thread or execution.
In addition, in a Wait step, do not specify a Sequence Call step to wait on if
the Sequence Call step launches more than one asynchronous call because
the Wait step waits on the last asynchronous call the Sequence Call step
launches. This behavior might change in a future version of TestStand. You
can encounter this situation if you include the Sequence Call step in a loop.
To wait on multiple asynchronous calls you launch from a Sequence Call
step in a loop, store an ActiveX reference to each thread or execution you
launch and wait on each reference in a Wait step.

Step Properties
In addition to the common custom properties, the Wait step type defines the
following step properties:

NI TestStand Reference Manual

Step.Result.TimeoutOccurredSet to True if the Wait for Thread


or Wait for Execution operation times out. This property only exists if
the step is configured for one of these operations.

Step.TimeoutEnabledContains the timeout enabled setting for the


Wait for Thread or the Wait for Execution operation.

Step.ErrorOnTimeoutContains the Timeout Causes Run-Time


Error setting for the Wait for Thread or the Wait for Execution
operation.

Step.ThreadRefExprContains the Thread Reference expression


for the Wait for Thread operation when the Step.SpecifyBySeqCall
property is set to False.

Step.SeqCallNameContains the name of the Sequence Call step


that creates the thread or execution the step waits for when the
Step.SpecifyBySeqCall property is set to True.

Step.SeqCallStepGroupIdxContains the step group of the


Sequence Call step that creates the thread or execution that the step
waits for when the Step.SpecifyBySeqCall property is set to True.
The valid values are 0 = Setup, 1 = Main, and 2 = Cleanup.

B-12

ni.com

Appendix B

Synchronization Step Types

Step.TimeoutExprContains the Timeout expression, in seconds,


for the Wait for Thread or the Wait for Execution operation.

Step.WaitForTargetContains a value that specifies the type of Wait


operation the step performs. The valid values are 0 = Time Interval,
1 = Time Multiple, 2 = Thread, and 3 = Execution.

Step.TimeExprContains the time expression for the Time Interval


or Time Multiple operation of the step.

Step.ExecutionRefExprContains the expression that evaluates to a


reference to the execution on which the Wait for Execution operation
waits.

Step.SpecifyBySeqCallContains the Specify By Sequence Call


setting for the Wait for Thread or the Wait for Execution operation.

TestStand also adds the following properties at run time to the results for
Wait steps that are configured to wait for a thread or execution.

AsyncModeSet to True if the Wait step is waiting on a thread. It is


set to False if the Wait step is waiting on an execution.

AsyncIdContains the value of the Id property of the thread or


execution that the step is waiting for.

Batch Synchronization
Use Batch Synchronization steps to define sections of a sequence in which
to synchronize multiple threads that belong to one batch. Typically, you use
these steps in a sequence that you execute using the Batch process model.
More specifically, you place Batch Synchronization steps around one or
more test steps to create a synchronized section.
Use the Synchronization panel on the Properties tab of the Step Settings
pane to synchronize a single step for the multiple threads that belong to
a batch.

Synchronized Sections
Use Batch Synchronization steps to define synchronized sections by
placing a step at the beginning and end of a section of steps in a sequence
and specifying an Enter operation for the beginning step and an Exit
operation for the ending step. While you must place the Enter and Exit steps
in the same sequence, you do not have to place them in the same step group.

National Instruments Corporation

B-13

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

There are three types of synchronized sectionsSerial, Parallel, and


One Thread Only. All synchronized sections share the following behaviors:

Each thread in a batch that enters a synchronized section blocks at the


Enter step until all other threads in the batch arrive at their respective
instances of the Enter step.

Each thread in a batch that reaches the end of the synchronized section
blocks at the Exit step until all other threads in the batch arrive at their
respective instances of the Exit step.

Serial Sections
Use a Serial section to ensure that each thread in the batch executes the
steps in the section sequentially and in the order that you specify when you
create the batch. When all threads in a batch arrive at their respective
instances of an Enter step for a Serial section, TestStand releases one thread
at a time in ascending order according to the order numbers you assign to
the threads when you add them to the batch using the Batch Specification
step. As each thread reaches the Exit step for the section, the next thread in
the batch proceeds from the Enter step. After all the threads in the batch
arrive at the Exit step, they exit the section together. Refer to the Semaphore
section of this appendix for more information about order numbers.

Parallel Sections
When all threads in a batch arrive at their respective instances of an Enter
step for a Parallel section, TestStand releases all the threads at once. Each
thread that arrives at the Exit step for the section blocks until all threads in
the batch reach that step.

One Thread Only Sections


Use a One Thread Only section to specify that only one thread in the batch
executes the steps in the section. Typically, you use this type of section to
perform an operation that applies to the batch as a whole, such as raising
the temperature in a test chamber. When all threads in a batch arrive at their
respective instances of an Enter step for a One Thread Only section,
TestStand releases only the thread with the lowest order number. When that
thread arrives at the Exit step for the section, all remaining threads in the
batch jump from the Enter step to the Exit step, skipping the steps within
the section. The threads in the batch then exit the section together.

Mismatched Sections
Sections become mismatched when all threads in a batch are blocked at an
Enter or an Exit operation, but they are not all blocked at the same Enter or

NI TestStand Reference Manual

B-14

ni.com

Appendix B

Synchronization Step Types

Exit operation. This can occur when a sequence has a conditional flow
of execution due to preconditions, post actions, or other flow control
operations.
When TestStand detects mismatched sections, it handles them as follows:

The thread that is at the Enter or Exit step that appears earliest in the
hierarchy of sequences and subsequences proceeds as if all threads in
the batch are at the same step.

If multiple Enter and Exit operations are equally early in the hierarchy
of sequences and subsequences, Enter operations proceed first.

Nested Sections
Nesting of sections can occur within the same sequence or as a result
of calling a subsequence inside of a synchronized section when the
subsequence also contains a synchronized section. When you nest one
section inside another, TestStand honors the inner section if the type of the
outer section is serial or parallel. For example, if you nest one serial section
in another serial section, each thread that enters the outer section proceeds
only until the Enter step of the inner section and then waits for the other
threads to reach the same step.
TestStand ignores the inner section if the type of the outer section is
One Thread Only.
Note You can create a synchronized section around a single step using the

Synchronization panel on the Properties tab of the Step Settings pane rather than
by using explicit Batch Synchronization steps.

Requirements for Using Enter and Exit Operations


TestStand generates a run-time error if your Enter and Exit operations do
not adhere to the following requirements:

Each Exit operation must match the most nested Enter operation.

A thread cannot reenter a section it is already within.

You must exit a section in the same sequence that you enter it.

Step Properties
In addition to the common custom properties, the Batch Synchronization
step type defines the following step properties:

National Instruments Corporation

Step.Result.TimeoutOccurredSet to True if an Enter or Exit


operation times out.

B-15

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

Step.TimeoutEnabledContains the Timeout Enabled setting for the


Enter or Exit operation.

Step.TimeoutExprContains the Timeout expression, in seconds,


for the Enter or Exit operation.

Step.ErrorOnTimeoutContains the Timeout Causes Run-Time


Error setting for the Enter or Exit operation.

Step.OperationContains a value that specifies the operation the


step is configured to perform. The valid values are 0 = Enter
Synchronized Section and 1 = Exit Synchronized Section.

Step.SectionNameExprContains the expression that specifies the


name of the section for the Enter or Exit operation.

Step.SectionTypeContains a value that specifies the type of


section the Enter operation defines. The valid values are 1 = Serial,
2 = Parallel and 3 = OneThreadOnly.

Auto Schedule
Use the Auto Schedule step to define a block that contains any number of
Use Auto Scheduled Resource step sub-blocks. The Auto Schedule step
executes each sub-block once. The order in which it executes the
sub-blocks may vary according to the availability of the resources that the
sub-blocks require. You typically use Auto Schedule steps in a sequence
that you execute using the Parallel or Batch process models. The Auto
Schedule step may increase CPU and or resource utilization by directing a
thread that would otherwise wait for a resource locked by another thread to
perform other actions using available resources instead.
Refer to the examples in the <TestStand>\Examples\Auto Schedule
directory to better understand how to use a Auto Schedule step and Use
Auto Scheduled Resource steps.

Step Properties
In addition to the common custom properties, the Auto Schedule step type
defines the following step properties:

NI TestStand Reference Manual

Step.Result.TimeoutOccurredSet to True if any Auto Scheduled


Resource blocks within the Auto Schedule block time out. This
property only exists if the step is configured for the Acquire operation.

Step.TimeoutExpressionContains the Timeout expression, in


seconds, for the Auto operation.

Step.TimeoutEnabledContains the Timeout Enabled setting for the


Auto Schedule operation.

B-16

ni.com

Appendix B

Synchronization Step Types

Step.TimeoutIsRuntimeErrorSet to True to cause a step run-time


error when a timeout occurs.

Step.DisplayRuntimeDescriptionSet to True to display execution


scheduling information in the step description.

Use Auto Scheduled Resource


Use the Use Auto Scheduled Resource step to define a sub-block of steps
within an Auto Schedule block that uses a specified resource or set of
resources. The Use Auto Scheduled Resource step locks the specified
resources while the steps in its sub-block execute.

Step Properties
In addition to the common custom properties, the Use Auto Scheduled
Resource step type defines the following step properties:

Step.ResourceExpressionsContains a list of expressions that


specify the lock alternatives the block can acquire before executing
the steps within the block.

Step.SelectedResourceExpressionContains an expression that


specifies a string variable or property into which to store the lock that
the step acquires during execution.

Thread Priority
Use the Thread Priority step to increment or decrement the priority of a
thread so that it receives more or less CPU time than other threads.
When you use this step, you must avoid starving important threads of CPU
time by boosting the priority of another thread too high. When you alter a
thread priority, remember to save the previous priority value and restore it
once your thread no longer requires the altered priority value.
Note Setting the priority of a thread to Time Critical can cause the user interface for your

application to become unresponsive.

Step Properties
In addition to the common custom properties, the Thread Priority step type
defines the following step properties:

National Instruments Corporation

Step.OperationContains a value that specifies the operation the


step is configured to perform. The valid values are 0 = Set Thread
Priority and 1 = Get Thread Priority.

B-17

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

Step.SetPriorityExprSpecifies the thread priority expression for


the Set Thread Priority operation.

Step.GetPriorityExprSpecifies the location to store the thread


priority for the Get Thread Priority operation.

Semaphore
Use Semaphore steps to limit concurrent access to a resource to a specific
number of threads. A semaphore stores a numeric count and allows threads
to increment (release) or decrement (acquire) the count as long as the count
stays equal to or greater than zero. If a decrement would cause the count to
go below zero, the thread attempting to decrement the count blocks until
the count increases. When multiple threads are waiting to decrement a
semaphore, the semaphore unblocks the threads in FIFO order whenever
another thread increments the semaphore count.
A semaphore with an initial count of one behaves like a lock, with one
exception. Like a lock, a one-count semaphore restricts access to a single
thread at a time. Unlike a lock, a thread cannot acquire a one-count
semaphore multiple times without first releasing it after each acquire.
When a thread attempts to acquire the semaphore a second time without
releasing it, the count is zero and the thread blocks. Refer to the Lock
section of this appendix for more information about Lock objects.

Step Properties
In addition to the common custom properties, the Semaphore step type
defines the following step properties:

NI TestStand Reference Manual

Step.Result.TimeoutOccurredSet to True if the Acquire


operation times out. This property only exists if the step is configured
for the Acquire operation.

Step.NameOrRefExprContains the Semaphore Name expression


for the Create operation and the Semaphore Name or Reference
expression for all of the other semaphore operations.

Step.AutoReleaseContains a Boolean value that specifies whether


the Acquire operation automatically performs a release when the
Acquire lifetime expires.

Step.LifetimeRefExprContains the object reference expression for


the semaphore lifetime or acquire lifetime when you set the lifetime to
Use Object Reference.

Step.TimeoutEnabledContains the Timeout Enabled setting for the


Acquire operation.

B-18

ni.com

Appendix B

Synchronization Step Types

Step.TimeoutExprContains the Timeout expression, in seconds,


for the Acquire operation.

Step.ErrorOnTimeoutContains the Timeout Causes Run-Time


Error setting for the Acquire operation.

Step.AlreadyExistsExprContains the Already Exists expression


for the Create operation or the Semaphore Exists expression for the
Get Status operation.

Step.InitialCountExprContains the Numeric expression that the


Create operation uses for the initial count of the semaphore.

Step.NumThreadsWaitingExprContains the Number of Threads


Waiting to Acquire the Semaphore expression for the Get Status
operation.

Step.OperationContains a value that specifies the operation the


step is configured to perform. The valid values are 0 = Set Thread
Priority and 1 = Get Thread Priority.

Step.LifetimeContains a value that specifies the lifetime setting


to use for the Create operation. The valid values are 0 = Same as
Sequence, 1 = Same as Thread, 2 = Use Object Reference, and
3 = Same as Execution.

Step.InitialCountOutExprContains the Initial Semaphore Count


expression for the Get Status operation.

Step.AcquireLifetimeContains a value that specifies the lifetime


setting for the Acquire operation. The valid values are 0 = Same as
Sequence, 1 = Same as Thread, and 2 = Use Object Reference. The
Acquire operation uses this setting only when Step.AutoRelease is
set to True.

Step.CurrentCountExprContains the Current Count expression


for the Get Status operation.

Batch Specification
When you write a process model, you can use Batch Specification steps to
define a group of threads where each thread in the group runs an instance
of the client sequence file. Defining a group allows you to perform Batch
Synchronization operations on the threads in the group. The TestStand
Batch process model uses Batch Specification steps to create a batch that
contains a thread for each test socket. For more information about the Batch
process model refer to the Batch Process Model section of Appendix A,
Process Model Architecture. For more information about batch
synchronization, refer to the Batch Synchronization section of this
appendix.

National Instruments Corporation

B-19

NI TestStand Reference Manual

Appendix B

Synchronization Step Types

When you test each UUT in a separate thread, you use the Batch
Specification step to include the UUT threads in one batch. Use the Batch
Synchronization step to control the interaction of the UUT threads as they
execute the test steps.

Step Properties
In addition to the common custom properties, the Batch Specification step
type defines the following step properties:

NI TestStand Reference Manual

Step.OperationContains a value that specifies the operation the


step is configured to perform. The valid values are 0 = Create, 1 = Add
Thread, 2 = Remove Thread, and 3 = Get Status.

Step.NameOrRefExprContains the Name expression for the


Create operation and the Name or Reference expression for all other
batch operations.

Step.LifetimeContains a value that specifies the lifetime setting


to use for the Create operation. The valid values are 0 = Same as
Sequence, 1 = Same as Thread, 2 = Use Object Reference, and
3 = Same as Execution.

Step.LifetimeRefExprContains the object reference expression for


the batch lifetime when you set the lifetime to Use Object Reference.

Step.AlreadyExistsExprContains the Already Exists expression


for the Create operation or the Batch Exists expression for the Get
Status operation.

Step.ThreadRefExprContains the Object Reference to Thread


expression for the Add Thread and Remove Thread operations.

Step.OrderNumExprContains the Order Number expression for


the Add Thread operation.

Step.NumThreadsWaitingExprContains the Number of Threads


Waiting at Synchronized Sections expression for the Get Status
operation.

Step.NumThreadsInBatchExprContains the Number of Threads


in Batch expression for the Get Status operation.

Step.DefaultBatchSyncExprContains the Default Batch


Synchronization expression for the Create operation.

Step.DefaultBatchSyncOutExprContains the Default Batch


Synchronization expression for the Get Status operation.

B-20

ni.com

Database Step Types

TestStand includes the following built-in step types that you can use to
communicate with a database:

Open Database

Open SQL Statement

Close SQL Statement

Close Database

Data Operation

Property Loader

A simple sequence of Database steps might include the following:


1.

Connect to the database using the Open Database step type.

2.

Use the Open SQL Statement step type to issue a SQL query on tables
in the database.

3.

Create new records, then get and update existing records using Data
Operation step types.

4.

Use the Close SQL Statement step type to close the SQL query.

5.

Close the database connection using the Close Database step type.

Note Use the Property Loader step type to import property and variable values from a file
or database during an execution.

To configure these steps, right-click the step and select Edit <step type>
from the context menu, or click the Edit <step type> button on the Edit
tab on the Step Settings pane of the sequence editor.
The following sections describe each Database step type and their custom
step properties.
You can view examples of Database step types in the <TestStand>\
Examples\Database and <TestStand>\Examples\Property
Loader directories. Refer to the NI TestStand Help for more information
about each of the Database step types.

National Instruments Corporation

C-1

NI TestStand Reference Manual

Appendix C

Database Step Types

Open Database
Use the Open Database step type to open a database for use in TestStand.
An Open Database step returns a database handle that you can use to open
SQL statements.

Step Properties
The Open Database step type defines the following step properties in
addition to the common custom properties:

Step.ConnectionStringSpecifies a string expression that contains


the name of the data link to open.

Step.DatabaseHandleSpecifies the numeric variable or property


assigned to the value of the opened database handle.

Open SQL Statement


After you open a database, you must select a set of data in the database to
work with. Use the Open SQL Statement step type to select this data. After
you open an Open SQL Statement step, you can perform multiple
operations on that data set using the Data Operation steps. An Open SQL
Statement step returns a statement handle that you can use in the Data
Operation steps.

Step Properties
The Open SQL Statement step type defines the following step properties
in addition to the common custom properties:

NI TestStand Reference Manual

Step.PageSizeSpecifies the number of records in a page for the


SQL statement.

Step.CommandTimeoutSpecifies the amount of time, in seconds,


TestStand waits when attempting to issue a command to the open
database connection.

Step.CacheSizeSpecifies the cache size for the SQL statement.

Step.MaxRecordsToSelectSpecifies the maximum number of


records the SQL statement can return.

Step.CursorTypeSpecifies the cursor type that the SQL statement


uses.

Step.CursorLocationSpecifies where the data source maintains


cursors for a connection.

Step.MarshalOptionsSpecifies the marshal options for the updated


records in the SQL statement.

C-2

ni.com

Appendix C

Database Step Types

Step.LockTypeSpecifies the lock type for the records the SQL


statement selects.

Step.CommandTypeSpecifies the command type of the SQL


statement.

Step.DatabaseHandleSpecifies the name of the variable or


property that contains the database handle with which you open the
SQL statement.

Step.StatementHandleSpecifies the numeric variable or property


that is assigned for the value of the SQL statement handle.

Step.SQLStatementSpecifies a string expression that contains the


SQL command.

Step.NumberOfRecordsSelectedSpecifies the numeric variable or


property to which the step assigns the number of records the SQL
statement returns.

Step.RequiresParametersSpecifies whether the SQL statement


requires input or output parameters to execute. If False, the step
immediately executes the SQL statement. If True, the step only
prepares the SQL statement, and a subsequent Data Operation step
must perform an Execute operation that defines the parameters for the
statement.

Close SQL Statement


Use the Close SQL Statement step to close a SQL statement handle that you
obtain from an Open SQL Statement step.
National Instruments recommends placing Close SQL Statement steps in the Cleanup
step group.

Tip

Step Properties
The Close SQL Statement step type defines the following step property in
addition to the common custom properties:

National Instruments Corporation

Step.StatementHandleSpecifies the name of the variable or


property of type Number that contains the SQL statement handle that
is to be closed.

C-3

NI TestStand Reference Manual

Appendix C

Database Step Types

Close Database
Use the Close Database step type to close the database handle that you
obtain from an Open Database step type.
Tip National Instruments recommends placing Close Database steps in the Cleanup step
group.

Step Properties
The Close Database step type defines the following step property in
addition to the common custom properties:

Step.DatabaseHandleSpecifies the name of the variable or


property that contains the open database handle that is to be closed.
The variable or property is of the Number data type.

Note TestStand does not automatically close open database handles. You must call a

Close Database step for your open handles. If you abort an execution, you must exit the
application process that loaded the TestStand Engine to guarantee that TestStand frees all
database handles. Selecting Unload All Modules from the File menu does not close the
handles.

Data Operation
Use the Data Operation step type to perform operations on a SQL statement
that you open with an Open SQL Statement step. With the Data Operation
step, you can fetch new records, retrieve values from a record, modify
existing records, create new records, and delete records. For SQL
statements that require parameters, you can create parameters and set input
values, execute statements, close statements, and fetch output parameter
values.

Step Properties
The Data Operation step type defines the following step properties in
addition to the common custom properties:

NI TestStand Reference Manual

Step.StatementHandleSpecifies a string expression that contains


the name of the SQL statement to operate on.

Step.RecordToOperateOnSpecifies the record to operate on.


Valid values are 0 = New, 1= Current, 2 = Next, 3 = Previous, and
4 = Index.

Step.RecordIndexSpecifies the index of the record to operate on


when Step.RecordToOperateOn is set to fetch a specific index.

C-4

ni.com

Appendix C

Database Step Types

Step.OperationSpecifies the operation to perform on the record.


Valid values are 0 = Fetch only, 1 = Set, 2 = Get, 3 = Put, 4 = Delete,
5 = Set and Put, 6 = Execute, and 7 = Close.

Step.ColumnListSourceSpecifies the name of the variable or


property that stores the column-to-variable or column-to-property
mappings. The variable or property must be an array of type
DatabaseColumnValue. By default, the value is Step.ColumnList.

Step.ColumnListSpecifies the column-to-variable or


column-to-property mapping to perform on a Get or Set operation.
The property must be an array of type DatabaseColumnValue.
The DatabaseColumnValue custom data type contains the following
subproperties:

ColumnNameSpecifies the name or number of the column


from which to get a value or to which to assign a value.

DataSpecifies the variable or property to which TestStand


assigns the column value or the expression that TestStand
evaluates and assigns to the column.

FormatStringSpecifies an optional format string for dates,


times, and currencies. Use the empty string ("") if you want to use
the default format. Refer to the NI TestStand Help for a
description of valid format strings.

WriteNullSpecifies whether to write NULL to the column


instead of the value in the Data expression property.

StatusIndicates the error code returned for the Get or Set


operation.

DirectionContains an enumerated value that specifies whether


the parameter direction is In, Out, In/Out, or Return.

TypeContains an enumerated value that specifies whether the


parameter value is String, Number, Boolean, or Date/Time.

SizeSpecifies the maximum size of a string parameter.

Step.SQLStatementSpecifies the SQL statement used by the Edit


Data Operation dialog box to populate the ring controls that contain
column names.

Note You cannot encapsulate your data operations within a transaction. Transactions are

not available in the current version of the TestStand Database step types.

National Instruments Corporation

C-5

NI TestStand Reference Manual

Appendix C

Database Step Types

Property Loader
Use the Property Loader step type to dynamically load the values for
properties and variables from a text file, a Microsoft Excel file, or a DBMS
database at run time. The Property Loader step type supports loading limits
from all TestStand-supported databases except for MySQL. You can either
apply the values that you load to the currently running sequence or to all
subsequent invocations of a sequence. For example, you can develop a
common sequence that can test two different models of a cellular phone,
where each model requires unique limit values for each step. If you use step
properties to hold the limit values, you can include a Property Loader step
in the sequence to load the correct limit values into the step properties.
When you do this, place a Property Loader step in the Setup step group of
a sequence. This directs the Property Loader step to initialize the property
and variable values each time before the steps in the Main step group
execute.
You can load values for properties into sequences so that all subsequent
invocations of the sequences in the file use the dynamically loaded property
values. For example, you can include the Property Loader step in a
ProcessSetup model callback that the execution calls once, allowing
the execution to call the client sequence file multiple times with the
dynamically loaded property values.

Loading from File


The source of file-based values can be a tab-delimited text file (.txt), a
comma-delimited text file (.csv), or an Excel file (.xls). The data is
presented in a table format, where cells are separated by a tab or comma.
The following is an example of a tab-delimited limits file with one data
block specified by starting and ending data markers.
Start Marker
<Step Name>
Voltage at Pin A
Voltage at Pin B
Self Test Output

Limits.Low
9.0
8.5

Limits.String

"SYSTEM OK"

<Locals>
Count

NI TestStand Reference Manual

Limits.High
11.0
9.5

Variable Value
100

C-6

ni.com

Appendix C

<FileGlobals>
Count

Variable Value
99

<StationGlobals>
Power_On

Variable Value
False

Database Step Types

End Marker

In the step name section, the row names correspond to step names, and the
column headings correspond to the names of step properties. Not all
columns apply to each row, and each row contains only values for the
columns that define properties that exist in the rows corresponding step.
For variable sections, each row specifies the name of the property and its
corresponding value. Starting and ending data markers designate the
bounds of the table. A data file can contain more than one block of data.
Use the Importing/Exporting Properties command in the Tools menu to
export property and variable data in the appropriate table format. Refer to
the examples in the <TestStand>\Examples\Property Loader\
LoadingLimits directory and the NI TestStand Help for more
information about loading limits from files.
Note When you specify starting and ending data markers in the Import/Export Properties

dialog box, enter the marker text in the text controls without double quotes. However, when
you specify starting and ending data markers in the expression controls of the Edit Property
Loader dialog box, you must surround literal marker text values with double quotes.

Loading from Database


The source of database values is a recordset returned from an Open SQL
Statement step. The SQL statement recordset is presented in a table format,
where each row pertains to a particular sequence step or to a variable scope,
as shown in Table C-1. The column headings correspond to the names of
properties in the steps or variable scopes. Not all columns apply to each
row. Each row contains only values for the columns that define properties
or variables that are actually in the step or variable scope for the row.

National Instruments Corporation

C-7

NI TestStand Reference Manual

Appendix C

Database Step Types

Table C-1. Example Data for Property Loader Step


LIMITS_
HIGH

LIMITS_
LOW

LIMITS_
STRING

POWER_ON

COUNT

SEQUENCE
NAME

Voltage at Pin A

11

Phone Test.seq

Voltage at Pin B

8.5

9.5

Phone Test.seq

Self Test Output

"SYS OK"

Phone Test.seq

<Locals>

100

Phone Test.seq

<File Globals>

99

Phone Test.seq

<Station Globals>

False

Phone Test.seq

Frequency at Pin A

100,000

10,000

Frequency
Test.seq

Frequency at Pin B

90,000

9,000

Frequency
Test.seq

"OK"

Frequency
Test.seq

STEPNAME

Self Test Output

For database sources, the Property Loader step can filter the data that the
SQL statement returns so that you only load values from rows that contain
specific column values. This is equivalent to the starting and ending data
markers when importing values from a file. For example, in Table C-1
you can load the rows only for rows where the SEQUENCE NAME field
contains the value Phone Test.seq.
Refer to the example in the <TestStand>\Examples\Property
Loader directory and the NI TestStand Help for more information about
loading limits from database tables.

Step Properties
In addition to the common custom properties, the Property Loader step type
defines the following step properties:

NI TestStand Reference Manual

Step.Result.NumPropertiesReadIndicates the total number of


values that the step loaded from the file or database.

Step.Result.NumPropertiesAppliedIndicates the total number of


values the step assigned to properties or variables. A number less than
Step.Result.NumPropertiesRead indicates that the step was unable to
update properties or variables.

Step.ColumnListSourceSpecifies the name of the variable or


property that stores the list of column comparisons that you are using

C-8

ni.com

Appendix C

Database Step Types

to filter the rows in a database recordset. The variable or property must


be an array of type DatabaseColumnValue. By default, the value is
Step.ColumnList.

Step.ColumnListSpecifies the column comparisons TestStand


makes on a recordset before loading its values into properties. This
property must be an array of type DatabaseColumnValue.
The DatabaseColumnValue custom data type contains the following
subproperties:

ColumnNameSpecifies the name or number of the column on


which to perform the comparison.

DataSpecifies the expression that TestStand evaluates at run


time to compare against the column value.

FormatStringSpecifies an optional format string for dates,


times, and currencies. Use an empty string ("") if you want to
use the default format. Refer to the NI TestStand Help for a
description of valid format strings.

DirectionContains an enumerated value that specifies whether


the parameter direction is In, Out, In/Out, or Return.

TypeContains an enumerated value that specifies whether the


parameter type is String, Number, Boolean, or Date/Time.

SizeSpecifies the maximum size of a string parameter.

WriteNullNot used.

StatusNot used.

Step.PropertiesListSourceSpecifies the name of the variable or


property that stores the list of variables and properties into which to
load data. The variable or property must be an array of type
DatabasePropertyMapping. By default, the value is
Step.PropertiesList.

Step.PropertiesListSpecifies the list of variables and properties in


which to load data. The list must be an array of type
DatabasePropertyMapping. Each element of the array defines a
mapping between the source data and a TestStand variable or property.
The DatabasePropertyMapping custom data type contains the
following subproperties:

National Instruments Corporation

PropertyNameSpecifies the name of the property or variable


to which a value is assigned.

PropertyTypeSpecifies the scope of the property or variable,


such as step, local, file global, or station global. Valid values are:
0 = Step, 1 = Local, 2 = File Global, and 3 = Station Global.

C-9

NI TestStand Reference Manual

Appendix C

Database Step Types

DataTypeSpecifies the TestStand type of the property.


Valid values are: 1 = String, 2 = Boolean, and 3 = Number.

ColumnNameSpecifies the name of the column from which


the value is obtained.

Step.DataSourceTypeSpecifies where the step imports property


values. Valid values are 2 = File and 3 = Database.

Step.DatabaseSpecifies the SQL statement handle and settings


from importing property values from a database to a sequence file.
The Database step property contains the following subproperties:

SQLStatementHandleSpecifies the name of the variable or


property that contains the SQL statement handle the step uses at
run time to load values.

SQLStatementSpecifies the SQL statement the Edit Property


Loader dialog box uses to populate ring controls that contain
column names.

StepNameColumnSpecifies the name of the column in the


recordset that contains the names of the steps and variable scopes
that define the rows of data.

AppendTypeNameSpecifies whether TestStand appends the


data type name of the property to the column name when selecting
a property from the available list.

FilterUsingColumnListSpecifies if the step loads only the


rows that match the specific column value.

MaxColumnSizeSpecifies the maximum number of characters


for a column name.

Step.FileSpecifies the file and settings for importing property


values from a file to sequence files.
The File step property contains the following subproperties:

NI TestStand Reference Manual

PathSpecifies a literal pathname for the data file.

DecimalPointSpecifies the type of decimal point the file uses.

UseExprSpecifies whether to use Step.File.Path or


Step.File.FileExpr for the pathname of the data file.

FileExprSpecifies a pathname expression that TestStand


evaluates at run time.

FormatSpecifies the type of delimiters in the file and the file


type. The possible values are Tab, Comma, or Excel.

Start.MarkerExprSpecifies the expression for the starting


marker.

C-10

ni.com

Appendix C

Database Step Types

EndMarkerExprSpecifies the expression for the ending


marker.

SkipSpecifies the string that, when it appears at the beginning


of a row, causes the step type to ignore the row.

MapColumnsUsingFirstRowSpecifies whether the first row


of each data block in the data file contains the names of the step
properties into which the step loads the property values.

ColumnMappingSpecifies the names of the properties into


which the step loads the values if
Step.File.MapColumnsUsingFirstRow is False.

Step.SequenceFileSpecifies the path to the sequence file to import


properties to.

Step.SequenceSpecifies the sequence the step imports properties to.

Step.ExpandToRelatedExecutionsSpecifies that imported


property values are applied to sequences running in related executions.
Related executions include the original execution initiated by the
application and all executions that TestStand invoked or invokes using
a Sequence Call step.

Step.UseCurrentSequenceSpecifies to import properties to the


run-time copy of the sequence where the step is located. Otherwise,
imported properties apply to all invocations of the sequences the step
imports to.

Step.UseCurrentFile Specifies to import properties to the sequence


file where the step is located.

Step.ImportAllSpecifies whether the step attempts to import all


property values listed in a file into the selected sequence files.

Step.StartMarkerMissingActionSpecifies the action the step


takes when the start marker is not found in the file. Valid values are
1 = Stop and error and 2 = Skip sequence.

National Instruments Corporation

C-11

NI TestStand Reference Manual

IVI-C Step Types

Note The IVI-C step types support the IVI-C class compliant instrument drivers. You can

use the ActiveX/COM Adapter when you use the IVI-COM class compliant instrument
drivers.
TestStand provides several step types that enable you to configure and
acquire data from Interchangeable Virtual Instrument (IVI) class-compliant
instruments. IVI is an instrument driver standard that provides common
programming interfaces for several classes of instruments. IVI drivers exist
for a number of popular instruments, including all applicable devices
from National Instruments. For more information about IVI and IVI
class-compliant instrument drivers, refer to the National Instruments Web
site at ni.com/ivi, Appendix F, Instrument Drivers, or the NI TestStand
Help.
You can view examples of the IVI-C step types in the <TestStand>\
Examples\IVI directory.
TestStand includes the following IVI-C step types:

DmmPerforms single-point and multipoint measurements with


digital multimeters.

ScopePerforms single-point and waveform measurements with


oscilloscopes.

FgenGenerates predefined or custom waveforms using arbitrary


waveform generators.

Power SupplyControls and monitors the output of DC power


supplies.

SwitchConnects or disconnects paths and routes, determines the


connectivity of two switches or the state of a route, and queries the
state of the switch module or virtual device.

ToolsSets or gets instrument attributes and performs utility


operations on any IVI instrument.

IVI-C step types offer a configuration-based approach to instrument


control. Use an initial step to configure an instrument and then perform
measurements in one or more subsequent steps. TestStand references a

National Instruments Corporation

D-1

NI TestStand Reference Manual

Appendix D

IVI-C Step Types

session to an instrument using the instrument logical name that you


configure in National Instruments Measurement & Automation Explorer
(MAX). TestStand automatically initializes the instrument session when
the instrument is first configured and automatically closes the instrument
session when the execution is closed. If two executions reference the same
logical name, the session is shared, and the session closes when the last
execution is released.
IVI-C step types complement, but do not replace, the instrument
configuration and measurement operations you perform in code modules
that you write using LabVIEW, Measurement Studio, Microsoft Visual
Basic, or other tools. Although IVI-C step types are the easiest way to
configure and acquire data from IVI class instruments, you must use code
modules to control instruments under the following circumstances:

When you need to precisely specify the instrument driver calls to


ensure optimal performance.

When you need to call specific driver functions that an IVI class does
not support.

When your instrument does not conform to an IVI class or does not
have an IVI driver.

When you need to interleave your instrument control operations with


other code that must reside in a single code module.

Note TestStand does not install IVI-compliant instrument drivers or configure sample

logical names in MAX. Refer to the application help for the IVI Instruments category
in MAX for more information about where to obtain and how to install IVI-compliant
instrument drivers, as well as information about how to create logical names that the
IVI-C step types use.
For more information about IVI and IVI class-compliant instrument drivers, refer to the
National Instruments Web site at ni.com/ivi, Appendix F, Instrument Drivers, or the
NI TestStand Help.

Editing an IVI Step


To use an IVI step, insert an IVI step for the class of instrument you want
to control. To edit the step, right-click the step and select Edit <step type>
from the context menu, or click the Edit <step type> button on the Edit tab
on the Step Settings pane of the sequence editor.

NI TestStand Reference Manual

D-2

ni.com

Appendix D

IVI-C Step Types

Figure D-1 shows the Configure operation for the Dmm step.

Figure D-1. IVI Dmm Step Configure Operation

Each Edit <Step Name> Step dialog box contains a Logical Name ring
control, which you use to select a logical name or a virtual instrument name
that you configure in MAX. Use the buttons to the right of the Logical
Name ring control to launch the Expression Browser dialog box and to
launch MAX.
Note All IVI names, such as logical names, virtual names, and channel names, are

case-sensitive. If you use logical names, driver session names, or virtual names in your
program, be sure that the name you use exactly matches the name in the IVI Configuration
Store file. Do not make any variations in the case of the characters in the name.
The Edit <Step Name> Step dialog box also contains an Operation ring
control, which specifies the action the step performs. Typical operations
include configuring the instrument, taking a reading, or showing/hiding a
graphical display panel for the instrument, also called a soft front panel
(SFP). Depending on the instrument, you can also select other low-level
actions such as Initiate, Send Software Trigger, or Get Information.

National Instruments Corporation

D-3

NI TestStand Reference Manual

Appendix D

IVI-C Step Types

Note When you select an operation, the area under the Operation ring control changes.

Many operations group their settings on tab controls.


In some cases, when TestStand configures an instrument, the instrument
driver may coerce a settings value. Configuring an instrument might
result in an invalid value error for a particular setting because the
instrument-based values are not checked for validity until the configuration
actually occurs. Once configuration completes successfully, you can issue
all of the other operations in subsequent steps.
Refer to the NI TestStand Help for more information about the Edit <Step
Name> Step dialog box associated with each IVI-C step type.

Extensions
The Configure operation configures the instrument to match the settings
as specified by the step. To enable instrument configuration controls that
apply to features that IVI defines as class extensions, select from the
Extensions tab the extended features that your instrument supports.
Figure D-2 shows the Extensions tab for the IVI Dmm step.

Figure D-2. IVI Dmm Extensions Tab

NI TestStand Reference Manual

D-4

ni.com

Appendix D

IVI-C Step Types

The Configure operation handles only those settings that are supported
by the base class specification and the extension groups specified on the
Extensions tab. For the best results, enable only those extensions that are
required for your application.

Operation Settings
Many of the operations, such as Configure and Fetch, allow you to specify
where the dialog box saves the Operation settings for the step. For example,
you could save the Configure settings in a shared variable so that multiple
steps could use the same settings. Figure D-3 shows the Operation Settings
tab for the Configure operation.

Figure D-3. IVI Dmm Operation Settings Tab

The Configuration Source ring control specifies the name of the property
or variable where TestStand stores the settings when you click OK. The
Load button reloads the settings from the specified property or variable
location.

National Instruments Corporation

D-5

NI TestStand Reference Manual

Appendix D

IVI-C Step Types

Validating a Configuration
When you edit a step that configures an instrument, click Validate to test
your configuration before closing the Edit <Step Name> Step dialog box.
Refer to the NI TestStand Help for more information about the Validate IVI
Configuration dialog box.

Using Soft Front Panels


Each IVI session for an IVI-C step type can display a graphical display
panel for the instrument, also called a soft front panel (SFP). The Show and
Hide Soft Front Panel operations control whether TestStand displays a SFP
for the instrument.
When the SFP is visible, you can interact directly with the instrument
session that TestStand is controlling.
Refer to the NI TestStand Help for more information about the Show and
Hide Soft Front Panel operations.

Get Information
Use the Get Information operation for each instrument class step type to
retrieve low-level status and information from the instrument. For the
Get Information operation, you must specify an expression that contains a
variable or property to which the step assigns the retrieved value. In some
cases, you must specify a channel name for the value to retrieve.

Instrument Session Manager


IVI-C step types use a software component, National Instruments Session
Manager, to share named instrument connections. Use Session Manager to
share instrument connections in code modules that you write, even if you
do not use IVI-C step types. Refer to the NI Session Manager Help for more
information by selecting StartAll ProgramsNational Instruments
Session ManagerNI Session Manager Help.
Note Currently available drivers do not allow you to use the same instrument driver

session in more than one operating system process simultaneously.

NI TestStand Reference Manual

D-6

ni.com

Appendix D

IVI-C Step Types

IVI Dmm
Use the IVI Dmm step type to perform single-point and multipoint
measurements with digital multimeters.

Step Operations
The IVI Dmm step type supports the following operations:

ConfigureConfigures the instrument to match the state as specified


by the step.

Show Soft Front PanelDisplays the SFP for the instrument.

Hide Soft Front PanelHides the SFP for the instrument.

ReadInitiates and returns a measurement from an instrument.

InitiateInitiates a measurement.

FetchReturns the measured value from a measurement that the


Initiate operation has started.

AbortCancels the wait for a trigger.

Send SW TriggerSends a software trigger command to trigger the


instrument.

Get InformationRetrieves low-level status and information from


the instrument.

Refer to the NI TestStand Help for more information about each of these
operations.

Step Properties
In addition to the common custom properties, the IVI Dmm step type
defines the following step properties:

Step.Result.ReadingContains the measurement values for the Read


and Fetch operations. The property data type is NI_IviSinglePoint or
NI_IviWave.

Step.LogicalNameContains the logical name expression.

Step.InstrOperationContains a value that specifies the operation


the step is configured to perform.

Step.SettingsSourceContains the name of the property or variable


where the step loads and stores the settings for the operation.

Step.ConfigurationContains the settings for the Configure


operation. The data type of this property is NI_IviDmmConfig.

National Instruments Corporation

D-7

NI TestStand Reference Manual

Appendix D

IVI-C Step Types

Step.SoftFrontPanelContains the settings for the Show Soft Front


Panel operation. The data type of this property is
NI_IviSoftFrontPanel.

Step.ReadingsContains the settings for the Read and Fetch


operations.

Step.GetInfoContains the settings for the Get Information


operation.

IVI Scope
Use the IVI Scope step type to acquire a voltage waveform from an analog
input signal with oscilloscopes.

Step Operations
The IVI Scope step type supports the following operations:

ConfigureConfigures the instrument to match the state as specified


by the step.

Show Soft Front PanelDisplays the SFP for the instrument.

Hide Soft Front PanelHides the SFP for the instrument.

ReadInitiates and returns a measurement from an instrument.

InitiateInitiates a measurement.

FetchReturns the measured value from a measurement that the


Initiate operation has started.

AbortCancels the wait for a trigger.

Auto SetupPerforms an automatic setup on the instrument.

Get InformationRetrieves low-level status and information from


the instrument.

Refer to the NI TestStand Help for more information about each of these
operations.

NI TestStand Reference Manual

D-8

ni.com

Appendix D

IVI-C Step Types

Step Properties
In addition to the common custom properties, the IVI Scope step type
defines the following step properties:

Step.Result.ReadingContains the measurement values for the Read


and Fetch operations. This property is an array of container, and the
size of the array is equal to the number of channels specified for the
Read or Fetch operation. The data type of each element of the array
is NI_IviSinglePoint, NI_IviWave, or NI_IviWavePair.

Step.LogicalNameContains the logical name expression.

Step.InstrOperationContains a value that specifies the operation


the step is configured to perform.

Step.SettingsSourceContains the name of the property or variable


where the step loads and stores the settings for the operation.

Step.ConfigurationContains the settings for the Configure


operation. The data type of this property is NI_IviScopeConfig.

Step.SoftFrontPanelContains the settings for the Show Soft Front


Panel operation. The data type of this property is
NI_IviSoftFrontPanel.

Step.ReadingsContains the settings for the Read and Fetch


operations. The data type of this property is NI_IviScopeReadings.
The Channels subproperty is an array of type NI_IviScopeChannel.

Step.GetInfoContains the settings for the Get Information


operation.

IVI Fgen
Use the IVI Fgen step type to instruct function generators to generate
predefined waveforms or custom waveforms using arbitrary waveform
generators.

Step Operations
The IVI Fgen step type supports the following operations:

ConfigureConfigures the instrument to match the state as specified


by the step.

Show Soft Front PanelDisplays the SFP for the instrument.

Hide Soft Front PanelHides the SFP for the instrument.

InitiateInitiates signal generation if the instrument is idle.

National Instruments Corporation

D-9

NI TestStand Reference Manual

Appendix D

IVI-C Step Types

AbortAborts a previously configured output and returns the


function generator to the idle state.

Send SW TriggerSends a software trigger command to trigger the


instrument.

Get InformationRetrieves low-level status and information from


the instrument.

Refer to the NI TestStand Help for more information about each of these
operations.

Step Properties
In addition to the common custom properties, the IVI Fgen step type
defines the following step properties:

Step.LogicalNameContains the logical name expression.

Step.InstrOperationContains a value that specifies the operation


the step is configured to perform.

Step.SettingsSourceContains the name of the property or variable


where the step loads and stores the settings for the operation.

Step.ConfigurationContains the settings for the Configure


operation. The data type of this property is NI_IviFgenConfig.

Step.SoftFrontPanelContains the settings for the Show Soft Front


Panel operation. The data type of this property is
NI_IviSoftFrontPanel.

Step.GetInfoContains the settings for the Get Information


operation.

IVI Power Supply


Use the IVI Power Supply step type to instruct power supplies to control
the output voltages and currents and to measure output values at the output
terminals.

Step Operations
The IVI Power Supply step type supports the following operations:

NI TestStand Reference Manual

ConfigureConfigures the instrument to match the state as specified


by the step.

Show Soft Front PanelDisplays the SFP for the instrument.

Hide Soft Front PanelHides the SFP for the instrument.

D-10

ni.com

Appendix D

IVI-C Step Types

MeasureTakes a measurement on the output signal and returns the


measured value.

InitiateMakes the power supply wait for a trigger.

AbortCancels the wait for a trigger.

Send SW TriggerSends a software trigger command to trigger the


instrument.

Reset Output ProtectionResets the power supplys output


protection on a specific channel after an overvoltage or overcurrent
condition occurs.

Get InformationRetrieves low-level status and information from


the instrument.

Refer to the NI TestStand Help for more information about each of these
operations.

Step Properties
In addition to the common custom properties, the IVI Power Supply step
type defines the following step properties:

Step.Result.ReadingContains the measurement values for the


Measure operation. The property data type is an array of
NI_IviSinglePoint.

Step.LogicalNameContains the logical name expression.

Step.InstrOperationContains a value that specifies the operation


the step is configured to perform.

Step.SettingsSourceContains the name of the property or variable


where the step loads and stores the settings for the operation.

Step.ConfigurationContains the settings for the Configure


operation. The data type of this property is NI_IviDCPowerConfig.

Step.SoftFrontPanelContains the settings for the Show Soft Front


Panel operation. The data type of this property is
NI_IviSoftFrontPanel.

Step.ReadingsContains the settings for the Measure operation. The


data type of this property is NI_IviDCPowerReadings.

Step.GetInfoContains the settings for the Get Information


operation.

Step.ResetOutputProtectionContains the channel setting for the


Reset Output Protection operation.

National Instruments Corporation

D-11

NI TestStand Reference Manual

Appendix D

IVI-C Step Types

IVI Switch
The IVI Switch step type provides a high-level programming layer for
instruments that are compliant with the IVI Switch class and National
Instruments Switch Executive virtual devices. A switch is an instrument
that can establish a connection between two I/O channels. The IVI Switch
step type also supports IVI-compliant instruments that can perform trigger
scanning and trigger-synchronized establishing or breaking of the paths.
The IVI Switch step type allows you to connect and disconnect paths and
routes, determine the connectivity of two switches or the state of a route,
and query the state of the switch module or virtual device.

National Instruments Switch Executive


National Instruments Switch Executive is an intelligent switch
management and routing application that you can use with TestStand.
NI Switch Executive allows you to interactively configure switch devices
from multiple vendors as a single virtual device. You can also specify
intuitive names for each channel within the virtual switch device and use
the end-to-end routing feature to automatically find switch routes by
selecting the channels you need to connect.
Use the TestStand IVI Switch step type and Switching panel of the
Properties tab on the Step Settings pane to connect and disconnect routes
required for steps in sequences.

Switching Tab
The Switching panel of the Properties tab on the Step Settings pane
specifies a switching action that TestStand performs around the execution
of the step. This feature is available only if you install the National
Instruments Switch Executive software. Refer to the NI TestStand Help
for more information about the Switching tab on the Step Properties
dialog box.
For more information about NI Switch Executive, refer to ni.com/
switchexecutive.

Route Specification String


When you instruct TestStand to connect or disconnect routes defined
in an NI Switch Executive virtual device, you must specify a route
specification string. The syntax of a route specification string consists of a
series of routes delimited by ampersands (&). National Instruments Switch
NI TestStand Reference Manual

D-12

ni.com

Appendix D

IVI-C Step Types

Executive ignores whitespace characters between tokens in a route


specification string.
routeOrGroup { & routeOrGroup } { & routeOrGroup } . . .

where routeOrGroup is one of the following:

Route name

Route group name

Fully specified pathEnclosed in square brackets and consists of a


series of channels delimited by "->". The following shows the format
of a fully specified path:
[ channel {-> channel } {-> channel} . . . ]

A channel must be one of the following:

Channel alias name

Unique nameA combination of the IVI device logical name and IVI
channel name separated by a "/" delimiter

IVI channel name

Channels on either end of a bracketed, fully specified path must not be a


Configuration or a Hardwired channel. Only one end channel can be a
Source channel. The inner channels in a route specification string must be
either a Configuration or Hardwired channel. The following is an example
of a route specification string:
MyRouteGroup & MyRoute & [Dev1/CH3->CH4,CH4->R0]

Step Operations
The IVI Switch step type supports the following IVI switch operations:

Connect/DisconnectConnects or disconnects the Source and


Destination channels in the switch instrument.

Configure ScanConfigures the switch module for scanning.

Start ScanInitiates a scanning operation.

WaitBlocks operations until all switches debounce for an


instrument.

Configure SwitchConfigures channels as Configuration or Source


channels and configures specific paths between channels.

Send Software TriggerSends a software trigger command to


trigger the instrument during a Scanning operation.

National Instruments Corporation

D-13

NI TestStand Reference Manual

Appendix D

IVI-C Step Types

Abort ScanCancels a Scanning operation.

Get InformationRetrieves low-level status and information from


the instrument.

The IVI Switch step type supports the following Switch Executive
operations:

Connect/DisconnectConnects or disconnects switch routes for


a virtual device.

WaitBlocks operations until all switches debounce for a virtual


device.

Get InformationRetrieves low-level status and information from a


virtual device.

Refer to the NI TestStand Help for more information about each of these
operations.

Step Properties
In addition to the common custom properties, the IVI Switch step type
defines the following step properties:

NI TestStand Reference Manual

Step.LogicalNameContains the logical name expression.

Step.InstrOperationContains a value that specifies the operation


the step is configured to perform.

Step.SettingsSourceContains the name of the property or variable


where the step loads and stores the settings for the operation.

Step.IviOperationContains a value that specifies the operation the


step is configured to perform for IVI Switching mode.

Step.ConnectDisconnectContains the settings for the Connect/


Disconnect operation.

Step.SoftFrontPanelContains the settings for the Show Soft Front


Panel operation. The data type of this property is
NI_IviSoftFrontPanel.

Step.GetInfoContains the settings for the Get Information


operation.

Step.ScanningConfigContains the settings for the Configure Scan


operation.

Step.WaitContains the settings for the Wait operation.

Step.ConfigureContains the settings for the Configure operation.

D-14

ni.com

Appendix D

IVI-C Step Types

IVI Tools
Use the IVI Tools step type to perform low-level operations on
an instrument.

Step Operations
The IVI Tools step type supports the following operations:

Get Session InfoRetrieves low-level session references and API


class handles to the IVI instrument.

Show Soft Front PanelDisplays the SFP for the tool.

Hide Soft Front PanelHides the SFP for the tool.

InitInitializes the driver or I/O resource for the session.

CloseCloses the IVI session.

ResetPlaces the instrument in a known state.

Self TestCauses the instrument to perform a self-test.

Revision QueryQueries the instrument driver and instrument for


revision information.

Error QueryReturns instrument-specific error information.

Get Error InfoReturns error information for the last IVI error for
a session.

Set/Get/Check AttributesAllows you to set, query, or verify the


value of attributes.

Refer to the NI TestStand Help for more information about each of these
operations.

Step Properties
In addition to the common custom properties, the IVI Tools step type
defines the following step properties:

Step.LogicalNameContains the logical name expression.

Step.InstrOperationContains a value that specifies the operation


the step is configured to perform.

Step.SettingsSourceContains the name of the property or variable


where the step loads and stores the settings for the operation.

Step.SoftFrontPanelContains the settings for the Show Soft Front


Panel operation. The data type of this property is
NI_IviSoftFrontPanel.

National Instruments Corporation

D-15

NI TestStand Reference Manual

Appendix D

IVI-C Step Types

NI TestStand Reference Manual

Step.InitContains the settings for the Init operation.

Step.SelfTestContains the settings for the Self Test operation.

Step.SessionInfoContains the settings for the Get Session Info


operation.

Step.RevisionQueryContains the settings for the Get Revision


Query operation.

Step.ErrorQueryContains the settings for the Error Query


operation.

Step.ErrorInfoContains the settings for the Get Error Info


operation.

Step.AttributesContains the settings for the Set/Get/Check


Attributes operation.

D-16

ni.com

LabVIEW Utility Step Types

Check Remote System Status


Use the Check Remote System Status step type to determine whether
LabVIEW is running on a remote system and allows TestStand to connect
to it.

Step Properties
In addition to the common custom properties, the Check Remote System
Status step type defines the following step properties:

Step.RemoteHostSpecifies the computer name or IP address of the


remote computer.

Step.RemoteHostByExprSpecifies whether to allow the remote


host field to be entered by expression.

Step.PortNumberSpecifies the port number of the remote host.

Step.TimeoutSpecifies the number of seconds to wait to connect to


the remote computer.

Step.ServerCheckExprSpecifies the location to store a Boolean


value that indicates whether the remote system check passed.

Run VI Asynchronously
Use the Run VI Asynchronously step type to run a VI in a new thread in the
TestStand execution.

Step Properties
In addition to the common custom properties, the Run VI Asynchronously
step type defines the following step properties:

Step.RemoteHostSpecifies the computer name or IP address of the


remote computer.

Step.RemoteHostByExprSpecifies whether to allow the remote


host field to be entered by expression.

National Instruments Corporation

E-1

NI TestStand Reference Manual

Appendix E

LabVIEW Utility Step Types

Step.PortNumberSpecifies the port number of the remote host.

Step.TimeoutSpecifies the number of seconds to wait to connect to


the remote computer.

Step.VIModuleContains the settings for the VI that the step calls.

Deploy Library
Use the Deploy Library step type to deploy or undeploy shared variables
defined in a LabVIEW project library file to the local system.

Step Properties
In addition to the common custom properties, the Deploy Library step type
defines the following step properties:

NI TestStand Reference Manual

Step.OperationSpecifies whether the step deploys or undeploys


shared variables. Valid values are: 0 = Deploy and 1 = Undeploy.

Step.LibrariesSpecifies an expression for the path of the project


library file on the local computer to deploy or undeploy. The project
library must only define shared variables and cannot contain any VI
files.

E-2

ni.com

Instrument Drivers

An instrument driver is a set of software routines that control a


programmable instrument. Each routine corresponds to a programmatic
operation such as configuring, reading from, writing to, and triggering the
instrument. Instrument drivers simplify instrument control and reduce
test program development time by eliminating the need to learn the
programming protocol for each instrument. Instrument drivers exist
for a wide variety of instruments and can be used in many application
development environments.
For more information about instrument drivers and how to find and
download instrument drivers that are compatible with National Instruments
software, refer to the Instrument Driver Network at ni.com/idnet.

Plug and Play Drivers


Plug and Play drivers simplify controlling and communicating with your
instrument through a standard, simple programming model for all drivers.
Plug and Play drivers exist for both LabVIEW and LabWindows/CVI.

LabVIEW Plug and Play Instrument Drivers


A LabVIEW Plug and Play instrument driver is a set of VIs, where each VI
corresponds to a programmatic operation to the instrument. LabVIEW Plug
and Play instrument drivers are distributed with the block diagram source
code, so you can customize the VI for a specific application, if necessary.
You can create instrument control applications and systems by
programmatically linking instrument driver VIs on the block diagram.
LabVIEW Plug and Play instrument drivers usually use VISA functions to
communicate with instruments.
In TestStand, you can call VIs that use LabVIEW Plug and Play instrument
drivers. When you need to return a VISA reference to TestStand, so that you
can later pass the reference to a different VI code module that uses the same
instrument driver, store the reference in a TestStand variable of type
LabVIEWIOReference. You can also directly call VIs in an instrument
driver in TestStand.

National Instruments Corporation

F-1

NI TestStand Reference Manual

Appendix F

Instrument Drivers

LabWindows/CVI Plug and Play Instrument Drivers


LabWindows/CVI Plug and Play instrument drivers are based on the
VXIplug&play standard architecture and usually use VISA functions
to communicate with instruments. A LabWindows/CVI Plug and Play
instrument driver is a set of ANSI C software routines exported from a
dynamic link library (DLL). You can call these instrument drivers from
any development environment that supports calls into DLLs, such as
LabWindows/CVI, Microsoft Visual Basic, and Microsoft Visual Studio.
Additionally, you can use a LabWindows/CVI instrument driver in
LabVIEW if you convert the instrument driver using the Create VI
Interface to CVI Instrument Driver tool that you can download from the
Instrument Driver Network at ni.com/idnet.
In TestStand, you can call code modules that use LabWindows/CVI Plug
and Play instrument drivers. When you need to return a C-based reference
to TestStand, so that you can later pass the reference to a different code
module that uses the same instrument driver, store the reference in a
TestStand numeric variable. You can also directly call the functions in an
instrument driver in TestStand using the LabWindows/CVI or C/C++ DLL
adapter.

Interchangeable Virtual Instrument (IVI) Drivers


In 1998, National Instruments, along with several other companies, formed
the Interchangeable Virtual Instrument (IVI) Foundation. The IVI
Foundation was formed to propose formal standards for instrument drivers
and to address existing limitations of earlier approaches to instrument
driver design. IVI drivers implement state-caching to eliminate redundant
commands that may be sent to the instruments in your system. They can
also be configured to run in simulation mode, where the actual instrument
and the signal it acquires or generates is simulated in software.
One of the most important features of IVI drivers is their ability to allow
instruments to be interchanged in a system without modifying the test
software. The IVI Foundation has defined multiple classes of instruments:
DC power supplies, DMMs, function generators, oscilloscopes/digitizers,
power meters, RF signal generators, spectrum analyzers, and switches.
An IVI instrument driver that conforms to one of these classes may be
substituted with another instrument of the same class, regardless of
manufacturer or bus connection.
Each class driver defines a set of extensions that an instrument might
support, and each specific IVI driver implements the interface between the

NI TestStand Reference Manual

F-2

ni.com

Appendix F

Instrument Drivers

class driver and the specific instrument for the extensions that the
instrument supports. A development environment, such as LabVIEW or
LabWindows/CVI, can call into the class driver or directly into the specific
instrument driver.
The IVI Foundation defines two architectures for IVI drivers: IVI-C, which
is based on ANSI C, and IVI-COM, which is based on Microsoft COM
technology. Refer to ni.com/ivi for more information about IVI
instrument drivers.

IVI-C Instrument Drivers


IVI-C instrument class drivers and specific drivers can be called from
any development environment that supports calls into DLLs, such as
LabWindows/CVI, Microsoft Visual Basic, and Microsoft Visual Studio.
Many of the IVI-C instrument drivers have native LabVIEW generated
wrappers. Additionally, you can convert an IVI-C instrument driver using
the Create VI Interface to CVI Instrument Driver tool that you can
download from the Instrument Driver Network at ni.com/idnet.
TestStand also provides several IVI-C step types that allow you to
configure and acquire data from IVI-C class-compliant instruments.
TestStand only supports the following classes defined by IVI: DC power
supplies, DMMs, function generators, oscilloscopes, and switches.
National Instruments does not recommend using the IVI step types if you
must directly access functions exported from an IVI specific instrument
driver, limit the overhead in your test system, or share handles between
code modules that use different development environments. Refer to the
TestStand Help for more information about using the TestStand IVI-C step
types.

IVI-COM Instrument Drivers


You can call IVI-COM instrument class drivers and specific drivers from
any development environment that supports ActiveX, such as LabVIEW,
LabWindows/CVI, Microsoft Visual Basic, and Microsoft Visual Studio. In
TestStand, you can configure TestStand steps that use the ActiveX/COM
Adapter to access objects defined by IVI-COM drivers.
Note The TestStand IVI-C step types do not support IVI-COM instrument drivers.

National Instruments Corporation

F-3

NI TestStand Reference Manual

Technical Support and


Professional Services

Visit the following sections of the National Instruments Web site at


ni.com for technical support and professional services:

SupportOnline technical support resources at ni.com/support


include the following:

Self-Help ResourcesFor answers and solutions, visit the


award-winning National Instruments Web site for software drivers
and updates, a searchable KnowledgeBase, product manuals,
step-by-step troubleshooting wizards, thousands of example
programs, tutorials, application notes, instrument drivers, and
so on.

Free Technical SupportAll registered users receive free Basic


Service, which includes access to hundreds of Application
Engineers worldwide in the NI Discussion Forums at
ni.com/forums. National Instruments Application Engineers
make sure every question receives an answer.
For information about other technical support options in your
area, visit ni.com/services or contact your local office at
ni.com/contact.

Training and CertificationVisit ni.com/training for


self-paced training, eLearning virtual classrooms, interactive CDs,
and Certification program information. You also can register for
instructor-led, hands-on courses at locations around the world.

System IntegrationIf you have time constraints, limited in-house


technical resources, or other project challenges, National Instruments
Alliance Partner members can help. To learn more, call your local
NI office or visit ni.com/alliance.

If you searched ni.com and could not find the answers you need, contact
your local office or NI corporate headquarters. Phone numbers for our
worldwide offices are listed at the front of this manual. You also can visit
the Worldwide Offices section of ni.com/niglobal to access the branch
office Web sites, which provide up-to-date contact information, support
phone numbers, email addresses, and current events.

National Instruments Corporation

G-1

NI TestStand Reference Manual

Index
A

HTBasic, 1-7
debugging, 5-15
source code template, 5-2
specifying, 5-15
subroutine, passing and returning
data, 5-16
LabVIEW, 1-6
creating event handlers (table), 9-17
localization functions (table), 9-25
source code template, 5-2
TestStand Utility Functions Library
(table), 9-21
updating menus (table), 9-24
LabWindows/CVI, 1-6
creating event handlers (table), 9-17
localization functions (table), 9-25
source code template, 5-2
TestStand Utility Functions Library
(table), 9-21
updating menus (table), 9-24
.NET, 1-7, 5-7
configuring, 5-11
creating event handlers (table), 9-17
debugging .NET assemblies, 5-8
localization functions (table), 9-25
options for stepping out of Visual
Studio .NET, 5-9
source code template, 5-2
TestStand Utility Functions Library
(table), 9-21
updating menus (table), 9-24
overview, 1-6
Sequence, 1-7, 4-15
parameters, defining, 5-17
remote sequence execution, 5-17
setting up TestStand, 5-18
Windows 2000 SP4, 5-21

abort executions, 3-5, 3-6


Action step, status, 4-15
ActiveX control
interface pointer, obtaining, 9-16
using with DLLs, 5-5
ActiveX/COM Adapter, 1-7
compatibility options for Visual Basic, 5-13
configuring, 5-12
object reference, modifying, 12-6
registering and unregistering servers, 5-13
running and debugging servers, 5-12
ActiveX/COM server
compatibility options, 5-13
registering, 5-13
using, 5-13
adapter
ActiveX/COM, 1-7
configuring, 5-12
server
registering and unregistering, 5-13
running and debugging, 5-12
using with TestStand, 5-13
Visual Basic, compatibility
options, 5-13
C/C++ DLL, 1-7
creating event handlers (table), 9-17
localization functions (table), 9-25
source code template, 5-2
TestStand Utility Functions Library
(table), 9-22
updating menus (table), 9-24
changing (note), 4-7
code module, supporting, 5-1
configuring, 5-1

National Instruments Corporation

I-1

NI TestStand Reference Manual

Index

Windows XP SP2, 5-19


specifying, 5-17
source code templates, 5-2
application development environment
(ADE), 1-2
Application Manager control, 9-3
application settings
configuration file location, 9-30
custom, adding, 9-30
persisting, 9-29
application styles
multiple window, 9-27
no visible window, 9-28
single window, 9-26
user interface, 9-26
applications
Editor versus Operator Interface, 9-12
architecture of TestStand. See TestStand
architecture overview
arguments, command-line, 9-29
array
bounds, modifying, 12-3
dynamic sizing, 12-6
empty, 12-3
specifying size, 12-2
array property, 1-9
automatic result collection. See result
collection

Test UUTs entry point, A-35


utility sequences, A-28, A-31
utility subsequence, A-33
Batch Specification step, B-19
Batch Synchronization step, B-13
Break step, 4-18
built-in
data type, customizing, 12-9
property, 1-10
note, 3-1
sequence property, 1-13
note, 3-1
step properties, 4-3
step type
common custom properties, 4-5
customizing, 13-2
overview, 4-1
Button control
command connections, 9-9
description (table), 9-5
image connections, 9-11

C
C++ (MFC)
creating event handlers (table), 9-17
localization functions (table), 9-25
menu open notification methods
(table), 9-24
Utility Functions Library
using (table), 9-22
C/C++ DLL Adapter, 1-7, 5-3
Call Executable step, 4-22
call stack, 1-12
Call Stack pane, 3-6
callback
customizing, 8-2
empty sequence (note), 10-10
Engine, 1-16, 3-13, A-12, A-21, A-34
categorization, 10-6
predefined (note), 10-6

B
Batch process model, A-5, A-26
Configuration entry point, A-31
Engine callbacks, A-34
hidden Execution entry points, A-31
main Execution entry points, A-28
Model callbacks, A-32, A-33
sequences (figure), A-27
Single Pass entry point, A-41
Test UUTs Test Socket entry
point, A-38

NI TestStand Reference Manual

I-2

ni.com

Index

special requirements (note), 10-9


table, 10-7
Front-End, 1-16
modifying, 10-10
predefined (note), 10-10
Model, 1-16
Batch process model, A-32
defining, 10-3
Parallel process model, A-20
Sequential process model, A-9
process model, 10-3
sequence, 1-15, 10-5
sequence file, 2-1
table, 1-16
callback function. See required callback
functions
callback sequences, 1-15
Calling, 5-5
caption connection, 9-10
Case step, 4-19
changing control connections, 9-12
Check Remote System Status step, E-1
CheckBox control, description (table), 9-5
class step type property, 13-3
Cleanup step group, 1-11
client sequence file, 1-15
Close Database step type, C-2
Close SQL Statement step type, C-3
code module, 1-1
dynamic array sizing, 12-7
LabWindows/CVI Plug and Play
driver, F-2
parameters, accessing, 1-13
specifying, 4-7
verifying privileges, current user, 7-3
code template, 13-7
customizing, 13-9
legacy, 13-7
module adapters, 5-2
multiple, specifying, 13-9
new, creating, 13-9

National Instruments Corporation

step type, 1-11, 13-9


template location (table), 13-8
collecting results, 1-15, 3-7
ComboBox control
description (table), 9-5
list connections, 9-7
command connections, 9-9
invoking, 9-10
command-line arguments, 9-29
compare, sequence file, 2-2
Components directory, 8-4
subdirectories (table), 8-5
configuration
See also customizing TestStand
adapters, 5-1
configuration file, user interface, 9-30
remote sequence execution, 5-18
Windows 2000 SP4, 5-21
Windows XP SP2, 5-19
TestStand, 8-1
Configure menu, 8-11
sequence editor or user interface
startup options (table), 8-9
Configuration entry point, 1-15
Batch process model, A-31
entry point sequences, 10-5
Parallel process model, A-19
process model, A-4
Sequential process model, A-8
configuration file, location, 9-30
Configure Database Options entry point, A-8
Configure menu, 8-11
Configure Model Options entry point, A-8
Configure Report Options entry point, A-8
configuring TestStand, 8-8
connection string, storing, 6-5
connections
command, 9-9
invoking, 9-10

I-3

NI TestStand Reference Manual

Index

control
changing, 9-12
specifying, 9-12
information source
caption, 9-10
image, 9-11
numeric value, 9-12
list (table), 9-7
view, 9-7
container property, 1-9
fields, adding, 12-10
context menu, creating data types (table), 12-1
Continue step, 4-19
control connections
specifying and changing, 9-12
controls
manager
Application, 9-3
connecting, 9-3
ExecutionView, 9-4
SequenceFileView, 9-4
visible, 9-3
connecting, 9-6
table, 9-5
conventions used in the manual, xv
creating
Editor applications, 9-13
translator DLLs, 15-2
custom data types, 1-9
creating and modifying, 12-8
custom property, 1-10
See also step properties
built-in step types, 4-5
lifetime of, 3-3
result properties, 3-8
step, 1-10
custom sequence file translators, 15-1
custom sequence files
versioning, 15-14

NI TestStand Reference Manual

custom step type


See also step type
creating, 13-1
modifying, 13-1
new, creating, 13-2
custom substeps, 13-6
custom translators, 15-1
custom user interface
documenting, 9-32
custom user privileges, 7-3
customizing TestStand
callbacks, 8-2
data types, 8-2
process models, 8-1
step types, 8-2
Tools menu, 8-2
user interfaces, 8-1

D
data link
connection strings, 6-5
definition, 6-5
specifying, 6-13
using, 6-13
Data Operation step type, C-4
data source, 4-12
data type
See also built-in; step type; types
built-in, customizing, 12-9
common properties, 12-9
container, 12-2
creating
categories of types, 12-2
custom data type, 12-8
instances (table), 12-1
custom
creating, 12-8
data types
properties, 12-10
modifying, 12-8

I-4

ni.com

Index

customizing, 8-2
displaying, 12-3
local variables (table), 12-4
modifying, 12-5
named, 1-9, 12-2
simple, 12-2
single-valued, modifying, 12-5
standard named, 1-9
using, 12-7
using, 12-1
database, 6-1
adding support, 6-10
creating default result tables, 6-10
data links, 6-5
discarding results
on-the-fly database logging, 6-12
on-the-fly report generation, 6-18
fields and columns, 6-1
logging, 6-6
how to, 6-7
Logging property in sequence
context, 6-8
on-the-fly, 6-12
records and rows, 6-1
result tables
adding support for other database
management systems, 6-10
creating, 6-10
default TestStand table schema, 6-9
sessions, 6-3
specifying data links, 6-13
specifying schemas, 6-13
step type
Close Database, C-2
Close SQL Statement, C-3
Data Operation, C-4
Open Database, C-2
Open SQL Statement, C-2
Property Loader, C-6
loading from database, C-7
loading from file, C-6

National Instruments Corporation

tables, 6-1
technologies, 6-3
table, 6-4
viewing data, 6-12
database file, 6-5
Database Viewer, 6-12
result tables, creating, 6-14
debug
DLLs, 5-3
LabVIEW 7.1.1, 5-6
LabVIEW 8 or later, 5-5
loading subordinate, 5-6
options for stepping out of DLL
functions (table), 5-4
options for stepping out of functions
(table), 5-4
reading parameter information, 5-7
using Microsoft Foundation Class
(MFC) Library, 5-6
HTBasic Adapter, 5-15
.NET assemblies, 5-8
panes, 3-6
Defining, 7-3
Deploy Library step, E-2
deploying
custom sequence files, 15-16
translators, 15-15
deployment utility, 2-6, 14-1
configuring, 14-3
engine, deploying, 14-7
file
collection, 14-3
filtering, 14-3
guidelines, 14-6
identifying components for
deployment, 14-2
installable images, 14-2
installer, creating, 14-2
path references, 14-5
sequence file processing, 14-5
setup, 14-2

I-5

NI TestStand Reference Manual

Index

TestStand Engine, deploying, 14-7


user interface, distributing, 14-11
using, 14-3
VI processing, 14-4
workspace
adding dynamically called
files, 14-10
distributing tests, 14-8
workspace file, creating, 14-3
diagnostic tools (NI resources), G-1
directory
Component, 8-4
search order, 8-6
subdirectories (table), 8-5
process model files, structure, A-5
structure, 8-3
subdirectories
NI, 8-4
TestStand subdirectories (table), 8-3
User, 8-4
DisplayExecution event, 9-19
displaying
custom properties of step types, 13-10
data types, 12-3
DisplaySequenceFile event, 9-18
DLLs
debugging
LabVIEW 7.1.1, 5-6
LabVIEW 8 or later, 5-5
LabVIEW, 5-5
MFC, using, 5-6
reading parameter information, 5-7
subordinate, loading, 5-6
translator, 15-2
creating, 15-2
DMM step type, D-1, D-7
Do While step, 4-18
documentation
conventions used in manual, xv
NI resources, G-1

NI TestStand Reference Manual

documenting
custom user interfaces, 9-32
drivers, F-1
IVI, F-2
IVI-C, F-3
IVI-COM, F-3
LabVIEW Plug and Play, F-1
LabWindows/CVI Plug and Play, F-2
NI resources, G-1
Plug and Play, F-1
dynamic array sizing, 12-6

E
Edit substep, 13-5
editing
sequence files, 10-3
callback sequences, 10-5
entry point sequences, 10-5
normal sequences, 10-4
Editor applications, 9-12
creating, 9-13
Else If step, 4-17
Else step, 4-17
empty arrays, 12-3
End step, 4-19
engine, 1-6
deploying, 14-7
Engine callback, 1-16, 3-13
Batch process model, A-34
categorization, 10-6
Parallel process model, A-21
predefined (note), 10-6
Sequential process model, A-12
special requirements (notes), 10-9
table, 10-7
entry point
Configuration, 1-15, 10-5
Execution, 1-15, 3-4, 10-5
sequence, 10-5

I-6

ni.com

Index

error
flag, 4-6
run-time, 1-12, 4-6
caution, 4-4
handling, 3-18
standard data type, 12-7
step, 3-17
error handling
tanslators, 15-13
escape codes (table), 8-8
event handling
creating event handlers, 9-17
DisplayExecution event, 9-19
DisplaySequenceFile event, 9-18
ExitApplication event, 9-18
ReportError event, 9-18
shut down, 9-19
startup, 9-19
Wait event, 9-18
events
handling, 9-17
examples (NI resources), G-1
exceptions, 4-6
execution
aborting, 3-5
definition, 3-1
direct, 3-4
Execution window, 3-3
interactive, 3-5
remote sequence, 5-17
run-time errors, 3-17
starting, 3-4
step, order of actions (table), 3-14
terminating, 3-5, 3-6
execution debugging panes, 3-6
Execution entry point, 1-15, 3-4, 10-5
Batch process model, A-28
Parallel process model, A-17
Sequential process model, A-8

National Instruments Corporation

Single Pass, 10-1, A-3


Batch process model, A-41
Parallel process model, A-24
Sequential process model, A-14
Single Pass Test Socket entry point
Batch process model, A-31, A-43
Parallel process model, A-19, A-25
Test UUTs, 10-1, A-3
Batch process model, A-35
Parallel process model, A-22
Sequential process model, A-12
Test UUTs Test Socket entry point
Batch process model, A-31, A-38
Parallel process model, A-19, A-23
Execution object, 1-16
execution pointer, 3-1
Execution window, 3-3
ExecutionView Manager, 9-4
connecting views, 9-7
ExitApplication event, 9-18
ExpressionEdit control
caption connections, 9-10
ExpressionEdit control, description
(table), 9-5
expressions, 1-8
context-sensitive editing, 1-8
current user, verifying, 7-2
sequence context, using, 3-2
Expressions panel, 4-5

F
failure chain in reports, 6-16
failure of steps, 3-17
Fgen step type, D-1, D-9
fields, in databases, 6-1
file type
configuration, location, 9-30
database, 6-5
project, 2-5
string resource, 8-6

I-7

NI TestStand Reference Manual

Index

type palette, 11-4


workspace, 2-5
files, collecting, 14-3
firewall settings, 5-21
flag
error occurred, 4-6
property, 12-9, 13-4
Flow Control step type
Break, 4-18
Case, 4-19
Continue, 4-19
Do While, 4-18
Else, 4-17
Else If, 4-17
End, 4-19
For, 4-17
For Each, 4-18
Goto, 4-19
If, 4-16
Select, 4-19
While, 4-18
For Each step, 4-18
For step, 4-17
Front-End callback, 1-16
modifying, 10-10
predefined (note), 10-10
sequence file, 2-1
FTP Files step, 4-24

hidden Execution entry points


Batch process model, A-31
Parallel process model, A-19
HTBasic Adapter, 1-7
debugging, 5-15
specifying, 5-15
subroutine, passing and returning
data, 5-16

I
If step, 4-16
image connections, 9-11
information source connection
caption, 9-10
image, 9-11
numeric value, 9-12
Insertion Palette, 4-2
figure, 2-4, 4-2
note, 4-3
InsertionPalette control
description (table), 9-5
view connections, 9-7
installer, deployment utility, 14-2
instance step type property, 13-3
instrument drivers, F-1
IVI, F-2
IVI-C, F-3
IVI-COM, F-3
NI resources, G-1
Plug and Play, F-1
LabVIEW, F-1
LabWindows/CVI, F-2
Instrument Session Manager, D-6
interactive execution
nested, 3-5
root, 3-5
interactive mode, 3-5
interface pointer, obtaining, 9-16
IVI drivers, F-2

G
General panel, 4-3
global variables, definition
sequence file, 2-2
station global, 1-7
Goto step, 4-19

H
handling events, 9-17
help, technical support, G-1

NI TestStand Reference Manual

I-8

ni.com

Index

IVI-C
editing steps, D-2
extensions, D-4
operation settings, D-5
validating configuration, D-6
Instrument Session Manager, D-6
soft front panel, D-6
step type
DMM, D-1, D-7
Fgen, D-1, D-9
Power Supply, D-1, D-10
Scope, D-1, D-8
Switch, D-1, D-12
Tools, D-1, D-15
IVI-C drivers, F-3
IVI-COM drivers, F-3

LabWindows/CVI
creating event handlers (table), 9-17
localization functions (table), 9-25
menu open notification methods
(table), 9-24
Plug and Play drivers, F-2
user interface controls, 9-14
Utility Functions Library (table), 9-21
LabWindows/CVI Adapter, 1-6, 5-2
language, 9-25
setting, 8-7
legacy code template, 13-7
library
TestStand UI Controls, 9-9
TestStand Utility Functions, 9-15, 9-20
C++ (MFC) (table), 9-22
LabVIEW (table), 9-21
LabWindows/CVI (table), 9-21
localization functions (table), 9-25
.NET (table), 9-21
license checking, 9-13
lifetime
custom step properties, 3-3
local variables, 3-3
parameters, 3-3
Synchronization step types, B-4
link, data, 6-5
specifying, 6-13
using, 6-13
list connections (table), 9-7
ListBar control, description (table), 9-6
ListBar page, list connections, 9-8
ListBox control
connecting lists, 9-7
description (table), 9-6
list connections, 9-8
local variables, 2-4
data types (table), 12-4
lifetime, 3-3
sequence local, 1-12
localization, 9-25

K
KnowledgeBase, G-1

L
Label control
caption connections, 9-10
description (table), 9-5
Label step, 4-20
LabVIEW, E-1
creating event handlers (table), 9-17
localization functions (table), 9-25
menu open notification methods
(table), 9-24
Plug and Play drivers, F-1
user interface controls, 9-14
Utility Functions Library (table), 9-21
Utility step types
Check Remote System Status, E-1
Deploy Library, E-2
Run VI Asynchronously, E-1
LabVIEW Adapter, 1-6, 5-2
LabVIEW Utility step type, E-1

National Instruments Corporation

I-9

NI TestStand Reference Manual

Index

Lock step, B-5


logging, database, on-the-fly, 6-12
loop results, 3-12
Looping panel, 4-4

Utility Functions Library, using


(table), 9-22
mode, interactive, 3-5
Model callback, 1-16
Batch process model, A-32, A-33
defining, 10-3
overriding, 10-5
Parallel process model, A-20
report generation (table), A-49
Sequential process model, A-9
model sequence file, 2-1
modifying types, 11-1
module adapter, 1-6
See also adapter
Multiple Numeric Limit Test step, 4-11
multithreading, 1-16

M
main Execution entry points, Batch process
model, A-28
Main sequence, 1-14
Main step group, 1-11
manager controls
Application Manager control, 9-3
connecting, 9-3
visible controls, 9-6
ExecutionView Manager control, 9-4
SequenceFileView Manager control, 9-4
menu
Configure, 8-11
items, dynamic, inserting, 9-23
notification methods (table), 9-24
Tools
customizing, 8-2
modifying, 8-2
updating, 9-23
merge sequence file, 2-2
Message Popup step, 4-20
Microsoft Access
creating result tables, 6-14
example data link and result table
setup, 6-13
Open Database Connectivity
(ODBC), 6-3
specifying data link and schema, 6-13
Microsoft databases
ActiveX Data Objects (ADO), 6-3
Object Linking and Embedding Database
(OLE DB), 6-3
Microsoft Foundation Class (MFC)
DLL, using, 5-6

NI TestStand Reference Manual

N
named data type, 1-9
National Instruments support and
services, G-1
nested interactive execution, 3-5
.NET
creating event handlers (table), 9-17
localization functions (table), 9-25
menu open notification methods
(table), 9-24
.NET Adapter, 1-7, 5-7
configuring, 5-11
.NET assemblies, debugging, 5-8
object reference, modifying, 12-5
Utility Functions Library (table), 9-21
NI subdirectory, 8-4
NI support and services, G-1
normal sequence file, 2-1, 10-4
Notification step, B-10
Numeric Limit Test step, 4-9
step properties, 4-10
numeric value connection, 9-12

I-10

ni.com

Index

Property Browser, 4-5


Requirements, 4-5
Run Options, 4-3
Switching, 4-4
Synchronization, 4-4
Parallel process model, A-4, A-16
Configuration entry point, A-19
Engine callbacks, A-21
Execution entry points, A-17
hidden, A-19
Model callbacks, A-20
sequences (figure), A-16
Single Pass Test Socket entry
point, A-25
Single Pass entry point, A-24
Test UUTs Test Socket entry
point, A-23
Test UUTs entry point, A-22
utility sequences, A-17
utility subsequences, A-21
parameters
code module, 1-13
complex data types, 12-2
lifetime, 3-3
reading, 5-7
sequence, 1-12, 2-3
Pass/Fail Test step, 4-8
Plug and Play drivers, F-1
LabVIEW, F-1
LabWindows/CVI, F-2
pointer, execution, 3-1
Post Actions panel, 4-4
Post-Step substep, 13-5
Power Supply step, D-1, D-10
Preconditions panel, 4-5
Pre-Step substep, 13-5
privileges
See also user privileges
defining, 7-3

object
Execution, 1-16
SequenceContext, 1-8
Synchronization, B-1
common attributes, B-3
User, 7-3
Object Linking and Embedding Database
(OLE DB), 6-3
data links, using, 6-13
object reference properties, 12-5
Open Database Connectivity (ODBC)
Administrator, using, 6-13
data links, using, 6-13
database technology, 6-3
Open Database step type, C-2
Open SQL Statement step type, C-2
Operator Interface applications, 9-12
operator interface. See user interface
Output pane, 3-7

P
pane
Call Stack, 3-6
Output, 3-7
Sequences, 2-5
Steps, 2-3, 2-5
Threads, 3-6
Types, 2-2, 11-3
Variables, 2-2, 2-3, 2-4, 2-5, 3-6
View Types For, 11-3
Watch View, 3-7
Workspace, 2-5
panel
Expressions, 4-5
General, 4-3
Looping, 4-4
Post Actions, 4-4
Preconditions, 4-5

National Instruments Corporation

I-11

NI TestStand Reference Manual

Index

process model, 1-13, 10-1


architecture, A-1
Batch, A-5, A-26
Configuration entry point, A-31
Engine callbacks, A-34
hidden Execution entry point, A-31
main Execution entry point, A-28
Model callbacks, A-32, A-33
sequences (figure), A-27
Single Pass Test Socket entry
point, A-43
Single Pass entry point, A-41
Test UUTs Test Socket entry
point, A-38
Test UUTs entry point, A-35
utility sequence
hidden test socket Execution
entry point, A-31
main Execution entry
point, A-28
utility subsequence, A-33
callbacks, 10-3
common features, A-3
Configuration entry point, A-4
customizing, 8-1, 10-1
default, selecting, A-5
defining, 1-14
directory structure, A-5
editing, 10-3
Execution entry point, A-3
modifying (tip), 10-3
Parallel, A-4
Configuration entry point, A-19
Engine callbacks, A-21
Execution entry points, A-17
hidden Execution entry points, A-19
Model callbacks, A-20
sequences (figure), A-16
Single Pass Test Socket entry
point, A-25
Single Pass entry point, A-24

NI TestStand Reference Manual

Test UUTs Test Socket entry


point, A-23
Test UUTs entry point, A-22
utility sequences, A-17
utility subsequences, A-21
process flow (figure), A-2
process model location (table), A-3
Sequential, A-4, A-6
Configuration entry points, A-8
Engine callbacks, A-12
Execution entry points, A-8
Model callbacks, A-9
sequences (figure), A-7
Single Pass entry point, A-14
Test UUTs entry point, A-12
utility subsequences, A-11
specifying for sequence files, 10-2
station model, 1-14, 10-2
support files, installation (table), A-45
programming examples (NI resources), G-1
project file, 2-5
property, 1-7
See also data type; variables
array property, 1-9
built-in properties, 1-10
note, 3-1
sequence properties, 1-13
built-in step type properties
class step type properties, 13-3
instance step type properties, 13-3
built-in, note, 3-1
categories, 1-9
container property, 1-9
container, fields, adding, 12-10
custom, 1-10
built-in step types, 4-5
lifetime, 3-3
result, 3-8
step, 1-10
step type, 13-10
logging, 6-8
I-12

ni.com

Index

modifying
object references, 12-5
single-valued properties, 12-5
monitoring, 3-2
property-array property, 1-9
single-valued property, 1-9
standard result, 3-10
using in expressions, 1-8
Property Browser panel, 4-5
property flags. See flag
Property Loader step type, 4-23, C-6
loading from database, C-7
loading from file, C-6
property-array property, 1-9

report generation, 3-13


functions and sequences, A-47
header and footer (table), A-47
Model callbacks (table), A-49
report body (table), A-48
ReportError event, 9-18
ReportView control
description (table), 9-6
view connections, 9-7
required callback functions, 15-3
CanTranslate, 15-3
GetDescription, 15-4
GetExtension, 15-5
GetFileFormatVersion, 15-6
GetFileVersion, 15-8
GetTranslatorCount, 15-10
TranslateToSequenceFile, 15-11
Requirements panel, 4-5
resolving type conflicts, 11-2
resource file
loading (note), 8-7
string
creating, 8-6
customizing, 8-7
escape codes (table), 8-8
format, 8-7
result collection, 1-15
custom result properties, 3-8
disabling, 3-7
loop results, 3-12
report generation, 3-13
standard result properties, 3-10
subsequence results, 3-11
root interactive execution, 3-5
route specification string, D-12
rows, in databases, 6-1
Run Options panel, 4-3
Run VI Asynchronously step, E-1
run-time copy, 3-1

Q
query, record set, 6-2
Queue step, B-8

R
reading parameter information, 5-7
records, in databases, 6-1
remote sequence execution, 5-17
TestStand server, 5-18
security permissions (tip), 5-19
Windows 2000 SP4, 5-21
Windows XP SP2, 5-19
Rendezvous step, B-7
report
batch, 6-16
failure chain, 6-16
generating, on-the-fly, 6-17
result collection, 3-7
schema, XML, 6-18
special formatting (tip), 6-17
test report, implementation, 6-15
using test reports, 6-16

National Instruments Corporation

I-13

NI TestStand Reference Manual

Index

run-time error, 1-12


caution, 4-4
description, 3-17
error occured flag, 4-6
handling, 3-18

compare, 2-2
deploying, custom, 15-15
deployment utility, processing, 14-5
front-end callback, 2-1
global variable, 1-13
merge, 2-2
model, 2-1
normal, 2-1
special editing capabilities for process
model sequence files
callback sequences, 10-5
entry point sequences, 10-5
marking as process model, 10-3
normal sequence file, 10-4
specifying a process model file, 10-2
station callback, 2-1
type concepts, 11-3
type definitions, 2-2
types of sequence files, 2-1
versioning, custom, 15-14
views, 2-4
sequence file global variables, 2-2
sequence file translators, 15-1
See also required callback functions
creating translator DLLs, 15-2
custom, 15-1
deploying, 15-15
error handling, 15-13
examples, 15-13
using, 15-1
versioning, 15-14
Sequence File window, 2-4
figure, 2-4
sequence local variables, 1-12
sequence parameters, 1-12
SequenceContext object, 1-8
SequenceFileView Manager, 9-4
connecting views, 9-7
Sequences pane, 2-5
sequences, callbacks, 2-1

S
schema
See also database
specifying, 6-13
Scope step type, D-1, D-8
Select step, 4-19
Semaphore step, B-18
sequence, 1-1, 2-3
built-in step properties, 1-13
callbacks, 1-15, 10-5
entry point, 10-5
executing directly, 3-4
note, 3-4
files, 1-13
local variables, 1-12, 2-4
parameters, 1-12, 2-3
step groups, 1-11, 2-3
Sequence Adapter, 1-7, 4-15
parameters, defining, 5-17
remote sequence execution, 5-17
specifying, 5-17
Sequence Call step, 4-15
sequence context
Logging property, 6-8
using, 3-2
sequence editor, 1-1, 1-2
startup options
configuring, 8-8
table, 8-9
sequence execution, 1-16
See also execution
sequence file, 1-1
callbacks, 2-1
client, 1-15

NI TestStand Reference Manual

I-14

ni.com

Index

SequenceView control
view connections, 9-7
SequenceView control, description (table), 9-6
Sequential process model, A-4, A-6
Configuration entry points, A-8
Engine callbacks, A-12
Execution entry point, A-8
Model callbacks, A-9
sequences (figure), A-7
Single Pass entry point, A-14
Test UUTs entry point, A-12
utility subsequences, A-11
Session Manager, D-6
settings, custom application, 9-30
Setup step group, 1-11
shut down, 9-19
Single Pass Test Socket entry point
Batch process model, A-43
Parallel process model, A-25
Single Pass Execution entry point, 10-1, A-3
Batch process model, A-41
Parallel process model, A-24
Sequential process model, A-14
single-valued data type, 12-5
single-valued property, 1-9
software (NI resources), G-1
source code control (SCC), 2-6
source code template, 1-11, 5-2
See also code template
specifying control connections, 9-12
standard named data type, 1-9
using, 12-7
standard result property, 3-10
startup, 9-19
Statement step, 4-20
station callback sequence file, 2-1
station global variables, 1-7, 11-4
Station Globals window, 11-4

National Instruments Corporation

station model
definition, 1-14
process model file, 10-2
status
Action step, 4-15
step, 3-16
StatusBar control, description (table), 9-6
StatusBar pane
caption connections, 9-10
image connections, 9-11
numeric value connections, 9-12
step, 1-1, 1-10
execution, order of actions (table), 3-14
failure, 3-17
interactive execution, 3-5
step execution (table), 3-14
step group, 2-3
Cleanup, 1-11
Main, 1-11
Setup, 1-11
step properties
built-in, 4-3
Call Executable, 4-23
Case, 4-19
Check Remote System Status, E-1
Deploy Library, E-2
Do While, 4-18
Else If, 4-17
For, 4-17
For Each, 4-18
FTP Files, 4-24
If, 4-16
Label, 4-20
lifetime of custom step properties, 3-3
Message Popup, 4-21
Multiple Numeric Limit Test, 4-11
Numeric Limit Test, 4-10
Pass/Fail Test, 4-9

I-15

NI TestStand Reference Manual

Index

Run VI Asynchronously, E-1


Select, 4-19
String Value Test, 4-14
While, 4-18
step result, 3-7
See also result collection
custom properties (table), 3-8
standard properties (table), 3-10
Step Settings pane
Expressions panel, 4-5
General panel, 4-3
Looping panel, 4-4
Post Actions panel, 4-4
Preconditions panel, 4-5
Property Browser panel, 4-5
Requirements panel, 4-5
Run Options panel, 4-3
Switching panel, 4-4
Synchronization panel, 4-4
step status, 3-16
built-in step types, 4-6
failures, 3-17
standard values (table), 3-16
step type, 1-11
See also built-in step type; Database step
type; Flow Control step type; IVI step
type; LabVIEW Utility step type;
Synchronization step type
application-specific (note), 4-1
built-in, 4-1
common custom properties, 4-5
customizing, 13-2
code template, specifying, 13-9
common properties, 13-3
custom
creating, 13-1
modifying, 13-1
properties, 13-10
customizing, 8-2
database, C-1
module adapter, use, 4-7

NI TestStand Reference Manual

source code templates, 1-11


using, 4-1
Steps pane, 2-3, 2-5
string
connection, storing, 6-5
resource file
creating, 8-6
customizing, 8-7
default resource string files, 8-6
directory search order, 8-6
escape codes (table), 8-8
format, 8-7
route specification, D-12
user interface control, localization, 9-25
String Value Test step, 4-13
structured query language (SQL)
Close SQL Statement step type, C-3
Open Database step type, C-2
Open SQL Statement step type, C-2
SELECT command (queries), 6-2
SQL null value, 6-2
SQL statement data, 6-2
subdirectory
NI, 8-4
TestStand subdirectories (table), 8-3
User, 8-4
subsequence, 1-1
Utility, 10-4
subsequence results, property names (table),
3-11
substep
Edit, 13-5
implementing, 13-5
module, 13-5
source code for, 13-6
Post-Step, 13-5
Pre-Step, 13-5
support, technical, G-1
Switch Executive, route specification
string, D-12
Switch step type, D-1, D-12

I-16

ni.com

Index

Switching panel, 4-4


Synchronization object, B-1
common attributes
lifetime, B-4
name, B-3
timeout, B-4
Synchronization panel, 4-4
Synchronization step type, B-1, B-5
Batch Specification, B-19
Batch Synchronization
Enter and Exit Operations,
requirements, B-15
mismatched section, B-14
nested section, B-15
one thread only section, B-14
parallel section, B-14
serial section, B-14
synchronized section, B-13
Lock, B-5
Notification, B-10
Queue, B-8
Rendezvous, B-7
Semaphore, B-18
Thread Priority, B-17
Wait, B-11
synchronized section, B-13
system deployment, 2-6

technical support, G-1


template
code, 13-7
customizing, 13-9
location (table), 13-8
multiple, specifying, 13-9
new, creating, 13-9
legacy code, 13-7
source code, 1-11, 5-2
terminating executions, 3-5, 3-6
test executive, 1-1
test executive engine, 1-2
See also engine
test module. See code module
test report
See also report; report generation
implementing, 6-15
using, 6-16
Test UUTs Test Socket entry point
Parallel process model, A-23
Test UUTs entry point
Batch process model, A-35
definition, 10-1, A-8
Parallel process model, A-22
Sequential process model, A-12
tests, distributing, 14-8
TestStand architecture overview, 1-1
building blocks, 1-7
automatic result collection, 1-15
callback sequences, 1-15
process models, 1-13
sequence files, 1-13
sequences, 1-11
steps, 1-10
variables and properties, 1-7
general concepts, 1-1
software components
module adapters, 1-6
sequence editor, 1-2
TestStand Engine, 1-6

T
tables, 6-1
database result, 6-9
default result, creating, 6-10
query
record set, 6-2
SQL statement data, 6-2
records, 6-1
row
fields, 6-1
SQL null value, 6-2

National Instruments Corporation

I-17

NI TestStand Reference Manual

Index

TestStand User Interface (UI)


Controls, 1-6
user interface, 1-3
TestStand Deployment Utility. See
deployment utility
TestStand Engine. See engine
TestStand process models. See Batch process
model; Parallel process model; process
model; Sequential process model
TestStand Sequence Editor. See sequence
editor
TestStand User Interface (UI) controls. See
connections; manager controls; user
interface controls; visible controls
TestStand Utility Functions Library. See
Utility Functions Library
Thread Priority step, B-17
Threads pane, 3-6
Tools step type, D-1, D-15
training and certification (NI resources), G-1
translators, 15-1
See also required callback functions
custom, 15-1
deploying, 15-15
DLLs, 15-2
creating, 15-2
error handling, 15-13
examples, 15-13
using, 15-1
versioning, 15-14
troubleshooting (NI resources), G-1
type definitions, 2-2
type palette file, 11-4
types
See also built-in; data type; step type
creating, 11-1
modifying, 11-1
resolving conflicts, 11-2
storing, 11-1
Types Window, 11-3
versioning, 11-2

NI TestStand Reference Manual

Types pane, 2-2, 11-3


Types window, 11-3

U
UI Controls Library, 9-9
unit under test (UUT), 1-2
user interface, 1-3
application style
multiple window, 9-27
no visible window, 9-28
single window, 9-26
application styles, 9-26
creating, 9-1
See also connections; manager
controls; user interface controls;
visible controls
customizing, 8-1
tip, 9-2
deploying. See deployment utility
distributing, 14-11
documenting custom, 9-32
example user interfaces, 9-2
localization, 9-25
menu and menu items, 9-23
updating menus, 9-23
shutting down, 9-19
starting up, 9-19
startup options
configuring, 8-8
table, 8-9
user interface controls, 1-6, 9-2
user interface controls, 1-6, 9-2
interface pointer, obtaining, 9-16
LabVIEW, 9-14
LabWindows/CVI, 9-14
library, 9-9
Manager controls
Application Manager control, 9-3
ExecutionView Manager control, 9-4

I-18

ni.com

Index

SequenceFileView Manager
control, 9-4
TestStand API, using, 9-31
Visual C++, 9-15
Visual Studio .NET, 9-15
User Manager window, 7-1, 11-4
user manager, security (note), 7-1
User object, 7-3
user privileges
accessing
any user, 7-3
current user, 7-2
defining, 7-3
verifying, 7-2
User subdirectory, 8-4
using DLLs, 5-3
calling LabVIEW, 5-5
MFC, 5-6
Utility Functions Library, 9-20
C++ (MFC) (table), 9-22
LabVIEW (table), 9-21
LabWindows/CVI (table), 9-21
localization functions (table), 9-25
.NET (table), 9-21
utility sequence
Batch process model, A-28, A-31
Parallel process model, A-17
utility subsequences
Batch process model, A-33
Parallel process model, A-21
Sequential process model, A-11

sequence file global, 2-2


sequence local, 1-12
standard and custom data types, 1-9
station global, 1-7
Variables pane, 2-2, 2-3, 2-4, 2-5, 3-6
VariablesView control
description (table), 9-6
view connections, 9-7
VI processing, deployment utility, 14-4
view connections, 9-7
View Types For pane, 11-3
visible controls, 9-3
description of controls (table), 9-5
manager controls, connecting, 9-6
Visual Basic, ActiveX/COM server, 5-13
Visual C++, user interface controls, 9-15
Visual Studio .NET
accessing TestStand API, 5-11
.NET assemblies, debugging, 5-8
user interface controls, 9-15

W
Wait event, 9-18
Wait step, B-11
step properties, B-12
waiting for execution threads to
complete, B-12
Watch View pane, 3-7
Web resources, G-1
While step, 4-18
window
Execution, 3-3
Sequence File, 2-4
Station Global, 11-4
Types, 11-3
User Manager, 7-1, 11-4
Windows 2000 SP4
remote execution, setup, 5-21

V
variables
See also properties
expressions, using, 1-8
local, 2-4
data types (table), 12-4
lifetime, 3-3
monitoring, 3-2

National Instruments Corporation

I-19

NI TestStand Reference Manual

Index

Windows remote execution


2000 Service Pack 4, 5-21
XP Service Pack 2, 5-19
firewall settings, 5-21
Windows XP SP2
firewall settings, 5-21
remote execution, setup, 5-19
workspace file
adding dynamically called files, 14-10
creating, 14-3

NI TestStand Reference Manual

source code control, 2-6


tests, distributing, 14-8
Workspace pane, 2-5

X
XML report schema, 6-18

I-20

ni.com