Automation Methods and Properties

Once you have created an automation object, you can use its methods or adjust its properties as you require. Automation methods are implemented as you'd expect with the Perl object syntax: 

$obj->some_method(args);

Automation methods can often take a number of optional parameters. You can pass undef for any unwanted parameters in the arguments list. For example, you can save a WorkTutorial in Excel with SaveAs. Additional settings allow you to add the WorkTutorial to the MRU list and create a backup copy: 

$xl->WorkBooks(1)->SaveAs($f, undef, undef, undef, undef, 1, undef, undef, 1);

For simplification, you can also use just the named parameters you want to set by passing a reference to a hash containing them. You can do this right in the argument list by creating an anonymous hash reference with {}. The previous example can therefore be written like this: 

$xl->WorkBooks(1)->SaveAs($f, {AddtoMru => 1, CreateBackup => 1});

Properties of automation objects are accessed via hash reference notation on the object. For example: 

$val = $obj->{"property"};
 # Get a property value $obj->{"property"} = $val; # Set a property value

Be aware that properties may not be writable (or even readable). Many automation objects have read-only properties and will generate an exception if you try to write to them. You'll need to consult the documentation for the object to find out which properties you can safely set.

You can enumerate the properties of an automation object using the normal methods for enumerating hashes, which are keys and each. Here's how you can print the properties and values contained within an object: 

$xl = Win32::OLE->new('Excel.Application', 'Quit'); while( ($key,$value) = each %$xl ) {
 print "$key=$value\n";
}

Win32::OLE Methods

Win32::OLE defines a couple of its own methods for dealing with the automation interface. These are not automation-defined methods, although they look the same. If a given method is not defined in Win32::OLE, the method call is dispatched to the automation object. If the method doesn't exist there, you will get an OLE error.

The following methods are defined by Win32::OLE.

Invoke 
$obj->Invoke(method, args)

This object method calls the given method for $obj with args as arguments. It is useful for invoking methods that would interfere with predefined names in Perl, or methods that contain characters that Perl can't recognize. You can also use Invoke to call an object's default method by using either undef or an empty string ("") as the first argument.

LastError 
Win32::OLE->LastError( )

This class method returns the last OLE error. In a numeric context, the error number is returned, while in a string context, the error message is returned.

QueryObjectType 
Win32::OLE->QueryObjectType($obj)

This class method returns the type of object queried ($obj). In list context, a two-element list of the type library name and the class name of the object is returned. In scalar context, just the class name is returned.

Win32::OLE Functions

The following functions are defined by Win32::OLE. They are not exported by default.

in 
in($coll)

Returns a list of all the members of a collection referenced by the collection object $coll. Same as Win32::OLE::Enum->All( ).

valof 
valof($obj)

Dereferences an automation object ($obj), calls the default method of the object, and returns the value.

with 
with($obj, property1 => value1, ...)

Sets the values of multiple properties on an object ($obj). The function calls $obj->{property}=valuefor each property/value pair.

Win32::OLE Class Variables

The Win32::OLE module defines certain class variables that set default behavior for automation usage:

  • $Win32::OLE::CP
  • Determines the codepage used by all translations between Perl strings and Unicode strings used by the OLE interface. The default value is CP_ACP, which is the default ANSI codepage. It can also be set to CP_OEMCP, which is the default OEM codepage. Both constants are not exported by default.
  • $Win32::OLE::LCID
  • Controls the locale identifier used for all OLE calls. It is set to LOCALE_NEUTRAL by default. Check the Win32 module for other locale-related information.
  • $Win32::OLE::Warn
  • Determines the behavior of the Win32::OLE module when an error happens. Valid values are:
    • Ignores error, returns undef.
    • Uses Carp::carp if $^W is set (-w option).
    • Always uses Carp::carp.
    • Uses Carp::croak.

    The error number and message (without Carp line/module info) are also available through the Win32::OLE->LastError method.