WinWord: WordBasic Shell Command Doesn't Return Success Value

ID: Q89785

The information in this article applies to:

SYMPTOMS

The WordBasic Shell command does not return any value indicating whether or not it was successful in starting an application in a Microsoft Word for Windows macro.

STATUS

Microsoft has confirmed this to be a problem in the Word for Windows version's listed above. This problem was corrected in Word 97 for Windows

The suggested workaround macro that uses a Winexec API call does not work in Word version 7.0. The names and locations of many Windows 3.x operating system routines (often referred to as API calls) changed in Windows 95 and Windows NT. You must update macros that declare Windows 3.x API calls to declare the correct routines in Windows 95 or Windows NT. Windows 3.x API function libraries are documented in the Microsoft Windows 3.1 Software Development Kit. Windows 95 and Windows NT function libraries are documented in the "Microsoft Win32 Software Development Kit."

WORKAROUND

You can work around this limitation of the WordBasic Shell command by directly calling the Windows API WinExec command from a Word for Windows macro. The WinExec command, similar to the Shell command, is used by Windows-based programs to start other programs. However, this command differs in that it returns a value indicating the successful completion of the command.

The syntax of the WinExec API call is as follows

   WORD WinExec(lpCmdLine, nCmdShow)

where "lpCmdLine" is a string that contains the command line (file name plus optional parameters) for the program to be executed, and "nCmdShow" specifies how a Windows program is to be appear when executed. This parameter can be set to one of the following:

   0 = Hides the window and passes activation to another window.
   1 = Activates and displays a window. If the window is minimized or
       maximized, it is restored.
   2 = Activates the window and displays it as an icon.
   3 = Activates the window and displays it maximized.
   4 = Displays window in most recent size and position. Active window
       remains active.
   5 = Activates a window and displays it in its current size and
       position.
   6 = Minimizes the window and activates the top level window in the
       window manager's list.
   7 = Displays the window as an icon and the active window remains
       active.
   8 = Displays the window in its current state and the active window
       remains active.

The return value specifies whether or not the function was successful. A return value less than 32 indicates that an error has occurred. The following describes the error values returned by the WinExec function:

   0  = Out of memory.
   2  = File not found.
   3  = Path not found.
   5  = Attempt to dynamically link to a task.
   6  = Library requires separate data segments for each task.
   10 = Incorrect Windows version.
   11 = Invalid .exe file (non-Windows .exe or error in .exe image).
   12 = OS/2 application.
   13 = DOS 3.0 application.
   14 = Unknown .exe type.
   15 = Attempt in protected mode to load an .exe file created for an
        earlier version of Windows.
   16 = Attempt to load a second instance of an .exe containing multiple
        writable data segments.
   17 = Attempt in large-frame EMS mode to load a second instance of an
        application that links to certain non-shareable DLLs already
        in use.
   18 = Attempt in real mode to load an application marked for
        protected mode only.

Using WinExec in a WordBasic Macro

The WordBasic Declare statement for the WinExec function is as follows:

   Word 7.0
   --------


   Declare Function WinExec Lib "Kernel32"(lpLine As String, \
   nShow As Integer) As Integer

   Word 6.0
   --------

   Declare Function WinExec Lib "Kernel"(lpLine As String, \
   nShow As Integer) As Integer

The following macro demonstrates how to use WinExec to start Microsoft Excel and recover from a possible error:

   Sub MAIN
   x = WinExec("c:\winapps\excel40\Excel", 8)
   If x < 32 Then
       Goto WinExecError
   Else
       MsgBox "Excel was launched successfully!"
   End If
   Goto ByeMAIN

   WinExecError:
   Select Case x
       Case 0
           MsgBox "Out of memory"
       Case 2, 3
           MsgBox "File or path not found"
       Case 10
           MsgBox "Incorrect Windows version"
       Case 15
           MsgBox "Attempted to run older Windows EXE"
       Case Else
           MsgBox "Other fatal WinExec error"
   End Select
   ByeMAIN:
   End Sub

WARNING: ANY USE BY YOU OF THE CODE PROVIDED IN THIS ARTICLE IS AT YOUR OWN RISK. Microsoft provides this macro code "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose.

MORE INFORMATION

The WordBasic Shell command is used in a Word for Windows macro to start other programs in Microsoft Windows. The syntax of the Shell command is as follows:

   Shell App$, [,WindowStyle]

This command does not return any value indicating the successful execution of App$, which makes it difficult for the macro to determine how to proceed (or if it can proceed if the program could not be started). Further, WordBasic provides no mechanism for trapping execution problems using the On Error facility.

The following macro illustrates this problem by attempting to run a program that does not exist or that cannot be found on the MS-DOS path:

   Sub MAIN
   Shell "noapp"
   MsgBox "I'm still running!"
   End Sub

Word for Windows responds with the following message when it fails to find the program named "noapp":

   Word cannot find or run the application

The macro then continues running as if no error occurred, even if error trapping has been activated.

REFERENCES

"Using WordBasic," by WexTech Systems and Microsoft, pages 284-285

"Microsoft Windows Programmer's Reference," pages 4-458, 4-459

Kbcategory: kbusage kbmacro KBSubcategory: Additional query words: 6.0 6.0a 6.0c launch 1.0 1.10 1.10a 2.0 word6 winword 7.0 word95 word7 winword winword2 2.0a 2.0a-CD 2.0b

Version           : 1.x 2.x 6.0 6.0a 6.0c 7.0 7.
Platform          : WINDOWS

Last Reviewed: July 30, 1997