Microsoft KB Archive/129796

From BetaArchive Wiki
< Microsoft KB Archive
Revision as of 12:26, 21 July 2020 by X010 (talk | contribs) (Text replacement - "&" to "&")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Article ID: 129796

Article Last Modified on 7/13/2004


  • Microsoft Visual Basic 6.0 Learning Edition
  • Microsoft Visual Basic 6.0 Professional Edition
  • Microsoft Visual Basic 6.0 Enterprise Edition
  • Microsoft Visual Basic 4.0 Standard Edition
  • Microsoft Visual Basic 4.0 Professional Edition
  • Microsoft Visual Basic 4.0 32-Bit Enterprise Edition

This article was previously published under Q129796


Executing the Shell() function in a Visual Basic for Windows program starts another executable program asynchronously and returns control to the Visual Basic application. This shelled program continues to run independently of your application until the user closes it.

However, if your Visual Basic application needs to wait for the shelled process to terminate, you could use the Windows API to poll the status of the application, but this is not a very efficient technique. The example in this article demonstrates a better way.

A 16-bit application would use a completely different technique to accomplish the same effect.

For additional information, click the article number on the 16-bitprocess below to view the article on the 16-bitprocess in the Microsoft Knowledge Base:

96844 How To Determine When a Shelled Process Has Terminated


The Win32 API has integrated functionality that enables an application to wait until a shelled process has completed. To use these functions, you need a handle to the shelled process. The easiest way to achieve this is to use the CreateProcess() API function to launch your shelled program rather than Visual Basic's Shell() function.

Creating the Shelled Process

In a 32-bit application, you need to create an addressable process. To do this, use the CreateProcess() function to start your shelled application. The CreateProcess() function gives your program the process handle of the shelled process through one of its passed parameters.

Waiting for the Shelled Process to Terminate

Having used CreateProcess() to get a process handle, pass that handle to the WaitForSingleObject() function. This causes your Visual Basic application to suspend execution until the shelled process terminates.

Getting the Exit Code from the Shelled Application

It was common for a DOS application to return an exit code indicating the status of the completed application. While Windows provides other ways to convey the same information, some applications only provide exit codes. Passing the process handle to the GetExitCodeProcess() API allows you to retrieve this information.

Following are the steps necessary to build a Visual Basic for Windows program that uses the CreateProcess() function to execute the Windows Notepad (Notepad.exe) application. This code demonstrates how to use the Windows API CreateProcess() and WaitForSingleObject() functions to wait until a shelled process terminates before resuming execution. It also uses the GetExitCodeProcess() function to retrieve the exit code of the shelled process, if any. The syntax of the CreateProcess() function is extremely complicated, so in the example code, it is encapsulated into a function called ExecCmd(). ExecCmd() takes one parameter, the command line of the application to execute.

Step-by-Step Example

  1. Start a new project in Visual Basic. Form1 is created by default.
  2. Add the following code to the General Declarations section of Form1:

       Private Type STARTUPINFO
          cb As Long
          lpReserved As String
          lpDesktop As String
          lpTitle As String
          dwX As Long
          dwY As Long
          dwXSize As Long
          dwYSize As Long
          dwXCountChars As Long
          dwYCountChars As Long
          dwFillAttribute As Long
          dwFlags As Long
          wShowWindow As Integer
          cbReserved2 As Integer
          lpReserved2 As Long
          hStdInput As Long
          hStdOutput As Long
          hStdError As Long
       End Type
          hProcess As Long
          hThread As Long
          dwProcessID As Long
          dwThreadID As Long
       End Type
       Private Declare Function WaitForSingleObject Lib "kernel32" (ByVal _
          hHandle As Long, ByVal dwMilliseconds As Long) As Long
       Private Declare Function CreateProcessA Lib "kernel32" (ByVal _
          lpApplicationName As String, ByVal lpCommandLine As String, ByVal _
          lpProcessAttributes As Long, ByVal lpThreadAttributes As Long, _
          ByVal bInheritHandles As Long, ByVal dwCreationFlags As Long, _
          ByVal lpEnvironment As Long, ByVal lpCurrentDirectory As String, _
          lpStartupInfo As STARTUPINFO, lpProcessInformation As _
       Private Declare Function CloseHandle Lib "kernel32" _
          (ByVal hObject As Long) As Long
       Private Declare Function GetExitCodeProcess Lib "kernel32" _
          (ByVal hProcess As Long, lpExitCode As Long) As Long
       Private Const NORMAL_PRIORITY_CLASS = &H20&
       Private Const INFINITE = -1&
       Public Function ExecCmd(cmdline$)
          Dim proc As PROCESS_INFORMATION
          Dim start As STARTUPINFO
          ' Initialize the STARTUPINFO structure:
          start.cb = Len(start)
          ' Start the shelled application:
          ret& = CreateProcessA(vbNullString, cmdline$, 0&, 0&, 1&, _
             NORMAL_PRIORITY_CLASS, 0&, vbNullString, start, proc)
          ' Wait for the shelled application to finish:
             ret& = WaitForSingleObject(proc.hProcess, INFINITE)
             Call GetExitCodeProcess(proc.hProcess, ret&)
             Call CloseHandle(proc.hThread)
             Call CloseHandle(proc.hProcess)
             ExecCmd = ret&
       End Function
       Sub Form_Click()
          Dim retval As Long
          retval = ExecCmd("notepad.exe")
          MsgBox "Process Finished, Exit Code " & retval
       End Sub
  3. Press the F5 key to run the application.
  4. Using the mouse, click the Form1 window. At this point the NotePad application is started.
  5. Quit NotePad. A MsgBox appears indicating termination of the NotePad application and an exit code of 0.

    NOTE: The MsgBox statement following the ExecCmd() function is not executed because the WaitForSingleObject() function prevents it. The message box does not appear until Notepad is closed when the user chooses Exit from Notepad's File menu (ALT, F, X).


For additional information, click the article number below to view the article in the Microsoft Knowledge Base:

288216 PRB: Call to ExitProcess() from Visual Basic Application Hinders Process Exit

For more information, please see the "CreateProcess" topic in the MSDN Library CD-ROM.

Additional query words: GetModuleUsage

Keywords: kbhowto kbtophit KB129796