WD2000: How to Call the ShellExecute Windows API Function

This article was previously published under Q238245
This article has been archived. It is offered "as is" and will no longer be updated.
You can call the ShellExecute() Windows API function from a Visual Basic for Applications macro to start another program under Microsoft Windows. Use ShellExecute() instead of Shell (a Visual Basic statement) or WinExec() (a Windows API function) to work around the following limitation of the latter commands:

With Shell and WinExec(), you cannot start an application by specifying a file name only. For example, the following Shell statement will fail:
x = Shell("C:\My Documents\Book1.Xls")				
Microsoft provides programming examples for illustration only, without warranty either expressed or implied. This includes, but is not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and with the tools that are used to create and to debug procedures. Microsoft support engineers can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific requirements. Below is a sample Visual Basic for Applications macro that calls the ShellExecute() Windows API function. ShellExecute() determines whether Microsoft Excel is already running; if so, it loads Book1.xls into the current Microsoft Excel session. If Microsoft Excel is not already running, ShellExecute() starts Microsoft Excel and loads Book1.xls.
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 LongDeclare Function apiFindWindow Lib "User32" Alias "FindWindowA" _   (ByVal lpclassname As Any, ByVal lpCaption As Any) As LongGlobal Const SW_SHOWNORMAL = 1Sub ShellExecuteExample()   Dim hwnd   Dim StartDoc   hwnd = apiFindWindow("OPUSAPP", "0")   StartDoc = ShellExecute(hwnd, "open", "C:\My Documents\Book1.xls", "", _      "C:\", SW_SHOWNORMAL)End Sub				
The ShellExecute() function opens or prints the specified file. The following is information about ShellExecute() from pages 901-904 of the Microsoft Windows Software Development Kit (SDK) "Programmer's Reference, Volume 2:Functions."


Parameter            Description---------------------------------------------------------------------------   hwnd                 Identifies the parent window.   lpszOp               A string specifying the operation to perform. This                        string can be "open" or "print".   lpszFile             Points to a string specifying the file to open.   lpszParams           Points to a string specifying parameters passed to                        the application when the lpszFile parameter                        specifies an executable file. If lpszFile points to                        a string specifying a document file, this parameter                        is NULL.   lpszDir              Points to a string specifying the default                        directory.   fsShowCmd            Specifies whether the application window is to be                        shown when the application is opened. This                        parameter can be one of the following values:      Value          Meaning      ---------------------------------------------------------------------      0              Hides the window and passes activation to another                     window.      1              Activates and displays a window. If the window is                     minimized or maximized, Windows restores it to its                     original size and position (same as 9).      2              Activates a window and displays it as an icon.      3              Activates a window and displays it as a maximized                     window.      4              Displays a window in its most recent size and                     position. The window that is currently active remains                     active.      5              Activates a window and displays it in its current                     size and position.      6              Minimizes the specified window and activates the                     top-level window in the system's list.      7              Displays a window as an icon. The window that is                     currently active remains active.      8              Displays a window in its current state. The window                     that is currently active remains active.      9              Activates and displays a window. If the window is                     minimized or maximized, Windows restores it to its                     original size and position (same as 1).				


The return value is the instance handle of the application that was openedor printed, if the function is successful. (This handle could also be thehandle of a DDE server application.) A return value less than or equal to32 specifies an error.


The ShellExecute() function returns the value 31 if there is no association for the specified file type or if there is no association for the specified action within the file type. The other possible error values are as follows:
Value          Meaning---------------------------------------------------------------------------   0             System was out of memory, executable file was corrupt, or                 relocations were invalid.   2             File was not found.   3             Path was not found.   5             Attempt was made to dynamically link to a task, or there                 was a sharing or network-protection error.   6             Library required separate data segments for each task.   8             There was insufficient memory to start the application.  10             Windows version was incorrect.  11             Executable file was invalid. Either it was not a Windows                 application, or there was an error in the .exe image.  12             Application was designed for a different operating system.  13             Application was designed for MS-DOS 4.0.  14             Type of executable file was unknown.  15             Attempt was made to load a real-mode application                (developed for an earlier version of Windows).  16             Attempt was made to load a second instance of an                 executable file containing multiple data segments that                 were not marked read-only.  19             Attempt was made to load a compressed executable file. The                 file must be decompressed before it can be loaded.  20             Dynamic-link library (DLL) file was invalid. One of the                 DLLs required to run this application was corrupt.  21             Application requires Microsoft Windows 32-bit extensions.				


The file specified by the lpszFile parameter can be a document file or an executable file. If it is a document file, this function opens or prints it, depending on the value of the lpszOp parameter. If it is an executable file, this function opens it, even if the string "print" is pointed to by lpszOp.
For more information about how to use the sample code in this article, clickthe article number below to view the article in the Microsoft Knowledge Base:
212536 OFF2000: How to Run Sample Code from Knowledge Base Articles
For more information about getting help with Visual Basic for Applications,please see the following Microsoft Knowledge Base article:
226118 OFF2000: Programming Resources for Visual Basic for Applications

Microsoft Windows SDK "Programmer's Reference, Volume 2: Functions,"pages 901-904
operating system environment winapi vba

Article ID: 238245 - Last Review: 12/05/2015 15:21:22 - Revision: 3.2

Microsoft Word 2000 Standard Edition

  • kbnosurvey kbarchive kbhowto kbprogramming KB238245