pi inteface for opc xml-da opc plug-in -...

PI Inteface for OPC XML-DA OPC Plug-in

Version 1.5.1.x

OSIsoft, LLC777 Davis St., Suite 250San Leandro, CA 94577 USATel: (01) 510-297-5800Fax: (01) 510-357-8136Web: http://www.osisoft.com

OSIsoft Australia • Perth, AustraliaOSIsoft Europe GmbH • Frankfurt, GermanyOSIsoft Asia Pte Ltd. • SingaporeOSIsoft Canada ULC • Montreal & Calgary, CanadaOSIsoft, LLC Representative Office • Shanghai, People’s Republic of ChinaOSIsoft Japan KK • Tokyo, JapanOSIsoft Mexico S. De R.L. De C.V. • Mexico City, MexicoOSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil

PI Inteface for OPC XML-DA OPC Plug-inCopyright: © 2002-2013 OSIsoft, LLC. All rights reserved.No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTSUse, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.

Published: 01/2013

http://www.osisoft.com/

Table of Contents

Chapter 1. Introduction...................................................................................................1Reference Manuals............................................................................................1Plug-in Specific Features...................................................................................2

Exception Reporting................................................................................2Source of Timestamps.............................................................................2Output Points...........................................................................................2

Chapter 2. Principles of Operation................................................................................3Overview of OPC XML-DA Servers and Clients.................................................3Subscription Architecture...................................................................................3Communication with an OPC XML-DA Server...................................................4

Chapter 3. Installation Checklist....................................................................................5

Chapter 4. Plug-in Installation and Administration......................................................7Locating Plug-in Directory..................................................................................7Configuring PI Tags...........................................................................................7Upgrading Plug-in..............................................................................................7Uninstalling Plug-In............................................................................................7

Chapter 5. Startup Command File.................................................................................9Configuring the Interface with PI ICU.................................................................9Configuration Tab...............................................................................................9OPC Plug-In Tab..............................................................................................10

Connection Settings Tab........................................................................11Command-line Parameters..............................................................................13

Plug-in Specific Parameters...................................................................13General PI-XML Interface Parameters...................................................15

Sample PIXML.bat File....................................................................................19

Appendix A. Error and Informational Messages......................................................21Message Logs..................................................................................................21System Errors and PI Errors............................................................................21

Appendix B. Terminology...........................................................................................23

Appendix C. Technical Support and Resources......................................................27Before You Call or Write for Help...........................................................27Help Desk and Telephone Support........................................................27Search Support......................................................................................28Email-based Technical Support.............................................................28Online Technical Support.......................................................................28Remote Access......................................................................................29


On-site Service......................................................................................29Knowledge Center.................................................................................29Upgrades...............................................................................................29OSIsoft Virtual Campus (vCampus).......................................................30

Appendix D. Revision History....................................................................................31


Chapter 1. Introduction

The default plug-in to the PI XML interface is the OPC plug-in that conforms to the OPC XML-DA schema. This plug-in can be used with the PI XML Interface to communicate with OPC XML-DA servers. This plug-in is in a file called PIXML_OPC.DLL.

Note: Neither this manual nor the plug-in are stand-alone products; they are to be used in conjunction with the PI XML Interface. This version of the plug-in requires 1.1.0.0 or above versions of the PI XML Interface.

Note: The value of [PIHOME] variable for the 32-bit interface will depend on whether the interface is being installed on a 32-bit operating system (C:\Program Files\PIPC) or a 64-bit operating system (C:\Program Files (x86)\PIPC).

The value of [PIHOME64] variable for a 64-bit interface will be C:\Program Files\PIPC on the 64-bit Operating system.

In this documentation [PIHOME] will be used to represent the value for either [PIHOME] or [PIHOME64]. The value of [PIHOME] is the directory which is the common location for PI client applications.

Note: Throughout this manual there are references to where messages are written by the interface which is the PIPC.log. This interface has been built against a of UniInt version (4.5.0.59 and later) which now writes all its messages to the local PI Message log.

Please note that any place in this manual where it references PIPC.log should now refer to the local PI message log. Please see the document UniInt Interface Message Logging.docx in the %PIHOME%\Interfaces\UniInt directory for more details on how to access these messages.

Reference Manuals

OSIsoft PI Server manuals

PI API Installation Instructions manual

UniInt Interface User Manual

Vendor Extensible Markup Language (XML) 1.0 (Second Edition)


