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!!

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