The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
libwin32-0.05
River stage zero No dependents
/ Win32::OLE

NAME

Win32::OLE - OLE Automation extensions and Variants

SYNOPSIS

        $ex = new Win32::OLE 'Excel.Application' or die "oops\n";
        $ex->Amethod("arg")->Bmethod->{'Property'} = "foo";

DESCRIPTION

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.

OCX's are currently not supported.

Functions/Methods

new Win32::OLE $oleclass

OLE Automation objects are created using the new() method, the second argument to which must be the OLE class of the application to create. Return value is undef if the attempt to create an OLE connection failed for some reason.

The object returned by the new() 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).

Properties can be retrieved or set using hash syntax, while methods can be invoked with the usual perl method call syntax.

If a method or property returns an embedded OLE object, method and property access can be chained as shown in the examples below.

Variant(TYPENAME, DATA)

This function returns a Win32::OLE::Variant object of the specified type that contains the given data. The Win32::OLE::Variant object can be used to specify data types other than IV, NV or PV (which are supported transparently). See Variants below for details.

Constants

These constants are exported by default:

        VT_UI1
        VT_I2
        VT_I4
        VT_R4
        VT_R8
        VT_DATE
        VT_BSTR
        VT_CY
        VT_BOOL

Other OLE constants are also defined in the Win32::OLE package, but they are unsupported at this time, so they are exported only on request:

        VT_EMPTY
        VT_NULL
        VT_DISPATCH
        VT_ERROR
        VT_VARIANT
        VT_UNKNOWN
        VT_UI2
        VT_UI4
        VT_I8
        VT_UI8
        VT_INT
        VT_UINT
        VT_VOID
        VT_HRESULT
        VT_PTR
        VT_SAFEARRAY
        VT_CARRAY
        VT_USERDEFINED
        VT_LPSTR
        VT_LPWSTR
        VT_FILETIME
        VT_BLOB
        VT_STREAM
        VT_STORAGE
        VT_STREAMED_OBJECT
        VT_STORED_OBJECT
        VT_BLOB_OBJECT
        VT_CF
        VT_CLSID

Variants

A Variant is a data type that is used to pass data between OLE connections.

The default behavior is to convert each perl scalar variable into an OLE Variant according to the internal perl representation. The following type correspondence holds:

        C type          Perl type       OLE type
        ------          ---------       --------
          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 Variant() method provides a solution to this. With Variants the script writer can specify the OLE variant type that the parameter should be converted to. Currently supported types are:

        VT_UI1     unsigned char
        VT_I2      signed int (2 bytes)
        VT_I4      signed int (4 bytes)
        VT_R4      float      (4 bytes)
        VT_R8      float      (8 bytes)
        VT_DATE    OLE Date
        VT_BSTR    OLE String
        VT_CY      OLE Currency
        VT_BOOL    OLE Boolean

When VT_DATE and VT_CY objects are created, the input parameter is treated as a Perl string type, which is then converted to VT_BSTR, and finally to VT_DATE of VT_CY using the VariantChangeType() OLE API function. See EXAMPLES for how these types can be used.

EXAMPLES

Here is a simple Microsoft Excel application.

        use Win32::OLE;
        $ex = new Win32::OLE 'Excel.Application' or die "oops\n";
        
        # open an existing workbook
        $ex->Workbooks->Open( 'test.xls' );
        
        # write to a particular cell
        $ex->Workbooks(1)->Worksheets('Sheet1')->Cells(1,1)->{Value} = "foo";
        
        # save and exit
        $ex->Save;
        $ex->Quit;

Here is an example of using Variant data types.

        use Win32::OLE;
        $ex = new Win32::OLE 'Excel.Application' or die "oops\n";
        $ex->{Visible} = 1;
        $ex->Workbooks->Add;
        $ovR8 = Variant(VT_R8, "3 is a good number");
        $ex->Range("A1")->{Value} = $ovR8;
        $ex->Range("A2")->{Value} = Variant(VT_DATE, 'Jan 1,1970');

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:

        $obj->Method( Variant(VT_UI1, "foo\000b\001a\002r") );

Here is a wrapper class that basically delegates everything but new() and DESTROY(). Such a wrapper is needed for properly shutting down connections if your application is liable to die without proper cleanup.

        package Excel;
        use Win32::OLE;
        
        sub new {
            my $s = {};
            if ($s->{Ex} = Win32::OLE->new('Excel.Application')) {
                return bless $s, shift;
            }
            return undef;
        }
        
        sub DESTROY {
            my $s = shift;
            if (exists $s->{Ex}) {
                print "# closing connection\n";
                $s->{Ex}->Quit;
                return undef;
            }
        }
        
        sub AUTOLOAD {
            my $s = shift;
            $AUTOLOAD =~ s/^.*:://;
            $s->{Ex}->$AUTOLOAD(@_);
        }
        
        1;

The above module can be used just like Win32::OLE, except that it takes care of closing connections in case of abnormal exits.

NOTES

There are some incompatibilities with the version distributed by Activeware (as of build 306).

  1. The package name has changed from "OLE" to "Win32::OLE".

  2. All functions of the form "Win32::OLEFoo" are now "Win32::OLE::Foo", though the old names are temporarily accomodated.

  3. Package "OLE::Variant" is now "Win32::OLE::Variant".

  4. The Variant function is new, and is exported by default. So are all the VT_XXX type constants.

You are responsible for properly closing any open OLE servers down. For example, if you open a OLE connection to Excel and subsequently just die(), Excel will not shutdown and you will have a process leak on your hands. You will need to wrap the OLE connection in your own object and provide a DESTROY method that does proper cleanup to ensure smooth shutdown. Alternatively, you can use a __DIE__ hook or an END{} block to do such cleanup. See EXAMPLES above for an example of using a wrapper object.

AUTHORS

Originally put together by the kind people at Hip and Activeware.

Gurusamy Sarathy <gsar@umich.edu> has subsequently fixed several major bugs, memory leaks, and reliability problems, along with some redesign of the code.

COPYRIGHT

    (c) 1995 Microsoft Corporation. All rights reserved. 
        Developed by ActiveWare Internet Corp., http://www.ActiveWare.com

    Other modifications (c) 1997 by Gurusamy Sarathy <gsar@umich.edu>

    You may distribute under the terms of either the GNU General Public
    License or the Artistic License, as specified in the README file.