OPC XML-DA specification (version 1.01)

Plug-in Specific Features

Several features of this product are unique to this plug-in. These features are detailed below.

Exception Reporting

For the OPC plug-in, the PI XML Interface handles exception reporting if the /sn command-line option is not specified. If it is specified, the interface will request that the XML server do the exception reporting by using the ExcDev attribute for each tag. If the ExcDev attribute is set to 0, then neither the interface nor the XML server will do any exception reporting. Additionally, /returnallitems can be used to force the XML server to return data after each scan. Other plug-ins may exhibit different behavior and the corresponding manual should be consulted.

Source of Timestamps

The OPC plug-in uses timestamps from the XML server, but if the /TS option is specified, local timestamps are used. For timestamps supplied by the OPC XML-DA server, the interface calculates the offset between the PI server and XML server and applies that correction to timestamps received from the XML server.

Output Points

The OPC plug-in supports output points.


Chapter 2. Principles of Operation

Overview of OPC XML-DA Servers and Clients

OLE for Process Control (OPC) is generally accepted as one of the popular industrial standards for data exchange between software components from different manufacturers. Currently, communication between clients and OPC DA servers uses Microsoft’s COM/DCOM technology. However, configuration of clients and OPC DA servers can be complex due to the security with DCOM. Moreover, it is required that the client machine and the OPC DA server reside on the same domain.

In order to overcome the limitations of DCOM, the OPC Foundation has established the OPC XML-DA specification which defines communication through the use of SOAP messages. In this manner, the server can be exposed as a web service and clients from different domains can communicate with the OPC XML-DA server. While this removes the complexity of DCOM security configuration, web services can potentially expose important information to any person connected to the Internet. Therefore, end-users are responsible for enabling and properly configuring the security features of their selected web server components. This may include enabling SSL capabilities to encrypt the data stream and restricting access to web services to authorized users.

Subscription Architecture

The design of the OPC XML-DA subscription employs a “polled-pull” style of subscription, in which the interface initiates a subscription and will issue periodic refresh requests. Moreover, as outlined in the OPC XML-DA specification (version 1.01), a controlled response mechanism has been implemented in order to simulate the callback capabilities of the original COM-based OPC DA design. In order to do this, two command-line parameters, /holdtime and /waittime, must be specified. If these parameters are not specified, their values default to zero. The /holdtime parameter instructs the server to hold off returning data until the specified absolute OPC XML-DA server time is reached. The /waittime parameter instructs the OPC XML-DA server to wait the specified duration after the /holdtime is reached before returning data if there are no changes to report. A change in one of the subscribed items, during this wait period, will result in the server returning immediately rather than completing the wait time. The following figure shows this mechanism.


Minimum time for service to

respond Maximum time for service to respond

Changes occurring during this time will result in a return at the end of Holdtime

Cur

rent

Tim

e

Hold Time Wait Time

Changes occurring during this time will result in an

immediate return

Communication with an OPC XML-DA Server

Since an OPC XML-DA server is exposed as a web service, communication is connectionless. The specification of the OPC XML-DA standard allows for buffering of data on the OPC XML-DA server itself. If communication to the OPC XML-DA server fails, and the tags are configured to enable buffering, and if the server supports buffering, then when communication is re-established, all data that was buffered by the OPC XML-DA server will be sent. However, because the OPC XML-DA server may need to buffer an unknown amount of data, the OPC XML-DA server may constrain the buffer to a fixed amount of data. This is typically done by dropping out the oldest data once the buffer reaches the maximum size.


Chapter 3. Installation Checklist

For those users who are familiar with running PI XML interface with the OPC Plug-in DLL, this checklist helps you get the PI XML interface running. If you are not familiar with the OPC Plug-in DLL for the PI XML Interface, you should return to this section after reading the rest of the manual in detail.

1. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)

2. Verify that PI-API and PI-SDK have been installed.

3. Install the PI XML interface.

4. Configure the PI XML Interface using the PI-Interface Configuration Utility which is the recommended way to configure the interface.

5. Configure PI points.

Location1 is the interface instance.Location2 specifies whether the tag is an input (0) or output tag (1).Location3 is the buffering flagLocation4 is the scan class; set to 1 for all tagsLocation5 is not used.ExDesc is not used.InstrumentTag is the item name.

6. Start the interface without buffering.

7. Verify data.

8. Stop interface, start buffering, start interface.


Chapter 4. Plug-in Installation and Administration

