TestStand II (Customization Course Manual).pdf

™

TestStand II: Customization Course Manual

Course Software Version 3.5 November 2005 Edition Part Number 323038D-01 TestStand II: Customization Course Manual Copyright © 2001–2005 National Instruments Corporation. All rights reserved. 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. Trademarks National Instruments, NI, ni.com, 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: Help»Patents in your software, the patents.txt file on your CD, or ni.com/legal/patents.

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 0 662 45 79 90 0, Belgium 32 0 2 757 00 20, Brazil 55 11 3262 3599, Canada 800 433 3488, China 86 21 6555 7838, Czech Republic 420 224 235 774, Denmark 45 45 76 26 00, Finland 385 0 9 725 725 11, France 33 0 1 48 14 24 24, Germany 49 0 89 741 31 30, India 91 80 51190000, Israel 972 0 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 095 783 68 51, Singapore 1800 226 5886, Slovenia 386 3 425 4200, South Africa 27 0 11 805 8197, Spain 34 91 640 0085, Sweden 46 0 8 587 895 00, Switzerland 41 56 200 51 51, Taiwan 886 02 2377 2222, Thailand 662 278 6777, United Kingdom 44 0 1635 523545 For further support information, refer to the Additional Information and Resources appendix. To comment on National Instruments documentation, refer to the National Instruments Web site at ni.com/info and enter the info code feedback.

Contents Student Guide A. B. C. D.

About This Manual ...............................................................................................viii What You Need to Get Started .............................................................................viii Course Goals.........................................................................................................ix Course Conventions ..............................................................................................x

Lesson 1 Using the TestStand API Utilizing the TestStand API ........................................................................................1-1 TestStand API .............................................................................................................1-2 TestStand API Objects................................................................................................1-3 API Classes .................................................................................................................1-4 API Inheritance ...........................................................................................................1-5 API Structure: Containment........................................................................................1-6 Methods and Properties ..............................................................................................1-8 PropertyObjects ..........................................................................................................1-9 Calling the TestStand API from Different Languages................................................1-10 Typical Uses of the TestStand API.............................................................................1-11 ActiveX/COM Adapter...............................................................................................1-12 TestStand API Resources............................................................................................1-14 Summary .....................................................................................................................1-18 Exercise 1-1 Utilizing the TestStand API..............................................................1-19

Lesson 2 Advanced User Management Login/Logout Procedure .............................................................................................2-2 Verifying User Privileges ...........................................................................................2-3 Creating/Deleting Users..............................................................................................2-4 Creating a New User...................................................................................................2-5 Configuring User Properties .......................................................................................2-7 Deleting an Existing User ...........................................................................................2-8 Summary .....................................................................................................................2-11 Exercise 2-1 A Creating a User Manager Tool with LabVIEW (Optional)..............2-12 Exercise 2-1 B Creating a User Manager Tool with LabWindows/CVI (Optional) .........................................................................................2-23

Lesson 3 Multithreading and Multi-UUT Testing Multithreading and Multi-UUT Testing .....................................................................3-1 Test System Concepts .................................................................................................3-2 Multihead Tester .........................................................................................................3-3 Definition—Multithreading ........................................................................................3-5

© National Instruments Corporation

iii


Contents

Multithreading in TestStand .......................................................................................3-7 Multithreading—Sequence Call Options....................................................................3-9 Synchronization Step Types ......................................................................................3-10 Types of Parallel Testing ............................................................................................3-16 Useful Process Models................................................................................................3-17 Batch Process Model ..................................................................................................3-18 Synchronized Sections ................................................................................................3-19 Batch Synchronized Sections .....................................................................................3-20 Synchronization Sections—Parallel ...........................................................................3-21 Synchronization Sections—Serial ..............................................................................3-22 Synchronization Sections—One-Thread-Only ...........................................................3-23 Parallel Process Model................................................................................................3-24 Implementing Synchronized Sections—Batch Synchronization Step Type...............3-25 Implementing Synchronized Sections—Synchronization Tab ...................................3-26 Identifying the Test Socket .........................................................................................3-27 Remote Execution.......................................................................................................3-29 Implementing Remote Execution ...............................................................................3-30 REngine Remote Server..............................................................................................3-31 Summary .....................................................................................................................3-33 Exercise 3-1 Using Synchronization Step Types ..................................................3-34 Exercise 3-2 Using the Parallel and Batch Process Models ..................................3-42 Exercise 3-3 Illustrating Remote Execution (Optional) ........................................3-49

Lesson 4 Modifying the Process Models and Overriding Callbacks Introduction.................................................................................................................4-1 What is a Process Model? (Review) ...........................................................................4-2 Default Process Model: (Review)...............................................................................4-3 Anatomy of a Process Model......................................................................................4-4 Modifying the Process Models—Callbacks ...............................................................4-7 Model Callbacks .........................................................................................................4-8 Process Model and Callbacks .....................................................................................4-10 Creating a Model Callback .........................................................................................4-11 Overriding Model Callbacks ......................................................................................4-12 Engine Callbacks ........................................................................................................4-13 Overriding Engine Callbacks......................................................................................4-16 Front-End Callbacks ...................................................................................................4-17 Modifying Process Models Directly ...........................................................................4-18 Summary .....................................................................................................................4-21 Exercise 4-1 Modifying and Overriding Callbacks...............................................4-22 Exercise 4-2 Editing a TestStand Process Model..................................................4-31


iv

ni.com

Contents

Lesson 5 Modifying the Operator Interface Introduction.................................................................................................................5-1 TestStand Operator Interfaces ....................................................................................5-3 TestStand User Interface (UI) Controls ......................................................................5-4 Manager Controls .......................................................................................................5-5 ApplicationMgr Control .............................................................................................5-6 SequenceFileViewMgr Control ..................................................................................5-7 ExecutionViewMgr Control .......................................................................................5-8 Visible TestStand User Interface Controls ................................................................5-9 Visible TestStand UI Controls ...................................................................................5-10 Connecting Visible and Manager Controls.................................................................5-11 View Connections.......................................................................................................5-12 List Connections .........................................................................................................5-13 Command Connections...............................................................................................5-14 Information Source Connections ................................................................................5-15 TestStand UI Controls in LabVIEW ..........................................................................5-16 TestStand UI Programming in LabVIEW .................................................................5-17 TestStand UI Controls in LabWindows/CVI..............................................................5-18 TestStand UI Programming in LabWindows/CVI......................................................5-19 What is a UIMessage? ................................................................................................5-22 How to Post a UIMessage...........................................................................................5-23 How to Detect Custom UIMessages ...........................................................................5-24 Summary .....................................................................................................................5-26 Exercise 5-1 A Building a LabVIEW Operator Interface .........................................5-27 Exercise 5-1 B Building a LabWindows/CVI Operator Interface ............................5-35 Exercise 5-2 A Handling Custom UIMessages in the LabVIEW Operator Interface.............................................................................5-45 Exercise 5-2 B Handling Custom UIMessages in the LabWindows/CVI Operator Interface.............................................................................5-52

Lesson 6 Modifying Result Collection and Report Generation Introduction.................................................................................................................6-1 Why Modify Result Collection? .................................................................................6-2 When and Where Results are Stored ..........................................................................6-3 What Results are Stored..............................................................................................6-4 View of Actual Results ...............................................................................................6-5 Subsequence Results...................................................................................................6-6 Modifying Result Collection ......................................................................................6-7 Method 1—AddExtraResult Method..........................................................................6-8 Method 2—Add Subproperty to Locals.ResultList ....................................................6-10 Method 3—Add Subproperty to Step.Result ..............................................................6-11 Formatting Results into a Report ................................................................................6-13 Customizing Report Generation .................................................................................6-14


v


Contents

Method 1—Configuring the Report Options Dialog Box ..........................................6-15 Method 2—Using Step.Result.ReportText .................................................................6-16 Method 3—Automatic Reporting Flags ....................................................................6-17 Method 4—Overriding Report Callbacks...................................................................6-18 Method 5—Modifying Test Report Callbacks and/or Report Generation Files ........6-19 Summary .....................................................................................................................6-21 Exercise 6-1 Modifying Result Collection Options ..............................................6-23 Exercise 6-2 Modifying Report Generation Options.............................................6-35

Lesson 7 System Design Projects Introduction.................................................................................................................7-1 Summary .....................................................................................................................7-10 Exercise 7-1 Dynamic Sequence Calling ..............................................................7-11 Exercise 7-2 Creating a Simple Process Model.....................................................7-12 Exercise 7-3 Storing LabVIEW References..........................................................7-13 Exercise 7-4 Passing Arguments to New Executions............................................7-14 Exercise 7-5 Time Delay Custom StepType .........................................................7-15 Exercise 7-6 Multithreading and Synchronization ................................................7-16 Exercise 7-7 Creating a Sequence Builder Tool....................................................7-17 Exercise 7-8 Asynchronous Report Generation ....................................................7-18

Appendix A Additional Information and Resources Course Evaluation


vi

ni.com

Student Guide Thank you for purchasing the TestStand II: Customization course kit. The course manual and the accompanying software are used in the two-day, hands-on TestStand II: Customization course. You can apply the full purchase of this course kit toward the corresponding course registration fee if you register within 90 days of purchasing the kit. Visit ni.com/training for online course schedules, syllabi, training centers, and class registration. For course manual updates and corrections, refer to ni.com/info and enter the info code rdts01.

Note

The TestStand II: Customization course is part of a series of courses designed to build your proficiency with NI TestStand and help you prepare for exams to become a NI Certified TestStand Developer and NI Certified TestStand Architect. The following illustration shows the courses that are part of the TestStand training series. Refer to ni.com/training for more information about NI Certification.

TestStand Series

TestStand I: Introduction

TestStand II: Customization


TestStand Advanced: System Design

vii


Student Guide

A. About This Manual This course covers advanced topics in TestStand, as well as how to customize TestStand to further meet your needs. You will learn some system design scenarios that are aimed to give you some direction and forethought before you start designing your test system. This course assumes that you have completed the TestStand I: Introduction course or have a good working knowledge of the fundamentals of programming with TestStand. A background knowledge of test executive software and a familiarity with either LabVIEW or C programming is also recommended. The course is divided into lessons that teach a topic or set of topics. Each lesson consists of the following: •

An introduction that describes the lesson objectives and the topics discussed.

•

A discussion of the topics.

•

A set of hands-on exercises that reinforce the concepts presented in the discussion. Some of the exercises are duplicated for LabVIEW and LabWindows™/CVI™ programming environments. For duplicate exercises, select the exercise that uses your preferred programming environment.

•

A summary that highlights the concepts covered in the lesson.

•

A self-review that allows you to test your mastery of the concepts covered in the lesson.

You can customize many of the topics discussed in this course to integrate further with your testing requirements.

Note

B. What You Need to Get Started Before you use this course manual, ensure you have all the following items: ❑ Computer running Windows 2000/NT/XP or later ❑ TestStand 3.5 or later ❑ LabVIEW 7.0 or later or LabWindows/CVI 7.0 or later ❑ TestStand II: Customization Course Manual


viii

ni.com

Student Guide

❑ TestStand II: Customization Course CD containing the following files: Filename

Description

Exercises

Folder for saving files created during the course and files necessary to complete some exercises

Solutions

Folder containing the solutions to all the course exercises

Installing the Course Software Install the course exercises and solutions by inserting the Course CD and extracting the contents of the self-extracting archives into the C:\Exercises\TestStand II directory. The solutions to all exercises should be installed in the C:\Solutions\TestStand II directory. The exercises in this course reinforce concepts presented in the lessons and provide additional explanations of the TestStand environment. Save your work in the C:\Exercises\TestStand II directory as you complete the exercises.

C. Course Goals This TestStand course teaches you the more advanced features and customizations of the TestStand environment. It begins with a discussion of the TestStand Application Programming Interface (API), then discusses more advanced features such as multithreading and multi-UUT test sytems. It also explains many of the customizable components within the TestStand environment. The course concludes by presenting ideas on possible system designs and implementations. This course prepares you to do the following: •

Use the TestStand API in designing your test system.

•

Configure TestStand applications to be used by different operators.

•

Develop customized TestStand applications.

•

Harness the power of testing multiple units under test.

•

Understand the different TestStand process models and how to modify them.

•

Customize report generation

•

Develop and customize an Operator Interface


ix


Student Guide

Introduction TestStand is a powerful, flexible test management software program. Built around an intuitive explorer-style interface and able to execute tests created in a variety of test development environments, TestStand allows you to build sophisticated testing programs customized to your exact needs.

D. Course Conventions The following conventions are used in this course manual: »

The » symbol leads you through nested menu items and dialog box options to a final action. The sequence File»Page Setup»Options 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.

bold

Bold text denotes items that you must select or click in the software, such as menu items and dialog box options, and text or characters that you should enter from the keyboard. Bold text also denotes parameter names.

italic

Italic text denotes variables, emphasis, a cross reference, or an introduction to a key concept. Italic text 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.


x

ni.com

1

Using the TestStand API

Lesson 1: Using the TestStand API In this lesson, you will learn: • What the TestStand API is • Common uses of the TestStand API • Where to find additional TestStand API resources

Utilizing the TestStand API This lesson describes how to utilize the TestStand Application Programming Interface (API) when you design test systems. The lesson explains the TestStand API, what classes and objects are available, describes common uses of the TestStand API, and shows where to find additional resources that document the methods and properties available to use in the TestStand API.


1-1


Lesson 1


TestStand API Operator Interfaces

Sequence Editor

Process Model

TestStand API

Code Modules

TestStand API The TestStand Engine exports an API that gives you a foundation on which to build a variety of test system components. You can use the TestStand API to access the internal data of TestStand sequences and steps or to create and control sequence executions. All the TestStand components are built on the TestStand API. The figure above shows typical clients of the TestStand API, which include components of TestStand and user-created code modules. The TestStand Engine is a dynamic linked library (DLL) that makes itself available to other applications according to the ActiveX automation specification. ActiveX automation implies a client/server relationship in which the client requests objects from the server and asks the server to perform actions on the objects.


1-2

ni.com

Lesson 1


TestStand API Objects Operator Interfaces

Sequence Editor

TestStand API SequenceFile Sequence Step

Execution SequenceContext

PropertyObject

Process Model

Report

Code Modules

TestStand API Objects The TestStand API is an object oriented API. An object is a service that an ActiveX server makes available to clients. Some of the more commonly used objects provided by the TestStand API are shown in the figure above. The connecting lines in the diagram indicate some of the objects that are used by the operator interfaces, sequence editor, process models, and code modules.


1-3


Lesson 1


API Classes Adapter

PropertyObjectFile

Thread

EditArgs

Report

TypeUsageList

Engine

Sequence

UIMessage

Execution

SequenceContext

User

InteractiveArgs

SequenceFile

UsersFile

InteractiveContext

Step

WorkspaceFile

PropertyObject

StepType

WorkspaceObject

API Classes A class defines a list of methods and properties that you can use with respect to the objects that you create as instances of that class. Of these classes, Engine is the only class for which you can create an object directly. The Engine class has methods for creating objects for the other classes. In some cases, you can obtain objects for one class from another class. For example, you can obtain a step object from the sequence object that contains the step.


1-4

ni.com

Lesson 1


API Inheritance TypeUsageList

PropertyObject Step

SequenceContext

Engine*

Sequence

User

* ActiveX Control

Execution

UIMessage

Report

EditArgs

Adapter

InteractiveArgs

Thread

InteractiveContext

PropertyObjectFile

WorkspaceFile

SequenceFile

WorkspaceObject

API Inheritance All classes in the TestStand API can inherit from the PropertyObject class. You can use PropertyObject methods and properties on objects of other classes. For example, you can use the PropertyObject.Name property to get the name of a SequenceFile object, Sequence object, or Step object. You also can create subproperties using the PropertyObject methods. For example, you can programmatically create a new subproperty of a step using the PropertyObject methods SetValNumber, SetValBoolean, or SetValString with the InsertIfMissing option. In most development environments, you must use the AsPropertyObject method to get a PropertyObject interface to the original object. LabWindows/CVI allows you to use the PropertyObject methods and property function without first obtaining the PropertyObject interface by using the AsPropertyObject method. Note


1-5


Lesson 1


API Structure: Containment SequenceFile ActiveX Objects • Methods • Properties

Sequence Any number per sequence file

Step Any number per sequence

API Structure: Containment In the TestStand API, many objects own or contain other types of objects. The figure above shows that a SequenceFile object contains Sequence objects, and Sequence objects in turn contain Step objects. •

Use the Engine.GetSequenceFile method to get a SequenceFile object.

•

Use the SequenceFile.GetSequence method to get a Sequence object.

•

Use the Sequence.GetStep method to get a Step object.


1-6

ni.com

Lesson 1


API Structure: Containment (Continued) Engine

Execution Thread

User

One or more per execution

Zero or one

SequenceContext

Adapter

One for each call stack entry in a thread

One or more

Report One per execution

API Structure: Containment (Continued) The figure above shows additional containment relationships between objects in the TestStand API.


1-7


Lesson 1


Methods and Properties • Method—Performs an operation or function on an object. • Property—Stores and maintains a setting or attribute of an object. Example Methods: • PropertyObject.GetValNumber • Engine.NewExecution • Engine.DisplayLoginDialog

Example Properties: • PropertyObject.Name • Engine.CurrentUser • Engine.BreakpointsEnabled

Methods and Properties After you obtain an object using the TestStand API, you can use methods and properties on the object as defined by the class of the object. •

Method—Performs an operation or function on an object.

•

Property—Stores and maintains a setting or attribute of an object.

•

Class—Analogous to a data type definition of a variable, such as double-precision floating-point or string, except that it applies to objects rather than variables.

•

Object—An instance of a class that is analogous to a variable of type double-precision floating-point or string.

For some classes, you can create objects directly. For other classes, you can only obtain objects by calling a method or property on an already existing object of another class. For example, Engine.GetSequenceFile returns a SequenceFile object.


1-8

ni.com

Lesson 1


PropertyObjects Hierarchical Collections of Properties • All API objects can be PropertyObjects except the Engine and the TypeUsageList • All variables and custom step properties are PropertyObjects

Use the PropertyObject methods to: • Get and set values • Enumerate, insert, or remove subproperties

Identify properties through a lookup string • Such as Step.Limits.High PropertyObjects TestStand defines a number of built-in properties that are always present for objects such as steps and sequences. Almost every object in TestStand has built-in properties. The built-in properties are static with respect to the API. In other words, the TestStand API has knowledge about each of these properties. The API employs this knowledge to make it easy for you to access these properties in the programming language you use. TestStand also allows you to define your own custom step properties, sequence local variables, sequence file global variables, and station global variables. Because the API has no knowledge of the variables and custom step properties that you define, these variables and properties are dynamic with respect to the API. The PropertyObject class allows developers to access dynamic properties and variables from within code modules. Rather than using defined constants, you use lookup strings to identify specific properties by name. For example, if you define a local variable named Channel, there is no method in the TestStand API called GetChannelValue( ). However, you can call a PropertyObject method such as GetValNumber(“Locals.Channel”, 0) to get the value of the variable, where “Locals.Channel” is the lookup string of the variable. The lookup string to a variable or property differs depending on which object you want to invoke the method on.


1-9


Lesson 1


Calling the TestStand API from Different Languages From LabVIEW • Property Get/Set VIs and LabVIEW Invoke and Property Nodes

From LabWindows /CVI •\API\CVI\tsapicvi.fp

From a step in a sequence • ActiveX/COM Adapter

From Visual C++ •\API\Mfc\tsapimfc.h

From other languages (VisualBasic, Java, Delphi, and so on) • Language-specific ActiveX support

Calling the TestStand API from Different Languages How you call the methods and access the properties of TestStand objects varies depending on the programming language you use. You can use the built-in ActiveX capabilities of your application development environment (ADE) to make calls to the TestStand API. LabVIEW and LabWindows/CVI have functions and controls that simplify the ActiveX interaction. LabVIEW contains common TestStand controls and functions on the TestStand palettes. The TestStand/LabVIEW components automatically install with TestStand. When you open the TestStand VIs, you can find the built-in LabVIEW Invoke Nodes and Property Nodes used within them. LabWindows/CVI includes an instrument driver, tsapicvi.fp, that contains C functions for all the methods and properties available in the TestStand API. You must load this instrument driver before it is available in LabWindows/CVI. You can load the tsapicvi.fp instrument driver from the \API\CVI directory.


1-10

ni.com

Lesson 1


Typical Uses of the TestStand API Code modules and step type modules • Access variables and properties

Operator interfaces • Start and monitor executions

Process models • Get report options and create reports

Custom add-in tools • Inspect or edit sequence files

Sequence editor • Build, execute, and debug sequence files

Typical Uses of the TestStand API Most often, you use the TestStand API to access TestStand variables and properties from their code modules. You pass the sequence context to the code module and use the PropertyObject methods to access the TestStand variables and properties. The PropertyObject methods use lookup strings to access the properties and variables of the sequence. You can use the TestStand API within your operator interfaces. The process models use the TestStand API to set the report after the report is created. The process models also use the API to instruct TestStand to include the limits and comparison types in the results. You can develop custom add-in tools to perform certain operations on a sequence or steps within a sequence. An example tool is the sequence file documentation generator or a tool that modifies certain aspects of each step in a sequence. Tools often need to use the TestStand API to gain direct access to the sequence and its steps to execute, inspect, or edit the sequence.


1-11


Lesson 1


ActiveX/COM Adapter • Allows calls to the TestStand API from within test sequences • Easy to use and can be very powerful

ActiveX/COM Adapter The ActiveX/COM Adapter in TestStand allows you to call all types of ActiveX servers. Not only can you call your own ActiveX servers that you may have written, but you also can make direct calls to the TestStand ActiveX Servers. Through the TestStand API you have access to hundreds of exported properties and methods, including the properties and methods the sequence editor and operator interfaces use in many of their operations. To use the ActiveX/COM Adapter to make a call to an ActiveX server, follow the guidelines below: •

Specify which server you want to manipulate.

•

Specify whether you want to access a property or call a method of that server.

•

Select the property or method you want to use.

•

Specify the input/output parameters, if there are any.

Using this adapter is convenient because you do not have to write any code to make calls to the TestStand ActiveX servers. To use the adapter, insert a step with the ActiveX/COM Adapter in the sequence and fill in the required fields. Also, with the large number of methods and properties available in the TestStand API, this combination can be a very powerful resource when creating test sequences or tools.


1-12

ni.com

Lesson 1


API Demo 1. Manually add a Message Popup step to the MainSequence of a new sequence file. Save the sequence file as launch.seq. 2. Create another sequence file and save the file as caller.seq. 3. In the MainSequence of the caller.seq file, add Action steps using the ActiveX/COM Adapter to call into the TestStand API and launch the launch.seq file in a new execution.You might need the following two methods to complete this step. • Engine.GetSequenceFileEx • Engine.NewExecution

In TestStand, ActiveX references are destroyed when the variables that hold them are out of scope. However, when using another ADE it might be important to close any references you obtain after you have finished using them. For more information about closing TestStand API references, refer to the TestStand Help. Note


1-13


Lesson 1


TestStand API Resources Select Help»TestStand Help and select TestStand API Reference Help on the Contents tab of the TestStand Help for more information about the TestStand API. The TestStand API Reference Help includes information about the following: • TestStand API overview • Writing an application • API-specific help

TestStand API Resources The TestStand API Reference Help is a valuable resource for learning more about the TestStand API and for information about specific properties and methods. There are many overviews available for discussing the high-level principles when working with ActiveX servers. The TestStand API Reference Help also includes a searchable index that contains detailed descriptions of all the methods and properties in the TestStand API. The Writing an Application with the TestStand Engine API section is useful for understanding the use of the TestStand API in the operator interfaces. Select Help»TestStand Help and browse to TestStand API Reference Help on the Contents tab to open the TestStand API Reference Help.


1-14

ni.com

Lesson 1


TestStand API Resources (Continued) The TestStand API Reference Help also contains information about how to use TestStand API objects.

TestStand API Resources (Continued) In the TestStand API, many objects reference other types of objects. From an object of one class, you can get an object of another class. For example, you can get a reference to the Engine, Thread, Execution, and Report objects from the SequenceContext object. In another example, a UIMessage object references an Execution object, and an Execution object references a SequenceFile object.

SequenceContext A SequenceContext object contains complete information about an execution at a particular point during the execution. TestStand gives you the option of passing a sequence context or its subproperties to your LabVIEW VI, .NET assembly, C function, or C/C++ DLL. You can use the sequence context to access all the objects, variables, and properties in the execution. From the sequence context, you also can obtain references to all the steps in the current sequence, the sequence contexts for the calling sequences, the process model entry point sequence, and the Main sequence in the client sequence file. All sequence context properties such as Engine, Thread, Execution, Report, SequenceFile, Sequence, SequenceContext, and Step are TestStand API objects. You can use the property path of an object as the ActiveX reference when you specify a step that uses the ActiveX/COM Adapter. In this manner, you can invoke methods and properties on these objects within your sequence.


1-15


Lesson 1


Engine Use the Engine class to create and access objects of other classes, to control executions, to display built-in dialog boxes, to implement a Tools menu, to find files and directories, and to invoke various utilities. One usage of this class is to write an operator interface. When you write an operator interface, create the Engine object directly using ActiveX. The Engine class is registered as TestStand.Engine in the TestStand installation. To access the Engine object from a step, use the API to get the value of the Engine property from the sequence context or pass the sequence context property RunState.Engine as an object parameter to the step. The previous figure includes only existing objects. It does not show how you can create new objects from the Engine object. Note


1-16

ni.com

Lesson 1


Exercise 1-1: Using the TestStand API Objective: To better understand the TestStand API and how to use it. Estimated Time: 45 minutes

Refer to page 1-19 for instructions for this exercise.


1-17


Lesson 1


Lesson 1 Summary • The TestStand API is widely used by the sequence editor and code modules • Use the ActiveX/COM Adapter to make API calls directly from test sequences • You also can call methods and properties of the TestStand API from within a test sequence or code module • Refer to the TestStand API Reference Help within the TestStand Help for more information about the TestStand API

Summary The TestStand API can be utilized by the sequence editor and operator interfaces and from test sequences and code modules. The ActiveX/COM Adapter is the recommended way to access the TestStand API from within test sequences. Using this adapter, you have access to all the exported properties and methods of the TestStand API. This is very useful because it allows the user to programmatically control the TestStand Engine. All the TestStand API properties and methods are documented in the TestStand API Reference Help.


1-18

ni.com

Lesson 1

Exercise 1-1 Objective:


Utilizing the TestStand API

To better understand the TestStand API and how to use it. In this exercise, you will use the TestStand API to programmatically create a new sequence file, insert a Message Popup step into the new sequence file, and execute the sequence file. You will use a variety of methods and properties from the TestStand API to perform this task. By the end of this exercise, you will be able to efficiently use all of the methods and properties from the TestStand API by understanding how to take advantage of these available API calls.

You can dynamically create sequences from within sequence files without using the sequence editor. It is important to remember that any test system that creates, modifies, or edits any sequence file using the TestStand API must have a TestStand development license registered for that computer. Note

Part A: Creating a New Sequence File and Inserting a Message Popup Step 1. Open the Ex 1-1 Utilizing the TestStand API.seq file located in the C:\Exercises\TestStand II directory. Additional Information In this exercise, you create all the steps for this sequence file. You opened an existing sequence file instead of creating a new one because the sequence file has a number of local variables which have been declared for you. Click the Locals tab to view the variables and their contents. 2. Select the ActiveX/COM Adapter from the Adapter ring control. 3. Insert an Action step and name it Load Type Palette Files. 4. Right-click the Load Type Palette Files step and select Specify Module from the context menu to open the Edit ActiveX/COM Call dialog box. Configure the Edit ActiveX/COM Call dialog box of the Load Type Palette Files step using the following information. Object Reference:

RunState.Engine

Automation Server:

NI TestStand API 3.5 (Ver 1.0)

Object Class:

Engine (IEngine)

Action:

Call Method

Method:

LoadTypePaletteFilesEx

Leave the parameters blank. © National Instruments Corporation

1-19


Lesson 1


Do not select the Create Object option, because a reference to the TestStand Engine object already exists and you can access this using the RunState.Engine property. Typically, the only time you must create a new Engine object reference is at the beginning of the code for writing an operator interface. Note

Additional Information To get the reference to a step in the type palette, you first must confirm that the step types are loaded into memory by calling the LoadTypePaletteFilesEx method of the Engine object class within the TestStand API. Notice that you can click the ? button to display the help information regarding the method or property you have selected in the TestStand API.

Tip

5. Click OK to close the Edit ActiveX/COM Call dialog box. 6. Insert another Action step below the Load Type Palette Files step. Name the Action step Create New Sequence File. 7. Right-click the Create New Sequence File step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

RunState.Engine

Automation Server:


Object Class:

Engine (IEngine)

Action:

Call Method

Method:

NewSequenceFile

Param (Return Value):

Locals.NewSeqFile

Additional Information This step uses the engine method NewSequenceFile to create a new sequence file and return a reference to it. You store the reference to the newly created sequence file in the Locals.NewStep local variable. 8. Click OK to close the Edit ActiveX/COM Call dialog box. 9. Insert another Action step below the Create New Sequence File step. Name the Action step Get MainSequence. 10. Right-click the Get MainSequence step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information.


1-20

ni.com

Lesson 1


Object Reference:

Locals.NewSeqFile

Automation Server:


Object Class:

SequenceFile

Action:

Call Method

Method:

GetSequenceByName


Locals.MainSeq

Param (sequenceNameParam):

"MainSequence"

Additional Information This step uses the sequence file reference you created in step 7 to get a reference to the MainSequence by calling the GetSequenceByName method. You use the Locals.MainSeq local variable to store a reference to the MainSequence. 11. Click OK to close the Edit ActiveX/COM Call dialog box. 12. Insert another Action step below the Get MainSequence step. Name the Action step Create New Instance of Step. 13. Right-click the Create New Instance of Step step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information to create a reference to a Message Popup step.


Object Reference:

RunState.Engine

Automation Server:


Object Class:

Engine (IEngine)

Action:

Call Method

Method:

NewStep


Locals.NewStep

Param (adapterKeyNameVal):

""

Param (stepTypeName):

"MessagePopup"

1-21


Lesson 1


Additional Information This step uses the engine method NewStep to create a new step and return a reference to it. You store the reference to the newly created step in Locals.NewStep. 14. Click OK to close the Edit ActiveX/COM Call dialog box. 15. Insert another Action step below the Create New Instance of Step step. Name the Action step Insert New Instance of Step. 16. Right-click the Insert New Instance of Step step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

Locals.MainSeq

Automation Server:


Object Class:

Sequence

Action:

Call Method

Method:

InsertStep

Param (stepToInsert):

Locals.NewStep

Param (index):

0

Param (stepGroupParam):

StepGroup_Main

Additional Information This step uses the step reference you created in step 13 and the sequence reference you created in step 10 to insert the step into the sequence using the InsertStep method. 17. Click OK to close the Edit ActiveX/COM Call dialog box. 18. Insert another Action step below the Insert New Instance of Step step. Name the Action step Set Name of New Step. 19. Right-click the Set Name of New Step step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

Locals.NewStep

Automation Server:



1-22

ni.com

Lesson 1


Object Class:

PropertyObject

Action:

Set Property

Property:

Name

Param (Name):

"Display Current User Login Name"

Additional Information This step uses the step reference you created in step 13 to set the name of the new step by treating the step reference as a PropertyObject and setting the Name property. You can treat a Step object as a PropertyObject because the Step class inherits from the PropertyObject class. Most TestStand classes inherit from the PropertyObject class and can therefore be treated as PropertyObjects. 20. Click OK to close the Edit ActiveX/COM Call dialog box. 21. Insert another Action step below the Set Name of New Step step. Name the Action step Save New Sequence File. 22. Right-click the Save New Sequence File step and select Specify Module from the context menu. Complete the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

