tcpresponse interface to the pi...

TCPResponseInterface to the PI System

Version 1.1.6.0

How to Contact UsOSIsoft, Inc. 777 Davis St., Suite 250San Leandro, CA 94577 USA

Telephone(01) 510-297-5800 (main phone)(01) 510-357-8136 (fax) (01) 510-297-5828 (support phone)

[email protected]

Houston, TX Johnson City, TN Mayfield Heights, OHPhoenix, AZ Savannah, GASeattle, WAYardley, PA

Worldwide Offices

OSIsoft AustraliaPerth, AustraliaAuckland, New Zealand

OSI Software GmbH Altenstadt, Germany

OSI Software Asia Pte Ltd.Singapore

OSIsoft Canada ULCMontreal, Canada

OSIsoft, Inc. Representative OfficeShanghai, People’s Republic of China

OSIsoft Japan KKTokyo, Japan

OSIsoft Mexico S. De R.L. De C.V.Mexico City, Mexico

Sales Outlets and Distributors Brazil Middle East/North Africa Republic of South Africa Russia/Central Asia

South America/Caribbean Southeast Asia South Korea Taiwan

www.osisoft.com

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.

RESTRICTED RIGHTS LEGENDUse, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Unpublished – rights reserved under the copyright laws of the United States.

© 2001-2008 OSIsoft, Inc. PI_TCPResponse.doc

http://www.osisoft.com/

mailto:[email protected]

Table of Contents

Introduction....................................................................................................................1Reference Manuals......................................................................................................1

Supported Features......................................................................................................2

Diagram of Hardware Connection................................................................................4

Principles of Operation.................................................................................................5Overview......................................................................................................................5

Specific Operations......................................................................................................6

Indirect DNS Server Connection...............................................................................6

FTP Server...............................................................................................................6

HTTP Server.............................................................................................................7

SMTP Server............................................................................................................7

Generic TCP Server.................................................................................................8

POP3 Server.............................................................................................................8

IMAP Server.............................................................................................................8

PI Server...................................................................................................................9

Direct DNS Server Connection.................................................................................9

Web Page Loading Time..........................................................................................9

Installation Checklist...................................................................................................13

Interface Installation....................................................................................................15Naming Conventions and Requirements....................................................................15

Interface Directories...................................................................................................16

PIHOME Directory Tree..........................................................................................16

Interface Installation Directory................................................................................16

Interface Installation Procedure..................................................................................16

Installing Interface as a Windows Service..................................................................16

Installing Interface Service with PI ICU...................................................................16

Installing Interface Service Manually......................................................................21

Digital States................................................................................................................23

TCP Response Interface to the PI System iii

PointSource..................................................................................................................25

PI Point Configuration.................................................................................................27Point Attributes...........................................................................................................27

Tag.........................................................................................................................27

PointSource............................................................................................................27

PointType...............................................................................................................27

Location1................................................................................................................28

Location2................................................................................................................28

Location3................................................................................................................29

Location4................................................................................................................29

Location5................................................................................................................29

InstrumentTag........................................................................................................30

ExDesc...................................................................................................................35

Scan.......................................................................................................................36

Shutdown................................................................................................................37

Performance Point Configuration...............................................................................39Configuring Performance Points with PI ICU (Windows)............................................39

Configuring Performance Points Manually.................................................................40

I/O Rate Point Configuration.......................................................................................41Monitoring I/O Rates on the Interface Node...............................................................41

Configuring I/O Rate Tags with PI ICU (Windows).....................................................41

Configuring I/O Rate Tags Manually..........................................................................43

Configuring PI Point on the PI Server.....................................................................43

Configuration on the Interface Node.......................................................................43

Startup Command File.................................................................................................45Configuring the Interface with PI ICU.........................................................................45

Manual Maintenance of the Startup Command File...................................................47

Command-line Parameters.........................................................................................48

Sample PITCPResp.bat File.......................................................................................51

Interface Node Clock...................................................................................................53

Security.........................................................................................................................55

Starting / Stopping the Interface on Windows...........................................................57

TCP Response Interface to the PI System iv

Starting Interface as a Service...................................................................................57

Stopping Interface Running as a Service...................................................................57

Buffering.......................................................................................................................59Configuring Buffering with PI ICU (Windows).............................................................59

Configuring Buffering Manually..................................................................................63

Example piclient.ini File..............................................................................................64

Appendix A: Error and Informational Messages.......................................................65Message Logs............................................................................................................65

System Errors and PI Errors.......................................................................................65

Appendix B: Troubleshooting.....................................................................................67Location5....................................................................................................................67

Common problems.....................................................................................................69

Appendix C: Acknowledgments.................................................................................71CURL..........................................................................................................................71

OpenSSL....................................................................................................................71

Revision History...........................................................................................................75

TCP Response Interface to the PI System v

IntroductionOSIsoft’s PI TCPResponse Interface program measures the availability and response times of various essential services that are part of a TCP/IP network. In particular, PI TCPResponse allows the user to determine the response times of

HTTP (Web) servers;

SMTP, POP3, and IMAP (mail) servers;

FTP servers;

DNS (name resolution) servers;

Microsoft Windows NT/2000/XP Terminal Servers; and

OSIsoft’s PI Servers.

This interface program also obtains the actual result (and not the response time) of a DNS operation. Finally, this Interface determines the time it takes to load a particular page on a Web server that requires username/password authentication.

PI TCPResponse stores these response times into OSIsoft’s PI Server. So, users can have access to long-term historical data as well as short-term current information regarding the performance of various servers. Therefore, PI TCPResponse assists network managers in proactively managing their networks.

The PI TCPResponse Interface program runs on Windows NT 4.0 SP 6, Windows 2000, Windows XP, or Windows 2003 Server computers. Unless otherwise noted, the remainder of this document uses the term "Windows" to refer to all these versions.

PI TCPResponse requires PI Server version 3.2 or higher. However, OSIsoft strongly recommends the use of PI Server v3.4.370.x (or higher) together with PI API v1.6 (or higher). The reason is that a PI point's InstrumentTag attribute often will need to hold more than 32 characters.

The Interface does not require any special hardware. A standard network interface card on the Windows machine is sufficient.

The direction of data flow is uni-directional; the Interface supports input PI points only.

The Interface does not support UniInt failover.

Reference Manuals

OSIsoft PI Server manuals

PI API Installation manual

UniInt Interface User Manual

TCP Response Interface to the PI System 1

Supported FeaturesFeature Support

Part Number PI-IN-OS-TCP-NTI

* Platforms Windows NT 4.0 SP6/ 2000 / XP / 2003

APS Connector No

Point Builder Utility Yes

ICU Control Yes

PI Point Types Float16 / Float32 / Float64 / Int16 / Int32 / String

Sub-second Timestamps Yes

Sub-second Scan Classes Yes

Automatically Incorporates PI Point Attribute Changes

Yes

Exception Reporting Yes

Outputs from PI No

Inputs to PI: Scan-based / Unsolicited / Event Tags

Scan-based / Event Tags

Supports Questionable Bit No

Supports Multi-character PointSource Yes

Maximum Point Count Maximum point count of PI Server

* Uses PI SDK No

PINet String Support No

* Source of Timestamps PI Server machine

History Recovery No

* UniInt-based Disconnected Startup SetDeviceStatus

YesYesYes

Failover No

Vendor Software Required on PI Interface Node / PINet Node

No

Vendor Software Required on Foreign Device

No

Vendor Hardware Required No

Additional PI Software Included with Interface

No

Device Point Types Not applicable

Serial-Based Interface No

* See paragraphs below for further explanation.


PlatformsThe Interface is designed to run on the above mentioned versions of the Microsoft Windows operating systems and greater. Windows NT 4.0 requires Service Pack 6.

Please contact OSIsoft Technical Support for more information.

Uses PI SDKThe PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface does not specifically make PI SDK calls.

Source of TimestampsThe clock on the computer running the PI Server provides the source of the timestamps for the data sent by PI TCPResponse. The Interface writes a timestamp that reflects the time at which it started the response time measurement.

UniInt-basedUniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers, and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt Interface User Manual is a supplement to this manual.

Disconnected Start-UpThe PI TCPResponse interface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the interface without a connection to the PI server. This functionality is enabled by adding /cachemode to the list of start-up parameters or by enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt Disconnect startup.

SetDeviceStatusFor a Health Tag whose Extended Descriptor attribute contains [UI_DEVSTAT], the Interface writes the following values:

a) "1 | Starting" – the Interface has started.

b) "Good" – the Interface has started successfully and is ready to measure response times; or, for all the points in the current scan class, the Interface has successfully connected to the service (e.g., FTP, HTTP) for which it needs to measure response time.

c) "3 | n device(s) in error" – for at least one of the points in the current scan class, the Interface cannot connect to the service (e.g., FTP, HTTP) for which it needs to measure response time.

d) "4 | Intf Shutdown" – the Interface has shut down.

This device status Health Tag does not apply to points that measure name server response (Location2 set to 1 or 10).


Introduction

Please refer to the UniInt Interface User Manual file for more information on how to configure Health Tags.

Diagram of Hardware Connection

4

Principles of OperationPI TCPResponse measures the response time of various services that are part of a TCP/IP network. In particular, the PI TCPResponse Interface program determines the response time of

HTTP (Web) servers;

