Article ID: 288902
Article Last Modified on 1/31/2007
APPLIES TO
- Microsoft Office Excel 2007
- Microsoft Office Excel 2003
- Microsoft Excel 2002 Standard Edition
- Microsoft Excel 2000 Standard Edition
- Microsoft Excel 97 Standard Edition
- Microsoft Office Access 2007
- Microsoft Office Access 2003
- Microsoft Access 2002 Standard Edition
- Microsoft Access 2000 Standard Edition
- Microsoft Access 97 Standard Edition
- Microsoft Office PowerPoint 2007
- Microsoft Office PowerPoint 2003
- Microsoft PowerPoint 2002 Standard Edition
- Microsoft PowerPoint 2000 Standard Edition
- Microsoft PowerPoint 97 Standard Edition
- Microsoft Project 2000 Standard Edition
- Microsoft Project 98 Standard Edition
- Microsoft Office Word 2007
- Microsoft Office Word 2003
- Microsoft Word 2002 Standard Edition
- Microsoft Word 2000 Standard Edition
- Microsoft Word 97 Standard Edition
This article was previously published under Q288902
SUMMARY
This article discusses the different behaviors that occur when you use the GetObject and CreateObject functions with various versions of Microsoft Office applications. GetObject and CreateObject are functions that are provided by Microsoft Visual Basic and Microsoft Visual Basic for Applications (VBA). However, the information is also applicable to Microsoft Visual C++ if you treat references to GetObject as calls to the GetActiveObject API, and references to CreateObject as calls to the CoCreateInstance API.
MORE INFORMATION
GetObject
GetObject is used to attach to a running instance of an automation server. There are a few different ways to call GetObject, but the syntax that is recommended for the Microsoft Office applications is as follows:
set xlApp = GetObject(, "Excel.Application")
If an instance of Microsoft Excel is running when this code is executed, you have access to the running instance's object model through the xlApp variable. If no instance is running, you receive the following trappable run-time error message:
If multiple instances of Microsoft Excel are running, GetObject attaches to the instance that is launched first. If you then close the first instance, another call to GetObject attaches to the second instance that was launched, and so forth.
You can attach to a specific instance if you know the name of an open document in that instance. For example, if an instance of Excel is running with an open workbook named Book2, the following code attaches successfully to that instance even if it is not the earliest instance that was launched:
Set xlApp = GetObject("Book2").Application
CreateObject
CreateObject is used to start a new instance of an Automation server. For example:
set xlApp = CreateObject("Excel.Application")
Depending on whether the server is designed as SingleUse or MultiUse, another server process may or may not be launched. This might be an important distinction for deciding whether you should forcibly shut down an Automation instance. For example, with a MultiUse server, if an instance is already running before you attach to it, then you might want to avoid shutting down the server programmatically when you are done automating it.
The following table serves as a helpful reference when implementing a solution with Microsoft Office. It lists behaviors and attributes of the various versions and applications of Microsoft Office, such as whether the server defaults to being visible when launched, if it is SingleUse or MultiUse, if it has a UserControl property, if it has a Quit method, and the class name for its main window.
| Application(s) | Visible | Instancing | Has UserControl | Has Quit | ClassName |
|---|---|---|---|---|---|
| Excel 97, 2000, 2002, 2003, 2007 | No | SingleUse | Yes | Yes | XlMain |
| Word 97, 2000, 2002, 2003, 2007 | No | SingleUse | Yes | Yes | OpusApp |
| PowerPoint 97 | No | MultiUse | No | Yes | PP97FrameClass |
| PowerPoint 2000 | No | MultiUse | No | Yes | PP9FrameClass |
| PowerPoint 2002 | No | MultiUse | No | Yes | PP10FrameClass |
| PowerPoint 2003 | No | MultiUse | No | Yes | PP11FrameClass |
| PowerPoint 2007 | No | MultiUse | No | Yes | PP12FrameClass |
| Access 97 | Yes | SingleUse | Yes | Yes | OMain |
| Access 2000, 2002, 2003, 2007 | No | SingleUse | Yes | Yes | OMain |
| Project 98, 2000 | No | MultiUse | Yes | Yes | JWinproj-WhimperMainClass |
The main window class name is helpful for calling the FindWindow API when you want to find out conveniently if any instance is already running. The UserControl property is a boolean property that indicates whether the server application automatically shuts down when its last reference is released (set to nothing). The Quit method allows you to override the UserControl property in cases where it is necessary (such as when an instance does not shut down after the last reference is released).
In general, Microsoft recommends that you use a new instance of an Office application instead of attaching to an instance that the user may be using. It is best create an instance by using the Application ProgID, and then open or create new objects from there. Other ProgIDs, such as Excel.Sheet and Word.Document, and so forth, are intended for use in OLE (Object linking and Embedding) and may give inconsistent results when used with CreateObject. By using the Application ProgID, you avoid potential issues by explicitly starting the server for Automation (not Embedding).
When you are finished with the Automation server, release all your references to it and call its Quit method (if available) so that the server shuts down as expected. If you want to configure an instance through Automation and then leave it open for the user to use, you need to set the UserControl property to TRUE and then release all your references. The server then stays running (because the UserControl property is TRUE) and shuts down appropriately when the user closes the application (because there are no outstanding references).
Note For Word, the UserControl property is read-only. It cannot be set to True or False. Word always remains running when the last reference is released.
REFERENCES
For more information about using GetObject/CreateObject, and to learn about some exceptions and issues with using Automation to Microsoft Office, click the following article numbers to view the articles in the Microsoft Knowledge Base:
222783 PPT2000: CreateObject Does Not Create New PowerPoint Session
188546 BUG: Starting Word Manually Uses Same Instance as Automation
265385 INFO: Automation of PowerPoint 97 and PowerPoint 2000 Viewers
259940 BUG: Word 2000 Does Not Quit When Keybindings.ClearAll Is Called
258511 HOWTO: Obtain Window Handle to Office Application For Automation
249169 PPT97: PowerPoint 97 Remains in Memory After Getting a Presentation and Being Closed
159922 XL97: Using Quit Method May Cause Illegal Operation
Additional query words: rot IRunningObjectTable LPRUNNINGOBJECTTABLE moniker reference counting
Keywords: kbautomation kbinfo KB288902
