Using Default and Custom UIMessages

This tutorial discusses UIMessages and how to use custom UIMessages to pass information about an execution to an operator interface.

What are UIMessages?

TestStand uses UIMessage objects to pass information about the state of the engine and the current executions to the Operator Interface or Sequence Editor. For example, a UIMessage could be used to notify the Operator Interface when a step has completed. The Operator Interface needs to know when the step completes so that it can update the information displayed in the Execution Window, such as the status of the step and the new current step. The Operator Interface receives the UIMessage and performs the actions necessary to update the Execution Window.

It is possible that you may want to update your Operator Interface based on an event that occurs within your sequence that is not already handled by the default TestStand UIMessages. To do this, you can make a custom UIMessage. For Example, custom UIMessages can be used to include the total number of units tested, update a progress bar, or pass numeric results from a test and append them to a graph.

This tutorial discusses the default TestStand UIMessages and how to use custom UIMessages to pass information about an execution to an operator interface.

Default TestStand UIMessages

The TestStand engine sends TestStand UIMessages (events) to the Operator Interface. TestStand defines several events, such as EndExecution, Trace, and BreakOnBreakpoint. These are defined as follows:

UIMsg_BreakOnUserRequest = 1
UIMsg_BreakOnBreakpoint = 2
UIMsg_BreakOnRunTimeError = 3
UIMsg_Trace = 4
UIMsg_TerminatingExecution = 5
UIMsg_AbortingExecution = 6
UIMsg_KillingExecutionThreads = 7
UIMsg_EndExecution = 8
UIMsg_ShutDownComplete = 9
UIMsg_StartExecution = 10
UIMsg_ProgressPercent = 11
UIMsg_ProgressText = 12
UIMsg_StartInteractiveExecution = 13
UIMsg_EndInteractiveExecution = 14
UIMsg_TerminatingInteractiveExecution = 15
UIMsg_TerminationCancelled = 16
UIMsg_ResumeFromBreak = 17
UIMsg_StartFileExecution = 18
UIMsg_EndFileExecution = 19
UIMsg_ShutDownCancelled = 20
UIMsg_UserMessageBase = 10000

TestStand 2.0.x added the following additional codes:

UIMsg_LocalizationSettingChanged = 21
UIMsg_OpenWindows = 22
UIMsg_TileWindows = 23
UIMsg_CascadeWindows = 24
UIMsg_ReportChanged = 25
UIMsg_CloseWindows = 26
UIMsg_RefreshWindows = 27
UIMsg_ClientFileChanged = 28
UIMsg_DisplayReport = 29

TestStand 3.x added the following additional codes:

UIMsg_ModelState_Initializing = 30
UIMsg_ModelState_Waiting = 31
UIMsg_ModelState_Identified = 32
UIMsg_ModelState_BeginTesting = 33
UIMsg_ModelState_TestingComplete = 34
UIMsg_ModelState_PostProcessingComplete = 35
UIMsg_ModelState_EnabledStateSet = 36
UIMsg_ReportLocationChanged = 37

Each operator interface must handle these events to update information about the execution.

Custom UIMessages

Other messages can be sent by the programmer to update progress and status on the Operator Interface. When you post a message, you can send string data and/or numeric data with the message.

You can define your own events by using an event number that is greater than or equal to the value of the UIMsg_UserMessageBase constant (10000). There are two parts to using custom UIMessages:

· Posting the UIMessage
· Receiving and handling the UIMessage

Posting UIMessages

To post the message, use the PostUIMessage method of the TestStand API. Look up this method in the ActiveX API Reference Help, which is in the TestStand Help menu. Because this function is a method of the Thread class, the thread and its associated execution are properties of the UIMessage by default. You can send additional data using the numeric and string data parameters of the method. Since this is a method of the TestStand API, you can post UIMessages from a code module or in a sequence using the ActiveX Automation Adapter.
The following is the prototype of the PostUIMessage method:

PostUIMessage ( eventCode, numericDataParam, stringDataParam, synchronous)

An example of how you might configure the Specify Module dialog for the Action step of the ActiveX Automation Adapter is shown below:


[+] Enlarge Image

At this point, whenever you execute this step, the execution will post a custom UIMessage which passes the string value of Parameters.Result.Status.

Receiving and Handling UIMessages

Each Operator Interface contains a UIMessage handler that continuously monitors events posted from the TestStand engine. How the UIMessage handler is implemented depends on the programming environment. The UIMessage handler is implemented depending on the programming environment. The following discusses how the UIMessage handler is implemented in the LabVIEW Operator Interface.

LabVIEW
The LabVIEW operator interface has a VI that handles all the events sent by the TestStand engine. This VI is called the UIMessage Handler. The VI checks if the message queue is empty. If the queue is not empty, it gets the next UIMessage. From the message, it gets the event code as a variant. The variant is converted to a number, which matches a defined event code. For all event codes, there is a case in the case structure. Some cases perform no action while others perform some action. Regardless, all cases must close the UIMessage.

The LabVIEW Simple Operator Interface calls a VI named Simple OI - Configure Event Callbacks.vi. This vi can be found in <TestStand>\OperatorInterfaces\NI\Simple\LabVIEW\TestExec.llb. You can then extend the Reg Event Callbacks and change the new inputs to User Message. Wire the Application Manager to User Message and a User Parameter to the User Parameter input. Finally, right-click the input for the VI Ref and select Create Callback VI. This will automatically create the callback vi for the UIMessage with all needed parameters and context.


[+] Enlarge Image


You can then use the created callback to handle each custom UIMessage with a Case Structure.

Reader Comments | Submit a comment »

LabVIEW section slightly confusing
LabVIEW section doesn't seem to distinguish between a UIMessage and a User Message. It is unclear how they relate if at all - or whether they are the same. In general it would be great if the LabVIEW section could be extended and made more clear.
- Ronnie Smith, Racal. rsmith@racalinst.com - Jun 10, 2009

CVI Example?
This document is not helpful for CVI programmers
- Hakan Toktas, MIKES A.S.. thakan@yahoo.com - Apr 22, 2008

Where is a CVI example
Where is a CVI example?
- steven block, Northrop Grumman. steven.block@ngc.com - Jan 4, 2008