Locating Plug-in Directory

The PIXML_OPC.dll is installed in the PI XML interface directory in the plug-ins sub-directory. For example if the interface is installed in[PIHOME]\Interfaces\XML

then the DLL should be present in the corresponding plug-in directory in:[PIHOME]\Interfaces\XML\Plug-ins\OPC

The other plug-in DLLs are installed in their own separate sub-folders.

Configuring PI Tags

A detailed description for configuring tags can be found in the XML Interface user manual.

Upgrading Plug-in

If the plug-in is upgraded independent of the PI XML interface, it will be necessary to stop the PI XML interface, install the plug-in in the appropriate directory and then restart the interface according to the instructions in the XML Interface user manual.

Uninstalling Plug-In

In order to run the interface without the OPC plug-in, select another plug-in using the XML ICU control. If the ICU control is not being used, change the /DLL command-line parameter in the batch file, pixml.bat, and stop and restart the interface according to the instructions in the XML Interface user manual. Note that if the OPC plug-in is not used, the operation of the XML interface will change drastically depending on which new DLL is selected.


Chapter 5. Startup Command File

Configuring the Interface with PI ICU

Note: PI ICU requires PI 3.3 or greater.

The PI-Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. By configuring the interface with PI-ICU, the user makes it possible to recognize the interface, edit configurations, run and stop the interface. If the interface is configured by the PI-ICU, the batch file of the interface (pixml.bat) will be maintained by the PI-ICU and all configuration changes will be kept in that file. The procedure describing the necessary steps for using PI-ICU to configure the PI XML Interface is described in the XML Interface user manual.

Configuration Tab

XML ServerEnter the URL of the XML server. (/server)

Pre-Processing DLLSelect the path and name of the PIXML_OPC.dll from the drop-down list. (/dll)


OPC Plug-In Tab

After this is done, the OPC Plug-In tab appears, and the following options will be available for selection.

Locale ID <language. [-<country>]Specify the LocaleID in the text box so that it can be requested by the interface in communicating with the XML server. The ID can be found by consulting your XML server documentation.

The LocaleID is specified in the following format:<language>[-<country>]

Where <language> is the two-letter ISO 639 code for a language and <country> is the two-letter ISO 3166 code for the country. (/locale=)

Keep Alive MultiplierThe keep alive multiplier instructs the XML server how long to keep a subscription alive. The subscription is kept alive at a rate that is equal to X times the scan frequency. (/KEEP_ALIVE_MULT=X)

Subscription Rate RatioThe subscription rate ratio represents the number of values to obtain between each scan and can be used to increase data throughput by buffering values on the XML-DA Server. The XML-DA server may revise this value downwards automatically if it cannot support the data rate. (/SRR=x)

HoldTime (msec) before returning dataHoldtime instructs the XML server to hold off returning any value until the specified absolute XML server time (X) in milliseconds is reached. (/holdtime=X)

WaitTime before returning changesWaitime instructs the XML server to wait for the specified duration, X, after the holdtime is reached, before returning if there are no changes to report. Changes that occur during this time will be immediately reported to the interface. (/waittime=X).


Return all values for each scanUse the check-box to notify the XML server to return all values for each scan. (/returnallitems)

Connection Settings Tab

The fields on this tab provide the connection options for the interface. The PI XML interface with the OPC plug-in is designed to provide authentication options, as well the ability to connect through a proxy server. The following is a list of available selections from the PI-ICU.

Use SSL SecuritySpecify the use of SSL to encrypt communication between the server and the interface. Note that the XML server must support the use of SSL. (/USESSL).

Ignore Initial Subscription ResultsUsed to ignore the initial subscription results from the XML OPC DA Server. If the command-line option is specified, the initial subscription results will be ignored. (/ISR)

Connection Timeout (msec)Limit the time in milliseconds it takes to make an initial connection with the XML server. After a connection to the server has been established the timeout property applies (/CONNECTTIMEOUT=X).

Runtime Timeout (msec)Specify the timeout in milliseconds after a connection to the XML server has been established. Communication taking longer than this value will be dropped. The default value is 30,000 milliseconds. Not all plug-in DLLs support this command-line parameter (/TIMEOUT=X).

Authentication Settings -- Use AuthenticationA check in the click-box enables the possibility to choose an acceptable authentication mechanism supported by the XML server. (/AUTHSCHEME=BITMASK).

Authentication Settings -- Auth Scheme


Startup Command File

