PI-Autopointsync Connector for the Pitopi Interface

PI-AutoPointSync Connector
for the PItoPI
Interface to the PI System

Version 1.2.0.0 and greater
02-Sep-04

09/02/2004 10:15:00 PM1

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721

Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PItoPI_APS.DOC

 2001,2002, 2003 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

09/02/2004 10:15:00 PM1

Table of Contents

Introduction

Principles of Operation

Assumptions

Installation Instructions

Installation Checklist

Un-install Procedure

Configuration Control

Tag Security

Tag Archive (Compression & Exception) Settings

‘SourceTag’ Attribute

Source Tag Name & Tag Name

SQL Filter for Available Source Host Points

Features

PI 2 Source Host

Tag Attributes

Compression & Exception Specs

Available Points

Point Types

PI Point Naming Convention

How PItoPI and PItoPI APS Find Source Tags

APS Connector Updates

Troubleshooting

Error -2147220451: Unable to obtain attributes from server

Error -2147220355: Call to retrieve points failed

Glossary

PI-AutoPointSync Connector for the PItoPI Interface to the PI System1

Introduction

PI-AutoPointSync (PI-APS) provides PI users with a utility that synchronizes the existing PI points for an interface with the tag definitions on the DCS, and that locates points on the DCS that do not yet exist in PI, and can be created. As DCS tag definitions change, PI points can be modified to reflect these changes automatically.

APS allows users to configure which attributes, on a per tag basis, will be synchronized with DCS. The user may also configure how PI-APS handles tags that have been created and deleted on the DCS.

PI-APS logs all actions and changes for the system administrator in order to allow for proper auditing of automated point changes. The audit logs, coupled with the versatility of tag-by-tag configuration, afford users a powerful tool for the PI system maintenance.

The PI-APS Connector for the PItoPI Interface (PItoPI_APS) is a specific module that communicates with the Target and Source Host PI Systems, gets tag attribute updates from the Source Host PI System, and locates new points on the Source Host PI System. The APS Connector and its attendant routines are called up with each synchronization scan.

The PItoPI APS Connector runs on Windows NT, Windows 2000, or Windows XP with the PI-APS Sync Engine and PI-APS Configuration Utility all on the same computer. The NT/2000/XP node may be either a PI server node, or a PI-SDK node. However, OSIsoft recommends that PI-APS be run on a separate PI-SDK node and not the PI Server home node. The PI server version that PI-APS talks to must be 3.3.361.43 or greater. This version of PI ensures compatibility with the PI-SDK version 1.1.

The PItoPI APS Connector must run on a Windows platform, but the Source Host may be a PI2 server. Please see the section about PI2 Source Host for more details.

The PI-Interface Configuration Utility (PI-ICU) must be used to register any interface for which PI-APS synchronizes points.

Principles of Operation

The PI-AutoPointSync Connector for the PItoPI Interface is implemented as an in-process COM object in a DLL called PItoPI_APS.dll. The COM object is registered during installation of the APS Connector.

The APS Connector will never appear in the Windows Task Manager process list as an independent process. It is loaded by a PI-APS process called the Synchronization Engine, which appears in the process list as piapsengine.exe. The Synchronization Engine loads the PItoPI APS Connector automatically at the scheduled synchronization time.

The PItoPI APS Connector synchronizes existing PI points on the target PI server to those on the source PI server, as well as creating a new PI point on the target PI server for each new PI point on the source PI server, and removing a PI point whose corresponding source PI point has been deleted.

The Sync Engine calls the PItoPI APS Connector twice at the user-specified time for information:

1. The first call is to the GetUpdatedAttributes method. This method gets a list of the attributes from the source host PI server for all the PI tags belonging to the interface. The Sync Engine passes the connector a list containing all the PI tags belonging to the current interface. The connector retrieves the updated attribute information for those specified tags and then sends the updated syncable attributes back to the Sync Engine. If a tag has been deleted from the Source Host PI server, the connector will return a point error for that tag indicating that the tag is not found. A message is also written to the sync log file indicating that the source host tag is no longer there.
2. The second call is the GetAvailablePoints method which gets all available points from the Source Host PI server. The Sync Engine passes the connector a list of existing PI tags for the current interface. The connector then gets a list of all available PI points on the Source Host PI server, and hands that list back to the Sync Engine.