Locals.NewSeqFile

Automation Server:


Object Class:

SequenceFile

Action:

Call Method

Method:

Save

Param (pathString):

Locals.PathString

Additional Information This step calls the Save method of the SequenceFile class to save a sequence file programmatically. This step saves the newly created sequence file to disk so that you will be able to access the sequence file after the execution has ended. The local variable named PathString specifies the path of the new file. The path has been specified for you. You can view or change it from the Locals tab. 23. Click OK to close the Edit ActiveX/COM Call dialog box.


1-23


Lesson 1


24. Insert another Action step below the Save New Sequence File step. Name the step Release New Sequence File. 25. Right-click the Release New Sequence File step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

RunState.Engine

Automation Server:


Object Class:

Engine(IEngine)

Action:

Call Method

Method:

ReleaseSequenceFileEx

Param (sequenceFileToRelease):

Locals.NewSeqFile

Additional Information Any time you use the NewSequenceFile method you must release the sequence file reference when you are through with it. You can release this reference using the ReleaseSequenceFileEx method of the Engine class in the TestStand API. 26. Click OK to close the Edit ActiveX/COM Call dialog box. Figure 1-1 shows the resulting sequence file.

Figure 1-1. Completed Sequence File


1-24

ni.com

Lesson 1


27. Save and execute the sequence by selecting Execute»Run MainSequence from the menu. 28. After the sequence executes, open the New Sequence File.seq file located in the C:\Exercises\TestStand II directory. The New Sequence File.seq file was created programmatically. Figure 1-2 shows the Message Popup step that you programmatically inserted into the new sequence file.

Figure 1-2. Programmatically Inserted Message Popup Step

29. Close the New Sequence File.seq file and keep the Ex 1-1 Utilizing the TestStand API.seq file open for Part B: Modifying Message Expressions.

End of Part A Part B: Modifying Message Expressions 1. Select the ActiveX/COM Adapter from the Adapter ring control. 2. Insert an Action step below the Set Name of New Step step in the Ex 1-1 Utilizing the TestStand API.seq file. 3. Name the step Set Message Expression of New Step. 4. Right-click the Set Message Expression of New Step step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:


Locals.NewStep

1-25


Lesson 1


Automation Server:


Object Class:

PropertyObject

Action:

CallMethod

Method:

SetValString

Param (lookupString):

"MessageExpr"

Param (options):

0

Param (newValue):

Locals.MessageExpr

Additional Information This step causes the message expression of the Message Popup step created in the new sequence to display the login name of the current user. The required message expression string has already been created and stored in Locals.MessageExpr for you. To set the message expression of the Message Popup step, treat the step reference as a PropertyObject and call the SetValString method of the PropertyObject class to set the MessageExpr property. 5. Click OK to close the Edit ActiveX/COM Call dialog box. Figure 1-3 shows the resulting sequence file.

Figure 1-3. Step Added to Sequence File

6. Select Execute»Run MainSequence to execute Ex 1-1 Utilizing the TestStand API.seq file.


1-26

ni.com

Lesson 1


After the sequence executes, open the New Sequence File.seq file located in the C:\Exercises\TestStand II directory. The New Sequence File.seq file was programmatically created. 7. Right-click the Display Current User Login Name step and select Edit Message Settings from the context menu to open the Configure Message Popup Step dialog box for the Message Popup step. Figure 1-4 shows the Configure Message Popup Step dialog box.

Figure 1-4. Configure Message Popup Step Dialog Box

8. Click OK to close the Configure Message Popup Step dialog box. 9. Close the New Sequence File.seq file. Keep the Ex 1-1 Utilizing the TestStand API.seq file open for use in Part C: Executing the New Sequence Using the TestStand API.

End of Part B Part C: Executing the New Sequence Using the TestStand API 1. Select the ActiveX/COM Adapter from the Adapter ring control. 2. Insert a new Action step below the Save New Sequence File step. Name the Action step Execute New Sequence. This step launches the new sequence that you have created so it executes in parallel to this sequence.


1-27


Lesson 1


3. Right-click the Execute New Sequence step and select Specify Module from the context menu. Use the following information to configure the Edit ActiveX/COM Call dialog box. Object Reference:

RunState.Engine

Automation Server:


Object Class:

Engine(IEngine)

Action:

Call Method

Method:

NewExecution


Locals.NewExecution

Param (sequenceFileParam):

Locals.NewSeqFile

Param (sequenceNameParam):

"MainSequence"

Param (processModelParam):

Nothing

Param (breakAtFirstStep):

False

Param (executionTypeMaskParam):

0

Leave the other parameter values blank. Additional Information This step creates a new execution object by calling the NewExecution engine method. When this step is executed, TestStand will begin executing the sequence specified by the parameter values. For more information about each individual parameter, refer to the TestStand API Reference section of the TestStand Help.

Note

4. Click OK to close the Edit ActiveX/COM Call dialog box. 5. Insert an Action step below the Execute New Sequence step you just inserted. Name the step Wait for New Execution to End. 6. Right-click the Wait for New Execution to End step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:


Locals.NewExecution

1-28

ni.com

Lesson 1


Automation Server:


Object Class:

Execution

Action:

Call Method

Method:

WaitForEndEx

Param (millisecondTimeOut):

–1

Param (processWindowsMsgs):

True

Leave the other parameter values blank. Additional Information The WaitForEndEx method of the Execution class pauses the execution of the current sequence while waiting for the new sequence to complete its execution. If you do not call this method, both sequences will continue their execution in parallel, which is desirable behavior in many circumstances. 7. Click OK to close the Edit ActiveX/COM Call dialog box. Figure 1-5 shows the resulting sequence file.

Figure 1-5. Completed Part C Sequence File

8. Save the file and select Execute»Run MainSequence to execute the Ex 1-1 Utilizing the TestStand API.seq file.


1-29


Lesson 1


9. A Message Popup dialog box containing the login name of the current user launches as shown in Figure 1-6. The login name should be administrator unless you logged into TestStand using a different login from the default login.

Figure 1-6. Message Popup Dialog Box

10. Click OK to close the Message Popup dialog box. 11. Save and close the files.

End of Part C End of Exercise 1-1


1-30

ni.com

Lesson 1


Self Review 1. What is the only class for which you can directly create an object?

2. Explain the concept of inheritance in terms of the TestStand API. List the only two classes that do not inherit from the PropertyObject class.

3. Give an example of an object that exhibits containment within TestStand.

4. Explain the difference between a method and a property, and give an example of each.

5. What is the PropertyObject class, and what is it used for?

6. Give three examples where the TestStand API is frequently used.

7. What is the purpose of the ActiveX/COM Adapter?

Activity Develop a small sequence that programmatically inserts a local

variable using the ActiveX/COM Adapter, the sequence context, and the PropertyObject class.


1-31


Lesson 1


Notes


1-32

ni.com

2

Advanced User Management

Note The material in this chapter is not covered in class. Feel free to read the material and complete the exercises outside of class.

Lesson 2: Advanced User Management In this lesson, you will: • Learn about the Login/Logout procedure • Use TestStand API to create and delete users • Use TestStand API to configure user privileges


2-1


Lesson 2


Login/Logout Procedure • Login/Logout functionality results from executing the LoginLogout sequence • The LoginLogout sequence is located in the FrontEndCallbacks.seq file

Login/Logout Procedure When you launch the sequence editor or any operator interfaces that come with TestStand, 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 displays the actual Login dialog box. When the user types in a user name and clicks OK, the method returns a user reference to the logged in user. This reference can be used to determine access privileges within the sequence editor or operator interfaces.


2-2

ni.com

Lesson 2


Verifying User Privileges CurrentUserHasPrivilege • Expression function and TestStand API method • Checks whether the current user has the specified privilege • CurrentUserHasPrivilege("Terminate")— Returns a Boolean value

Accessing Privileges of Any User • Engine.GetUser— Returns the user object • User.HasPrivilege—Returns a Boolean value

Verifying User Privileges There are several ways to verify what privileges a user has. To verify user privileges for the current user, either use the CurrentUserHasPrivileges expression function in the Expression Browser dialog box in a sequence or use the CurrentUserHasPrivileges method of the TestStand API to verify the privileges from a code module. This method behaves identically to the expression function, except that it takes additional parameters. When using either procedure to verify user privileges, the string argument is the specific property name that you are interested in verifying. Both procedures will return a Boolean value indicating whether the user has the specified privilege or not. You can pass a “*” as the string argument to determine if a user is currently logged in. You also can verify user privileges of any other user defined in the TestStand User Manager by first calling the Engine.GetUser method which returns the corresponding User object. When you have the User object, you can then call the User.HasPrivilege method to verify whether the user has the specified privilege. The HasPrivilege method behaves identically to the CurrentUserHasPrivilege method in that they both return a Boolean value.


2-3


Lesson 2


Creating/Deleting Users User Manager window vs. the TestStand API • Use the User Manager window when possible • When you cannot use the User Manager window, use the TestStand API methods/properties: – Creating TestStand users from a user database – Configure user management from the test floor

• You can use the user management methods/properties to create a tool or build functionality into the operator interface

Creating/Deleting Users The TestStand Engine maintains a list of users, along with their corresponding login names, passwords, and privileges. This capability of the TestStand Engine is called the user manager. Typically users are created, deleted, and configured from the user manager using the User Manager window which provides an easy-to-use interface for configuring the user manager. However, there are situations where it is not possible or convenient to use the User Manager window. When this is the case, there are some TestStand API methods and properties available to use for programmatically configuring the user manager. Next, you will learn how to programmatically create, configure, and delete users using the TestStand API.


2-4

ni.com

Lesson 2


Creating a New User 1. Specify the user information like user name, login name, group, and password. 2. Create a new user with the user information 3. Add the user to the appropriate group(s) 4. Get the UsersFile 5. Get the UserList from the UsersFile 6. Insert the new user 7. Update the UsersFile Note: You can perform the steps from a sequence, an operator interface, or a code module. Creating a New User For instances when the User Manager window does not meet your needs for creating new users, you can follow the list of steps above to use the TestStand API to insert new users. For more information regarding these TestStand API methods and properties, refer to the TestStand Help.


2-5


Lesson 2


Creating a New User (Continued)

Creating a New User (Continued) Here is an example of the functions you might call to create a user through the TestStand API.


2-6

ni.com

Lesson 2


Configuring User Properties • Methods and properties are available for configuring the user properties • Configurable properties include: – LoginName – FullName – Password – Privileges

Configuring User Properties You also can utilize the TestStand API to programmatically modify user properties of an existing user. To do this, you must obtain the User object, Engine.GetUser, for the user you wish to modify. Next, you will make the appropriate TestStand API call to set the corresponding property to its new value. Once you have made all the changes to a user, you should write the UsersFile back to disk. For example, to change a user’s password you can use the User object obtained above to access the TestStand API property, User.Password, and set it to the new value.


2-7


Lesson 2


Deleting an Existing User 1. 2. 3. 4. 5.

Determine the index of the user to delete Get the UsersFile Get the UsersList Delete the user Update the UsersFile

Note: You can perform the steps from a sequence, an operator interface, or a code module.

Deleting an Existing User Now that you have learned how to use the TestStand API to create new users and configure the properties of existing users, the last item to illustrate in this lesson is how to delete an existing user. The steps needed to delete a user are similar to those needed to create a new user. The following list shows the steps and the corresponding TestStand API calls. Step 1: Determine the zero-based index of the User object in the UsersList Step 2: Engine.UsersFile Step 3: UsersFile.UsersList Step 4: PropertyObject.DeleteElements Step 5: UsersFile.AsPropertyObjectFile PropertyObjectFile.WriteFile For more information regarding the TestStand API methods and properties, refer to the TestStand Help.


2-8

ni.com

Lesson 2


Deleting an Existing User (Continued)

Deleting an Existing User (Continued) This sequence is an example of deleting a user by using the TestStand API. You can determine the user index and user group index with the user manager. This example only removes the user from a single group, if a user belongs to multiple groups you must perform steps 7–9 for each group.


2-9


Lesson 2


Exercise 2-1A: Creating a User Manager Tool with LabVIEW (Optional) Exercise 2-1B: Creating a User Manager Tool with LabWindows/CVI (Optional) Objective: To create a sequence tool that displays, edits, adds, and removes TestStand users from the UserList. Estimated Time: 30 minutes Refer to page 2-12 for instructions for Exercise 2-1A. Refer to page 2-23 for instructions for Exercise 2-1B.


2-10

ni.com

Lesson 2


Lesson 2 Summary • Login/Logout procedure is handled by the LoginLogout sequence in the FrontEndCallbacks.seq file • You can check user privileges using the following TestStand API methods: –CurrentUserHasPrivilege –HasPrivilege • You can use the TestStand API to programmatically create, configure, and delete users

Summary This lesson has explained how the Login/Logout procedure takes place. It also has explained how TestStand can verify user privileges using the TestStand API when a user has logged in through the LoginLogout Front-End callback sequence. Lastly, the lesson showed you how to create, configure, and delete users programmatically using the TestStand API.


2-11


Lesson 2


Exercise 2-1A Creating a User Manager Tool with LabVIEW (Optional) Objective:

To create a sequence tool that displays, edits, adds, and removes TestStand users from the UserList. This exercise demonstrates how to use some of the methods and properties of the TestStand API UsersFile class to display, edit, add, and remove users from the TestStand UserList. This exercise uses LabVIEW to create a user manager tool. Use the VIs located on the ActiveX palette for performing functions such as opening and closing references to ActiveX servers and invoking methods and properties on ActiveX objects.

Part A: Displaying Existing Users Each user in TestStand has a User object that represents the data and privileges that TestStand associates with that user. You can obtain the User object for each user from the UserList property, which returns an array of User objects. By indexing the UserList array, you can obtain each user element in the array and gather the information needed for each user. 1. Open the Ex 2-1A Creating User Manager Tool.seq file located in the C:\Exercises\TestStand II directory. 2. Right-click the Show Users step and select Edit Code from the context menu to open the front panel of the ShowUsers VI in LabVIEW. 3. Select Window»Show Block Diagram and modify the block diagram of the ShowUsers VI. a. Place a Property Node, located on the ActiveX palette, on the block diagram. Right-click an empty space on the block diagram to display the Functions palette. Click Search on the Functions palette toolbar to search for a specific palette, VI, or function.

Tip

Wire the output of the Sequence Context reference to the reference input of the Property Node. Right-click the Property terminal and select Properties»Engine from the context menu. b. Place another Property Node on the block diagram. Wire the Engine output of the first Property Node to the reference input of the new Property Node. Be sure to wire the error cluster between the Property Nodes. Right-click the Property terminal and select Properties»UsersFile from the context menu. c. Place another Property Node on the block diagram. Wire the UsersFile output from the previous Property Node to the reference input of the new Property Node. Wire the error cluster between the


2-12

ni.com

Lesson 2


Property Nodes. Right-click the Property terminal and select Properties»UserList from the context menu. Figure 2-1 shows the resulting block diagram.

Figure 2-1. Block Diagram with Property Nodes

4. Place an Invoke Node, located on the ActiveX palette, on the block diagram. 5. Wire the UserList output of the Property Node to the reference input of the Invoke Node. Right-click the Method terminal of the Invoke Node and select Methods»GetNumElements from the context menu. Wire the GetNumElements output to the Number of Users indicator. Wire the UserList reference output to the For Loop. Wire the error cluster to the Close Reference function. Wire the GetNumElements reference output to the border of the For Loop. 6. Wire the UsersFile reference output of the UsersFile Property Node to the reference input of the Close Reference function to close the reference. 7. Wire the Engine reference output of the Engine Property Node to the reference input of the Close Reference function to close the reference.


2-13


Lesson 2


8. Wire the error cluster output of the Close Reference function to the border of the For Loop. Figure 2-2 shows the resulting block diagram.

Figure 2-2. Block Diagram with Invoke Node

9. In this VI, the For Loop goes through each user element and obtains the UserLogin string for each user. Complete the following steps to add the TS.User control to the For Loop. The TS.User control is used for the type input on the Variant to Data function. a. Select Window»Show Front Panel to switch to the front panel. b. Place an Automation Refnum, located on the Refnum palette, on the front panel. c. Right-click the refnum control and select Select ActiveX Class» Browse from the context menu. d. Select NationalInstruments.TestStand.Interop.API from the list of type libraries. e. Remove the checkmark from the Show Creatable Objects Only checkbox, if necessary, and select the User object from the list of TestStand objects. f. Click OK to store your changes. The TS.User icon now appears on the block diagram and you can wire it to the type input of the Variant to Data function. g. Select Window»Show Block Diagram and modify the For Loop as shown in Figure 2-3.


2-14

ni.com

Lesson 2


Figure 2-3. Block Diagram with Finished For Loop

10. Make sure you close all the ActiveX references you created. Figure 2-4 shows the resulting block diagram.

Figure 2-4. Completed Block Diagram

11. Select Window»Show Front Panel and adjust the scroll bars of the front panel so the Login User Names and Number of Users indicators and OK button are clearly visible when the VI is called from TestStand, as shown in Figure 2-5.


2-15


Lesson 2


Figure 2-5. Front Panel

12. Save and close the VI.

End of Part A Part B: Adding New Users You can add a new user to the TestStand UserList by inserting a new User object into the UserList. The DisplayNewUserDialog method of the TestStand API provides a simple wizard to create a new User object. After the new user is added, save the new user to file by calling the WriteFile method of the TestStand API to add the new user to the Users.ini file. 1. Within the Ex 2-1A Creating User Manager Tool.seq file, right-click the Add User step and select Edit Code from the context menu to open the Add User VI in LabVIEW. 2. Select Window»Show Block Diagram and complete the following steps to modify the block diagram of the Add User VI to add a new user programmatically. a. Use the Sequence Context reference as an input to a Property Node to obtain a reference to an Engine object. b. Use the Engine object reference as an input to an Invoke Node to call the DisplayNewUserDialog method of the TestStand API. This method displays the TestStand New User dialog box and allows you to create a new User object. c. Use the string constant "Enter New User" for the dlgTitle parameter and the Boolean value True for the modalToAppMainWind parameter.


2-16

ni.com

Lesson 2


Figure 2-6 shows the resulting block diagram.

Figure 2-6. Adding a User

3. Take the new User object obtained from the previous step, add it to the UserList array, then programmatically save the UsersFile to disk. Add the code to perform these actions within the True case of the Case structure, as shown in Figure 2-7. Note When you use a TestStand API Numeric Constant, you can change the value. The TestStand API Numeric Constant is located on the TestStand palette.

Figure 2-7. True Case Structure


2-17


Lesson 2


4. Open the False case of the Case structure and wire the IEngine and Error inputs to the corresponding Case structure outputs. Return to the True case. 5. Wire the Engine reference and error out cluster from the Case structure to the Close Reference function to release the Engine reference. Figure 2-8 shows the resulting Add User VI.

Figure 2-8. Final Add User VI Block Diagram

6. Save the VI. You can also add users by invoking the GetUserProfile and NewUser methods of the Engine class. With this method, you set the LoginName and Password properties for the user and then add the user to the UserList programmatically. Note

End of Part B Part C: Editing Existing Users You can modify the properties of an existing user with the DisplayPropertiesDialog method of the TestStand API. This method allows you to modify the properties of existing users and automatically saves the UsersFile for you. 1. Within the Ex 2-1A Creating User Manager Tool.seq file, right-click the Edit User step and select Edit Code from the context menu to open the Edit User VI in LabVIEW.


2-18

ni.com

Lesson 2


Modify the block diagram of the Edit User VI to programmatically edit the properties of an existing user. Additional Information This VI consists of a While Loop and a Case structure. The While Loop continuously runs the VI until the user clicks OK or Cancel and determines whether the LoginName the user specified exists in the UserList. If the LoginName exists, the True case of the Case structure calls the appropriate methods and properties to allow the user to edit the corresponding user properties. 2. Modify the True case of the Case structure to allow for editing the properties of the specified user, as shown in Figure 2-9.

Figure 2-9. True Case Structure

3. Save and close the VI and return to the sequence editor.

End of Part C Part D: Deleting Existing Users Just as you can add users to the user list, you can also delete users from the user list by removing the corresponding element. Since each user is referenced in the UserList array by an index, determine which user element to remove from the array by searching the UserList array for the specified LoginName and deleting the element corresponding to that user. 1. Within the Ex 2-1A Creating User Manager Tool.seq file, right-click the Delete User step and select Edit Code from the context menu to open the Delete User VI in LabVIEW. 2. Select Window»Show Block Diagram to display the block diagram of the VI. Additional Information This VI determines if a user with the specified LoginName exists and then reads all the user elements in the UserList array until it finds the


2-19


Lesson 2


matching user element. If the VI finds a matching user element, it deletes the user element and saves the UserList changes. Parts of this VI have already been completed for you.These parts include the portion of the code that verifies a user exists with the specified LoginName and the code that determines how many user elements there are in the UserList array. The main part of the VI is the For Loop which goes through the UserList array to find the matching user for the specified LoginName and then deletes the user when it is located. 3. Add functions to the While Loop to go through the UserList array to find the matching user for the specified LoginName. Complete the True case of the Case structure to include the necessary code. This code deletes the user element once it is located. Figures 2-10 and 2-11 show the resulting For Loop and Case structure with the necessary components.

Figure 2-10. Completed For Loop

Figure 2-11. Completed True Case Structure


2-20

ni.com

Lesson 2


4. Save and close the VI and return to the sequence editor. Save the sequence file.

End of Part D Part E: Using the User Manager Tool You have finished building the individual components of the User Manager tool. Because this tool is a sequence, you can run the tool from within the sequence editor or an operator interface. You can also add the tool to the Tools menu within the sequence editor or operator interface. 1. To add the new tool to the Tools menu in the sequence editor, select Tools»Customize. 2. From the Customize Tools Menu dialog box, click Add. 3. In the Add Tools Menu Item dialog box, select the options as shown in Figure 2-12.

Figure 2-12. Add Tools Menu Item Dialog Box

4. Click OK to return to the Customize Tools Menu dialog box. 5. In the Customize Tools Menu dialog box, specify the options and settings as shown in Figure 2-13.


2-21


Lesson 2


Figure 2-13. Customize Tools Menu Dialog Box

6. Enter "Add/Edit/Delete Users" in the Item Text Expression field before you select it in the Tools Menu listbox. Click OK to close the Customize Tools Menu dialog box. The tool appears under the Tools menu in the sequence editor and the default operator interface. 7. Select Tools»Add/Edit/Delete Users from the sequence editor menu to execute the User Manager tool.

End of Part E End of Exercise 2-1A


2-22

ni.com

Lesson 2


Exercise 2-1B Creating a User Manager Tool with LabWindows/CVI (Optional) Objective:

To create a sequence tool that displays, edits, adds, and removes TestStand users from the UserList. This exercise demonstrates how to use some of the methods and properties of the TestStand API UsersFile class to display, edit, add, and remove users from the TestStand UserList. This exercise uses LabWindows/CVI to create a user manager tool. Use the functions located in the TestStand API function panel, tsapicvi.fp, to perform functions such as opening and closing references to TestStand objects. You can also invoke methods and properties on the TestStand objects.

Part A: Displaying Existing Users Each user in TestStand has a User object that represents the data and privileges that TestStand associates with that user. You can obtain the User object for each user from the UserList property which returns an array of the User objects. By indexing the UserList array, you can obtain each user element in the array and gather the information needed for each user. 1. Open the Ex 2-1B Creating User Manager Tool.seq file located in the C:\Exercises\TestStand II directory. 2. Right-click the Show Users step and select Edit Code from the context menu. Add the ShowUser function and any additional functions needed to show all the TestStand users. All the LabWindows/CVI variables you need have been declared for you in the source code. 3. Insert the TS_SeqContextGetEngine function. Locate the function panel using the following list of classes: Instrument» TestStand API 3.5»Advanced»Sequence Context» Static Properties»Run State»Get Engine. Complete the parameters for this function as shown in Figure 2-14. Insert the function into the source code file.


2-23


Lesson 2


Figure 2-14. Reference to a TestStand Engine Object

The function call updates in the bottom of the Function Panel window as you type in the fields. Use the function call information to see how to complete the fields because the screen limitations do not allow all the text to display. Tip

After you have entered the function parameters select Code»Insert Function Call or press to insert the function into the source file. The function will be inserted at the cursor position, so ensure that the cursor is in the correct location, as specified by the source file comments.

Tip

Right-click in the Function Panel window to display the help for this function. Right-click each control to display the help for each parameter. Note

4. Use the Engine object to obtain a reference to the UsersFile property. Use the TS_EngineGetUsersFile function to obtain this reference. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced»Engine» Static Properties»Users»Get Users File. Use the following information to complete the parameters for the Get Users File function panel. Insert the function into the source code file.


2-24

ni.com

Lesson 2

Object Handle:

engine

Error Info:

&errorInfo

Users File Object:

&usersFile


5. You can obtain the UserList object from the reference to the UsersFile object. Use the TS_UsersFileGetUserList function to do this. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced»Users File» Static Properties»Get User List. Use the following information to complete the parameters for the Get User List function panel. Insert the function into the source code file. Object Handle:

usersFile

Error Info:

&errorInfo

List of Users:

&userList

6. To obtain each user from the UserList array, index through the elements in the UserList. First determine the number of elements in the array by using the TS_PropertyGetNumElements function. Locate the function panel using the following list of classes: Instrument» TestStand API 3.5»Property Object»Characteristics»Arrays» Get Num Elements. Use the following information to complete the parameters for the Get Num Elements function panel. Insert the function into the source code. Object Handle:

userList

Error Info:

&errorInfo

Number of Elements:

&numElements

7. Go through each element in the UserList array and obtain the corresponding User object. Use the TS_PropertyGetPropertyObjectByOffset function within the For Loop to go through each element in the UserList array. Locate the function panel using the following list of classes: Instrument» TestStand API 3.5»Property Object»SubProperties» Get Property Object By Offset. Use the following information to complete the parameters for the Get Property Object By Offset function panel. Insert the function into the source code.


Object Handle:

userList

Error Info:

&errorInfo

2-25


Lesson 2


Array Offset:

i

Options:

0

Object Value:

&user

8. To obtain the LoginName from each User object, call the TS_UserGetLoginName function. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced» User»Static Properties»Get Login Name. Use the following information to complete the parameters for the Get Login Name function panel. Insert the function into the source code. Object Handle:

user

Error Info:

&errorInfo

Login Name:

&loginName

9. Insert each LoginName into the listbox by calling the InsertListItem function. Select Library»User Interface» Controls/Graphs/Strip Charts»List (Label/Value) Controls» Insert List Ite to locate the function panel. Use the following information to complete the parameters for the Insert List Item function panel. Insert the function into the source code file. Panel Handle:

panelHandle

Control ID:

PANEL_LISTBOX

Item Index:

–1

Item Label:

loginName

Item Value:

0

The resulting ShowUser function should resemble the following code. Note

The following code is for illustration purposes only.

void __declspec(dllexport) _stdcall ShowUser(CAObjHandle seqContextCVI, short *errorOccurred, long *errorCode, char errorMsg[1024]) { int i,error = 0; static TSObj_UsersFile usersFile; static TSObj_Engine engine; static TSObj_Property user; static TSObj_Property userList;


2-26

ni.com

Lesson 2


ErrMsg errMsg = {'\0'}; ERRORINFO errorInfo; panelHandle = LoadPanelEx (0, "UserManagerTool.uir", PANEL, __CVIUserHInst); DisplayPanel (panelHandle); //get the engine reference TS_SeqContextGetEngine (seqContextCVI, &errorInfo, &engine); //get the usersfile reference TS_EngineGetUsersFile (engine, &errorInfo, &usersFile); //get the userlist reference TS_UsersFileGetUserList (usersFile, &errorInfo, &userList); //get the number of elements in the userlist i.e. number of users TS_PropertyGetNumElements (userList, &errorInfo, &numElements); //loop on the userlist and get the login names of all the users and display for (i=0; i
(usersFile); (engine); (user); (userList);

if (error < 0) { *errorOccurred = TRUE; } return; }


2-27


Lesson 2


10. Save the UserManagerTool.c file. Leave this source file open for use in Part B: Adding New Users.

End of Part A Part B: Adding New Users You can add a new user to the TestStand UserList by inserting a new User object into the UserList. The DisplayNewUserDialog method of the TestStand API provides a simple wizard to create a new User object. After you add the new user, save the new user to file by calling the WriteFile method of the TestStand API. This adds the new user to the Users.ini file. 1. Within the UserManagerTool.c source file, scroll to the AddUser function. Add the necessary code to add a new user programmatically. 2. Add a reference to a TestStand Engine object by calling the TS_SeqContextGetEngine function. This function is included for you in the AddUser function. 3. Using the Engine object reference, invoke the DisplayNewUserDialog method of the Engine class by calling the TS_EngineDisplayNewUserDialog function. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced»Engine»Dialogs»Dialogs for Editing Objects» Display New User Dialog. Complete the parameters for this function as shown in Figure 2-15. Insert the function into the source code file.


2-28

ni.com

Lesson 2


Figure 2-15. Invoking the Display New User Dialog Method

An IF statement determines whether the user selected OK or Cancel on the Display New User Dialog function panel. If the OK variable is True, the functions within the IF statement execute to add the new user to the UserList. 4. Add the following functions within the IF statement. a. Use the Engine object to obtain a reference to the UsersFile property. Use the TS_EngineGetUsersFile function to obtain this reference. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced»Engine» Static Properties»Users»Get Users File. Use the following information to complete the parameters for the Get Users File function panel. Insert the function into the source code file. Object Handle:

engine

Error Info:

&errorInfo

Users File Object:

&usersFile

b. You can obtain the UserList object from the reference to the UsersFile object. Use the TS_UsersFileGetUserList function to do this. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced»Users File»


2-29


Lesson 2


Static Properties»Get User List. Use the following information to complete the parameters for the Get User List function panel. Insert the function into the source code file. Object Handle:

usersFile

Error Info:

&errorInfo

List of Users:

&userList

c. Use the PropertyObject class to insert the new user into the UserList. Specifically, call the TS_PropertySetPropertyObjectByOffset function. Locate the function panel using the following list of classes: Instrument» TestStand API 3.5»Property Object»SubProperties» Set Property Object By Offset. Use the following information to complete the parameters for the Set Property Object By Offset function panel. Insert the function into the source code file. Object Handle:

userList

Error Info:

&errorInfo

Array Offset:

1

Options:

1

New Object Value:

userObject

You have added the new User object to the UserList. Next, save the UserList to the UsersFile. d. Call the TS_PropertyObjectFileWriteFile function to write the UsersFile to disk. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced» Property Object File»Write File. Use the following information to complete the parameters for the Write File function panel. Insert the function into the source code file. Object Handle:

usersFile

Error Info:

&errorInfo

Write Format:

WriteFileFormat_Current

e. Increment the Change Count flag of the AddUser function to indicate you have modified the UsersFile by calling the TS_PropertyObjectFileIncChangeCount function. Locate the function panel for this function using the following list


2-30

ni.com

Lesson 2


of classes: Instrument»TestStand API 3.5»Advanced» Property Object File»Inc Change Count. Use the following information to complete the parameters for the Inc Change Count function panel. Insert the function into the source code file. Object Handle:

usersFile

Error Info:

&errorInfo

The resulting AddUser function should resemble the following code. Note