The value of the authentication scheme bitmask is displayed in the text field.

The various authentication schemes that are supported by the server can be selected by the group of check boxes: Basic Auth, ntlm Auth, Digest Auth, and Negotiate Auth. Many servers support one or more authentication schemes and the correct scheme must be chosen in order to ensure successful communication with the XML server.

Negotiate Auth and ntlm Auth are selected by default.

Authentication Settings -- UserSupply a username for authentication. (/AUTHUSER=NAME).

Authentication Settings -- PasswordSupply a password associated with the user for authentication. (/AUTHPASSWORD=PASSWORD).

Proxy Server -- Use Proxy ServerUse this click-box to enable options for connecting to a proxy server through which the interface will connect to the XML server. (/PROXYSERVER).

Proxy Server -- Proxy ServerSpecify the proxy server through which the interface will connect to the XML server. (/PROXYSERVER=SERVER)

Proxy Server -- Proxy UserSpecify a username for the proxy server. (/PROXYUSER=USER)

Proxy Server -- Proxy PasswordSupply a password associated with the user for the proxy server. (/PROXYPASSWORD=PASSWORD)

Additional ParametersEnter any additional parameters not currently supported by the XML Interface PI-ICU Control.

Command-line Parameters

Command-line parameters can begin with a / or with a -. For example, the /ps=M and -ps=M command-line parameters are equivalent.

For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.

Not all the options available to the PI XML interface are used and only the ones listed below are relevant when using this plug-in.

Note: The UniInt End User Document includes details about other command-line parameters, which may be useful.

Plug-in Specific Parameters

Parameter Description

/authpassword=<pwd>Optional

Used for authentication with the XML server. Use this option if the XML server has been configured to support authentication. It works in conjunction with the /authuser option. If the /authuser option is specified but this option is not, then an empty string will be passed as the password. Not all plug-in DLLs support this command line parameter.

/authscheme=#Optional

Enables you to choose an acceptable authentication mechanism that is supported by the XML server. The value of # corresponds to the following values.1 - basic authentication2 - ntlm authentication8 - digest authentication16 - negotiate authenticationNote that # is a bitmask so you can combine these values (bitwise OR) to enable multiple types of authentication. For example, to enable both basic and digest auth, set x to 9 (1+8=9). The default value for this property is 18 (ntlm and negotiate).

/authuser=<username>Optional

Used for authentication with the XML server. This option should only be used if the XML server has been configured to support authentication. Not all plug-in DLLs support this command line parameter.

/connecttimeout=#Optional

Limits the time (in milliseconds) it takes to make an initial connection with the XML server. After a connection to the server has been established the timeout property applies.

/dll=path\nameOptional

Specifies the path for the plug-in DLL.The default :<interface directory>\Plug-ins\OPC\PIXML_OPC.dll

/holdtime=#Optional

