INFO: OLE Automation Objects with GetObject and CreateObject

Last reviewed: September 29, 1997
Article ID: Q114347
The information in this article applies to:
  • Standard, Professional, and Enterprise Editions of Microsoft Visual Basic, 16-bit and 32-bit, for Windows, version 4.0
  • Standard and Professional Editions of Microsoft Visual Basic Programming System, version 4.0, for Windows
  • Microsoft Excel, versions 5.0 and 7.0
  • Microsoft Project, versions 4.0 and 4.1
  • Microsoft Word for Windows, versions 6.0 and 7.0

SUMMARY

This article documents the behavior of top-level Microsoft OLE Automation objects in Microsoft Word, Microsoft Excel, and Microsoft Project when manipulated by the Visual Basic CreateObject() and GetObject() functions.

Because only the products and versions listed at the beginning of this article support OLE 2.0 Automation, the version-dependent top-level OLE Automation objects, such as Excel.Application.5, function the same way as the version-independent top-level OLE automation objects such as Excel.Application. Therefore, only the version-independent top-level OLE Automation objects are discussed in this article.

In addition, this article does not discuss the possibility of other applications referencing the same objects or the possibility of running out of resources or memory.

MORE INFORMATION

Each Microsoft application that currently supports OLE Automation behaves differently with respect to how its top-level OLE Automation objects function. The following sections list the behaviors of each application and each possible syntax used with each top-level OLE Automation objects within that application.

Microsoft Excel Versions 5.0 & 7.0

  • Excel exposes three top-level OLE Automation objects (Application, Sheet, and Chart).
  • Excel supports multiple instances.
  • New instances of Excel created through top-level OLE Automation objects are invisible. They can be made visible by setting the visible property of the application object to True (...Application.Visible = True).
  • In some cases, Excel creates invisible Workbooks. They can be made visible by setting the visible property of the window to true (...Window(n).Visible = True).
  • In some cases, Excel does not create a workbook. To create one, use the add method of the Workbooks collection (...Workbooks.Add).
  • To remove an instance of Excel from memory, you must use the quit method of the application object (...Application.Quit).

Syntax Statements for Microsoft Excel Versions 5.0 & 7.0 Application Object

Set Obj = CreateObject("Excel.Application")

  • Creates a new invisible instance of Excel.
  • No workbooks are loaded.

Set Obj = GetObject("", "Excel.Application")
  • Creates a new invisible instance of Excel.
  • No workbooks are loaded.

Set Obj = GetObject(, "Excel.Application")
  • Tries to get an existing instance of Excel at random. If an instance is found, Obj points to it.
  • Fails if there is not an existing instance.

Syntax Statements for Microsoft Excel Versions 5.0 & 7.0 Sheet Object

Set Obj = CreateObject("Excel.Sheet")

  • If there are no instances of Excel, a new invisible instance of Excel is created with a workbook named "Object" containing one worksheet named "Sheet1."
  • If one instance of Excel exists, a new visible workbook is added named "Object" containing one worksheet named "Sheet1."
  • If multiple instances of Excel exist, a new workbook is added to one instance chosen at random. The workbook name is "Object" and it contains one worksheet named "Sheet1."
  • If Obj goes out of scope, the workbook is removed. However, the instance of Excel remains in memory.

Set Obj = GetObject("", "Excel.Sheet")
  • If there are no instances of Excel, a new invisible instance of Excel is created with a workbook named "Object" containing one worksheet named "Sheet1."
  • If one instance of Excel exists, a new workbook is added named "Object" containing one worksheet named "Sheet1."
  • If multiple instances of Excel exist, a new workbook is added to one instance chosen at random. The workbook name is "Object," and it contains one worksheet named "Sheet1."
  • If Obj goes out of scope, the workbook is removed. However, the instance of Excel remains in memory.

Set Obj = GetObject(, "Excel.Sheet")
  • Always fails.

