Most user interface messages notify you to update an Execution window. When you receive one of these user interface messages, use the UIMessage.Execution property to obtain a reference to the Execution object to which the message applies. Use the Execution.Id property to determine which user interface display to update.

The following user interface messages apply to executions:

  • Start/End Events—If you receive a UIMsg_StartExecution event, create a new window for the execution or reinitialize an existing window for the execution. The Execution window already exists when the user restarts the execution. If you receive a UIMsg_EndExecution event, modify the display for the execution to show that the execution has ended. Then, release any handles to Thread, Step, or SequenceContext objects you have for the execution, and display the execution report, if one exists.

    TestStand posts the UIMsg_StartInteractiveExecution and UIMsg_EndInteractiveExecution events to notify you when the user runs steps interactively in an execution. The user can run steps interactively in a new execution or from an existing execution while at a breakpoint.

    TestStand posts the UIMsg_StartFileExecution and UIMsg_EndFileExecution events to notify the user interface of the period during which an execution uses a particular sequence file. You can use this information to disable the editing of the sequence file or to indicate that it is in use.

  • Break Events—TestStand posts the UIMsg_BreakOnBreakpoint, UIMsg_BreakOnUserRequest, or UIMsg_BreakOnRunTimeError user interface message when an execution enters a suspended state. Each of these messages indicates a different reason for the change in state.

    For each of these events, you can choose to display the following information:

    • Information about the steps in the currently executing step group
    • A call stack list that identifies the locations of the active sequence calls in the current thread
    • A list of the threads the execution contains
    To display information about the steps in the currently executing step group, you must first obtain the foreground Thread object by obtaining the value of the Execution.ForegroundThreadIndex property and then calling the Execution.GetThread method with the index. From the Thread object, you can then obtain the SequenceContext object that represents the top of the call stack by calling the Thread.GetSequenceContext method. Pass 0 for the call stack index and then pass a variable in which to store the frame ID, which is a unique identifier for the call stack entry. The frame ID is not required to handle this event, but is useful when handling .

    Once you have the SequenceContext object, you can access all the information about the currently executing sequence. The Sequence object from the SequenceContext.Sequence property provides the run-time copy of the sequence. Access this run-time copy to obtain all the information about the steps you require. You can also use the other SequenceContext properties to obtain information such as the currently executing step group, the sequence file that contains the executing sequence, and other information.

    To display a call stack list, first obtain the Thread.CallStackSize property of the current thread to determine the number of call stack entries. Then obtain the SequenceContext object for each entry by passing its zero-based index to the Thread.GetSequenceContext method. Use the SequenceContext.CallStackName property to obtain the display name for an entry.

    To display a thread list, first obtain the number of threads from the Execution.NumThreads property. Then, obtain each thread by passing its zero-based index to the Execution.GetThread method. Obtain the display name of the thread from the Thread.DisplayName property.

    When you receive the UIMsg_BreakOnRunTimeError event, display the run-time error to the user after updating the user interface. Obtain the run-time error message from the SequenceContext.GetRunTimeErrorMessageEx method for the top-level SequenceContext. Resuming execution from a UIMsg_BreakOnRunTimeError event causes the execution to go to the Cleanup step group. To ignore the run-time error, you must first call the Thread.ClearCurrentRTE method of the foreground thread. However, for trace events, call the Engine.DisplayRunTimeErrorDialogEx method to launch the Run-time Error dialog box. You can also create a custom dialog box to launch instead.

  • Trace Events—The update to the user interface a UIMsg_Trace event requires is very similar to that of a break event, except that you use only the name of the foreground thread and the top entry in the call stack list instead of the names of all the threads and call stack entries because the user interface disallows switching threads or browsing the call stack while tracing. In addition, because the trace event does not indicate a suspended state, you do not need to call the Execution.Resume method to continue. Instead, execution continues automatically when you finish handling the user interface message for the trace event by releasing the user interface message or returning from the event handling callback sequence. In addition, you can use the frameId output parameter of the Thread.GetSequenceContext method to update the display.

    As an optimization, the user interface holds the step group and frameId value from the last trace event. If the next event is a trace event and its sequence context specifies the same frameId value and step group, you need only to update the display of the previously executed step and the step to execute next. Because this is typically the case when users trace through a long list of steps in the same sequence and step group, this optimization can significantly increase the maximum tracing speed of the application.

    Note If the application polls for user interface messages, the rate at which you poll limits the maximum tracing rate.
  • Resume Events—TestStand posts the UIMsg_ResumeFromBreak event to the user interface whenever an execution is about to resume from a suspended state. This event allows the user interface to update the enabled state of controls on its execution display and to show that the execution is running.
  • Execution State Change Events—The purpose of the execution state change events is to notify the user interface that the state of an execution is about to change. The action these events specify does not occur until you finish handling the user interface message by releasing the user interface message or returning from the event handling callback. also signify an execution state change.

    The name of the following execution state change events indicate the meaning for each event:

    • UIMsg_TerminatingExecution
    • UIMsg_TerminationCancelled
    • UIMsg_TerminatingInteractiveExecution
    • UIMsg_AbortingExecution
    • UIMsg_KillingExecutionThreads
  • Progress Events—A step posts progress events to notify the user interface to update its progress indicator or text message, if one exists. If you receive a UIMsg_ProgressPercent event, check the UIMessage.NumericData property for the percentage of the progress indicator to shade. If you receive a UIMsg_ProgressText event, you can find the text to display in the UIMessage.StringData property.