NAME

Win32::OLE::OPC - OPC Server Interface

SYNOPSIS

Two ways of using the OPC interface are provided, the class methods:

    use Win32::OLE::OPC;
    my $opcintf = Win32::OLE::OPC->new('Someones.OPCAutomation',
                                       'Someones.Server');
    $opcintf->MoveToRoot;
    foreach $item ($opcintf->Leafs) {
      print $item->{name}, "\n";
      my %result = $opcintf->ItemData($item->{itemid});
      for $attrib (keys %result) {
        print "        [", $attrib, " = '", $result{$attrib}, "']", "\n";
      }
      print "\n";
    }
    foreach $item ($opcintf->Branches) {
      print $item->{name}, "\n";
    }

or a tied hash:

    use Win32::OLE::OPC;
    my %OPC;
    tie %OPC, Win32::OLE::OPC, 'Someones.OPCAutomation', 'Someones.Server';
    # OK, list the keys...
    for $key (keys %OPC) {
      my %x = %{$OPC{$key}};
      print $key, "\n";
      for $attrib (keys %x) {
        print "        '", $attrib, "' = '", $x{$attrib}, "'", "\n";
      }
      print "\n";
    }

The tied hash method has to return a reference to a hash containing the item data hence the unpleasant code '%x = %{$OPC{$key}}'. Alternatively one can assign the returned value into a scalar and dereference it when using the hash like this 'keys %$x' and '$result->{$item}'.

Note that both methods can be used together. First create an interface using the new() method and then tie it like this:

    tie %OPC, $opcintf, 'Someones.OPCAutomation', 'Someones.Server';

To connect to a remote server add the name of the server as a parameter to the call to new() or to the tie:

  my $opcintf = Win32::OLE::OPC->new('Someones.OPCAutomation',
                                     'Someones.Server',
                                     'machine.name');
  tie %OPC, Win32::OLE::OPC, 'Someones.OPCAutomation',
                             'Someones.Server',
                             'machine.name';

DESCRIPTION

A partial implementation of the OLE for Process Control dispatch interface as defined in the 'Data Access Automation Interface Standard' version 2.

An exception is raised using Carp::croak() on any failure.

METHODS

Win32::OLE::OPC->new(DLLPROGID, SERVERPROGID, SERVERNODE)
The new() method creates an instance of an OPC server object. The DLLPROGID argument is the COM progid of the Dll which implements the Dispatch interface to the OPC server. The SERVERPROGID is the COM progid of the OPC server containing the data you wish to access. The DLLPROGID and SERVERPROGID arguments are required.

The SERVERNODE argument is optional and is the name of a remote machine running the SERVERPROGID. When SERVERNODE is specified a connection is made to the server using DCOM. WARNING: DCOM security can be a little difficult to understand so perseverance is required.

As the OPC specification only allows one browser per instance of the dispatch Dll the new() method creates and keeps a browser object in Win32::OLE::OPC->{browser}

MoveToRoot
A browser method. Moves the current browse position to the root of the address space.

MoveDown(TO)
A browser method. Moves the current browse position one branch down the address space. The TO parameter is the branch name.

MoveUp
A browser method. Moves the current browse position one node up the address space.

MoveTo(TO)
A browser method. Moves the current browse position to the absolute location specified by TO. 
    $opcintf->MoveTo('COM1._Diagnostics');

Branches
A browser method.

Returns the branch names and itemid in a hash in an array. The method has a different name from the OPC ShowBranches method because it doesn't do quite the same thing.

The returned array is also stored in Win32::OLE::OPC->{items}.

See synopsis for an example of how to call this method.

Leafs
A browser method.

Returns the leaf names and itemid in a hash in an array. The method has a different name from the OPC ShowLeafs because it doesn't do quite the same thing. The hash has the members name and itemid. The number of items in the array is saved in Win32::OLE::OPC->{count}

The returned array is also stored in Win32::OLE::OPC->{items}.

    foreach $item ($opcintf->Leafs) {
      print $item->{name}, " ", item->{itemid}, "\n";
    }

