Figure 1
As shown in Figure 1, I simply inserted a Sequence Call and named it ‘SequenceCallProgressBar’. Now if I right-click on the Sequence Call and select Open Sequence we can look at the sequence code as shown below in Figure 2.
Figure 2
Using the Seconds() function, ‘SequenceCallProgressBar’ consists of a While Loop that repeatedly grabs a current timestamp and loops until 60 seconds has expired. Now suppose this loop was much more elaborate and could essentially take hours to execute. Wouldn’t it be nice to be able to take a quick look at the sequence during execution and know just how much execution time remains? Sure you could just put a watch on the variable, but what if this script is to be executed on the manufacturing floor and the end user isn’t familiar with getting around in TestStand? This is where controlling the progress bar may be of interest.
So let’s take a look at how to edit ‘SequenceCallProgressBar’ such that we can display current status on the progress bar. First, I’ll add an Action step with adapter type ActiveX/COM. For Automation Server I’ll select the TestStand API and for Object Reference I’m going to type ‘RunState.Execution’. Now the purpose of this step is to retrieve an object reference to the Sequence Call thread such that when it is executing you can update the progress bar. Therefore, for the Object Class I’ll select Execution and then I’ll use the Get Property ‘ForegroundThread’. Now I’ll declare a variable (Locals.refThread) to store the object reference of the Sequence Call thread. Figure 3 below shows now what this step should look like.
Figure 3
Now that we have the object reference of the Sequence Call thread, we can start controlling the progress bar. The TestStand API contains two event codes that allow you to edit the progress bar. One allows you to control the percent complete and the other allows you to add text to the progress bar. Let’s start with editing the percent complete status.
First I’ll add another Action step with adapter type ActiveX/COM. For Automation Server once again I’ll select the TestStand API but this time for Object Reference I’m going to use the variable (Locals.refThread) in which I stored my thread reference. Next, for Object Class I’m going to select Thread and now I’ll use the built in Call Method, ‘PostUIMessageEx’. TestStand also comes with a Call Method called ‘PostUIMessage’ that could do the same trick, but according to the Help File, this function has been obsoleted and ‘PostUIMessageEx’ is the preferred Call Method to use.
The ‘PostUIMessageEx’ Call Method contains 5 parameters. Depending on what you select for the first parameter determines how the other four will be used. For example, with the eventCode parameter, I’m going to drop the enumeration down and select the ‘UIMsg_ProgressPercent’ message code. Now the other four parameters involved include a numeric data parameter, a string data parameter, an ActiveX data object reference, and a boolean variable. For the progess percent message code, the progress indicator is updated via the numeric parameter. Therefore, in the string parameter I’ll simply send an empty string. Also, I don’t need to pass an ActiveX reference with the message so for the ActiveX object reference I’ll type the key word ‘Nothing’ which is TestStand’s equivalent to a null object. Finally, for the synchronous boolean I’ll want to set it ‘True’. Setting this to ‘True’ will require the Call Method to wait for the user interface to process the message before continuing on. This is very important that you set this ‘True’ as I’ll show you in a later post how setting this ‘False’ can hose up your script.
Now I’m ready to manipulate the progess indicator to show percent complete. As you may recall, the while loop simply loops until 60 seconds has expired. Therefore, I’m going to want to show a percent complete based on the number of seconds that has expired out of the 60. So for the numeric parameter I pass in the following code ‘(Locals.nCurrentTime/60)*100’. Figure 4 below now shows what this step looks like.
Figure 4
Finally, I’m going to add a third Action step with adapter type ActiveX/COM and configure it similar to the step above, but instead of selecting the ‘UIMsg_ProgressPercent’ message code, I will now select the ‘UIMsg_ProgressText’ message code. This message code uses the string parameter to display text on the progress bar. Therefore, I’ll set the numeric parameter to 0 and once again set the ActiveX object reference and boolean the same as before. For the string parameter, I’m going to display the current number of seconds that has currently expired so therefore I pass in the code Str(Locals.nCurrentTime) + ” Seconds has Expired”. Figure 5 below shows what this step now looks like.
Figure 5
Now my Sequence Call is complete and I’m ready for execution. However, before I do, let’s take a look at how the finished Sequence Call code looks.
Figure 6
So now I’m going to execute the sequence and let’s see what we get.
Figure 7
Figure 7 shows that whenever I execute the sequence my progess indicator now shows a scrolling percent complete to the user and the progress bar text has been edited to show the current number of seconds that has expired.
It is always good practice however to clear the progress bar indicator and text upon Sequence Call completion so I would recommend adding two steps in Cleanup to set the numeric parameter to 0 for ‘UIMsg_ProgressPercent’ and the string parameter to empty strings for ‘UIMsg_ProgressText’.