SMTP, POP3, and IMAP (mail) servers;

FTP servers;

DNS (name resolution) servers;

Microsoft Windows NT/2000/XP Terminal Servers; and

PI Servers

In addition, PI TCPResponse also stores the actual result (and not the response time) of a DNS operation. Finally, the Interface determines the time it takes to load a particular page on a Web server that requires username/password authentication.

OverviewIn general, the PI TCPResponse Interface measures the response time of a particular service by

sending a connection request to the appropriate TCP port of the machine on which the service resides,

waiting for the appropriate response message from the server machine.

For example, the Interface measures the response time of the HTTP server www.somecompany.com by sending a connection request to TCP port number 80 of the machine named www.somecompany.com. PI TCPResponse then waits for a connection confirmation message. The time interval between the sending of the connection request and the receipt of the connection confirmation is the response time.

If the Interface does not receive a response within a specified time limit, it writes the digital state I/O Timeout. However, PI TCPResponse does not wait for a service to respond or to time out before it performs the next measurement. For example, the user configures 3 points so that the Interface measures FTP response times to 3 FTP servers whose IP addresses are, respectively,

192.168.100.11

192.168.100.12

192.168.100.13

PI TCPResponse sends three FTP connection requests, one right after the other. That is, the Interface does not wait until the response time measurement for 192.168.100.11 has completed before it sends a connection request to the other two machines.

A value of 0 for a point means that the measured response time is less than 1 millisecond.


Specific Operations

Indirect DNS Server ConnectionFor points with Location2 set to 1, the Interface indirectly measures DNS Server response times of the default nameserver. To find out the IP address of this nameserver, use the nslookup at the Windows command prompt. For example,C:> nslookupAddress: 192.168.100.45

Entries in the InstrumentTag determine whether the Interface performs a hostname to IP address lookup (for example, INPUT=www.anothercompany.com in the InstrumentTag) or an IP address to hostname lookup (for example, INPUT=192.168.10.100 in the InstrumentTag). The Interface uses the function gethostbyname() for the former and gethostbyaddr() for the latter.

The response time measured by the Interface is the amount of time required for these functions to complete. If these functions fail, the Interface writes the value Bad Input. If the Interface does not receive a reply within a user-specified timeout duration, it write I/O Timeout.

If the PI point is of type String, PI TCPResponse writes the value of the translation; for example, 192.168.10.100. Otherwise, PI TCPResponse writes the response time value.

However, the Windows operating system caches the results from gethostbyname() and gethostbyaddr(). In addition, these functions will not directly connect to the default nameserver if the HOSTS file (located typically in C:\Windows\System32\drivers\etc) contains the necessary information for hostname/IP address translation. So, in order to accurately measure DNS Server response time, the user should use the direct DNS Server Connection operation (described later).

FTP ServerThe Interface measures FTP Server response times for points with Location2 set to 2.

PI TCPResponse connects to the FTP port of the specified machine (for example, DEVICE=www.somecompany.com in the InstrumentTag). The FTP port is either the default (port number 21) or a user-specified (via PORT= in the InstrumentTag) port. After establishing the connection, the Interface waits for the FTP server to send a message that contains the text:

220That is, PI TCPResponse performs a substring search for 220 in the received reply.

The reason is that RFC 959 states:Under normal circumstances, a server will send a 220 reply, "awaiting input", when the connection is completed. The user should wait for this greeting message before sending any commands.

The user can tell the Interface to perform a substring search for another text string by specifying the case-sensitive string via REPLY= in the InstrumentTag. (The keyword REPLY= itself is not case sensitive.)

The response time measured by the Interface is the amount of time required, starting from the connection request, for the Interface to receive the message containing 220. If


the Interface does not receive a message containing 220, it writes the value Bad Input. If the Interface does not receive a reply within a user-specified timeout duration, it write I/O Timeout.

HTTP ServerThe Interface measures HTTP Server response times for points with Location2 set to 3.

PI TCPResponse connects to the HTTP port of a specified machine (for example, DEVICE=www.somecompany.com in the InstrumentTag). The HTTP port is either the default (port number 80) or a user-specified (via PORT= in the InstrumentTag) port. After establishing the connection, the Interface sends the following message to the HTTP server:

HEAD / HTTP/1.1\r\n Host: www.somecompany.com\r\n \r\nwhere \r is the ASCII character whose decimal code is 13 and \n is the ASCII character whose decimal code is 10. PI TCPResponse then waits for the HTTP server to send a message that contains the (case-sensitive) ASCII text:

HTTP/1.1

That is, PI TCPResponse performs a case-sensitive substring search for HTTP/1.1 in the received reply.

The user can tell the Interface to perform a substring search for another text string by specifying the case-sensitive string via REPLY= in the InstrumentTag. (The keyword REPLY= itself is not case sensitive.)

The response time measured by the Interface is the amount of time required, starting from the connection request, for the Interface to receive a response message containing HTTP/1.1. If the Interface does not receive a message containing HTTP/1.1, it writes the value Bad Input. If the Interface does not receive a reply within a user-specified timeout duration, it write I/O Timeout.

SMTP ServerThe Interface measures SMTP Server response times for points with Location2 set to 4.

PI TCPResponse connects to the SMTP port of the specified machine (for example, DEVICE=mail.somecompany.com in the InstrumentTag). The SMTP port is either the default (port number 25) or a user-specified (via PORT= in the InstrumentTag) port. After establishing the connection, the Interface waits for the SMTP server to send a message that contains the text:

220That is, PI TCPResponse performs a substring search for 220 in the received reply.

The reason is that RFC 2821 defines a status code of 220 as Service Ready. The user can tell the Interface to perform a substring search for another text string by specifying the case-sensitive string via REPLY= in the InstrumentTag. (The keyword REPLY= itself is not case sensitive.)

The response time measured by the Interface is the amount of time required, starting from the connection request, for the Interface to receive the message containing 220. If the Interface does not receive a message containing 220, it writes the value Bad Input.


Principles of Operations

If the Interface does not receive a reply within a user-specified timeout duration, it write I/O Timeout.

Generic TCP ServerThe Interface measures generic TCP server response times for points with Location2 set to 5.

PI TCPResponse connects to the user-specified (via PORT= in the InstrumentTag) port of the specified machine (for example, DEVICE=machine.somecompany.com in the InstrumentTag). The Interface then waits for the server to accept the connection.

The response time measured by the Interface is the amount of time required for the connection to be established. If the connection is rejected, the Interface writes the value Bad Input.

POP3 ServerThe Interface measures POP3 Server response times for points with Location2 set to 7.

PI TCPResponse connects to the POP3 port of the specified machine (for example, DEVICE=mail.somecompany.com in the InstrumentTag). The POP3 port is either the default (port number 110) or a user-specified (via PORT= in the InstrumentTag) port. After establishing the connection, the Interface waits for the POP3 server to send a message that contains the text:

+OKThat is, PI TCPResponse performs a case-sensitive substring search for +OK in the received reply.

RFC 1939 indicates that +OK is a positive status indication. The user can tell the Interface to perform a substring search for another text string by specifying the case-sensitive string via REPLY= in the InstrumentTag. (The keyword REPLY= itself is not case sensitive.)

The response time measured by the Interface is the amount of time required, starting from the connection request, for the Interface to receive the message containing +OK. If the Interface does not receive a message containing +OK, it writes the value Bad Input. If the Interface does not receive a reply within a user-specified timeout duration, it write I/O Timeout.

IMAP ServerThe Interface measures IMAP Server response times for points with Location2 set to 8.

PI TCPResponse connects to the IMAP port of the specified machine (for example, DEVICE=mail.somecompany.com in the InstrumentTag). The IMAP port is either the default (port number 143) or a user-specified (via PORT= in the InstrumentTag) port. After establishing the connection, the Interface waits for the IMAP server to send a message that contains the text:

* OKThat is, PI TCPResponse performs a case-sensitive substring search for "* OK" in the received reply.

RFC 2060 indicates that "* OK" is a positive status indication. The user can tell the Interface to perform a substring search for another text string by specifying the case-

8

sensitive string via REPLY= in the InstrumentTag. (The keyword REPLY= itself is not case sensitive.)

The response time measured by the Interface is the amount of time required, starting from the connection request, for the Interface to receive the message that contains "* OK". If the Interface does not receive a message containing "* OK", it writes the value Bad Input. If the Interface does not receive a reply within a user-specified timeout duration, it write I/O Timeout.

PI ServerThe Interface measures PI server response times for points with Location2 set to 9.

PI TCPResponse connects to the PI server port of the specified machine (for example, DEVICE=piserver.somecompany.com in the InstrumentTag). The PI port is either the default (port number 5450) or a user-specified (via PORT= in the InstrumentTag) port. After establishing the connection, the Interface sends a low-level message that simulates a PI API connection. The Interface then waits for a response from the PI server.

The response time measured by the Interface is the amount of time required, starting from the simulated PI API connection, to the time that the PI server acknowledges the connection. If the Interface encounters errors during this sequence, it writes the value Bad Input. If the Interface does not receive a reply within a user-specified timeout duration, it write I/O Timeout.

Direct DNS Server ConnectionThe Interface directly measures DNS Server response times for points with Location2 set to 10. This operation is available only if the Interface runs on Windows XP.

