PI Interface for OPC XML-DA File Reader...

PI Interface for OPC XML-DA File Reader 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 Interface for OPC XML-DA File Reader 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............................................................................................2Plug-in Specific Features...................................................................................2

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

Chapter 2. Principles of Operation................................................................................3

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.................................................................9

Configuration Tab....................................................................................9Plug-in Specific Parameters.............................................................................12General PI XML Interface Parameters.............................................................13Sample PIXML.bat File....................................................................................17

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

Appendix B. Debugging..............................................................................................21/DBDLL=1........................................................................................................21/DBDLL=2........................................................................................................21/DBDLL=4........................................................................................................21

Appendix C. Terminology...........................................................................................23

Appendix D. 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......................................................................................29On-site Service......................................................................................29


Knowledge Center.................................................................................29Upgrades...............................................................................................29OSIsoft Virtual Campus (vCampus).......................................................30

Appendix E. Revision History....................................................................................31


Chapter 1. Introduction

The PI XML interface reads XML data that conforms to the OPC XML-DA specification that is transported using the SOAP protocol. In order to handle other XML schemas and transport mechanisms, the PI XML interface supports the development of custom plug-in DLLs. To obtain XML data that exists as XML files, OSIsoft created the File Reader plug-in DLL, which can process XML documents that exist locally on the hard drive. In addition, the File Reader Plug-In DLL can do XSL transformations after reading the XML documents. Therefore, it is possible to use XML documents that do not conform to the OPC XML-DA schema, provided an XSLT document is written that does appropriate transformations, that is, that transform the source XML into an XML document that is compliant with the OPC XML-DA schema). This plug-in is in a file called PIXML_FileReader.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 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

It is not possible to request that exception reporting be performed by the XML server through the use of the /sn command-line option when using the File Reader plug-in, because the data is independently written to the files.

If the /sn command-line option is specified, the PI XML interface will not do any exception reporting.

The /returnallitems command-line option, which is typically used to force the XML server to return data after each scan, has no effect when this plug-in is being used.

Source of Timestamps

When the File Reader plug-in is being used, the timestamps must be specified in the XML files being read. However, the interface can ignore these timestamps if the /TS command-line option is specified, in which case the local timestamps will be used. For timestamps supplied in the XML files, the interface calculates the offset between the PI server and the local time on the machine where the XML files are being read and applies that correction to the timestamps received in the XML files.

Output Points

The File Reader plug-in supports output points. Data from PI output points will be written to a file corresponding to the WriteResponse extract of the OPC XML DA specification. The file is written to the path that is specified with the /output=path command-line option and the filename will correspond to the timestamp of the output in order to guarantee uniqueness. If no path is specified, the plug-in will use the directory where the interface executable is found. In addition, the /xslout=path command-line option can be used to transform the output so that it conforms to any schema.


Chapter 2. Principles of Operation

The File Reader plug-in provides a mechanism to read raw XML files, including XML files that are not compliant to the OPC XML DA schema. The plug-in forces the PI XML Interface to read files from a directory that is specified in the /server command-line option. The oldest file in the directory will be read during each scan and after the data is read, the file is renamed with a .old extension. By default, only files with an .xml extension will be read, although it is possible to override this through the use of the /mask command-line option. After reading the raw XML, it is possible to do an XSL transformation by specifying the path to an XSLT file through the use of the /xsl command-line option. The transformed XML is then passed on to the interface and it must be compliant with the OPC XML DA schema. A diagram outlining this process is shown below.

Raw XML Files Residing on local

file system

<xml>

<raw data>

<tag item=“Abc”

timestamp=“6-6-2004”>19.86

</tag>

…

</raw data>

</xml>

PIXML_FileReader_plugin.DLL

Plugin DLL applies XSL Transform to Raw XML

data if needed

PIXML interface receives OPC XML DA compliant data

PIXML Interface

XSL Transform

<xsl:stylesheetversion="1.0"

xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:templatematch="/">…

PI

Output points can also be configured to write data to XML files in a directory that is specified by the /output command-line option. The output files conform to the WriteResponse extract of the OPC XML-DA schema.


The format of the transformed XML files should conform to the ReadResponse extract of the OPC XML-DA schema, which is listed below. <?xml version="1.0"?><ReadResponse xmlns="http://opcfoundation.org/webservices/XMLDA/1.0/"><RItemList><Items ItemName="file/testA" Timestamp="2004-06-20T06:16:31.6718750-07:00">

<Value>14.467</Value></Items><Items ItemName="file/testB" Timestamp="2004-06-20T06:16:31.6718750-07:00">

<Value>15.467</Value></Items><Items ItemName="file/testA" Timestamp="2004-06-21T06:16:31.6718750-07:00">

<Value>17.467</Value></Items><Items ItemName="file/testC" Timestamp="2004-06-20T06:16:31.6718750-07:00">

