ShellExecute Function

Declare Function ShellExecute Lib "shell32.dll" Alias "ShellExecuteA" (ByVal hwnd As Long, ByVal lpOperation As String, ByVal lpFile As String, ByVal lpParameters As String, ByVal lpDirectory As String, ByVal nShowCmd As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

ShellExecute opens, prints, or executes a file using the Windows shell. When working with a non-executable file, the file is opened using its associated program. ShellExecute can also open Windows Explorer windows. The function returns immediately after opening the file, starting the program, or performing whatever other action was specified.

Return Value

If successful, the function returns a handle to the instance of the application which the function started. If an error occured, the function returns either 0 (indicating a lack of memory) or one of the following flags:

ERROR_BAD_FORMAT: The specified executable file was somehow invalid.
SE_ERR_ACCESSDENIED: Access was denied.
SE_ERR_ASSOCINCOMPLETE: The filename association is either incomplete or invalid.
SE_ERR_DDEBUSY: The DDE action could not run because other DDE actions are in process.
SE_ERR_DDEFAIL: The DDE transaction failed.
SE_ERR_DDETIMEOUT: The DDE transaction was not completed because the request timed out.
SE_ERR_DLLNOTFOUND: A required DLL file could not be found.
SE_ERR_FNF: The file could not be found.
SE_ERR_NOASSOC: There is no program associated with the specified type of file.
SE_ERR_OOM: Windows has insufficient memory to perform the operation.
SE_ERR_PNF: The path could not be found.
SE_ERR_SHARE: A sharing violation occured.

Visual Basic-Specific Issues

None.

Parameters

hwnd

A handle to the window calling the function.

lpOperation

The operation to perform on lpFile. This can be one of the following strings, although other options are possible, depending on the file being acted upon:

"explore": If lpFile is a path name, open it in a Windows Explorer window.
"open": Open lpFile using its associated program. Opening an executable file runs it. This is the default action if none is specified.
"print": Print lpFile using its associated program.

lpFile

The name of the file to open, print, execute, or whatever is specified by lpVerb.

lpParameters

Additional parameters to use to perform the action. This would typically be additional command-line options to use, especially when running an executable file.

lpDirectory

The path name of the working directory to use. If this is not specified, the current directory is used.

nShow

One of the following flags specifying how to display any window that might be opened:

SW_HIDE: Hide the opened window.
SW_MAXIMIZE: Maximize the opened window.
SW_MINIMIZE: Minimize the opened window.
SW_RESTORE: Restore the opened window (not maximized nor minimized).
SW_SHOW: Show the opened window.
SW_SHOWMAXIMIZED: Show the opened window maximized.
SW_SHOWMINIMIZED: Show the opened window minimized.
SW_SHOWMINNOACTIVE: Show the opened window minimized but do not activate the it.
SW_SHOWNA: Show the opened window in its current state but do not activate it.
SW_SHOWNOACTIVATE: Show the opened window in its most recent size and position but do not activate it.
SW_SHOWNORMAL: Show the opened window and activate it (as usual).

Constant Definitions

Const ERROR_BAD_FORMAT = 11
Const SE_ERR_ACCESSDENIED = 5
Const SE_ERR_ASSOCINCOMPLETE = 27
Const SE_ERR_DDEBUSY = 30
Const SE_ERR_DDEFAIL = 29
Const SE_ERR_DDETIMEOUT = 28
Const SE_ERR_DLLNOTFOUND = 32
Const SE_ERR_FNF = 2
Const SE_ERR_NOASSOC = 31
Const SE_ERR_OOM = 8
Const SE_ERR_PNF = 3
Const SE_ERR_SHARE = 26
Const SW_HIDE = 0
Const SW_MAXIMIZE = 3
Const SW_MINIMIZE = 6
Const SW_RESTORE = 9
Const SW_SHOW = 5
Const SW_SHOWMAXIMIZED = 3
Const SW_SHOWMINIMIZED = 2
Const SW_SHOWMINNOACTIVE = 7
Const SW_SHOWNA = 8
Const SW_SHOWNOACTIVATE = 4
Const SW_SHOWNORMAL = 1

Example

Use ShellExecute to perform the following tasks automatically:

Run the program "C:\MyProg\startup.exe" with the "-fast" command line, in a maximized window.
Open the file "C:\Project\nucleus.doc" with its associated program, in a restored window.
Print the file "C:\Project\picture.bmp" via its associated program.

The example begins each task immediately and then finishes -- it does not wait for any of these three tasks to complete. The example runs when button Command1 is clicked. Naturally, to run this example, you must create a command button named Command1 on form window Form1.

' This code is licensed according to the terms and conditions listed here.

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Declare Function ShellExecute Lib "shell32.dll" Alias "ShellExecuteA" (ByVal hwnd As Long, _
	ByVal lpOperation As String, ByVal lpFile As String, ByVal lpParameters As String, ByVal _
	lpDirectory As String, ByVal nShowCmd As Long) As Long
Public Const SW_MAXIMIZE = 3
Public Const SW_MINIMIZE = 6
Public Const SW_RESTORE = 9

' Place the following code inside window Form1. ***

Private Sub Command1_Click()
	Dim retval As Long  ' return value
	
	' 1. Run the program:
	retval = ShellExecute(Form1.hWnd, "open", "C:\MyProg\startup.exe", "-fast", "C:\MyProg\", _
		SW_MAXIMIZE)
	' 2. Open the document:
	retval = ShellExecute(Form1.hWnd, "open", "C:\Project\nucleus.doc", "", "C:\Project\", _
		SW_RESTORE)
	' 3. Print the document (minimized in case a window opens):
	retval = ShellExecute(Form1.hWnd, "print", "C:\Project\picture.bmp", "", "C:\Project\", _
		SW_MINIMIZE)
End Sub