Item(N)
Returns a hash contining the name and itemid of item N. Calls to Leafs and Branches collect the item data. This is an alternative method of fetching the address space. 
  $opcintf->Leafs;
  for (my $i = 0; $i < $opcintf->{count}; $i++) {
    my $item = $opcintf->Item($i);
    print $item->{name}, " ", item->{itemid}, "\n";
  }

ItemData(ITEMID)
Use this to extract all the data the server holds for this item of data. The ITEMID is the itemid member of the hash returned by the Leafs method.

It returns a hash, the keys of which are the available attributes (found by calling the OPC QueryAvailableProperties() method) and the values of in the hash are obtained by calling GetItemProperties.

AvailableProperties(ITEMID)
Returns the available properties of an item. The ITEMID is the itemid member of the hash returned by the Leafs method.

It returns an array of hashes containing the available attributes found by calling the OPC QueryAvailableProperties() method. The hash contains Id, Description and DataType members.

The returned array is also stored in Win32::OLE::OPC->{properties}.

    print " Id Type Description\n";
    foreach my $prop ($opcintf->AvailableProperties($item->{itemid})) {
      printf "%3d %4d %s\n",
          $prop->{Id},
          $prop->{DataType},
          $prop->{Description};
    }

ServerProperties
Return a hash indexed by the following properties containing the property value: 
    StartTime CurrentTime LastUpdateTime MajorVersion
    MinorVersion BuildNumber VendorInfo ServerState LocaleID
    Bandwidth OPCGroups PublicGroupNames ServerName
    ServerNode ClientName

Note that the OPCGroups value is itself a reference to a hash and it contains a hash member indexed 'Parent' which is a hash pointing back up.

GetOPCServers
Return an array containing the names of available servers. Can be called with the progid of the dispatch Dll as an argument, in which case it will connect to the Dll and extract the list of servers. It can also be called using the object created by a call to new, in which case the name of the Dll is not required. The GetOPCServers is not exported by default. 
  use Win32::OLE::OPC qw(GetOPCServers);
  my @AvailableServers = GetOPCServers('Someones.OPCAutomation');

BrowserProperties
Return a hash indexed by the following properties containing the property value: 
    Organization Filter DataType AccessRights CurrentPosition Count

GetItemIdFromName
This is not a standard OPC browser method. It translates a full OPC path name to an item id. It is often the case that the item id and the OPC path name is one and the same thing, but you cannot assume that!

TIED HASH

See the SYNOPSIS for example code.

If you tie a hash to this module you can:

Read an items attributes
A reference to a hash keyed by attribute names is returned. See the synopsis fo an example.

Access the Keys
The keys of the hash can be enumerated so keys and each function will work.

Writing, deleting or undefining a member of the hash is not possible.

OPCGroups

The Win32::OLE::OPC::OPCGroups method returns an OPCGroups object which is blessed into the perl Win32::OLE::OPC::Groups class.

Properties
Return a hash indexed by the following properties containing the property value: 
  Parent DefaultGroupIsActive DefaultGroupUpdateRate DefaultGroupDeadband
  DefaultGroupLocaleID DefaultGroupTimeBias Count

Note that the hash member indexed 'Parent' is a hash pointing back up to the parent properties.

SetProperty(PROPERTY,VALUE)
Set one of these properties to the value given. 
  DefaultGroupIsActive DefaultGroupUpdateRate DefaultGroupDeadband
  DefaultGroupLocaleID DefaultGroupTimeBias

Add(NAME)
Add a group to the OPC groups collection. NAME is optional.

Item([NUMBER | NAME])
Get group by 1 based index or by the name used when it was added to the groups list.

GetOPCGroup([SERVERHANDLE|NAME])
Get group using the server handle or by the name used when it was added to the groups list.

Remove([SERVERHANDLE|NAME])
Remove group using the server handle or by the name used when it was added to the groups list.

RemoveAll
Remove all groups from the groups list.

ConnectPublicGroup(NAME)
You connect to a public group, it cannot be added. NAME is a string which identifies the group.

This is untested as I have no server which implements public groups.

RemovePublicGroup([SERVERHANDLE|NAME})
You remove to a public group using this method. NAME is a string which identifies the group or SERVERHANDLE is the server handle. Talk about stating the obvious!

This is untested as I have no server which implements public groups.