Note: It is important to remember that the user controls whether or not changes will be automatically made to the target PI point database by settings within the APS Configuration Utility.

For details on how to configure PI-APS to create, edit, and delete PI points as desired, please refer to the PI-AutoPointSync Configuration & Management Utility manual. Brief instructions can be found in the Installation Checklist section of this manual.

The following diagram depicts a typical configuration:

Assumptions

• Target PI system is running version 3.3 or later.
• APS connector is running on Windows NT 4 SP6 or higher, Windows 2000, or Windows XP

Installation Instructions

The PItoPI APS Connector requires that PI-APS be installed on the machine on which the PItoPI APS Connector is to be run.

The PItoPI APS Connector Installation package is called PItoPI_APSSetup.msi. This installation package will install just the PItoPI APS Connector, not the PItoPI Interface or PI-APS. To install the PItoPI APS Connector, run PItoPI_APSSetup.msi on the node where PI-APS is installed.

Installation Checklist

1. Install PI-AutoPointSync (PI-APS). (The PI-APS setup installs PI-SDK and PI-Interface Configuration Utility (PI-ICU)).
2. Install the interface whose points are to be synchronized, if it is not already installed.
3. Run the PI-ICU (installed by PIAPSSetup) and configure the PItoPI interface whose tags are to be synchronized.
4. Install the PItoPI APS Connector with PItoPI_APSSetup.msi.
5. Run the PI-AutoPointSync Configuration Utility and select Register New from the Interface menu
   
   The Configure Interface or COM Connector for PI-APS dialog will be displayed:
   
   Follow the instructions for configuring the PItoPI interface for PI-APS. The PI-APS Sync Engine will be started automatically when the PI-AutoPointSync Configuration Utility is run. For details on using the Add an Interface dialog, see the section that is titled Add an Interface - Configure an Interface for AutoPointSync in the PI-APSUserManual.doc.
6. Configure the APS Connector for the newly added interface with the options under the Settings menu on the PI-AutoPointSync Configuration Utility main window. Review all of the following settings under the Settings menu, as it is likely that the default settings need to be changed for individual interfaces and sites:

• Rules
  
• Sync Schedule
  
• User-set Defaults
  
  and
  

For details on using the Configuration & Settings dialog, see the section that is titled PI-APS Configuration Utility in the PI-APSUserManual.doc.

1. Configure the PItoPI -specific settings for the newly added interface with the Connector-specific… dialog under the Settings menu on the PI-AutoPointSync Configuration Utility main window.
   
   Review the settings, as it is likely that the default settings need to be changed for individual interfaces.
2. Enable the Sync Engine with the Tools menu option titled Enable Sync Enginevia the PI-AutoPointSync Configuration Utility. The PI-APS Sync Engine is installed disabled and requires the user to enable it. If this menu item has a check next to it, the Sync Engine is already enabled, and does not need to be enabled.
   
3. Enable the connector for the selected interface with the Tools menu option titled Enable Connector via the PI-AutoPointSync Configuration Utility. All PI-APS Connectors are installed disabled and require the user to enable them. If this menu item has a check next to it, then the Connector is already enabled, and does not need to be enabled.

Un-install Procedure

To uninstall the PItoPI APS Connector, run the Add-Remove Programs applet (this is found from the Start Menu, Settings>Control Panel> Add-Remove Programs). The following program needs to be removed:

• PItoPI APS Connector (PItoPI_APS)

Configuration Control

The APS Connector for the PItoPI Interface has an extra configuration control that is used to configure the following settings:

• Security settings for Available Tags when they are created in PI.
• Flag indicating whether to keep the SourceTag attribute from the Source Tag.
• Tag naming convention to apply to Available Tags.
• SQL Filter for Available Source Host Points.

The control looks like this:

Tag Security

If the Use the security settings from the source tagoption is checked, then the security settings used by the source tag on the source PI server will be used by APS when creating the PI point on the target PI server. If the user or group used by the source tag for Data Group, Data Owner, Point Group, or Point Owner do not exist on the target server, the point create will fail.