Set Obj = GetObject("C:\BOOK.XLS", "Excel.Sheet")
  • If no instances of Excel exists, a new invisible instance is created with an invisible workbook.
  • If one instance of Excel exists, a new invisible workbook is loaded. If the loaded instance already has the specified workbook loaded, that workbook is used.
  • If more than one instance of Excel is loaded, a new invisible workbook is loaded into one at random. If one of the instances already has the specified workbook open, an error occurs unless the random instance chosen is the one using the specified workbook.
  • Obj points to the first worksheet in the specified workbook.
  • Fails if workbook does not exist.
  • When Obj goes out of scope, the instance of Excel stays loaded in memory. However, the specified workbook will be unloaded unless the invisible workbook was made visible.

Syntax Statements for Microsoft Excel Versions 5.0 & 7.0 Chart Object

Set Obj = CreateObject("Excel.Chart")

  • If there are no instances of Excel, a new invisible instance of Excel is created with a workbook named "Object" containing one chart named "Chart1" and one worksheet named "Sheet1."
  • If one instance of Excel exists, a new workbook is added named "Object" containing one chart named "Chart1" and one worksheet named "Sheet1" by default.
  • If multiple instances of Excel exist, a new Workbook is added to one instance chosen at random. The workbook's default name is "Object," and it contains one chart named "Chart1" and one worksheet named "Sheet1."
  • If Obj goes out of scope, the workbook is removed. However, the instance of Excel remains in memory.

Set Obj = GetObject("", "Excel.Chart")
  • If there are no instances of Excel, a new invisible instance of Excel is created with a workbook named "Object" containing one chart named "Chart1" and one worksheet named "Sheet1."
  • If one instance of Excel exists, a new workbook is added named "Object" containing one chart named "Chart1" and one worksheet named "Sheet1" by default.
  • If multiple instances of Excel exist, a new Workbook is added to one instance chosen at random. The workbook's default name is "Object" and it contains one chart named "Chart1" and one worksheet named "Sheet1."
  • If Obj goes out of scope, the workbook is removed. However, the

          instance of Excel remains in memory.
    

Set Obj = GetObject(, "Excel.Chart")
  • Always fails.

Set Obj = GetObject("C:\BOOK.XLS", "Excel.Chart")
  • If no instances of Excel exist, a new invisible instance is created with an invisible workbook.
  • If one instance of Excel exists, an invisible workbook is loaded. If the loaded instance already has the specified workbook loaded, that workbook is used.
  • If more than one instance of Excel is loaded, an invisible workbook is loaded into one at random. If one of the instances already running has the specified workbook open an error occurs unless the random instance chosen is the one using the specified workbook.
  • Obj points to the first chart in the workbook.
  • Fails if workbook does not exist.
  • When Obj goes out of scope, the instance of Excel stays loaded in memory. However, the specified workbook will be unloaded unless the invisible workbook was made visible.

Microsoft Word Version 6.0

  • Word exposes one top level OLE Automation object (Basic).
  • Word supports multiple instances.
  • Instances of Word created with its top level OLE Automation object are visible.
  • When the OLE Automation object goes out of scope, the instance of Word is unloaded unless the object was created from a previous instance.

Syntax Statements for Microsoft Word Version 6.0 Basic Object

Set Obj = CreateObject("Word.Basic")

  • If no instances of Word exist, a new visible instance is loaded that does not contain a document. If Obj goes out of scope, Word is unloaded from memory.
  • If an instance of Word exists, Obj points to it. If Obj goes out of scope, the instance of Word remains in memory.
  • If more than one instance of Word exists, Obj points to one chosen at random. If Obj goes out of scope, all the instances remain in memory.

Set Obj = GetObject("", "Word.Basic")
  • If no instances of Word exist, a new visible instance is loaded that does not contain a document. If Obj goes out of scope, Word is unloaded from memory.
  • If an instance of Word exists, Obj points to it. If Obj goes out of scope, the instance of Word remains in memory.
  • If more than one instance of Word exists, Obj points to one chosen at random. If Obj goes out of scope, all the instances remain in memory.

Set Obj = GetObject(, "Word.Basic")
  • Always Fails.

Microsoft Word Version 7.0

  • Word exposes one top level OLE Automation object (Basic).
  • Word supports multiple instances.
  • Instances of Word created with its top level OLE Automation object are invisible, but can be made visible by issuing the Wordbasic Appshow command.
  • When the OLE Automation object goes out of scope, the instance of Word is unloaded unless the object was created from a previous instance.