OPCGroup

The Win32::OLE::OPC::Group object has methods Add, Item, GetOPCGroup and ConnectPublicGroup which all return a hash blessed into the OPCGroup class.

Properties
Return a hash indexed by the following properties containing the property value: 
  Parent Name IsPublic IsActive IsSubscribed ClientHandle ServerHandle
  LocaleID TimeBias DeadBand UpdateRate OPCItems

Note that the hash member indexed 'Parent' is a hash pointing back up to the parent properties.

SetProperty(PROPERTY,VALUE)
Set one of these properties to the value given. 
  Name IsActive IsSubscribed ClientHandle LocaleID TimeBias DeadBand
  UpdateRate

OPCItems
The Win32::OLE::OPC::OPCGroup::OPCItems method returns an OPCItems object which is blessed into the perl Win32::OLE::OPC::Items class.

SyncRead(SOURCE, NUM, SERVERHANDLES, VALUES, ERRORS, [QUALITIES, TIMESTAMPS])
Read a load of items. 
  SOURCE is source of data.
  NUM is how many.
  SERVERHANDLES is a reference to an array of server handles.
  VALUES is a reference to an variant array to hold item values.
  ERRORS is a reference to an array to hold error codes.

OPCItems

This class contains a collection of OPCItem objects.

Properties
Return a hash indexed by the following properties containing the property value: 
  Parent DefaultRequestedDataType DefaultAccessPath DefaultIsActive Count

Note that the hash member indexed 'Parent' is a hash pointing back up to the parent properties.

SetProperty(PROPERTY,VALUE)
Set one of these properties to the value given. 
  DefaultRequestedDataType DefaultAccessPath DefaultIsActive Count

Item(NUMBER])
Get item by 1 based index.

GetOPCItem(SERVERHANDLE)
Get item using the server handle.

AddItem(ITEMID, CLIENTHANDLE)
Add an item identified by ITEMID, CLIENTHANDLE is a value you get back later.

AddItems(NUM, ITEMIDS, CLIENTHANDLES, SERVERHANDLES, ERRORS)
Add a load of items. 
  NUM is how many.
  ITEMIDS is a reference to an array of itemids.
  CLIENTHANDLES is a reference to an array of client handles.
  CLIENTHANDLES is a reference to an array of client handles.
  SERVERHANDLES is a reference to an array to hold server handles.
  ERRORS is a reference to an array to hold error codes.

Remove(NUM, SERVERHANDLES, ERRORS)
Removes the items in SERVERHANDLES.

OPCItem

This is the object used for reading and writing actual values.

Properties
Return a hash indexed by the following properties containing the property value: 
  Parent ClientHandle ServerHandle AccessPath AccessRights ItemID IsActive
  RequestedDataType Value Quality TimeStamp CanonicalDataType

Note that the hash member indexed 'Parent' is a hash pointing back up to the parent properties.

Read(SOURCE)
Read the value for this item. SOURCE is either $OPCCache or $OPCDevice, each of which is exported by OPC.pm by default.

Read returns a hash reference which contains Value, Quality and TimeStamp values.

Write(VALUE)
Write VALUE to this item.

ServerHandle
Returns the items server handle.

INSTALLATION

If you have nmake you can use MakeMaker as follows:

  perl Makefile.PL
  nmake
  nmake test
  nmake install
  nmake documentation

The final step makes OPC.html and OPC.txt from OPC.pm.

If you don't have nmake then you will find OPC.html and OPC.txt are included in the package ready built and all you have to do is copy OPC.pm into the site/lib/Win32/OLE directory with your Perl installation. This module has been tested with ActiveState Perl build 522.

COPYRIGHT

    (c) 1999,2000,2001,2002 Martin Tomes.  All rights reserved.
    Developed by Martin Tomes <martin@tomes.freeserve.co.uk>.
    (c) 2004 Modified by Karl Scherer. Mods to AddItems and $items->Remove.
    Added SyncRead methode to group object 
    <scherer@hotmail.com, scherer@gene.com>.
    You may distribute under the terms of the Artistic License.  See
    LICENSE.txt

AUTHOR

Martin Tomes, martin@tomes.org.uk

VERSION

Version 1.01