If the Use the default security settings for this interface (set on the User-set defaults dialog found on the Settings menu) option is checked, the security settings belonging to the source tag will not be used when creating the target PI point. The defaults specified on the User-set defaults dialog will be used.

Tag Archive (Compression & Exception) Settings

If the Use the archive (compression & exception) settings from the source tag option is checked, then the exception and compression settings used by the source tag on the source PI server will be used by APS when creating the PI point on the target PI server.

If the Use the default archive settings for this interface (set on the User-set defaults dialog found on the Settings menu) option is checked, the exception and compression settings belonging to the source tag will not be used when creating the target PI point. The defaults specified on the User-set defaults dialog will be used.

‘SourceTag’ Attribute

If the Do not keep ‘SourceTag’ attribute from Source Host’s tag check box is checked, the tag name stored in the Source host’s ‘SourceTag’ attribute will not be used when creating the Available point. If this check box is not checked, and the tag name specified in the ‘SourceTag’ attribute does not exist on the target PI server, the point create will fail.

Source Tag Name & Tag Name

The source tag name, used by the PItoPI interface to identify the tag on the source host that a PItoPI point pulls data from, can be specified in one of the following attributes. One or more of these options must be checked:

Instrument Tag: The PItoPI point’s instrument tag field. The interface first looks in this field.

Extended Descriptor (Exdesc): The PItoPI point’s exdesc field, in the form of STAG=<tagname>. The interface looks in this field second.

Tag: If the PItoPI interface cannot locate the source tag from the instrument tag or exdesc field, it will then attempt to locate the source tag using the PItoPI point’s tagname.

Tag Naming Convention

If the tag name is not to be used to store the source tag name, then a tag naming convention may be specified. The default naming convention for target server Available points is to use the same tag name as the Source Host’s tag name. The button with the greater-than arrow provides the following options that may be used as part of the tag name convention:

• Source Tagname (Name of the source tag)
• Interface Name (Name of the interface these points belong to)
• Period (“.”)
• Space (“ “)
• Underscore (“_”)

The illegal characters for PI tag names are listed on the control. If any illegal characters are specified in the tag naming convention mask, the text box will turn yellow, and the illegal mask will not be saved.

SQL Filter for Available Source Host Points

An optional SQL syntax filter may be defined to filter which points on the source host are considered to belong to this instance of the PItoPI interface. If no filter is specified, then all points on the Source Host are retrieved as Available Points.

For example, if there are 2 PItoPI interfaces pulling data from one source host, and point that have a point source of ‘B’ on the source host are retrieved by PItoPI1, then the SQL statement for that PItoPI1’s APS connector would be:

Tag = ‘*’ and PointSource = ‘B’ The configuration control has a “Test Expression” button, which pulls the list of point names from the Source Host that pass the specified SQL filter, so that the filter can be tested before it is saved. Only the first 100 points matching that filter will be displayed, so that an expensive query does not fill up the list box.

The Source Host that this interface instance uses, the number of points found by the query, and the return status of the query are displayed, as well.

Features

PI2 Source Host

If the Source Host is a PI2 server, there are a few differences in the point definitions on the source host and the receiving host that need attention. If the Source Host is a PI2 server, the following attributes should have sync set to off:

datagroup

dataowner

ptgroup

ptowner

The reason for this is that there is no PI2 equivalent of these attributes, so the value scanned in from the PI2 source host will always be blank (“”), which sets the attributes back to their default values on the PI3 receiving node, and overwrites the manually set settings for these attributes:

Attribute / Default Value
datagroup / piadmin
dataowner / piadmin
ptgroup / piadmin
ptgroup / piadmin

The default sync settings for these four attributes are “Off”.

Special Point Attribute Cases

There are a few special cases where attributes from the PI2 source host do not directly translate into attributes on the PI3 target, or where attributes that apply on the PI2 source host no longer apply on the PI3 target. They are discussed below.

Filter Code

A PI2 digital point may have a Filter Code other than 0, but on PI3, digital tags can only have a filter code of 0. The connector will not pass through the filter code from the PI 2 source host, but will set it to 0 for the PI3 target point.

Typical Value

