Shell Function

Shell Function

---

Class

Microsoft.VisualBasic.Interaction

Syntax

 Shell(   pathname   [,   style   ][,   Wait   ][,   Timeout   ] ) 

pathname (required; String)

Name of the program to execute

style (optional; AppWinStyle enumeration)

The style of window and whether it receives the focus; see Section

Wait (optional; Boolean)

Boolean indicating whether to wait for the pathname application to finish execution before continuing execution of subsequent code

Timeout (optional; Integer)

If Wait is True , number of milliseconds to wait for the pathname application to terminate before the Shell function times out

Return Value

An Integer representing the Process ID, or 0

Description

Launches another application and, if successful, returns that application's task ID

Rules at a Glance

• pathname can include a drive letter. If a drive letter is not included in pathname , the current drive is assumed.

• pathname can include a folder name. You can use either a fully qualified path (i.e., starting from the root directory) or a relative path (i.e., starting from the current directory). If the folder name is not included in pathname , the current folder is assumed.

• pathname can include any command-line arguments and switches required by the application. For example:

   Shell("notepad.exe c:\data.txt", AppWinStyle.NormalFocus) 

  launches Notepad, which loads the file data.txt .

• Visual Basic includes the following intrinsic constants for setting the style argument:

  AppWinStyle.Hide Value: 0

  New application window is hidden

  Focus: New application

  AppWinStyle.NormalFocus Value: 1

  New application window is shown in its original position and size

  Focus: New application

  AppWinStyle.MinimizedFocus Value: 2

  New application window is displayed as an icon

  Focus: New application

  AppWinStyle.MaximizedFocus Value: 3

  New application window is maximized

  Focus: New application

  AppWinStyle.NormalNoFocus Value: 4

  New application window is shown in its original position and size

  Focus: Current application

  AppWinStyle.MinimizedNoFocus Value: 6

  New application window is displayed as an icon

  Focus: Current application

• The default when no style is specified is AppWinStyle.MinimizedFocus (2).

• If the application named in pathname executes successfully, Shell returns the windows task ID of the program. (The task ID is better known as the process ID or PID, a unique 32-bit value used to identify each running process.) It can be used as a parameter to the AppActivate procedure to give the application the focus and possibly to control it remotely using the Send and SendWait methods . The process ID is also required by a number of Win32 API calls.

• If the application named in pathname fails to execute, a runtime error is generated.

• The file launched by Shell must be executable. That is, it must be a file whose extension is .EXE or .COM (an executable file), .BAT (a batch file), or .PIF (a DOS shortcut file).

• Wait determines whether the Shell function operates synchronously ( True ) or asynchronously ( False ). The default is False ; control returns to the application, and code continues executing as soon as the process ID is known. If True , the Shell function returns only when the pathname application is closed or, if Timeout is not -1, when the timeout period has expired .

• If Wait is False , the Shell function returns the application's process ID. If Wait is True , it returns either the process ID (if control returns to the application because Timeout has elapsed) or 0 (if control returns to the application because the pathname application has been closed). In this latter case, Shell returns a 0 because, since the pathname application has been closed, its process ID is no longer valid.

• Timeout applies only when Wait is True . It defines the number of milliseconds that the application will wait for the pathname application to end before the wait is abandoned and application code resumes execution. Its default value is -1, which means that there is no timeout value and control returns to the application only when the pathname application has terminated .

Programming Tips and Gotchas

• Wait is a long-needed addition to the Shell function that allows your application to know when the launched application has terminated.

• The Shell function does not use file associations. You cannot, for example, supply MyReport.Doc as the pathname in the hope that VB will load Microsoft Word, which in turn will load MyReport.Doc .

• Setting Wait to True and leaving Timeout at its default value of -1 creates the possibility that control will never return from the pathname application to the VB.NET application.

VB.NET/VB 6 Differences

The Wait and Timeout arguments are new to VB.NET. They are not supported by VB 6.