How to Use OLE Automation with Word 6.0/7.0

Last reviewed: February 6, 1998
Article ID: Q161547

The information in this article applies to:

Microsoft Word for Windows versions 7.0, 7.0a
Microsoft Word for Windows, versions 6.0, 6.0a, 6.0c

SUMMARY

This article provides an overview of using OLE Automation with the versions of Word for Windows listed at the beginning of this article.

NOTE: Throughout this article, examples utilizing OLE Automation assume that the following lines of Visual Basic code have been used to initiate the OLE Automation session:

   Dim WBO As Object                       'Declare an object variable
   Set WBO = CreateObject("Word.Basic")    'Set the object pointer

MORE INFORMATION

Word versions 6.x and 7.x can be OLE Automation servers. Word makes available a single object, Word.Basic, allowing you to issue WordBasic commands from another application to control actions in Word. If you wish to use WordBasic to control other applications, you must use DDE.

General Example

The following Visual Basic example creates and uses a WordBasic OLE object:

Sub WordExample ()
   Dim WBO As Object                    'Declare an object variable
   Set WBO = CreateObject("Word.Basic") 'Set the object pointer
   WBO.FileNew                          'Create a new File in Word
   WBO.Bold                             'Make the Font Bold
   WBO.FontSize 24                      'Make the Font 24 point in size
   WBO.CenterPara                       'Center Text on page
   WBO.Insert "Automation's Great!"     'Insert some text
   WBO.FilePrintDefault                 'Print the current document
   WBO.FileClose 2                      'Close file without saving.
   Set WBO = Nothing                    'Clear the object pointer.
End Sub

The CreateObject function launches Word if it is not already running. Otherwise it uses the currently-active instance of Word.

The Set WBO = Nothing statement exits Word if Word was launched by the CreateObject statement.

OLE Automation cannot invoke the FileExit method of WordBasic. Because OLE Automation cannot start a new instance of Word after the initial instance, OLE Automation assumes that the user started Word and the user is responsible for exiting the application.

Using Named and Positional Arguments

There are generally two ways of sending commands when using OLE Automation, using either Named or Positional arguments. Positional arguments have many drawbacks: all arguments for a command have to be used, the arguments have to be in the proper order, and your code is generally less readable. The following example uses positional arguments:

   WBO.FormatFont ,,,,,,,,,,,,,,,,True  'Format selection as bold.

Named arguments allow you to specify only those arguments you wish to use. They can be in any order and, because the arguments are named, the code is generally more readable. For example:

   WBO.FormatFont Bold:=True            'Format selection as bold.

It is generally better to use named arguments whenever possible. However, Visual Basic 3.0 for Windows supports using only positional arguments.

Many of the WordBasic commands documented in Word's Help or in the Word Developer's Kit do not have the arguments listed in the correct order, because WordBasic itself uses named arguments and isn't particular about the order in which the arguments are used.

Microsoft has made available a file, Position.txt, that lists all the WordBasic commands and their arguments in the correct order. However, you must be sure you are using the correct version of this file. The version in the first and second edition of the Word Developer's Kit is designed for Word 6.x and the Position.txt file included in the third edition of the Word Developer's Kit is designed for Word for Windows version 7.x.

Programmers using Visual Basic 4.0 should use named arguments to avoid concerns about argument positions.

REFERENCES

For additional information, please see the following article(s) in the Microsoft Knowledge Base:

   ARTICLE-ID: Q105534
   TITLE     : OLE: Visual Basic 3.0 Does Not Support Named Arguments

   ARTICLE-ID: Q112733
   TITLE     : POSITION.HLP File for VB OLE Automation w/ Word for Windows

General Syntax for Named Arguments

WordBasic (without using OLE Automation) arguments are preceded with a period. This is how the commands are documented in all references about WordBasic. Consider the following example:

   EditBook .Name="test", .Add

OLE Automation does not use the same type of syntax. Because OLE Automation is programmed in another application, you must use that application's syntax for passing OLE Automation arguments. Visual Basic, for example, does not use periods before argument names, and a colon must be used before the equal sign (:=). The following sample OLE Automation syntax using Visual Basic or Visual Basic for Applications is typical:

   WBO.EditBookmark Name:="test", Add:=True

Syntax for Using String Functions

The syntax of WordBasic functions that return strings includes a dollar sign ($) to indicate the return type. Visual Basic version 3.0 and other applications, such as Microsoft Access for Windows version 7.0 may require that these functions be enclosed in square brackets ([]). The following example returns the text stored in the bookmark MyBookMark:

   MyVar = WBO.[GetBookMark$]("MyBookMark")  'Return text from bookmark

Without using the square brackets, Visual Basic version 3.0 returns the error, Bad Parameter.

Using Boolean Arguments

Many WordBasic commands use arguments to specify actions, which usually equate to buttons in a Word dialog box. To use these arguments, you must pass a Boolean value of True. For example, the EditBookmark command has multiple actions you can specify (Add, Delete, and GoTo). In WordBasic, the most commonly used syntax would be:

   EditBookmark .Name="test", .Add

However, the following syntax is also valid:

   EditBookmark .Name="test", .Add=True

When using OLE Automation, you must specify the Boolean value. Using named arguments with OLE Automation, the command would be:

   WBO.EditBookmark Name:="test", Add:=True

Using positional arguments, the command would be:

   WBO.EditBookmark "test", , True

Background Processing

Word performs some actions in the background, including printing, auto- saving, and spelling. The background printing option, in particular, can cause problems when using OLE Automation to print from Word. Background printing should be turned off when using OLE Automation.

To turn background printing off, click Options on the Tools menu. Then click the Print tab, and click to clear the checkbox for background printing. Or, you can use the following code to do this through OLE Automation prior to printing:

   WBO.ToolsOptionsPrint Background:=0

For example, when background printing is on, setting WBO=Nothing may cause the print job to be canceled. If you encounter this problem, you can also work around it by making the Word object variable's scope local to the form rather than to the Sub procedure.

CreateObject Fails

The CreateObject function could cause an error under any of the following circumstances:

Word is not registered in the Windows Reg.dat file.

Windows is low on system resources.

Your user-defined Normal.dot template and/or automatically loading macros in Word could run automatic actions that might conflict with your requested OLE Automation commands.

The OLE server application is not found. With Windows version 3.1, object linking and embedding (OLE) clients look for a server application in the following order:

      1. The location specified in the Windows Reg.dat file.
      2. The location specified in the Win.ini file.
      3. The Windows folder.
      4. The Windows\System folder.
      5. The location specified in the MS-DOS PATH environment variable
         (specified in the Autoexec.bat file).

KBCategory: kbmacro
KBSubcategory:
Additional query words: 6.0 7.0 winword word7 word95
Keywords : kbinterop kbole kbmacro
Version : 6.0 6.0a 6.0c 7.0 7.0a
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: February 6, 1998
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.