PI TCPResponse invokes the Windows API function DnsQuery() to connect to port 53 of the specified machine (for example, DEVICE=192.168.10.20 in the InstrumentTag). The Interface uses the value of the keyword INPUT in the InstrumentTag (for example, INPUT=www.anothercompany.com) as the first parameter to DnsQuery(). That is, the Interface queries 192.168.10.20 for the IP address of www.anothercompany.com.

The response time measured by the Interface is the amount of time it takes for the DnsQuery() function to complete. If the response from DNS Server does not indicate a Type A record, or if DnsQuery() fails, the Interface writes the value Bad Input. If the Interface does not receive a reply within a user-specified timeout duration, it write I/O Timeout.

If the PI point is of type String, PI TCPResponse writes the value of the IP address translation; for example, 192.168.10.100. Otherwise, PI TCPResponse writes the response time value.

Web Page Loading TimeFor points with Location2 set to 11, the Interface determines the time it takes to load a particular page on a Web server.

PI TCPResponse invokes a third-party library function call to load a user specified Web page (for example, DEVICE=192.168.8.76/cgi-bin/aTestProgram.exe in the


Principles of Operations

InstrumentTag). The Interface uses either the HTTPS protocol (by default) or the HTTP protocol (PROT=HTTP in the InstrumentTag).

When the protocol is HTTPS, the default port number is 443. When the protocol is HTTP, the default port number is 80. The user may specify a particular port number via PORT= in the InstrumentTag.

The time measured by the Interface is the amount of time that the third-party library function call takes to complete. If the third-party library function reports that it cannot connect to the specified machine, the Interface writes I/O Timeout. For all other errors, the Interface writes Bad Input.

Username/Password Authentication and Expected ReplyThe user has the option of specifying a username, password, and authentication type. At startup, the Interface loads usernames and passwords that it finds in the file named pitcpresp.password. This file must be located in the same directory as the interface executable.

The format of this plain text file is as follows:# pitcpresp.password

# a '#' indicates a comment line

# specify a grouping of device, username, and password

device=www.theWebSite.com/thePage.html

user=theUser

password=thePassword

# for easier legibility, use '#' to separate a group of device,

# username, password


user=anotherUser

password=anotherPassword

#

device=www.company.com/cgi-bin/theApp.exe

user=user1

password=passwordForUser1

# end of pitcpresp.password

Note that a comment line cannot occur within a group of device, username, and password. The following is illegal:# Invalid pitcpresp.password file


user=theUser

# you cannot have a comment within a grouping

password=thePassword

10

Specify the username and authentication type in the InstrumentTag (via USER= and AUTH= respectively). For example,

device=www.theWebSite.com/thePage.html; user=theUser; auth=BASIC;

The Interface supports the following authentication types:

Basic

NTLM

After loading the Web page, the Interface checks whether the user-specified value in REPLY= is within the first 1024 characters of the page. Please note that this is a case-sensitive search. Thus, if the Web page contains the text "Welcome" as part of the first 1024 characters, you need to specify REPLY=Welcome in the InstrumentTag. Otherwise, the Interface writes Bad Input.


Installation ChecklistFor those users who are familiar with running PI data collection interface programs, this checklist helps get the Interface running. Those who are not familiar with PI interfaces should read the rest of the manual in detail and then return to this section.

1. If the PI Server is version 3.3.361.43 or higher, install the PI ICU.

2. Install the PI API. (Installation of the PI ICU automatically installs these products.)

3. Confirm connectivity between the interface node and the PI Server by running the apisnap program.

4. Install the PI TCPResponse program files by running the installation program.

5. Choose a point source for use by the Interface (–ps).

6. Configure PI points. Location1 is the interface instance (–id).Location2 indicates the service (e.g., FTP, HTTP, etc.)Location3 specifies the timeout durationLocation4 is the scan class.Location5 is used for debuggingExDesc specifies the trigger point for event-based inputs.InstrumentTag specifies the device

7. Configure the Interface to be used with the PI ICU. Alternatively, edit the Interface startup command file (PITCPResp.bat) using the supplied PITCPResp.bat_new as a template.

8. If desired, configure performance points.

9. If desired, configure an I/O Rate point.

10. Confirm that the time and time zone settings on the interface node are correct.

11. Modify the security of the PI Server. Edit the PI Trust or PI Proxy table as appropriate.

12. Stop the PI Buffer Server

13. Interactively start the Interface.

14. Verify that data are correctly being written to the PI Server.

15. Stop the Interface and start the PI Buffer Server.

16. Start the Interface as a service.

17. Confirm that the Interface re-starts after a complete machine shutdown and restart.


Interface InstallationOSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server node. A PI Interface Node is any node other than the PI Server node where the PI Application Programming Interface (PI API) has been installed (see the PI API manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PI Server is to archive data and to service clients that request data.

After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI API manual). Bufserv is distributed with the PI API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.

In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of an interruption in electrical power.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. This typical scenario assumes that Bufserv is not enabled on the PI Server node. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt Interface User Manual for special procedural information.

Naming Conventions and Requirements

