Chip 2000 May

home *** CD-ROM | disk | FTP | other *** search

/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _a0f0936077f96f30a30ea37d46f61bf5 < prev next >

Wrap

Text File | 2000-03-23 | 40KB | 788 lines

<HTML> <HEAD> <TITLE>Win32::OLE - OLE Automation extensions</TITLE> <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css"> <LINK REV="made" HREF="mailto:"> </HEAD> <BODY> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> Win32::OLE - OLE Automation extensions </TD></TR> </TABLE> <A NAME="__index__"></A>  <UL> <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI> <LI><A HREF="#synopsis">SYNOPSIS</A></LI> <LI><A HREF="#description">DESCRIPTION</A></LI> <UL> <LI><A HREF="#methods">Methods</A></LI> <LI><A HREF="#object methods and properties">Object methods and properties</A></LI> <LI><A HREF="#functions">Functions</A></LI> <LI><A HREF="#overloading">Overloading</A></LI> <LI><A HREF="#events">Events</A></LI> <LI><A HREF="#module options">Module Options</A></LI> </UL> <LI><A HREF="#examples">EXAMPLES</A></LI> <LI><A HREF="#notes">NOTES</A></LI> <UL> <LI><A HREF="#hints for microsoft office automation">Hints for Microsoft Office automation</A></LI> <LI><A HREF="#incompatibilities">Incompatibilities</A></LI> <LI><A HREF="#bugs and limitations">Bugs and Limitations</A></LI> </UL> <LI><A HREF="#see also">SEE ALSO</A></LI> <LI><A HREF="#authors">AUTHORS</A></LI> <LI><A HREF="#copyright">COPYRIGHT</A></LI> <LI><A HREF="#version">VERSION</A></LI> </UL>  <HR> <H1><A NAME="name">NAME</A></H1> Win32::OLE - OLE Automation extensions <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> <PRE> $ex = Win32::OLE->new('Excel.Application') or die "oops\n"; $ex->Amethod("arg")->Bmethod->{'Property'} = "foo"; $ex->Cmethod(undef,undef,$Arg3); $ex->Dmethod($RequiredArg1, {NamedArg1 => $Value1, NamedArg2 => $Value2});</PRE> <PRE> $wd = Win32::OLE->GetObject("D:\\Data\\Message.doc"); $xl = Win32::OLE->GetActiveObject("Excel.Application");</PRE> <HR> <H1><A NAME="description">DESCRIPTION</A></H1> This module provides an interface to OLE Automation from Perl. OLE Automation brings VisualBasic like scripting capabilities and offers powerful extensibility and the ability to control many Win32 applications from Perl scripts. The Win32::OLE module uses the IDispatch interface exclusively. It is not possible to access a custom OLE interface. OLE events and OCX's are currently not supported. Actually, that's no longer strictly true. This module now contains ALPHA level support for OLE events. This is largely untested and the specific interface might still change in the future. <H2><A NAME="methods">Methods</A></H2> <DL> <DT><A NAME="item_new">Win32::OLE->new(PROGID[, DESTRUCTOR])</A> <DD> The <A HREF="#item_new"><CODE>new()</CODE></A> class method starts a new instance of an OLE Automation object. It returns a reference to this object or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if the creation failed. The PROGID argument must be either the OLE program id or the class id of the required application. The optional DESTRUCTOR specifies a DESTROY-like method. This can be either a CODE reference or a string containing an OLE method name. It can be used to cleanly terminate OLE applications in case the Perl program dies. To create an object via DCOM on a remote server you can use an array reference in place of PROGID. The referenced array must contain the machine name and the program id or class id. For example: <PRE> my $obj = Win32::OLE->new(['my.machine.com', 'Program.Id']);</PRE> If the PROGID is a program id then Win32::OLE will try to resolve the corresponding class id locally. If the program id is not registered locally then the remote registry is queried. This will only succeed if the local process has read access to the remote registry. The safest (and fastest) method is to specify the <CODE>class id</CODE> directly. <DT><A NAME="item_EnumAllObjects">Win32::OLE-><CODE>EnumAllObjects([CALLBACK])</CODE></A> <DD> This class method returns the number Win32::OLE objects currently in existance. It will call the optional CALLBACK function for each of these objects: <PRE> $Count = Win32::OLE->EnumAllObjects(sub { my $Object = shift; my $Class = Win32::OLE->QueryObjectType($Object); printf "# Object=%s Class=%s\n", $Object, $Class; });</PRE> The <A HREF="#item_EnumAllObjects"><CODE>EnumAllObjects()</CODE></A> method is primarily a debugging tool. It can be used e.g. in an END block to check if all external connections have been properly destroyed. <DT><A NAME="item_GetActiveObject">Win32::OLE->GetActiveObject(CLASS[, DESTRUCTOR])</A> <DD> The <A HREF="#item_GetActiveObject"><CODE>GetActiveObject()</CODE></A> class method returns an OLE reference to a running instance of the specified OLE automation server. It returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if the server is not currently active. It will croak if the class is not even registered. The optional DESTRUCTOR method takes either a method name or a code reference. It is executed when the last reference to this object goes away. It is generally considered <CODE>impolite</CODE> to stop applications that you did not start yourself. <DT><A NAME="item_GetObject">Win32::OLE->GetObject(MONIKER[, DESTRUCTOR])</A> <DD> The <A HREF="#item_GetObject"><CODE>GetObject()</CODE></A> class method returns an OLE reference to the specified object. The object is specified by a pathname optionally followed by additional item subcomponent separated by exclamation marks '!'. The optional DESTRUCTOR argument has the same semantics as the DESTRUCTOR in <A HREF="#item_new"><CODE>new()</CODE></A> or GetActiveObject(). <DT><A NAME="item_Initialize">Win32::OLE-><CODE>Initialize([COINIT])</CODE></A> <DD> The <A HREF="#item_Initialize"><CODE>Initialize()</CODE></A> class method can be used to specify an alternative apartment model for the Perl thread. It must be called before the first OLE object is created. If the <CODE>Win32::OLE::Const</CODE> module is used then the call to the <A HREF="#item_Initialize"><CODE>Initialize()</CODE></A> method must be made from a BEGIN block before the first <A HREF="../../../lib/Pod/perlfunc.html#item_use"><CODE>use</CODE></A> statement for the <CODE>Win32::OLE::Const</CODE> module. Valid values for COINIT are: <PRE> Win32::OLE::COINIT_APARTMENTTHREADED - single threaded Win32::OLE::COINIT_MULTITHREADED - the default Win32::OLE::COINIT_OLEINITIALIZE - single threaded, additional OLE stuff</PRE> COINIT_OLEINITIALIZE is sometimes needed when an OLE object uses additional OLE compound document technologies not available from the normal COM subsystem (for example MAPI.Session seems to require it). Both COINIT_OLEINITIALIZE and COINIT_APARTMENTTHREADED create a hidden top level window and a message queue for the Perl process. This may create problems with other application, because Perl normally doesn't process its message queue. This means programs using synchronous communication between applications (such as DDE initiation), may hang until Perl makes another OLE method call/property access or terminates. This applies to InstallShield setups and many things started to shell associations. Please try to utilize the <A HREF="#item_SpinMessageLoop"><CODE>Win32::OLE->SpinMessageLoop</CODE></A> and <A HREF="#item_Uninitialize"><CODE>Win32::OLE->Uninitialize</CODE></A> methods if you can not use the default COINIT_MULTITHREADED model. <DT><A NAME="item_Invoke">OBJECT->Invoke(METHOD[, ARGS])</A> <DD> The <A HREF="#item_Invoke"><CODE>Invoke()</CODE></A> object method is an alternate way to invoke OLE methods. It is normally equivalent to <CODE>$OBJECT-</CODE>METHOD(@ARGS)>. This function must be used if the METHOD name contains characters not valid in a Perl variable name (like foreign language characters). It can also be used to invoke the default method of an object even if the default method has not been given a name in the type library. In this case use <undef> or <CODE>''</CODE> as the method name. To invoke an OLE objects native <A HREF="#item_Invoke"><CODE>Invoke()</CODE></A> method (if such a thing exists), please use: <PRE> $Object->Invoke('Invoke', @Args);</PRE> <DT><A NAME="item_LastError">Win32::OLE-><CODE>LastError()</CODE></A> <DD> The <A HREF="#item_LastError"><CODE>LastError()</CODE></A> class method returns the last recorded OLE error. This is a dual value like the <CODE>$!</CODE> variable: in a numeric context it returns the error number and in a string context it returns the error message. The error number is a signed HRESULT value. Please use the <A HREF="#item_HRESULT">HRESULT(ERROR)</A> function to convert an unsigned hexadecimal constant to a signed HRESULT. The last OLE error is automatically reset by a successful OLE call. The numeric value can also explicitly be set by a call (which will discard the string value): <PRE> Win32::OLE->LastError(0);</PRE> <DT><A NAME="item_LetProperty">OBJECT-><CODE>LetProperty(NAME,ARGS,VALUE)</CODE></A> <DD> In Win32::OLE property assignment using the hash syntax is equivalent to the Visual Basic <CODE>Set</CODE> syntax (by reference assignment): <PRE> $Object->{Property} = $OtherObject;</PRE> corresponds to this Visual Basic statement: <PRE> Set Object.Property = OtherObject</PRE> To get the by value treatment of the Visual Basic <CODE>Let</CODE> statement <PRE> Object.Property = OtherObject</PRE> you have to use the <A HREF="#item_LetProperty"><CODE>LetProperty()</CODE></A> object method in Perl: <PRE> $Object->LetProperty($Property, $OtherObject);</PRE> <A HREF="#item_LetProperty"><CODE>LetProperty()</CODE></A> also supports optional arguments for the property assignment. See OBJECT-SetProperty(NAME,ARGS,VALUE)> for details. <DT><A NAME="item_Option">Win32::OLE-><CODE>Option(OPTION)</CODE></A> <DD> The <A HREF="#item_Option"><CODE>Option()</CODE></A> class method can be used to inspect and modify <A HREF="#module options">Module Options</A>. The single argument form retrieves the value of an option: <PRE> my $CP = Win32::OLE->Option('CP');</PRE> A single call can be used to set multiple options simultaneously: <PRE> Win32::OLE->Option(CP => CP_ACP, Warn => 3);</PRE> <DT><A NAME="item_QueryObjectType">Win32::OLE-><CODE>QueryObjectType(OBJECT)</CODE></A> <DD> The <A HREF="#item_QueryObjectType"><CODE>QueryObjectType()</CODE></A> class method returns a list of the type library name and the objects class name. In a scalar context it returns the class name only. It returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> when the type information is not available. <DT><A NAME="item_SetProperty">OBJECT-><CODE>SetProperty(NAME,ARGS,VALUE)</CODE></A> <DD> The <A HREF="#item_SetProperty"><CODE>SetProperty()</CODE></A> method allows to modify properties with arguments, which is not supported by the hash syntax. The hash form <PRE> $Object->{Property} = $Value;</PRE> is equivalent to <PRE> $Object->SetProperty('Property', $Value);</PRE> Arguments must be specified between the property name and the new value: <PRE> $Object->SetProperty('Property', @Args, $Value);</PRE> It is not possible to use ``named argument'' syntax with this function because the new value must be the last argument to SetProperty(). This method hides any native OLE object method called SetProperty(). The native method will still be available through the <A HREF="#item_Invoke"><CODE>Invoke()</CODE></A> method: <PRE> $Object->Invoke('SetProperty', @Args);</PRE> <DT><A NAME="item_SpinMessageLoop">Win32::OLE->SpinMessageLoop</A> <DD> This class method retrieves all pending messages from the message queue and dispatches them to their respective window procedures. Calling this method is only necessary when not using the COINIT_MULTITHREADED model. All OLE method calls and property accesses automatically process the message queue. <DT><A NAME="item_Uninitialize">Win32::OLE->Uninitialize</A> <DD> The <A HREF="#item_Uninitialize"><CODE>Uninitialize()</CODE></A> class method uninitializes the OLE subsystem. It also destroys the hidden top level window created by OLE for single threaded apartments. All OLE objects will become invalid after this call! It is possible to call the <A HREF="#item_Initialize"><CODE>Initialize()</CODE></A> class method again with a different apartment model after shutting down OLE with Uninitialize(). <DT><A NAME="item_WithEvents">Win32::OLE->WithEvents(OBJECT[, HANDLER[, INTERFACE]])</A> <DD> This class method enables and disables the firing of events by the specified OBJECT. If no HANDLER is specified, then events are disconnected. For some objects Win32::OLE is not able to automatically determine the correct event interface. In this case the INTERFACE argument must contain either the COCLASS name of the OBJECT or the name of the event DISPATCH interface. Please read the Events section below for detailed explanation of the Win32::OLE event support. </DL> Whenever Perl does not find a method name in the Win32::OLE package it is automatically used as the name of an OLE method and this method call is dispatched to the OLE server. There is one special hack built into the module: If a method or property name could not be resolved with the OLE object, then the default method of the object is called with the method name as its first parameter. So <PRE> my $Sheet = $Worksheets->Table1; or my $Sheet = $Worksheets->{Table1};</PRE> is resolved as <PRE> my $Sheet = $Worksheet->Item('Table1');</PRE> provided that the $Worksheets object doesnot have a <CODE>Table1</CODE> method or property. This hack has been introduced to call the default method of collections which did not name the method in their type library. The recommended way to call the ``unnamed'' default method is: <PRE> my $Sheet = $Worksheets->Invoke('', 'Table1');</PRE> This special hack is disabled under <CODE>use strict 'subs';</CODE>. <H2><A NAME="object methods and properties">Object methods and properties</A></H2> The object returned by the <A HREF="#item_new"><CODE>new()</CODE></A> method can be used to invoke methods or retrieve properties in the same fashion as described in the documentation for the particular OLE class (eg. Microsoft Excel documentation describes the object hierarchy along with the properties and methods exposed for OLE access). Optional parameters on method calls can be omitted by using <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> as a placeholder. A better way is to use named arguments, as the order of optional parameters may change in later versions of the OLE server application. Named parameters can be specified in a reference to a hash as the last parameter to a method call. Properties can be retrieved or set using hash syntax, while methods can be invoked with the usual perl method call syntax. The <A HREF="../../../lib/Pod/perlfunc.html#item_keys"><CODE>keys</CODE></A> and <A HREF="../../../lib/Pod/perlfunc.html#item_each"><CODE>each</CODE></A> functions can be used to enumerate an object's properties. Beware that a property is not always writable or even readable (sometimes raising exceptions when read while being undefined). If a method or property returns an embedded OLE object, method and property access can be chained as shown in the examples below. <H2><A NAME="functions">Functions</A></H2> The following functions are not exported by default. <DL> <DT><A NAME="item_HRESULT"><CODE>HRESULT(ERROR)</CODE></A> <DD> The <A HREF="#item_HRESULT"><CODE>HRESULT()</CODE></A> function converts an unsigned number into a signed HRESULT error value as used by OLE internally. This is necessary because Perl treats all hexadecimal constants as unsigned. To check if the last OLE function returned ``Member not found'' (0x80020003) you can write: <PRE> if (Win32::OLE->LastError == HRESULT(0x80020003)) { # your error recovery here }</PRE> <DT><A NAME="item_in"><CODE>in(COLLECTION)</CODE></A> <DD> If COLLECTION is an OLE collection object then <CODE>in $COLLECTION</CODE> returns a list of all members of the collection. This is a shortcut for <CODE>Win32::OLE::Enum-</CODE>All($COLLECTION)>. It is most commonly used in a <CODE>foreach</CODE> loop: <PRE> foreach my $value (in $collection) { # do something with $value here }</PRE> <DT><A NAME="item_valof"><CODE>valof(OBJECT)</CODE></A> <DD> Normal assignment of Perl OLE objects creates just another reference to the OLE object. The <A HREF="#item_valof"><CODE>valof()</CODE></A> function explictly dereferences the object (through the default method) and returns the value of the object. <PRE> my $RefOf = $Object; my $ValOf = valof $Object; $Object->{Value} = $NewValue;</PRE> Now $ValOf still contains the old value wheras $RefOf would resolve to the $NewValue because it is still a reference to $Object. The <A HREF="#item_valof"><CODE>valof()</CODE></A> function can also be used to convert Win32::OLE::Variant objects to Perl values. <DT><A NAME="item_with">with(OBJECT, PROPERTYNAME => VALUE, ...)</A> <DD> This function provides a concise way to set the values of multiple properties of an object. It iterates over its arguments doing <CODE>$OBJECT-</CODE>{PROPERTYNAME} = $VALUE> on each trailing pair. </DL> <H2><A NAME="overloading">Overloading</A></H2> The Win32::OLE objects can be overloaded to automatically convert to their values whenever they are used in a bool, numeric or string context. This is not enabled by default. You have to request it through the OVERLOAD pseudoexport: <PRE> use Win32::OLE qw(in valof with OVERLOAD);</PRE> You can still get the original string representation of an object (<CODE>Win32::OLE=0xDEADBEEF</CODE>), e.g. for debugging, by using the <CODE>overload::StrVal()</CODE> method: <PRE> print overload::StrVal($object), "\n";</PRE> Please note that <CODE>OVERLOAD</CODE> is a global setting. If any module enables Win32::OLE overloading then it's active everywhere. <H2><A NAME="events">Events</A></H2> The Win32::OLE module now contains ALPHA level event support. This support is only available when Perl is running in a single threaded apartment. This can most easily be assured by using the <CODE>EVENTS</CODE> pseudo-import: <PRE> use Win32::OLE qw(EVENTS);</PRE> which implicitly does something like: <PRE> use Win32::OLE; Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE);</PRE> The current interface to OLE events should be considered experimental and is subject to change. It works as expected for normal OLE applications, but OLE control events often don't seem to work yet. Events must be enabled explicitly for an OLE object through the Win32::OLE-><A HREF="#item_WithEvents"><CODE>WithEvents()</CODE></A> class method. The Win32::OLE module uses the IProvideClassInfo2 interface to determine the default event source of the object. If this interface is not supported, then the user must specify the name of the event source explicitly in the <A HREF="#item_WithEvents"><CODE>WithEvents()</CODE></A> method call. It is also possible to specify the class name of the object as the third parameter. In this case Win32::OLE will try to look up the default source interface for this COCLASS. The HANDLER argument to Win32::OLE-><A HREF="#item_WithEvents"><CODE>WithEvents()</CODE></A> can either be a CODE reference or a package name. In the first case, all events will invoke this particular function. The first two arguments to this function will be the OBJECT itself and the name of the event. The remaining arguments will be event specific. <PRE> sub Event { my ($Obj,$Event,@Args) = @_; print "Event triggered: '$Event'\n"; } Win32::OLE->WithEvents($Obj, \&Event);</PRE> Alternatively the HANDLER argument can specify a package name. When the OBJECT fires an event, Win32::OLE will try to find a function of the same name as the event in this package. This function will be called with the OBJECT as the first argument followed again by the event specific parameters: <PRE> package MyEvents; sub EventName1 { my ($Obj,@Args) = @_; print "EventName1 event triggered\n"; }</PRE> <PRE> package main; Win32::OLE->WithEvents($Obj, 'MyEvents', 'IEventInterface');</PRE> If Win32::OLE doesn't find a function with the name of the event then nothing happens. Event parameters passed by reference are handled specially. They are not converted to the corresponding Perl datatype but passed as Win32::OLE::Variant objects. You can assign a new value to these objects with the help of the <CODE>Put()</CODE> method. This value will be passed back to the object when the event function returns: <PRE> package MyEvents; sub BeforeClose { my ($self,$Cancel) = @_; $Cancel->Put(1) unless $MayClose; }</PRE> Direct assignment to $Cancel would have no effect on the original value and would therefore not command the object to abort the closing action. <H2><A NAME="module options">Module Options</A></H2> The following module options can be accessed and modified with the <CODE>Win32::OLE-</CODE>Option> class method. In earlier versions of the Win32::OLE module these options were manipulated directly as class variables. This practice is now deprecated. <DL> <DT><A NAME="item_CP">CP</A> <DD> This variable is used to determine 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. Other possible values are CP_OEMCP, CP_MACCP, CP_UTF7 and CP_UTF8. These constants are not exported by default. <DT><A NAME="item_LCID">LCID</A> <DD> This variable controls the locale idnetifier used for all OLE calls. It is set to LOCALE_NEUTRAL by default. Please check the <A HREF="../../../site/lib/Win32/OLE/NLS.html">the Win32::OLE::NLS manpage</A> module for other locale related information. <DT><A NAME="item_Warn">Warn</A> <DD> This variable determines the behavior of the Win32::OLE module when an error happens. Valid values are: <PRE> 0 Ignore error, return undef 1 Carp::carp if $^W is set (-w option) 2 always Carp::carp 3 Carp::croak</PRE> The error number and message (without Carp line/module info) are available through the <CODE>Win32::OLE-</CODE>LastError> class method. </DL> <HR> <H1><A NAME="examples">EXAMPLES</A></H1> Here is a simple Microsoft Excel application. <PRE> use Win32::OLE;</PRE> <PRE> # use existing instance if Excel is already running eval {$ex = Win32::OLE->GetActiveObject('Excel.Application')}; die "Excel not installed" if $@; unless (defined $ex) { $ex = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;}) or die "Oops, cannot start Excel"; }</PRE> <PRE> # get a new workbook $book = $ex->Workbooks->Add;</PRE> <PRE> # write to a particular cell $sheet = $book->Worksheets(1); $sheet->Cells(1,1)->{Value} = "foo";</PRE> <PRE> # write a 2 rows by 3 columns range $sheet->Range("A8:C9")->{Value} = [[ undef, 'Xyzzy', 'Plugh' ], [ 42, 'Perl', 3.1415 ]];</PRE> <PRE> # print "XyzzyPerl" $array = $sheet->Range("A8:C9")->{Value}; for (@$array) { for (@$_) { print defined($_) ? "$_|" : "<undef>|"; } print "\n"; }</PRE> <PRE> # save and exit $book->SaveAs( 'test.xls' ); undef $book; undef $ex;</PRE> Please note the destructor specified on the Win32::OLE->new method. It ensures that Excel will shutdown properly even if the Perl program dies. Otherwise there could be a process leak if your application dies after having opened an OLE instance of Excel. It is the responsibility of the module user to make sure that all OLE objects are cleaned up properly! Here is an example of using Variant data types. <PRE> use Win32::OLE; use Win32::OLE::Variant; $ex = Win32::OLE->new('Excel.Application', \&OleQuit) or die "oops\n"; $ex->{Visible} = 1; $ex->Workbooks->Add; # should generate a warning under -w $ovR8 = Variant(VT_R8, "3 is a good number"); $ex->Range("A1")->{Value} = $ovR8; $ex->Range("A2")->{Value} = Variant(VT_DATE, 'Jan 1,1970');</PRE> <PRE> sub OleQuit { my $self = shift; $self->Quit; }</PRE> The above will put value ``3'' in cell A1 rather than the string ``3 is a good number''. Cell A2 will contain the date. Similarly, to invoke a method with some binary data, you can do the following: <PRE> $obj->Method( Variant(VT_UI1, "foo\000b\001a\002r") );</PRE> Here is a wrapper class that basically delegates everything but <A HREF="#item_new"><CODE>new()</CODE></A> and DESTROY(). The wrapper class shown here is another way to properly shut down connections if your application is liable to die without proper cleanup. Your own wrappers will probably do something more specific to the particular OLE object you may be dealing with, like overriding the methods that you may wish to enhance with your own. <PRE> package Excel; use Win32::OLE;</PRE> <PRE> sub new { my $s = {}; if ($s->{Ex} = Win32::OLE->new('Excel.Application')) { return bless $s, shift; } return undef; }</PRE> <PRE> sub DESTROY { my $s = shift; if (exists $s->{Ex}) { print "# closing connection\n"; $s->{Ex}->Quit; return undef; } }</PRE> <PRE> sub AUTOLOAD { my $s = shift; $AUTOLOAD =~ s/^.*:://; $s->{Ex}->$AUTOLOAD(@_); }</PRE> <PRE> 1;</PRE> The above module can be used just like Win32::OLE, except that it takes care of closing connections in case of abnormal exits. Note that the effect of this specific example can be easier accomplished using the optional destructor argument of Win32::OLE::new: <PRE> my $Excel = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;});</PRE> Note that the delegation shown in the earlier example is not the same as true subclassing with respect to further inheritance of method calls in your specialized object. See <A HREF="../../../lib/Pod/perlobj.html">the perlobj manpage</A>, <A HREF="../../../lib/Pod/perltoot.html">the perltoot manpage</A> and <A HREF="../../../lib/Pod/perlbot.html">the perlbot manpage</A> for details. True subclassing (available by setting <CODE>@ISA</CODE>) is also feasible, as the following example demonstrates: <PRE> # # Add error reporting to Win32::OLE #</PRE> <PRE> package Win32::OLE::Strict; use Carp; use Win32::OLE;</PRE> <PRE> use strict qw(vars); use vars qw($AUTOLOAD @ISA); @ISA = qw(Win32::OLE);</PRE> <PRE> sub AUTOLOAD { my $obj = shift; $AUTOLOAD =~ s/^.*:://; my $meth = $AUTOLOAD; $AUTOLOAD = "SUPER::" . $AUTOLOAD; my $retval = $obj->$AUTOLOAD(@_); unless (defined($retval) || $AUTOLOAD eq 'DESTROY') { my $err = Win32::OLE::LastError(); croak(sprintf("$meth returned OLE error 0x%08x",$err)) if $err; } return $retval; }</PRE> <PRE> 1;</PRE> This package inherits the constructor <A HREF="#item_new"><CODE>new()</CODE></A> from the Win32::OLE package. It is important to note that you cannot later rebless a Win32::OLE object as some information about the package is cached by the object. Always invoke the <A HREF="#item_new"><CODE>new()</CODE></A> constructor through the right package! Here's how the above class will be used: <PRE> use Win32::OLE::Strict; my $Excel = Win32::OLE::Strict->new('Excel.Application', 'Quit'); my $Books = $Excel->Workbooks; $Books->UnknownMethod(42);</PRE> In the sample above the call to <CODE>UnknownMethod()</CODE> will be caught with <PRE> UnknownMethod returned OLE error 0x80020009 at test.pl line 5</PRE> because the Workbooks object inherits the class <CODE>Win32::OLE::Strict</CODE> from the <CODE>$Excel</CODE> object. <HR> <H1><A NAME="notes">NOTES</A></H1> <H2><A NAME="hints for microsoft office automation">Hints for Microsoft Office automation</A></H2> <DL> <DT><A NAME="item_Documentation">Documentation</A> <DD> The object model for the Office applications is defined in the Visual Basic reference guides for the various applications. These are typically not installed by default during the standard installation. They can be added later by rerunning the setup program with the custom install option. <DT><A NAME="item_Class%2C_Method_and_Property_names">Class, Method and Property names</A> <DD> The names have been changed between different versions of Office. For example <CODE>Application</CODE> was a method in Office 95 and is a property in Office97. Therefore it will not show up in the list of property names <CODE>keys %$object</CODE> when querying an Office 95 object. The class names are not always identical to the method/property names producing the object. E.g. the <CODE>Workbook</CODE> method returns an object of type <CODE>Workbook</CODE> in Office 95 and <CODE>_Workbook</CODE> in Office 97. <DT><A NAME="item_Moniker">Moniker (GetObject support)</A> <DD> Office applications seem to implement file monikers only. For example it seems to be impossible to retrieve a specific worksheet object through <A HREF="#item_GetObject"><CODE>GetObject("File.XLS!Sheet")</CODE></A>. Furthermore, in Excel 95 the moniker starts a Worksheet object and in Excel 97 it returns a Workbook object. You can use either the Win32::OLE::QueryObjectType class method or the $object->{Version} property to write portable code. <DT><A NAME="item_Enumeration_of_collection_objects">Enumeration of collection objects</A> <DD> Enumerations seem to be incompletely implemented. Office 95 application don't seem to support neither the <CODE>Reset()</CODE> nor the <CODE>Clone()</CODE> methods. The <CODE>Clone()</CODE> method is still unimplemented in Office 97. A single walk through the collection similar to Visual Basics <CODE>for each</CODE> construct does work however. <DT><A NAME="item_Localization">Localization</A> <DD> Starting with Office 97 Microsoft has changed the localized class, method and property names back into English. Note that string, date and currency arguments are still subject to locale specific interpretation. Perl uses the system default locale for all OLE transaction whereas Visual Basic uses a type library specific locale. A Visual Basic script would use ``R1C1'' in string arguments to specify relative references. A Perl script running on a German language Windows would have to use ``Z1S1''. Set the LCID module option to an English locale to write portable scripts. This variable should not be changed after creating the OLE objects; some methods seem to randomly fail if the locale is changed on the fly. <DT><A NAME="item_SaveAs_method_in_Word_97_doesn%27t_work">SaveAs method in Word 97 doesn't work</A> <DD> This is an known bug in Word 97. Search the MS knowledge base for Word / Foxpro incompatibility. That problem applies to the Perl OLE interface as well. A workaround is to use the WordBasic compatibility object. It doesn't support all the options of the native method though. <PRE> $Word->WordBasic->FileSaveAs($file);</PRE> The problem seems to be fixed by applying the Office 97 Service Release 1. <DT><A NAME="item_Randomly_failing_method_calls">Randomly failing method calls</A> <DD> It seems like modifying objects that are not selected/activated is sometimes fragile. Most of these problems go away if the chart/sheet/document is selected or activated before being manipulated (just like an interactive user would automatically do it). </DL> <H2><A NAME="incompatibilities">Incompatibilities</A></H2> There are some incompatibilities with the version distributed by Activeware (as of build 306). <OL> <LI> The package name has changed from ``OLE'' to ``Win32::OLE''. <LI> All functions of the form ``Win32::OLEFoo'' are now ``Win32::OLE::Foo'', though the old names are temporarily accomodated. Win32::OLECreateObject() was changed to Win32::OLE::CreateObject(), and is now called Win32::OLE::new() bowing to established convention for naming constructors. The old names should be considered deprecated, and will be removed in the next version. <LI> Package ``OLE::Variant'' is now ``Win32::OLE::Variant''. <LI> The Variant function is new, and is exported by default. So are all the VT_XXX type constants. <LI> The support for collection objects has been moved into the package Win32::OLE::Enum. The <CODE>keys %$object</CODE> method is now used to enumerate the properties of the object. </OL> <H2><A NAME="bugs and limitations">Bugs and Limitations</A></H2> <UL> <LI> To invoke a native OLE method with the same name as one of the Win32::OLE methods (<CODE>Dispatch</CODE>, <A HREF="#item_Invoke"><CODE>Invoke</CODE></A>, <A HREF="#item_SetProperty"><CODE>SetProperty</CODE></A>, <CODE>DESTROY</CODE>, etc.), you have to use the <A HREF="#item_Invoke"><CODE>Invoke</CODE></A> method: <PRE> $Object->Invoke('Dispatch', @AdditionalArgs);</PRE> The same is true for names exported by the Exporter or the Dynaloader modules, e.g.: <CODE>export</CODE>, <CODE>export_to_level</CODE>, <A HREF="../../../lib/Pod/perlfunc.html#item_import"><CODE>import</CODE></A>, <CODE>_push_tags</CODE>, <CODE>export_tags</CODE>, <CODE>export_ok_tags</CODE>, <CODE>export_fail</CODE>, <CODE>require_version</CODE>, <CODE>dl_load_flags</CODE>, <CODE>croak</CODE>, <CODE>bootstrap</CODE>, <CODE>dl_findfile</CODE>, <CODE>dl_expandspec</CODE>, <CODE>dl_find_symbol_anywhere</CODE>, <CODE>dl_load_file</CODE>, <CODE>dl_find_symbol</CODE>, <CODE>dl_undef_symbols</CODE>, <CODE>dl_install_xsub</CODE> and <CODE>dl_error</CODE>. </UL> <HR> <H1><A NAME="see also">SEE ALSO</A></H1> The documentation for <A HREF="../../../site/lib/Win32/OLE/Const.html">the Win32::OLE::Const manpage</A>, <A HREF="../../../site/lib/Win32/OLE/Enum.html">the Win32::OLE::Enum manpage</A>, <A HREF="../../../site/lib/Win32/OLE/NLS.html">the Win32::OLE::NLS manpage</A> and <A HREF="../../../site/lib/Win32/OLE/Variant.html">the Win32::OLE::Variant manpage</A> contains additional information about OLE support for Perl on Win32. <HR> <H1><A NAME="authors">AUTHORS</A></H1> Originally put together by the kind people at Hip and Activeware. Gurusamy Sarathy <<A HREF="mailto:gsar@activestate.com">gsar@activestate.com</A>> subsequently fixed several major bugs, memory leaks, and reliability problems, along with some redesign of the code. Jan Dubois <<A HREF="mailto:jand@activestate.com">jand@activestate.com</A>> pitched in with yet more massive redesign, added support for named parameters, and other significant enhancements. He's been hacking on it ever since. Please send questions about problems with this module to the Perl-Win32-Users mailinglist at ActiveState.com. The mailinglist charter requests that you put an [OLE] tag somewhere on the subject line (for OLE related questions only, of course). <HR> <H1><A NAME="copyright">COPYRIGHT</A></H1> <PRE> (c) 1995 Microsoft Corporation. All rights reserved. Developed by ActiveWare Internet Corp., now known as ActiveState Tool Corp., <A HREF="http://www.ActiveState.com">http://www.ActiveState.com</A></PRE> <PRE> Other modifications Copyright (c) 1997-1999 by Gurusamy Sarathy <gsar@activestate.com> and Jan Dubois <jand@activestate.com></PRE> <PRE> You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the README file.</PRE> <HR> <H1><A NAME="version">VERSION</A></H1> Version 0.1101 24 September 1999 <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> Win32::OLE - OLE Automation extensions </TD></TR> </TABLE> </BODY> </HTML>