Automation Methods and Properties (Perl in a Nutshell, 2nd Edition)

23.2. 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 WorkBook in Excel with SaveAs. Additional settings allow you to add the WorkBook 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";
}

23.2.3. 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:

0: Ignores error, returns undef.
1: Uses Carp::carp if $^W is set (-w option).
2: Always uses Carp::carp.
3: Uses Carp::croak.

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

23.2. Automation Methods and Properties

23.2.1. Win32::OLE Methods

23.2.2. Win32::OLE Functions

23.2.3. Win32::OLE Class Variables