When Configuring the Interface ManuallyWhen an interface is configured as a Windows service, the executable file name (i.e., PITCPResp.exe) and the command file (i.e., PITCPResp.bat) must have the same root name (i.e., PITCPResp). The reason is that at service startup, the interface executable (i.e., PITCPResp.exe) looks specifically for startup parameters in a .bat file (i.e., PITCPResp.bat) that has the same root name (i.e., PITCPResp as the executable.

Thus, when manually configuring the interface and running multiple copies, the user needs to copy and rename both the executable and the startup command file. For example, copy PITCPResp.exe so that PITCPResp1.exe results and copy PITCPResp.bat so that PITCPResp1.bat results. Subsequently, PITCPResp1.exe and PITCPResp1.bat are typically used for interface instance number 1. Repeat the process so that PITCPResp2.exe and PITCPResp2.bat are used for interface instance number 2, and so on.


Interface Installation

Interface Directories

PIHOME Directory TreeThe PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file; it is located in the directory where Windows itself is installed.

A typical pipc.ini file contains the following lines:[PIPC]PIHOME=c:\Program Files\pipc

The above lines define the \Program Files\pipc directory as the root of the PIHOME directory tree on the C: drive.

OSIsoft recommends using \Program Files\pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.

Interface Installation DirectoryIf installing the interface manually, place all copies of the interface into a single directory. The suggested directory is:PIHOME\Interfaces\TCPResp\Replace PIHOME with the corresponding entry in the pipc.ini file.

Interface Installation ProcedureThe PI TCPResponse Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and greater operating systems. When running on Windows NT 4.0 systems, the PI TCPResponse setup program will install the Windows Installer itself if necessary. To install, run the installation kit executable (e.g., TCPResponse_x.x.x.x.exe).

Installing Interface as a Windows ServiceThe PI TCPResponse Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.

Installing Interface Service with PI ICUThe PI Interface Configuration Utility provides a graphical user interface for creating, editing, and deleting the Interface as a Windows service. However, before the user can create the PI TCPResponse Interface service, he first has to configure PI ICU to recognize the Interface.

From the PI ICU menu, select Interface, New Windows Interface from EXE, and then Browse to the PITCPResp.exe executable file. Select a PI Server from the Host PI System dropdown list box. Then, enter values for Point Source and Interface ID#. A window such as the following results:

16

Click on Add.

A display such as the following should then appear:

Near the top of the main PI ICU screen, the Interface Type should be tcpresponse. If not, use the drop-down box to change the Interface Type to be tcpresponse.

Click on Apply to enable PI ICU to manage this copy of the PI TCPResponse Interface.



To install the Interface as a service, click on the Service tab.

18

The above picture shows that this pitcpresp2 service is dependent on the tcpip service.

Finally, click on Create to create the interface service.

If the user wishes to remove the interface service, he should click on Remove.

To start the PI TCPResponse Interface service, click on the start button ( ) located on the PI ICU toolbar.

When the PI TCPResponse Interface service is currently running, the user can click on the stop button ( ) to stop it.

Service Configuration

Service nameThe Service name box shows the name of the current interface service. This service name is obtained from the interface executable.

IDThis is the service id used to distinguish multiple instances of the same interface using the same executable.

Display nameThe Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a "PI-" prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix "PI-" be appended to the beginning of the interface to indicate that the service is part of the OSIsoft suite of products.

Log on asThe Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use.

PasswordIf a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.

Confirm PasswordIf a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.

DependenciesThe Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependent should be moved into the Dependencies

list using the button. For example, if PI API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a



service from the list of dependencies, use the button, and the service name will be removed from the Dependencies list.

When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.

Note: Please see the PI Log and Windows Event Logger for messages that may indicate the cause for any server not running as expected.

- Add ButtonTo add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove ButtonTo remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.

The full name of the service selected in the Installed services list is displayed below the Installed services list box.

Startup TypeThe Startup Type indicates whether the interface service will start automatically or needs to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, interface services are set to start automatically.

CreateThe Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.

Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.

20

Start or Stop ServiceTo Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

The status of the Interface service is indicated in the lower portion of the PI ICU dialog.

Installing Interface Service ManuallyHelp for installing the interface as a service is available at any time with the command:PITCPResp.exe –help

Change to the directory where the PITCPResp.exe executable is located. Then, consult the following table to determine the appropriate service installation command.

Windows Service Installation Commands on a PI Interface Node or a PI Server Nodewith Bufserv implemented

Manual service PITCPResp.exe –install –depend “tcpip bufserv”

Automatic service PITCPResp.exe –install –auto –depend “tcpip bufserv”

*Automatic service with service id

PITCPResp.exe –serviceid X –install –auto –depend “tcpip bufserv”

Windows Service Installation Commands on a PI Interface Node or a PI Server Nodewithout Bufserv implemented

Manual service PITCPResp.exe –install –depend tcpip

Automatic service PITCPResp.exe –install –auto –depend tcpip

*Automatic service with service id

PITCPResp.exe –serviceid X –install –auto –depend tcpip

*When specifying service id, the user must include an id number. It is suggested that this number correspond to the interface id (-id) parameter found in the interface .bat file.

Check the Microsoft Windows services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa.


Status of the ICU Status of the

Interface Service

Service installed or uninstalled

Digital StatesFor more information regarding Digital States, refer to the PI Server documentation.

Digital State SetsPI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.

An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.

System Digital State SetSimilar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state Bad Input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients. Digital States 193-320 are reserved for OSIsoft applications.


PointSource The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string TCPRespPts may be used to identify points that belong to the PI TCPResponse Interface. To implement this identification, the user would set the PointSource attribute to TCPRespPts for every PI Point that is configured for the PI TCPResponse Interface. Then, if -ps=TCPRespPts is used on the startup command-line of the PI TCPResponse Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of TCPRespPts. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the -ps startup command parameter.

Case-sensitivity for PointSource AttributeThe case of the PointSource character point attribute is not significant.

In addition, the PointSource character that is supplied with the -ps command-line parameter is not case sensitive. That is, -ps=P and -ps=p are equivalent.

Reserved Point SourcesSeveral subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.

Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.


PI Point ConfigurationThe PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.

Point AttributesEvery two minutes, PI TCPResponse checks the PI Server for changes to PI points whose PointSource is associated with the Interface. The Interface automatically incorporates these changes into its point list.

However, PI TCPResponse can process only 25 point changes every 30 seconds. If more than 25 points are added, edited, or deleted, PI TCPResponse will process the first 25 points, wait 30 seconds, process the next 25 points, and so on. As soon as the Interface has processed all point changes, it will resume checking for point updates every two minutes.

Use the point attributes below to define the response time values that the Interface measures. The most important attributes are Location2 and InstrumentTag.

TagA tag is a label or name for a point. Any tag name can be used in accordance with the normal PI point naming conventions.

PI documentation uses the terms tag and point synonymously.

LengthThe length of the Tag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below indicates the maximum length of this field for all the different combinations of PI API and PI Server versions.

PI API PI Server Maximum Length

1.6 or higher 3.4.370.x or higher 1023

1.6 or higher Below 3.4.370.x 255

Below 1.6 3.4.370.x or higher 255

Below 1.6 Below 3.4.370.x 255

PointSourceThe PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the -ps command-line parameter and the “Point Source” section.

PointTypePI TCPResponse supports the following PI 3.x point types: Int16


Int32 Float16 Float32 Float64 StringFor more information on these point types, see the PI Server manual.

The value of Location2 determines whether a particular point type is supported. The table below provides a summary.

Location2 Supported point types

1 (name translation) Int16, Int32, Float16, Float32, Float64, String

2 (FTP) Int16, Int32, Float16, Float32, Float64

3 (HTTP) Int16, Int32, Float16, Float32, Float64

4 (SMTP) Int16, Int32, Float16, Float32, Float64

5 (Generic application) Int16, Int32, Float16, Float32, Float64;

7 (POP3) Int16, Int32, Float16, Float32, Float64

8 (IMAP) Int16, Int32, Float16, Float32, Float64

9 (PI) Int16, Int32, Float16, Float32, Float64;

10 (DNS) Int16, Int32, Float16, Float32, Float64, String

11 (Web page) Int16, Int32, Float16, Float32, Float64

Location1The Location1 attribute associates a point with a particular copy of PI TCPResponse. Location1 is a positive integer. Its value is equal to the -id= parameter used in the startup command file (described later).

For example, if -id=1 then the user should set Location1 to 1.

Location2The Location2 attribute defines the operation that the Interface will perform. The following table summarizes the acceptable values for Location2.

Location2 Value type

1 translation of hostname to IP address; or translation of IP address to hostname; or indirect DNS (name resolution) server response time measurement

2 FTP server response time measurement

3 HTTP (Web) server response time measurement

4 SMTP (mail) server response time measurement

5 Generic TCP server application response time measurement

7 POP3 (mail) server response time measurement

8 IMAP (mail) server response time measurement

9 PI server response time measurement


Location2 Value type

10 Direct DNS (name resolution) server response time; translation of hostname to IP address; available only if the Interface runs on Windows XP

11 measurement of Web page loading time

Location3The Location3 attribute specifies the timeout duration in milliseconds. For example, if Location3 is 500, a response time longer than 500 milliseconds causes the Interface to write I/O Timeout.

If Location3 is 0, the Interface uses the value of the –wt startup command parameter (described later) as the timeout duration.

Location4

Scan-based InputsThe Location4 attribute specifies the scan class number. PI TCPResponse uses this attribute for scan-based input points.

A scan class number is a positive integer. It refers to the instance of the appearance of the –f= parameter (described later) in the startup command file. For example, if the file contains the following:

PITCPResp.exe –f=120 –f=180 –f=240 …then it defines the following scan classes: 1, 2, and 3. So, for a point configured with Location4 set to 2, PI TCPResponse measures response times every 180 seconds.

For more information, see the description of the -f parameter in the section called “Startup Command File”.

Trigger-based InputsA trigger-based input point is a point that contains the keyword EVENT= in the Extended Descriptor (described later). Location4 should be set to zero for these points.

Location5The Location5 attribute causes the Interface to print debugging messages. For normal operations, Location5 should be zero. However, during a first time installation of PI TCPResponse or the investigation of anomalous behavior, the user may wish to set Location5 to a non-zero value. See the Troubleshooting section of this manual for details.

InstrumentTag

LengthThe length of the InstrumentTag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below indicates the maximum length of this field for all the different combinations of PI API and PI Server versions.


PI Point Configuration





Below 1.6 Below 3.4.370.x 32

Thus, in order to effectively run the Interface, the user most likely will need to have PI API v1.6 (or higher) and PI Server 3.4.370.x (or higher) installed. For example,

DEVICE=192.168.10.100; PORT=2340;

contains 34 characters.

Alternatively, the user may enable the PI SDK by specifying -pisdk=1 on the startup command line. This allows the Interface to use an InstrumentTag of length 1023.

The InstrumentTag attribute holds various keywords/value pairs (e.g., DEVICE=ftp.somecompany.com) that, together with Location2, uniquely define the operation that the Interface performs.

The available keywords are DEVICE=

PORT=

INPUT=

REPLY=

A semicolon terminates a keyword/value pair. For example, DEVICE=192.168.10.100; INPUT=www.somecompany.com;

The keywords themselves are not case sensitive; however, the values are. For example, REPLY=HTTP;

is the same as Reply=HTTP;

However, it is not the same as REPLY=Http;

Not every keyword is applicable or required for each Location2 value. The following table summarizes the keywords and their applicability.

Location2 Applicable keywords in InstrumentTag

1 (name translation) INPUT= (required); DEVICE= supported for backwards compatibility

2 (FTP) DEVICE= (required); PORT= (optional); REPLY= (optional);

3 (HTTP) DEVICE= (required); PORT= (optional); REPLY= (optional);

4 (SMTP) DEVICE= (required); PORT= (optional); REPLY= (optional);

5 (Generic application) DEVICE= (required); PORT= (required);

30


7 (POP3) DEVICE= (required); PORT= (optional); REPLY= (optional);

8 (IMAP) DEVICE= (required); PORT= (optional); REPLY= (optional);

9 (PI) DEVICE= (required); PORT= (optional);

10 (DNS) DEVICE= (required, must be an IP address); INPUT= (required, cannot be an IP address);

11 (Web page) DEVICE= (required); PORT= (optional); PROT= (optional); USER= (optional); AUTH= (required if USER= is used); REPLY= (required if USER= is used);

Location2 = 1If Location2 is 1, the required keyword is INPUT=. Based on the value of this keyword, Interface performs

a hostname to IP address translation; or

an IP address to address translation

Specifically, if the value of INPUT= is a hostname, (for example, INPUT=www.osisoft.com;) the Interface performs a hostname to IP address translation.

If the value of INPUT= is an IP address (for example, INPUT=63.95.45.104;), the Interface performs an IP address to hostname translation.

For either case, when the PI point type is String, the Interface writes to the point the results of the translation. When the PI point type is numeric (e.g., Int32), the Interface writes the time taken to perform such a translation.

In both cases, the Interface makes use of the default name server. The user can find out the name of the default name server by invoking nslookup at the command prompt. For example,C:\> nslookup

Address: 192.168.100.45

However, the underlying method by which the Interface uses to perform the address translation does not always generate a connection to the default name server. So, if the user wants to directly measure the response time of the default name server (or any name server), he should use the operation associated with Location2 set to 10.

For backwards compatibility, the keyword DEVICE= is the same as INPUT= for points with Location2 equal to 1.

Location2 = 2If Location2 is 2, the required keyword is DEVICE=. Its value specifies an FTP server; for example, DEVICE=ftp.mycompany.com.

By default, the Interface assumes that the specified FTP server uses port 21. If the FTP server is not using port 21, specify the port number via the optional PORT= keyword. For example,



DEVICE=ftp.mycompany.com; PORT=2021;

By default, the Interface expects a reply that contains the text 220. If the user wants the Interface to expect another reply, specify this text via the optional REPLY= keyword. For example,DEVICE=ftp.mycompany.com; REPLY=server is ready;

Location2 = 3If Location2 is 3, the required keyword is DEVICE=. Its value specifies an HTTP server; for example, DEVICE=www.mycompany.com.

By default, the Interface assumes that the specified HTTP server uses port 80. If the HTTP server is not using port 80, specify the port number via the optional PORT= keyword. For example,DEVICE=www.mycompany.com; PORT=2080;

By default, the Interface expects a reply that contains the text HTTP/1.1. If the user wants the Interface to expect another reply, specify this text via the optional REPLY= keyword. For example,DEVICE=www.mycompany.com; REPLY=Forbidden;

Note that PI TCPResponse can measure the response time of an HTTP server only. That is, the Interface cannot measure the response time required to load a particular page on an HTTP server.

Location2 = 4If Location2 is 4, the required keyword is DEVICE=. Its value specifies an SMTP server; for example, DEVICE=smtp.mycompany.com.

By default, the Interface assumes that the specified SMTP server uses port 25. If the SMTP server is not using port 25, specify the port number via the optional PORT= keyword. For example,DEVICE=smtp.mycompany.com; PORT=2025;

By default, the Interface expects a reply that contains the text 220. If the user wants the Interface to expect another reply, specify this text via the optional REPLY= keyword. For example,DEVICE=smtp.mycompany.com; REPLY=server is ready;

Location2 = 5If Location2 is 5, the required keywords are DEVICE= and PORT=. The value of the former keyword specifies a server that contains an application whose response time the user wants to measure. The value of the latter specifies the port on which the application runs. For example,DEVICE=server.mycompany.com; PORT=3389;

Location2 = 7If Location2 is 7, the required keyword is DEVICE=. Its value specifies a POP3 server; for example, DEVICE=pop3.mycompany.com.

32

By default, the Interface assumes that the specified POP3 server uses port 110. If the POP3 server is not using port 110, specify the port number via the optional PORT= keyword. For example,DEVICE=pop3.mycompany.com; PORT=2110;

By default, the Interface expects a reply that contains the text +OK. If the user wants the Interface to expect another reply, specify this text via the optional REPLY= keyword. For example,DEVICE=pop3.mycompany.com; REPLY=server is ready;

Location2 = 8If Location2 is 8, the required keyword is DEVICE=. Its value specifies an IMAP server; for example, DEVICE=imap.mycompany.com.

By default, the Interface assumes that the specified IMAP server uses port 143. If the IMAP server is not using port 143, specify the port number via the optional PORT= keyword. For example,DEVICE=imap.mycompany.com; PORT=2143;

By default, the Interface expects a reply that contains the text "* OK". If the user wants the Interface to expect another reply, specify this text via the optional REPLY= keyword. For example,DEVICE=imap.mycompany.com; REPLY=server is ready;

Location2 = 9If Location2 is 9, the required keyword is DEVICE=. Its value specifies a PI server whose response time the user wants to measure; for example, DEVICE=pi.mycompany.com. This PI server should be different from the PI Server that the holds the points that the Interface is servicing.

By default, the Interface assumes that the specified PI server uses port 5450. If the PI server is not using port 5450, specify the port number via the optional PORT= keyword. For example,DEVICE=pivax.mycompany.com; PORT=545;

Location2 = 10This operation is available only when the Interface runs on Windows XP and higher.

If Location2 is 10, the required keywords are DEVICE= and INPUT=. The value of the former keyword specifies the IP address of a name server whose response time the user wants to measure. The value of the latter specifies the hostname that the name server should translate. For example,DEVICE=192.168.10.100; INPUT=www.mycompany.com;

When the PI point type is String, the Interface writes to the point the results of the translation. When the PI point type is numeric (e.g., Int32), the Interface writes the time taken to perform such a translation.

The value of DEVICE= must be an IP address. The value of INPUT= cannot be an IP address.



Location2 = 11If Location2 is 11, the required keyword is DEVICE=. Its value specifies a Web page; for example, DEVICE=www.mycompany.com/thePage.html.

By default, the Interface uses HTTPS to load the Web page. If you want to use HTTP, specify PROT=HTTP. For example,

DEVICE=www.mycompany.com/thePage.html; PROT=HTTP;

For HTTPS, the Interface connects to port 443 of the remote device. For HTTP, the Interface connects to port 80. To tell the Interface to connect to a particular port number, specify it via the PORT= keyword. For example,

DEVICE=www.mycompany.com/thePage.html; PROT=HTTP; PORT=2080;

If the Web page requires username and password authentication, you need to specify three additional fields: USER=, AUTH=, and REPLY=.

The USER= keyword indicates the username for the Web page. The Interface sends the corresponding password from the pitcpresp.password file. Please see the "Principles of Operations" chapter of this manual for the format of this file.

The AUTH= keyword indicates the authentication type. Valid values are:

AUTH value Authentication Type

BASIC Basic

NTLM NTLM

Separate multiple authentication types with "|". For example, to use both Basic and NTLM authentication:DEVICE=www.mycompany.com/thePage.html; USER=theUser; AUTH=BASIC | NTLM;

The REPLY= keyword specifies a string of characters that is among the first 1024 on the Web page. The Interface performs a case-sensitive search for these characters to confirm that it has successfully loaded the page. For example, if the Web page contains the word "Welcome", specify this word in the point configuration:DEVICE=www.mycompany.com/thePage.html; REPLY=Welcome;

If the characters are not found in the first 1024 characters of the Web page, the Interface writes Bad Input.

User-specified repliesMany of the operations mentioned above (e.g., HTTP server response) allow the user to tell the Interface to expect a custom text string in the reply from the server. In particular, when measuring HTTP server response time, the Interface normally expects a reply that contains the text HTTP/1.1.

However, some HTTP servers require a username/password, and the reply it sends does not contain HTTP/1.1, but perhaps a text such as 403 Forbidden. The user can tell the Interface to expect the text Forbidden via the keyword REPLY in the point’s InstrumentTag.

34

To find out the actual response from the server, set the point’s Location5 value to 4. The Interface then prints out the server response in PIPC.LOG. See the Troubleshooting section for more details.

ExDesc

LengthThe length of the Extended Descriptor field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below indicates the maximum length of this field for all the different combinations of PI API and PI Server versions.





Below 1.6 Below 3.4.370.x 80

PI TCPResponse uses the Extended Descriptor attribute for Performance Points and event-based input points (also known as trigger-based input points).

Performance Points For UniInt-based interfaces, the extended descriptor is checked for the string “PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a performance point. See the section called “Performance Point Configuration.”

Trigger-based InputsFor trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form:keyword=trigger_tag_name

where keyword is replaced by “event” and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute.

An input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value.

Conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows:Event='trigger_tag_name' event_condition

The trigger tag name must be in single quotes. For example,



Event='Sinuoid' Anychange

will trigger on any event to the PI Tag sinusoid as long as the next event is different than the last event. The initial event is read from the snapshot.

The keywords in the following table can be used to specify trigger conditions.

Event Condition

Description

Anychange Trigger on any change as long as the value of the current event is different than the value of the previous event. System digital states also trigger events. For example, an event will be triggered on a value change from 0 to “Bad Input,” and an event will be triggered on a value change from “Bad Input” to 0.

Increment Trigger on any increase in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 0 to 1, but an event will not be triggered on a value change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change from 0 to “Bad Input.”

Decrement Trigger on any decrease in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 1 to 0, but an event will not be triggered on a value change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change from 0 to “Bad Input.”

Nonzero Trigger on any non-zero value. Events are not triggered when a system digital state is written to the trigger tag. For example, an event is triggered on a value change from “Pt Created” to 1, but an event is not triggered on a value change from 1 to “Bad Input.”

Scan The Scan attribute has the default value of 1, indicating that the Interface should collect data for the point. Setting the Scan attribute to 0 turns data collection off. If the Scan attribute is 0 when the interface starts, the Interface writes SCAN OFF to the point. If the user changes the Scan attribute from 1 to 0 while the interface is running, the Interface also writes SCAN OFF.

There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.

ShutdownThe Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes

36

in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.

Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the -stopstat=Shutdown command-line argument is specified.

SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.

Bufserv It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.


Performance Point ConfigurationPerformance points can be configured to monitor the amount of time in seconds that an interface takes to complete a scan for a particular scan class. A scan completion time that is close to 0 seconds indicates that the TCP/IP servers are responding very quickly.

The Interface records the scan completion time to millisecond resolution

Configuring Performance Points with PI ICU (Windows)The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing Performance Points.

CreateTo create a Performance Point, right-click the line belonging to the tag to be created, and select Create.

DeleteTo delete a Performance Point, right-click the line belonging to the tag to be deleted, and select Delete.

CorrectIf the “Status” of a point is marked “Incorrect”, the point configuration can be automatically corrected by ICU by right-clicking on the line belonging to the tag to be corrected, and selecting Correct. The Performance Points are created with the following PI attribute values. If ICU detects that a Performance Point is not defined with the following, it will be marked Incorrect:

Attribute Details

Tag Tag name that appears in the list box

PointSource Point Source for tags for this interface, as specified on the first tab

Compressing Off

ExcMax 0

Descriptor Interface name + “ Scan Class # Performance Point”

RenameRight-click the line belonging to the tag and select “Rename” in order to rename the Performance Point.


StatusThe Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in column 2.

Created – Indicates that the Performance Point does exist

Not Created – Indicates that the Performance Point does not exist

Deleted – Indicates that a Performance Point existed, but was just deleted by the user

Scan ClassThe Scan Class column indicates which scan class the Performance Point in the Tagname column belongs to. There will be one scan class in the Scan Class column for each scan class listed in the Scan Classes combo box on the UniInt Parameters tab.

TagnameThe Tagname column holds the Performance Point tag name.

SnapshotThe Snapshot column holds the snapshot value of each Performance Point that exists in PI. The Snapshot column is updated when the Performance Points/Counters tab is clicked, and when the interface is first loaded.

Configuring Performance Points ManuallyPerformance point configuration is the same on all operating system platforms. Performance points are configured as follows.

1. Set the extended descriptor to:PERFORMANCE_POINTor to:PERFORMANCE_POINT=interface_idwhere interface_id corresponds to the identifier that is specified with the -id parameter on the startup command-line of the interface. The character string PERFORMANCE_POINT is case insenstive. The interface_id does not need to be specified if there is only one copy of an interface that is associated with a particular point source.

2. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the -f parameter for a description of scan classes.

3. Set the PointSource attribute to correspond to the -ps parameter on the startup command-line of the interface.

4. Set the PointType attribute to float32.


I/O Rate Point ConfigurationAn I/O Rate point measures the throughput of an Interface. In particular, the value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the Interface sends to the PI Server. Because values are averaged over a 10-minute interval, the first calculated value is not written to the PI Server until 10 minutes after the Interface has started. The user can configure one I/O Rate point for each copy of the Interface that is in use.

Monitoring I/O Rates on the Interface NodeFor Windows nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as PI ProcessBook.

Configuring I/O Rate Tags with PI ICU (Windows)The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing I/O Rate Tags.

PI ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rate tags.

Enable IORates for this InterfaceThe Enable IORates for this interface check box enables or disables I/O Rates for the current interface. To disable I/O Rates for the selected interface, uncheck this box. To enable I/O Rates for the selected interface, check this box.

Event CounterThe Event Counter number correlates a point specified in the IORates.dat file with this Interface. This correlation results from the command line parameter


/ec=x

where x is the same number that is assigned to the point named in the IORates.dat file.

TagnameThe tag name listed under the Tagname column is the name of the I/O Rates point.

Tag StatusThe Tag Status column indicates whether the I/O Rate point currently exists in PI Server. The possible states are:

Created - This status indicates that the point exists in PI Server

Not Created - This status indicates that the point does not yet exist in PI Server

Deleted - This status indicates that the point has just been deleted

Unknown - This status indicates that the PI ICU is not able to access PI Server

In FileThe In File column indicates whether the I/O Rates point listed in the Tagname column and the event counter number listed in the Event Counter column are in the IORates.dat file. The possible states are:

Yes - This status indicates that the I/O Rate point and the event counter number are in the IORates.dat file

No - This status indicates that the I/O Rate point and the event counter number are not in the IORates.dat file

SnapshotThe Snapshot column holds the snapshot value of the I/O Rate tag, if the I/O Rate tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the Interface is first loaded.

Button Menu Options

CreateCreate the suggested I/O Rates point with the tag name indicated in the Tagname column.

DeleteDelete the I/O Rate point listed in the Tagname column.

ResetChange the value in the Tagname text box back to the default value.

RenameAllow the user to specify a new name for the I/O Rate point listed in the Tagname column.


Add to FileAdd the I/O Rate point and the event counter number to the IORates.dat file.

Search Allow the user to search the PI Server a previously defined I/O Rate points.

Update Snapshot Allow the user to refresh the snapshot value.

Configuring I/O Rate Tags ManuallyThere are two configuration steps.

1. Configuring the PI Point on the PI Server

2. Configuration on the Interface Node

Configuring PI Point on the PI ServerCreate an I/O Rate Tag with the following point attribute values.

Attribute Value

PointSource L

PointType float32

Compressing 0

ExcDev 0

Configuration on the Interface NodeThe following procedure for I/O Rate point configuration on the interface node assumes that the tag name of this point is sytcpresp001. With respect to I/O Rate point configuration, an interface node is the computer on which the Interface runs.

1. Edit/Create a file called IORates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence.

Since the PIHOME directory is typically C:\Program Files\PIPC, the full name of the IORates.dat file will typically be

C:\Program Files\PIPC\dat\IORates.dat.

Add a line in the IORates.dat file of the form:sytcpresp001, x

where sytcpresp001 is the name of the I/O Rate Tag and x corresponds to the first instance of the -ec=x parameter in the startup command file. X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and


I/O Rate Point Configuration

additional entries in the IORates.dat file. The event counter, -ec=x, should be unique for each copy of the interface.

2. Set the -ec=x parameter on the startup command file of the interface to match the event counter in the IORates.dat file.

The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.

44

Startup Command FileCommand-line parameters begin with the dash character (-). For backwards compatibility, the Interface also supports the slash character (/). For example, the /ps=M and –ps=M command-line parameters are equivalent.

Configuring the Interface with PI ICUOn Windows, the PI Interface Configuration Utility (PI ICU) is a graphical tool that allows a user to configure the Interface’s startup command file. OSIsoft strongly recommends that the user run the PI ICU to configure and maintain the Interface's startup command file.

When running the PI ICU, the user should make sure that "tcpresponse" is selected for the Type of interface. That is,

OSIsoft recommends that the user configure this Interface to write the digital state Intf Shut at interface shutdown. So, PI ICU’s UniInt tab should look like the following:


The interface-specific tab (i.e., "tcpresponse") allows the user to enter values for the startup parameters that are particular to PI TCPResponse.

Time to wait for responsePI TCPResponse measures the response times of servers. By default, if a server takes longer than 5000 milliseconds (5 seconds) to respond, the Interface writes I/O Timeout to the particular interface point.


If the user wants the Interface to wait for a different duration, he should check the Enable wait time box and specify the amount of time in the text box. For example, to tell the Interface to wait 10 seconds:

The minimum allowable wait time is 100 milliseconds. In addition, a point’s non-zero Location3 attribute overrides this wait time parameter for that particular point.

Manual Maintenance of the Startup Command FileOSIsoft strongly recommends that the user run the PI ICU to configure and maintain the Interface's startup command file. However, if he chooses to do so, the user can manually edit the command file that starts up the Interface.

For proper operation, the Interface requires various command-line parameters. These parameters begin with the dash character (-). For backwards compatibility, the Interface also supports the slash character (/).

The user should put these parameters, along with the name of the Interface executable, into a startup command file. For example,

PITCPResp.exe –ps=P –id=1 –ec=11

For Windows, various filename extensions are associated with command files. For example, .bat and .cmd are both acceptable. However, only the .bat extension is valid for a command file used by the Interface.

The name of the startup command file must be the name of the Interface executable, with the .exe extension replaced by the .bat extension. Thus, the startup command file for this Interface will typically be PITCPResp.bat. (The installation program installs a sample command file named PITCPResp.bat_new. The user should use this file as a template for his own PITCPResp.bat.)

The contents of a PI interface command file may contain the caret line continuation character (^). For example, a PITCPResp.bat file with contentsPITCPResp.exe ^ –ps=P ^ –id=1 ^ –ec=11is equivalent to the above example.

The maximum length of each line in a command file is 1024 characters. The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters. If a value for a parameter contains a space, use a pair of double quotes to enclose both the parameter and its value. For example,

PITCPResp.exe –ps=P –id=1 –stopstat="Intf Shut"


Startup Command File

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

Command-line ParametersParameter Description

-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 # 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. Configuration of I/O Rate points is discussed in the section called "I/O Rate Tag Configuration."

-f=SSor-f=SS,SSor -f=HH:MM:SSor-f=HH:MM:SS,hh:mm:ss

Required for reading scan-based inputs

The -f parameter defines the time period between scans in terms of hours (HH), minutes (MM), and seconds (SS). 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), and seconds (ss). 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) + offset