A PI2 digital point’s Typical Value is based on the PI2 digital state indexing scheme where the users selects a starting digital state and indicates how many more digital states are included in the set. One digital state is selected as the typical value. When the PI3 target point is created, the digital set is also created, and the typical value is translated so that the same value that was the typical value on the PI2 source host is the typical value on the PI3 target.

Source Tag

A PI2 Source Tag that is blank is actually a blank space. The PItoPI APS Connector traps this and sets it to a blank without spaces so that the attribute is not edited on each synchronization loop.

Resolution Code

The PI2 source tag Resolution Code is translated to the PI3 target tag’s step. The following conversion is used:

PI2 Source Host
Resolution Code / PI3 Target Step
1 – 3 / 0
4 / 1

Shutdown

PI2 does not have a shutdown attribute. If the source host is PI2, then the default value for shutdown is used. Typically, the default value for shutdown is On (1).

Tag Attributes

The following PI attributes may be synchronized by the PItoPI APS Connector, based on the settings that the user configures for each. It is recommended that the userint1 field have sync enabled, and that either one or both of the extended descriptor (exdesc) and the instrumenttag fields have sync enabled:

PIBase Attributes / Description / Syncable / Key Field
tag / PI Tag Name / No / Yes
exdesc / Source Tagname / Yes / Yes (Note 1)
instrumenttag / Source Tagname / Yes / Yes (Note 1)
userint1 / Source PointID / Yes / Yes
pointtype / PI Point Type / No / Yes
archiving / PI Archiving Flag / Yes / No
descriptor / PI Descriptor / Yes / No
engunits / PI Engineering Units / Yes / No
excmin / PI Exception Min Time / Yes / No
excmax / PI Exception Max Time / Yes / No
excdev / PI Exception Deviation in engineering units / Yes / No
excdevpercent / PI Exception Deviation in percent of span / Yes / No
compressing / PI Compression Flag / Yes / No
compdev / PI Compression Deviation / Yes / No
compdevpercent / PI Compression Deviation in percent of span / Yes / No
compmin / PI Compression Min Time / Yes / No
compmax / PI Compression Max Time / Yes / No
digitalset / PI Digital Set (Digitals) / Yes / No
displaydigits / PI Display Digits / Yes / No
dataacess / PI Data Access / Yes (Note 2) / No
datagroup / PI Data Group / Yes (Note 2) / No
dataowner / PI Data Owner / Yes (Note 2) / No
ptaccess / PI Point Access / Yes (Note 2) / No
ptclassname / PI PointClass / No / No
ptgroup / PI Point Group / Yes (Note 2) / No
ptowner / PI Point Owner / Yes (Note 2) / No
typicalvalue / PI Typical Value / Yes (Note 3) / No
scan / PI Scan Flag / Yes / No
shutdown / PI Shutdown Flag / Yes / No
sourcetag / PI Source Tag / Yes / No
span / PI span / Yes / No
step / PI Step Flag / yes / No
zero / PI zero / Yes / No
PI Classic Attributes / Description / Syncable / Key Field
convers / PI Conversion Factor / Yes / No
filtercode / PI Filter Code / Yes / No
location1 / Interface Number / No (Note 3) / No
location2 / Timestamp Adjustment / Yes (Note 4) / No
location3 / DigitalState Suppression / Yes (Note 4) / No
location4 / PI Scan Class / Yes (Note 5) / No
location5 / PI Location5 / Yes / No
squareroot / PI Square Root code / Yes / No
totalcode / PI Total Code / Yes / No
userint2 / PI User Integer 2 / Yes / No
userreal1 / PI User Real 1 / Yes / No
userreal2 / PI User Real 2 / Yes / No
Other (Required)
Digitalstateset / States in PIDigitalSet / No / No

Note 1:Under normal operation, the PItoPI interface allows users to define the Source Host point name in the Exdesc or InstrumentTag fields. However, if the interface is run with the /tn command line options, then the InstrumentTag field and the Exdesc field are not used as Key Attributes, and they are synchronized with the InstrumentTag and Exdesc values on the Source Host. If these attributes are set not to hold the source tag name, they will be synchronized with the Exdesc and InstrumentTag attribute values from the source tag.