Instructs the XML server to hold off returning any value until the specified absolute XML server time (#) in milliseconds is reached. Not all plug-in DLLs support this command line parameter.




/isrOptionalDefault: Send initial subscription results to PI

Used to ignore the initial subscription results from the XML OPC DA Server. If the command-line option is specified, the initial subscription results will be ignored.

/keep_alive_mult=#Optional

Instructs the XML server how long to keep a subscription alive. The subscription is kept alive at a rate that is equal to # times the scan frequency. Not all plug-in DLLs support this command line parameter.

/locale=xOptional

Specifies the LocaleID to be requested by the interface in communicating with the XML server. Error information and data values of type ‘string’ in the response of a server can vary depending on LocaleID. The LocaleID is specified in the following format:<language>[-<country>]Where <language> is the two-letter ISO 639 code for a language and <country> is the two-letter ISO 3166 code for the country. In the event the XML server does not support the requested locale, the server will respond with a different LocaleID and a message will be written to the log file. Further information can be found in the OPC XML-DA specification (version 1.01). Not all plug-in DLLs support this command line parameter.

/proxypass=<pwd>Optional

Specifies the password used for proxy authentication. The default is an empty string. Not all plug-in DLLs support this command line parameter.

/proxyserver=xOptional

Identifies the proxy server (x) through which messages are sent and received. Use it if communication to the XML server is through a proxy server. This option may have one of the following values:<LOCAL_MACHINE> -- Indicates that the proxy configuration specified using the proxycfg utility is to be used. Use this setting when the interface is configured as a Windows service, and there is no "current user" with proxy settings.<CURRENT_USER> — Indicates that the Microsoft Internet Explorer proxy settings for the current user should be used. Use this setting for client programs run by a user.host[:port] – Indicates that a specific host and port should be used. Replace "host" with the DNS name or IP address of the proxy server. Replace "port" with the proxy port on that server. Omit ":port" to use the default port of "80". Use this setting if the proxy is known when the client program is created or when a client application provides a way for the user to specify a proxy configuration. Not all plug-in DLLs support this command line parameter.

/proxyuser=<username>Optional

Used for proxy authentication. The default is the value of the proxy server port shown in the Local Area Network (LAN) Settings dialog box in Microsoft Internet Explorer. To open this dialog box, on the Tools menu, point to Internet Options, select the Connections tab, and then click LAN Settings. Not all plug-in DLLs support this command line parameter.

/returnallitemsOptional

Instructs the XML server to return all values for each scan. For some plug-in DLL’s this option may do nothing.


/server=URLRequired

Specifies the URL of the XML server for the XML server. For example, the URL could be specified as:http://localhost:8080/XmlDaSampleServer/Da30Service.asmxFor some plug-in DLLs, this option could be used differently and the corresponding plug-in manual should be consulted. Note if this parameter has spaces, the value should be enclosed in quotes.

/snOptional

When this flag is specified on the command-line, all exception reporting by the interface is disabled, and the XML server will do the exception reporting using the excdev point attribute. If the excdev is set to 0, and this flag is specified, then all values will be returned from the XML server and neither the interface nor the server will do any exception reporting.

/srr=#Optional

Specifies the subscription rate ratio. The value of # represents the number of values to obtain between each scan and can be used to increase data throughput by buffering values on the XML-DA server. Not all plug-in DLLs support this command line parameter and XML-DA server may revise this value downwards automatically if they cannot support the data rate.

/timeout=#Optional

Specifies the timeout in milliseconds after a connection to the XML server has been established. Communication taking longer than this value will be dropped. The default value is 30,000 milliseconds. Not all plug-in DLLs support this command line parameter.

/usesslOptional

A Boolean value (True or False) that specifies the use of SSL to encrypt communication between the server and the interface. Note the XML server must support the use of SSL.

/waittime=#Optional

Instructs the XML server to wait for the specified duration, # milliseconds, after the holdtime is reached before returning if there are no changes to report. Changes that occur during this time will be immediately reported to the interface. Not all plug-in DLLs support this command line parameter.

General PI-XML Interface Parameters


/ec=#Optional

The first instance of the /ec parameter on the command-line is used to specify a counter number, #, for an I/O Rate point. If the # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without /ec=#explicitly defined will write to the same I/O Rate point. This means either explicitly defining an event counter other than 1 for each copy of the interface or not associating any I/O Rate points with event counter 1.For interfaces that run on Windows nodes, subsequent instances of the /ec parameter may be used by specific interfaces to keep track of various input or output operations. Subsequent instances of the /ec parameter can be of the form /ec*, where * is any ASCII character sequence. For example, /ecinput=10, /ecoutput=11, and /ec=12 are legitimate choices for the second, third, and fourth event counter strings.




/f=SS.## or/f=SS.##,SS.##or/f=HH:MM:SS.##or/f=HH:MM:SS.##,hh:mm:ss.##

Required

Note: For the File Reader Plug-In DLL, it is required that only one scan class be defined.The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), seconds (SS) and sub-seconds (##). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), seconds (ss) and sub-seconds (##). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds.Each instance of the /f parameter on the command-line defines a scan class for the interface. There is no limit to the number of scan classes that can be defined. The first occurrence of the /f parameter on the command-line defines the first scan class of the interface; the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on.Two scan classes are defined in the following example:/f=00:01:00,00:00:05 /f=00:00:07or, equivalently:/f=60,5 /f=7The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans occur at discrete moments in time according to the formula:scan times = (reference time) + n(frequency) + offsetwhere n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:07:05, the second scan would be at 05:08:05, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined.The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section “Performance Summaries” in the UniInt Interface User Manual.doc for more information on skipped or missed scans.Sub-second Scan ClassesSub-second scan classes can be defined on the command-line, such as/f=0.5 /f=00:00:00.1where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 of a second.Similarly, sub-second scan classes with sub-second offsets can be defined, such as/f=0.5,0.2 /f=1,0Wall Clock SchedulingScan classes that strictly adhere to wall clock scheduling are now possible. This feature is available for interfaces that run on Windows and/or UNIX. Previously, wall clock scheduling was possible, but not across daylight saving time. For example,


/f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight saving time), use /f=24:00:00,00:08:00,L. The ,L at the end of the scan class tells UniInt to use the new wall clock scheduling algorithm.

