OLE Automation (Perl in a Nutshell, 2nd Edition)

The Win32::OLE modules give Perl support for OLE automation. OLE automation is a Microsoft technology based on COM that allows objects created by another application to be used and manipulated by a program through a common interface.

The application (or DLL) that implements the automation interface is called the automation server. The application that creates and uses the interface is called the automation controller or automation client. Many popular applications expose their objects through automation. Microsoft Word, Excel, and other Office applications can be used as automation servers. Automation is widely used by Active Server Pages (ASP) and CGI scripts to access data repositories, perhaps via ActiveX Data Objects (ADO). You can even use automation to control many development environments and editors.

To create an automation object, the server needs to be registered on the system. This is typically done by the server's installation program, but can be done manually using a utility such as regsvr32.exe. This involves adding entries to the system registry to tell COM how to find the component, the types of interfaces it provides, the type of server it is, etc. You should be able to find the object model, available methods, and properties of the interface in the documentation provided by the application. This object model can be used via Perl's object syntax to create and control objects in your programs.

Note that there are a few limitations to Win32::OLE. There is currently no support for OCXs or OLE events (notifications generated by the automation server). Win32::OLE implements the IDispatch interface only, and therefore cannot access a custom OLE interface.

23.1. Creating Objects

Automation objects are represented in Perl as instances of Win32::OLE objects. The module provides three constructors for creating objects from a registered automation server.

new

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.

GetActiveObject

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.

GetObject

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.

Chapter 23. OLE Automation

Contents:

23.1. Creating Objects