<Value>16.467</Value></Items></RItemList></ReadResponse>

A more detailed description, including the schema definition, can be found at http://opcfoundation.org. If XSLT files are being used to transform the raw XML, it is highly recommended that the transformation be tested and validated before using with the File Reader plug-in.

The format of the transformed XML is fairly straightforward. Each item below the RItemList node corresponds to one data value. It is necessary to specify the ItemName attribute which should match to the InstrumentTag attribute of the corresponding PI tag. The Timestamp attribute is specified in the ISO8601 timestamp format. Note that multiple values for the same ItemName can be specified as long as a separate Items node is defined. In the above example, it can be seen that two values are specified for the “file/testA” ItemName. When multiple values are specified for the same ItemName, they should appear in chronological order to improve performance, although it is not necessary to group the nodes together. If multiple values are being sent, the Location3 field for the tag in question should be set to 0.

When using the File Reader plug-in, there should only be one scan class defined in the interface startup file. Moreover, it is necessary to configure all tags to use only one scan class. The interval of this scan class will define how often the plug-in polls the directory. After the file is read, the plug-in will compare the InstrumentTag fields for all the tags in the scan class to each ItemName attribute for all Items nodes in the transformed XML and will discard any Items nodes which have ItemName attributes that do not have a corresponding match. Further internal processing of the transformed XML will occur in order to conform to the SubscribeResponse and the SubscribePolledRefreshResponse extracts of the OPC XML-DA schema.


http://opcfoundation.org/

Chapter 3. Installation Checklist

For those users who are familiar with running PI XML interface with the File Reader Plug-in DLL, this checklist helps you get the PI XML interface running. If you are not familiar with the File Reader 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. The only interface-specific, required parameters are:

/server=URL defines the connection./xsl=path defines the XSLT file to read to do transformations. /output=path defines the location where outputs should be written./dll=path defines the location on the plug-in DLL.

5. Configure PI points.

Location1 is the interface instance.Location2 is specified whether the tag is an input or output tag.Location3 is the buffering flag. If multiple values are being sent, this value should be 0.Location4 is the scan class and only one scan class should be used. Therefore, this

should equal 1 for all input points.Location5 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_FileReader.dll is installed in the PI XML interface directory in the File Reader plug-ins sub-directory. For instance if the interface is installed in this folder:[PIHOME]\Interfaces\XML

then the DLL is present in the corresponding plug-in directory in:[PIHOME]\Interfaces\XML\Plug-ins\File Reader

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

Configuring PI Tags

A detailed description for configuring tags can be found in the XML Interface to the PI System manual. However, when using the File Reader Plug-in DLL, there are a few notable differences that should be adhered to.

All tags MUST have Location4 = 1 to be in the only scan class.

All tags should support buffering by setting Location3 = 0.

The InstrumentTag attribute should correspond to the ItemName attribute for the appropriate Items node in the transformed XML.

Upgrading Plug-in

If the plug-in is upgraded independent of the PI XML interface, it is 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 this plug-in, use the PI ICU program to change the plug-in DLL to use. Or, alternately, delete the /DLL command-line parameter from the batch file, pixml.bat. This causes the PI XML Interface to use the PIXML_OPC.dll instead. Stop and restart the interface according to the instructions in the XML Interface user manual. Note that if the File Reader plug-in is not used, the operation of the XML interface changes depending on the new Plug-in DLL that is selected.


Chapter 5. Startup Command File

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.

The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the interface 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 Server:Enter the path to the files that the interface will process. (/server)


Pre-Processing DLL:Select the path and name of the PIXML_FileReader.dll from the drop-down list. (/dll)

File Reader Plug-in Tab

After the plug-in path and name have been selected, the File Reader Plug-In tab appears and the following options are available for selection.

Purge timelimit for *.OLD files:Any *.old files older than the time specified in the text box are deleted on each scan. The format of the time string should be a number followed by a one-digit letter, which can be either h for hours, m for minutes, s for seconds, or d for days. For example, all files that are older than two days would are deleted if 2d is used (/purge=2d).

FileName Mask:Specify the mask to be used when reading files from the directory location specified in the XML Server field on the Configuration tab. For example, in order to read all files with .XML as the filename extension, enter *.XML in this field. (/mask)

XSLT Trans. Filespec (.xsl):Enter the path and filename for the XSLT file that is used to transform the raw XML into OPC XML-DA compliant XML for the interface to read. Use the Browse button to locate the XSLT file. (/xsl=path\filename)


XSLT Output Trans. Filespec:Specify the path and filename of the XSLT file that is used to transform output data from OPC XML-DA compliant XML format into any XML format. If this parameter is not specified, no XSLT transformation is done. Use the Browse button to locate the XSLT file. (/xslout=path\filename)