/host=host:portOptional

The /host parameter is used to specify the PI Home node. Host is the IP address of the PI Sever node or the domain name of the PI Server node. Port is the port number for TCP/IP communication. The port is always 5450. It is recommended to explicitly define the host and port on the command-line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults.Defaults:The default port name and server name is specified in the pilogin.ini or piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is found. Refer to the PI-API manual for more information about the piclient.ini and pilogin.ini files.

Examples:

The interface is running on a PI Interface Node, the domain name of the PI home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host parameters would be:/host=marvin/host=marvin:5450/host=206.79.198.30/host=206.79.198.30:5450

/id=xRequired

The /id parameter is used to specify the interface identifier.The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See Appendix A Error and Informational Messages in the XML Interface user manual for more information.UniInt always uses the /id parameter in the fashion described above. This interface also uses the /id parameter to identify a particular interface copy number that corresponds to an integer value that is assigned to Location1. For this interface, use only numeric characters in the identifier. For example,/id=1

/ps=xRequired

The /ps parameter specifies the point source for the interface. X is not case sensitive and can be any single or multiple character string. For example, /ps=P and /ps=p are equivalent. The length of X is limited to 100 characters by UniInt. X can contain any character except ‘*’ and ‘?’.The point source that is assigned with the /ps parameter corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source.If the PI API version being used is prior to 1.6.x or the PI Server version is prior to 3.4.370.x, the PointSource is limited to a single character unless the SDK is being used.




/SIOOptionalDefault: Send output values at interface startup and output tag edits.

The /sio parameter stands for “suppress initial outputs.” The parameter applies only for interfaces that support outputs. If the /sio parameter is not specified, the interface will behave in the following manner.When the interface is started, the interface determines the current Snapshot value of each output tag. Next, the interface writes this value to each output tag. In addition, whenever an individual output tag is edited while the interface is running, the interface will write the current Snapshot value to the edited output tag.This behavior is suppressed if the /sio parameter is specified on the command line. That is, outputs will not be written when the interface starts or when an output tag is edited. In other words, when the /sio parameter is specified, outputs will only be written when they are explicitly triggered.

/stopstator/stopatat=digstateDefault:/stopstat=”Intf shut”Optional

If /stopstat=digstate is present on the command line, then the digital state, digstate, will be written to each PI Point when the interface is stopped. For a PI 3 Server, digstate must be in the system digital state table. UniInt will use the first occurrence of digstate found in the table.If the /stopstat parameter is present on the startup command line, then the digital state “Intf Shut” will be written to each PI Point when the interface is stopped. For a PI 3 Server, digstate must be in the system digital state table. For a PI 2 Server, where there is only one digital state table available, digstate must simply be somewhere in the table. UniInt uses the first occurrence in the table.If neither /stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down.

Note: The /stopstat parameter is disabled If the interface is running in a UniInt failover configuration. Therefore, the digital state, digstate, will not be written to each PI Point when the interface is stopped. This prevents the digital state being written to PI Points while a redundant system is also writing data to the same PI Points. The /stopstat parameter is disabled even if there is only one interface active in the failover configuration.

Examples:/stopstat=shutdown/stopstat=”Intf Shut”The entire digstate value should be enclosed within double quotes when there is a space in digstate.

Sample PIXML.bat File

The following is an example file that exists in the

PIHOME\Interfaces\XML\Plug-Ins\OPC\ directory. REM=======================================================================REMREM pixml.batREMREM Sample startup file for the PI XML InterfaceREMREM======================================================================REM REM OSIsoft strongly recommends using PI ICU to modify startup files.REMREM Sample command lineREM

.\pixml.exe ^/ps=XML ^/id=1 ^/host=XXXXXX:5450 ^/f=00:00:05 ^/f=00:00:10 ^/f=00:00:30 /server=http://opcfoundation.org/XmlDaSampleServer/Service.asmx ^/dll=".\Plug-Ins\OPC\PIXML_OPC.dll" ^/stopstat="Intf Shut"

REMREM End of pixml.bat File

The above command line instructs the Interface to

service PI points with a PointSource of X and Location1 is 1,

