SAMPLE: TERMWAIT Spawns Task and Waits for its Termination

ID: Q84456

The information in this article applies to:

Microsoft Windows Software Development Kit (SDK) versions 3.0, 3.1

SUMMARY

Termwait.exe is a self-extracting file in the Microsoft Software Library that demonstrates how an application can launch a child task and then wait for it to complete before executing specific code. Termwait.exe uses notification messages from the Toolhelp dynamic-link library (DLL) to determine that the child task has completed. The techniques demonstrated by the Termwait.exe sample work for both Windows and MS-DOS (non-Windows) child tasks.

MORE INFORMATION

The following file is available for download from the Microsoft Download Center. Click the file name below to download the file:

Termwait.exe

For more information about how to download files from the Microsoft Download Center, please visit the Download Center at the following Web address

http://www.microsoft.com/downloads/search.asp

and then click How to use the Microsoft Download Center.

The Termwait.exe sample application calls the NotifyRegister() function to install a notification callback function before it calls the WinExec() function to launch the child task. If a callback function is registered, it is called before any task in the system terminates. The notification callback function calls the TaskFindHandle() function to fill a TASKENTRY data structure with information about the terminating task. When the callback determines that the child task has terminated, it notifies the Termwait.exe application.

When it spawns the child task, Termwait.exe sets its bChildIsExecuting global variable to TRUE. The notification callback resets this variable to FALSE when the child task is complete. Any code that must not execute while the child task is running can query the value of the bChildIsExecuting flag. During the wait, any menu selections that will cause reentrancy problems should be disabled. Doing so keeps the user informed about the options that are presently valid. In the TERMWAIT sample, the AfterChildHasTerminated() function contains code that is executed only after the child task has completed.

If an application tracks a number of child tasks, its NotifyRegister() callback function should process both the NFY_STARTTASK and NFY_EXITTASK notifications. The callback function uses these notifications to maintain a list of child task handles. Note that while no two tasks will have the same handle, it is possible for task handles to be reused. Consequently, if one task ends and a new task begins, the new task can use the same task handle.

Version 3.1 of the Windows SDK is required to build the Termwait.exe sample. However, the compiled code is compatible with both Windows 3.0 and 3.1. Note that because the TOOLHELP.DLL is not part of the default installation for Windows 3.0, it must be installed into the Windows system directory (by default, C:\WINDOWS\SYSTEM) before Termwait.exe will run. The TOOLHELP.DLL file is provided as a redistributable file with the Windows 3.1 SDK.

NOTE: The NotifyRegister callback function must be placed in a separate source file and this file must be compiled with /GA/GEa. This is because the NotifyRegisterCallback function is called with the Data Segment (DS) of the task that installed the callback and the Stack egment of the task which is notifying the callback. So SS != DS and /GA/GEs cannot be used to compile this file.

Additional query words: synchronize softlib TERMWAIT.EXE

Keywords : kbfile kbsample kb16bitonly kbWinOS310 kbWinOS300 KrToolHlp
Version : WINDOWS:3.0,3.1
Platform : WINDOWS
Issue type :