where 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:06:10, the second scan would be at 05:07:10, 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

48

Parameter Description

a large load, then some scans may occur late or be skipped entirely. See the section called “Performance Point Configuration” for more information on skipped or missed scans.

Sub-second Scan Classes

Sub-second scan classes can be defined on the command-line, such as

-f=0.5 -f=00:00:00.1

where 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 Scheduling

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

WARNING: The user must think very carefully before setting scan frequencies for less than 2 minutes. If there are many points defined, the combination of both multiple and frequent connection requests sent by the Interface may overwhelm the network and/or the servers whose response times are being measured.

-host=host:port

Required

The –host parameter is used to specify the PI Server node. host is the IP address of the PI Sever node or the name of the PI Server node. port is the port number for TCP/IP communication. This number is always 5450.

Examples:The interface is running on a PI Interface Node, the name of the PI Server node is Marvin, and the IP address of Marvin is 192.168.8.30. Valid -host parameters are:-host=marvin -host=marvin:5450 -host=192.168.8.30-host=192.168.8.30:5450


Startup Command File

Parameter Description

-id=x

Required

The –id parameter specifies the Interface identification number. Each instance of PI TCPResponse uses the –ps and -id parameters to identify uniquely its particular list of points to service. In addition, the Interface uses the value of this parameter in the messages that it writes to the log file. For example, if the user specifies –id=8, then the message log file will have contents such as:

12-Dec-02 14:44:58

PI TCPResponse 8> 125 points found for point source P

-ps=ptSrc

Required

The -ps parameter specifies the point source for the interface. ptSrc can be a single or multiple characters, and is not case sensitive. 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.

-q

Optional

When the -q parameter is present, Snapshots and exceptions are queued before they are sent to the PI Server node.

The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it is not filled.

-stopstator-stopstat=digstate

Recommended:-stopstat="Intf Shut"

Optional

The –stopstat parameter causes the Interface to write the specified digital state to its list of points before it exits. The recommended digital state is Intf Shut. Because there is a space in this digital state value, the user needs to use quotation marks. For example,

PITCPResp.exe –ps=P –stopstat="Intf Shut"

If the user specifies a digital state that does not exist in the PI Server, the Interface does not write any digital state values before it exits.

-wt=#

Optional

The -wt parameter specifies (in milliseconds) the amount of time the Interface should wait for a response. If the user does not specify this parameter, the Interface waits 5000 milliseconds. The lower limit for this value is 100.

A point’s non-zero Location3 attribute overrides this parameter.

50

Sample PITCPResp.bat FileThe following is an example of the contents of a startup command file for the PI TCPResponse Interface:REM=======================================================================REMREM PITCPResp.batREMREM Sample startup file for the TCP Response Interface to the PI SystemREMREM=======================================================================REM REM OSIsoft strongly recommends using PI ICU to modify startup files.REMREM Sample command lineREM.\PITCPResp.exe -ps=P -id=1 -f=300 -host=XXXXXX:5450 -stopstat="Intf Shut"REMREM End of PITCPResp.bat File

