PI AutoPointSync Connector for the PItoPI Interface to the ...
PI AutoPointSync Connector
for the PItoPI Interface
to the PI System
Version 1.2.2.0
Revision A
How to Contact Us
|OSIsoft, Inc. |Worldwide Offices |
|777 Davis St., Suite 250 |OSIsoft Australia |
|San Leandro, CA 94577 USA |Perth, Australia |
| |Auckland, New Zealand |
|Telephone |OSI Software GmbH |
|(01) 510-297-5800 (main phone) |Altenstadt, Germany |
|(01) 510-357-8136 (fax) |OSI Software Asia Pte Ltd. |
|(01) 510-297-5828 (support phone) |Singapore |
| |OSIsoft Canada ULC |
|techsupport@ |Montreal, Canada |
| |OSIsoft, Inc. Representative Office |
|Houston, TX |Shanghai, People’s Republic of China |
|Johnson City, TN |OSIsoft Japan KK |
|Mayfield Heights, OH |Tokyo, Japan |
|Phoenix, AZ |OSIsoft Mexico S. De R.L. De C.V. |
|Savannah, GA |Mexico City, Mexico |
|Seattle, WA | |
|Yardley, PA | |
|Sales Outlets and Distributors |
|Brazil |South America/Caribbean |
|Middle East/North Africa |Southeast Asia |
|Republic of South Africa |South Korea |
|Russia/Central Asia |Taiwan |
| |
|WWW. |
|OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, |
|Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks |
|have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the |
|property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's |
|products or any affiliation with such party of any kind. |
|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 |
| |
|Unpublished -- rights reserved under the copyright laws of the United States. |
| |
|© 1999 - 2008 OSIsoft, Inc. PI_PItoPI_APS.doc |
Table of Contents
Introduction 1
Supported Features 1
Principles of Operation 3
Installation Instructions 5
Installation Checklist 5
Uninstall Procedure 11
Configuration Control 13
Tag Security 13
Tag Archive (Compression & Exception) Settings 14
‘SourceTag’ Attribute 14
Location1 (Interface ID) Setting 14
Location4 (Scan Class) Setting 14
Source Tag Name & Tag Name 15
Filter for Available Source Host Points 16
Features 19
PI2 Source Server 19
Tag Attributes 20
Compression & Exception Specs 22
Available Points 22
Point Types 23
PI Point Naming Convention 23
PI Point Renaming 23
How PItoPI and PItoPI APS Find Source Tags 23
Best Practices, Hints and Techniques 25
PItoPI Interface with Multiple Instances 25
Example 1: PItoPI Interface with Multiple Instances Using Solution 1 25
Example 2: PItoPI Interface with Multiple Instances Using Solution 2 27
APS Connector Updates 29
Troubleshooting 31
Error -2147220451: Unable to obtain attributes from server 31
Error -2147220355: Call to retrieve points failed 31
Glossary 33
Revision History 35
Introduction
PI AutoPointSync (PI APS) provides PI users with a tool 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.
PI APS allows users to configure which attributes, on a per tag basis, will be synchronized with the 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 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 Servers, gets tag attribute updates from the Source PI Server, and locates new points on the Source PI Server. The PItoPI APS Connector and its attendant routines are called up with each synchronization scan.
The PItoPI APS Connector runs on Windows NT, Windows 2000, Windows 2003, or Windows XP with the PI APS Sync Engine and PI APS Configuration Utility all on the same computer. The Windows node may be either a PI Server node or a PI SDK node. However, OSIsoft recommends running PI APS on a separate PI SDK node and not the PI Server node. The PI Server that PI APS talks to must be version 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 PI Server may be a PI2 server. Please see the section “PI2 Source Server” for more details.
The PI Interface Configuration Utility (PI ICU) must be used to register any interface for which PI APS synchronizes points.
Supported Features
|Feature |Support |
|Part number | |
|Platforms |Windows (NT-Intel, Windows 2000, Windows 2003, |
| |Windows XP) |
|PI Point Types |int16, int32, float16, float32, float64, digital, |
| |string |
|Vendor Software Required on PI API / PINet Node |No |
|Vendor Software Required on Foreign Device |No |
|Vendor Hardware Required |No |
|Additional PI Software Included with APS Connector |No |
|Supports Tag Naming features |No |
|*Supports Tag Selection features |No |
* See paragraphs below for further explanation.
Supports Tag Selection features
The PItoPI APS Connector does not support the standard APS Tag Selection feature.
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 PI APS Connector.
The PI 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, creates a new PI point on the target PI Server for each new PI point on the Source PI Server, and removes a PI point whose corresponding source PI point has been deleted.
The PI APS 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 PI Server for all the PI tags belonging to the interface. The PI APS Sync Engine passes the connector a list containing all the PI tags belonging to the current interface. The connector retrieves the current attribute information for those specified tags and then sends the updated syncable attributes back to the PI APS Sync Engine. If a tag has been deleted from the Source 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 PI Server. The PI APS 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 PI Server, excluding the points that have existing interface points, and hands that list back to the PI APS 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 PI 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 for Interfaces and PI COM Connectors user manual (PI-APSUserManual.doc). Brief instructions can be found in the “Installation Checklist” section of this manual.
The following diagram depicts a typical configuration:
[pic]
Assumptions
• Target PI Server is running version 3.3 or later.
• PI APS connector is running on Windows NT 4 SP6 or higher, Windows 2000, Windows 2003, 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_APS_v_x_y_z.exe. 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_APS_v_x_y_z.exe 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 PItoPI interface whose points are to be synchronized, if it is not already installed.
3. Run the PI ICU (installed by PIAPSSetup) and configure the interface whose tags are to be synchronized.
4. If the interface is not running on the same computer as PI APS, make sure that both the source and target PI Servers are in the SDK Known Servers List on the PI APS node. This can be done by opening the Connections… dialog from the Interface menu option in the PI APS Configuration Utility on the PI APS node and adding both servers.
5. Install the PItoPI APS Connector with PItoPI_APS_v_x_y_z.exe.
6. Run the PI AutoPointSync Configuration Utility and select Register New from the Interface menu
[pic]
The Configure Interface or COM Connector for PI-APS dialog will be displayed:
[pic]
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 this dialog box, see the section that is titled “Add an Interface - Configure an Interface for AutoPointSync” in the PI AutoPointSync for Interfaces and PI COM Connectors user manual.
7. Configure the PI 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
[pic]
• Sync Schedule
[pic]
• User-set Defaults
[pic]
and
[pic]
For details on using these dialog boxes, see the section that is titled “PI-APS Configuration Utility” in the PI AutoPointSync for Interfaces and PI COM Connectors user manual.
8. Configure the PItoPI-specific settings for the newly added interface with the Connector-specific… dialog box under the Settings menu on the PI AutoPointSync Configuration Utility main window.
[pic]Review the settings, as it is likely that the default settings need to be changed for individual interfaces.
9. Enable the Sync Engine with the Tools menu option titled Enable Sync Engine via 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.
[pic]
10. 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.
Uninstall Procedure
To uninstall the PItoPI APS Connector, run the Add or Remove Programs applet (this is found from the Start menu, Settings>Control Panel> Add or Remove Programs). The following program needs to be removed:
• PI PItoPI TCP/IP (PItoPI) APS Connector
Configuration Control
The PI 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.
• Filter for Available Source Host Points.
The control looks like this:
[pic]
Tag Security
If the Use the security settings from the source tag option is checked, then the security settings from the source tag on the Source PI Server will be used by PI 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 does not exist on the target PI 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 from the source tag will not be used when creating the target PI point. The defaults specified on the User-set defaults dialog box 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 from the source tag on the Source PI Server will be used by PI 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 from the source tag will not be used when creating the target PI point. The defaults specified on the User-set defaults dialog box 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 point’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.
Location1 (Interface ID) Setting
The PitoPI Interface supports command line argument /C1=x, which tells the interface to ignore the /ID=n command line argument and load all tags that have the point source defined by the /PS=m command line argument. If /C1=x is on the command line, the PitoPI APS connector will synchronize all points that use the interface’s point source, regardless of their location1 setting. It will also create PI points or Available Points for the interface using the source point’s location1 value for each new point.
If the /C1=x command line argument is present, PitoPI APS can be configured such that PitoPI APS will use the value (x) from the /C1=x command line argument for the location1 value for all Available Points. To enable this feature, check the Use /c1 argument value x for AvailablePoint’s Location1 (Interface ID) value button:
[pic]
This option will be grayed out if the /C1=x argument is not configured for this interface.
Location4 (Scan Class) Setting
The PitoPI APS connector configuration control allows users to specify a scan class (Location4 value) to be set for all Available Points. The configuration control will load up all the scan classes defined for the PitoPI interface instance being configured so that the user can select a scan class number:
[pic]
If the interface instance has the /C4=x command line argument defined, this option will be disabled and the PitoPI APS connector uses the Location4 value from the source point.
Source Tag Name & Tag Name
[pic]
The source tag name, used by the PitoPI interface to identify the tag on the Source PI Server that a PitoPI point collects 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 attribute. The interface first looks in this attribute.
Extended Descriptor (Exdesc): The PitoPI point’s exdesc attribute, in the form of STAG=tagname. The interface looks in this attribute second.
Tag: If the PitoPI interface cannot locate the source tag from the instrument tag or exdesc attribute, it will then attempt to locate the source tag using the PitoPI point’s tag name.
Tag Naming Convention
If the tag name is not 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 point. The button with the greater-than arrow provides the following options that may be used as part of the tag name convention:
[pic]
• 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 name mask, the box will turn yellow, and the illegal mask will not be saved.
Filter for Available Source Host Points
An optional WHERE clause may be defined to filter which points on the Source PI Server are considered to belong to this instance of the PitoPI interface. Click Source Point Filter in the list on the left to show the options related to filtering the Source PI Server points considered for Available Points.
[pic]
If the Retrieve only Available Points from the Source Host that satisfy the following WHERE clause check box is not selected, then all points on the Source PI Server are retrieved as Available Points.
When the Retrieve only Available Points from the Source Host that satisfy the following WHERE clause check box is selected, enter a WHERE clause in the box. The PitoPI APS Connector calls the PI SDK GetPoints or GetPointsSQL method with the WHERE clause as the query string parameter. The Source PI Server returns a list of points that satisfy the query. The PitoPI APS Connector then considers this list of points to belong to this instance of the PitoPI Interface.
Note: When the WHERE clause is changed, the Available Points from the last synchronization scan using the old WHERE clause remain in the APSPoints database for the interface. On the next synchronization scan, the Available Points from the new WHERE clause will be merged into the APSPoints database. Therefore, after changing the WHERE clause, OSIsoft recommends that you purge Available Points from the APSPoints database (select Manage Databases… on the Tools menu) and review any Hidden points.
The GetPoints and GetPointsSQL buttons select which query method is used. Both choices are available when the Source PI Server is PI3. The PI SDK does not support calling GetPoints to retrieve points from a PI2 Server. Therefore, if the Source PI Server is PI2, you must select GetPointsSQL. The connector-specific control does not validate the choice of query method because a connection to the Source PI Server is necessary to determine whether it is PI2 or PI3 and connecting to a remote Source PI Server can be slow. When a synchronization scan occurs, the PitoPI APS Connector determines whether the Source PI Server is PI2 and, if so, calls GetPointsSQL regardless of the configuration choice.
The GetPoints and GetPointsSQL methods have different capabilities and performance characteristics that will influence the choice of method. GetPoints is generally faster than GetPointsSQL but GetPoints cannot handle complex queries. Also, some WHERE clause attribute names are different for GetPoints and GetPointsSQL. GetPoints uses the native attribute names of the PI3 Point Database and GetPointsSQL uses the attribute names defined by PI ODBC.
The PI SDK on-line help provides information about the GetPoints and GetPointsSQL methods. In the PI SDK on-line help, these methods are in the “PI-SDK Programming Reference” under the Server object. The GetPoints2 method under the IgetPoints2 interface contains a link to the “GetPoints vs. GetPointsSQL” page that summarizes the differences between GetPoints and GetPointsSQL.
The configuration control has a Test Expression button that allows the WHERE clause to be tested before it is saved. Click Test Expression to call the selected query method with the WHERE clause. The first 200 points returned by the query are displayed in the box on the left of the Test Expression button. The Source PI Server that this interface instance uses, the number of points returned by the query, and the return status of the query are displayed under the Test Expression button. Since a connection to the Source PI Server is necessary, the configuration control determines whether the Source PI Server is PI2 or PI3. If the Source PI Server is PI2, the configuration control selects the GetPointsSQL query method and makes the query method buttons unavailable.
GetPoints WHERE clause syntax summary
The following description of WHERE clause syntax for the GetPoints method is summarized from the on-line help for PI SDK version 1.3.4. Since the PI SDK can be updated independently of PI APS, this summary may not be completely accurate for other PI SDK versions. The WHERE clause summary in this document is not a substitute for PI SDK on-line help, which is the authoritative reference.
• A WHERE clause (query expression) is composed of one or more phrases separated by or.
• A phrase is composed of one or more basic tests separated by and.
• A basic test is:
attribute-name relational-operator value
The relational operators are: = (equal), (not equal), =.
When relational operators equal (=) or not equal () are used with a string-valued attribute, value can contain “*” or “?” wildcard characters. When value contains wildcard characters, value is a pattern that the attribute value must match for the equal operator to be true (or not match for the not equal operator to be true).
If a phrase is composed of more than one basic test, an attribute name cannot be used more than once in the phrase. For example,
span > 10 and span < 50
is an illegal phrase.
Support for parentheses is limited to enclosing entire phrases. That is, parentheses cannot contain an or operator. For example,
tag = ‘sin*’ and (pointsource = ‘L’ or pointsource = ‘R’)
is an illegal WHERE clause. However, this expression can be rewritten as
(tag = ‘sin*’ and pointsource = ‘L’) or (tag = ‘sin*’ and pointsource = ‘R’)
which is a legal WHERE clause composed of two phrases.
When a WHERE clause is composed of more than one phrase, the PI Server effectively processes each phrase as a separate query and returns a list of points for each phrase. If a point satisfies more than one phrase, the PI Server will return the point multiple times. If a large number of points satisfy more than one phrase, this can increase the load on the PI Server to process the WHERE clause and on the network to transfer the same point multiple times. Other than increased load, a multi-phrase WHERE clause has no other negative consequences. The PI SDK merges the individual lists from the multiple phrases into a single, final point list that is returned to the client application. Before adding a point to the final list for the client application, the PI SDK checks that the point is not already in the final list. Thus, the final list does not contain duplicate points.
Features
PI2 Source Server
If the Source PI Server is a PI2 server, there are a few differences in the point definitions on the Source PI Server and the receiving PI Server that need attention. If the Source PI Server 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 server will always be blank (“”), which sets the attributes back to their default values on the PI3 receiving server 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 Server do not directly translate into attributes on the target PI3 Server or where attributes that apply on the PI2 Source Server no longer apply on the target PI3 Server. They are discussed below.
Filter Code
A PI2 digital point may have a Filter Code attribute other than 0, but PI3 digital tags can only have a filter code of 0. The connector will not pass through the filter code from the PI2 Source Server but will set it to 0 for the PI3 target point.
Typical Value
A PI2 digital point’s Typical Value attribute is based on the PI2 digital state indexing scheme where the digital point configuration specifies 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 state that was the typical value on the PI2 Source Server is the typical value on the PI3 target point.
Source Tag
A PI2 SourceTag attribute that is blank is actually a single 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 |PI3 Target Step |
|Resolution Code | |
|1 – 3 |0 |
|4 |1 |
Shutdown
PI2 does not have a shutdown attribute. If the Source Server 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 attribute have sync enabled and that either one or both of the extended descriptor (exdesc) and the instrumenttag attributes have sync enabled:
|PI Base Attributes |Description |Syncable |Key Field |
|tag |PI Tag Name |No |Yes |
|exdesc |Source Tag Name |Yes |Yes (Note 1) |
|instrumenttag |Source Tag Name |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 |Digital State 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 PI DigitalSet |No |No |
Note 1: Under normal operation, the PitoPI interface allows users to define the Source PI Server point name in the Exdesc or InstrumentTag attributes. However, if the interface is run with the /tn command line parameter, then the InstrumentTag attribute and the Exdesc attribute 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.
Note 2: If the Source PI Server 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 Server will always be blank (“”), which actually sets the attributes back to their default values:
datagroup: piadmin
dataowner: piadmin
ptgroup: piadmin
ptowner: piadmin
Note 3: Location1 is the interface number – and it pertains strictly to the PitoPI tag on the target PI Server. If location1 changes, the PitoPI interface will drop that point. Since the interface number is not related to the Source PI Server, this value cannot be synchronized to the location1 attribute value from the source point.
Note 4: Location2 and Location3 define how the PitoPI interface handles timestamps and digital states – this means that if this value changes, the behavior of the PitoPI interface will change. Since the location2 and location3 settings for the PitoPI tag are not related to the location2 and location3 attributes of the source tags, these attributes cannot be synchronized to the attributes of the source point. However, if the interface is run with the /c2=x for location2 (override location2…) or /c3=x for location3 (override location3…) command line options, then these attributes can be synchronized with the source point attributes.
Note 5: Location4 is the scan class. Since there is no way to ensure that the scan class specified by location4 for the source tag matches up with a scan class definition for the PitoPI interface, this attribute cannot be synchronized. For example, if there is a CHIPtoPI interface scanning values on a Source PI Server and the CHIP interface has 5 scan classes but the PitoPI target interface has only 3 scan classes, synchronizing the target PitoPI point’s location4 setting could result in an invalid scan class setting – a scan class number that does not exist for the PitoPI interface. However, if the interface is run with the /c4=x for location4 (override location4…) command line option, then this attribute can be synchronized with the source point location4 attribute.
Compression & Exception Specs
When PI APS first creates tags, it will create them with the default Compression and Exception specs specified by the user via the PI APS Configuration Utility. If the user has enabled sync for the compression and/or exception specs, during the next sync loop these attributes will be updated to match the Source PI Server. There is no shortcut right now that allows users to tell PI APS to use the compression and exception specs from source points when creating new points.
Available Points
Available points are points that PI AutoPointSync has detected in the Source PI Server that do not exist in the target PI Server.
Point Types
Available Points from a PI3 Source Server are assigned the same point type as their corresponding source point types. Point types for Available Points from a PI2 Source Server are:
|PI2 Source Server |PI Target Point Type |
|Point Type | |
|I |Int16 |
|R |Float16 |
|D |Digital |
PI Point Naming Convention
Available Points located on the Source PI Server are named the same as their source point tag names, unless a Tag Naming Convention is specified via the Configuration Control.
Users may rename points created or managed by PI APS.
PI Point Renaming
If a point was renamed on the Source PI Server, the point on the target PI Server by default will keep the original name. To enable tag renaming of target PI Server points when a point name changes on the Source PI Server, the attribute “NEWTag” must be marked for synchronizing. By default this attribute is not checked.
[pic]
How PitoPI and PitoPI APS Find Source Tags
Under normal interface operation, the PitoPI interface and the PitoPI APS Connector:
1. First look at the Instrument Tag attribute for the source tag name.
2. If the instrument tag is empty, they then look at the extended descriptor, looking for the source tag name in the format STAG=.
3. If neither instrument tag nor extended descriptor has a tag name, then the receiving tag name is assumed to be the source tag name.
4. If the source tag is not in the Instrument Tag, Exdesc, or Tag attribute, then the PitoPI APS Connector checks to see if the source tag’s PointNumber (PI2 Source Server) or the PointID (PI3 Source Server) holds the source point’s ID number. This option is something that only the PitoPI APS connector – not the interface – supports. This feature is supported so that PI APS can store the point ID of the source tag in case the source tag’s name is changed. In order to enable this feature, the UserInt1 attribute must be set to syncable for each PitoPI point via PI APSConfig, so that PI APS can store that attribute.
If the /tn command line argument is present, the PitoPI interface and the PitoPI APS Connector:
1. The receiving tag name is assumed to be the source tag name.
2. If the source tag is not the same as the Tag name, then the PitoPI APS Connector checks to see if the source tag’s PointNumber (PI2 Source Server) or the PointID (PI3 Source Server) holds the source point’s ID number. This option is something that only the PitoPI APS connector – not the interface – supports. This feature is supported so that PI APS can store the point ID of the source tag in case the source tag’s name is changed. In order to enable this feature, the UserInt1 attribute must be set to syncable for each PitoPI point via PI APSConfig, so that PI APS can store that attribute.
Best Practices, Hints and Techniques
This section addresses special cases and describes how to accomplish some of the less common or more specialized tasks with PitoPI APS.
PitoPI Interface with Multiple Instances
On a target server where there are multiple instances of the PitoPI interface pulling data from one Source PI Server, PI APS will assign new (Available) points to each instance of the interface that it synchronizes. PI APS for each of the other PitoPI instances will see these points as well, and, if PI APS is configured to create the points automatically, the create operation will fail on all but the first PitoPI instance that is synchronized because the point will have been created on the PI Server and will belong to the first PitoPI interface instance that synchronizes after the source point is created. There are some options to be considered while setting up interfaces with multiple instances:
Solution 1: Leave the existing PitoPI interface interfaces as they are, register them to use PI APS, but configure them to update their existing points only and not to look for new (Available) points. Add an extra PitoPI interface copy and register it to use PI APS, but allow this copy to run with Update and get Available points modes enabled so that all new points added to the Source PI Server are automatically added to this extra copy of the PitoPI interface.
Solution 2: The PitoPI APS connector supports filtering which new (Available) points are brought over from the Source PI Server by a user-defined WHERE clause. PI APS for each interface instance can be configured to “own” a certain subset of points from the Source PI Server so that there is no overlap in point ownership of the multiple interface instances. With this solution, an extra copy of the interface, setup specifically to find and own new points, is not needed. However, when devising the WHERE clauses for filtering (Settings ► Connector-specific…), careful consideration must be used to be sure that the logic catches all new points on the Source Host.
Example 1: PitoPI Interface with Multiple Instances Using Solution 1
1. Perform this step for each registered PitoPI interface except the new one for collecting Available Points. Run the PI APS Configuration Utility. Select one of the PitoPI registered interfaces from the Interface: drop-down list. Click Settings ► Rules…. On the Rules for interface dialog, choose Skip search for new points in the Points Not in PI frame:
[pic]
This will turn off the search for new points for each interface.
2. Then, create a new instance of the PitoPI interface that will be used to collect data for all new points added to the Source PI Server. Register this instance of the interface with PI APS, and set its Points Not in PI rule to Create automatically and PI Point Edits rule to Edit automatically:
[pic]
This new instance of the interface will then own any new points created on the Source PI Server. These points can be moved to other instances of the PitoPI interface as needed.
Example 2: PitoPI Interface with Multiple Instances Using Solution 2
Devise a plan for defining how to group all possible desired Source PI Server points into the various interface instances already configured. The goal here is to configure PI APS for each instance of the PitoPI interface such that each instance owns a certain subset of points possible on the Source PI Server and such that all subsets of points possible on the Source PI Server are assigned an interface. For example, Source PI Server points can be grouped by Point Source.
Example: If the plan is to bring all tags from the Source PI Server to the Target PI Server that use specific Point Sources, like A, M, N, O, R, and L, and there are three copies of PitoPI, the points can be distributed in the following manner:
|PitoPI Instance |WHERE clause |
|PitoPI1 |pointsource = ‘A*’ or pointsource = ‘M*’ |
|PitoPI2 |pointsource = ‘N*’ or pointsource = ‘O*’ |
|PitoPI3 |pointsource = ‘R*’ or pointsource = ‘L*’ |
Each instance would then update Existing points and find new Available points. After devising the logic for assigning Source PI Server points to an instance of an interface, do the following two steps for each interface instance:
1. Perform this step for each PitoPI interface. Run the PI APS Configuration Utility. Select one of the registered interfaces from the Interface: drop-down list. Click Settings ► Connector-specific…. In the Filter for Available Source Host Points area, check the Retrieve only Available Points from the Source Host that are defined by the following WHERE clause box and then define your WHERE clause. Use the Test Expression button to be sure that the WHERE clause is a valid expression, or synchronization will fail:
[pic]
2. Then open the Rules dialog box by clicking Settings ► Rules…. On the Rules for interface dialog box, set its Points Not in PI rule to Create automatically and PI Point Edits rule to Edit automatically:
[pic]
This tells PI APS to run in automatic mode and update.
APS Connector Updates
For information on the current version of the PitoPI_APS Connector, please see the following web site:
Troubleshooting
The following is a list of known error messages, their explanations and steps for resolving the circumstances that caused those messages to be displayed.
Error -2147220451: Unable to obtain attributes from server
The full error message appears similar to this:
PIAPSEngine.exe>PI-APS> Error -2147220451: Error -2147220451: Unable to obtain attributes from server. :retrieve pointrecord from call ptrPAs->getItem (RecNo) in GetAvailablePoints (00:TEST .1) (00:TEST .1) (localhost) (pitopi3) (casaba) (1) from call ptrAPSC->GetAvailablePoints in PerformASynchronization
The information that appears in parentheses is system dependent. What this means is that the Source PI Server is a PI2 server and the version of the PI SDK on the PI APS node is a version prior to the PI SDK 1.2 release. This is a known problem with the PI SDK where more than one PI2 server is in the known servers list and the Source PI Server is not the last server connected to in the known servers list. The solution is to upgrade the PI SDK to version 1.2 release. A workaround is to remove all PI2 servers from the known servers list on the PI APS node except for the Source PI Server for the PitoPI interface that PI APS is synchronizing.
Error -2147220355: Call to retrieve points failed
The full error message appears similar to this:
PIAPSEngine.exe>PI-APS> Error -2147220355: Call to retrieve points failed. [-10722] PINET: Timeout on PI RPC or System Call. From call m_ptrServer->GetPointsSQL in GetExistingTagsWithSyncON
Typically, this error is received when the Source PI Server is a PI2 server. It indicates that the call from the PitoPI APS Connector to retrieve all the existing points on the PI2 Server timed out. The PI SDK, when talking to a PI2 server, typically makes use of the PI API to perform its functions. This particular call uses the PI API to retrieve the points. Since it uses the PI API under the hood, it uses the PI API timeout setting, as well, and not the SDK timeout setting. To increase the timeout setting, on the PI APS node, go to the \PIPC\DAT directory and edit the pilogin.ini file. Modify or add the following section:
[NETWORK]
TIMEOUT=x
where x is the timeout in seconds. The required timeout setting will depend on the number of points on the server as well as network traffic, system resources, etc. Once this setting is added or modified, save and close the file. Then stop and restart the PI APS Synchronization Engine and the PI APS Configuration Utility, so that this new setting is picked up.
Glossary
Available Points
Available points are points that PI AutoPointSync has detected on the DCS but do not exist in PI. Available Points are displayed grayed out.
Hidden Points
Hidden points are points that PI AutoPointSync has detected on the DCS, that do not exist in PI, and that the user has marked to be hidden from view.
Existing Points or Existing PI Points
Existing Points or Existing PI Points refers to points that already exist in PI and belong to the current interface.
APS Connector (APS Interface Connector)
The APS Connector or APS Interface Connector is responsible for attribute data collection from the DCS.
ID Attribute
PI point attribute that holds the interface’s ID number. For example, the PitoPI interface uses location1 to hold the interface’s ID number – the number that matches up with the /ID command-line argument.
Key Field (Key Attribute)
A Key Field or Key Attribute is a PI point attribute that is required in order to identify what point on the DCS the PI tag corresponds to. For example, the PitoPI interface uses the target PitoPI point’s ExDesc attribute, InstrumentTag attribute, or the Tag attribute to locate the source tag.
Revision History
|Date |Author |Comments |
|27-Mar-01 |HAB |Written |
|01-Nov-01 |HAB |Updated for Beta 2. |
|18-Feb-02 |HAB |Added information on using the connector with a PI 2 source. |
|01-May-02 |HAB |Updated for 1.0 (1.0.0.18) Release. |
|03-May-02 |HAB |Added to troubleshooting. |
|08-May-02 |HAB |Added to PI 2 Source Host section. |
|15-May-02 |HAB |Updated with more sections. |
|29-Aug-02 |HAB |Updated with new screen shots for PitoPI APS 1.0 SR1 (1.0.1.1) |
|24-Dec-02 |HAB |Added section on Configuration Control (1.0.1.5) |
|19-Sep-03 |HAB |Added -2147220355 to Troubleshooting (1.0.1.6, doc rev a). |
|26-Sep-03 |CG |Fixed some typos; fixed page numbering and TOC |
|30-Jan-04 |HAB |Added note on using UserInt1 to hold the source tag’s pointed (1.0.1.6, doc rev b) |
|08-Jun-04 |HAB |Added section on support for /tn, /c2-/c5 command line parameters, and the Configuration |
| | |Control’s SQL statement (1.1.0.6) |
|02-Sep-04 |HAB |Updated with new Configuration Control and its features (1.2.0.0) |
|19-Nov-04 |HAB |Updated with new Configuration Control and its features (1.2.0.3) |
|26-Nov-04 |HAB |Updated with new Configuration Control and its features (1.2.0.7) |
|06-May-05 |HAB |Added “Best Practices, Hints and Techniques” section (1.2.0.7, doc rev A) |
|11-May-07 |GM |Updated with new Configuration Control. Added “Point renaming” section (1.2.1.0, doc rev A) |
|07-Jan-2008 |LDaley |Version 1.2.2.0. Updated title page, How to Contact Us section, and Configuration Control |
| | |section. |
|28-Jan-2008 |MKelly |Version 1.2.2.0 Revision A; Updated template being used, resized screenshots to fit within |
| | |margins, fixed revision date, fixed headers and footers, corrected uninstall procedure. |
-----------------------
Source PI Server
APS Connector
APS
Synchronization Engine
APS Configuration Utility
API/SDK Node
Target PI Server
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.