# OLE Automation

Perl for Win32

ActiveWare

# NAME

OLE Automation extensions and Variants

# DESCRIPTION

OLE Automation provides Visual Basic-like scripting capabilities to Perl 5 under Windows NT or Windows 95, exploiting the object-oriented programming facilities of Perl 5.

OCX's are currently not supported.

## Syntax

A simple Microsoft Excel application:

>     use OLE;
>     $excel = CreateObject OLE 'Excel.Application'
>     	or warn "Couldn't create new instance of Excel App!!";
>     $excel->Workbooks->Open( 'test.xls' );
>     $excel->Workbooks(1)->Worksheets('Sheet1')->Cells(1,2)->{Value} = 'foo';
>     $excel->Workbooks(1)->Worksheets('Sheet1')->Cells(1,2)->{Value} = 'bar';
>     $excel->Save(); $excel->Quit();

OLE Automation objects are created using the `CreateObject` method of the `OLE` module. The name of the class of OLE object to create is supplied as the only argument. On success, the handle to the object is returned, otherwise undef is returned.

>     $object = CreateObject OLE $class
>      	or warn "Couldn't create instant of $class!!\n";

To invoke methods or retrieve properties within the object, one then uses the standard Perl 5 O-O syntax. Arguments must be supplied in the correct order (usually in the order that they are listed in the documentation associated with a particular class. e.g. in the help files for Microsoft Excel).

>     $object->wave();
>     $object->say_hello();

Properties are also accessible via the perl object's hash structure. Since the return value of a function cannot be treated as an lvalue, the hash is the only means by which we can modify an object's properties.

>     print "I weigh this many pounds: ", 	$object->{weight}, "\n";
>     	$object->{weight} -= 25;
>     print "Hey, I lost 25 pounds, I now weigh this many pounds: ",
>     	$object->{weight}, "\n";

If a method or a property returns an embedded OLE object, it can automatically be treated as a perl object itself. E.g.

>     $object->dad->grandad->tell_old_war_stories();

...will invoke the method `tell_old_war_stories` in `grandad` which is an embedded object within `dad`, which itself is an embedded object in `$object`. The same goes for properties:

>     print "My girlfriend weighs this many pounds: ",
>     	$object->girlfriend->{weight}, "\n";
>     $object->girlfriend->{weight} -= 25;
>     print "Hey, she lost 25 pounds, she now weigh this many pounds: ",
>     	$object->girlfriend->{weight}, "\n";

Simple as Pie!!

How to get the last OLE error

## Variants

Variants provide a method of ensuring the variant type of parameters passed to OLE objects. The default behavior in the OLE extension is to convert each perl scalar variable into an OLE variant according to the current internal perl representation as such:

> C type | perl | OLE variant
> --- | --- | ---
> int | IV | VT_I4
> double | NV | VT_R8
> char * | PV | VT_BSTR

Note that VT_BSTR is a wide character or Unicode string. This presents a problem if you want to pass in binary data as a parameter as 0x00 is inserted between all the bytes in your data. The OLE::Variant object provides a solution to this. With OLE::Variants the script writer can specify the OLE variant type that the parameter should be converted.

Currently supported types are:

> OLE::VT_UI1 | unsigned character
> OLE::VT_I2 | signed integer (2 bytes in size)
> OLE::VT_I4 | signed integer (4 bytes in size)
> OLE::VT_R4 | floating point (4 bytes in size)
> OLE::VT_R8 | floating point (8 bytes in size)
> OLE::VT_DATE | OLE Date
> OLE::VT_BSTR | OLE string
> OLE::VT_CY | OLE currency
> OLE::VT_BOOL | OLE boolean

When OLE::VT_DATE and OLE::VT_CY objects are are created, the input parameter is treated as a Perl String, it is then converted to a VT_BSTR and finally converted to VT_DATE or VT_CY with the OLE VariantChangeType function.

So as an example:

>     use OLE;
>     $ExcelApp = CreateObject OLE "excel.application"
>     	|| die "Unable to create Excel Object: \n";
>     $ExcelApp->{'Visible'} = 1;
>     $ExcelApp->Workbooks->Add();
>     $ovR8 = new OLE::Variant(OLE::VT_R8, '3 is a good number');
>     $ExcelApp->Range("a1")->{'Value'} = $ovR8;
>     $ExcelApp->Range("a2")->{'Value'}
>     	= new OLE::Variant(OLE::VT_DATE,  'May 28, 1963');

This will put the value '3' in cell A1 rather than the string '3 is a good number'. Cell A2 will contain my birthday. The temporary OLE::VT_DATE object will be destroyed after the assignment statement.

For binary data store the data in a Perl string and create a VT_UI1 Variant type:

>     $binaryString = 'some binary data';
>     $ovBinParam = new OLE::Variant(OLE::VT_UI1, $binaryString);
>     $object->Method($ovBinParam);

> Perl for Win32

> ActiveWare