How to Call the ShellExecute Windows API in a WordBasic Macro

• Microsoft Word for Windows, versions 2.0, 2.0a, 2.0a-CD, 2.0b, 2.0c, 6.0, 6.0a, 6.0c

SUMMARY

You can call the ShellExecute() Windows API function from a WordBasic macro to start another program under Microsoft Windows. Use ShellExecute() instead of Shell (a WordBasic statement) or WinExec() (a Windows API function) to work around the following limitation of the latter commands:

• With Shell and WinExec(), you cannot both start an application and open a file in that application. For example, you cannot both start Microsoft Excel and open a worksheet.

Below is a sample WordBasic 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 "Shell"(hWnd As Integer, lpszOp
   As String, lpszFile As String, lpszParams As String, lpszDir As
   String, fsShowCmd As Integer) As Integer

   Declare Function FindWindow Lib "User"(lpClassName$, lpWindowName As
   Long) As Integer

   Sub MAIN
   Rem The FindWindow API function returns the Window handle for Word.
   hWnd = FindWindow("OPUSAPP", 0)

   X = ShellExecute(hWnd, "Open", "c:\excel\book1.XLS", "", "", 1)
   End Sub

MORE INFORMATION

The ShellExecute() function opens or prints the specified file. Below 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.

6              Minimizes the specified window and activates the top-level
               window in the system's list.

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).

5              Activates a window and displays it in its current size and
               position.

3              Activates a window and displays it as a maximized window.

2              Activates a window and displays it as an icon.

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.

4              Displays a window in its most recent size and position. The
               window that is currently active remains active.

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).

Returns

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

Errors

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.

Comments

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.

REFERENCES

Microsoft Windows SDK "Programmer's Reference, Volume 2: Functions," pages 901-904