Syntax Statements for Microsoft Word Version 7.0 Basic Object

Set Obj = CreateObject("Word.Basic")

  • If no instances of Word exist, a new invisible instance is loaded that does not contain a document. If Obj goes out of scope, Word is unloaded from memory.
  • If an instance of Word exists, Obj points to it. If Obj goes out of scope, the instance of Word remains in memory.
  • If more than one instance of Word exists, Obj points to one chosen at random. If Obj goes out of scope, all the instances remain in memory.

Set Obj = GetObject("", "Word.Basic")
  • If no instances of Word exist, a new invisible instance is loaded that does not contain a document. If Obj goes out of scope, Word is unloaded from memory.
  • If an instance of Word exists, Obj points to it. If Obj goes out of scope, the instance of Word remains in memory.
  • If more than one instance of Word exists, Obj points to one chosen at random. If Obj goes out of scope, all the instances remain in memory.

Set Obj = GetObject(, "Word.Basic")
  • Always Fails.

Microsoft Project Versions 4.0 & 4.1

  • Project exposes two top-level OLE Automation objects (Application and Project).
  • Project does not support multiple instances.
  • New instances of Project created through top-level OLE Automation objects are invisible. They can be made visible by setting the visible property of the application object to true (...Application.Visible = True).
  • In some cases, Project creates an invisible project.
  • If an instance of Project is not unloaded, use the quit method of the application object to unload it (...Application.Quit).

Syntax Statements for Microsoft Project Versions 4.0 & 4.1 Application Object

Set Obj = CreateObject("MSProject.Application")

  • If no instance of Project exists, a new invisible instance is loaded. If Obj goes out of scope, the instance of Project is unloaded.
  • If an instance of Project exists, Obj points to it. If Obj goes out of scope, the instance of Project is not unloaded.
  • No projects are loaded.

Set Obj = GetObject("", "MSProject.Application")
  • If no instance of Project exists, a new invisible instance is loaded. If Obj goes out of scope, the instance of Project is unloaded.
  • If an instance of Project exists, Obj points to it. If Obj goes out of scope, the instance of Project is not unloaded.
  • No projects are loaded.

Set Obj = GetObject(, "MSProject.Application")
  • If an instance of Project exists, Obj points to it. No projects are loaded.
  • Fails if there is no existing instance.

Syntax Statements for Microsoft Project Versions 4.0 & 4.1 Project Object

Set Obj = CreateObject("MSProject.Project")

  • If no instance of Project exists, a new invisible instance is created, and Obj points to a newly created invisible project object. The project is named "Project1" by default. If Obj goes out of scope, the instance of Project is unloaded from memory.
  • If an instance of Project exists, Obj points to a newly created invisible project object. Existing projects will still be loaded. If Obj goes out of scope, Project will not be unloaded.

Set Obj = GetObject("", "MSProject.Project")
  • If no instance of Project exists, a new invisible instance is created, and Obj points to a newly created invisible project object. The project is named "Project1" by default. If Obj goes out of scope, the instance of Project is unloaded from memory.
  • If an instance of Project exists, Obj points to a newly created invisible project object. Existing projects will still be loaded. If Obj goes out of scope, Project will not be unloaded.

Set Obj = GetObject(, "MSProject.Project")
  • Always Fails.

Set Obj = GetObject("C:\PROJ.MPP", "MSProject.Project")
  • If no instance of Project exists, a new invisible instance is loaded with the specified project file. The project is not visible.
  • If an instance of Project exists, the project is loaded but it is not visible, and Obj points to it. Existing projects will be loaded. If the specific project was already loaded, the statement will fail.
  • Fails if project file does not exist.

NOTE: When an object variable goes out of scope, it is de-referenced. The object reference count is de-cremented, and if it reaches zero, the object can be removed from memory. You can explicitly de-reference an object by setting it to nothing (Set Obj = Nothing). This should have the same effect as the object variable going out of scope.


Additional query words: W_VBApp
Keywords : IAPOLE VB4ALL VB4WIN vbwin GnrlVb kbprg
Technology : kbole kbvba
Version : WINDOWS:3.0 4.0
Platform : WINDOWS
Issue type : kbinfo


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: September 29, 1997
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.