Professional Documents
Culture Documents
TestStand II (Customization Course Manual) PDF
TestStand II (Customization Course Manual) PDF
Course Software Version 3.5 November 2005 Edition Part Number 323038D-01 TestStand II: Customization Course Manual
Copyright 20012005 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: HelpPatents 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 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
iii
Contents
Multithreading in TestStand .......................................................................................3-7 MultithreadingSequence 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 SectionsParallel ...........................................................................3-21 Synchronization SectionsSerial ..............................................................................3-22 Synchronization SectionsOne-Thread-Only ...........................................................3-23 Parallel Process Model................................................................................................3-24 Implementing Synchronized SectionsBatch Synchronization Step Type...............3-25 Implementing Synchronized SectionsSynchronization 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
iv
ni.com
Contents
Contents
Method 1Configuring the Report Options Dialog Box ..........................................6-15 Method 2Using Step.Result.ReportText .................................................................6-16 Method 3Automatic Reporting Flags ....................................................................6-17 Method 4Overriding Report Callbacks...................................................................6-18 Method 5Modifying 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
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.
Note
For course manual updates and corrections, refer to ni.com/info and enter the info code rdts01. 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
vii
Student Guide
Note
You can customize many of the topics discussed in this course to integrate further with your testing requirements.
viii
ni.com
Student Guide
Description Folder for saving files created during the course and files necessary to complete some exercises Folder containing the solutions to all the course exercises
Solutions
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 FilePage SetupOptions directs you to pull down the File menu, select the Page Setup item, and select Options from the last dialog box. This icon denotes a tip, which alerts you to advisory information. This icon denotes a note, which alerts you to important information. 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 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. 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. Italic text in this font denotes text that is a placeholder for a word or value that you must supply.
italic
monospace
monospace italic
ni.com
1-1
Lesson 1
TestStand API
Operator Interfaces Sequence Editor
TestStand API
Process Model
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
SequenceFile Sequence Step Execution SequenceContext Report Process Model
PropertyObject
Code Modules
1-3
Lesson 1
API Classes
Adapter EditArgs Engine Execution InteractiveArgs InteractiveContext PropertyObject PropertyObjectFile Report Sequence SequenceContext SequenceFile Step StepType Thread TypeUsageList UIMessage User UsersFile WorkspaceFile 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
PropertyObject
Step Sequence Execution Report Adapter Thread PropertyObjectFile SequenceFile SequenceContext User UIMessage EditArgs InteractiveArgs InteractiveContext WorkspaceFile WorkspaceObject
TypeUsageList Engine*
* ActiveX Control
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
Step
Any number per sequence
1-6
ni.com
Lesson 1
Execution
Thread
One or more per execution
Adapter
One or more
SequenceContext
One for each call stack entry in a thread
Report
One per execution
1-7
Lesson 1
Example Properties:
PropertyObject.Name Engine.CurrentUser Engine.BreakpointsEnabled
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
1-9
Lesson 1
1-10
ni.com
Lesson 1
Operator interfaces
Start and monitor executions
Process models
Get report options and create reports
Sequence editor
Build, execute, and debug sequence files
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
1-14
ni.com
Lesson 1
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
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:
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: Automation Server: Object Class: Action: Method: Leave the parameters blank.
National Instruments Corporation 1-19 TestStand II: Customization Course Manual
RunState.Engine NI TestStand API 3.5 (Ver 1.0) Engine (IEngine) Call Method LoadTypePaletteFilesEx
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.
Tip
Notice that you can click the ? button to display the help information regarding the method or property you have selected in the TestStand API. 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: Automation Server: Object Class: Action: Method: Param (Return Value): 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.
RunState.Engine NI TestStand API 3.5 (Ver 1.0) Engine (IEngine) Call Method NewSequenceFile Locals.NewSeqFile
1-20
ni.com
Lesson 1
Object Reference: Automation Server: Object Class: Action: Method: Param (Return Value): Param (sequenceNameParam): Additional Information
Locals.NewSeqFile NI TestStand API 3.5 (Ver 1.0) SequenceFile Call Method GetSequenceByName Locals.MainSeq "MainSequence"
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: Automation Server: Object Class: Action: Method: Param (Return Value): Param (adapterKeyNameVal): Param (stepTypeName):
RunState.Engine NI TestStand API 3.5 (Ver 1.0) Engine (IEngine) Call Method NewStep Locals.NewStep "" "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: Automation Server: Object Class: Action: Method: Param (stepToInsert): Param (index): Param (stepGroupParam): 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: Automation Server:
Locals.NewStep NI TestStand API 3.5 (Ver 1.0) Locals.MainSeq NI TestStand API 3.5 (Ver 1.0) Sequence Call Method InsertStep Locals.NewStep 0 StepGroup_Main
1-22
ni.com
Lesson 1
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: Automation Server: Object Class: Action: Method: Param (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.
Locals.NewSeqFile NI TestStand API 3.5 (Ver 1.0) SequenceFile Call Method Save Locals.PathString
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: Automation Server: Object Class: Action: Method: Param (sequenceFileToRelease): 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.
RunState.Engine NI TestStand API 3.5 (Ver 1.0) Engine(IEngine) Call Method ReleaseSequenceFileEx Locals.NewSeqFile
1-24
ni.com
Lesson 1
27. Save and execute the sequence by selecting ExecuteRun 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.
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.
1-25
Lesson 1
Automation Server: Object Class: Action: Method: Param (lookupString): Param (options): Param (newValue): Additional Information
NI TestStand API 3.5 (Ver 1.0) PropertyObject CallMethod SetValString "MessageExpr" 0 Locals.MessageExpr
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.
6. Select ExecuteRun 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.
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: Automation Server: Object Class: Action: Method: Param (Return Value): Param (sequenceFileParam): Param (sequenceNameParam): Param (processModelParam): Param (breakAtFirstStep): Param (executionTypeMaskParam):
RunState.Engine NI TestStand API 3.5 (Ver 1.0) Engine(IEngine) Call Method NewExecution Locals.NewExecution Locals.NewSeqFile "MainSequence" Nothing False
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.
Note
For more information about each individual parameter, refer to the TestStand API Reference section of the TestStand Help. 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: Action: Method: Param (millisecondTimeOut): Param (processWindowsMsgs):
NI TestStand API 3.5 (Ver 1.0) Execution Call Method WaitForEndEx 1 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.
8. Save the file and select ExecuteRun 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.
10. Click OK to close the Message Popup dialog box. 11. Save and close the files.
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.
4. Explain the difference between a method and a property, and give an example of each.
variable using the ActiveX/COM Adapter, the sequence context, and the PropertyObject class.
1-31
Lesson 1
Notes
1-32
ni.com
Note The material in this chapter is not covered in class. Feel free to read the material and complete the exercises outside of class.
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
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
2-5
Lesson 2
2-6
ni.com
Lesson 2
2-7
Lesson 2
Note: You can perform the steps from a sequence, an operator interface, or a code module.
2-8
ni.com
Lesson 2
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
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. Wire the output of the Sequence Context reference to the reference input of the Property Node. Right-click the Property terminal and select PropertiesEngine 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 PropertiesUsersFile 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 PropertiesUserList from the context menu. Figure 2-1 shows the resulting block diagram.
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 MethodsGetNumElements 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.
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 WindowShow 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 WindowShow Block Diagram and modify the For Loop as shown in Figure 2-3.
2-14
ni.com
Lesson 2
10. Make sure you close all the ActiveX references you created. Figure 2-4 shows the resulting block diagram.
11. Select WindowShow 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
2-16
ni.com
Lesson 2
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.
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.
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
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.
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.
2-20
ni.com
Lesson 2
4. Save and close the VI and return to the sequence editor. Save the sequence file.
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
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 ToolsAdd/Edit/Delete Users from the sequence editor menu to execute the User Manager tool.
2-22
ni.com
Lesson 2
2-23
Lesson 2
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 Tip
After you have entered the function parameters select CodeInsert Function Call or press <Ctrl+I> 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.
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: InstrumentTestStand API 3.5AdvancedEngine Static PropertiesUsersGet 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
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: InstrumentTestStand API 3.5AdvancedUsers File Static PropertiesGet 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: Error Info: List of Users:
usersFile &errorInfo &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.5Property ObjectCharacteristicsArrays 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: Error Info: Number of Elements:
userList &errorInfo &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.5Property ObjectSubProperties 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: Error Info:
userList &errorInfo
2-25
Lesson 2
i 0 &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: InstrumentTestStand API 3.5Advanced UserStatic PropertiesGet 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: Error Info: Login Name:
user &errorInfo &loginName
9. Insert each LoginName into the listbox by calling the InsertListItem function. Select LibraryUser Interface Controls/Graphs/Strip ChartsList (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: Control ID: Item Index: Item Label: Item Value:
panelHandle PANEL_LISTBOX 1 loginName 0
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<numElements; i++) { //get user object for element in user list TS_PropertyGetPropertyObjectByOffset (userList, &errorInfo, i, 0, &user); //get the users login name TS_UserGetLoginName (user, &errorInfo, &loginName); //insert the users into the listbox on the UIR InsertListItem (panelHandle, PANEL_LISTBOX, -1, loginName, 0); } RunUserInterface (); DiscardPanel (panelHandle); Error: CA_DiscardObjHandle CA_DiscardObjHandle CA_DiscardObjHandle CA_DiscardObjHandle (usersFile); (engine); (user); (userList);
2-27
Lesson 2
10. Save the UserManagerTool.c file. Leave this source file open for use in Part B: Adding New Users.
2-28
ni.com
Lesson 2
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: InstrumentTestStand API 3.5AdvancedEngine Static PropertiesUsersGet 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: Error Info: Users File Object:
engine &errorInfo &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: InstrumentTestStand API 3.5AdvancedUsers File
2-29
Lesson 2
Static PropertiesGet 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: Error Info: List of Users:
usersFile &errorInfo &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.5Property ObjectSubProperties 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: Error Info: Array Offset: Options: New Object Value:
userList &errorInfo 1 1 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: InstrumentTestStand API 3.5Advanced Property Object FileWrite 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: Error Info: Write Format:
usersFile &errorInfo 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: InstrumentTestStand API 3.5Advanced Property Object FileInc 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: Error Info:
usersFile &errorInfo
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
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
2-32
ni.com
Lesson 2
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: InstrumentTestStand API 3.5AdvancedEngineObject AccessGet 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: Error Info: Login Name: User Object:
engine_for_edit &errorInfo userLoginName &user
b. Obtain the User as a PropertyObject by calling the TS_UserAsPropertyObject function. Locate the function panel using the following list of classes: InstrumentsTestStand API 3.5 AdvancedUserAs 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: Error Info: Property Object:
user &errorInfo &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.5Property ObjectDialogsDisplay 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: Error Info: Dialog Title: File: Dialog Options: Status Flags:
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.
2-36
ni.com
Lesson 2
following list of classes: InstrumentTestStand API 3.5 Property ObjectCharacteristicsArraysDelete Elements. Complete the parameters for this function as shown in Figure 2-17. Insert the function into the source code file.
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<numElements; i++) { TS_PropertyGetPropertyObjectByOffset (userList, &errorInfo, i, 0, &user); TS_UserGetLoginName ((TSObj_User)user, &errorInfo, &loginName); // // // if 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<numGroups; i++) { // Get the members list for each group TS_PropertyGetPropertyObjectByOffset (groupList, &errorInfo, i, 0, &group); TS_UserGetMembers ((TSObj_User)group, &errorInfo, &members); //Get the number of members in each group TS_PropertyGetNumElements (members, &errorInfo, &numMembers); for(j=0; j<numMembers; j++) { // Check the name of each member against the specified name TS_PropertyGetValStringByOffset (members, &errorInfo, j, 0, &loginName); if (!stricmp (userLoginName, loginName)) { // Remove deleted user from group TS_PropertyDeleteElements (members, &errorInfo, j, 1, 0); } } } //write usersfile to disk TS_PropertyObjectFileWriteFile (usersFile, &errorInfo, TS_WriteFileFormat_Current);
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 BuildCreate 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.
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.
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 ToolsAdd/Edit/Delete Users to execute the user manager tool 8. Close all windows when you finish.
2-41
Lesson 2
Self Review
1. How is the Login dialog box displayed?
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
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
3-1
Lesson 3
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 RateThe 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 TimeDuration 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
DefinitionMultithreading
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
DefinitionMultithreading
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
DefinitionMultithreading (Continued)
Process Thread 1 Thread N 1 Thread N t/N t/N Processor Time = t
DefinitionMultithreading (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 threads process.
t/N
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
3-8
ni.com
Lesson 3
3-9
Lesson 3
3-10
ni.com
Lesson 3
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
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
Create Notification Acquire Data Set notification Test 1
Sequence 2
Wait on Notification Process Data
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
Batch
UUT UUT
Common Carrier
Test Fixture
Test Fixture
Test Fixture
Test Fixture
3-16
ni.com
Lesson 3
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.seqControls multiple independent test sockets.
The Parallel process model allows you to start and stop testing on any socket at any time.
BatchModel.seqControls 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
Test
Test
Test
Test
Test
Socket 0
Socket 1
Socket 2
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
Test
Test
Test
Test
Test
Synchronized Section
Socket 0
Socket 1
Socket 2
3-20
ni.com
Lesson 3
Synchronization SectionsParallel
Test Test Wait for all units Test
Test
Test
Test
Socket 0
Socket 1
Socket 2
Synchronization SectionsParallel
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 SectionsSerial
Test Test Wait for all units Test Test Wait for all units Test Test Test Wait for all units Test Socket 0 Socket 1 Socket 2 Shared Resource Test Each test socket executes in series Shared Resource
Synchronization SectionsSerial
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 SectionsOne-Thread-Only
Test Test Wait for all units Action Action Skip Action Wait for all units Action Action Skip Action Only one test socket executes the actions in the section Test
Socket 0
Socket 1
Socket 2
Synchronization SectionsOne-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
Test
Test
Test
Socket 0
Socket 1
Socket 2
3-24
ni.com
Lesson 3
Implementing Synchronized SectionsBatch Synchronization Step Type Implements a synchronized section around a group of steps Enter a synchronized section Exit a synchronized section
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
3-26
ni.com
Lesson 3
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 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
3-30
ni.com
Lesson 3
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
3-33
Lesson 3
Exercise 3-1
Objective:
To demonstrate how to use some of the built-in Synchronization step types in a test.
Tip
Right-click in the Sequence File window and select Insert StepSynchronization from the context menu to access the default Synchronization step types. Figure 3-1 shows the Synchronization step types available.
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.
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.
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.
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.
3-39
Lesson 3
15. Configure TestStand to use the Batch process model. a. Select ConfigureStation 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 ConfigureModel 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.
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 StartProgramsNational InstrumentsMeasurement 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 ConfigureStation 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.
Lesson 3
Exercise 3-2
Objective:
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.
3-42
ni.com
Lesson 3
5. Select ConfigureModel 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.
b. Click OK to close the Model Options dialog box. 6. Select ExecuteTest 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
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
Select EditSequence 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.
3-45
Lesson 3
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 ExecuteTest 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.
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 ConfigureStation 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.
3-48
ni.com
Lesson 3
Exercise 3-3
Objective:
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.
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.
c. Click OK to close the Station Options dialog box. Additional Information A TestStand server is active when the TestStand application <TestStand> Bin\Rengine.exe is running on a remote system. The following describes how each TestStand client interacts with a remote system.
Windows 2000/NT/XPThe 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.
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
6. Click OK to close the Remote Execution Settings dialog box. Figure 3-15 shows the resulting 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 ExecuteSingle 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.
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.
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.
3-54
ni.com
Lesson 3
Notes
3-55
Lesson 3
Notes
3-56
ni.com
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 onea 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
4-2
ni.com
Lesson 4
4-3
Lesson 4
Red Purple
4-4
ni.com
Lesson 4
4-5
Lesson 4
4-6
ni.com
Lesson 4
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
Client #1
PreUUT
Client #2
MainSequence
MainSequence
MainSequence
PostUUT PostUUT
4-10
ni.com
Lesson 4
4-11
Lesson 4
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
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 <TestStand>\Components\NI\ Callbacks\Station directory. Add your own Station Engine callbacks in the StationCallbacks.seq file in the <TestStand>\Components\User\ Callbacks\Station directory.
4-15
Lesson 4
4-16
ni.com
Lesson 4
Front-End Callbacks
Sequences that are called external of the process model or test sequence Defined in the <TestStand>\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 <TestStand>\Components\NI\ Callbacks\FrontEnd directory. You can add your own Front-End callbacks or override a predefined callback in the FrontEndCallbacks.seq file in the <TestStand>\Components\User\Callbacks\FrontEnd directory.
4-17
Lesson 4
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
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
Exercise 4-1
Objective:
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
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.
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 ExecuteTest 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.
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: Button 2: Active Control:
"OK" "STOP" Response String
Figure 4-4 shows the resulting Text and Buttons tab of the Configure Message Popup Step dialog box.
4-25
Lesson 4
b. Click the Options tab to configure the options as shown in Figure 4-5.
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.
10. Click OK to close the Edit Statement Step dialog box. 11. Save and run the sequence using ExecuteTest 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 EditSequence 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 EditSequence 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.
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"
4-28
ni.com
Lesson 4
Figure 4-8 shows the resulting Text and Buttons tab of the Configure Message Popup Step dialog box.
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"
4-29
Lesson 4
Figure 4-9 shows the resulting Text and Buttons tab of the Configure Message Popup Step dialog box.
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 ExecuteTest UUTs and select a step to fail. When a step fails, a message popup should display the name of the step that failed.
Hint
Create two Message Popup steps and set a precondition for each step.
4-30
ni.com
Lesson 4
Exercise 4-2
Objective:
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 <TestStand>\Components\ NI\Models. 2. Select the TestStandModels directory and select EditCopy or press the <Ctrl-C> keys to copy. 3. Navigate to the <TestStand>\Components\User\Models directory and select EditPaste or press the <Ctrl-V> 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 <TestStand>\ 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
Purpose Subsequences called by entry points or callbacks Sequence of process model that can be overridden in a client sequence file. Sequence that defines an Execution entry point that appears in the Execute menu. Sequence that defines the behavior of one of the options on the Configure menu. Sequences that influence the behavior of certain pre-defined aspects in the TestStand engine.
Red
Dark Blue
Purple
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 EditPaste 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
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"
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
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 ModeSkip 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 EditSequence 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 <TestStand>\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 EditSequence 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 ExecuteDebug 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 <TestStand>\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.
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 DebugDebug 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 StartPrograms National InstrumentsTestStand 3.5Operator 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 <TestStand>\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
<TestStand>\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
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
5-2
ni.com
Lesson 5
5-3
Lesson 5
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 controlsthe 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
5-9
Lesson 5
5-10
ni.com
Lesson 5
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 Controlsuch as the ComboBox, ListBox, or ListBarto 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
5-15
Lesson 5
5-16
ni.com
Lesson 5
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
5-18
ni.com
Lesson 5
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
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
5-23
Lesson 5
5-24
ni.com
Lesson 5
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
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.
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 WindowShow 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.
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.
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.
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.
End of Part A
5-31
Lesson 5
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 : ""
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 : ""
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<TestStand>\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.
5-34
ni.com
Lesson 5
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.
5-36
ni.com
Lesson 5
Control Type TestStand UI Button Control TestStand UI ComboBox Control TestStand UI SequenceView Control TestStand UI ReportView Control TestStand UI Application Manager TestStand UI SequenceFileView Manager TestStand UI ExecutionView Manager
Constant Name
ENTRYPOINT2BTN SEQUENCECOMBOBOX EXECUTIONVIEW REPORTVIEW APPLICATIONMGR SEQUENCEFILEVIEWMGR EXECUTIONVIEWMGR
Caption
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 <F2> 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 <F2> 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 <F2> 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
Tip
Select ViewFind 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.
//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 <F2> 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 InstrumentNI TestStand UI Controls 3.5 from the toolbar, and select Event Callback Registration FunctionsApplicationMgrEventsRegister 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.
Note
If the NI TestStand UI Controls 3.5 instrument is not present in the menu, select InstrumentLoad and load tsui.fp in the <TestStand>\API\CVI directory. Repeat this process with the tsuisupp.fp, tsutil.fp, and tsapicvi.fp.
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 HelpFunction 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.
function call. d. Close the function panel. e. Use the function panels found in InstrumentNI TestStand UI Controls 3.0Event Callback Registration Functions ApplicationMgrEvents to register the ActiveX control event callbacks for the events shown in Table 5-2.
5-39
Lesson 5
Callback Function
ApplicationMgr_OnQueryShutdown ApplicationMgr_OnDisplaySequenceFile 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 <F2> 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 <F2> 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
h. Press the <F2> 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 <F2> 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 <F2> 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 InstrumentsNI TestStand UI Controls 3.5 SequenceFileViewMgrConnect 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));
End of Part B
5-42
ni.com
Lesson 5
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 : ""
9. Click OK to close the Properties dialog box. 10. Save the operator interface. 11. Select RunDebug 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 <TestStand>\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.
5-44
ni.com
Lesson 5
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: Automation Server: Object Class: Action: Method:
RunState.Thread NI TestStand API 3.5 (Ver 1.0) Thread Call 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. numericDataParam: stringDataParam: activeXDataParam: synchronous:
Note Locals.Voltage "" Nothing 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.
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: Automation Server: Object Class: Action: Method:
RunState.Thread NI TestStand API 3.5 (Ver 1.0) Thread Call 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: stringDataParam: activeXDataParam: synchronous:
0 "" ThisContext True
Figure 5-15 shows the resulting Edit ActiveX/COM Call dialog box.
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
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. 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
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.
5-50
ni.com
Lesson 5
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.
5-51
Lesson 5
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: Automation Server: Object Class: Action: Method:
RunState.Thread NI TestStand API 3.5 (Ver 1.0) Thread Call 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. numericDataParam: stringDataParam: activeXDataParam: synchronous:
Note Locals.Voltage "" Nothing 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
Figure 5-19 shows the resulting 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: Automation Server: Object Class: Action: Method:
RunState.Thread NI TestStand API 3.5 (Ver 1.0) Thread Call 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: stringDataParam: activeXDataParam: synchronous:
0 "" Locals.Waveform True
Figure 5-20 shows the resulting Edit ActiveX/COM Call dialog box.
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 TestStand II: Customization Course Manual
Lesson 5
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
8. Save the file and select RunDebug 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.
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?
4. How do you post a UIMessage? From where can you post UIMessages?
5-59
Lesson 5
Notes
5-60
ni.com
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
Sequence Execution
Report
6-2
ni.com
Lesson 6
6-3
Lesson 6
Step 0
Step 1
6-4
ni.com
Lesson 6
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. SequenceFileAbsolute path of the sequence file that contains the subsequence. SequenceName of the subsequence that the step called. StatusStatus of the subsequence that the step called. ResultListValue 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
6-7
Lesson 6
example, Step.Limits.High
resultPropertyName stringThe 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
6-9
Lesson 6
Method 2Add 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
6-10
ni.com
Lesson 6
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
Report Header
(reportgen_xxx.seq)
6-13
Lesson 6
6-14
ni.com
Lesson 6
6-15
Lesson 6
The result from this expression would appear in the report as shown in the figure above.
6-16
ni.com
Lesson 6
6-17
Lesson 6
Add any or all of the report callbacks to your sequence file to override the associated callback in the process model
Method 4Overriding Report Callbacks
You can override the following report callbacks from within a client sequence file. ReportOptionsGives 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. TestReportOverrides the TestReport callback in the client sequence file if you want to change its behavior entirely from the default behavior. ModifyReportHeaderAllows 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. ModifyReportEntryAllows 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. ModifyReportFooterAllows 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
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.
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 <TestStand>\ Components\NI\Models\TestStandModels directory to the <TestStand>\ Components\User\Models\TestStandModels directory. Then edit the process
model in the user directory. By default, TestStand searches for files in the <TestStand>\Components\User\Models directory before searching the <TestStand>\Components\NI\Models directory. You can configure the search directories by selecting ConfigureSearch 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
6-21
Lesson 6
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
Exercise 6-1
Objective:
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 ExecuteRun 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 DebugResume to finish executing the test. Close the Execution window after the test completes execution.
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: Automation Server: Object Class: Action:
RunState.Execution NI TestStand API 3.5 (ver 1.0) Execution 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.
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 ExecuteRun 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
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 DebugResume 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: Automation Server: Object Class: Action: Method:
ThisContext NI TestStand API 3.5 (ver 1.0) PropertyObject Call Method SetValString
Note
If the Convert Step Names to Unique Ids? dialog displays, click No to reference the Power On step by name. Figure 6-4 shows the resulting Edit ActiveX/COM Call dialog box.
6-28
ni.com
Lesson 6
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 ExecuteRun 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 DebugResume to finish executing the test. Close the Execution window after the test completes execution.
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
ThisContext NI TestStand API 3.5 (ver 1.0) PropertyObject Call Method SetValString
1 // InsertIfMissing ""
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.
6-31
Lesson 6
Figure 6-5 shows the resulting Edit ActiveX/COM Call dialog box.
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
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 ExecuteRun 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 DebugResume to finish executing the test. Close the Execution window after the test completes execution.
6-34
ni.com
Lesson 6
Exercise 6-2
Objective:
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
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 MainPower OnTSSDataCallFunc as shown in Figure 6-8.
6-37
Lesson 6
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
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.
Note
You can set the flags of any property using the SetFlags method of the PropertyObject class programmatically.
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.
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.
6-40
ni.com
Lesson 6
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.
6-41
Lesson 6
2. Execute the test sequence and view the default report footer, "End UUT Report.", shown in Figure 6-13.
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."
6-42
ni.com
Lesson 6
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.
6-43
Lesson 6
Self Review
1. What is the purpose of the ResultList local variable?
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?
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?
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
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
7-2
ni.com
Lesson 7
7-3
Lesson 7
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
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
Exercise 7-1
Objective:
Hints
Use the first character of the serial number to determine which type of processor to test. For example: Serial Number Begins With
I or i A or a
Anything else
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.
7-11
Lesson 7
Exercise 7-2
Objective:
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 callbackNotifies the user of the UUT Pass/Fail status. Report callbackPasses 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 EditSequence 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 ConfigureStation OptionsModel. Execute the Test File.seq test sequence located in the C:\Exercises\TestStand II directory.
Lesson 7
Exercise 7-3
Objective:
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.
7-13
Lesson 7
Exercise 7-4
Objective:
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.
Tip
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.
7-14
ni.com
Lesson 7
Exercise 7-5
Objective:
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 <None> 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.
7-15
Lesson 7
Exercise 7-6
Objective:
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 stepsone 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.
7-16
ni.com
Lesson 7
Exercise 7-7
Objective:
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.
Note
Any computer that uses the Sequence Builder tool must have a TestStand development license because this tool creates and modifies sequence files.
7-17
Lesson 7
Exercise 7-8
Objective:
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.
Lesson 7
Notes
7-19
Lesson 7
Notes
7-20
ni.com
This appendix contains additional information about National Instruments technical support options and TestStand resources.
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
A-2
ni.com
Course Evaluation
Course ______________________________________________________________________________________ Location ____________________________________________________________________________________ Instructor _________________________________________ Date ___________________________________
Instructor
Please evaluate the instructor by checking the appropriate circle.UnsatisfactoryPoorSatisfactoryGoodExcellent Instructors ability to communicate course concepts Instructors knowledge of the subject matter Instructors presentation skills Instructors sensitivity to class needs Instructors preparation for the class Yes No Too short Just right Not enough No Sometimes Too much Yes Yes No Just right
Course
Training facility quality Training equipment quality Was the hardware set up correctly? The course length was Too long
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?
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 ____________________________________________________________________________________