Microsoft KB Archive/136203

= Microsoft Knowledge Base =

How to Wait a Finite Time for a Run Process to Terminate
Last reviewed: September 7, 1995

Article ID: Q136203

The information in this article applies to:


 * Microsoft Visual Test for Windows 95 and Windows NT, version 4.0
 * Microsoft Test for Windows, version 3.0a

SUMMARY
The Run TestBasic statement starts an application and either returns immediately or waits for the application to exit. The Run statement has an optional second parameter that specifies when it is to return to the TestBasic script to allow it to continue processing. If the second parameter is not specified, the Run statement won't return until the application is closed. Specifying NoWait as the second parameter makes the Run statement return immediately, which causes the application to run asynchronously with the TestBasic script.

Waiting for an application to complete is often useful while testing applications. However, if the application being waited upon cannot complete for unknown reasons, the Run statement will never return, so the the TestBasic script will never continue.

By uing the Win32 API function WaitForSingleObject in conjunction with CreateProcess, you can specify a finite time to wait. This article shows by example how to do this.

MORE INFORMATION
WaitForSingleObject returns when the specified object is in the signaled state or when the time-out interval elapses. An application object becomes signaled when it terminates. WaitForSingleObject needs a handle to the application, which can be obtained from the CreateProcess function.

CreateProcess is a Win32 API function that starts an application running and returns a handle to that application. It is used in this article as a replacement for the TestBasic Run statement.

Step-by-Step Example for Using WaitForSingleObject and CreateProcess
The following steps detail the process for creating a TestBasic script that will:


 * Starts the Windows NotePad (NOTEPAD.EXE) application.
 * Waits 10 seconds.
 * Displays a messagebox asking if you want to terminate the NotePad application or continue waiting.

  Copy the following code into a new window: '$Include 'Declares' Const STILL_ACTIVE = &h0103&

Dim hApp As Long Dim si As STARTUPINFO Dim pi As PROCESS_INFORMATION

' Start the NotePad application. The handle of the application ' pi.hProcess will contain the handle to NotePad. ' Note: The handle in this case is to the application not its window. ' You may need to change the path to Notepad. CreateProcess( "c:\win95\NotePad.exe", NULL, NULL, NULL, FALSE, _                 NORMAL_PRIORITY_CLASS, 0, NULL, si, pi )

' Move NotePad to the upper-left corner. Dim hwnd As Long hwnd = WFndWndC( NULL, "NotePad" ,FW_FOCUS, 5 ) WSetWndPosSiz( hwnd, 0, 0, 200, 200 )

Dim lExitCode As Long

' Infinite loop that waits for NotePad to terminate. Every ten seconds ' prompt user about waiting another ten seconds. Do     ' Wait up to 10 seconds for NotePad to terminate. WaitForSingleObject( pi.hProcess, 10 * 1000 ) ' Determine if NotePad is still running. GetExitCodeProcess( pi.hProcess, VarPtr( lExitCode ) ) If lExitCode = STILL_ACTIVE Then ' NotePad is still running ask user if NotePad should be terminated. If MsgBox( "NotePad is still running. Click 'OK' to wait " + _                    "another 10 seconds or click 'Cancel' to " + _                    "terminate NotePad.", _                    MB_OKCANCEL, "Waiting For NotePad" ) = IDCANCEL Then TerminateProcess( pi.hProcess, 0 ) Exit Do         End If      Else Exit Do     End If   Loop While True

' Must close the handles when they are no longer needed. CloseHandle( hThread ) CloseHandle( hProcess )  Run the script by pressing the F5 function key.

At this point, 10 seconds will pass before the message box is first displayed. Click Cancel to terminate NotePad and the TestBasic script, or click OK to wait another 10 seconds. If NotePad is exited during a 10-second wait period, WaitForSingleObject returns immediately.

NOTE: This sample code uses five Win32 API functions: CloseHandle, CreateProcess, GetExitCodeProcess, TerminateProcess, and WaitForSingleObject. For more information concerning these functions, please see the Win32 SDK Help file.