XSLT Output File Path:Specify the path where the output files should be written. This parameter is used in conjunction with output points. Use the Browse button to locate the folder. (/output=path)

XML Schema Filespec (.xsd):This specifies the path and filename of the schema file that is used to validate the XML format read from the files. If this argument is not specified, no validation is done. Use the Browse button to locate the XML schema file. (/xsd=path\filename)

Retry files not processedCheck this box to tell the interface not to mark files as old when they cannot be read by the plug-in. They will be reprocessed during the next scan. (/retry)

Debug Settings -- Log message when XML files are found:Selecting this check box causes messages to be written to the pipc.log file when XML files are found. (/dbdll=1)

Debug Settings -- Write content of XSLT file during initialization:Selecting this check box forces the File Reader plug-in to send the entire contents of the XSLT file being read during initialization of the DLL to the pipc.log file. Long XSLT files may be truncated. (/dbdll=2)

Debug Settings -- Log XML being read after being transformed: Selecting this check box causes the File Reader plug-in to log the XML being read from input files after being transformed with an XSLT file. This can be helpful in creating and debugging XSLT files for input. The XML that is written to the pipc.log file should conform to the ReadResponse extract of the OPC XML-DA schema as discussed in section Principles of Operation. (/dbdll=4)

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


Startup Command File

Plug-in Specific Parameters

Parameter Description

/dbdll=flagOptionalDefault: No plug-in debugging

Debugging flag used to print plug-in-level debug messages. See Appendix B for more information.

/dll=path\filename

Optional

Specifies the path and filename for the plug-in DLL and should point to the File Reader plug-in. The default for this location is:<interface directory>\Plug-ins\File Reader\PIXML_FileReader.dll

/ignore_offsetOptionalDefault: Use time offsets

Forces the interface to ignore any offsets between the PI home node and the interface node.

/mask=file.extOptionalDefault: /mask=*.xml

Specifies the mask to use when reading files from the directory specified by the /server command-line option. The asterisk (*) and the question mark (?) are acceptable wildcard characters.

/output=pathRequired if using output points

Specifies the path where the output files are written. This parameter is used in conjunction with output points.

/purge=timeOptionalDefault: 10h

Any *.old files older than the time specified are deleted on each scan. The format of the time string should be a number followed by a one-digit letter, which can be either h for hours, m for minutes, s for seconds, or d for days. For example, all files that are older than 2 days are deleted if /purge=2d is used.

/retryOptionalDefault: False

When the /retry parameter is present, files that cannot be read by the plug-in will not be marked as old and will be reprocessed during the next scan. This option could be useful in a situation where very large files are being copied to the target directory and are therefore not valid until the copy operation has completed. Use this option with caution as data retrieval will halt until the error condition within the file is cleared.

/server=pathRequired

This parameter tells the interface the path where the XML files reside. For example, the path could be specified as:C:\PIPC\Interfaces\XML\Plug-ins\File Reader\FilesFor other plug-in DLLs, this option could be used differently and the corresponding plug-in manual should be consulted.

/snOptionalDefault: Interface does the exception reporting

When this parameter is specified on the command-line, all exception reporting by the interface is disabled.Note: It is not possible to have the XML server to do any exception reporting, unlike other plug-in DLLs.

/xsd=path\filenameOptionalDefault: No validation

Specifies the path and filename for the XML schema file that is used to validate the XML that is read from the files. If this argument is not specified then no validation will be done.

/xsl=path\filenameOptionalDefault: No transformation

Specifies the path and filename for the XSLT file that is used to transform the raw XML into OPC XML-DA compliant XML. If this argument is not specified then no XSLT transformation is done.

Parameter Description

/xslout=path\filenameOptionalDefault: No XSLT transformation done

Specifies the path and file name for the XSLT file that is used to transform outputted OPC XML-DA compliant XML into any kind of XML. If this argument is not specified then no XSLT transformation is done.

/pxOptionalDefault: No PX handling

A special switch to deal with Pemex incomplete XML files for use with the WITSML transform. This switch should NOT be used by anyone other than for Pemex.

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, every interface that is running without /ec=# explicitly defined will write to the same I/O Rate point. Either explicitly define an event counter other than 1 for each instance of the interface or do not associate any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in section I/O Rate Point in the XML Interface user manual.

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

Required for reading scan-based inputs

Note that 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 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:portRequired

The /host parameter is used to specify the PI Home node. Host is the IP address of the PI Server 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.Examples:

The interface is running on a 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 instance number that corresponds to an integer value that is assigned to one of the Location code point attributes, most frequently 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 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.

/sioOptional

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.



/stopstat=digstateor/stopstat

/stopstat only is equivalent to/stopstat="Intf Shut"

OptionalDefault = no digital state written at shutdown.

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 PI3 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.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 as defined in the UniInt Failover Configuration chapter of the XML Interface user manual. 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 must be enclosed within double quotes when there is a space in digstate.

