Microsoft KB Archive/89785

{|
 * width="100%"|

WinWord: WordBasic Shell Command Doesn't Return Success Value

 * }

Q89785

-

The information in this article applies to:


 * Microsoft Word for Windows, versions 1.0, 1.1, 1.1a, 2.0, 2.0a, 2.0a-CD, 2.0b, 2.0c, 6.0, 6.0a, 6.0c
 * Microsoft Word for Windows, versions 7.0, 7.0a

-

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 &quot;Microsoft Win32 Software Development Kit.&quot;

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 &quot;lpCmdLine&quot; is a string that contains the command line (file name plus optional parameters) for the program to be executed, and &quot;nCmdShow&quot; 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 &quot;Kernel32&quot;(lpLine As String, \    nShow As Integer) As Integer

Word 6.0
  Declare Function WinExec Lib &quot;Kernel&quot;(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(&quot;c:\winapps\excel40\Excel&quot;, 8) If x < 32 Then Goto WinExecError Else MsgBox &quot;Excel was launched successfully!&quot; End If  Goto ByeMAIN

WinExecError: Select Case x      Case 0 MsgBox &quot;Out of memory&quot; Case 2, 3 MsgBox &quot;File or path not found&quot; Case 10 MsgBox &quot;Incorrect Windows version&quot; Case 15 MsgBox &quot;Attempted to run older Windows EXE&quot; Case Else MsgBox &quot;Other fatal WinExec error&quot; 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 &quot;as is&quot; 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 &quot;noapp&quot; MsgBox &quot;I'm still running!&quot; End Sub Word for Windows responds with the following message when it fails to find the program named &quot;noapp&quot;:

Word cannot find or run the application

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