The installation program installs a sample command file named PITCPResp.bat_new. The user may use this file as a template to configure the PITCPResp.bat file.


Interface Node ClockMake sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,

In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,

C:> set

Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.


SecurityThe PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.

Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure. See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.

If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Server, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.

PI Server v3.3 and Higher

Security configuration using piconfigFor PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:C:\PI\adm> piconfig@table pitrust@mode create@istr Trust,IPAddr,NetMask,PIUsera_trust_name,192.168.100.11,255.255.255.255,piadmin@quit

For the above,

Trust: An arbitrary name for the trust table entry; in the above example,

a_trust_name

IPAddr: the IP Address of the computer running the Interface; in the above example,

192.168.100.11

NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr

PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user

Security Configuring using Trust EditorThe Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.

See the PI System Management chapter in the PI Server manual for more details on security configuration.

PI Server v3.2For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:


C:\PI\adm> piconfig@table pi_gen,piproxy@mode create@istr host,proxyaccountpiapimachine,piadmin@quitIn place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.


Starting / Stopping the Interface on Windows This section describes starting and stopping the interface once it has been installed as a service. See the UniInt Interface User Manual to run the interface interactively.

Starting Interface as a ServiceIf the interface was installed a service, it can be started from PI ICU, the services control panel or with the command:PITCPResp.exe –start

To start the interface service with PI ICU, use the button on the PI ICU toolbar.

A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. Even if the message indicates that the service started successfully, make sure that the service is still running by checking in the services control panel.

There are several reasons that a service may immediately terminate after startup. One is that the service may not be able to find the command-line parameters in the associated .bat file. For an interface service startup to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory.

If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file, the Windows Event Viewer, or other sources of error messages. See the section “Appendix A: Error and Informational Messages,” for additional information.

Stopping Interface Running as a ServiceIf the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:PITCPResp.exe –stopThe service can be removed by:PITCPResp.exe –remove

To stop the interface service with PI ICU, use the button on the PI ICU toolbar.


BufferingFor complete information on buffering, please refer to the PI API Installation Instructions.

PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.

Note: Change the Local Security Policy on Windows XP. 1. Open “Administrative Tools” from the control panel. 2. Open “Local Security Policy” from administrative tools. 3. Browse to “Security Options” under “Local Policies.” 4. Double click on “System Objects: Default owner for objects created by members of the Administrators group.” 5. Change the dropdown from “Object Creator” to “Administrators group.”

The behavior of Bufserv should now be the same on Windows XP as it was for Windows NT 4 and 2000.

Configuring Buffering with PI ICU (Windows)Buffering is enabled through the PI Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI API will not buffer data, sending data directly to the home node.

The API Buffering… dialog allows the user to view and configure the parameters associated with the PI API Buffering (bufserv) process. The user can start and stop the PI API Buffering process from the Service tab:


Service TabThe Service tab allows for some PI API Buffering service configuration. For further configuration changes, use the Services applet.

Service NameThe Service name displays the name of the PI API Buffering Service.

Display NameThe Display name displays the full name associated with the PI API Buffering service.

Log On AsLog on as indicates the Windows user account under which the PI API Buffering service is setup to start automatically on reboot, or manually.

PasswordPassword is the name of the password for the Windows user account entered in the Log on as: above.

Confirm passwordReenter the password to verify it has been typed correctly both times.

DependenciesThe Dependencies lists the Windows services on which the PI API Buffering service is dependent.

Dependent ServicesThe Dependent services area lists the Windows services that depend on bufserv to function correctly.

Start / Stop ServiceThe Start / Stop buttons allow for the PI API Buffering service to be started and stopped. If the service is not created, this box will show Not Installed.

After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv.

Service Startup TypeThe Startup Type indicates whether the PI API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, the PI API Buffering service is set to start automatically.


Create/Remove ServiceThe Create / Remove buttons allow for the creation or removal of the PI API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.

Settings TabThe Settings tab allows for configuration of the 7 configurable settings used by PI API Buffering. Default values are used if no other value is provided.

Enable BufferingEnable the PI API Buffering feature.

Maximum File SizeMaximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.

The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Send RateSend rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.


Primary Memory Buffer Size


Buffering

Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Secondary Memory Buffer SizeSecondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Max Transfer ObjectsMax transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.


Pause RateWhen buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.


Retry RateWhen the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.


Max Theoretical Send RateThis is the theoretical max send rate which is calculated like this:max = MAXTRANSFEROBJS / SENDRATE * 1000Default value is 5000. This value is automatically calculated for the user and can not be changed.

There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.

Configuring Buffering ManuallyBuffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI API will not buffer data, sending data directly to the home node.

62

There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.

Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.

Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the dat subdirectory of the PIHOME directory (which is typically c:\program files\pipc\dat) under Windows. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.

The following settings are available for buffering configuration:

Keywords Values Default Description

BUFFERING 0, 1 0 Turn off/on buffering. OFF = 0, ON = 1,

PAUSERATE 0 – 2,000,000 2 When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds)

RETRYRATE 0 – 2,000,000 120 When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds)

MAXFILESIZE 1 – 2,000,000 100,000 Maximum buffer file size before buffering fails and discards events. (Kbytes)

MAXTRANSFEROBJS

1 – 2,000,000 500 Maximum number of events to send between each SENDRATE pause.

BUF1SIZE 64 – 2,000,000

32768 Primary memory buffer size. (bytes)

BUF2SIZE 64 – 2,000,000

32768 Secondary memory buffer size. (bytes)

SENDRATE 0 – 2,000,000 100 The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds)

In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define an optional time offset change that may occur between the client and server.

Keywords Values Default Description

DSTMISMATCH 0 – 2,000,000 0 The time that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in time zones whose DST rules differ (seconds)


Buffering

Example piclient.ini FileOn Windows, the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds, meaning “Wait 10 minutes after losing a connection before retrying”.

On Windows a piclient.ini file might look like:[APIBUFFER]BUFFERING=1MAXFILESIZE=100000; The PI API connection routines have a 1 minute default timeout.RETRYRATE=600

64

Appendix A:Error and Informational Messages

The string PI TCPResponse ID> is pre-pended to error and informational messages written to the message log. The value of the -id parameter on the startup command line determines the ID identifier.

Message LogsThe name of the message log is pipc.log. It is located in the dat subdirectory where the PI API is installed. For example,C:\program files\pipc\dat\pipc.logMessages are written to this file at the following times:

At startup, the Interface writes many informational messages log. These include the version of the Interface, the version of the UniInt template, the command-line parameters used, and the version of the PI API found.

As the Interface retrieves points from the PI Server, it writes messages to the log if there are problems with the configuration of the points.

When a PI point's Location5 attribute is non-zero, the Interface logs debugging messages. See Appendix B, "Troubleshooting" for more details.

System Errors and PI ErrorsOperating system errors are associated with positive error numbers. Errors related to the PI System are associated with negative error numbers.

The user can obtain descriptions of operating system and PI System errors with the pidiag program found on the computer running PI Server. This program is located in the adm subdirectory of the directory where PI Server is installed. Use –e command line parameter followed by the error number. For example,C:\PI\adm\pidiag –e 100[100] Cannot create another system semaphore.