/sync_readOptionalDefault: Asynchronous reads

Forces the interface to use synchronous reads instead of asynchronous reads. Note that this parameter should always be used for the File Reader plug-in for optimal performance.

Sample PIXML.bat File

The following is an example file that exists in the PIHOME\Interfaces\XML\Plug-Ins\File Reader\ 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 ^/f=00:00:30 ^/host=XXXXXX:5450 ^/server="c:\XMLFiles\testfiles" ^/dll=".\Plug-Ins\File Reader\PIXML_FileReader.dll" ^/xsl="c:\XSLT\process.xsl"^/xslout="c:\outputs\test.xsl" ^/output="c:\output files" ^/stopstat="Intf Shut"

REMREM End of pixml.bat File

The above command line tells the Interface to:

service PI points whose PointSource is XML and Location1 is 1.

connect to the PI 3 PI Server, “XXXXXX”.

use the PIXML_FileReader.dll to process data.

defines one scan class with a period of 30 seconds.

read files from a directory whose location is c:\XMLFiles\testfiles.

write files for output points to a directory whose location is c:\output files\.

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, 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 DescriptionsDescriptions of system and PI errors can be obtained with the pidiag utility:

\PI\adm\pidiag /e error_number


Appendix B. Debugging

The debug parameter is included to assist in understanding problematic or unexplained behavior, such as duplicate values or invalid timestamps. Use of the debug parameter should be limited to short periods of time. The parameter itself is actually a bit mask, which means you can set more than one option at the same time. A value of /DBDLL=5 is the same as /DBDLL=1 and /DBDLL=4. Here are the possible settings and what they do:

/DBDLL=1

This setting will cause messages to be written to the pipc.log file when XML files are found.

/DBDLL=2

This setting will force the File Reader plug-in to output the entire contents of the XSLT file being read during initialization of the DLL to the pipc.log file. Long XSLT files could be truncated.

/DBDLL=4

This setting will cause the File Reader plug-in to log the XML being read from input files after being transformed with an XSLT file, which can be helpful in creating and debugging XSLT files for inputs. The XML that is written to the pipc.log file should conform to the ReadResponse extract of the OPC XML-DA schema as discussed in section Principles of Operation.


Appendix C. 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 D. 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 E. Revision History

Date Author Comments

11-Aug-2004 ASingh Version 1.0.0.0 Rev A: Added purge command-line option. Ready for release.

08-Sep-2004 Chrys Version 1.0.0.0 Rev B: fixed some grammar; changed some headings; fixed page numbers; accepted all changes; made final

24-Oct-2004 ASingh Added section describing ICU control.

24-Nov-2004 MPKelly Fixed Sample Bat file (formatting and quotes in the correct place), Accepted all changes and made final.

01-Dec-2004 MPKelly Fixed directory references in several places.

03-Jan-2005 ASingh Added /XSLout and /DBDLL descriptions.

04-Jan-2005 ASingh Added /mask description.

19-Jan-2005 ASingh Add /xsd description

12-Apr-2005 MPKelly Added new screenshots for ICU Control. Also rearranged the sample batch file to conform to required and optional as stated in the command-line parameters section. Updated copyright page.

13-Jul-2005 ASingh Version 1.1.0.0 release.

17-Aug-2005 MPKelly Made changes to the sample batch file and screenshots for the ICU Control.

22-Aug-2005 ASingh Updated with MPK revisions and addressed his 3 comments.

30-Aug-2005 MPKelly Made Final.

08-Dec-2005 ASingh Version 1.2.0.0 Rev A: Updated .bat file for 1.2.0.0 release

16-Dec-2005 Chrys Version 1.2.0.0 Rev C: Clarified ICU fields; formatting;

10-Jan-2005 Chrys Version 1.2.0.0 Rev D: Fixed document properties

10-Aug-2007 SPatterson Version 1.2.1.0, updated to current skeleton

28-Aug-2007 /17-Oct-2007

Janelle/MKelly

Version 1.2.1.0, Rev A, updated ICU screen shots, alphabetized command line parameter table, fixed headers, updated TOC, fixed page numbering, fixed headers and footer, and saved as Final.

22-Oct-2007 SPatterson Version 1.2.1.0, Rev B: Clarified sections in Principles of Operation

3-Jun-2008 ASingh Version 1.2.1.1: Updated with new /retry command line option

14-Sep-10 RGilbert Version 1.4.1.0, Updated the version number.

16-Sep-2010 MKelly Version 1.4.1.0, Revision A, Updated copyright page and title page also screenshots.


Date Author Comments

26-Jul-2012 SBranscomb Version 1.4.1.0 Revision B; Updated to Skeleton Version 3.0.35.


PI Interface for OPC XML-DA File Reader...

Documents

Transcript of PI Interface for OPC XML-DA File Reader...