Objects

Typically, the first action a script must perform when working with a COM-enabled application is to create or retrieve an object to work with.

Creating objects

There are two ways of creating objects: the new statement and the COM_CreateObject() function. The following example shows how to use the COM_CreateObject() function to create a new instance of Microsoft Word.

local Word.Application app;

app = COM_CreateObject("Word.Application");
if app = null then
	error "Could not create Word application object.";
end if;

Whether you use new or COM_CreateObject() will depend on how the object is being created and will be used. Note the following differences between the two techniques:

• The new statement uses a COM reference to specify the COM object to create, while the COM_CreateObject() function uses a string value. This means the object type can be verified at compile-time for the new statement.
• The COM_CreateObject() function allows you to implement Distributed COM (DCOM) by specifying the machine on which the COM object will be created. The new statement doesn’t allow the machine to be specified.

Only certain objects can be created with the COM_CreateObject() function or the new statement. Most objects must be created using methods provided in the COM library for the specific application. For example, in Microsoft Excel you can’t use the following statement to create a chart:

chart = new Excel.Chart();

Instead, you must use the Add() method for the workbook object:

chart = workbook.Charts.Add();

Guidelines

Keep in mind the following guidelines when creating objects:

• Use COM_CreateObject() to create application objects by name, and when using Distributed COM (DCOM). Otherwise, use the new statement to create application objects.
• When possible, use methods within a library to create additional objects.
• If a library doesn’t contain methods to create new objects, try the new statement to create the object.
• If the new statement doesn't work to create an object, then use the COM_CreateObject() function.

Retrieving objects

In some cases, the application you want to interact with may already be running. You can use the COM_GetObject() function to retrieve an object for an application that is already running.

local Excel.Application app;

{Retrieve a reference to a running instance of Excel.}
app = COM_GetObject("Excel.Application");
if app = null then
	warning "Excel is not running.";
end if;

Destroying objects

When you have finished working with a COM object, you should properly dispose of the object. Dexterity keeps track of how many times a specific object is being referenced. An object will exist as long as there is a valid reference to it.

A reference to an object is cleared automatically when the field or variable goes out of scope, such as a script ending or a form being closed. You can explicitly destroy a reference to a COM object by setting it to null, or by using the clear statement.

Documentation Feedback

---