define three scan classes with periods of 5, 10 and 30 seconds

connect to an XML server with this URL: http://opcfoundation.org/XmlDaSampleServer/Service.asmx

use the post-processing dll for the OPC XML-DA specification (version 1.01),

write Intf Shut to its list of points upon exit.

The installation program installs a sample command file named pixml.bat_new. If you are not using the PI-ICU, you should use this file as a template for your own pixml.bat.


Appendix A. Error and Informational Messages

A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id parameter on the startup command-line.

Message Logs

The location of the message log depends upon the platform on which the interface is running. See the UniInt Interface User Manual for more information.

Messages are written to [PIHOME]\dat\pipc.log at the following times.

When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points.

As the interface loads points, messages are sent to the log if there are any problems with the configuration of the points.

If the UniInt /dbUniInt parameter is found in the command-line, then various informational messages are written to the log file.

System Errors and PI Errors

System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions on Windows SystemsDescriptions of system and PI errors can be obtained with the pidiag utility:

\PI\adm\pidiag /e error_number


Appendix B. Terminology

To understand this interface manual, you should be familiar with the terminology used in this document.

BufferingBuffering refers to an interface node’s ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers.

N-Way BufferingIf you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI Servers however it does not guarantee identical archive records since point compressions attributes could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)

ICUICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use to configure PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.

You can configure an interface by editing a startup command file. However, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.

ICU ControlAn ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.

Interface NodeAn interface node is a computer on which

the PI API and/or PI SDK are installed, and

PI Server programs are not installed.

PI APIThe PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.


PI CollectiveA PI Collective is two or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.

PIHOMEPIHOME refers to the directory that is the common location for PI 32-bit client applications.

A typical PIHOME on a 32-bit operating system is C:\Program Files\PIPC.

A typical PIHOME on a 64-bit operating system is C:\Program Files (x86)\PIPC.

PI 32-bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME.

For example, files for the 32-bit Modbus Ethernet Interface are in

[PIHOME]\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory path. For example, ICU files in [PIHOME]\ICU.

PIHOME64PIHOME64 is found only on a 64-bit operating system and refers to the directory that is the common location for PI 64-bit client applications.

A typical PIHOME64 is C:\Program Files\PIPC.

PI 64-bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME64.

For example, files for a 64-bit Modbus Ethernet Interface would be found in

C:\Program Files\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory path. For example, ICU files in [PIHOME]\ICU.

PI Message LogThe PI message log is the file to which OSIsoft interfaces based on UniInt 4.5.0.x and later write informational, debug and error messages. When a PI interface runs, it writes to the local PI message log. This message file can only be viewed using the PIGetMsg utility. See the UniInt Interface Message Logging.docx file for more information on how to access these messages.

PI SDKThe PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.

PI Server NodeA PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.


PI SMTPI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a interface node.

Pipc.logThe pipc.log file is the file to which OSIsoft applications write informational and error messages. When a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.

PointThe PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.

A PI point does not necessarily correspond to a “point” on the foreign device. For example, a single “point” on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.

ServiceA Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.

The ICU allows you to configure a PI interface to run as a Service.

Tag (Input Tag and Output Tag)The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms “tag” and “point” interchangeably.

Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.


Appendix C. Technical Support and Resources

You can read complete information about technical support options, and access all of the following resources at the OSIsoft Technical Support Web site:

http://techsupport.osisoft.com (http://techsupport.osisoft.com)

Before You Call or Write for Help

When you contact OSIsoft Technical Support, please provide:

Product name, version, and/or build numbers

Computer platform (CPU type, operating system, and version number)

The time that the difficulty started

The log file(s) at that time

Help Desk and Telephone Support

You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table below to find the most appropriate number for your area. Dialing any of these numbers will route your call into our global support queue to be answered by engineers stationed around the world.

Office Location Access Number Local Language OptionsSan Leandro, CA, USA 1 510 297 5828 English

Philadelphia, PA, USA 1 215 606 0705 English

Johnson City, TN, USA 1 423 610 3800 English

Montreal, QC, Canada 1 514 493 0663 English, French

Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese

Frankfurt, Germany 49 6047 989 333 English, German

Manama, Bahrain 973 1758 4429 English, Arabic

Singapore 65 6391 181186 021 2327 8686

English, MandarinMandarin

Perth, WA, Australia 61 8 9282 9220 English


http://techsupport.osisoft.com/