void __declspec(dllexport) _stdcall AddUser(CAObjectHandle seqContextCVI, short *errorOccurred, long *errorCode, char errorMsg[1024]) { int error = 0; static TSObj_Engine engine; static TSObj_UsersFile usersFile; static TSObj_Property userList; CAObjHandle userObject; VBOOL ok; ErrMsg errMsg = {'\0'}; ERRORINFO errorInfo; //get engine reference TS_SeqContextGetEngine (seqContextCVI, &errorInfo, &engine); //display the new user dialog TS_EngineDisplayNewUserDialog (engine, &errorInfo, "New User", VTRUE, &userObject, &ok); if (ok){ //get the usersfile reference TS_EngineGetUsersFile (engine, &errorInfo, &usersFile); //get the userlist reference TS_UsersFileGetUserList (usersFile, &errorInfo, &userList); //insert the user obtained above into the userlist TS_PropertySetPropertyObjectByOffset (userList, &errorInfo, 1, 1, userObject); //write usersfile to disk TS_PropertyObjectFileWriteFile (usersFile, &errorInfo, TS_WriteFileFormat_Current); //flag the file as being changed TS_PropertyObjectFileIncChangeCount (usersFile, &errorInfo); }


2-31


Lesson 2


Error: CA.DiscardObjHandle CA.DiscardObjHandle CA.DiscardObjHandle Ca.DiscardObjHandle

(Engine) (usersFile) (userList) (userObject)

if (error < 0) { *errorOccurred = TRUE; } return; }

5. Save the UserManagerTool.c file. Leave the source file open for Part C: Editing Existing Users. You can also add users by invoking the GetUserProfile and NewUser methods of the Engine class. With this method you set the LoginName and Password properties for the user and then add the user to the UserList programmatically. Note

End of Part B Part C: Editing Existing Users You can modify the properties of an existing user with the DisplayPropertiesDialog method of the TestStand API. This method allows you to modify the properties of existing users and it automatically saves the UsersFile for you. Complete the following steps to add the necessary code to programmatically edit a TestStand user. 1. Scroll down to the CVICallback okbutton function and verify that there is a valid User element in the UserList with the LoginName of an existing user. Use the TS_EngineUserNameExists function within this callback to verify that a user exists with the given LoginName. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced»Engine»Object Access» User Name Exists. Complete the parameters for this function as shown in Figure 2-16. Insert the function into the source code file.


2-32

ni.com

Lesson 2


Figure 2-16. Checking for an Existing User

The resulting CVICallback okbutton function should resemble the following code. Note


