HOWTO: Use ShellExecute to Launch Associated File (16-bit)

Last reviewed: July 2, 1997
Article ID: Q147807
The information in this article applies to:
  • Microsoft Visual Basic Professional and Enterprise Editions, 16-bit only, for Windows, version 4.0
  • Microsoft Visual Basic Standard and Professional Editions for Windows, version 3.0

SUMMARY

You can use the Windows API ShellExecute() function to start the application associated with a given document extension without knowing the name of the associated application. For example, you could start the Paintbrush program by passing the filename ARCADE.BMP to the ShellExecute() function.

MORE INFORMATION

The ShellExecute function opens or prints the specified file. Following is the declaration to use when calling this function from Visual Basic:

   Declare Function ShellExecute Lib "SHELL" (ByVal hwnd%, ByVal lpszOp$, _
   ByVal lpszFile$, ByVal lpszParams$, ByVal lpszDir$, ByVal _
   fsShowCmd%) As Integer

The table below provides descriptions for each parameter:

Parameter   Description

hwnd%       Identifies the parent window. This window receives any message
            boxes an application produces (for example, for error
            reporting).
lpszOp$     Points to a null-terminated string specifying the operation to
            perform. This string can be "open" or "print." If this
            parameter is NULL, "open" is the default value.
lpszFile$   Points to a null-terminated string specifying the file to open.
lpszParams$ Points to a null-terminated 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 null-terminated 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
            values described in the API ShowWindow().

Step-by-Step Example

The following example demonstrates how to start an application or load a document into its associated application. The Windows API ShellExecute() function is different from the Visual Basic Shell() function in that you can pass the ShellExecute() function the name of a document and it will launch the associated application, and then pass the filename to the application. In the following code sample, the underscore character, "_", indicates a continuation of one line of code and must be removed for Visual Basic 3.0:

  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: (NOTE: Remove the keyword "PRIVATE" when using Visual Basic 3.0)

          Option Explicit
          
          Const SW_SHOWNORMAL = 1
          
          Private Declare Function ShellExecute Lib "shell.dll" (ByVal hwnd%, _
          ByVal lpszOp$, ByVal lpszFile$, ByVal spszParams$, ByVal _
          lpszDir$, ByVal fsShowCmd%) As Integer
          
          Private Declare Function GetDesktopWindow Lib "USER" () As Integer
          
          Function StartDoc(DocName As String) As Integer
    
             Dim Scr_hDC As Integer
             Scr_hDC = GetDesktopWindow()
             StartDoc = ShellExecute(Scr_hDC, "Open", DocName, "", "C:\", _
             SW_SHOWNORMAL)
          End Function
          
          Sub Form_Click()
             Dim r As Integer
             r = StartDoc("C:\WINDOWS\ARCADE.BMP")
          End Sub
    
    

General Information About the Process

If the function succeeds, the return value is the instance handle of the application that was run. If there was an error, the return value is less than or equal to 32.

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 can only open it and the lpszOp$ parameter must specify "OPEN."

REFERENCES

"Programmer's Reference, Volume 2: Functions" of the Microsoft Windows Software Development Kit (SDK), pages 901-904.

ShellExecute topic of the Windows 3.1 SDK Help file.


Keywords : APrgWindow vb4all vb4win kbprg
Version : 3.0 4.0
Platform : WINDOWS


THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: July 2, 1997
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.