C:\PI\adm\pidiag –e -10401[-10401] No Write Access - Secure Object


Appendix B:Troubleshooting

Location5A non-zero value in a point’s Location5 point attribute tells the Interface to print debugging messages to the message log. The Interface automatically incorporates point attribute changes. Thus, the user does not have to stop and re-start the interface to enable/disable these debugging messages. (However, the user may have to wait up to 2 minutes for point changes to take effect.)

Location5 Meaning

0 no debugging

1 messages regarding point loading

2 messages regarding network communications

3 messages regarding code execution

4 show response from server

The effects of the value of Location5 are cumulative. That is, a debug value of 2 causes the Interface also to take the actions associated with a debug value of 1.

The examples below use a test point named tcpresptest.

Location5 set to 1A debugging value of 1 results in messages relating to whether the Interface has loaded or rejected the point. For example,PI TCPResponse 1> pt (tcpresptest) LOADED

andPI TCPResponse 1> pt (tcpresptest) REFUSED; cannot find "DEVICE=" in InstrumentTag

Location5 set to 2

Set Location5 to a value of 2 to debug Bad Input or I/O Timeout values. The Interface prints the message it receives from the underlying TCP/IP software. For example,PI TCPResponse 1> pt (tcpresptest) connect() failed for 192.168.100.172:3389; err:10061 Connection Refused; is the device listening on the specified port?

Location5 set to 3A value of 3 in Location5 causes the Interface to print out messages as it executes various portions of the program code. For example, for a point configured for the measurement of HTTP server response times,PI TCPResponse 1> pt (tcpresptest) connect() to 192.168.210.40:80 good; sending HTTP

msg


This message tells the user that the Interface successfully connected to port 80 of the machine with IP address 192.168.210.40. The Interface then sent an HTTP message.

PI TCPResponse 1> pt (tcpresptest) aMsg.rval is 160.00PI TCPResponse 1> pt (tcpresptest) aMsg sent to queue

These messages tell the user that the Interface has stored the value of 160.0 into its internal queue.

PI TCPResponse 1> pt (tcpresptest), found matching message in queuePI TCPResponse 1> pt (tcpresptest), drval=160.00 returned to UniInt

These messages tell the user that the Interface has processed the value of 160.0 from its internal queue and returned this value to the UniInt template. Thus, the value for the point should be 160.0.

If the messagePI TCPResponse 1> pt (tcpresptest), ... returned to UniInt

does not appear, the reason is that the response time the user is trying to measure is too long, and a timeout occurred.

In general, if the values for a point are unexpected, set the point’s Location5 attribute to 3 and examine the message log. Afterwards, the user can set Location5 back to 0 to prevent these debugging messages.

The user should not have too many points with Location5 set to 3 or higher. Otherwise, the message log will become very large very quickly.

Location5 set to 4

A value of 4 in Location5 causes the Interface to show the reply message that it received from the server. For example,> 0000 32 32 30 20 63 6f 76 61 64 2e 6e 65 74 20 45 53 220 cova d.net ES> 0010 4d 54 50 0d 0a MTP..

Setting Location5 to 4 is useful for determining user-specified replies (i.e., REPLY= in the InstrumentTag). As such, this debug setting is valid only for the following Location2 values:


2 (FTP) DEVICE= (required); PORT= (optional); REPLY= (optional);

3 (HTTP) DEVICE= (required); PORT= (optional); REPLY= (optional);

4 (SMTP) DEVICE= (required); PORT= (optional); REPLY= (optional);

7 (POP3) DEVICE= (required); PORT= (optional); REPLY= (optional);

8 (IMAP) DEVICE= (required); PORT= (optional); REPLY= (optional);


Common problems

Interface exits on startupIf the Interface immediately exits upon startup, the most likely cause is that required command line parameters are not specified. PI TCPResponse requires the following command line parameters

–ps= (point source character or string)

–id= (interface identifaction number)

-host= (PI Server name and port number)

If the user omits any of these parameters, the Interface exits.

No new value for a pointIf a point does not receive new value (e.g., the value remains at Pt Created), a likely cause is that the Interface node does not have sufficient privileges to send data to PI Server. A symptom of this problem is a –10401 error in the message log file. The solution is to check the entries in the PI Proxy Table (PI Server v3.2) or the PI Trust Table (PI Server v3.3 and higher).

Another reason that a point is not getting a new value is that the Interface has not loaded the point. To confirm whether the Interface has loaded a point, set the point’s Location5 attribute to 1. Within two minutes, PI TCPResponse writes to the log file information regarding whether it has loaded the point. For example,PI TCPResponse 1> pt (tcpresptest) debug setting is 1PI TCPResponse 1> pt (tcpresptest) LOADED

orPI TCPResponse 1> pt (tcpresptest2) debug setting is 1PI TCPResponse 1> pt (tcpresptest2) REFUSED; -id/Location1 mismatch; -id=1, Location1=9

Value of 0 for a pointA value of 0 for a point means that the measured response time is less than 1 millisecond.

Value of Bad Input for a pointA value of Bad Input for a point means that the Interface encountered an error during the measurement of response times. A common error is the inability to translate the device specification into an IP address. For example, the user want to measure the response time of the Web server named www.somecompany.com. Accordingly, the user configures a point such that its InstrumentTag contains

device=www.somecompany.com;

Before the Interface can send an HTTP request to www.somecompany.com, it first has to find the IP address of this machine. If this IP address lookup fails, PI TCPResponse writes Bad Input to the point.

See the Principles of Operations section of this document for more reasons that the Interface writes Bad Input to a point. Also, the user can set the point’s Location5 attribute to 3 to tell the Interface to print out the reason it is writing Bad Input.


Appendix B: Troubleshooting

Value of I/O Timeout for a pointA value of I/O Timeout for a point indicates that the Interface did not receive a response message within the timeout time. The timeout time for a point is one of the following:

the Location3 value, if Location3 is non zero

the value of the –wt command line parameter if Location3 is zero

5000 milliseconds if Location3 is zero and the –wt parameter is not specified.

The user can set the point’s Location5 attribute to 3 to tell the Interface to print out the reason it is writing I/O Timeout.

70

Appendix C:Acknowledgments

The PI TCPResponse Interface contains components from the CURL and OpenSSL projects. Copyright notices and acknowledgments follow.

CURLCOPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1996 - 2004, Daniel Stenberg, <[email protected]>.

All rights reserved.

Permission to use, copy, modify, and distribute this software for any purposewith or without fee is hereby granted, provided that the above copyrightnotice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall notbe used in advertising or otherwise to promote the sale, use or other dealingsin this Software without prior written authorization of the copyright holder.

OpenSSLPortions of this program are Copyright (c) 1998-2006 The OpenSSL Project. All rights reserved.

Copyright (c) 1998-2006 The OpenSSL Project. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.


3. All advertising materials mentioning features or use of this software must display the following acknowledgment:"This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)"

4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].

5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project.

6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)"

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANYEXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.===============================================================

This product includes cryptographic software written by Eric Young ([email protected]). This product includes software written by Tim Hudson ([email protected]).

Original SSLeay License-------------------------------

Copyright (C) 1995-1998 Eric Young ([email protected])All rights reserved.

This package is an SSL implementation written by Eric Young ([email protected]).The implementation was written so as to conform with Netscapes SSL.

This library is free for commercial and non-commercial use as long as the following conditions are aheared to. The following conditions apply to all code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution is covered by the same copyright termsexcept that the holder is Tim Hudson ([email protected]).


Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed.If this package is used in a product, Eric Young should be given attributionas the author of the parts of the library used.This can be in the form of a textual message at program startup orin documentation (online or textual) provided with the package.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.3. All advertising materials mentioning features or use of this software must display the following acknowledgement:"This product includes cryptographic software written by Eric Young ([email protected])"The word 'cryptographic' can be left out if the rouines from the library being used are not cryptographic related :-).4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement:"This product includes software written by Tim Hudson ([email protected])"

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The licence and distribution terms for any publically available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and put under another distribution licence [including the GNU Public Licence.]


Revision HistoryDate Author Comments

17-Jun-2002 ETam Version 1.0.3

20-Mar-2004 ETam Version 1.1.0.0; used skeleton v1.14

06-Sep-2006 ETam Skeleton v2.52; version 1.1.3.0

07-Sep-2006 Janelle Version 1.1.3.0 Revision A: updated hardware diagram, minor formatting changes.

11-Sep-2006 MKelly Version 1.1.3.0 Revision B: Fixed headers and footers, page margins, screenshots and tables outside margins.

03-Oct-2006 Janelle Skeleton v2.5.2, Version 1.1.4.0

18-Dec-2006 MKelly Version 1.1.4.0; Revision A; Updated ICU Control screenshots, updated supported features table, fixed headers and footers..

16-Apr-2007 ETam Interface v1.1.5.0, Skeleton v2.5.2

3-May2007 Janelle Interface v1.1.5.0, Revision A: updated ICU screen shots, add serial based information to supported features table

2-Jul-2007 ETam Interface v1.1.5.1 (Beta version)

10-Jul-2007 ETam Interface v1.1.5.2 (Beta version)

05-Dec-2007 PChow Version 1.1.6.0

Updated to Skeleton 2.5.6.


tcpresponse interface to the pi...

Documents