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:

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:

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