int CVICALLBACK okbutton (int panel, int control, int event, void *callbackData, int eventData1, int eventData2) { switch (event) { case EVENT_COMMIT: GetCtrlVal (panel, PANEL_2_newuserloginname, userLoginName); //check if the user specified exists TS_EngineUserNameExists (engine_for_edit, NULL, userLoginName, &exists); if(exists) QuitUserInterface (0); else MessagePopup ("Message", "User does not exist"); break; } return 0; }


2-33


Lesson 2


2. Scroll to the EditUser function within the UserManagerTool.c source file. 3. Create a reference to a TestStand Engine object by calling the TS_SeqContextGetEngine function. This function is included for you in the EditUser function. An IF statement within the EditUser function checks the value of the exists variable. When the exists variable is True, you know there is a valid user for the given LoginName. 4. Within the IF statement, use the given LoginName to obtain the corresponding User object. a. Call the TS_EngineGetUser function. Locate the function panel using the following list of classes: Instrument»TestStand API 3.5»Advanced»Engine»Object Access»Get User. Use the following information to complete the parameters for the Get User function panel. Insert the function into the source code file. Object Handle:

engine_for_edit

Error Info:

&errorInfo

Login Name:

userLoginName

User Object:

&user

b. Obtain the User as a PropertyObject by calling the TS_UserAsPropertyObject function. Locate the function panel using the following list of classes: Instruments»TestStand API 3.5» Advanced»User»As Property Object. Use the following information to complete the parameters for the As Property Object function panel. Insert the function into the source code file. Object Handle:

user

Error Info:

&errorInfo

Property Object:

&userAsPropertyObj

c. After you have the corresponding User object, you can call the TS_PropertyDisplayPropertiesDialog function. Locate the function panel using the following list of classes: Instrument» TestStand API 3.5»Property Object»Dialogs»Display Properties Dialog. Use the following information to complete the parameters for the Display Properties Dialog function panel. Insert the function into the source code file.


2-34

ni.com

Lesson 2

Object Handle:

user

Error Info:

&errorInfo

Dialog Title:

"Edit User"

File:

usersFile

Dialog Options:

0

Status Flags:

&status


The resulting EditUser function should resemble the following code. Note


void __declspec(dllexport) _stdcall EditUser(CAObjectHandle seqContextCVI, short *errorOccurred, long *errorCode, char errorMsg[1024]) { int panelHandle; int error = 0; long status; static TSObj_UsersFile usersFile; CAObjHandle user; ErrMsg errMsg = {'\0'}; ERRORINFO errorInfo; exists=FALSE; panelHandle = LoadPanelEx (0, "UserManagerTool.uir", PANEL_2, __CVIUserHInst); //get engine reference TS_SeqContextGetEngine (seqContextCVI, &errorInfo, &engine_for_edit); DisplayPanel (panelHandle); RunUserInterface (); DiscardPanel (panelHandle); //if the user specified by the operator exists, then edit that user if(exists) { //get user from loginname TS_EngineGetUser (engine_for_edit, &errorInfo, userLoginName, &user); //get the user as a property object TS_UserAsPropertyObject (user, &errorInfo, &userAsPropertyObj); //display properties dialog


2-35


Lesson 2


TS_PropertyDisplayPropertiesDialog (userAsPropertyObj, &errorInfo, "Edit User", usersFile, 0, &status); } Error: CA_DiscardObjHandle (usersFile); CA_DiscardObjHandle (user); CA_DiscardObjHandle (engine_for_edit); if (error < 0) { *errorOccurred = TRUE; } return; }

5. Save the changes to the UserManagerTool.c file. Leave the source file open for Part D: Deleting Existing Users.

End of Part C Part D: Deleting Existing Users Just as you can add users, you can also delete users from the UserList by removing the corresponding element. Because each user is referenced in the UserList array by index, determine which user element to remove from the array by searching the UserList array for the specified LoginName, then delete the element corresponding to that user. 1. Within the UserManagerTool.c source file, scroll to the DeleteUser function. Complete the following steps to add the necessary code to delete an existing TestStand user programmatically. 2. Examine the pre-existing code within the DeleteUser function. Many of the functions called at the beginning of this function are the same functions that you have called in previous portions of this source code file to gain access to the Engine, UserList, and UsersFile objects. Notice that the DeleteUser function prompts the operator to enter a LoginName, then loops through the UserList to determine whether a user exists with that LoginName. If a user exists with that LoginName, the DeleteUser function deletes that user from the list and updates the UsersFile accordingly. 3. Scroll down to the IF statement within the DeleteUser function. In this section of the For Loop, the LoginName entered by the operator of this tool is compared to the LoginNames of the existing users. If a match is found, then the corresponding user should be deleted. 4. Add the TS_PropertyDeleteElements function to the beginning of the IF statement to delete the user. Locate the function panel using the


2-36

ni.com

Lesson 2


following list of classes: Instrument»TestStand API 3.5» Property Object»Characteristics»Arrays»Delete Elements. Complete the parameters for this function as shown in Figure 2-17. Insert the function into the source code file.

Figure 2-17. Deleting a User

The code within the IF statement in the DeleteUsers function should resemble the following code. Note


void __declspec(dllexport) __stdcall DeleteUser(CAObjHandle seqContextCVI, short *errorOccurred, long *errorCode, char errorMsg[1024]) { int panelHandle; int i, j, error = 0; long numGroups, numMembers; static TSObj_UsersFile usersFile; static TSObj_Engine engine; static TSObj_Property userList; static TSObj_Property user; static TSObj_Property group; static TSObj_Property groupList; static TSObj_Property members;


2-37


Lesson 2


ErrMsg errMsg = {'\0'}; ERRORINFO errorInfo; // get the engine reference TS_SeqContextGetEngine (seqContextCVI, &errorInfo, &engine_for_delete); //get the usersfile reference TS_EngineGetUsersFile (engine_for_delete, &errorInfo, &usersFile); //get the userlist reference TS_UsersFileGetUserList (usersFile, &errorInfo, &userList); //get the number of elements in the userlist ie. number of users TS_PropertyGetNumElements (userList, &errorInfo, &numElements); panelHandle = LoadPanelEx (0, "UserManagerTool.uir", PANEL_3, __CVIUserHInst); DisplayPanel (panelHandle); RunUserInterface (); DiscardPanel (panelHandle); // Loop to match the user entered in by the operator to the // corresponding array element of userlist and delete that user. for (i=0; i
Compare the user login name typed in by the operator with the login name at this index. If they match, then delete that user referenced by that index (!stricmp (userLoginName, loginName)){ // Delete the user from the user list break;

}

} // Remove the user from all groups // Get group list TS_UsersFileGetUserGroupList (usersFile, &errorInfo, &groupList);


2-38

ni.com

Lesson 2


// Get the number of groups TS_PropertyGetNumElements (groupList, &errorInfo, &numGroups); for(i=0; i
//flag the file as being changed TS_PropertyObjectFileIncChangeCount (usersFile, &errorInfo);

Error: CA_DiscardObjHandle CA_DiscardObjHandle CA_DiscardObjHandle CA_DiscardObjHandle CA_DiscardObjHandle

(usersFile); (engine); (userList); (user); (engine_for_delete);

if (error < 0) { *errorOccurred = TRUE; } return;


2-39


Lesson 2


5. Save the UserManagerTool.c file. Close the Source Code File window and return to the User Manager Tool Project window within LabWindows/CVI. 6. Select Build»Create Debuggable Dynamic Link Library and build the User Manager Tool project into a DLL named UserManagerTool.dll in the C:\Exercises\TestStand II\ CVI Project Files directory. 7. Close LabWindows/CVI completely and return to the sequence editor. Save the Ex 2-1B Creating User Manager Tool.seq sequence file.

End of Part D Part E: Using the User Manager Tool You have built the individual components of the User Manager tool and are ready to use the tool. Because this tool is a sequence, you can run the tool from within the sequence editor or an operator interface. You can also add the tool to the Tools menu within each of the above environments. 1. Select Tools»Customize to add the user manager tool to the Tools menu in the sequence editor . 2. In the Customize Tools Menu dialog box, click Add. 3. In the Add Tools Menu Item dialog box, select the options as shown in Figure 2-18.

Figure 2-18. Add Tools Menu Item Dialog Box

4. Click OK to return to the Customize Tools Menu dialog box.


2-40

ni.com

Lesson 2


5. In the Customize Tools Menu dialog box, specify the options and settings as shown in Figure 2-19.

Figure 2-19. Customize Tools Menu Dialog Box

6. Enter "Add/Edit/Delete Users" in the Item Text Expression field before you select it in the Tools Menu listbox. Click OK to close the Customize Tools Menu dialog box. The user manager tool should now display in the Tools menu in the sequence editor and default operator interfaces. 7. Select Tools»Add/Edit/Delete Users to execute the user manager tool 8. Close all windows when you finish.

End of Part E End of Exercise 2-1B


2-41


Lesson 2


Self Review 1. How is the Login dialog box displayed?

2. What are the two ways of verifying user privileges?

3. List the steps that you must take to create a new user using the TestStand API.

4. List the steps that you must take to delete an existing user.


2-42

ni.com

Lesson 2


Notes


2-43


Lesson 2


Notes


2-44

ni.com

Multithreading and Multi-UUT Testing

3

Lesson 3: Multithreading and Multi-UUT Testing In this lesson, you will: • Identify the advantages of multithreading and multiUUT testing • Use the multi-UUT process models • Use the TestStand synchronization step types to control multithreaded tests • Explore the TestStand remote execution feature

Multithreading and Multi-UUT Testing This lesson defines multithreading and multi-UUT testing using TestStand and the advantages of multithreading and multi-UUT testing. You will also learn more about the functionality of the process models that TestStand provides for easily integrating these types of testing. The Synchronization step types will also be discussed further because of their role in a multithreaded test environment. Lastly, this lesson will illustrate the ability of TestStand to perform remote executions.


3-1


Lesson 3


Test System Concepts • Production line speed determined by: – Pulse rate – Cycle time

• Example: Pulse rate = 1/10 (UUTs/sec) Cycle time = 23 (sec) • Minimum number of testers needed = (1/10) × (23) = 2.3 ~ 3 testers • Options: Three testers or one multihead tester Test System Concepts The following parameters characterize the speed of a production line: Pulse Rate—The number of UUTs per unit time coming off the production line that need testing. Because pulse rate is typically defined by the speed of the production line itself, it is often given to a test engineer as a fixed parameter. Cycle Time—Duration of time it takes to test and handle a single UUT. If cycle time were the reciprocal of pulse rate, you could test each item as it comes off the line. However, cycle time is often greater than the reciprocal of the pulse rate, so it is necessary to place several testers in parallel to keep up with the line. As the example above indicates, there are two options to meet the testing demands of the production line. You could have the line fan out to three independent testers or you could implement a single multihead tester.


3-2

ni.com

Lesson 3


Multihead Tester • Tests two or more UUTs in parallel • Single computer shares expensive instruments • Less space required than several independent testers • Requires sophisticated software for UUT tracking • TestStand Engine has full multithreading capabilities Multihead Tester A multihead tester is a test system with fixtures, instrumentation, and software capable of testing two or more UUTs in parallel. A multihead tester usually uses a single computer and can share expensive instruments, lowering capital equipment costs. In addition, a multihead tester occupies much less floor or bench space than several independent testers. Implementing a multihead tester puts more vigorous demands on the software that controls the test system. The tester must simultaneously track multiple units and record their results while communicating with handlers and other peripheral devices. For example, consider a production line with N testers. Typically, each tester is identical and operates independently. This means that all instruments and software are duplicated in each tester. Because it is very unlikely that all N multimeters, for example, are always being used at the same time, this is a tremendous waste of resources. Instead, you could implement a multihead tester in which you use one computer and one set of instruments with N test bays. In reality, a hybrid of these two situations is often implemented in which less expensive instruments are duplicated for each test bay and more expensive instruments are shared. One challenge in implementing a multihead tester, however, is in the software. Executing tests in parallel, tracking multiple UUTs, and sharing resources requires more sophisticated testing software than simple sequential testing.


3-3


Lesson 3


Multithreading is a modern software technique used to meet these demands. The TestStand Engine is a sophisticated sequencer with full multithreading capability and built-in tools.


3-4

ni.com

Lesson 3


Definition—Multithreading • Technology for executing multiple routines in parallel within a single application • Applications divide multiple tasks into subtasks, called threads • OS constantly switches execution among threads at high speeds • Allows single computer to make several measurements in parallel

Definition—Multithreading Modern operating systems use multithreading technology to execute multiple routines in parallel within a single application. An application divides multiple tasks into subtasks, called threads. A multithreaded operating system constantly switches execution among these threads. Because modern processors are so fast, the switching happens at a high rate so the threads appear to run in parallel.


3-5


Lesson 3


Definition—Multithreading (Continued) Process Thread 1 Thread N – 1 Thread N t/N

t/N

t/N

Processor Time = t Definition—Multithreading (Continued) Consider a process that has N threads running in it. The process is allotted a chunk of the processor time t. Provided that each thread running in the process has the same priority, each thread will receive t/N amount of processor time. If the priority of a thread is increased or decreased, then that thread will receive a larger or smaller portion of the total processor time t allotted for that process. You might have multiple processes running on the same processor, in which case each process would receive a fraction of the total processor time. Each thread within the individual process would then receive a fraction of the processor time that was allotted to the thread’s process.


3-6

ni.com

Lesson 3


Multithreading in TestStand • The sequence editor and operator interface are processes • Each process can launch multiple executions • Each execution can have multiple threads running inside of it • All threads in execution suspend or terminate when the execution suspends or terminates • An execution completes when all its threads complete

Multithreading in TestStand In TestStand, the operator interface or sequence editor are processes. Each of these processes can launch multiple executions, and in turn, each execution can contain multiple threads. Each execution must contain at least one thread, but additional threads might be added as required. When an execution suspends or terminates, all threads within the execution will suspend or terminate as well. When all the threads within the execution have completed, the execution is then complete. Keep in mind that all threads within an execution operate independently of each other, and that you must use a method of inter-process communication to share resources between threads. Each thread maintains a call stack that contains a SequenceContext object for each active sequence invocation. Both execution and thread are TestStand objects. You can obtain a Thread object from the Execution object and vice versa. When you run a sequence, TestStand creates an Execution object and a Thread object and a new Execution window launches to show the current execution. If you create a new thread within the current execution, a new Execution window does not appear, but the thread executes in the background. TestStand only creates Execution windows when you start a new execution.


3-7


Lesson 3


Multithreading in TestStand (Continued) Execution and Thread are TestStand objects Process (Operator Interface or Sequence Editor) Execution 1

Execution 2 Thread 1

Thread 1

Thread 2

Thread 2 Thread 3

Multithreading in TestStand (Continued) This slide shows the relationship between the Execution and the Thread objects in TestStand. A TestStand process—sequence editor or operator interface—can run any number of executions, each one running a sequence and possibly a process model. Each execution can run any number of threads, with each thread running a sequence. If more than one operator interface or sequence editor are instantiated, each process has its own set of executions and threads totally independent from each other. You can communicate between threads or executions of different processes by using the Synchronization step types such as Queue and Notification, as long as their name expressions are preceded by a star (*), for example *myQueue.


3-8

ni.com

Lesson 3


Multithreading—Sequence Call Options Sequence Call Options • Run the sequence in a new thread • Run the sequence in a new execution • Run the sequence on a remote computer

Multithreading—Sequence Call Options The Sequence Call step type provides additional multithreading features in TestStand. You can use the Multithreading and Remote Execution section of the Edit Sequence Call dialog box to execute a subsequence running in a new thread within the same execution or in a new local or remote execution. Refer to the TestStand Help for more information about the options on the Multithreading and Remote Execution section of the Edit Sequence Call dialog box.


3-9


Lesson 3


Synchronization Step Types Standard • Lock • Rendezvous • Queue • Notification • Wait • Batch Synchronization • Auto Scheduler Advanced • Semaphore • Thread Priority • Batch Specification

Synchronization Step Types TestStand includes the following Synchronization step types which help you synchronize multiple threads of sequence execution: •

Lock—Ensures that only one thread can access a particular resource or data item at a time.

•

Rendezvous—Makes threads wait for each other before they proceed past a specific location.

•

Queue—Synchronizes the production and consumption of data among your threads.

•

Notification—Notifies one or more threads when a particular event or condition has been met. You can also pass data to the threads you notify.

•

Wait—Waits for an execution or thread to complete or for a time interval to elapse.

•

Batch Synchronization—Defines sections of the sequence to synchronize multiple threads that belong to one batch. Typically, use these steps in a sequence that you execute using the Batch process model.

•

Auto Schedule—Defines a block that contains any number of Use Auto Scheduled Resource sub-blocks. The Auto Schedule step executes each sub-block once. The order in which the step executes the sub-blocks can vary according to the availability of the resources that the sub-blocks require.


3-10

ni.com

Lesson 3


Synchronization Step Types (Continued) Common Features • • • •

Names and references Timeouts Suspension/termination friendly Shareable among processes and machines • Configurable lifetimes – Example: Acquire lock for duration of sequence

Synchronization Step Types (Continued) • • •

Thread Priority—Adjusts the operating system priority of a TestStand thread. Semaphore—Limits concurrent access to a resource to a specific number of threads. Batch Specification—Defines a group of threads where each thread in the group runs an instance of the client sequence file.

Common Features Most of the Synchronization steps share several common features: • In general, each step type creates a Synchronization object. You can create a Lock step named DMM1. You can then refer to the Lock step as DMM1, in other steps or sequences. • You can specify a step time out, if it cannot synchronize in a specified amount of time. • Synchronization steps recognize when you terminate or suspend an execution and release resources accordingly. • You can use Synchronization steps to synchronize between processes on a single machine and between multiple machines on a network. • You can specify the lifetime of the Synchronization object that a step creates or the lifetime of an operation that a Synchronization step performs. Refer to the TestStand Help for more information about the Synchronization step types.


3-11


Lesson 3


Lock and Rendezvous Demo Thread 1

Thread 2

Lock DMM

Lock DMM

Test Using DMM

Test Using DMM

Unlock DMM

Unlock DMM

Test 1 Test 2

Test 1 Test 2

Rendezvous

Rendezvous

Test 3

Test 3


3-12

ni.com

Lesson 3


Queue Demo Thread 1 Create Queue Acquire Data Enqueue Loop


Thread 2 Dequeue Analyze Store Loop

3-13


Lesson 3


Notification Demo Sequence 1

Sequence 2

Create Notification

Wait on Notification

Acquire Data

Process Data

Set notification Test 1


3-14

ni.com

Lesson 3


Exercise 3-1: Using Synchronization Step Types Objective: To demonstrate some of the built-in Synchronization step types in a test. Estimated Time: 20 minutes



3-15


Lesson 3


Types of Parallel Testing Parallel UUT

Batch UUT

UUT

UUT

UUT

UUT

UUT

UUT Common Carrier UUT

UUT

UUT

Common Carrier

Test Fixture

Test Fixture

Test Fixture

Test Fixture

Types of Parallel Testing To help introduce the Parallel process models in TestStand, it is worth noting that there are many types of parallel test systems. At one extreme, you could have a set of UUTs that are tested independently of each other. For example, you might have five test sockets for testing radios. Each radio would be loaded into its respective test socket and tested. Once the first radio has completed testing, it can be loaded off the tester and the next radio can be loaded, independent of whether the other radios have completed testing. On the other hand, you can have a test system operate on a batch of UUTs at a time. The UUTs enter and exit the tester as a group but are tested in parallel. As an example, you might have several units that are connected to a common carrier. The UUTs arrive at the test socket station, and are loaded into their respective test sockets. Only after all UUTs have been tested can the next set of UUTs be loaded into their test sockets. However, these situations are not the only ones in which you might use parallel testing.


3-16

ni.com

Lesson 3


Useful Process Models Parallel Model • Controls multiple independent test sockets at the same time • Allows you to start and stop testing on any socket at any time

Batch Model • Controls a set of test sockets that test multiple UUTs as a group • Ensures that you start and stop testing all UUTs at the same time Useful Process Models TestStand offers several process models to help you further integrate multithreading and multi-UUT testing into your test system. •

ParallelModel.seq—Controls multiple independent test sockets.

The Parallel process model allows you to start and stop testing on any socket at any time. •

BatchModel.seq—Controls a set of test sockets that test multiple

UUTs as a group. The Batch model ensures that you start and finish testing all UUTs at the same time. The Batch model also provides batch synchronization features. For example, you can specify for a step in a batch that the step runs only once per batch instead of once for each UUT. The Batch model also makes it easy 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. Finally, the Batch model can generate batch reports that summarize the test results for the UUTs in the batch.


3-17


Lesson 3


Batch Process Model Start testing all units in the batch

Test

Test

Test

Test

Test

Test Wait until all units are complete

Socket 0

Socket 1

Socket 2

Batch Process Model A batch test starts on all test sockets at the same time and does not complete until all test sockets complete testing. During the testing process, individual tests might or might not be synchronized. By default, synchronization applies to your test as a whole. In the Batch process model, each test socket executes relative to the other test sockets. The test sockets are centrally controlled from the Batch UUT Identification dialog box. The UUTs for each test socket are sequentially tested in a loop until the operator stops the execution for the batch using the Batch UUT Identification dialog box.


3-18

ni.com

Lesson 3


Synchronized Sections Three types of synchronized sections: • Parallel • Serial • One-Thread-Only

Synchronized Sections When you create a synchronized section, you can specify one of three section types: Parallel, Serial, or One-Thread-Only.


3-19


Lesson 3


Batch Synchronized Sections

Test

Test

Test Wait for all units

Test

Test

Test

Wait for all units

Socket 0

Socket 1

Socket 2

Synchronized Section

Batch Synchronized Sections A batch test automatically synchronizes the start and end of testing on all test sockets. In addition, you can add a special area of synchronization in your test sequences called a Synchronized section. A Synchronized section is similar to the entire batch test in that all test sockets enter and leave the section at the same time. Synchronized sections only take effect when your sequence runs under a Batch process model.


3-20

ni.com

Lesson 3


Synchronization Sections—Parallel Test

Test Test Wait for all units

Test

Test

Test

Test Test

No synchronization with parallel panel


Socket 0

Socket 1

Socket 2

Synchronization Sections—Parallel A Parallel section is the simplest type of section. 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 is blocked until all threads in the batch reach that step. In other words, the Parallel section does not perform any action beyond synchronizing all test sockets at the beginning and end of the section.


3-21


Lesson 3


Synchronization Sections—Serial Test Test Test

Wait for all units Test

Each test socket executes in series Shared Resource


Test Test

Shared Resource Test

Wait for all units

Test Socket 0

Socket 1

Socket 2

Synchronization Sections—Serial You 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. For example, if all test sockets share one instrument, you can use a Serial section to give each test socket exclusive access to the instrument one at a time.


3-22

ni.com

Lesson 3


Synchronization Sections—One-Thread-Only Test Test

Test Wait for all units Action

Action Skip

Action Wait for all units

Socket 0

Action

Socket 1

Action Skip

Only one test socket executes the actions in the section

Action

Socket 2

Synchronization Sections—One-Thread-Only You 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 section type 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. You can use a One-Thread-Only section to ensure that an action that applies to all test sockets executes only once.


3-23


Lesson 3


Parallel Process Model

Test

Test

Test

Test Test Testing

Testing Test

Socket 0

Socket 1

Socket 2

Unloaded and next UUT loaded

Parallel Process Model Consider the case in which you have three test sockets: Socket 0, Socket 1, and Socket 2. All three of your UUTs might or might not start testing at the same time. Socket 1 finishes all the tests and is unloaded and the next UUT is loaded into Socket 1. This happens regardless of whether or not the other two UUTs have completed testing. As you can see, each test socket operates independent of the others. The test sockets are centrally controlled from the Parallel Model Test UUTs dialog box.


3-24

ni.com

Lesson 3


Implementing Synchronized Sections—Batch Synchronization Step Type • Implements a synchronized section around a group of steps • Enter a synchronized section • Exit a synchronized section

Implementing Synchronized Sections—Batch Synchronization Step Type You can implement synchronized sections within TestStand using the following two methods: •

Grouped steps—Involves using the Batch Synchronization step type.

•

Step-by-step—Implements a synchronized section around a group of steps.

Use Batch Synchronization steps to define synchronized sections by placing a step in a sequence and specifying an Enter operation for the beginning step and an Exit operation for the ending step. You must place the Enter and Exit operations in the same sequence, but you do not have to place them in the same step group. There are certain requirements for using the Enter and Exit operations. TestStand generates a run-time error if the Enter and Exit operations do not comply with 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 in which you enter it.


3-25


Lesson 3


Implementing Synchronized Sections— Synchronization Tab • Controls the thread accessibility • Synchronizes a single step for batch testing

Implementing Synchronized Sections—Synchronization Tab In addition to the Synchronization step types, you can specify common synchronization properties on any one step instead of a group of steps. Refer to the TestStand Help for more information about the options on the Synchronization tab of the Step Properties dialog box.


3-26

ni.com

Lesson 3


Identifying the Test Socket • Examine properties: – RunState.TestSockets.MyIndex – RunState.TestSockets.Count

• Batch and Parallel process models update these properties

Identifying the Test Socket In order to determine which test socket to test when you run under the Batch or Parallel process models, your test sequence can examine two RunState properties to determine the number of test sockets in the system and the zero-based index of the test socket on which it is testing. Specifically, the two properties are RunState.TestSockets.MyIndex and RunState.TestSockets.Count.


3-27


Lesson 3


Exercise 3-2: Using the Parallel and Batch Process Models Objective: To illustrate the features built into the Parallel and Batch process models for multithreading and multi-UUT testing. Estimated Time: 20 minutes



3-28

ni.com

Lesson 3


Remote Execution

TestStand Sequence Init Seq A

Unit Under Test

Seq B Seq C Generate Report

Remote Execution The distributed architecture of TestStand allows you to run tests on remote machines. Using this client-server model, a single computer can sequence through a series of tests and archive results while each test runs on a different networked machine. A distributed architecture allows you to decrease test time and improve the efficiency of your production line by creating tests that pass information to each other over a network.


3-29


Lesson 3


Implementing Remote Execution Configure remote execution using the Edit Sequence Call dialog box

Implementing Remote Execution The remote execution feature in TestStand can be very useful when designing a test system that utilizes distributed execution. This feature can be implemented from within the Edit Sequence Call dialog box. When you have specified the file pathname and sequence to be called on the remote machine, select Run Sequence on a Remote Computer from the context menu. Next, specify the name of the remote computer on the network by clicking the Settings button. From within the Remote Execution Settings dialog box, you can specify the computer name directly or use an expression that TestStand evaluates at run time.


3-30

ni.com

Lesson 3


REngine Remote Server • Runs in the background on a remote machine • Provides a TestStand ActiveX server to execute the remote sequences

REngine Remote Server TestStand utilizes the DCOM features in Windows-based platforms to perform the remote execution of a test sequence. When using TestStand to execute a test sequence on a remote machine, you need to configure the DCOM settings on your client and server computers. In general, before a client can communicate with a server through DCOM, you must configure the security permissions for the server on the Windows system of the server. You can configure the Windows system security permissions using the DCOMCNFG utility. If you want TestStand to invoke a sequence on a remote TestStand server host, you need to properly configure the server on the remote system. You must enable the TestStand server to accept remote execution requests, register the server with the operating system, and configure the Windows system security of DCOM to allow users to access and launch the server remotely. A TestStand server is active when the TestStand application, \Bin\REngine.exe, is running on the remote system.

Each TestStand client communicates with a dedicated version of the remote engine application. In Windows 2000/NT/XP, the remote server launches automatically each time a TestStand client uses the server. Refer to the TestStand Reference Manual for more information about implementing remote execution in TestStand.


3-31


Lesson 3


Exercise 3-3: Illustrating Remote Execution (Optional) Objective: To use the remote execution feature in TestStand to execute tests on a remote system. Estimated Time: 20 minutes



3-32

ni.com

Lesson 3


Lesson 3 Summary • TestStand has full multithreading capabilities • Multithreading benefits include: – Multi-UUT testing – Improved testing throughput – Maximized use of available hardware, instrumentation, and space – Lower capital equipment costs

• Multithreading is accomplished in TestStand through using: – Batch and Parallel process models – Synchronization step types

• Remote execution can be configured and implemented in TestStand Summary Increasingly, test times are scrutinized as a means to lower costs on a production line. Typically, functional tests cannot keep up with the throughput of a production line, so several testers are required for each line. Because racks of test equipment are expensive and consume factory floor space, this “fanning out” of testers must be minimized to keep costs down. Many techniques are used in both hardware and software to increase test throughput and thus lower capital equipment costs. In software, multithreading has emerged as a powerful technology for faster throughput and easier integration when using several functional testers on a single production line. TestStand has full multithreading capabilities including a multithread safe engine, the Parallel and Batch process models, execution and thread properties for each step, and Synchronization step types. TestStand also provides very powerful solutions for performing distributed execution. You have the ability with TestStand to execute sequences located on a machine somewhere else on the network using remote execution.


3-33


Lesson 3



Using Synchronization Step Types

To demonstrate how to use some of the built-in Synchronization step types in a test. TestStand provides Synchronization step types that you can include in a test. These steps are primarily used during parallel executions, such as when TestStand executes the same test multiple times simultaneously. Synchronization steps allow multiple executions to communicate and manage resources. For example, an instrument that is used by multiple, simultaneous executions must be managed to prevent two executions accessing it at the same time. In this exercise, you will use an existing sequence file that performs multiple executions and only has access to a single instrument. You will make use of Synchronization steps so the instrument is accessed and used by only one execution at a time.

Right-click in the Sequence File window and select Insert Step»Synchronization from the context menu to access the default Synchronization step types. Figure 3-1 shows the Synchronization step types available.

Tip

Figure 3-1. Default Synchronization Step Types

1. Open the Ex 3-1 Using Synchronization Step Types.seq file located in the C:\Exercises\TestStand II directory. Notice that this file already contains IVI DMM steps that are configured to read a waveform from a DMM instrument. You will add a Lock and a Rendezvous Synchronization step so that when you launch two or more parallel executions, all the executions do not try to use the instrument at the same time. Additional Information A Lock step allows only one thread to execute between a Lock and an Unlock operation. A Rendezvous step causes the thread from which it was called to be blocked from execution. When the number of blocked


3-34

ni.com

Lesson 3


threads reaches the total number of threads you specified when creating the Rendezvous step, all the threads resume execution. 2. Go to the Setup step group and insert a Lock step named Create Lock. 3. Right-click this step and select Configure Lock from the context menu to open the Lock Step Configuration dialog box. a. Select Create from the Operation ring control. b. In the Lock Name Expression text field, enter the following string including quotes: "instrument". c. Leave the Already Exists expression empty for this step. d. Set the Lock Reference Lifetime ring control to Same as Thread. Figure 3-2 shows the resulting Lock Step Configuration dialog box.

Figure 3-2. Lock Step Configuration Dialog Box

e. Click OK to close the Lock Step Configuration dialog box. 4. Insert a Rendezvous step beneath the Lock step in the Setup step group. Name this step Create Rendezvous. 5. Right-click this step and select Configure Rendezvous to open the Rendezvous Step Configuration dialog box. a. Select Create from the Operation ring control. b. In the Rendezvous Name Expression text field, enter the following string including quotes: "test". c. Leave the Already Exists expression empty for this step.


3-35


Lesson 3


d. Set the Rendezvous Reference Lifetime ring control to Same as Thread. e. Change the Number of Threads Per Rendezvous expression to 4. Figure 3-3 shows the resulting Rendezvous Step Configuration dialog box.

Figure 3-3. Rendezvous Step Configuration Dialog Box

f. Click OK to close the Rendezvous Step Configuration dialog box. You have configured the Lock and Rendezvous steps you need for this exercise. Use the Lock step to lock a thread so that only one thread executes at a time, allowing only one execution to use the instrument at a time. 6. Go to the Main step group and insert a Lock step. Name this step Lock. 7. Move the step to the top of the MainSequence so the Lock step is the first step that executes in the Main step group. 8. Right-click the Lock step and select Configure Lock from the context menu to open the Lock Step Configuration dialog box. a. Select Lock from the Operation ring control. b. For the Lock Name or Reference Expression text field, enter the following string including quotes: "instrument". c. For the Lock Operation Lifetime ring control, select the Same as Sequence option.


3-36

ni.com

Lesson 3


Additional Information If the you do not manually release the lock and the sequence execution ends, the lock reaches its lifetime and automatically releases. Alternatively, you can establish a timeout limit so the lock releases after a specified amount of time. Figure 3-4 shows the resulting Lock Step Configuration dialog box.


d. Click OK to close the Lock Step Configuration dialog box. Insert a step that releases the lock. The lock should release after the last step in the Main step group. 9. Insert a Lock step and name this step Unlock. This step is the last step in the Main step group. 10. Right-click the Unlock step and select Configure Lock from the context menu to open the Lock Step Configuration dialog box. a. Select Early Unlock from the Operation ring control. b. In the Lock Name or Reference Expression field, enter the following string including quotes: "instrument".


3-37


Lesson 3


Figure 3-5 shows the resulting Lock Step Configuration dialog box.


c. Click OK to close the Lock Step Configuration dialog box. Figure 3-6 shows the resulting sequence file.

Figure 3-6. Completed Sequence File

After releasing the lock, the TestStand execution should wait until all parallel executions have reached that point. Create a Rendezvous step that serves as a rendezvous point for all parallel executions.


3-38

ni.com

Lesson 3


11. Insert a Rendezvous step after the Unlock step. Name this step Rendezvous. 12. Right-click the Rendezvous step and select Configure Rendezvous from the context menu to open the Rendezvous Step Configuration dialog box. a. Select Rendezvous from the Operation ring control. b. For the Rendezvous Name or Reference Expression, enter the following string including the quotes: "test". This references the same Rendezvous step that you created in the Setup step group. c. Click OK to close the Rendezvous Step Configuration dialog box. The following steps insert a step that waits for a specific period of time using the Wait step type. 13. Insert a Wait step after the IVI DMM: Read Measurement step. Name this step Wait. 14. Right-click the Wait step and select Configure Wait from the context menu to open the Wait Step Configuration dialog box. a. Select the Time Interval option from the Wait for ring control. b. For the Specify the amount of time to wait (in seconds) expression, enter 2 so this step waits for two seconds before continuing the execution. c. Click OK to close the Wait Step Configuration dialog box. Figure 3-7 shows the resulting sequence.

Figure 3-7. Sequence with Wait Step


3-39


Lesson 3


15. Configure TestStand to use the Batch process model. a. Select Configure»Station Options to open the Station Options dialog box. b. Click the Model tab. c. Select BatchModel.seq from the Station Model ring control. d. Click OK to close the Station Options dialog box. 16. Select Configure»Model Options to open the Model Options dialog box and change the Number of Test Sockets control to 4 so a single batch tests four UUTs. Figure 3-8 shows the resulting Model Options dialog box.

Figure 3-8. Model Options Dialog Box

17. Save and execute the sequence file using Test UUTs.


3-40

ni.com

Lesson 3


18. Enter serial numbers for the batch and for each socket, then click Go to exit the Enter UUTs dialog. Notice that when the batch execution starts, only one thread is able to access the IVI DMM steps that are bounded by the Lock and Unlock steps. After the Unlock step is executed, each test socket execution waits at its Rendezvous step until all four Rendezvous operations have occurred. When running this exercise, you may get a Run-Time Error dialog informing you that “The specified IVI logical name is not defined in Measurement and Automation Explorer”. If this occurs, you must perform the following steps to define an IVI logical name to simulate the instrument. Continue to step 20 if there is no error. Note

a. Select Start»Programs»National Instruments»Measurement and Automation to start Measurement and Automation Explorer. b. Expand the IVI Drivers tree. c. Right click the Driver Sessions directory and select Create New. d. Name the new driver session niDMM. e. Select nisDmm from the Simulate With ring control. f. Click the Software tab in the lower portion of the window. g. Select NIDMM from the Software Module ring control. h. Right click the Logical Names directory and select Create New. i. Name the new logical name NIDMM. j. Select niDMM from the Driver Session ring control. k. Click Save IVI Configuration. l. Close Measurement and Automation Explorer. m. Return to TestStand and select Retry from the Handle Current Error option frame of the Run-Time Error dialog. n. Click OK to exit the Run-Time Error dialog. 19. If the IviDmm Simulator Setup dialog appears, click OK to exit. 20. Change the default process model to the Sequential model. a. Select Configure»Station Options to open the Station Options dialog box. b. Click the Model tab. c. Select SequentialModel.seq from the Station Model ring control. d. Click OK to close the Station Options dialog box. 21. Close all open windows when you finish.

End of Exercise 3-1 © National Instruments Corporation

3-41


Lesson 3



Using the Parallel and Batch Process Models

To illustrate the features built into the Parallel and Batch process models for multithreading and multi-UUT testing. In this exercise, you will execute sequences using the Parallel and Batch process models. You will learn about their features, when to use each one of them, as well as their differences.

Part A: Using the Parallel Process Model (ParallelModel.seq) You can use the Parallel process model, ParallelModel.seq, to control multiple independent test sockets. The Parallel process model allows you to start and stop testing on any socket at any time. TestStand tests each of the UUTs completely independent from the others. A big advantage of using the Parallel model is that a test sequence can be reused for testing multiple UUTs at the same time. During this part of the exercise you will test three computer motherboards in parallel. 1. Open the computer.seq file located in the \ Examples\Demo\C directory. 2. Verify that TestStand is configured to use the Sequential process model by looking at the process model path displayed in the status bar of the Sequence Editor window. 3. Select Execute»Test UUTs to run the sequence with the Sequential process model. Notice how the computer simulation test works and only one instance of this sequence executes at a time. 4. Configure TestStand to use the Parallel process model to run this same sequence multiple times simultaneously. a. Select Configure»Station Options to open the Station Options dialog box. b. Click the Model tab and select ParallelModel.seq from the Station Model ring control. c. Click OK to close the Station Options dialog box. Notice that the process model path in the status bar of the Sequence Editor window has been updated to reflect your selection.


3-42

ni.com

Lesson 3


5. Select Configure»Model Options to open the Model Options dialog box. The Model Options dialog box allows you to select how many test sockets (UUTs) you want to run in parallel. In this dialog box you can also set options to tile and hide the Execution windows. a. Set the Number of Test Sockets control to 3 as shown in Figure 3-9.

Figure 3-9. Model Options Dialog Box

b. Click OK to close the Model Options dialog box. 6. Select Execute»Test UUTs to execute the computer simulation sequence. The Execution windows should tile together in the back, and the Test UUTs window, shown in Figure 3-10, should be in front.


3-43


Lesson 3


Figure 3-10. Test UUTs Dialog Box

7. Assign a serial number to each UUT and click OK in the UUT Information dialog box, to execute UUT. Additional Information Each time you execute a UUT, the Parallel process model executes the Computer.seq sequence file independently and generates a report just as it would use the Sequential process model. The difference is that you can launch the same sequence file multiple times in parallel. This feature is very powerful because you create one sequence file that the Parallel process model executes. Notice that the Test UUTs dialog box allows you to stop each or all the UUTs. It also allows you to view the report for each UUT after the completion of each test. 8. Click corresponding Stop in the Test UUTs dialog box, to stop the execution of a particular UUT. 9. When all UUTs have finished execution, click Exit in the bottom right corner of the Test UUTs dialog box. 10. Return to the sequence editor. Close all Execution windows and the computer.seq file.

End of Part A


3-44

ni.com

Lesson 3


Part B: Using the Batch Process Model (BatchModel.seq) Use the Batch process model, BatchModel.seq, to control a set of test sockets that test multiple UUTs as a group. The Batch process model ensures that you start and finish testing all UUTs at the same time. The Batch process model also provides batch synchronization features. For example, you can specify that, because a step applies to the batch as a whole, the step runs only once per batch instead of once for each UUT. You can also use the Batch model 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. Finally, the Batch model can generate batch reports that summarize the test results for the UUTs in the batch as well as reports specific for each UUT. 1. Open the BatchUUT.seq example test sequence located in the \Examples\MultiUUT directory. Additional Information The BatchUUT.seq example sequence file simulates a three part batch test. The first part, which includes the Set Chamber Temperature step, applies to the batch of UUTs as a whole. Notice that when you open this sequence, the process model path in the status bar of the sequence editor changes from the Parallel process model to the Batch process model. This occurs because the BatchUUT.seq has been configured to require the Batch process model. Select Edit»Sequence File Properties and set the corresponding parameters on the Advanced tab as shown in Figure 3-11 to assign a specific process model to a sequence file.

Note


3-45


Lesson 3


Figure 3-11. Sequence File Advanced Properties

The Pulse Test subsequence contains a group of steps that are synchronized to run on each UUT in turn. This subsequence simulates sharing a single instrument that must be used in one UUT a time. The test sequence itself handles synchronization of this test, not the process model. 2. Double-click the Set Chamber Temperature step to display the Step Properties dialog box. The step comment describes the behavior of the step. 3. Click the Synchronization tab to set the batch behavior of the step. Enable the Use Lock to Allow Only One Thread at a Time to Execute the Step option so that regardless of having multiple UUTs executing at the same time, only one UUT can execute this step and its actions apply to the entire batch. 4. Click OK to close the Step Properties dialog box. 5. Right-click the Pulse Test Sequence Call step and select Open Sequence from the context menu. Notice that the first and last steps of the Pulse Test sequence control the entrance and exit to the batch section. 6. Return to the MainSequence using the View ring control.


3-46

ni.com

Lesson 3


The third part of this test, the Frequency Sweep test, does not specify any synchronization. The Frequency Sweep test runs in parallel on each UUT in the batch. 7. Select Execute»Test UUTs to execute the batch test . The batch size is currently set to three, the same Model Option setting used in Part A for the number of test sockets. The Enter UUTs dialog box, shown in Figure 3-12, should appear. You can enter serial numbers for each UUT as well as a batch serial number in this dialog box.

Figure 3-12. Entering UUTs for a Batch Sequence

8. Enter a batch number and three serial numbers. Clicking Go to execute the batch. 9. Click OK in the Batch Model Example dialog box. This dialog box contains information about the example you are executing. Observe that the Set Chamber Temperature step executes once for the entire test. The Pulse Test step executes serially, once for each UUT. The Frequency sweep test executes in parallel for all three UUTs. 10. When executing batch tests, you have the option of viewing independent UUT reports or a batch report. Click Next Batch to proceed to the next batch. 11. To finish testing, click Stop in the Enter UUTs dialog box.


3-47


Lesson 3


12. Close all remaining Execution and Report windows. 13. Change the default process model to the Sequential model. a. Select Configure»Station Options to open the Station Options dialog box. b. Click the Model tab and select SequentialModel.seq from the Station Model ring control. c. Click OK to close the Station Options dialog box. 14. Close all windows when you finish.

End of Part B End of Exercise 3-2


3-48

ni.com

Lesson 3



Illustrating Remote Execution (Optional)

To use the remote execution feature in TestStand to execute tests on a remote system. Because this exercise requires the computers to be linked by a Local Area Network (LAN), you might not be able to complete this exercise in the classroom. However, this feature is important and you should consider doing this exercise at your convenience when you have access to computers on a LAN. It is also possible to perform remote execution with TestStand over a peer-to-peer network using a hub or crossover ethernet cable. For more information about the configuration for a peer-to-peer remote access setup, refer to the TestStand section of the NI Developer Zone Web site at ni.com/zone. The remote execution feature in TestStand provides the ability to execute test sequences remotely. This feature can be useful when designing a test system that uses distributed execution. This exercise describes the steps needed to configure TestStand and the Windows OS to implement calling sequences remotely. If the TestStand development software is already installed on your remote computer, then only copy the sequence files and supporting files to that computer. For this exercise, copy the files located in the C:\Exercises\ TestStand II\RemoteCPUTest directory on your client computer to the C:\RemoteCPUTest directory on the remote computer. If you do not want to install the TestStand development software on your remote machine, you need to ensure that you at least have the TestStand Run-time Engine, the TestStand Remote Engine (REngine), and an operator interface of your choice installed on the remote machine. You also need to copy the RemoteCPUTest directory to the remote computer as mentioned in the previous paragraph.

Part A: Setting up TestStand as a Server for Remote Execution If you want TestStand to invoke a sequence on a remote TestStand server host, you must properly configure the server on the remote system. Specifically, you must enable the TestStand server to accept remote execution requests, register the server with the operating system, and configure the Windows system security to allow users to access and launch the server remotely. 1. Enable the remote server to accept remote execution requests from the client machine. a. Open the Station Options dialog box and click the Remote Execution tab.


3-49


Lesson 3


b. Place checkmarks in the Allow Sequence Calls from Remote Machines to Run on this Machine and Allow All Users Access from Remote Machines checkboxes as shown in Figure 3-13.

Figure 3-13. Station Options Dialog Box

c. Click OK to close the Station Options dialog box. Additional Information A TestStand server is active when the TestStand application Bin\Rengine.exe is running on a remote system. The following describes how each TestStand client interacts with a remote system. •

Windows 2000/NT/XP—The remote server launches automatically each

time a TestStand client uses the server. Before a client or local computer can communicate with a server or remote computer, you must configure the security permissions for the server on the Windows system of the server.


3-50

ni.com

Lesson 3


By selecting the Allow All Users Access from Remote Machines option, you allow any user from any machine to launch and access the TestStand Remote Engine on this machine. If you prefer to allow only a specific user or a group of users to launch and access the TestStand Remote Engine, you must configure the security permissions. Refer to the TestStand Reference Manual for more information about configuring security permissions.

End of Part A Part B: Configuring a Test Sequence to Call a Sequence Remotely 1. Within the sequence editor environment on your local machine, open the Ex 3-3 Remote Execution.seq file located in the C:\Exercises\ TestStand II directory. This is one of the computer motherboard example test sequences that ship with the TestStand development software. In this exercise, the cpu.seq subsequence file will execute on the remote machine rather than the local machine. 2. Right-click the CPU Sequence Call step in the MainSequence and select Specify Module from the context menu. 3. Remove the checkmark from the Use Current File checkbox, if necessary. 4. For the File Pathname, specify the path to the sequence file you want to call relative to the remote machine. In this case, use the path C:\RemoteCPUTest\Cpu.seq. This path corresponds to the path of the file to be called located on the remote machine, not the local machine. The File not found message might display under the file pathname because the file does not exist in the specified location on the local machine. 5. Select the Run Sequence on a Remote Computer option in the Multithreading and Remote Execution section. Click Settings to specify the name of the remote computer on the network. Additional Information When you specify the remote host within the Remote Execution Settings dialog box, you can specify a remote host directly, such as \\ComputerName, or you can use a TestStand expression that is evaluated at run-time. You need to know the actual name of the remote computer you are calling on your network.


3-51


Lesson 3


This course manual is unable to provide you with the actual name of the remote computer you are calling because it is specific to the network and computer you are using. The example Remote Execution Settings dialog box shown in Figure 3-14 is based on a computer on the network named Blackhole. Note

Figure 3-14. Remote Execution Settings Dialog Box

6. Click OK to close the Remote Execution Settings dialog box. Figure 3-15 shows the resulting Edit Sequence Call dialog box.

Figure 3-15. Edit Sequence Call Dialog Box


3-52

ni.com

Lesson 3


7. Click OK to close the Edit Sequence Call dialog box. 8. Save the Ex 3-3 Remote Execution.seq file. 9. Select Execute»Single Pass from the sequence editor menu on the local machine. The sequence should execute and properly call the remote sequence. The remote executing sequence will be transparent to the appearance of the execution on the local computer. You will not directly notice that the sequence execution occurred on the remote machine. The test report also shows that the remote test executed on the local machine. This is because TestStand handles passing all of the result data back to the calling computer so it can be included in the test report. For visual verification that the remote sequence is called, add a Message Popup step to the MainSequence of the CPU.seq file on the remote computer. This causes a message popup to appear on the remote computer when the sequence executes and requires you to click OK before the test continues. Note



3-53


Lesson 3


Self Review 1. List some of the benefits of using a multihead tester.

2. What is the difference between a thread and a process?

3. Explain what multithreading is and how it relates to TestStand.

4. After inserting a Sequence Call step, what are the three Multithreading and Remote Execution options that you can select?

5. Describe the Lock Synchronization step type and give an example of why you would use a Lock step.

6. What is a Rendezvous step?

7. What is a Notification step?

8. What properties would you examine to determine the number of test sockets in the system and the zero-based index of the test socket on which it is testing?

9. List and describe the three types of Synchronization sections within the Batch process model.

10. What is the purpose of the REngine Remote Server?


3-54

ni.com

Lesson 3


Notes


3-55


Lesson 3


Notes


3-56

ni.com

Modifying the Process Models and Overriding Callbacks

4

Lesson 4: Modifying the Process Models and Overriding Callbacks In this lesson, you will: • Identify the structure and use of process models • Modify process models • Use callbacks within your test sequences

Introduction In this lesson, you will examine a common customization to TestStand, learn how the various process models work, modify the process models, and use callbacks in your test sequences. Remember that TestStand is basically two products in one—a ready-to-run test executive and a customizable test executive that can suit any test environment. As you work through this lesson, consider which aspects of TestStand you might need to customize for your specific objectives.


4-1


Lesson 4


What is a Process Model? (Review) • A sequence file that contains common operations of the test system that execute before and after the test sequence : – – – – –

Serial number entry Generating reports Logging to databases Displaying Pass/Fail banners Successive UUT Testing

• Contains configurations of these operations – Report options – Database options – Model options

• Is associated with a client sequence file

What is a Process Model? (Review) Testing a UUT requires more operations than executing a set of tests. Usually, the test executive must perform a series of operations before and after it executes the sequence that performs the test. Common operations which define the testing process include identifying the UUT, notifying the operator of the Pass/Fail status, generating a test report, and logging results. The set of operations and their flow of execution is called a process model. The process model contains a chain of steps and sequences that perform a series of operations before and after testing the UUT. For example, the PreUUT Callback is part of the process model and is responsible for gathering the serial numbers of the UUTs. Another example is the TestReport Callback, which is also located inside the process model, which handles the generation of the test report. The process model performs both operations, outside the client sequence file. In addition to these operations, the process model contains special sequences called Configuration entry points. These sequences configure certain features of the process model. By default, when you execute a test sequence using Single Pass or Test UUTs, the test sequence file becomes the client sequence file of the process model. The process model then performs a set of operations before and after executing the test sequence. In other words, when you execute a test sequence using a Process Model entry point, the test sequence does not run directly. Instead, the test sequence executes as the client sequence file of the process model.


4-2

ni.com

Lesson 4


Default Process Model (Review) Sequential Model: Test UUTs Mode Pre-UUT Callback Setup Main Cleanup Main Sequence Setup Main

Pre-UUT Loop Pre-UUT Main Sequence

Loop Until Operator Quits

Post-UUT Generate Report

Cleanup Post-UUT Loop

Default Process Model: (Review) The flowchart above depicts the order in which TestStand executes the Main sequence and all the TestStand callback sequences for the Test UUTs mode of the Sequential process model. When you initiate the Test UUTs mode, TestStand executes the PreUUTLoop Callback (test system setup operations), followed by the PreUUT Callback (UUT setup operations). These callback sequences are always part of the process model, unless you modify the process model yourself. Process model customization and callbacks are discussed later in this lesson. The next step is the MainSequence step, which is the test sequence you created using the sequence editor. TestStand then executes the PostUUT Callback (UUT clean up operations) and updates a test report. Execution then returns to the PreUUT Callback for the next UUT to be tested. On completion of testing, TestStand steps out of the loop, generates a test report, and executes the PostUUT Loop Callback test (system clean up operations).


4-3


Lesson 4


Anatomy of a Process Model The TestStand process model is a collection of special typed sequences. Blue Green

Normal—A standard test sequence. Callback—A sequence that allows customized behavior of the process model from the client sequence. Entry Points—Sequences that give the user different ways to invoke a main sequence. Execution—A sequence that runs test programs. Configuration—A sequence that configures a process model feature.

Red Purple

Anatomy of a Process Model TestStand process models are sequence files composed of sequences. Sequences within a process model sequence file can be one of the two following types of callbacks that have unique properties. •

Normal—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. Sequences in non-model sequence files can only be normal sequences. The other sequence types are only relevant within a process model.

•

Model callbacks—Sequences that entry point sequences call and that the client sequence files can override. By marking sequences in a process model file as callbacks, you specify the set of process model operations that a sequence developer can customize. Some Model callbacks have full implementations. For example, the TestReport callback in the default process model is sufficient to handle most types of test results. Other Model callbacks are merely placeholders that you override with sequences in the client file. For example, the MainSequence callback in the model file is a placeholder for the MainSequence callback in the client sequence file. Model callbacks are discussed in more detail later in this lesson.


4-4

ni.com

Lesson 4


Anatomy of a Process Model (Continued)

Anatomy of a Process Model (Continued) 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. You can specify the following two types of entry points: •

Execution entry point—Runs a test program. 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 appear in the Execute menu. Execution entry points appear in the menu only when the active window contains a sequence file that has a MainSequence callback.

•

Configuration entry point—Configures a feature of the process model. Configuration entry points usually save the configuration information in a .ini file in the \Cfg directory. By default, Configuration entry points appear in the Configure menu. For example, the default process model contains the Configuration entry point, Configure Report Options. The Configure Report Options entry point is visible as Report Options in the Configure menu.


4-5


Lesson 4


Modifying the Process Models Two methods: • Overriding model callbacks • Modifying the process model directly

Modifying the Process Models The TestStand process models contain sequences that define operations before and after testing a UUT, such as querying for serial numbers or report generation. There are two ways to modify the process models—overriding callbacks and modifying the process model directly. The following slides discuss these methods in more detail.


4-6

ni.com

Lesson 4


Modifying the Process Models—Callbacks • Callbacks are sequences that TestStand calls under certain circumstances and times during execution • Callbacks are divided into three categories: – Model – Engine – Front-End

Modifying the Process Models—Callbacks One method of modifying the process model is to override callbacks. Callbacks are sequences that TestStand calls under certain circumstances and at certain times during execution. The callbacks are divided into three sections: Model, Engine, and Front-End. The following slides will cover these in more detail. You can create new callback sequences or you can replace existing callbacks to customize the operation of the test station.


4-7


Lesson 4


Model Callbacks • Contained within the process models • Used to customize the behavior of the process model without modifying the process model directly • Examples of Model callbacks: – TestReport Callback – PreUUT Callback – MainSequence Callback

Model Callbacks By default, each test sequence you execute uses the process model that you select for the entire test station. Use a Model callback to customize the behavior of a process model for each client sequence file that uses it. Model callbacks are sequences in a process model that you configure to be a callback. A user can override a Model callback by creating a sequence of the same name as the callback within the client sequence file. When the process model executes, TestStand checks the client sequence file for any sequences that have the same name as the callbacks defined within the process model. If there are such sequences, the process model executes the code within the sequences located in the client sequence file and bypasses those defined in the process model. By defining one or more model callbacks in a process model, you specify the set of process model operations that you can customize. 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. The sequence developer can, however, override the default TestReport callback by defining a different TestReport callback in a particular client sequence file. Another example of a callback is the MainSequence callback. In every sequence file you create, TestStand automatically inserts a sequence named MainSequence. Therefore, the MainSequence of the sequence file overrides the MainSequence callback defined in the process model. In other words, when the process model reaches the MainSequence callback in its


4-8

ni.com

Lesson 4


execution, the process model checks the client sequence file for the MainSequence and runs the code that you have defined inside the MainSequence within the client sequence file.


4-9


Lesson 4


Process Model and Callbacks Process Model

Client #1 PreUUT

MainSequence

PreUUT

MainSequence

Client #2 MainSequence

PostUUT PostUUT

Process Model and Callbacks Consider two separate client sequence files, Client #1 and Client #2, that utilize the same process model. Client #1 contains code that reads a serial number from a database, while Client #2 uses the default PreUUT Callback that prompts the user to enter the serial number. In addition, Client #2 does not display the Pass/Fail banner of the default PostUUT Callback, but Client #1 does. Rather than creating two separate process models for each client sequence file, you can use callbacks to implement the unique requirements of each client and use the same process model for the client sequence files. When execution of Client #1 begins, the process model detects that there are two callback sequences within the sequence file—PreUUT and MainSequence. When the process model reaches these callbacks, it executes the callback of the client file instead of the callback sequence that is defined in the process model. Therefore, the default code which displays a serial number dialog box does not appear. Instead, TestStand executes the code contained in the callback. A Pass/Fail banner displays because Client #1 does not override the PostUUT Callback. When execution of Client #2 begins, the process model detects that there are two callback sequences within the client sequence file—PostUUT and MainSequence. When the process model reaches these callbacks, it executes the callback of the client sequence file instead of the callback sequence that is defined in the process model. Therefore, the default code that displays the Pass/Fail banner dialog box does not appear. Instead, the code contained in the PostUUT Callback executes. Because Client #2 does not override the PreUUT Callback, the user is prompted to enter a serial number.


4-10

ni.com

Lesson 4


Creating a Model Callback To create a Model callback: 1. Add a new sequence to your process model file. 2. Right-click the sequence and select Properties from the context menu. 3. Click the Model tab and select Callback from the Type ring control.

Creating a Model Callback You define a Model callback by adding a sequence to the process model file, defining it as a callback, and 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. To create a Model callback, complete the following steps: 1. Add a new sequence to the process model file. 2. Right-click the sequence and select Properties from the context menu. 3. Click the Model tab and select Callback from the Type ring control.


4-11


Lesson 4


Overriding Model Callbacks

Overriding Model Callbacks To specify the Model callbacks you want to override, use the Sequence File Callbacks dialog box. The slide above demonstrates the selection for overriding the TestReport model callback. Select Edit»Sequence File Callbacks in an active Sequence File window to launch the Sequence File Callbacks dialog box. This dialog box displays the callbacks you can override. Any callbacks marked yes are overridden. Notice that the MainSequence callback is overridden. To override a Model callback, select the callback you want to override and click Add to insert that callback into the sequence file. Select the callback and click Edit in the Sequence File Callbacks dialog box to edit the new callback.


4-12

ni.com

Lesson 4


Engine Callbacks • Defined by the TestStand Engine and invoked under specific conditions • You can configure Engine callbacks to call defined sequences: – – – – – –

Before and after individual step execution Before and after interactive execution When loading a sequence file When unloading a sequence file After a run-time error When a step fails

Engine Callbacks The TestStand Engine defines a set of callbacks, called Engine callbacks, that it invokes at specific points during execution. TestStand defines the name of each Engine callback. Engine callbacks allow you to configure TestStand to call certain sequences before and after the execution of individual steps, before and after interactive executions, after loading a sequence file, or 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, of the TestStand Reference Manual for a complete list of the Engine callbacks in TestStand.


4-13


Lesson 4


Engine Callbacks (Continued) Exist in the following three groups based on location: • Normal sequence files – Affect behavior in that specific sequence • Process model files – Affect all client sequences of the process model • The StationCallbacks.seq file – Affects all sequences including the process model sequence file

Engine Callbacks (Continued) The three groups of Engine callbacks are defined by the file where they appear. The Engine callbacks are defined in the StationCallbacks.seq file, the process model file, or the test sequence file. TestStand invokes Engine callbacks in a normal sequence file only when executing steps in the sequence file or during loading or unloading of the sequence file. TestStand can invoke 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 the Engine callbacks in the StationCallbacks.seq file whenever TestStand executes steps on the test station. Certain types of Engine callbacks, such as PostStep, are common across the three groups. Depending on where the callback is defined, the effect of the callback is different. For example, if PostStep is defined as a Normal Sequence Engine callback, SequenceFilePostStep, after every step in that sequence file executes, a defined action occurs. If PostStep is defined as a Process Model Engine callback, ProcessModelPostStep, a defined action occurs after execution of every step of the process model client sequence. If PostStep is defined in the StationCallbacks.seq file, StationPostStep, a defined action occurs after execution of every step of every sequence file and the process model. Engine callbacks defined in the StationCallbacks.seq file have the highest level scope and affect all sequence files on the test station. If it is necessary to implement a particular functionality of the PostStep different than what is defined in StationCallbacks.seq for a particular sequence


4-14

ni.com

Lesson 4


file, you can use a sequence file level Engine callback. Even though a station level PostStep Engine callback is defined, the sequence level PostStep Engine callback takes precedence. The same situation occurs if a process model level Engine callback is defined and a sequence level Engine callback of the same type, but different functionality, is defined. Note TestStand installs predefined Station Engine callbacks in the StationCallbacks.seq file in the \Components\NI\ Callbacks\Station directory. Add your own Station Engine callbacks in the StationCallbacks.seq file in the \Components\User\ Callbacks\Station directory.


4-15


Lesson 4


Overriding Engine Callbacks

Overriding Engine Callbacks Engine callbacks are different from Model callbacks in that they are a set of predefined callbacks that the TestStand Engine invokes at specific points during execution. Engine Callbacks are in three general groups, based on the file in which the callback sequence appears. You can define Engine callback sequences in normal sequence files, process model files, or the station callbacks file to control when TestStand invokes the Engine callbacks. 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. You can override Engine callbacks in the same manner as Model callbacks. Select the callback you want to override and click the Add button to insert the callback into the test sequence file. The SequenceFilePostStepFailure callback is an example of an Engine callback that you can use in a test sequence if you want to execute a specified group of steps when any step in the test sequence fails.


4-16

ni.com

Lesson 4


Front-End Callbacks • Sequences that are called external of the process model or test sequence • Defined in the \Components\ NI\Callbacks\FrontEnd\ FrontEndCallbacks.seq file

• The FrontEndCallbacks.seq file contains the LoginLogout sequence • Invoke using the Engine.CallFrontEndCallbackEx API method • Add a new Front-End callback sequence to the FrontEndCallbacks.seq file

Front-End Callbacks Front-End callbacks are sequences in the FrontEndCallbacks.seq file that operator interface programs call. Front-End callbacks allow multiple operator 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 operator interfaces that come with TestStand call LoginLogout. When you implement operations as Front-End callbacks, you write them as sequences. Thus, you can modify a Front-End callback without modifying the source code for the operator interfaces or rebuilding the executables for them. For example, to change how the various operator interfaces perform the login procedure, you only have to modify the LoginLogout sequence in the FrontEndCallbacks.seq. You can create new Front-End callbacks by adding a sequence to the FrontEndCallbacks.seq file. You then can invoke this sequence from each of the operator interface programs that you use by using the Engine.CallFrontEndCallbackEx method of the TestStand API. You cannot edit the source for the TestStand Sequence Editor. Thus, you 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 \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 \Components\User\Callbacks\FrontEnd directory.


4-17


Lesson 4


Modifying Process Models Directly Directly Modifying Callbacks • Modify the default callbacks and/or actions used in the process model • You also can add user-defined callbacks and/or actions to the process model

Modifying Process Models Directly Method 2—Directly Modifying Callbacks The other method of modifying the process models is to modify the process model sequence files directly or replace them entirely, which alters the behavior of the process model for all sequences. When you create a new process model, copy the TestStandModel folder from the \ Components\NI\Models directory to the \Components\ User\Models directory. You can edit the copy of the process model to include new callbacks and steps necessary for your test environment. By default, TestStand searches for the specified process model in the \Components\User\Models directory before searching in the \Components\NI\Models directory. You can configure the search directories by selecting Configure»Search Directories. You can configure TestStand to use a different process model by selecting Configure»Station Options and clicking the Model tab. Note For Exercise 4-2, do not modify the default \Components\NI\ Models\TestStandModels\SequentialModel.seq. Instead, follow the instructions to copy it to the \Components\User\Models\ TestStandModels directory before making any modifications.


4-18

ni.com

Lesson 4


Exercise 4-1: Modifying and Overriding Callbacks Objective: To modify the execution of the process model by using callbacks. Estimated Time: 20 minutes



4-19


Lesson 4


Exercise 4-2: Editing a TestStand Process Model Objective: To edit a TestStand process model. Estimated Time: 20 minutes



4-20

ni.com

Lesson 4


Lesson 4 Summary • You can modify the following TestStand components: – Process model – Result collection – Report generation

– Operator Interface – Step types – Data types

• Two options available for modifying process models are: – Overriding callbacks – Modifying the process models directly

• There are three types of callbacks available: – Model – Engine – Front-End

Summary In this lesson, you learned how to modify the process models and override callbacks to suit your particular test environment needs. You can customize the process model by overriding certain callback sequences or altering the process model directly. Remember to make a copy of the process model sequence file if you want to make any direct modifications, otherwise installing TestStand can overwrite your modification.


4-21


Lesson 4



Modifying and Overriding Callbacks

To modify the execution of the process model by using callbacks.

Part A: Overriding PreUUT and PostUUT Callbacks A Model callback is a sequence explicitly defined in the process model to run at a certain point in an execution. 1. Select Configure»Station Options and configure TestStand to use the Sequential process model. In the Station Options dialog box, click the Model tab and select SequentialModel.seq from the Station Model ring control. 2. Open the Ex 4-1 Modifying Callbacks.seq file located in the C:\Exercises\TestStand II directory. 3. Select Edit»Sequence File Callbacks to open the Modifying Callbacks dialog box, shown in Figure 4-1.

Figure 4-1. Modifying Callbacks Dialog Box

4. Configure the Sequence File Callbacks dialog box. a. In the Callback Name column, select the PreUUT Callback and click Add. The setting in the Present column should change from no to yes. This causes TestStand to override the default PreUUT Callback sequences in the process model with callbacks specific to this file. b. Select the PostUUT Callback and click Add. This causes TestStand to override the default PostUUT Callback sequence in the process model with callbacks specific to this file. Note

Double-click the callback name add steps to the sequence file.


4-22

ni.com

Lesson 4


c. Click OK to return to the sequence editor. 5. Select All Sequences from the View ring control. Notice that the sequence file now has five sequences: MainSequence, CPU Diagnostics, CPU Test, PreUUT, and PostUUT as shown in Figure 4-2.

Figure 4-2. All Sequences View

6. Select PreUUT from the View ring control. Notice that initially this is an empty sequence with no steps in the Setup, Main, or Cleanup step groups. However, there are two parameter variables already included in this sequence that are inherent to the PreUUT Callback. You will use these parameters later in this exercise to modify the PreUUT Callback. Click the Parameters tab to view these parameters. The appearance of the PreUUT Callback applies for the PostUUT Callback also. Initially, this is an empty sequence with two existing parameters that are inherent to the PostUUT Callback. Note

Because these two callbacks are included in the sequence file, TestStand uses these callback sequences when executing the PreUUT and PostUUT Callbacks instead of calling these sequences from the process model. The default PreUUT Callback contains steps that display the UUT serial number prompt. Additional Information The default PostUUT Callback contains steps that display the status banner at the end of the test, indicating whether the test passed or failed. When you override these callbacks and leave these callback sequences


4-23


Lesson 4


as empty (no steps), TestStand does not display the UUT serial number prompt or the test status banner. 7. Select Execute»Test UUTs. Notice that TestStand does not display the UUT serial number prompt or the test status banner. Instead, it immediately starts the next UUT test without asking for the next UUT serial number. In fact, because the UUT serial number prompt does not display, there is no way to stop this test. 8. Click Terminate Execution to stop the execution.

End of Part A Part B: Modifying PreUUT and PostUUT Callbacks In this part of the exercise, you will insert steps in the PreUUT Callback sequence so it displays a Message Popup dialog box to act as the UUT serial number prompt. 1. Close any open Execution windows. 2. Select the PreUUT sequence from the View ring control. 3. Insert a Message Popup step and name this step Obtain UUT serial number. 4. Insert a Statement step and name this step Check to continue. 5. Insert another Statement step and rename it Set UUT serial number. Figure 4-3 shows the completed sequence.

Figure 4-3. PreUUT Sequence View


4-24

ni.com

Lesson 4


6. Modify the Message Popup step so it requests the test operator to enter a UUT serial number. a. Right-click the Message Popup step and select Edit Message Settings from the context menu. Complete the following information: Title Expression:

"UUT Information"

Message Expression: "Enter UUT Serial Number" Button 1:

"OK"

Button 2:

"STOP"

Active Control:

Response String

Figure 4-4 shows the resulting Text and Buttons tab of the Configure Message Popup Step dialog box.

Figure 4-4. Configure Message Popup Text and Buttons Tab


4-25


Lesson 4


b. Click the Options tab to configure the options as shown in Figure 4-5.

Figure 4-5. Configure Message Popup Options Tab

c. Click OK to close the Configure Message Popup Step dialog box. 7. Right-click the Check to continue step and select Edit Expression from the context menu. Enter the following information or use the Expression Browser dialog box to select the variables. Expression: Parameters.ContinueTesting =(RunState.Sequence.Main ["Obtain UUT serial number"].Result.ButtonHit == 1)

8. Click OK to close Edit Statement Step dialog box. 9. Right-click the Set UUT serial number step and select Edit Expression from the context menu. Complete the following information or use the Expression Browser dialog box to select variables. Expression: Parameters.UUT.SerialNumber = RunState.Sequence.Main ["Obtain UUT serial number"].Result.Response


4-26

ni.com

Lesson 4


Figure 4-6 shows the resulting Edit Statement Step dialog box.

Figure 4-6. Edit Statement Step Dialog Box

10. Click OK to close the Edit Statement Step dialog box. 11. Save and run the sequence using Execute»Test UUTs. You have just created the steps to display a message popup, determine whether the user has clicked the Stop button, and store the UUT serial number into a parameter.

End of Part B Part C: Adding Engine Callbacks Into the Sequence File So far, you have used PreUUT and PostUUT Callbacks. These callbacks belong to a set of Model callbacks, meaning that these callbacks are called by the process model. Some other Model callbacks that the process model calls are PreUUTLoop, PostUUTLoop, and TestReport. Select Edit»Sequence File Callbacks from the sequence editor to view a complete list of Model callbacks. This list also contains Engine callbacks. Engine callbacks are called directly by the TestStand Engine rather than the process model. Note

In this part of the exercise, you will insert the SequenceFileLoad and SequenceFilePostStepFailure Engine callbacks in the sequence file. The SequenceFileLoad callback executes only when the file is opened. The SequenceFilePostStepFailure callback executes only during the execution of the sequence file when a certain steps fails. 1. Close any open Execution windows. Open the Ex 4-1 Modifying Callbacks.seq file located in the C:\Exercises\TestStand II directory.


4-27


Lesson 4


2. Select Edit»Sequence File Callbacks. Select the SequenceFileLoad callback from the list and click Add. The Present column should change to yes as shown in Figure 4-7.

Figure 4-7. Modifying Callbacks Dialog Box

3. Select the SequenceFilePostStepFailure callback from the list and click Add. 4. Click OK to close the Sequence File Callbacks dialog box and return to the sequence editor. 5. In the sequence editor, change the View ring control to SequenceFileLoad to edit this callback sequence. 6. Insert a Message Popup step and rename the step Display info. The Display info step displays the user name of the user who is currently logged into TestStand as well as the absolute pathname of the sequence file. 7. Right-click the Display info step and select Edit Message Settings from the context menu. Complete the following information or use the Expression Browser dialog box to select the variables. Title Expression:

"File Information"

Message Expression: "You are logged on as: "+ StationGlobals.TS.CurrentUser.Login Name + " \n\nYou have opened the following sequence file: " + RunState.SequenceFile.Path


4-28

ni.com

Lesson 4



Figure 4-8. Configure Message Popup Step Dialog Box for Display Info Step

8. Click OK to close the Configure Message Popup Step dialog box. 9. From the Sequence File window, change the View ring control to SequenceFilePostStepFailure to edit this callback sequence. 10. Insert a Message Popup step and rename the step Failure message. This Message Popup step displays the step name that failed during execution. 11. Right-click the Failure message step and select Edit Message Settings from the context menu. Complete the following information or use the Expression Browser to select the variables. Title Expression:

"Failure"

Message Expression: "The following step failed: \n\n" + NameOf(Parameters.Step)


4-29


Lesson 4



Figure 4-9. Configure Message Popup Step Dialog Box for Failure Message Step

12. Save and close the sequence file. 13. Open the sequence file and verify that the message popup displays when the file loads. 14. Select Execute»Test UUTs and select a step to fail. When a step fails, a message popup should display the name of the step that failed.

End of Part C Optional: Customize PostUUT Callback sequence Create steps in the PostUUT Callback sequence that display a message popup indicating whether the test passed or failed.

Hint Create two Message Popup steps and set a precondition for each step.

End of Exercise 4-1


4-30

ni.com

Lesson 4



Editing a TestStand Process Model

To edit a TestStand process model.

Part A: Creating an Execution Entry Point In addition to creating new callbacks inside the sequence file to override the Process Model callbacks, TestStand allows you to modify the process model itself. The modifications described in the previous exercise affect only the sequence file to which you add callbacks. In this exercise, you modify the process model directly. The changes you make affect every sequence file that uses the process model. Note Whenever you modify a process model, complete the following procedure to duplicate a default process model. If you do not follow this procedure, TestStand might not correctly run certain sequences, and you might need to reinstall TestStand.

If you have not already done so, complete the following steps to make a copy of the Sequential process model so the original Sequential process model remains unchanged. 1. Using Windows Explorer, navigate to \Components\ NI\Models. 2. Select the TestStandModels directory and select Edit»Copy or press the keys to copy. 3. Navigate to the \Components\User\Models directory and select Edit»Paste or press the keys. Remember the search order that TestStand uses to look for sequences and code modules. In the search order, TestStand searches Components\User before Components\NI, so TestStand finds the files in the User directory first. 4. In the sequence editor, close all open sequence files. Open the SequentialModel.seq file located in the \ Components\User\Models\TestStandModels directory. 5. Select All Sequences from the View ring control to display all sequences within the SequentialModel.seq file. The sequences are color coded. The four different colors represent the four types of sequences, as shown in Table 4-1.


4-31


Lesson 4


Table 4-1. Sequence Types

Sequence Type

Color

Purpose

Normal

Light Blue

Subsequences called by entry points or callbacks

Callback

Green

Execution Entry Point Configuration Entry Point Engine Callbacks

Sequence of process model that can be overridden in a client sequence file.

Red

Sequence that defines an Execution entry point that appears in the Execute menu.

Dark Blue

Sequence that defines the behavior of one of the options on the Configure menu.

Purple

Sequences that influence the behavior of certain pre-defined aspects in the TestStand engine.

The SequentialModel.seq file currently has two Execution entry points: TestUUTs and Single Pass. Add another Execution entry point for debugging. 6. Select the Test UUTs sequence and select Edit»Paste to paste a copy of the sequence below the Test UUTs sequenc. Rename the new sequence Debug Mode. Figure 4-10 shows the resulting All Sequences view of the SequentialModel.seq file.


4-32

ni.com

Lesson 4


Figure 4-10. All Sequences View with New Debug Mode Sequence

7. Right-click the Debug Mode sequence and select Properties from the context menu to open the Sequence Properties dialog box. 8. Click the Model tab. The Type ring control identifies this sequence as an Execution entry point. Keeping all other options as they are, change the Entry Point Name Expression to "Debug Mode" and change the Entry Point Enabled Expression to True as shown in Figure 4-11. Click OK to close the Debug Mode Properties dialog box. Additional Information The Entry Point Name Expression text field indicates what string appears in the menu to execute this entry point. The Entry Point Enabled Expression text field determines whether or not to enable the entry point name in the menu. The Test UUTs and Single Pass entry points use a ResStr function in the entry point name expression. TestStand uses this method to keep all menu strings in a resource file to make translation to other languages easier. You will not use the ResStr function in this exercise. Note


4-33


Lesson 4


Figure 4-11. Debug Mode Properties Dialog Box

9. Select the Debug Mode sequence from the View ring control. Because the Debug Mode sequence was copied from the Test UUTs sequence, the contents of the sequences are the same. 10. Add a Message Popup step to the Debug Mode sequence after the Clear Report step. Rename the step Debug Mode Message. 11. Right-click the Debug Mode Message step and select Edit Message Settings from the context menu. In the Edit Message Settings dialog box, enter the following information: Title Expression:

"Debug Mode Popup"

Message Expression: "Running in debug mode." Note

Be sure to include the quotation marks in the expression to denote it as a string. 12. Click OK to close the Configure Message Popup Step dialog box. 13. Right-click the Debug Mode Message step and select Properties from the context menu to Disable Result Recording for the Debug Mode Message step. On the Run Options tab, disable the Record Results option. Click OK to close the Step Properties dialog box.


4-34

ni.com

Lesson 4


Figure 4-12 shows the completed sequence.

Figure 4-12. Completed Sequence

The remaining steps change the Debug Mode sequence so it executes in the same manner as the Test UUTs Execution entry point but does not generate a test report at the end. 14. Scroll down in the Debug Mode sequence to the TestReport Callback step. Select this step, right-click, and select Run Mode»Skip from the context menu. The Execution Flow column for this step should now show Skip, Precondition, indicating that TestStand will skip the step. 15. Repeat step 14 setting the following steps to skip: Set Report, the first instance of Write UUT Report, and Read Entire Report. 16. Save the process model sequence.

End of Part A Part B: Examine Changes Resulting from Editing the Sequential Process Model 1. Open the Ex 4-2 Editing Process Model.seq file located in the C:\Exercises\TestStand II directory. 2. Select Edit»Sequence File Properties. Click the Advanced tab of the Sequence File Properties dialog box. Under Model Options, select Require Specific Model and browse to the SequentialModel.seq file that you just edited in the \Components\User\ Models\TestStandModels directory. This causes TestStand to always use that particular process model for the sequence file.


4-35


Lesson 4


In this exercise, TestStand accepts the new process model because the sequence filename is the same as the default, but in a directory higher in the search order. If the sequence file does not have the same name, TestStand has advanced options in the Sequence File Properties dialog box, located in the Edit»Sequence File Properties menu, to accept these sequence files as well. Note

3. Click OK to return to the sequence editor. Save the sequence. 4. Select Execute»Debug Mode. When the sequence runs, the message popup appears, indicating that the sequence is running in Debug Mode. Although Execution entry points appear in the Execute menu by default, you can change this setting. 5. Return to the SequentialModel.seq Sequence File window or, if it is closed, open it from the \Components\User\ Models\TestStandModels directory. 6. Change the View ring control to All Sequences. Right-click the Debug Mode sequence and select Properties from the context menu. 7. Click the Model tab. In the Menu Hint ring control, select Debug as shown in Figure 4-13.

Figure 4-13. Debug Menu Hint


4-36

ni.com

Lesson 4


8. Click OK to close the dialog box. 9. Save the sequence. 10. Return to the Ex 4-2 Editing Process Model.seq Sequence File window. 11. Select Debug»Debug Mode and verify that the Debug Mode entry point executes as before. Also, verify that when you stop the execution, it does not show you the test report. Entry points appear not only in the sequence editor, but in the operator interfaces as well. 12. Minimize the sequence editor and select Start»Programs» National Instruments»TestStand 3.5»Operator Interfaces» LabWindows-CVI to launch the LabWindows/CVI Operator Interface. Login as Administrator. 13. Open the Ex 4-2 Editing Process Model.seq file from the C:\Exercises\TestStand II directory. Verify that the Debug Mode entry point appears in the Debug menu and executes the same as it did in the sequence editor. 14. Close the LabWindows/CVI Operator Interface and close all open sequence files in the sequence editor. 15. Navigate to \Components\User\Models\ TestStandModels and delete the SequentialModel.seq file to delete this process model when you finish the exercise. This way, the rest of the exercises will use the default process model located in the \Components\NI\Models\TestStandModels

directory.



4-37


Lesson 4


Self Review 1. List the three types of callbacks and give an example of each.

2. If you wanted to change the Login dialog box installed with TestStand, which callback would you modify?

3. What are the two methods of modifying the process model? Give one reason why you would use one method over the other.

4. If you wanted to modify the UUT Information dialog box that is installed with TestStand, what callback would you override, and how would you do it?


4-38

ni.com

Lesson 4


Notes


4-39


Lesson 4


Notes


4-40

ni.com

5

Modifying the Operator Interface

Lesson 5: Modifying the Operator Interface In this lesson, you will: • Learn how operator interfaces communicate with TestStand • Identify the components of an operator interface • Modify the built-in operator interfaces

Introduction In TestStand, operator interfaces are ActiveX clients that use the TestStand API. In this lesson, you will learn how the operator interface works, the minimum programming required to build an operator interface, and how to modify the built-in operator interfaces.


5-1


Lesson 5


Definition of an Operator Interface An Operator Interface • is a graphical user interface (GUI) for executing tests at a production station • allows interaction between the user and the test system • is an ActiveX client of the TestStand Engine (ActiveX Server)


5-2

ni.com

Lesson 5


TestStand Operator Interfaces • Default operator interfaces have the same functionality – Sequence file, execution, and report view – Breakpoints and single stepping – User login

• TestStand includes five operator interfaces written in the following languages – LabVIEW – LabWindows/CVI – VisualBasic .NET – C# – C++ (MFC)

TestStand Operator Interfaces TestStand provides five built-in operator interfaces, and for many applications, one of these is likely to be sufficient with little or no modification necessary. The operator interfaces provided by TestStand all have very similar functionality. They allow you to start multiple concurrent executions, set breakpoints, and single-step just like the sequence editor. Unlike the sequence editor, however, the operator interfaces do not allow you to modify sequences, and they do not display sequence variables, sequence parameters, step properties, and other programming variables in TestStand. Typically, you do not need this functionality on the production floor. The operator interface allows you to create a simple user interface for the test operator. If the built-in operator interfaces are not sufficient to meet the needs of your application, you can customize the operator interface to have the exact functionality necessary for your particular test system and test application. TestStand provides all five operator interfaces in source code to make modifications possible. The full-featured operator interfaces are located in the \OperatorInterfaces\NI\Full-Featured directory. There are also simple versions of the built-in operator interfaces located in the \OperatorInterfaces\NI\Simple directory. These simple operator interfaces are a useful starting point when designing your own operator interfaces.


5-3


Lesson 5


TestStand User Interface (UI) Controls • Simplify programming of an OI • Provide their own API • Divided into 2 categories: – Manager Controls – Visible Controls

TestStand User Interface (UI) Controls The TestStand User Interface (UI) Controls are a set of ActiveX controls that implement the common functionality that applications need to display, execute, and debug test sequences. These ActiveX controls reduce the amount of source code an operator interface application requires. National Instruments recommends that you use the TestStand UI Controls to develop your operator interface applications. However, you also can 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 TestStand Help for more information about writing an application with the TestStand Engine API.


5-4

ni.com

Lesson 5


Manager Controls • Call TestStand API to perform various tasks • Visible at design time and invisible at run time • Three Manager controls to manage different aspects of TestStand executions: – Application Manager – SequenceFileView Manager – ExecutionView Manager

Manager Controls The 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. There are three types of Manager controls—the Application Manager, the SequenceFileView Manager, and the ExecutionView Manager. Each Manager control is responsible for specific tasks within TestStand.


5-5


Lesson 5


ApplicationMgr Control • Controls basic operations necessary to use the TestStand Engine • Performs the following tasks • Initializes and shuts down the TestStand Engine • Logs users in and out • Loads and unloads files • Launches executions • Tracks existing sequence files and executions

ApplicationMgr Control The Application Manager control controls the basic operation necessary to use the TestStand Engine. The Application Manager control performs the following tasks: •

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 only one Application Manager control that exists for the duration of the operator interface.


5-6

ni.com

Lesson 5


SequenceFileViewMgr Control • Manages how the user views and interacts with a selected sequence file • One SequenceFileView Manager control per sequence file selection or display – – – –

Sets a sequence file as the active sequence file Tracks the currently selected sequence, step group, and steps Updates the visible UI controls with sequence file information Provides methods for executing the selected sequence file

SequenceFileViewMgr Control 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.

•

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 methods for executing the selected sequence file.

Your application needs one SequenceFileView Manager control for each location, such as a window, form, or panel, where you display a sequence file or the user selects a current sequence file.


5-7


Lesson 5


ExecutionViewMgr Control • Performs tasks related to how you view and interact with an execution • One ExecutionView Manager control per execution selection or display – Sets an execution as the active execution – Updates the visible UI controls with execution information – Provides debugging commands

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

Designates an execution as the selected execution.

•

Tracks which thread, stack frame, sequence, step group, and steps 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.

Your application needs one ExecutionView Manager control for each location, such as a window, form, or panel, where you display an execution or the user selects a current execution.


5-8

ni.com

Lesson 5


Visible TestStand User Interface Controls • Displays information from and interacts with the manager controls • Visible at design time and run-time • Connects to a manager control

Visible TestStand User Interface Controls Visible TestStand UI Controls are ActiveX controls that resemble commonly used UI controls, but allow the user to connect them to manager controls to automatically display information or enable the user to select an item to view. How you add a visible TestStand UI Control is dependent upon your operator interface development environment. In LabVIEW, the controls are available on the TestStand Controls Palette. In any other programming language, you would add a visible TestStand UI Control the same way you would add any other ActiveX control. When you have added the visible TestStand UI Control to your operator interface, you can configure the controls by accessing the ActiveX properties of the controls. The configurations you set for the visible TestStand UI Controls are visible during design and during run-time. You can also change these configurations programmatically during run-time using the TestStand API.


5-9


Lesson 5


Visible TestStand UI Controls • • • • • • • • • •

Button Label ListBox ListBar ComboBox StatusBar ExpressionEdit ReportView SequenceView Checkbox

Visible TestStand UI Controls The last step of implementing a visible TestStand UI Control is to connect the visible TestStand UI Control to a manager control. There are nine visible TestStand UI Controls, including the Button, Label, ListBox, ListBar, ComboBox, StatusBar, ExpressionEdit, ReportView, and SequenceView controls. Refer to the TestStand Help for more information about each control.


5-10

ni.com

Lesson 5


Connecting Visible and Manager Controls • Connect visible TestStand UI Controls to manager controls • Manager controls automatically update visible controls at run time • Types of connections: – View connections – List connections – Command connections – Information Source Connections

Connecting Visible and Manager Controls When you connect a manager control to a visible control, the TestStand UI Controls automatically update and display information about the 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. Each type of connection is implemented using the TestStand UI Controls API.


5-11


Lesson 5


View Connections • Connect a visible TestStand UI Control that displays information about the sequence or execution and a manager control • Call the following methods to connect to view controls: –SequenceFileViewMgr.ConnectSequenceView –ExecutionViewMgr.ConnectExecutionView –ExecutionViewMgr.ConnectReportView

View Connections Use view connections to establish a connection between a visible TestStand UI Control that displays information about a sequence or execution handled by manager control. For example, you can connect manager controls to the SequenceView and ReportView controls to display the current sequence or report, respectively. Connect a SequenceFileView Manager control to a SequenceView control to display the steps in the selected step group of 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. Connect an ExecutionView Manager control to a ReportView control to display the report for the selected execution. Call the following methods to connect to view controls: •

SequenceFileViewMgr.ConnectSequenceView

•

ExecutionViewMgr.ConnectExecutionView

•

ExecutionViewMgr.ConnectReportView


5-12

ni.com

Lesson 5


List Connections • Connect a visible TestStand UI Control, such as the ComboBox, ListBox, or ListBar, to a manager control – SequenceFileViewMgr.ConnectSequenceFileList – SequenceFileViewMgr.ConnectSequenceList – SequenceFileViewMgr.ConnectStepGroupList – ExecutionViewMgr.ConnectExecutionList – ExecutionViewMgr.ConnectCallStack – ExecutionViewMgr.ConnectThreadList

List Connections Use list connections to connect a visible TestStand UI Control—such as the ComboBox, ListBox, or ListBar—to one of the manager controls. Each manager control contains information about the sequence or execution. The SequenceFileView Manager control contains sequence files, sequences, and step groups. The ExecutionView Manager control contains executions, threads, and stack frames. Call the following methods to connect a list to a ComboBox or ListBox control or a ListBar page: •

SequenceFileViewMgr.ConnectSequenceFileList

•

SequenceFileViewMgr.ConnectSequenceList

•

SequenceFileViewMgr.ConnectStepGroupList

•

ExecutionViewMgr.ConnectExecutionList

•

ExecutionViewMgr.ConnectCallStack

•

ExecutionViewMgr.ConnectThreadList

Depending on which method you use to connect the manager control to the visible TestStand UI Control, the visible control shows the contents of the TestStand list or stack. For example, if you use the method SequenceFileViewMgr.ConnectSequenceList, a list of the sequences displays in the visible TestStand UI Control. TestStand automatically updates the sequences shown in the visible TestStand UI Control if the selected sequence file changes.


5-13


Lesson 5


Command Connections • Connect a common TestStand command to a Visible TestStand UI Control • API Methods – ConnectCommand – GetCommand – NewCommands – Command.Execute

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. Each manager control contains a set of defined commands. All the defined commands are located in the CommandKinds enumeration. Refer to the TestStand Help for more information about the commands located in the CommandKinds enumeration. There are TestStand UI Controls API methods which you can use to connect and perform TestStand commands. ConnectCommand connects a command to a Button control. GetCommand and NewCommands get a command API object. Use the Command.Execute method to perform a command programmatically, without being initiated from a visible TestStand UI Control.


5-14

ni.com

Lesson 5


Information Source Connections • Display information about the state of the application – Caption connections – Image connections – Numeric value connections

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 display text that describes the status of the application. The CaptionSources enumeration defines the set of captions to which you can connect. Use the API method, ConnectCaption, of each of the manager controls to connect a caption to a Label control, an ExpressionEdit control, or a StatusBar pane. Use the API method, GetCaptionText, of each of the manager controls to obtain the text of a caption without connecting it to a control. Image connections display icons that illustrate the status of the application. The ImageSources enumeration defines the set of images to which you can connect. Use the API method, ConnectImage, of each of the manager controls to connect an image to a StatusBar pane. Use the API method, GetImageName, of each of the manager controls to obtain an image without connecting it to a control. A numeric value connection graphically displays a numeric value that illustrates the status of the application. The NumericSources enumeration defines the set of values to which you can connect. 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.


5-15


Lesson 5


TestStand UI Controls in LabVIEW • Controls palette has both manager and visible TestStand UI Controls • Control Properties Page

TestStand UI Controls in LabVIEW You can access the manager controls and the visible TestStand UI Controls from the TestStand Controls palette in LabVIEW. When you place these controls on the front panel of a VI, you can program them using the LabVIEW ActiveX functionality. You can also configure the controls interactively using the LabVIEW Property Browser or any property pages featured by the controls. Right-click any control and select Property Browser from the context menu to open the LabVIEW Property Browser. To open property pages, right-click any eligible control and select »Properties from the context menu where Control Name is the name of the currently selected control. When you have placed the TestStand controls on the front panel of your LabVIEW VI, you can programmatically modify the components and how they interact. 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.


5-16

ni.com

Lesson 5


TestStand UI Programming in LabVIEW • TestStand Utility Library VIs • Use Invoke Node and Property Node to perform Manager API methods

TestStand UI Programming in LabVIEW The TestStand Utility Library VIs are the LabVIEW versions of the functions in the TestStand Utility Functions Library, or TSUtil. These VIs are located on the TestStand palette. The TestStand Utility Library VIs assist user interface developers with the following tasks: •

Inserting menu items that automatically execute commands provided by the TestStand UI Controls.

•

Localizing the strings on your user interface. These VIs are compatible with LabVIEW 6.1 or later.

•

Making dialog boxes that are launched by LabVIEW VIs modal to TestStand applications. These VIs are compatible with LabVIEW 6.1 or later.

•

Checking whether an execution that calls a VI has stopped. These VIs are compatible with LabVIEW 6.1 or later.

•

Setting and getting the values of TestStand properties and variables.

To access the help for a TestStand Utility Library VI, place the VI on a LabVIEW block diagram, right-click the VI, and select Help from the context menu.


5-17


Lesson 5


TestStand UI Controls in LabWindows/CVI

TestStand UI Controls in LabWindows/CVI To add a TestStand UI Control to a panel in the LabWindows/CVI User Interface Editor, select Create»ActiveX and select a UI control whose name begins with TestStand UI. You can configure a UI control using the standard LabWindows/CVI Edit Control dialog box, which you launch by double-clicking the control. To open property pages that are supported by a UI control, right-click the control and select Properties from the context menu.


5-18

ni.com

Lesson 5


TestStand UI Programming in LabWindows/CVI • TestStand UI Controls driver – \API\CVI directory

• Other ActiveX function panel files – TestStand UI Controls tsui.fp – TestStand UI Support Library tsuisupp.fp – TestStand Utility Functions tsutil.fp – TestStand API tsapicvi.fp

TestStand UI Programming in LabWindows/CVI To access the methods, properties, and events specific to an ActiveX control, you must use the ActiveX driver for the control. The TestStand UI Controls driver and additional support instrument drivers are located in the \API\CVI directory. Add the following function panel files to the LabWindows/CVI project for your TestStand application. •

TestStand UI Controls (tsui.fp)—Contains functions for dynamically creating controls, calling methods and accessing properties on controls, and handling events from the controls.

•

TestStand UI Support Library (tsuisupp.fp)—Contains functions for various collections that the TestStand UI Controls driver uses.

•

TestStand Utility Functions (tsutil.fp)—Contains utility functions for managing menu items that correspond to TestStand commands, localizing strings on the user interface, making dialog boxes associated with LabWindows/CVI code modules modal in respect to TestStand applications, and checking whether an execution that calls a code module has stopped.


5-19


Lesson 5


•

TestStand API (tsapicvi.fp)—Provides low-level access to TestStand objects. For each interface that the ActiveX control supports, the driver contains a function that you can use to programmatically create an instance of the ActiveX control. The ActiveX driver also includes functions that you can use to register callback functions for receiving events defined by the control.

Languages besides LabVIEW and LabWindows/CVI are handled in their native language support.


5-20

ni.com

Lesson 5


Exercise 5-1: Building an Operator Interface Exercise 5-1A: Building a LabVIEW Operator Interface Exercise 5-1B: Building a LabWindows/CVI Operator

Interface

Objective: To gain an understanding of how an operator interface works and the minimum required components to build an operator interface. Estimated Time: 60 minutes Refer to page 5-27 for instructions for Exercise 5-1A. Refer to page 5-35 for instructions for Exercise 5-1B.


5-21


Lesson 5


What is a UIMessage? • UIMessages allow the engine and operator interface to communicate • The engine sends UIMessages to inform the operator interface of the current state of execution • Default messages handled by manager controls

What is a UIMessage? The TestStand Engine uses UIMessages to send information about the state of the engine and the current executions to your application. The TestStand Engine posts a default set of messages depending on the various events that occur. A unique event code identifies each of these events. These UIMessages include Start Execution, End Execution, Trace, and so on. By default, the Application Manager control handles all the default messages posted by the engine. TestStand defines a base value event code TS_UIMsg_UserMessageBase(=10000), beyond which you can define

customized UIMessages for unique purposes. You must program the operator interface to respond to custom UIMessages or User Messages. The sequence editor discards custom UIMessages so they do not affect operation of the sequence editor.


5-22

ni.com

Lesson 5


How To Post Custom UIMessages? • TestStand Engine posts the UIMessages • You can inform the engine to post additional UIMessages from sequences and code modules • Post a UIMessage using the PostUIMessageEx method • Post Synchronously or Asynchronously How to Post a UIMessage The TestStand Engine posts all the UIMessages. Some of the UIMessages originate from the TestStand Engine while test sequences or code modules might request others. You can request that the TestStand Engine post a UIMessage by calling the PostUIMessageEx method from the Thread class in the TestStand API. You can access the thread object of an executing sequence through the RunState.Thread property. When posting a UIMessage you must use a unique event code equal to or greater than the UserMessageBase of 10,000. You can also post messages that are either asynchronous or synchronous. Synchronous messages prevent the thread which posted the message from continuing until the operator interface handles the message, that is, closes the reference of calling UIMessage.Acknowledge. Asynchronous messages do not prevent the thread from continuing to other processes. The UIMessages that the engine automatically posts are asynchronous, so the execution continues while the UIMessage is handled. When you post custom UIMessages, you have the option of setting these messages as synchronous or asynchronous.


5-23


Lesson 5


How to Detect Custom UIMessages • TestStand Application Manager control handles default UIMessages • Configure the manager controls to handle custom UIMessages – ApplicationManager.UserMessage Event – Add case to UserMessage Event Handler

How to Detect Custom UIMessages Depending on how you create the Engine object, you can set up the UIMessage handler in one of several ways. Each of these methods are illustrated in at least one of the operator interfaces that TestStand provides. When you have posted the UIMessage, you need to handle that UIMessage in your operator interface. The TestStand Application Manager control automatically handles the default UIMessages. If you have a User Message, you must add code to handle that message in your operator interface. Whenever a User Message is posted, the User Event is initiated. For your operator interface to obtain UIMessage objects, you must implement a function to handle the event. The engine calls the event handler when it receives a UIMessage. If you do not provide an event handler, you can set the Engine.UIMessagePollingEnabled property to True and call the Engine.GetUIMessage method to poll for UIMessage objects. Both the Application Manager and Execution Manager controls have events that notify your application that a UserMessage has occurred. You can handle that event using an event handler function. You can have only one event handler assigned to a custom UIMessage. The event handler must include code to handle each custom event that you post. This is usually implemented using a case structure.


5-24

ni.com

Lesson 5


Exercise 5-2: Handling Custom UI Messages Exercise 5-2A: Handling Custom UI Messages Using LabVIEW Exercise 5-2B: Handling Custom UI Messages Using LabWindows/CVI Objective: To handle custom UI messages. Estimated Time: 60 minutes

Refer to page 5-45 for instructions for Exercise 5-2A. Refer to page 5-52 for instructions for Exercise 5-2B.


5-25


Lesson 5


Lesson 5 Summary • Three Manager Controls, Application Manager, Sequence File View Manager, and Execution View Manager, handle TestStand executions and events • Connect the visible TestStand UI Controls to the manager controls to automatically update the operator interface • UIMessages allow the engine and operator interface to communicate. You can define custom UIMessages. Summary In this lesson, you learned about another important component of TestStand, the operator interface. The operator interface is an ActiveX client application separate from the sequence editor. Because it is separate and provided in source code, you can ensure that each operator possesses the test interface you designate. The TestStand manager and UI Controls help to significantly simplify the code required to build an operator interface. Using the ActiveX API of TestStand and the visible TestStand UI Controls, you can modify what the operator views during sequence execution to suit your particular test environment needs. You can use the simple operator interface examples that ship with TestStand to create a new operator interface. You can also modify one of the full operator interface examples.


5-26

ni.com

Lesson 5


Exercise 5-1A Building a LabVIEW Operator Interface Objective:

To learn how to use and modify the LabVIEW Operator Interface.

Part A: Creating a LabVIEW Operator Interface In this exercise, you learn how to build a basic LabVIEW Operator Interface that is based on the minimum required components for an operator interface. The operator interface you build in this exercise will be capable of opening and executing a sequence file through the Single Pass and Test UUTs Execution entry points. However, it will not contain all the additional features that are built into the standard operator interfaces that ship with TestStand. Using a limited set of features makes it easier to understand how the operator interface works. 1. Launch LabVIEW and open the Ex 5-1A Simple OI.vi file located in the C:\Exercises\TestStand II\VIs directory. 2. Build the front panel shown in Figure 5-1 using the following instructions.

Figure 5-1. LabVIEW Operator Interface Front Panel


5-27


Lesson 5


a. Add the following TestStand UI Controls located on the TestStand palette to the LabVIEW Operator Interface front panel: Application Manager, SequenceFileView Manager, and ExecutionView Manager. These controls interact with the TestStand Engine in a predefined manner. The TestStand manager controls do not display on the user interface at run-time, but must be present to manage the visible TestStand UI Controls. b. Add the TestStand UI SequenceView Control located on the TestStand palette to the front panel. This control is configured to display the run-time information about the execution. Rename the control Execution Display. c. Add the TestStand UI ReportView Control located on the TestStand palette to the front panel. This control displays the completed report generated by TestStand. Rename the control Report. d. Add five TestStand UI Button Controls to the front panel. Right-click the control and select Property Browser from the context menu to change the caption for each control. Enter the following captions: Open Sequence File, Run Selected Sequence, Test UUTs, Single Pass, and Exit. Enter the caption in the Caption field as shown in Figure 5-2. Change the label of each button to match its caption and hide the labels.

Figure 5-2. Property Browser

e. Add two TestStand UI ComboBox Controls to the front panel. Right-click the control and select Properties from the context menu to change the ComboBox control labels to Sequence File and Sequences, respectively. Enter the name in the Label field.


5-28

ni.com

Lesson 5


3. Set the VI to be the TestStand Application Window so that TestStand recognizes that this is a main operator interface. a. Select Window»Show Block Diagram to open the block diagram of the VI. b. Place the TestStand - Set TestStand Application Window VI located on the TestStand palette on the block diagram. c. Wire the TestStand UI Application Manager control to the Application Manager input of the TestStand - Set TestStand Application Window VI. 4. Connect the visible Exit Control to the Application Manager Control. a. Place an Invoke Node located on the ActiveX palette on the block diagram. b. Wire the TestStand UI Application Manager control to the reference input of the Invoke Node. c. Right-click the Method terminal and select Methods» ConnectCommand from the context menu. d. Wire the Exit button to the uiObj input. e. Right-click the cmdKind input and select Create Constant from the context menu. Click the enumerated constant and select CommandKind_Exit. Figure 5-3 shows the Exit button connection to the TestStand UI Application Manager control.

Figure 5-3. Exit Button Connection

To change the appearance of controls and indicators on the LabVIEW block diagram, right-click the control or indicator and enable or disable View As Icon on the context menu. Tip

5. Connect the Open Sequence File, Run Selected Sequence, Single Pass, and Test UUTs buttons to the TestStand UI SequenceFileView Manager control using the same technique. For each button, select a


5-29


Lesson 5


CommandKind that matches the intended behavior of the button. Refer to Figure 5-4 for CommandKind and additional parameter information. 6. Connect the Sequence File and Sequences combo boxes to the SequenceFileView Manager control using the ConnectSequenceFileList and ConnectSequenceList methods, respectively. Figure 5-4 shows a portion of the resulting block diagram.

Figure 5-4. Sequence Manager Connections

7. Connect the Execution Display control to the TestStand UI Execution View Manager control using the ConnectExecutionView method. 8. Connect the Report control to the TestStand UI Execution View Manager control using the ConnectReportView method. Figure 5-5 shows a portion of the resulting block diagram.

Figure 5-5. Execution View Manager Connections


5-30

ni.com

Lesson 5


9. Wire the error out output from the Invoke Node configured to call the ConnectReportView method to the error in input of the Create User Event function. The Create User Event function creates a quit event to quit the operator interface programmatically. 10. Wire the TestStand UI SequenceFileView Manager control and the TestStand UI ExecutionView Manager control to the Bundle function. 11. Wire the Application Manager reference from the Application Manager ConnectCommand Invoke Node output to the Application Manager Start Invoke Node input and to the Application Manager input of the Configure Event Callbacks VI. 12. Wire the output cluster of the Bundle function to the User Parameters input of the Configure Event Callbacks VI. Figure 5-6 shows a portion of the resulting block diagram.

Figure 5-6. Create User Event Connection

13. Save the VI.

End of Part A


5-31


Lesson 5


Part B: Using the LabVIEW Operator Interface Now you will use the basic operator interface you have built. 1. Select Window»Show Front Panel to return to the front panel. Click Run in LabVIEW to execute the project. 2. Click Open Sequence File and select the sequence file you want to execute. Navigate to the computer.seq file located in the \Examples\Demo\C directory and click OK. Notice that the Sequence File combo box automatically updates with the sequence file you selected. The Sequences combo box automatically updates with the sequences in the selected sequence file. The visible TestStand UI Controls automatically update because you connected them to the appropriate TestStand manager controls. 3. Click one of the following buttons to select an execution mode—Single Pass, Test UUTs, or Run Selected Sequence. The operator interface executes the selected test sequence according to the Execution entry point you select. The SequenceView control automatically updates as the execution progresses. When the test completes, the report automatically displays. After the execution completes, the report displays in the format last specified in the Report Options dialog box in TestStand. 4. Click Exit on the operator interface to quit.

End of Part B Part C: Modifying the Basic LabVIEW Operator Interface Some of the visible TestStand UI Controls have property pages which you can use to configure what information displays and how that information displays during run-time. In this section, you will configure the TestStand Execution window to show the high and low limits of a step. 1. Open the front panel of the Ex 5-1A Simple OI VI. 2. Right-click the TestStand Sequence View control and select SequenceView»Properties from the context menu. 3. Click the Columns tab and click Add to add a new column. 4. Name the new column Low Limit and enter Low Limit in the Caption field. Select Expression from the Type ring control.


5-32

ni.com

Lesson 5


5. In the Expression field, type or use the Expression Browser dialog box to create the following statement: PropertyExists("Step.Limits.Low")? Step.Limits.Low : ""

Figure 5-7 shows the resulting dialog box.

Figure 5-7. Low Limits Expression

6. Click Add to add a new column. 7. Name the new column High Limit and enter High Limit in the Caption field. Select Expression from the Type ring control.


5-33


Lesson 5


8. In the Expression field, type or use the Expression Browser dialog box to create the following statement: PropertyExists("Step.Limits.High")? Step.Limits.High : ""


Figure 5-8. High Limits Expression

9. Click OK to close the Properties dialog box. 10. Save the VI. 11. Click Run in LabVIEW to execute the VI. Click Open Sequence File and select the sequence file you want to execute. Navigate to the computer.seq file located in the\Examples\Demo\C directory and click OK. Notice that the low and high limits display for the Power On and Video Test steps because these steps contain the Limit.Low and Limit.High properties. 12. Click Exit to close the operator interface. 13. Close the VI and LabVIEW when you finish testing the operator interface.

End of Part C End of Exercise 5-1A


5-34

ni.com

Lesson 5


Exercise 5-1B Building a LabWindows/CVI Operator Interface Objective:

To learn how to use and modify the LabWindows/CVI Operator Interface.

Part A: Creating a LabWindows/CVI Operator Interface In this exercise, you will learn how to build a basic LabWindows/CVI operator interface that is based on the minimum required components for an operator interface. The operator interface you build in this exercise will be capable of opening and executing a sequence file through the Single Pass and Test UUTs Execution entry points. However, it will not contain all the additional features that are built into the standard operator interfaces that ship with TestStand. Using a limited set of features makes it easier to understand how the operator interface works. 1. Launch LabWindows/CVI and select File»Open»Project. Open the Ex 5-1B Simple OI.prj file located in the C:\Exercises\ TestStand II\CVI Project Files directory. 2. Open the Ex 5-1B Simple OI.uir file. Complete the following steps to add the TestStand UI Controls listed in Table 5-1 to the user interface panel. Position the controls on the panel as shown in Figure 5-9. Some controls have already been added for you.

Figure 5-9. LabWindows/CVI Simple OI UIR Panel


5-35


Lesson 5


a. Right-click the panel and select ActiveX from the context menu. b. Select TestStand UI Button Control from the list of ActiveX Objects and click OK. c. Right-click the TestStand UI Button Control and select Edit Control from the context menu to open the Edit ActiveX Control dialog box. d. In the Edit ActiveX Control dialog box you can change the default properties of the control, assign a name to the control, and set the CVI properties. •

Change the Constant Name to OPENFILEBTN.

•

Delete the label text.

•

The ActiveX Property Page of the control appears in the middle of the Edit ActiveX Control dialog box. Change the ActiveX Caption property to OPEN_FILE. The caption specifies the text that displays in the control. Figure 5-10 shows the resulting Edit ActiveX Control dialog box.

Figure 5-10. Edit ActiveX Control Dialog Box


5-36

ni.com

Lesson 5


e. Add the following controls in the same manner. Table 5-1. TestStand UI Controls

Control Type

Constant Name

Caption

TestStand UI Button Control

ENTRYPOINT2BTN

TestStand UI ComboBox Control

SEQUENCECOMBOBOX

—

TestStand UI SequenceView Control

EXECUTIONVIEW

—

TestStand UI ReportView Control

REPORTVIEW

—

TestStand UI Application Manager

APPLICATIONMGR

—

TestStand UI SequenceFileView Manager

SEQUENCEFILEVIEWMGR

—

TestStand UI ExecutionView Manager

EXECUTIONVIEWMGR

—

ENTRY_POINT2

The last three controls in Table 5-1 are the TestStand manager controls. They do not appear on the user interface at run-time, but must be present to manage the visible TestStand UI Controls. The resulting user interface should be similar to Figure 5-9. 3. Save the UIR file. 4. Double-click the Ex 5-1B Simple OI.c source file in the project tree in the right pane of the LabWindows/CVI window. 5. Place the cursor at the top of the file and press the key to go to the first tag. This section declares all the ActiveX control handles to the TestStand controls that this example uses. 6. Press the key to go to the next tag. This is the main function of the operator interface example. This function loads the user interface and calls functions to set up the ActiveX controls, gets a reference to the TestStand Engine, and starts the TestStand User Interface Components. 7. Complete the contents of the SetupActiveXControls function. a. Press the key to go to the next tag inside the SetupActiveXControls function. This function gets handles to the ActiveX controls, registers the ActiveX event callbacks, and connects the controls to a specific TestStand manager control. b. Add code to get the handles for the ActiveX controls you added to the UIR. Some of the code is already written for you. Use the LabWindows/CVI function panels to complete the following code.


5-37


Lesson 5


Select View»Find Function Panel and enter the name of the function you want to insert to. All the function panels that match that name will open. You can also use the function panel library to navigate to a function. You will use the function panel library later in this exercise.

Tip

//get handles to ActiveX controls errChk( GetObjHandleFromActiveXCtrl(gMainWindow.panel, MAINPANEL_APPLICATIONMGR, &gMainWindow.applicationMgr)); errChk( GetObjHandleFromActiveXCtrl(gMainWindow.panel, MAINPANEL_SEQUENCEFILEVIEWMGR, &gMainWindow.sequenceFileViewMgr)); errChk( GetObjHandleFromActiveXCtrl(gMainWindow.panel, MAINPANEL_EXECUTIONVIEWMGR, &gMainWindow.executionViewMgr)); errChk( GetObjHandleFromActiveXCtrl(gMainWindow.panel, MAINPANEL_ENTRYPOINT2BTN, &gMainWindow.entryPoint2Btn)); errChk( GetObjHandleFromActiveXCtrl(gMainWindow.panel, MAINPANEL_SEQUENCECOMBOBOX, &gMainWindow.sequenceComboBox)); errChk( GetObjHandleFromActiveXCtrl(gMainWindow.panel, MAINPANEL_EXECUTIONVIEW, &gMainWindow.executionView)); errChk( GetObjHandleFromActiveXCtrl(gMainWindow.panel, MAINPANEL_REPORTVIEW, &gMainWindow.reportView));

c. Press the key to go to the next tag. In this section you need to register the ActiveX control callbacks. By registering the ActiveX control callbacks, you indicate to LabWindows/CVI which CVI Callback to execute when it receives a specific event. To add the first function call, select Instrument»NI TestStand UI Controls 3.5 from the toolbar, and select Event Callback Registration Functions»ApplicationMgrEvents»Register ExitApplication Callback. This opens the TSUI__ApplicationMgrEventsRegOnExitApplication

function panel. Complete the function panel as shown in Figure 5-11. The complete function call is displayed in the bottom pane of the function panel. If the NI TestStand UI Controls 3.5 instrument is not present in the menu, select Instrument»Load and load tsui.fp in the \API\CVI directory. Repeat this process with the tsuisupp.fp, tsutil.fp, and tsapicvi.fp.

Note


5-38

ni.com

Lesson 5


Figure 5-11. ApplicationMgrEventsRegOnExitApplication Function Panel Tip If you did not already know the prototype of the ApplicationMgr_OnExitApplication callback, you could select Help»Function to view the function help. The prototype for the CVICALLBACK is shown in the help.

You can copy and paste the prototype into your code. This example includes the CVICALLBACKs for you.

Select Code»Insert Function Call to insert the TSUI__ApplicationMgrEventsRegOnExitApplication

function call. d. Close the function panel. e. Use the function panels found in Instrument»NI TestStand UI Controls 3.0»Event Callback Registration Functions» ApplicationMgrEvents to register the ActiveX control event callbacks for the events shown in Table 5-2.


5-39


Lesson 5


Table 5-2. ActiveX Control Event Callbacks and Callback Functions

ActiveX Control Event Callback

Callback Function

Register QueryShutdown Callback

ApplicationMgr_OnQueryShutdown

Register DisplaySequenceFile Callback

ApplicationMgr_OnDisplaySequenceFile

Register DisplayExecution Callback

ApplicationMgr_OnDisplayExecution

The resulting code should be similar to the following example. The errChk function is error handling code. Note


//register ActiveX control event callbacks errChk(TSUI__ApplicationMgrEventsRegOnExitApplication(gMainWindow.applicationM gr, ApplicationMgr_OnExitApplication, NULL, 1, NULL)); errChk(TSUI__ApplicationMgrEventsRegOnQueryShutdown(gMainWindow.applicationMgr , ApplicationMgr_OnQueryShutdown, NULL, 1, NULL)); errChk(TSUI__ApplicationMgrEventsRegOnDisplaySequenceFile(gMainWindow.applicat ionMgr, ApplicationMgr_OnDisplaySequenceFile, NULL, 1, NULL)); errChk(TSUI__ApplicationMgrEventsRegOnDisplayExecution(gMainWindow.application Mgr, ApplicationMgr_OnDisplayExecution, NULL, 1, NULL));

f. Press the key to go to the next tag. Connect the Execution View control that displays the sequence during execution to the ExecutionView Manager using the following function call. Note


//connect Execution View to ExecutionView Manager tsErrChk(TSUI_ExecutionViewMgrConnectExecutionView (gMainWindow.executionViewMgr, &errorInfo, gMainWindow.executionView, TSUIConst_ExecutionViewConnection_NoOptions, NULL));

g. Press the key to go to the next tag. Connect the Report View control that displays the report during execution to the ExecutionView Manager using the following function call.


5-40

ni.com

Lesson 5

Note



//connect Report View to ExecutionView Manager tsErrChk(TSUI_ExecutionViewMgrConnectReportView(gMainWindow.executionViewMgr, &errorInfo, gMainWindow.reportView, NULL));

h. Press the key to go to the next tag. Connect the Sequence File combo box control that lists the available sequence files to the SequenceFileView Manager using the following function call. Note


//connect Sequence File combo box to SequenceFileView Manager tsErrChk(TSUI_SequenceFileViewMgrConnectSequenceFileList(gMainWindow.sequenceF ileViewMgr, &errorInfo, gMainWindow.sequenceFileComboBox, VFALSE, NULL));

i. Press the key to go to the next tag. Connect the Sequence combo box control that displays the available sequences of the selected sequence file to the SequenceFileView Manager using the following function call. Note


//connect Sequence combo box to SequenceFileView Manager tsErrChk(TSUI_SequenceFileViewMgrConnectSequenceList(gMainWindow.sequenceFileV iewMgr, &errorInfo, gMainWindow.sequenceComboBox, NULL));

j. Press the key to go to the next tag. Connect the each of the TestStand button controls to a specific TestStand command using the following function calls. Remember to use the function panels found at Instruments»NI TestStand UI Controls 3.5» SequenceFileViewMgr»Connect Command to help complete each function call. Select from the available CommandKind constants to specify which command to execute when a button is clicked.


5-41


Lesson 5


Note


//connect TestStand buttons to commands tsErrChk(TSUI_SequenceFileViewMgrConnectCommand(gMainWindow.sequenceFileViewMg r, &errorInfo, gMainWindow.openFileBtn, TSUIConst_CommandKind_OpenSequenceFile, 0, TSUIConst_CommandConnection_NoOptions, NULL)); tsErrChk(TSUI_SequenceFileViewMgrConnectCommand(gMainWindow.sequenceFileViewMg r, &errorInfo, gMainWindow.entryPoint2Btn, TSUIConst_CommandKind_ExecutionEntryPoints_Set, 1, TSUIConst_CommandConnection_NoOptions, NULL));

8. Save the changes to the file.

End of Part A Part B: Using the LabWindows/CVI Operator Interface Now you will use the basic operator interface you have built. 1. Select Run»Debug Ex 5-1B Simple OI.exe to execute the project. 2. Click Open Sequence File and select the sequence file you want to execute. Navigate to the computer.seq file located in the \Examples\Demo\C directory and click Open. Notice that the Sequence File combo box automatically updates with the sequence file you selected. The sequence combo box automatically updates with the sequences in the selected sequence file. The visible TestStand UI Controls automatically update because you connected them to the TestStand manager controls. 3. Click one of the following buttons to select an execution mode—Single Pass, Test UUTs, or Run Selected Sequence. The operator interface executes the selected test sequence according to the Execution entry point you select. The execution displays as it progresses and the SequenceView control automatically updates. When the test completes, the report automatically displays. The report displays in the format last specified in the Report Options dialog box in TestStand. 4. Click Exit on the operator interface to quit.

End of Part B


5-42

ni.com

Lesson 5


Part C: Modifying the LabWindows/CVI Operator Interface Some of the visible TestStand UI Controls have property pages which you can use to configure what information displays and how that information displays during run-time. In this section, you will configure the TestStand Execution window to show the high and low limits of a step. 1. Open the Ex 5-1B Simple OI.uir file of the LabWindows/CVI Operator Interface. 2. Right-click the TestStand SequenceView Control and select Properties from the context menu to open the SequenceView Control Properties dialog box. 3. Click the Columns tab and click Add to add a new column. 4. Name the new column Low Limit and enter Low Limit in the Caption field. Select Expression from the Type ring control. 5. In the Expression field, type or use the Expression Browser dialog box to create the following statement: PropertyExists("Step.Limits.Low")? Step.Limits.Low : ""


Figure 5-12. Low Limits Expression

6. Click Add to add a new column. 7. Name the new column High Limit and enter High Limit in the Caption field. Select Expression from the Type ring control.


5-43


Lesson 5


8. In the Expression field, type or use the Expression Browser dialog box to create the following statement: PropertyExists("Step.Limits.High")? Step.Limits.High : ""

Figure 5-13 shows the resulting Properties dialog box.

Figure 5-13. High Limits Expression

9. Click OK to close the Properties dialog box. 10. Save the operator interface. 11. Select Run»Debug Ex 5-1B Simple OI.exe to execute the project A. Click Open Sequence File and select the sequence file you want to run. Navigate to the computer.seq file located in the \Examples\Demo\C directory and click OK. Notice that the low and high limits display for the Power On and Video Test steps because these steps contain the Limits.Low and Limits.High properties. 12. Click Exit to close the operator interface. 13. Close the project file and LabWindows/CVI when you finish testing the operator interface.

End of Part C End of Exercise 5-1B


5-44

ni.com

Lesson 5


Exercise 5-2A Handling Custom UIMessages in the LabVIEW Operator Interface Objective:

To send messages to an operator interface and display information about the execution. In this exercise, you will maintain and display measurement data from a DMM and an oscilloscope in the operator interface. The sequence file sends the measurement data to the operator interface using UIMessages. During an execution, the TestStand Engine notifies the operator interface about the state of the execution by posting UIMessages or events to the operator interface. Each operator interface must handle these events in order to update information about the execution. TestStand defines several events, such as EndExecution, Trace, and BreakOnBreakpoint. For example, the Start Execution event notifies the operator interface that an execution has started. The operator interface might take an action when it receives the event, such as turn on an LED. By default, the TestStand manager controls handle the TestStand-defined UIMessage events. Refer to the TestStand Help for more information about UIMessageCodes. You can send custom UIMessages to update progress and status on the operator interface. When you post a message, you can send string data, numeric data, and/or ActiveX data with the message. For this exercise, you will create and post a UIMessage to update the DMM measurement and the oscilloscope measurement data displayed on the operator interface. You can define your own events by using an event number that is greater than or equal to the value of the UIMsg_UserMessageBase constant.

Part A: Posting a message from the execution 1. Launch the TestStand Sequence Editor and open the Voltage Test Sequence.seq file located in the C:\Exercises\TestStand II directory. 2. Select the ActiveX/Com Adapter from the Adapter ring control. 3. Insert an Action step below the Read Voltage step. Name the step Send Voltage Measurement.


5-45


Lesson 5


4. Right-click the Send Voltage Measurement step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

RunState.Thread

Automation Server:


Object Class:

Thread

Action:

Call Method

Method:

PostUIMessageEx

Click the ring control in the eventCode value field, select UIMsg_UserMessageBase, and enter +0 after UIMsg_UserMessageBase to complete the first argument, eventCode. Configure the remaining parameters using the following information.

Note

numericDataParam:

Locals.Voltage

stringDataParam:

""

activeXDataParam:

Nothing

synchronous:

True

TestStand uses the keyword Nothing to specify a NULL object reference. This step instructs the TestStand Engine to post a UIMessage to the operator interface with an event code of 10,000 (UIMsg_UserMessageBase + 0) that contains the Voltage value. You can post a UIMessage from a LabVIEW VI, a LabWindows/CVI project, a DLL, any code module, or a step that uses the ActiveX/COM Adapter. In this exercise, you use the ActiveX/COM Adapter.


5-46

ni.com

Lesson 5


Figure 5-14 shows the resulting Edit ActiveX/COM Call dialog box.

Figure 5-14. Edit ActiveX/COM Call Dialog Box

5. Click OK to close the Edit ActiveX/COM Call dialog box. 6. Insert an Action step below the Scope Measurement step. Name the step Send Scope Waveform. 7. Right-click the Send Scope Waveform step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

RunState.Thread

Automation Server:


Object Class:

Thread

Action:

Call Method

Method:

PostUIMessageEx

Click the ring control in the eventCode value field, select UIMsg_UserMessageBase, and enter+1 after


5-47


Lesson 5


UIMsg_UserMessageBase to complete the first argument, eventCode. Configure the remaining parameters using the following information. numericDataParam:

0

stringDataParam:

""

activeXDataParam:

ThisContext

synchronous:

True



This step instructs the TestStand Engine to post a UIMessage with an event code of 10,001 (UIMsg_UserMessageBase + 1) that contains an ActiveX reference to the sequence context of the current execution. 8. Click OK to close the Edit ActiveX/COM Call dialog box. 9. Save the sequence.

End of Part A


5-48

ni.com

Lesson 5


Part B: Handling Custom UIMessage Events in the LabVIEW Operator Interface Now that the TestStand Engine has posted the custom UIMessage events, you must add code to the operator interface to handle these events. 1. Launch LabVIEW and open the Ex 5-2A Simple OI.vi located in the C:\Exercises\TestStand II\VIs directory. The front panel has been modified to include an indicator for the DMM measurement and an indicator for the oscilloscope measurement. 2. Select Window»Show Block Diagram to open the block diagram. Notice there is a reference to the DMM Measurement and a reference to the Scope Measurement. These references are bundled and sent to the Configure Event Callbacks VI. 3. Open the Configure Event Callbacks VI by double-clicking it. This VI registers all the ActiveX events that are not handled by the TestStand Manager Controls. There is an extra case added for the UserMessage Event. To register an additional event, select the border of the Register Event Callback VI and drag the border to create another event, then select the event from the list of possible events by clicking the arrow. In this exercise, this step has been done for you.

Tip

4. Complete the Configure Events Callback VI using the following information. a. Wire the Application Manager output to the UserMessage input of the Reg Event Callback Node. b. Wire the DMM Measurement and Scope Measurement indicators to a Bundle function and wire the output of the Bundle function to the User Parameter input of the Reg Event Callback Node. c. Right-click the VI Ref input and select Create Callback VI from the context menu to create a VI that executes every time a UserMessage Event is received. Figure 5-17 shows the Configure Event Callbacks VI.


5-49


Lesson 5


Figure 5-16. Configure Events Callback VI

5. Double-click the Callback VI to open it and select Window» Show Block Diagram to open the block diagram. Because this VI executes each time a UserMessage is received, you need to add code to handle each custom UIMessage. Complete the block diagram as shown in Figure 5-17 and Figure 5-18.

Figure 5-17. Case 10,000 of UserMessage Event Callback Case Structure


5-50

ni.com

Lesson 5


Figure 5-18. Case 10,001 of UserMessage Event Callback Case Structure

Create the Property Object refnum control by placing an Automation Refnum on the Front Panel. Right-click the Automation Refnum and choose Select ActiveX Class. Browse to the NationalInstruments.TestStand.Interop.API and select the PropertyObject object. Tip

The case structure should also have a default case. The default case does not need to contain any code. 6. Save the VI as UserMessageCallback.vi in the C:\Exercises\ TestStand II\VIs directory. Close all open VIs. 7. Run the Ex 5-2A Simple OI.vi with the Voltage Test Sequence.seq file. The DMM Measurement and Scope Measurement indicators should update during sequence execution. 8. Close the files, saving any changes.

End of Part B End of Exercise 5-2C


5-51


Lesson 5


Exercise 5-2B Handling Custom UIMessages in the LabWindows/CVI Operator Interface Objective:

To send messages to an operator interface and display information about the execution. In this exercise, you will maintain and display measurement data from a DMM and an oscilloscope in the operator interface. The sequence file sends the measurement data to the operator interface using UIMessages. During an execution, the TestStand Engine notifies the operator interface about the state of the execution by posting UIMessages or events to the operator interface. Each operator interface must handle these events in order to update information about the execution. TestStand defines several events, such as EndExecution, Trace, and BreakOnBreakpoint. For example, the Start Execution event notifies the operator interface that an execution has started. The operator interface might take an action when it receives the event, such as turn on an LED. By default, the TestStand manager controls handle the TestStand-defined UIMessage events. Refer to the TestStand Help for more information about UIMessageCodes. You can send custom UIMessages to update progress and status on the operator interface. When you post a message, you can send string data, numeric data, and/or ActiveX data with the message. For this exercise, you will create and post a UIMessage to update the DMM measurement and the oscilloscope measurement data displayed on the operator interface. You can define your own events by using an event number that is greater than or equal to the value of the UIMsg_UserMessageBase constant.

Part A: Posting a Message from the Execution 1. Launch the TestStand Sequence Editor and open the Voltage Test Sequence.seq file located in the C:\Exercises\TestStand II directory. 2. Select the ActiveX/COM Adapter from the Adapter ring control. 3. Insert an Action step below the Read Voltage step. Name the step Send Voltage Measurement.


5-52

ni.com

Lesson 5


4. Right-click the Send Voltage Measurement step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

RunState.Thread

Automation Server:


Object Class:

Thread

Action:

Call Method

Method:

PostUIMessageEx

Click the ring control in the eventCode value field, select UIMsg_UserMessageBase, and enter +0 after UIMsg_UserMessageBase to complete the first argument eventCode. Configure the remaining parameters using the following information.

Note

numericDataParam:

Locals.Voltage

stringDataParam:

""

activeXDataParam:

Nothing

synchronous:

True

TestStand uses the keyword Nothing to specify a NULL object reference. This step instructs the TestStand Engine to post a UIMessage to the operator interface with an event code of 10,000 (UIMsg_UserMessageBase + 0) that contains the Voltage value. You can post a UIMessage from a LabVIEW VI, a LabWindows/CVI project, a DLL, any code module, or a step that uses the ActiveX/COM Adapter. In this exercise, you use the ActiveX/COM Adapter.


5-53


Lesson 5




5. Click OK to close the Edit ActiveX/COM Call dialog box. 6. Insert an Action step below the Scope Measurement step. Name the step Send Scope Waveform. 7. Right-click the Send Scope Waveform step and select Specify Module from the context menu. Configure the Edit ActiveX/COM Call dialog box using the following information. Object Reference:

RunState.Thread

Automation Server:


Object Class:

Thread

Action:

Call Method

Method:

PostUIMessageEx


5-54

ni.com

Lesson 5


Click the ring control in the eventCode value field, select UIMsg_UserMessageBase, and enter +1 after UIMsg_UserMessageBase to complete the first argument, eventCode. Configure the remaining parameters using the following information. numericDataParam:

0

stringDataParam:

""

activeXDataParam:

Locals.Waveform

synchronous:

True



This step instructs the TestStand Engine to post a UIMessage with an event code of 10,001 (UIMsg_UserMessageBase + 1) that contains an ActiveX reference to the sequence context of the current execution. 8. Click OK to close the Edit ActiveX/COM Call dialog box. 9. Save the sequence.

End of Part A © National Instruments Corporation

5-55


Lesson 5


Part B: Handling Custom UIMessage Events in the LabWindows/CVI Operator Interface Now that the TestStand Engine has posted the custom UIMessage events, you must add code to the operator interface to handle these events. 1. Launch LabWindows/CVI and open the Ex 5-2B Simple OI.cws file located in the C:\Exercises\TestStand II\CVI Project Files directory. 2. Open the Ex 5-2B Simple OI.uir file. Notice that the user interface has two additional controls—a meter that represents the value of a DMM measurement taken from the sequence and a graph that represents the value of an oscilloscope measurement taken from the sequence. 3. Close the Ex 5-2B Simple OI.uir file. 4. Open the Ex 5-2B Simple OI.c file. Place the cursor at the the top of the file and press the key twice to go to the line where the UIMessage UserMessage event is registered. This function call tells LabWindows/CVI to execute the ApplicationMgr_OnUIMessage callback each time a UserMessage is received from TestStand. 5. Press the key again to go to the ApplicationMgr_OnUserMessage callback. All the variables are declared for you. You will add code to retrieve and display the DMM Measurement and Scope Measurement data for the two custom User Messages. 6. The 10,000 case is the event code for the DMM Measurement UIMessage. This case executes when a UIMessage with event ID 10,000 is received. Add the following lines of code to get the DMM measurement value and update the DMM control. You do not need to enter the comments; they have been added to the .c file. Note

The following code is for illustration purposes only. // DMM Measurement data from TestStand tsErrChk(TS_UIMessageGetNumericData (uiMsg, &errorInfo, &dmmMeasurementData)); // Update DMM Display on UIR with the DMM Measurement Value SetCtrlVal (gMainWindow.panel, MAINPANEL_DMMDISPLAY, dmmMeasurementData);

7. The 10,001 case is the event code for the Scope Measurement UIMessage. This case executes when a UIMessage with event ID 10,001 is received. Because the UIMessage passes a reference to the waveform data, you must convert the reference so you can retrieve the waveform


5-56

ni.com

Lesson 5


data from the oscillioscope. Add the following lines of code inside the 10,001 case to get the oscilloscope measurement data. You do not need to enter the comments because they have been added to the .c file. Note

The following code is for illustration purposes only. //Get waveform ActiveX data tsErrChk(TS_UIMessageGetActiveXData (uiMsg, NULL, &tempActiveXRef)); //Convert LPUNKNOWN to Variant tempTSWaveform = CA_VariantIUnknown (tempActiveXRef); //Convert variant to object handle errChk(CA_VariantConvertToType(&tempTSWaveform, CAVT_OBJHANDLE, &TSWaveform)); //Get contents of waveform tsErrChk(TS_PropertyGetValVariant (TSWaveform, &errorInfo, "", 0, &tmpVariant)); //Convert the one-dimensional Safe Array passed in //the Variant parameter into a dynamically allocated //C-style array. errChk(CA_VariantGet1DArray(&tmpVariant, CAVT_DOUBLE, &scopeMeasurementData, &numElements)); //Update waveform graph with scope measurement data PlotY(gMainWindow.panel, MAINPANEL_SCOPEDISPLAY, scopeMeasurementData, numElements, VAL_DOUBLE, VAL_THIN_LINE, VAL_EMPTY_SQUARE, VAL_SOLID, 1, VAL_RED); //Free the memory allocated by CA_VariantGet1DArray CA_FreeMemory(scopeMeasurementData);

8. Save the file and select Run»Debug Ex 5-2B Simple OI.exe to execute the code.


5-57


Lesson 5


9. Open the Voltage Test Sequence.seq file and run the MainSequence. The DMM Measurement and Scope Measurement should update during sequence execution. 10. Save and close the files when you finish.

End of Part B End of Exercise 5-2B


5-58

ni.com

Lesson 5


Self Review 1. What are the three TestStand manager controls?

2. How is a visible TestStand UI Control different from a normal UI control such as a button?

3. What are UIMessages used for?

4. How do you post a UIMessage? From where can you post UIMessages?

5. How do you assign a visible TestStand UI Control to a specific function or display?


5-59


Lesson 5


Notes


5-60

ni.com

6

Modifying Result Collection and Report Generation

Lesson 6: Modifying Result Collection and Report Generation In this lesson, you will: • Identify the difference between result collection and report generation • Modify result collection • Customize report generation

Introduction In this lesson, you will learn how to modify result collection, how to add extra result data, and how to customize report generation.


6-1


Lesson 6


Why Modify Result Collection? Memory (ResultList) Report Generation

Result Collection

Sequence Execution

Report

Why Modify Result Collection? Most users can easily understand why you might need to modify the report generation features in TestStand. However, it is not always clear why you also might need to modify the result collection. Creation of the report in TestStand involves two steps—result collection and report generation. By default, TestStand collects certain step properties into memory and generates a report. •

Result Collection—The report can only contain what has been collected into memory during the execution of the sequence. By default, TestStand collects all subproperties of Step.Result into memory (ResultList). You must explicitly add any extra results you want to the result collection, and you must modify report generation to include the new data or content in the generated report.

•

Report Generation—Modifying the content and appearance of the report involves changes in both result collection and report generation. TestStand generates a report from the contents of the ResultList in memory. You can change the appearance of the report by modifying the sequences or DLLs that generate the report.


6-2

ni.com

Lesson 6


When and Where Results are Stored • Results of each test step are stored in the Locals.ResultList after the step executes • Locals.ResultList is an initially empty array of containers

When and Where Results are Stored TestStand automatically collects the results of each step. Each sequence has a ResultList local variable that is an initially empty array of containers. TestStand appends a new container property to the end of the ResultList array before a step executes. This container property is called the Step Result. After the step executes, TestStand automatically copies the contents of the Result subproperty for the step (that is, Step.Result) into the appropriate step result container of the ResultList array. •

You can control the result collection option for each step from the Run Options tab of the Step Properties dialog box.

•

You can control result collection for an entire sequence from the Sequence Properties dialog box.

•

You can enable/disable result recording for all sequences on a station level from the Execution tab of the Station Options dialog box.


6-3


Lesson 6


What Results are Stored Sequence

Step 0

Step.Result Step.TS Step.*

Step 1

Step.Result Step.TS Step.*

Locals.ResultList (array)

Step Result [0] (container) Step Result [1] (container)

Step n-1 Step.Result Step.TS Step.*

Step Result [n-1] (container)

* Indicates other items may be present depending on step type

What Results are Stored In TestStand, each step type can have a different set of subproperties under its Step.Result property. Therefore, the Step Result varies according to the step type. 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 container, it also adds information such as the name of the step and its position in the sequence. In addition to copying step type dependent step properties, TestStand adds a set of standard properties to each step result. TestStand adds standard result properties to the Step Result as subproperties of the TS property. These standard result properties include the StartTime, TotalTime, ModuleTime, Index, StepName, StepGroup, StepID, InteractiveExeNum, and StepType properties.


6-4

ni.com

Lesson 6


View of Actual Results ResultList property indicates that six steps have stored their results • [0] contains results of step index 0, • [1] contains results of step index 1, and so on

View of Actual Results The figure above shows an actual view of a Locals.ResultList variable that contains some collected step results. Each container in the ResultList array stores the results for its respective step in the sequence. For example, Locals.ResultList[0] contains the step results for the first step in the sequence, and so on. Notice that within each ResultList container you see several elements such as the Error container, the TS container, and the status of the step. You can expand each of these containers to reveal more result information for the step. The figure above was obtained by completing the following steps: 1. Open any sequence of steps and place a breakpoint before the end of the sequence. 2. Execute the sequence by selecting Execute»Single Pass. 3. When the sequence pauses at the breakpoint, select the Context tab from the Execution window and expand the Locals.ResultList container to view the contents.


6-5


Lesson 6


Subsequence Results • Locals.ResultList[x].TS.SequenceCall • The ResultList of the subsequence is shown below as a property within the results of a SequenceCall step

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 sequence. The subproperty name varies depending on the type of step that called the subsequence or generated a call to a callback sequence. For example, TS.SequenceCall is the subproperty name for a Sequence Call step type, and TS.PostAction is the subproperty name for a Post Action callback. TestStand adds the following properties to the above subproperty for each subsequence called. •

SequenceFile—Absolute path of the sequence file that contains the subsequence.

•

Sequence—Name of the subsequence that the step called.

•

Status—Status of the subsequence that the step called.

•

ResultList—Value of Locals.ResultList for the subsequence that the step called. This property contains the results for the steps in the subsequence.

The ResultList of the subsequence passes back up to the calling sequence. Therefore, the ResultList of the top level test sequence is conveniently passed back to the process model sequence that called the MainSequence of the test sequence.


6-6

ni.com

Lesson 6


Modifying Result Collection • Involves changing the contents of the Locals.ResultList property • The following are common methods for adding results: – AddExtraResult method of the TestStand API – Insert subproperties in Locals.ResultList – Add subproperties to Step.Result

Modifying Result Collection There are three techniques that can be used to modify result collection in TestStand. The different methods for changing the contents of the Locals.ResultList property are listed below: •

Use the AddExtraResult method of the TestStand API

•

Directly insert subproperties into Locals.ResultList

•

Add subproperties to Step.Result


6-7


Lesson 6


Method 1—AddExtraResult Method • Add any number of extra results by calling this method repeatedly • Add property to the ResultList for every step that contains property

Method 1—AddExtraResult Method Call this method to specify a step property for TestStand to copy to the ResultList after the execution of each step. TestStand always copies each subproperty within the Result property of each step to the ResultList, if the step has a Result property. You can use the AddExtraResult method of the TestStand API to specify an additional step property to include in the ResultList. If a step does not have the property you specify, it does not add that property to the ResultList element for that step. You can add any number of extra results by calling this method repeatedly. You can call this method using an ActiveX/COM Adapter step within a sequence or from within a code module. Use the following syntax for the AddExtraResult method: Execution.AddExtraResult(propertyName, resultPropertyName) propertyName string—The name of the property to add to the results, for

example, Step.Limits.High resultPropertyName string—The name with which to store the copy of

the property in the results list entry for each step Other useful methods are DeleteExtraResult and ClearExtraResultList.


6-8

ni.com

Lesson 6


Method 1—AddExtraResult Method (Continued)

Method 1—AddExtraResult Method (Continued) Notice that Limits.Low, Limits.High, and Comp are not subproperties of the Result object. Because they exist outside this special property, TestStand does not know to automatically include them in the Locals.ResultList array. However, depending on the report options you select in the Report Options dialog box, you can include the subproperties in the report. In the process model, the subsequence call Setup Result Settings contains two steps—Include Limits in Results and Include Comparison Type in Results. Both of these steps make use of the AddExtraResult method of the Execution class. You can call this method by using the ActiveX/COM Adapter or using code that can be called from within TestStand. The process model demonstrates how to use the ActiveX/COM Adapter with this method. The AddExtraResult method can be used in any sequence, including other process model subsequences and generic test sequences. This technique is useful when you know the step property that you want to copy to the ResultList array. For example, if you create a custom step type with the property Step.MyMeasurement, you can use the AddExtraResult method to ensure that the value of MyMeasurement is copied from every step that contains it to the appropriate step result container in the ResultList.


6-9


Lesson 6


Method 2—Add Subproperty to Locals.ResultList • A code module can use the TestStand API to insert a subproperty directly into the ResultList • Use the SetValNumber, SetValString, or SetValBoolean methods of the PropertyObject class • Use InsertIfMissing for the options parameter used in the above methods

Method 2—Add Subproperty to Locals.ResultList You can add additional information to the ResultList of a test sequence by using the TestStand API to insert subproperties directly into the ResultList. You can do this using the SetValNumber, SetValString, or SetValBoolean methods of the PropertyObject class from within your code modules. You must select InsertIfMissing for the property options parameter of the method you use. This allows TestStand to insert the new subproperty and its associated value directly into the ResultList. This technique is useful if you do not know what Result property to insert until run time. Depending on your needs, you can insert most data types directly into ResultList. After you insert the property into the ResultList, you must set the flags of the inserted property to include the IncludeInReport option.


6-10

ni.com

Lesson 6


Method 3—Add Subproperty to Step.Result • TestStand copies each subproperty within Step.Result to the ResultList • Following are two ways in which you can add subproperties to the Step.Result property. – Create a custom step type and add a subproperty to the Step.Result property – Use the TestStand API to dynamically add a subproperty to the Step.Result property

Method 3—Add Subproperty to Step.Result Another way to add extra data to the ResultList is to add a new subproperty to the Step.Result property. Use one of the following ways to add a new subproperty to the Step.Result property. •

Create a custom step type and add a subproperty to the Step.Result property of the step type. This technique is useful if you plan to make custom step types.

•

Use the TestStand ActiveX API to dynamically add a subproperty to the Result property of the step. The methods of the PropertyObject class have an option parameter.

•

Set the option parameter to PropOption_InsertIfMissing to create a new property if the property specified by the lookup string does not exist. PropOption_InsertIfMissing is an enumeration with the assigned value of 1.

In either case, you must set the flags of the inserted property to include the IncludeInReport option.


6-11


Lesson 6


Exercise 6-1: Modifying Result Collection Options Objective: To demonstrate some of the options for modifying result collection in TestStand. Estimated Time: 20 minutes



6-12

ni.com

Lesson 6


Formatting Results into a Report Report Header

Process Model

(reportgen_xxx.seq)

Test UUTs/Single Pass

Test Report Callback ResultList[0]

Report Body Test Report

(modelsupport2.dll)

Sequence Report Footer (reportgen_xxx.seq)

Formatting Results into a Report The TestReport sequence is a model callback that the execution entry point sequences call to generate the contents of the test report for each UUT. The default process model defines a test report for a UUT consisting of a header, an entry for each step result, and a footer. TestStand has two options available for creating the report body—the DLL option and the sequence option. When you select the DLL option, the TestReport sequence calls a single function in modelsupport2.dll to build the entire report body before returning. The LabWindows/CVI project and source code for this DLL is located in the \ Components\NI\Models\TestStandModels directory. The DLL option is selected by default, allowing TestStand to generate reports faster. However, when using the DLL option, the ModifyReportEntry callback does not execute. If the Sequence option is enabled in the Report Options dialog box, the TestReport sequence calls the AddReportBody sequence in reportgen_txt.seq, reportgen_html.seq, or reportgen_xml.seq to build the report body. The sequence report generator uses a series of sequences that recursively process the contents of the ResultList parameter.


6-13


Lesson 6


Customizing Report Generation Five methods available: 1. Configure Report Options dialog box 2. Add text to Step.Result.ReportText 3. Use automatic reporting flags 4. Override test report callbacks 5. Directly modify test report callbacks and/or report generation files

Customizing Report Generation Method 1—Modify settings in the Report Options dialog box. Method 2—Use Step.Result.ReportText. Method 3—Use automatic reporting flags. Method 4—Override report callbacks. There are five callbacks related to report generation: Report Options, Test Report, ModifyReportHeader, ModifyReportEntry, and ModifyReportFooter. Method 5—Directly modify one of the components of report generation. These components include the above callbacks, and the files reportgen_txt.seq, reportgen_html.seq, and reportgen_xml.seq that are called by the TestReport callback. The sequences contained in the files reportgen_txt.seq, reportgen_html.seq, and reportgen_xml.seq add the header, body, and footer for a UUT into an ASCII, HTML, or XML report, respectively. Note Before you change the components, copy the \Components\NI\ Models\TestStandModels directory to the \Components\User\ Models directory. Then edit the copy of the SequentialModel.seq file. By default, TestStand searches for the SequentialModel.seq file in the \ Components\User\Models directory before searching in the \ Components\NI\Models\TestStandModels directory. Select Configure»

Search Directories to configure the search directories.


6-14

ni.com

Lesson 6


Method 1—Configuring the Report Options Dialog Box

Method 1—Configuring the Report Options Dialog Box Launch the Report Options dialog box by selecting Configure» Report Options. You can customize report properties such as the filename of report, path, which data items are included in the report, filtering for report, and color settings for XML and HTML reports. You also can set which report format to use (ASCII, HTML, or XML).


6-15


Lesson 6


Method 2—Using Step.Result.ReportText

Method 2—Using Step.Result.ReportText Each default step type has a ReportText subproperty. This property, found under Step.Result.ReportText, contains a message string that TestStand automatically includes in the report. The default report generation only adds the ReportText string when it is not empty, providing you with an easy way to add text to the report. You do not need to make any customizations to use this feature. TestStand automatically detects whether you add text to Step.Result.ReportText. You can set the value of the message string directly in your code module. The LabVIEW and LabWindows/CVI Adapters allow code modules to set this property by modifying the corresponding member of the test data structure or cluster. Refer to Chapter 5, Module Adapters, of the TestStand Reference Manual for more information about the property assignments that the module adapters automatically perform to and from step properties. You also can set the value of the message using a TestStand expression, such as the following string: Step.Result.ReportText = "This is a ReportText String."

The result from this expression would appear in the report as shown in the figure above.


6-16

ni.com

Lesson 6


Method 3—Automatic Reporting Flags Certain step properties contain the following flags: • IncludeInReport—Specifies whether a property appears in the report automatically. • IsMeasurementValue—Indicates whether a property is a measurement that should be handled by the report generator according to report settings. • IsLimit—Indicates whether a property is a limit. Method 3—Automatic Reporting Flags TestStand contains flags related to report generation that you can set on variables and properties. The names of the flags are IncludeInReport, IsMeasurementValue and, IsLimit. TestStand uses these flags to identify result properties to display in the report. TestStand step types set the IncludeInReport flag on a subset of their result properties to specify that these properties automatically appear in the report. TestStand step types also set the IsMeasurementValue and IsLimit flags on their properties that hold output values or limit values. The report generator uses these 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 one of these flags, the report generator also considers the flag to be set for all array elements or sub-properties within the containing object. You can set these flags manually or programmatically. To manually set the flags of a particular step property, complete the following steps: 1. Right-click the property in the tree view of the step type definition and select Properties from the context menu. 2. Click Advanced on the Step Properties dialog box. 3. Set the flags using the Edit Flags dialog box. Set the flags using the SetFlags method of the PropertyObject class programmatically. You must call the SetFlags method on the property for which you want to set the flags.


6-17


Lesson 6


Method 4—Overriding Report Callbacks

Add any or all of the report callbacks to your sequence file to override the associated callback in the process model Method 4—Overriding Report Callbacks You can override the following report callbacks from within a client sequence file. •

ReportOptions—Gives the client sequence file an opportunity to modify the report options by calling the ReportOptions callback after reading the test station report options from disk. The ReportOptions callback is initially empty in the default process model.

•

TestReport—Overrides the TestReport callback in the client sequence file if you want to change its behavior entirely from the default behavior.

•

ModifyReportHeader—Allows the client sequence file to modify the report header called by the TestReport callback. The ModifyReportHeader callback is initially empty in the default process model.

•

ModifyReportEntry—Allows the client sequence file to modify the entry for each step result by calling the TestReport callback through subsequences for each result in the ResultList. The ModifyReportEntry callback is initially empty in the default process model.

•

ModifyReportFooter—Allows the client sequence file to modify the report footer. ModifyReportFooter is called by the TestReport callback. The ModifyReportFooter callback is initially empty in the default process model.


6-18

ni.com

Lesson 6


Method 5—Modifying Test Report Callbacks and/or Report Generation Files Report header and footer created in either: • reportgen_txt.seq • reportgen_html.seq • Reportgen_xml.seq

Report body generated in either: • modelsupport2.dll • reportgen_txt.seq • reportgen_html.seq • Reportgen_xml.seq

Method 5—Modifying Test Report Callbacks and/or Report Generation Files An alternative to overriding the Report callbacks in the client sequence file is to modify the process model directly. Use this method if you want your changes to exist in most or all of your sequence files. If you use the DLL option for generating the report body, modify the source file, C_report.c, and rebuild modelsupport2.dll. If you recompile modelsupport2.dll you will need to have the Windows SDK support files installed from the LabWindows/CVI installation CD. You might be required to perform a custom install/repair of your software to acquire the necessary files.

Note

If you use the Sequence option for generating the report body, customize the sequence files in one of the following files: reportgen_txt.seq, reportgen_html.seq, and/or reportgen_xml.seq. Note Before making changes to the above components copy the \ Components\NI\Models\TestStandModels directory to the \ Components\User\Models\TestStandModels directory. Then edit the process

model in the user directory. By default, TestStand searches for files in the \Components\User\Models directory before searching the \Components\NI\Models directory. You can configure the search directories by selecting Configure»Search Directories.


6-19


Lesson 6


Exercise 6-2: Modifying Report Generation Options Objective: To illustrate some of the options for customizing report generation in TestStand. Estimated Time: 30 minutes



6-20

ni.com

Lesson 6


Lesson 6 Summary Result Collection and Report Generation • Results are stored in Locals.ResultList • Each step has its own results container • Subsequence results are passed up to the calling sequence • The ResultList parameter is sent to the TestReport sequence in process model • The TestReport sequence formats results into a report Summary In this lesson, you learned that TestStand handles result collection and report generation in the following ways: •

Results from each step are collected and placed into their respective Locals.ResultList container when the step finishes executing.

•

Each step result container in the ResultList contains the Step.Result and Step.TS properties of the step. The step result container of the ResultList can contain other step properties that vary from step type to step type.

•

The subsequence results are passed back up to the calling sequence. This eventually enables all the results from the test sequence to return to the process model.

•

After all the results return to the process model upon completion of the test sequences, they are sent to the TestReport sequence. The TestReport sequence formats all the results into a report.


6-21


Lesson 6


Lesson 6 Summary (Continued) • Result collection can be modified by: – AddExtraResult API method – Adding subproperty to Locals.ResultList – Adding subproperty to Step.Result

• Report generation can be modified by: – – – – –

Configure»ReportOptions Using Step.Result.ReportText Automatic Reporting Flags TestReport Callbacks Direct modification of report generation files

Summary (Continued) You can customize result collection and report generation to further meet your needs. There are three different ways to modify result collection in TestStand: •

Use the AddExtraResult method of the TestStand API.

•

Directly insert subproperties into Locals.ResultList.

•

Add subproperties to Step.Result.

Use the method that works best for your test system needs. You also can customize report generation. While the default report structure that TestStand provides might work well for you out-of-the-box, you can customize the appearance and layout of the reports to meet your needs. The default report structure provides a good starting point. You can use the five described methods to customize the report to meet your needs. •

Configuring the Report Options dialog box

•

Using Step.Result.ReportText

•

Using automatic reporting flags

•

Overriding report callbacks

•

Modifying TestReport callbacks and/or report generation files


6-22

ni.com

Lesson 6



Modifying Result Collection Options

To demonstrate some of the options for modifying result collection in TestStand. In this exercise, you will use the Step.Result.ReportText method to customize report generation and each of the three methods to modify result collection in TestStand. Modify result collection in TestStand when you want to have additional data available for logging to the test report or database. In order for any data to be added to the report or database, it must first be placed in the ResultList.

Part A: Using the Step.Result.ReportText Method In this part of the exercise, you will add the function name of the Power On step to the ResultList using the ReportText property. You can assign a value to this property by using an expression in the TestStand environment. 1. Open the Ex 6-1 Modifying Result Collection.seq file located in the C:\Exercises\TestStand II directory. 2. Select Configure»Station Options and click the Preferences tab. Enable the Show Hidden Properties option to access the function names of steps you will need later. Click OK to close the Station Options dialog box. 3. Double-click the Power On step to open the Step Properties dialog box and click the Expressions tab. 4. Use the Post Expression text box to assign the code module function name to the ReportText property. The function name for the code module of a step is located under the Step.TS.SData.Call.Func property. You can use the Expression Browser dialog box to browse for this lookup string, or enter the expression: Step.Result.ReportText = Step.TS.SData.Call.Func, into the Post Expression text box. 5. Verify that the Post Expression control is similar to the expression shown in Figure 6-1. Click OK to close the Step Properties dialog box.


6-23


Lesson 6


Figure 6-1. Post Expression Control Note The TS property contains hidden properties, such as SData.Call, in the TestStand environment. These properties are specified as hidden because they are subject to change in future versions of TestStand and they are handled by the TestStand Engine in a special way for multithreaded testing situations. In general, you should avoid writing to these properties. However, you can read from these properties without problems.

6. Save the changes to the sequence file. 7. Place a breakpoint next to the CPU Sequence Call step. 8. Select Execute»Run MainSequence. Set all tests to pass. Allow the sequence to run until it reaches the breakpoint. 9. While paused at the CPU Sequence Call step, select the Context tab from the Execution window. 10. Expand the Locals property in the tree view and navigate to the Locals.ResultList[2].ReportText property. The right side of the display should show that the value of this property is "PowerOnTest", the function that the Power On step calls.


6-24

ni.com

Lesson 6


Additional Information In this exercise you selected the Run MainSequence execution option because you do not need to generate a report after the test completes. The objective of this exercise is to demonstrate the methods for modifying the contents of the Result List. Note that adding an item to the Result List is not sufficient for that item to be included in the report. Other exercises in this chapter demonstrate how to add items which have been collected in the Result List to the report. 11. Select Debug»Resume to finish executing the test. Close the Execution window after the test completes execution.

End of Part A Part B: Using the AddExtraResult Method Another way to place additional data into the ResultList is to use the AddExtraResult method. You can call this method at the beginning of a sequence to instruct the TestStand Engine to check whether a specific property exists for a step. If the property exists, the engine adds the property and its value to the ResultList entry for that step. If the property does not exist for a step, nothing changes for the ResultList entry of that step. 1. If it is not already open, open the Ex 6-1 Modifying Result Collection.seq file located in the C:\Exercises\TestStand II directory, and click the Setup tab. 2. Select the ActiveX/COM Adapter from the Adapter ring control. 3. Insert an Action step so that it is located above the Simulation Dialog step. Name this step Add FuncName to ResultList. Tip

You drag a step to reposition it in a sequence. 4. Configure the new step. a. Right-click the Add FuncName to ResultList step and select Specify Module from the context menu. b. Complete the Edit ActiveX/COM Call dialog box with the following values. Object Reference:

RunState.Execution

Automation Server:

NI TestStand API 3.5 (ver 1.0)

Object Class:

Execution

Action:

Call Method


6-25


Lesson 6


Method:

AddExtraResult

Param (propertyName): "Step.TS.SData.Call.Func" Param (resultPropertyName):"FuncName" Figure 6-2 shows the resulting Edit ActiveX/COM Call dialog box.

Figure 6-2. Edit Activex/COM Call Dialog Box

c. Click OK to close the Edit ActiveX/COM Call dialog box. 5. Save the changes to the sequence file. 6. If you cleared the breakpoint you placed in Part A, place a breakpoint next to the CPU Sequence Call step. 7. Select Execute»Run MainSequence. Set all tests to pass. Allow the sequence to run until it reaches the breakpoint. 8. While paused at the CPU sequence call step, select the Context tab from the Execution window. 9. Expand the Locals property in the tree view and browse to the Locals.ResultList[3].FuncName property. Notice on the right side of the display, as shown in Figure 6-3, that the value of this property is "PowerOnTest", the function that the Power On step calls.


6-26

ni.com

Lesson 6


You have added the FuncName property to the ResultList.

Figure 6-3. Value Column in Context Tab

Additional Information An important difference between using the AddExtraResult method and other methods explained in the other parts of this exercise is that the AddExtraResult method adds the FuncName property to the ResultList for every step that contains the Step.TS.SData.Call.Func property. In this exercise, you could view the result list entry for every step that executes using the LabWindows/CVI Adapter and find the FuncName property. 10. Select Debug»Resume to finish executing the test. Close the Execution window after the test completes execution.

End of Part B Part C: Using the Insert Subproperty into Locals.ResultList Method This part of the exercise illustrates the option for directly inserting a property into the ResultList for a specific step. Use the InsertIfMissing option of the SetValxxx method in the TestStand API to insert the property. 1. Click the Setup step group and delete the Add FuncName to ResultList step fthat you added in Part B of this exercise. This ensures that the FuncName property that you add to the ResultList in


6-27


Lesson 6


this part of the exercise is not a result of the step that you inserted in Part B. 2. Select the ActiveX/COM Adapter from the Adapter ring control. 3. Right-click the Power On step in the Main step group and insert an Action step. Name the new step Insert FuncName in ResultList. 4. Configure the new step. a. Right-click the Insert FuncName in ResultList step and select Specify Module from the context menu. b. Complete the Edit ActiveX/COM Call dialog box with the following values. Object Reference:

ThisContext

Automation Server:


Object Class:

PropertyObject

Action:

Call Method

Method:

SetValString

Param (lookupString): "Locals.ResultList[3]. FuncName"

Param (options):

1 // InsertIfMissing

Param (newValue):

RunState.Sequence. Main["Power On"]. TS.SData.Call.Func

If the Convert Step Names to Unique Ids? dialog displays, click No to reference the Power On step by name.

Note



6-28

ni.com

Lesson 6



Additional Information The property specified for the newValue parameter, RunState.Sequence.Main["Power On"].TS.SData. Call.Func, contains the function name of the Power On step. Because

you are accessing this property from a step other than the Power On step, you are required to provide an explicit path, rather than using Step.TS.SData.CAll.Func as you did in Parts A and B. You set the options parameter to 1 to alert TestStand to InsertIfMissing because the property does not yet exist at the lookup string you provided. If you do not set the options parameter to 1, TestStand returns an error message at run-time to indicate that the property you are trying to set does not exist. By using this option, TestStand inserts the property specified by the lookup string if the property does not exist, thereby adding the FuncName property to the ResultList at run-time. 5. Save the changes you have made to the sequence file. 6. If you cleared the breakpoint in Part A, place a breakpoint next to the CPU Sequence Call step in the sequence.


6-29


Lesson 6


7. Select Execute»Run MainSequence. Do not place checkmarks in any of the dialog box checkboxes. Allow the sequence to run until it reaches the breakpoint. 8. While paused at the CPU Sequence Call step, click the Context tab in the Execution window. 9. Expand the Locals property in the tree view and browse to the Locals.ResultList[3].FuncName property. The right side of the display should show that the value of this property is "PowerOnTest", the function that the Power On step calls. Note This method only adds the FuncName property to the ResultList for the step that you specified with the "Locals.ResultList[3].FuncName" lookup string. Therefore, only the Power On test will have the FuncName property.

10. Select Debug»Resume to finish executing the test. Close the Execution window after the test completes execution.

End of Part C Part D: Using the Add Subproperty to Step.Result Method In this part of the exercise, you add data to the ResultList by placing the property in the Step.Result property as a subproperty. You can do this because all items in the Step.Result property are automatically added to the ResultList. You can add a subproperty to the Step.Result property the following two ways: •

Use the SetValxxx method with the InsertIfMissing option to dynamically add a property during run-time.

•

Create a custom step type that contains a permanently added subproperty in the Step.Result property.

For this exercise, you will use the SetValString method. 1. Move the Insert FuncName in ResultList step that you added in Part C to the top of the Main step group so that it is above the Power On test. Rename the step Add FuncName Subproperty. 2. Configure the step. a. Right-click the Add FuncName Subproperty step and select Specify Module from the context menu. b. Complete the Edit ActiveX/COM Call dialog box with the following values using the Expression Browser dialog box, as necessary. Notice that you cannot explicitly browse to some of the parameter input values that you must enter. Browse as far as you can and manually enter the rest of the value.


6-30

ni.com

Lesson 6


Object Reference:

ThisContext

Automation Server:


Object Class:

PropertyObject

Action:

Call Method

Method:

SetValString

Param (lookupString): "RunState.Sequence. Main[\"Power On\"]. Result.FuncName"

Param (options):

1 // InsertIfMissing

Param (newValue):

""

Because you enclose the entire lookup string in quotes, you must change the inner quotes to special characters (\") to alert TestStand that you want the inner quotes to be part of the larger string.

Note


6-31


Lesson 6




c. Click OK to close the Edit ActiveX/COM Call dialog box. 3. Double-click the Power On step and click the Expressions tab. Delete the Post Expression that you used in Part A and replace it with Step.Result.FuncName = Step.TS.SData.Call.Func. Step.Result.FuncName will not exist until run-time when it is created by the previous step. Note


6-32

ni.com

Lesson 6


Figure 6-6 shows the resulting Step Properties dialog box.

Figure 6-6. Post Expression

4. Click OK to close the Step Properties dialog box. 5. Save the changes to the sequence file. 6. If you cleared the breakpoint you placed in Part A, place a breakpoint next to the CPU Sequence Call step in the sequence. 7. Select Execute»Run MainSequence. Set all tests to pass. Allow the sequence to run until it reaches the breakpoint. 8. While paused at the CPU Sequence Call step, click the Context tab in the Execution window. 9. Expand the Locals property in the tree view and browse to the Locals.ResultList[3].FuncName property. The right side of the display should show that the value of this property is "PowerOnTest", the function that the Power On step calls. Note The difference between this method and the method used in Part C is that the property is added to the actual Results container of the step instead of being added


6-33


Lesson 6


directly to the result list. The Results container is used to generate the Result List, but it is also used by other parts of the process model. For example, the Logging object used to college database results also uses the step Results container. Adding the property to the Results container also allows you to reference the property directly from the step, as you did with the Post-Expression in this section. 10. Select Debug»Resume to finish executing the test. Close the Execution window after the test completes execution.

End of Part D End of Exercise 6-1


6-34

ni.com

Lesson 6



Modifying Report Generation Options

To illustrate some of the options for customizing report generation in TestStand. In this exercise, you will use four different methods to modify report generation in TestStand. Each part of this exercise addresses an option for modifying report generation. There are many reasons why you might want to modify report generation, such as changing the color of text used in an HTML report, adding additional data to the report, or completely reformatting the report to meet your needs. You can accomplish each of these and more using one or more of the methods in this exercise.

Part A: Configure Report Options Dialog 1. Open the Ex 6-2 Modifying Report Generation.seq file located in the C:\Exercises\TestStand II directory. 2. Select Configure»Report Options to open the Report Options dialog box. Use the Report Options dialog box to customize the generation of report files. When you use the Test UUTs and Single Pass entry points in the Execute menu, the settings in this dialog box apply to all sequences that you run on a station. Refer to the TestStand Help for information about the options on the Contents tab of the Report Options dialog box. Click Cancel to close the dialog box without making any changes. 3. Select Execute»Single Pass and run the test sequence. Notice the information that displays in the report. 4. Select Configure»Report Options again and select different options from the Contents tab. Close the Report Options dialog box and run the sequence again. View the report to examine the differences in the report. 5. Select Configure»Report Options and click the Report File Pathname tab. The Report Options dialog box should resemble Figure 6-7. Use the Report File Pathname tab of the Report Options dialog box to specify how to save the report information. You can save the report information as a temporary file or specify a file to create.


6-35


Lesson 6


Figure 6-7. Report Options Dialog Box Report File Pathname Tab

6. Click the Directory ring control to view the other options for saving the file to a specific location. Leave these options in their default settings. Additional Information The default setting for the Directory ring control is Client Sequence File Directory, which saves the report in the same location as the sequence file. Below the Base Name option are several options for the sequence file name, including prefixing the filename, adding the time and date to the filename, forcing a unique filename, and appending the serial number to the report filename. You also have the option for specifying an extension for the report format. The bottom of the Report File Pathname tab also illustrates the current report format based on the selected options. 7. Remove the checkmark from the Prefix Sequence File Name to Report File checkbox. Change the Add Time and Date to File Name ring control to Date Only. Click OK to close the Report Options dialog box.


6-36

ni.com

Lesson 6


8. Execute the test sequence again. 9. Using Windows Explorer, navigate to the file created in the C:\Exercises\TestStand II directory. The filename should match the options selected in the Report File Pathname tab. Double-click the file to view the information in it. 10. Launch the Report Options dialog box again and select different options for creating different types of reports. View the reports to see the effects of the changes implemented. By default, TestStand launches the application that the operating system associates with the file extension of the report. In some cases, you might want to use a different report viewer such as Word or Netscape. For more information about how to configure the report viewer, refer to Chapter 10, Customizing the Report, in Using TestStand and Chapter 6, Database Logging and Report Generation, in the TestStand Reference Manual. Note

End of Part A Part B: Use Automatic Reporting Flags Another option for modifying report generation in TestStand is to use automatic reporting flags. Automatic reporting flags reduce the number of circumstances in which you must directly modify the report generating files. There are three flags available to use—IncludeInReport, IsMeasurementValue, and IsLimit. You can set these flags on properties and variables in your sequences. TestStand uses these flags to identify result properties to automatically display in the report. Note The automatic reporting flags only take effect if the property or variable on which the flags are set is included in the ResultList. Refer to the previous exercise for information on adding properties to the Result List.

This part of the exercise uses the automatic reporting flags to add the name of the function being called from a step to the report. Notice the Setup step group includes a step to place a FuncName property into the ResultList. 1. Return to the Main step group and select the Power On step. Right-click this step and select Open Tree View from the context menu. 2. In the tree view, select Main»Power On»TS»SData»Call»Func as shown in Figure 6-8.


6-37


Lesson 6


Figure 6-8. Expanded Tree View

After you have located and selected the Func property for the Power On step in the tree view, specify the automatic reporting flag for this property. 3. Right-click the Func property in the left pane of the window and select Properties from the context menu to specify this property. Click Advanced in the Properties dialog box. 4. In the Edit Flags dialog box that displays, select the PropFlags_IncludeInReport flag, as shown in Figure 6-9. This flag instructs TestStand to automatically include the Func property in the test report for the Power On step. In the Setup step group, the ActiveX/COM step Add FuncName to ResultList adds the function name property to the result list (as you did in Exercise 6-1). Setting the property flag on this object ensures that the property also displays in the report file. Note


6-38

ni.com

Lesson 6


Figure 6-9. Edit Flags Dialog Box

5. Click OK twice to store your flag settings and close the Edit Flags and Properties dialog boxes. 6. Save the sequence file. Execute the sequence and view the test report. Notice that the function name was automatically included in the test report for the Power On step. 7. Close the Execution window containing the report. You can set the flags of any property using the SetFlags method of the PropertyObject class programmatically.

Note

End of Part B Part C: Overriding Report Callbacks You can use this method of modifying report generation when you want to modify the report for a particular test sequence. You can override the Report callbacks in your client sequence file similar to overriding any of the other Process Model callbacks. In this part of the exercise, you will override a Report callback to modify the report header. 1. Select Configure»Report Options and enable the ASCII Text File option in the Report Format ring control. Click OK to close the Report Options dialog box. 2. Select Execute»Test UUTs or Execute»Single Pass to execute the test sequenceand notice the header at the top of the report. 3. To modify the report header, select Edit»Sequence File Callbacks to override the ModifyReportHeader callback in the process model.


6-39


Lesson 6


4. Select the ModifyReportHeader callback and click Add to insert the callback into the test sequence. Click Edit to go to the callback that you inserted in the test sequence. Figure 6-10 shows the resulting Sequence File Callbacks dialog box.

Figure 6-10. Sequence File Callbacks Dialog Box

5. Insert a Statement step in the ModifyReportHeader callback. Name the step Add Report Header. 6. Edit the expression of the Add Report Header step so it contains the expression, Parameters.ReportHeader = "This is the report header." + "\n", as shown in Figure 6-11.

Figure 6-11. Edit Statement Step Dialog Box

7. Click OK to close the Edit Statement Step dialog box.


6-40

ni.com

Lesson 6


Figure 6-12 shows the completed ModifyReportHeader sequence.

Figure 6-12. Configured Add Report Header Step

8. Save the changes to the sequence file. 9. Execute the sequence and notice that the generated report only contains the string "This is the report header." for the report header, instead of the default header.

End of Part C Part D: Directly Modify Report Generation Files The last part of the exercise illustrates the final method for modifying report generation in TestStand. Use this method if you want the changes to be effective for the majority of your sequences that you execute. Changes you make using this method affect all test reports unless a sequence overrides one or more of the report callbacks. In this part of the exercise, you will directly modify the ModifyReportFooter callback in the Sequential process model. 1. Verify that the Report Options dialog box is configured to the ASCII Text File report format.


6-41


Lesson 6


2. Execute the test sequence and view the default report footer, "End UUT Report.", shown in Figure 6-13.

Figure 6-13. Illustrated Report Footer

3. Open the Sequential process model, SequentialModel.seq, so you can modify it. The Sequential process model should be the current process model in use. You can open this process model by double-clicking the file path in the lower right-hand corner of the Sequence Editor window. 4. Select the ModifyReportFooter callback from the View ring control. The ModifyReportFooter callback is empty by default. 5. Insert a Statement step in the ModifyReportFooter callback. Name the step Add Report Footer. 6. Use the Expression Browser dialog box to edit the expression for the Add Report Footer step so the expression contains the following string: Parameters.ReportFooter = "This is the report footer."

7. Click OK to close the dialog box.


6-42

ni.com

Lesson 6


Figure 6-14 shows the resulting sequence.

Figure 6-14. Add Report Footer Step in Sequence

8. Return to the Ex 6-2 Modifying Report Generation.seq window. 9. Execute the sequence and notice that the report header now states, "This is the report footer.", instead of the default, "End of UUT Report.". Because you modified the process model directly, the change in the report footer affects all test sequences that you execute using the Sequential process model. Also, while this exercise only modified this particular aspect of report generation, you could also modify reportgen_html.seq, reportgen_txt.seq, reportgen_xml.seq, and/or modelsupport2.dll to further customize report generation in TestStand. Note

10. Close the window for the SequentialModel.seq file. Do not save changes to the process model. 11. Close the Ex 6-2 Modifying Report Generation.seq file.

End of Part D End of Exercise 6-2


6-43


Lesson 6


Self Review 1. What is the purpose of the ResultList local variable?

2. How are the results of a subsequence call displayed within Locals.ResultList?

3. What are the two means by which you can create the report body? What are the two sequence files used when generating the report file?

4. What is the difference between result collection and report generation?

5. What are the four methods of modifying result collection?

6. The AddExtraResult method will add a property to the ResultList for every step that contains the property you want to add. True or False

7. What are the four methods available for modifying report generation?

8. What flag must be set for a property to be included in the report?

9. When using the DLL method to generate a report, which one of the following Model callbacks is not called: ModifyReportHeader, ModifyReportFooter, or ModifyReportEntry?


6-44

ni.com

Lesson 6


Notes


6-45


Lesson 6


Notes


6-46

ni.com

7

System Design Projects

Lesson 7: System Design Projects In this lesson, you will: • Implement various design features for a customized TestStand system • Explore areas you still have questions about • Learn methods to implement common features

Introduction This lesson presents a variety of open ended design project ideas for you to implement based on the knowledge you have gained from the TestStand II: Customization course. Each exercise begins with a description of the feature that you will implement. This reinforces the topics covered in the course and helps you identify areas where you might have questions.


7-1


Lesson 7


Exercise 7-1: Dynamic Sequence Calling Objective: To implement dynamic sequence calling in a TestStand system. Estimated Time: 30 minutes



7-2

ni.com

Lesson 7


Exercise 7-2: Creating a Simple Process Model Objective: To create a simple process model. Estimated Time: 30 minutes



7-3


Lesson 7


Exercise 7-3: Storing LabVIEW References Objective: To store various references obtained from LabVIEW as variables in TestStand for later use in your test sequence. Estimated Time: 30 minutes



7-4

ni.com

Lesson 7


Exercise 7-4: Passing Arguments to New Executions Objective: To pass parameters to a new execution. Estimated Time: 30 minutes



7-5


Lesson 7


Exercise 7-5: Time Delay Custom Step Type Objective: To create a time delay custom step type. Estimated Time: 60 minutes



7-6

ni.com

Lesson 7


Exercise 7-6: Multithreading and Synchronization Objective: To further explore multithreading and synchronization. Estimated Time: 45 minutes



7-7


Lesson 7


Exercise 7-7: Creating a Sequence Builder Tool Objective: To use the TestStand API to create a Sequence Builder tool. Estimated Time: 60 minutes



7-8

ni.com

Lesson 7


Exercise 7-8: Asynchronous Report Generation Objective: To implement asynchronous report generation. Estimated Time: 90 minutes



7-9


Lesson 7


Lesson 7 Summary • In this lesson, you applied the concepts presented in the TestStand II: Customization course to implement useful features in TestStand • You also identified which topics you still had questions about

Summary The goal of this lesson was to give you an opportunity to implement features in TestStand based on the knowledge you gained from the TestStand courses. Also, you should have been able to clear up any remaining doubts or questions regarding the topics covered in the courses.


7-10

ni.com

Lesson 7



Dynamic Sequence Calling

To implement dynamic sequence calling in a TestStand system. In this exercise, you will modify the Ex 7-1 Dynamic Sequence Calling.seq sequence so the UUT serial number determines which subsequence executes.

Hints •

Use the first character of the serial number to determine which type of processor to test. For example: Serial Number Begins With

Sequence to Run

I or i

Intel Processor

A or a

AMD Processor

Anything else

Generic Processor

•

The Test UUTs execution entry point in the default process model stores the serial number in a local variable. You can access this variable from your client sequence file using the expression RunState.Root.Locals.UUT.SerialNumber.

•

The Root property is only available during execution because it is not filled until execution begins. To view the Root property, set a breakpoint at the first step of the sequence and use the Context tab in the Execution window.

•

Use the Left() function and the Equality ( == ) operator within your step preconditions. Both functions are available in the Expression Browser under the Operators/Functions tab.

End of Exercise 7-1


7-11


Lesson 7



Creating a Simple Process Model

To create a simple process model. In this exercise, you will begin with a new sequence file and transform it into a process model file that contains an execution entry point and three callbacks—PreTest, MainSequence, and PostTest. Include the following three callbacks in your sequence file. •

PreTest callback—Prompts the user to enter a serial number for the

UUT and allows the user to stop the test. The serial number and status of whether to continue to the next test should be passed back to the execution entry point sequence. •

PostTest callback—Notifies the user of the UUT Pass/Fail status.

•

Report callback—Passes the test results from the client sequence

file to the report generating sequence provided for you in the ReportGen.seq file located in the C:\Exercises\TestStand II directory. The process model also should obtain the test data from the client test sequence, generate a text report, and loop back to the PreTest callback after the report generation sequence has been called. After the user stops the test in the PreTest callback, the test report displays.

Hints •

Select Edit»Sequence File Properties and change the sequence file property to Model sequence file.

•

Rename the MainSequence from the new sequence file to the name of the execution entry point you want to use. Change the sequence property to execution entry point.

•

Disable the Record Results option for all steps in the process model except the MainSequence callback step.

•

You can access the test result data of the client sequence from the Locals.ResultList sequence local variable of the process model execution entry point. Because the sequence call step to the Main Sequence callback is the only step for which the results are recorded, you can access the test results using the following lookup string: Locals.ResultList[0].TS.SequenceCall.ResultList.

•

To test your process model, ensure that the new process model has the same configuration as the default process model by selecting Configure»Station Options»Model.

•

Execute the Test File.seq test sequence located in the C:\Exercises\TestStand II directory.

End of Exercise 7-2 TestStand II: Customization Course Manual

7-12

ni.com

Lesson 7



Storing LabVIEW References

To store various references obtained from LabVIEW as variables in TestStand for later use in your test sequence. 1. Write a sequence that uses the LabVIEW Adapter to create a VISA session reference, a File I/O reference, and a DAQ taskID reference. 2. Store these references as variables in TestStand. 3. Use these references in LabVIEW code modules to query a GPIB instrument, acquire a waveform of data from a DAQ device, determine the RMS value of the waveform, and write the RMS value to file. 4. Release all references.

Hints •

Open a VISA refnum to a GPIB instrument and store it as a Numeric variable in TestStand using the VISA Refnum To Session VI located on the TestStand palette in LabVIEW.

•

Open a File I/O refnum and store it as a Numeric variable in TestStand by type casting the refnum to an unsigned 32-bit integer Numeric data type in LabVIEW.

•

Initialize an analog input channel on a DAQ device to acquire an input waveform where sampling rate is 10,000 and buffer size is 1,000 scans. Type cast the taskID refnum to an unsigned 32-bit integer Numeric data type in LabVIEW and then store it as a Numeric variable in TestStand.

•

Obtain the session numeric variable from TestStand and convert it to a VISA refnum in LabVIEW by using the Session to VISA Refnum VI. Use this refnum to query a GPIB Instrument Simulator ("*IDN?").

•

Obtain the unsigned 32-bit integer Numeric variable that references the taskID refnum from TestStand and type cast it to a taskID data type to perform continuous data acquisition until the user clicks a Stop button.

•

Get the RMS value for the waveform and store this value in TestStand as a local variable.

•

Obtain the unsigned 32-bit integer Numeric variable that references the File I/O refnum from TestStand and type cast it to a File I/O refnum. Use this refnum to write the RMS value stored in TestStand to file.

•

Close the VISA, File I/O, and taskID refnums in LabVIEW.

End of Exercise 7-3


7-13


Lesson 7



Passing Arguments to New Executions

To pass parameters to a new execution. In this exercise, you will create a sequence that graphically monitors the value of a local variable in the same sequence. It programmatically launches another sequence in parallel and continuously updates the value of the local variable in the top-level sequence. This is done by repeatedly writing a random number to it.

Hints •

Pass data to a new execution using the sequence call step and the sequenceArgsParam parameter of the Engine.NewExecution TestStand API method.

•

The subsequence running in parallel should monitor the execution of the top-level sequence so that the subseqeunce terminates, when the top-level sequence stops.

If you need additional flexibility while accessing different variables and properties of the calling sequence execution, pass the sequence context of the top-level sequence as a parameter to the parallel execution.

Tip

End of Exercise 7-4


7-14

ni.com

Lesson 7



Time Delay Custom StepType

To create a time delay custom step type. In this exercise, you will create a time delay custom step type that induces a specified time delay between steps in a sequence. The purpose of this exercise is to test your ability to create custom step types, not to demonstrate the usefulness of time delay steps.

Hints •

Create a new step type in the Types view of a sequence file or in the Type Palette window.

•

Determine the data requirements for the step by analyzing what data inputs your step type might require at run-time and what data outputs your step might produce at run-time.

•

Create input/output properties for the step type, if any.

•

Create a step subproperty for each data input, choosing the appropriate data type and setting the default value. If you want an output property to automatically appear in the Locals.ResultList property, create the output property within the Step.Result property.

•

Designate an adapter, if appropriate. If your step is not designed to call user-written code modules, enable the Designate an Adapter option in the Step Properties dialog box and select the adapter.

•

Define run-time functionality for your step by creating a Pre or Post substep to call a code module you develop to perform the necessary operations. You can use the Wait functions in LabVIEW or LabWindows/CVI for this step type.

•

Define an Edit Substep dialog box, if needed.

•

Configure the built-in step type properties appropriately.

End of Exercise 7-5


7-15


Lesson 7



Multithreading and Synchronization

To further explore multithreading and synchronization. In this exercise, you will create a test sequence that initializes an instrument once and then uses the instrument in multiple sequences. The sequences should run in parallel threads to acquire data in one thread and share the test data between the other threads.

Hints •

Take advantage of the batch synchronization options within each step and the Notification step type.

•

Configure TestStand to use the Batch process model, BatchModel.seq.

•

Use an IVI DMM step to initialize/configure a DMM. When you configure this step, use the IVI logical name, NIDMM, that is already created in MAX. Verify that the logical name is configured to run in simulation mode. Using the batch synchronization step properties, configure the step so only one thread executes.

If multiple steps in your sequence use the One Thread Only batch synchronization step setting, the thread that executes the first step with this setting is the thread that executes all remaining steps with this setting. Note

•

Use a Notification step type to create a notification that can transmit data as well as receive data for the threads. Use the batch synchronization properties with this step so that only one thread executes this step.

•

Use an IVI DMM step to acquire a simulated single point reading that falls in the range specified in the IVI DMM Configure step.

•

Use the notification you create with two Notification steps—one to set or broadcast a notification and the other to receive a notification. Only the thread that obtained the DMM reading should execute the Set Notification step. All threads should execute the Receive Notification step so each thread can read the value sent by the Set Notification step.

•

Display the values received by each thread in a separate dialog box so a dialog box displays for each test socket when multiple test sockets execute.

End of Exercise 7-6


7-16

ni.com

Lesson 7



Creating a Sequence Builder Tool

To use the TestStand API to create a Sequence Builder tool. In this exercise, you will create a tool that allows operators to select steps from a template test sequence and create a new test sequence based on the selected steps using the TestStand API. The Sequence Builder reads the step names from a template sequence, displays the step names, copies the selected steps, then inserts the steps into a new sequence file using the ActiveX/COM Adapter for everything except displaying the list of step names.

Hints Use the following suggestions to obtain the list of step names in the template sequence. •

Get a reference to the template sequence file.

•

Get a reference to the MainSequence of the template file. Read the step names from MainSequence.

•

Determine the number of steps in the Main step group. Ignore steps in Setup and Cleanup step groups.

•

Load the Step object and obtain the step name. Loop on this action until you obtain all step names within the template sequence.

Use the following hint to allow the user to select steps for a new test sequence. •

Display the list of step names in a listbox using LabVIEW or LabWindows/CVI and store the selected step indexes.

Use the following hints to create a new test sequence based on the steps the user selects. •

Get a reference to the MainSequence in a new sequence file.

•

Use the PropertyObject.Clone method to clone a selected step. Repeat this action to copy all selected steps and insert them into the new sequence.

•

Save programmatically the new sequence file to disk.

•

Release the references to the template sequence file and the new sequence file.

•

Add the Sequence Builder tool to the Tools menu.

Any computer that uses the Sequence Builder tool must have a TestStand development license because this tool creates and modifies sequence files. Note

End of Exercise 7-7


7-17


Lesson 7



Asynchronous Report Generation

To implement asynchronous report generation. After a test sequence executes, any information, such as test data or limits, that needs to be saved is combined into a report. The report generation in TestStand happens sequentially after the test finishes execution and it depends on the amount of data logged. When there is a large amount of data to place in the report, report generation can take longer and increase the total test cycle time. Because TestStand can perform multithreaded operations, reports can generate asynchronous to the tests that are running. This ensures that the report generation does not affect the total test cycle time and improves the total throughput of your test station. In this exercise, you will use synchronization and sequence call step types to reduce the cycle time of the process in the Ex 7-8 Asynchronous Report Generation.seq sequence file located in the C:\Exercises\TestStand II directory. The sample test sequence executes in approximately 15 seconds and the report generation takes an additional 10 seconds. By implementing asynchronous report generation, you can start the next test immediately and avoid waiting for the report to generate.

Hints •

The Ex 7-8 Asynchronous Report Generation.seq file is configured to use the Ex 7-8 Process Model\ SequentialModel.seq process model located in the C:\Exercises\TestStand II directory. Make your modifications to this process model file.

Note Before you modify the process model, thoroughly examine how and when the result data passes to the TestReport sequence and how and when the report is cleared, set, read, and so on.

•

Changing the TestReport callback to run in a new execution will not complete this exercise. You must also move some of the existing report-related steps around, creating additional variables and parameters, and using Lock synchronization steps.

This is a challenging system design project. The solution description and process model file are located in the C:\Solutions\TestStand II\ Ex 7-8 Process Model\ directory.

End of Exercise 7-8 TestStand II: Customization Course Manual

7-18

ni.com

Lesson 7


Notes


7-19


Lesson 7


Notes


7-20

ni.com

Additional Information and Resources

A

This appendix contains additional information about National Instruments technical support options and TestStand resources.

National Instruments Technical Support Options Visit the following sections of the National Instruments Web site at ni.com for technical support and professional services. •

Support—Online technical support resources at ni.com/support include the following: –

Self-Help Resources—For 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 Support—All registered users receive free Basic Service, which includes access to hundreds of Application Engineers worldwide in the NI Developer Exchange at ni.com/exchange. 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.

•

System Integration—If you have time constraints, limited in-house technical resources, or other project challenges, National Instruments Alliance Partner members can help. The NI Alliance Partners joins system integrators, consultants, and hardware vendors to provide comprehensive service and expertise to customers. The program ensures qualified, specialized assistance for application and system development. 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.


A-1


Appendix A

Additional Information and Resources

Other National Instruments Training Courses National Instruments offers several training courses for TestStand users. These courses continue the training you received here and expand it to other areas. Visit ni.com/training to purchase course materials or sign up for instructor-led, hands-on courses at locations around the world.

National Instruments Certification Earning an NI certification acknowledges your expertise in working with NI products and technologies. The measurement and automation industry, your employer, clients, and peers recognize your NI certification credential as a symbol of the skills and knowledge you have gained through experience. areas. Visit ni.com/training for more information about the NI certification program.


A-2

ni.com

Course Evaluation Course ______________________________________________________________________________________ Location ____________________________________________________________________________________ Instructor _________________________________________

Date ___________________________________

Student Information (optional) Name _______________________________________________________________________________________ Phone __________________________________

Company _________________________________________

Instructor Please evaluate the instructor by checking the appropriate circle.UnsatisfactoryPoorSatisfactoryGoodExcellent Instructor’s ability to communicate course concepts❍❍

❍❍

❍

Instructor’s knowledge of the subject matter ❍ ❍

❍❍

❍

Instructor’s presentation skills

❍ ❍

❍❍

❍

Instructor’s sensitivity to class needs

❍ ❍

❍❍

❍

Instructor’s preparation for the class

❍ ❍

❍❍

❍

❍ ❍

❍❍

❍

❍ ❍

❍❍

❍

Course Training facility quality Training equipment quality Was the hardware set up correctly? The course length was

❍ Too long

❍ Yes

❍ No

❍ Just right

❍ Too much

The detail of topics covered in the course was The course material was clear and easy to follow. Did the course cover material as advertised?

❍ Too short

❍ Yes

❍ Yes

❍ Just right

❍ No

❍ Not enough

❍ Sometimes

❍ No

I had the skills or knowledge I needed to attend this course. ❍ Yes ❍ No If no, how could you have been better prepared for the course? ___________________________________________________________________ ____________________________________________________________________________________________ What were the strong points of the course? _________________________________________________________ ____________________________________________________________________________________________ What topics would you add to the course? __________________________________________________________ ____________________________________________________________________________________________ What part(s) of the course need to be condensed or removed? ___________________________________________ ____________________________________________________________________________________________ What needs to be added to the course to make it better? _______________________________________________ ____________________________________________________________________________________________ How did you benefit from taking this course? _______________________________________________________ ____________________________________________________________________________________________ Are there others at your company who have training needs? Please list. ___________________________________ ____________________________________________________________________________________________ ____________________________________________________________________________________________ Do you have other training needs that we could assist you with? ________________________________________ ____________________________________________________________________________________________ How did you hear about this course? ❍ NI Web site ❍ NI Sales Representative ❍ Mailing

❍ Co-worker

❍ Other ____________________________________________________________________________________

TestStand II (Customization Course Manual).pdf

Recommend Documents