Support may be provided in languages other than English in certain centers (listed above) based on availability of attendants. If you select a local language option, we will make best efforts to connect you with an available Technical Support Engineer (TSE) with that language skill. If no local language TSE is available to assist you, you will be routed to the first available attendant.

If all available TSEs are busy assisting other customers when you call, you will be prompted to remain on the line to wait for the next available TSE or else leave a voicemail message. If you choose to leave a message, you will not lose your place in the queue. Your voicemail will be treated as a regular phone call and will be directed to the first TSE who becomes available.

If you are calling about an ongoing case, be sure to reference your case number when you call so we can connect you to the engineer currently assigned to your case. If that engineer is not available, another engineer will attempt to assist you.

Search Support

From the OSIsoft Technical Support Web site, click Search Support.

Quickly and easily search the OSIsoft Technical Support Web site’s Support Solutions, Documentation, and Support Bulletins using the advanced MS SharePoint search engine.

Email-based Technical Support

[email protected]

When contacting OSIsoft Technical Support by email, it is helpful to send the following information:

Description of issue: Short description of issue, symptoms, informational or error messages, history of issue

Log files: See the product documentation for information on obtaining logs pertinent to the situation.

Online Technical Support

From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.

Using OSIsoft’s Online Technical Support, you can:

Enter a new call directly into OSIsoft’s database (monitored 24 hours a day)

View or edit existing OSIsoft calls that you entered

View any of the calls entered by your organization or site, if enabled

See your licensed software and dates of your Service Reliance Program agreements


mailto:[email protected]

Remote Access

From the OSIsoft Technical Support Web site, click Contact Us > Remote Support Options.

OSIsoft Support Engineers may remotely access your server in order to provide hands-on troubleshooting and assistance. See the Remote Access page for details on the various methods you can use.

On-site Service

From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service Visit.

OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more information.

Knowledge Center

From the OSIsoft Technical Support Web site, click Knowledge Center.

The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center on the Technical Support Web site.

The Search feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including user manuals, release notes, and white papers).

System Manager Resources include tools and instructions that help you manage: Archive sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server security, PI System sizing and configuration, PI trusts for interface nodes, and more.

Upgrades

From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.

You are eligible to download or order any available version of a product for which you have an active Service Reliance Program (SRP), formerly known as Tech Support Agreement (TSA). To verify or change your SRP status, contact your Sales Representative or Technical Support (http://techsupport.osisoft.com / ) for assistance.


http://techsupport.osisoft.com/

Technical Support and Resources

OSIsoft Virtual Campus (vCampus)

The OSIsoft Virtual Campus (vCampus) Web site offers a community-oriented program that focuses on PI System development and integration. The Web site's annual online subscriptions provide customers with software downloads, resources that include a personal development PI System, online library, technical webinars, online training, and community-oriented features such as blogs and discussion forums.

OSIsoft vCampus is intended to facilitate and encourage communication around PI programming and integration between OSIsoft partners, customers and employees. See the OSIsoft vCampus Web site, http://vCampus.osisoft.com (http://vCampus.osisoft.com) or contact the OSIsoft vCampus team at [email protected] for more information.

http://vCampus.osisoft.com/

Appendix D. Revision History

Date Author Comments

19-Apr-2005 MPKelly Fixed page numbering, TOC, headers and footers, and modified the ICU section.

18-Aug-2005 MPKelly Updated the TOC, ICU Control section, sample batch file and made minor other grammatical corrections. Made Final.

8-Dec-2005 ASing Updated the batch file for 1.2.0.0 release

16-Dec-2005 Chrys Version 1.2.0.0 Rev C: formatting; clarified ICU fields; alphabetized and made two tables of parameters

10-Aug-2007 SPatterson Version 1.2.1.0

17-Oct-2007 MKelly Version 1.2.1.0, Rev A, Fixed page layout, fixed headers and footers, updated TOC, saved as Final.

14-Sep-2010 RGilbert Version 1.4.1.0 Updated the version number.

16-Sep-2010 MKelly Version 1.4.1.0; Revision A; Updated title and copyright page, fixed headers and footers.

04-Feb-2011 SBranscomb Version 1.4.1.0, Revision B; Updated to Skeleton Version 3.0.31.

25-Jul-2012 SBranscomb Version 1.4.1.0, Revision C; Updated to Skeleton Version 3.0.35.


pi inteface for opc xml-da opc plug-in -...

Documents