Chapter 23. OLE Automation

Win32::OLE->new(progid, [destructor])

Creates a new automation object. This method always creates a new instance of the server, even if a previous instance of the server is running. If the object cannot be created, new returns undef.

progid, the program identifier (ProgID), is a string that uniquely identifies an automation object. progid is used to look up the object's class ID (CLSID), which is stored in the registry.

The second, optional argument to the new method describes a way to destroy the object in case the Perl program dies unexpectedly. destructor can be either a string with the name of the defined OLE destructor method, or a code reference that will destroy the object. You should use some form of destructor to close out all your objects, for they can be extremely expensive in terms of system resources. You can explicitly destroy an object using the undef function. If you don't explicitly destroy the object, Perl takes care of it for you when the last reference to the object goes away.

Here is what new would look like with the destructor arguments:

# Quit is the OLE-defined destructor method
$x1 = Win32::OLE->new("Excel.Application", 'Quit');

# The object reference is the first argument ($_[0]) passed to new
# The code reference will undef it to destroy the object
$x2 = Win32::OLE->new("Excel.Application", sub{undef $_[0];})

Notice that we're supplying Excel.Application as the ProgID. Excel supports several different automation objects, including an Application object, WorkBook objects, and several more. You don't necessarily have to create the top-level object (Application, in this case) when dealing with automation objects (this is determined by the automation server). In Excel's case, we could have directly created a WorkSheet object (e.g., Excel.Sheet) or a Chart object, for example.

Win32::OLE->GetActiveObject(progid)

Creates an object for a currently active instance of a server, if one exists. If the server is registered, but no instance of it is running, the method returns undef. If the server is not registered, the method will croak.

You should probably call GetActiveObject inside an eval so that you can do exception handling in the event that the server is unregistered or is not currently running. If the method returns undef, you can just create a new instance of the server and the object with new.

Win32::OLE->GetObject(filename)

Creates an automation object based on a document. filename is the full pathname of the document, which can be optionally followed by additional item subcomponents separated by exclamation marks (!). For example:

$doc = 'c:\test\test.xls';
$x1 = Win32::OLE->GetObject($doc);

This code creates an Excel instance based on an Excel file. It is not always clear what type of object GetObject will return from a document since applications may register for more than one document type (e.g., worksheets, charts, macro files, etc. for Excel). You can use QueryObjectType on an object to get the class name of the object.