PI-TCPResponse
PI-TCPResponse
Interface
Version 1.0.0
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|E-mail |techsupport@ |
|World Wide Web | |
|Mail |OSI Software, Inc. |OSI Software, Asia Pte Ltd |
| |P.O. Box 727 |152 Beach Road |
| |San Leandro, CA 94577-0427 |#09-06 Gateway East |
| |USA |Singapore, 189721 |
| | | |
| |OSI Software GmbH |OSI Software, Ltd |
| |Hauptstra(e 30 |P. O. Box 8256 |
| |D-63674 Altenstadt 1 |Level One, 6-8 Nugent Street |
| |Deutschland |Auckland 3, New Zealand |
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI-IN-OSI-TCP
(2001 OSI Software, Inc. All rights reserved
OSI Software, Inc. 777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 5
Reference Manuals 6
Supported Features 6
Diagram of Connections 7
Program Applications 9
Principles of Operation 13
Installation Checklist 15
Interface Installation on Windows NT 17
Microsoft Windows Installer 17
PI-SDK Installation and PIHOME 18
Interface Installation Procedure 18
Installing the Interface as a Windows NT Service 18
PointSource 21
PI Point Configuration 23
Point Attributes 23
Examples 27
Performance Point Configuration 31
I/O Rate Point Configuration 33
Monitoring I/O Rate points 33
Point attributes 33
Configuration on the interface node 33
Startup Command File 35
Command-Line parameters 35
Sample pitcpresp.bat file 38
Interface node clock 39
Security 41
Starting / Stopping the Interface 43
Starting the Interface interactively 43
Starting the Interface as a service 43
Stopping the Interface running as a service 43
Other service related commands 43
Buffering 45
Example piclient.ini file 46
Error and Informational Messages 47
Message Logs 47
Messages 47
System errors and PI errors 48
Troubleshooting 49
Location5 49
Common problems 50
Technical Details 53
Introduction
OSIsoft’s PI-TCPResponse program measures the availability and response times of various essential services that are part of a TCP/IP network. In particular, PI-TCPResponse allows you 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 Terminal Servers; and
• OSIsoft’s PI Universal Data Servers.
The program can also measure how long a particular device on the network takes to respond to ICMP echo requests (“pings”). Finally, the program can obtain the actual result (and not the response time) of a DNS operation.
PI-TCPResponse stores these response times into OSIsoft’s PI Universal Data Server system. So, you can have access to long-term historical data as well as short-term current information regarding the performance of your various servers. Therefore, PI-TCPResponse assists you in proactively managing your network.
Additionally, PI-TCPResponse can help you
• verify your SLAs (service level agreements),
• verify DNS load balancing, and
• test a computer’s readiness for Denial of Service attacks.
The PI-TCPResponse program runs on Windows NT (version 4.0) or Windows 2000 computers. Unless otherwise noted, the remainder of this document uses the term “Windows NT” to refer to both.
PI-TCPResponse requires
• PI Universal Data Server version 3.2 or higher, and
• PI-SDK v1.0.0 or higher (the PI-SDK automatically includes the PI-API)
PI-TCPResponse does not require any special hardware. A standard network interface card on the Windows NT machine is sufficient.
Terminology: PI-TCPResponse is not technically an “interface” because it does not transfer to the PI Universal Data Server existing data located on a device. Instead, it measures values and stores these measurements into PI Universal Data Server.
However, PI-TCPResponse operates within the PI Interface model. For example, PI-TCPResponse was developed using OSIsoft’s UniInt (Universal Interface) template. Therefore, the rest of this document refers to the PI-TCPResponse data measurement program as an “interface”.
Reference Manuals
The user may find the following documents useful during the operation of the PI-TCPResponse Interface.
OSI Software
• UniInt end user document
• PI Universal Data Server manual
• PI-API installation instructions
• PI-API manual
Supported Features
The following table summarizes the features of the PI-TCPResponse Interface:
|Feature |Support |
|Part Number |PI-IN-OS-TCP |
|Platform |Windows NT (Intel) |
|PI point types |float16 / float32 / float64 / int16 / int32 / string |
|Sub-second timestamps |Yes |
|Sub-second scan classes |No |
|Automatically incorporates PI point attribute changes |Yes |
|Exception reporting |Yes; performed by the Interface |
|Outputs from PI |No |
|Inputs to PI: scan-based / unsolicited / event tags |Scan-based / event tags |
|Maximum point count |Unlimited |
|Uses PI-SDK |Yes |
|PINet to PI 3.x string support |Not applicable |
|* Source of timestamps |PI Universal Data Server |
|History recovery |No |
|Failover |No |
|* UniInt-based |Yes |
|Vendor software required on PI-API node |No |
|Vendor software required on foreign device |No |
|Vendor hardware required |No |
|Additional PI software included with the interface |No |
|Device point types |Not applicable |
* See paragraphs below for further explanation.
Source of timestamps
The clock on the computer running the PI Universal Data Server provides the source of timestamps for the values sent by PI-TCPResponse.
UniInt-based
UniInt stands for Universal Interface; it is a template created by OSISoft to facilitate the rapid development of data collection interface programs. The purpose of UniInt is to keep a consistent feature set and consistent behavior across as many interfaces as possible. UniInt is constantly being upgraded with new options and features.
UniInt is not a separate product or file. Instead, it is integrated into interface programs such as PI-TCPResponse. In any UniInt-based interface, the UniInt template handles some of the startup parameters while the interface itself handles others.
The UniInt End User Document is a supplement to this manual.
Diagram of Connections
Program Applications
The following are some specific uses for the PI-TCPResponse Interface.
SLA verification
A Service Level Agreement is a contract between a network provider and its customers. The SLA typically guarantees a certain level of performance of the network.
For example, a corporation has a Wide Area Network (WAN). It has an SLA with the WAN provider. The SLA specifies a minimum response time between various computers on the WAN. This minimum response time is defined in terms of a ping response times. In addition, these minimum response times change during different parts of the day. That is, the SLA calls for a slower response time during regular business hours versus a quicker one during the night.
You can use PI-TCPResponse to perform response time measurements at all hours of the day. These measurements are stored into PI Universal Data Server. You will then have historical data regarding network response times.
So, if you are the network provider, you can prove to your customers that you have met the SLA. Conversely, if you are the customer of the WAN service provider, you can verify that you are receiving the network performance for which you have paid.
Web Server availability
Some network administrators have their web server machines configured so that they do not respond to ping requests. (Examples are and .) To confirm that such Web sites are available, you can use PI-TCPRespone to measure the response times of these servers.
Web Site Hosting verification
Many organizations outsource the management and operation of their Web sites. Web hosting companies that perform these actual management and operational duties often guarantee the level of the availability of the hosted services. When uptime requirements are not met, rebates are provided to customers. For example,
|Uptime (monthly %) |Rebate |
|99.50% to 100.00% |0% |
|98.00% to 99.49% |25% |
|97.00% to 97.99% |50% |
|95.00% to 96.99% |75% |
|< 95% |100% |
You can use PI-TCPResponse to constantly perform availability measurements of Web servers. These measurements are stored into PI Universal Data Server. You will then have historical data regarding a Web site’s availability.
So, if you are the Web hosting company, you can prove to your customers that you have met your uptime guarantee. Conversely, if you are the customer, you can check whether you are entitled to compensation because of server downtime.
DNS Load Balancing verification
If you have a Web site that receives heavy traffic, you will often distribute such traffic to different physical machines via DNS Load Balancing. For example, you are responsible for the Web site whose address is some_. You configure your name server to resolve the address some_ into three distinct IP addresses:
• 192.168.100.11
• 192.168.100.12
• 192.168.100.13
You can use PI-TCPResponse to look up the IP address for the Web site some_ at various times of the day. The results of this lookup are stored into PI Universal Data Server. You can then verify that your DNS server is properly load balancing the address some_.
IP address to name translation
There are many applications that can determine the amount of network resources consumed by your computers. Some of them (such as OSIsoft’s PI-NetFlow Interface) present their results in terms of IP addresses. For example,
|Date |Machine |% network usage |
|2/1 |192.168.100.11 |21 |
|2/2 |192.168.100.13 |28 |
|2/3 |192.168.100.17 |18 |
|2/4 |192.168.100.11 |22 |
You probably do not have IP address and the corresponding machine names committed to memory. Also, you may be using DHCP for IP addresses assignment, and you have many notebook computers that connect and disconnect from the network every day.
Thus, on 2/1, the machine with the IP address of 192.168.100.11 may actually be the same machine with the IP address of 192.168.100.13 on 2/2. Similarly, on 2/1, the machine assigned to IP address of 192.168.100.11 may be different than the machine assigned to this same IP address of 192.168.100.11 on 2/4.
The reverse name lookup function of PI-TCPResponse allows you periodically to obtain the machine name for a given IP address. The results of this lookup are stored into PI Universal Data Server. You can then have a record of the DHCP assigned addresses and the corresponding machine names.
Denial of service attack readiness
A denial of service attack occurs when hackers use the Internet to constantly and maliciously connect to one or more of your computers. Your computer spends much of its resources processing the requests for these connections. Meanwhile, users who legitimately want to access your computers cannot get through.
You can use PI-TCPResponse to simulate a denial of service attack. Simply configure the Interface to send, at a high frequency, multiple connection requests to the same computer. Then, use another machine to try to access this computer under attack. As a result, you can determine your machine’s readiness for denial of service attacks.
Router fault detection in a WAN
You can use PI-TCPResponse to determine which router in your WAN is periodically malfunctioning. For example, the following picture shows that the network path between the computer with IP address 192.168.100.10 and the computer with IP address of 10.109.200.143 involves three routers:
• 192.168.100.1
• 152.63.53.237
• 10.109.200.1
You can install PI-TCPResponse on 192.168.100.10 and periodically measure ping response times to each of these four devices:
• 192.168.100.1
• 152.63.53.237
• 10.109.200.1
• 10.109.200.143
Similarly, you can run PI-TCPResponse on 10.109.200.143 and periodically measure ping response times to
• 10.109.200.1
• 152.63.53.237
• 192.168.100.1
• 192.168.100.10
For a particular moment in time, if you get the following values
|Tag |value |
|ping_192.168.100.10_192.168.100.1 |10 |
|ping_192.168.100.10_152.63.53.237 |I/O Timeout |
|ping_192.168.100.10_10.109.200.1 |I/O Timeout |
|ping_192.168.100.10_10.109.200.143 |I/O Timeout |
and
|Tag |value |
|ping_10.109.200.143_10.109.200.1 |11 |
|ping_10.109.200.143_152.63.53.237 |I/O Timeout |
|ping_10.109.200.143_192.168.100.1 |I/O Timeout |
|ping_10.109.200.143_192.168.100.143 |I/O Timeout |
you can conclude that the router 152.63.53.237 is malfunctioning. The reason is that for both sets of values, the I/O Timeout occurred starting with 152.63.53.237.
Principles of Operation
PI-TCPResponse measures the response time of various services that are part of a TCP/IP network. In particular, the PI-TCPResponse program allows you to determine the response time of
• HTTP (Web) servers;
• SMTP, POP3, and IMAP (mail) servers;
• FTP servers;
• DNS (name resolution) servers;
• Microsoft Windows NT/2000 Terminal Servers; and
• PI Universal Data Servers
PI-TCPResponse also measures how long a particular machine on the network takes to respond to ICMP echo requests (“pings”). In addition, it stores the actual result (and not the response time) of a DNS operation.
In general, PI-TCPResponse 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 Web server by sending a connection request to TCP port number 80 of the machine named . 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.
For the measurement of DNS server response time, PI-TCPResponse does not explicitly make a connection request to TCP port 42. Instead, it uses the standard Winsock functions gethostbyname() or gethostbyaddress() to query the DNS server that is indicated in the Microsoft Windows TCP/IP settings.
For the measurement of ping response times, PI-TCPRespnose does not send a connection request to a TCP port. Instead, it sends an ICMP echo request message and waits for an ICMP echo reply message.
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, you configure 3 points so that the Interface measures ping response times to 3 machines whose IP addresses are, respectively,
• 192.168.100.11
• 192.168.100.12
• 192.168.100.13
PI-TCPResponse sends three ping requests, one right after the other. It does not wait until the measurement for the response time from 192.168.100.11 is finished before it sends pings to the other two machines.
In contrast, OSIsoft’s PI-Ping program (v1.4.0 and earlier) waits for a ping response time measurement to complete before it sends the next ping request.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you in getting the PI-TCPResponse Interface up and running. Users who are not familiar with PI interfaces should return to this section after reading the rest of this manual in detail.
You should follow the steps in the order listed below.
1. Install the PI-SDK. Verify this installation by running the AboutPI-SDK.exe program and clicking on Connect.
2. If necessary, obtain and install Microsoft Windows Installer.
3. Install the Interface itself by running pitcpresp.msi.
4. Choose a point source for use by the Interface.
5. Configure PI points.
For most cases, the InstrumentTag specifies the device.
Location1 is the interface identification number.
Location2 indicates the service.
Location3 should be 0.
Location4 specifies the scan class (and hence the scan frequency).
Location5 is used for debugging.
Exdesc specifies the trigger point for trigger-based inputs.
6. If desired, configure interface performance points.
7. If desired, configure an I/O Rate point.
8. Edit the startup command file (pitcpresp.bat).
9. Confirm the settings of the clock on the computer on which the Interface runs.
10. Set up security on the PI Universal Data Server so that it accepts data sent by the Interface.
11. With PI Buffer Server not running, run the Interface interactively.
12. Verify that data are correctly being written to the PI Universal Data Server.
13. Stop the interactive execution of the Interface.
14. If the Interface runs on a PI-API node, set the Shutdown attribute of configured PI points to 0.
15. Start PI Buffer Server.
16. Run the Interface as a Windows NT service.
17. Verify that data are correctly being written to the PI Universal Data Server.
18. Confirm that the Interface re-starts after a complete machine shutdown and restart.
Interface Installation on Windows NT
OSIsoft recommends that you install PI data collection interface programs on PI-API nodes instead of on PI Server nodes. A PI Server node is a computer on which the PI Universal Data Server runs. A PI-API node is any computer that has the PI Application Programming Interface (PI-API) installed and which is not a PI Server node.
The primary function of a PI Server node is to run the applications that compose the PI Universal Data Server. These applications archive data and provide data to client computers that request them. Thus, if PI interface programs are absent from the PI Server node, then PI Universal Data Server applications need not compete with these interface programs for this computer’s resources.
After you have installed and tested the Interface, you should enable the PI Buffer Server application. PI Buffer Server (also known as Bufserv) is a utility program distributed with the PI-API. It provides the capability to store and forward events to the PI Universal Data Server. The primary purpose of Bufserv is to allow continuous data collection when communications between the PI-API node and the PI Universal Data Server is lost. Communications will be lost when network problems exist, or when the PI Universal Data Server is shut down because of maintenance, upgrades, backups, or unexpected failures.
Please see the PI-API Installation manual for instructions on installing the PI-API and PI Buffer Server.
After confirming that the Interface and PI points have been configured properly to collect data, you should install the Interface as an automatic service under Windows NT. A Windows NT service keeps running even after the user has logged off. An automatic service automatically restarts when the computer itself restarts. This feature is useful in the event of a power failure.
Microsoft Windows Installer
The PI-TCPResponse interface program and its associated files are distributed as a Microsoft Windows Installer file called pitcpresp.msi. Computers running Windows 2000 already have Windows Installer built-in and can therefore process this file. However, if you have a Windows NT machine, you may need to download the Windows Installer redistributable, found via:
Otherwise, you will not be able to run this pitcpresp.msi file.
The PI-TCPResponse installation program first prompts you to install or update the PI-SDK, if necessary.
PI-SDK Installation and PIHOME
Installation of the PI-SDK creates the PIHOME directory tree. In particular, it creates a PIHOME entry in the pipc.ini configuration file that determines the PIHOME directory tree. The pipc.ini file is an ASCII text file located in the WinNT directory where Windows NT itself is installed (commonly, C:\WinNT).
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. The PIHOME directory does not need to be on the C: drive.
Interface Installation Procedure
Install PI-TCPResponse by running the pitcpresp.msi Windows Installer file. Windows Installer places the Interface and its associated files into a sub-directory of the PI-SDK/PI-API. For example, the following directory structure and files result:
C:\program files\pipc\interfaces\tcpresp\pitcpresp.exe
C:\program files\pipc\interfaces\tcpresp\pitcpresp.bat
C:\program files\pipc\interfaces\tcpresp\pitcpresp.doc
C:\program files\pipc\interfaces\tcpresp\pitcpresp.bat.new
The installation program also places debug symbols for the pitcpresp.exe file into a symbols\exe subdirectory of the Windows directory. For example,
C:\WinNT\symbols\exe\pitcpresp.dbg
If the Interface should crash, this debug file provides the standard Windows NT Drwtsn32 program with detailed information.
Installing the Interface as a Windows NT Service
The installation program asks you to choose from one of the following:
• install the Interface as a manual Windows NT service, or
• install the Interface as an automatic Windows NT service, or
• not install the Interface as a Windows NT service.
If you change your decision afterwards, you can use the PI-Interface Configuration Utility or manually type in the commands below.
Command lines
You can get help for installing the interface as a service at any time by using the -help command line parameter. For example,
C:\program files\pipc\interfaces\tcpresp\pitcpresp.exe –help
The commands below are shown on two lines because of space limitations. However, you should type them all as a single line.
|With PI-Buffer Server implemented |
|Manual Service |C:> pitcpresp.exe –install –display "PI-TCPResponse Interface" -depend "tcpip bufserv" |
|Automatic Service |C:> pitcpresp.exe –install –display "PI-TCPResponse Interface" –auto -depend "tcpip bufserv" |
|Without PI-Buffer Server implemented |
|Manual Service |C:> pitcpresp.exe –install –display "PI-TCPResponse Interface" -depend tcpip |
|Automatic Service |C:> pitcpresp.exe –install –display "PI-TCPResponse Interface" –auto -depend tcpip |
Services control panel
Check the Microsoft Windows NT services control panel to verify that the Interface was correctly added as a service. You can use the services control panel at any time to change the Interface from an automatic service to a manual service or vice versa.
PointSource
The PI point is the basic building block for controlling data flow to and from the PI Universal Data Server. The PointSource attribute is a single character that is used to identify a PI point as one that belongs to a particular interface. For example, you may choose the letter P to identify points that belong to the PI-TCPResponse Interface. To implement this identification, configure PI points such that their PointSource attribute is P. Then, if you use -ps=P on the Interface’s startup command line (described later) and start the Interface, PI-TCPResponse receives from PI Universal Data Server a list of every point with its PointSource set to P.
However, before the Interface begins data transfer for a point from this list, it examines additional PI point attributes. This examination further determines the validity of a PI point for use with the Interface. For additional information, see the section on Point Configuration and the description of the -ps parameter in Startup Commands.
PI Universal Data Server version 3.x comes pre-configured with several applications that use some of the otherwise available point source characters. In particular, the Totalizer program uses the point source character T; the Alarm program uses G and @; and the Performance Equations scheduler uses C. In addition, the Random Interface Simulator uses R and the RampSoak Simulator uses 9. Finally, the default point source character for PI points is L. Accordingly, you should not use any of the following point source characters to associate PI points with the PI-TCPResponse interface:
• 9
• C
• G
• L
• R
• T
• @
Of course, you also should not use any point source character that is already associated with another one of your interface programs.
PI Point Configuration
For PI Universal Data Server 3.x, points are created and their attribute fields are set via the PI-PointBuilder program, the PIConfig program, or the PI-SMT utility.
Every two minutes, PI-TCPResponse checks the PI Universal Data 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 that PI-TCPResponse measures, and
• the values that PI-TCPResponse sends to the PI Universal Data Server.
For this Interface, the most important point attributes are Instrument Tag, Location2, and Point Type.
Point Attributes
Tag
A tag is a label or name for a point. There is a one-to-one correspondence between a tag and a point.
You may use any tag name that conforms to the normal PI point naming conventions. See the PI Universal Data Server manual for the details regarding this naming convention.
PointSource
The PointSource is a single character used to identify a PI point as a point that belongs to a particular interface. For additional information, see the description for the -ps command line parameter and the Point Source section.
PointType
You may store the measured response time as one of the following point types:
• Float16 (scaled floating point values; accurate to with 1 in 32,767)
• Float32 (single precision floating point values)
• Float64 (double-precision floating point values)
• Int16 (15-bit non-negative integer values)
• Int32 (32-bit signed integers values)
In addition, you may store the result of a DNS lookup as a String type point.
For more information on these point types, see the PI Universal Data Server manual.
Instrument Tag
The Instrument Tag attribute specifies the computer containing the service whose response time PI-TCPResponse measures. The actual service whose response time is to be measured is specified in Location2 (described later).
For example, to measure the response time of a Web server, enter the following for the Instrument Tag:
device=a_company_
You may also specify the IP address of the computer:
device=192.168.100.10
The Instrument Tag can also contain the port number of the service. For example,
device=piserver.a_company_; port=5450
device=192.168.100.10; port=5450
Notice that a semicolon separates the device and port specifications.
If a port number is not specified, the Interface uses standard port numbers for measuring the response time of the following services:
|Service |Port Number |
|FTP |21 |
|HTTP |80 |
|SMTP |25 |
|POP3 |110 |
|IMAP |143 |
If a point is configured for a generic TCP/IP service (Location2 set to 5), you must specify a port number in the Instrument Tag attribute field.
If a point is configured for name resolution (Location2 set to 1), the device specification indicates the hostname or the IP addressed to be resolved. It does not indicate the name of the DNS server. The DNS server used is the one indicated in the Microsoft Windows TCP/IP settings of the computer running the Interface.
Location1
Location1 associates a point with a particular copy of PI-TCPResponse. Location1 is a positive integer from 1 to 99, inclusive. This number should match the value of the -id= parameter used in the startup command file (described later).
Location2
Location2 specifies the service whose response time the Interface measures. The value of Location2 must be between 1 and 6, inclusive.
|Location2 |Service |
|1 |DNS (name resolution) |
|2 |FTP |
|3 |HTTP (Web) |
|4 |SMTP (mail) |
|5 |Generic TCP/IP service; port number specification in the Instrument Tag attribute field is |
| |required |
|6 |Ping |
|7 |POP3 (mail) |
|8 |IMAP (mail) |
Location3
PI-TCPResponse does not currently use Location3. However, you should set this attribute to zero to accommodate future enhancements to the Interface.
Location4
The Location4 attribute field indicates the scan class number. PI-TCPResponse uses this attribute for scan-based input tags.
A scan class number is a positive integer. It refers to the instance of the appearance of the –f= parameter (described later) in the Interface startup command file. For example, if the file contains the following command:
pitcpresp –f=120 –f=180 –f=240 …
then the following scan classes are defined: 1, 2, and 3. So, for a point configured with Location4 equal to 2, PI-TCPResponse measures response times every 180 seconds.
Location5
Location5 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, you may wish to set Location5 to a non-zero value. See the Troubleshooting section of this manual for details.
ExDesc
PI-TCPResponse uses the extended descriptor attribute for Performance Points and Trigger-based input points.
Performance points
The Interface checks the extended descriptor attribute for the occurrence of the string PERFORMANCE_POINT. If it finds it, the Interface treats this point as a performance point. See the section called “Performance Points” for more information.
Trigger-based inputs
In contrast to values for scan-based input points (whose values are measured periodically), the Interface measures a value for a trigger-based point only when another PI point receives a new value. You configure a trigger-based input point by specifying the following in the extended descriptor attribute field:
event=PITriggerTag
In the above example, PITriggerTag is the tag name of the trigger point. An input is triggered when PITriggerTag receives a new value. The new value need not be different from the previous value. The new value only needs to have a timestamp that is greater than or equal to the previous value’s timestamp.
EngUnits
For numeric point types (i.e., all valid interface point types except String), set the engineering units attribute to milliseconds, msec, ms, or a variation thereof. The reason is that PI-TCPResponse measures response times in milliseconds. The resolution of measurements is 1 millisecond.
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 you change 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 the Interface will write SCAN OFF to a 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 Interface removes the point and writes SCAN OFF. For example, if you change the value of the PointSource of a PI point that is currently loaded by the Interface, the Interface removes this point and writes SCAN OFF.
Technically, PI-TCPResponse does not “scan” for values because it does not poll various devices for data. Instead, PI-TCPResponse measures the response times of TCP/IP services on various devices. However, because PI-TCPResponse operates within the PI Interface model, this document refers to such a measuring of values as a “scan”.
Shutdown
The Shutdown attribute of a PI point has the default value of 1, indicating that PI Universal Data Server will write a Shutdown digital state to this point upon PI Universal Data Server startup. These Shutdown events give you an indication of when data collection has stopped.
The timestamp used for Shutdown events is contained on a file on disk. When PI Universal Data Server shuts down, it stores the time of shutdown to this file. Also, while PI Universal Data Server is running, it updates this timestamp on file every 15 minutes. Thus, Shutdown events are accurate to within 15 minutes in the case of a power failure or an improper termination of the PI Universal Data Server.
You can change the Shutdown point attribute to 0 for a point and prevent PI Universal Data Server from writing a Shutdown event to this point. You should make this change when you run the Interface on a PI-API node and use PI Buffer Server. The reason is that when the PI Universal Data Server shuts down, Bufserv provides temporary storage (i.e., buffering) of values collected by the Interface. Therefore, data collection continues, and the writing of Shutdown is inappropriate.
For more information on Shutdown events, refer to the PI Universal Data Server manual.
Note: The Shutdown events written by the PI Universal Data Server are independent of the Shutdown events that will be written by the Interface if you specify the -stopstat=Shutdown command-line parameter.
Examples
DNS resolution from IP address to name
|Instrument tag |device=192.168.100.54 (this is NOT the DNS server; it is the IP address to|
| |be resolved) |
|Location2 |1 |
|Point type |String |
Response time for DNS resolution from IP address to name
|Instrument tag |device=192.168.100.54 (this is NOT the DNS server; it is the IP address to|
| |be resolved) |
|Location2 |1 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
DNS resolution from a name to IP address
|Instrument tag |device=host. |
|Location2 |1 |
|Point type |String |
Response time for DNS resolution from a name to IP address
|Instrument tag |device=host. |
|Location2 |1 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
Response time for an FTP server running on 192.168.100.10
|Instrument tag |device=192.168.100.10 |
|Location2 |2 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
Response time for a Web server running on 192.168.100.10
|Instrument tag |device=192.168.100.10 |
|Location2 |3 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
Response time for an SMTP Mail server running on 192.168.100.10
|Instrument tag |device=192.168.100.10 |
|Location2 |4 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
Response time for a PI Server running on 192.168.100.10
|Instrument tag |device=192.168.100.10; port=5450 |
|Location2 |5 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
For the measurement of PI Universal Data Server response times, do not specify the same PI Universal Data Server for device= as that in the –host= command line parameter (described later).
Response time for a Windows Terminal server running on 192.168.100.10
|Instrument tag |device=192.168.100.10; port=3389 |
|Location2 |5 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
Ping response time for 192.168.100.10
|Instrument tag |device=192.168.100.10 |
|Location2 |6 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
Response time for a POP3 Mail server running on 192.168.100.10
|Instrument tag |device=192.168.100.10 |
|Location2 |7 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
Response time for an IMAP Mail server running on 192.168.100.10
|Instrument tag |device=192.168.100.10 |
|Location2 |8 |
|Point type |float16 / float32 / int16 / int32 |
|EngUnits |milliseconds |
The installation program installs a file called tcpresp_example.xls. You can use this file as a template for tag building using Microsoft Excel and PI-SMT.
Performance Point Configuration
Performance points monitor the amount of time in seconds that the Interface takes to complete a scan for a particular scan class. (For PI-TCPResponse, a “scan” is the measurement of the response time of a particular service.) The closer this scan time is to 0, the better the performance. The Interface records the performance point values to millisecond resolution.
Performance points are configured as follows:
1. Set the extended descriptor to
PERFORMANCE_POINT=interface_id
where interface_id corresponds to the value specified in the –id= command line parameter.
2. Set Location4 to correspond to the scan class whose performance will be monitored. For example, to monitor scan class 2, set Location4 to 2. See the –f= command line parameter (described later) for a description of scan classes.
3. Set the PointSource attribute to correspond to the –ps= command line parameter.
4. Set the PointType attribute to Float32.
I/O Rate Point Configuration
An 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 sent by the Interface to the PI Universal Data Server. Because values are averaged over a 10-minute interval, the first value is not written to PI Universal Data Server until 10 minutes after the Interface has started. You can configure one I/O Rate point for each copy of the Interface that is in use.
Monitoring I/O Rate points
You can monitor the value of an I/O Rate point by using a PI client application such as PI-ProcessBook or PI-DataLink.
Point attributes
Use the following PI point attribute values for an I/O Rate point.
|Attribute |Value |
|PointSource |L |
|PointType |float32 |
|Compressing |0 |
|ExcDev |0 |
|EngUnits |events/minute |
You may accept the default values for the other point attributes.
Configuration on the interface node
The following procedure for I/O Rate point configuration on the interface node assumes that the tag name of this point is sytcpresp01. An interface node is the computer on which the Interface runs. Either a PI-API node or a PI Server node can be an interface node.
1. Edit or create the file named iorates.dat in the dat subdirectory of the directory where the PI-API was installed. You can find out the name of this PI-API directory by looking at the pipc.ini file located in the Windows NT directory (typically, C:\WinNT). The pipc.ini file contains an entry for PIHOME and PIPCSHARE. The PI-API directory is given either by the value for PIPCSHARE (if both PIHOME and PIPCSHARE exist in pipc.ini) or by the value for PIHOME (if only PIHOME exists).
2. Set the value for the -ec parameter in the Interface’s startup command file (described later) to be the same number as that entered in the iorates.dat file. For the above example,
sytcpresp01,11
3. Because you have made changes to the Interface’s startup command file, you need to stop and restart the Interface for these changes to take effect.
Startup Command File
For proper operation, the Interface requires various command-line parameters. These parameters must begin with the dash character (-). You should put these parameters, along with the name of the Interface executable, into a startup command file. For example,
pitcpresp.exe –ps=P –f=120 –ec=11
For Windows NT, 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 contents of a PI Interface command file may contain the caret line continuation character (^). For example, a pitcpresp.bat file with contents
pitcpresp.exe ^
–ps=P ^
–f=120 ^
–ec=11
is 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 –f=120 "–stopstat=Intf Shut"
Command-Line parameters
Some of the following parameters are required and some are optional. However, they may appear in any order on the command line.
|Command line parameters |
|-ps= |The –ps parameter specifies the point source character for the Interface. Each |
|(required) |instance of PI-TCPResponse uses the –ps and –id parameters to identify uniquely its|
| |particular list of points to service. The value for the –ps parameter is not case |
| |sensitive. That is, –ps=P is identical to –ps=p. |
|-id= |The –id parameter specifies the Interface number from 1 to 99, inclusive. Each |
|(required) |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 you|
| |specify –id=8, then the message log file will have contents such as: |
| |31-May-01 16:39:45 |
| |PI-TCPResponse 8> 125 points found for point source P |
|-f=HH:MM:SS, |The –f parameter is used for input points. It defines the time period between |
|hh:mm:ss |scans in terms of hours (HH), minutes (MM), and seconds (SS). You can schedule the|
|or |scans to occur at discrete moments in time with an optional time offset specified |
|-f=SS,ss |in terms of hours (hh), minutes (mm), and seconds (ss). If you omit HH and MM, |
|(at least 1 |then the specified time period is assumed to be in seconds. |
|required) |Each instance of –f defines a scan class for the Interface. There is no limit to |
| |the number of scan classes that you can define. The first occurrence of –f defines |
| |scan class number 1, the second occurrence defines scan class number 2, and so on. |
| |For interface inputs points, the Location4 point attribute defines a particular |
| |scan class, and consequently, a scan frequency and/or time offset. For example, |
| |all input interface points that have a Location4 value of 1 will receive input |
| |values at the frequency defined by the first scan class. Similarly, all input |
| |points that have a Location4 value of 2 will receive input values at the frequency |
| |specified by the second scan class, and so on. |
| |The following example defines 2 scan classes: |
| |–f=00:02:00,00:00:05 –f=00:05:00 |
| |or equivalently, |
| |–f=120,5 –f=300 |
| |The first scan class has a frequency of 2 minutes with an offset of 5 seconds, and |
| |the second scan class has a frequency of 5 minutes. |
| |WARNING: Think very carefully before setting scan frequencies for less than 2 |
| |minutes. If you have many points defined, the combination of both multiple and |
| |frequent connection requests sent by the Interface may overwhelm your network |
| |and/or the devices whose response times you are trying to measure. |
| |When an offset is specified, the scans occur at discrete moments in time according |
| |to the formula |
| |scan time = (reference time) + n * (frequency) + offset |
| |where n is an integer and reference time is midnight on the day that the Interface |
| |starts. In the above example, frequency is 120 seconds and offset is 5 seconds for|
| |the first scan class. These numbers mean that if the Interface starts at 05:06:06,|
| |the first scan occurs at 05:06:10, the second scan occurs at 05:08:10, and so on. |
| |Because the second scan class does hot have an offset specified, absolute scan |
| |times are undefined. |
| |(In the above example, 05:05:06 refers to the clock running on the PI Universal |
| |Data Server computer and not the clock running on the interface computer.) |
| |The existence of a scan class does not guarantee that the Interface will scan the |
| |associated points at the given frequency. If the is heavily loaded, or if many |
| |timeouts to devices occur, then some scans may occur late or be skipped entirely. |
| |See the section called "Performance Point Configuration" for more information on |
| |monitoring the performance of scans. |
| |You can use a ",L" to tell the Interface to adhere to strict wall clock time. For |
| |example, |
| |-f=24:00:00,00:08:00,L |
| |corresponds to 1 scan a day at 8 AM (PI Universal Data Server wall clock time). |
|-host=host:port |The –host parameter specifies either the IP address or the TCP/IP hostname of the |
|(optional, but |machine on which the PI Universal Data Server runs. The syntax for –host should |
|recommended) |include the port number for communications between the PI-API and PI Universal Data|
| |Server. For example, |
| |pitcpresp.exe –ps=P –host=piserver:5450 |
|-wt |The –wt parameter defines the time (in milliseconds) that the Interface waits for a|
|(optional) |service to respond. If the service does not respond within this time, the |
| |Interface writes the digital state I/O Timeout to the associated point. For |
| |example, to specify a timeout wait time of 8 seconds: |
| |pitcpresp.exe –ps=P –wt=8000 |
| |If you do not specify this parameter, the Interface uses a default value of 5000 |
| |milliseconds. |
|-exittime |The –exitttime parameter is used when the Interface exits. It defines the time (in|
|(optional) |seconds) that the Interface will wait for all outstanding measurements to complete |
| |before exiting. If the Interface exits before these measurements complete, it |
| |often crashes. For example, to specify an exit wait time of 2 minutes: |
| |pitcpresp.exe –ps=P –exittime=240 |
| |If you do not specify this parameter, the Interface uses a default value of 120 |
| |seconds. |
|-stopstat= |The –stopstat parameter causes the Interface to write the specified digital state |
|(optional, but |to its list of points before it exits. The recommended digital state is Intf Shut.|
|recommended) |Because there is a space in this digital state value, you need to use quotation |
| |marks. For example, |
| |pitcpresp.exe –ps=P "–stopstat=Intf Shut" |
| |If you specify a digital state that does not exist in the PI Universal Data Server,|
| |the Interface does not write any digital state values before it exits. |
|-ec= |The –ec parameter indirectly specifies the I/O Rate point associated with the |
|(optional) |Interface. For example, if |
| |pitcpresp.exe –ps=P –ec=11 |
| |and the iorates.dat file contains |
| |sytcpresp01,11 |
| |then the tag name of the I/O Rate point used by the Interface will be sytcpresp01. |
|-sn |The –sn parameter causes the Interface to send a value to the PI Universal Data |
|(optional) |Server at every scan. If you do not specify –sn, the Interface performs exception |
| |reporting. Exception reporting means that the Interface sends a value to PI |
| |Universal Data Server only if |
| |this value differs from the previous value by a user-specified amount, or |
| |a user-specified time interval has elapsed since the sending of the previous value.|
| |These user-specified criteria are known as exception specifications. See the PI |
| |Universal Data Server manual for more information on exception specifications and |
| |exception reporting. |
Sample pitcpresp.bat file
The following is an example of the contents of a pitcpresp.bat file:
rem pitcpresp.bat
rem
rem required parameters
rem -ps= point source; must match PointSource point attribute
rem -id= interface ID; must match Location1 point attribute
rem -f= scan frequency class; referenced by Location4 point attribute
rem
rem optional parameters
rem -host= PI Universal Data Server name and port number
rem -wt= wait time in milliseconds before writing I/O Timeout
rem if not specified, the Interface uses 5000ms
rem -exittime= wait time in seconds during interface's exit; prevents an
rem interface crash at exit. If not specified, the Interface uses
rem 120s.
rem -stopstat= digital state to write when Interface exits
pitcpresp.exe -ps=P -id=1 -f=00:05:00 -host=pimachine:5450 "-stopstat=Intf Shut"
The above command line tells the Interface to
• service PI points whose PointSource is P and Location1 is 1,
• measure response times every 5 minutes,
• send the measured values to the PI Universal Data Server named pimachine,
• write Intf Shut to its list of points upon exit.
Interface node clock
You must make sure that the time and time zone settings on your computer are correct. To confirm, run the Date/Time applet located in the Windows NT Control Panel. If your locale observes Daylight Savings Time, check the box marked “Automatically adjust clock for daylight savings changes”. For example,
[pic]
In addition, make sure that the TZ environment variable is not defined. You can see all of the currently defined environment variables by opening a Command Prompt window and typing set. That is,
C:> set
You should confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel. Click on the Environment tab. Remove TZ from the list of environment variables.
Security
If you installed the Interface on a PI Server node, this section probably does not apply.
If you installed the Interface on a PI-API node that is already running other PI interface programs that are successfully sending data to PI Universal Data Server, this section probably does not apply.
In general, you will need to edit PI Universal Data Server’s Trust (PI Universal Data Server v3.3) or Proxy (version 3.2) table. Such a procedure modifies the security configuration of PI Universal Data Server and allows programs running on a PI-API node to write data to PI points.
PI Universal Data Server v3.2
For PI Universal Data 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,proxyaccount
piapimachine,piadmin
@quit
In place of piapimachine, put the name of the PI-API node as it is seen by PI Universal Data Server.
PI Universal Data Server v3.3
For PI Universal Data Server v3.3, the following example demonstrates how to edit the PI Trust table:
C:\PI\adm> piconfig
@table pitrust
@mode create
@istr Trust,IPAddr,NetMask,PIUser
a_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 you want the Interface to be entrusted as; piadmin is usually an appropriate user
See the PI System Management chapter in the PI Universal Data Server manual for more details on security configuration.
If the Interface cannot write data to PI Universal Data Server because of security issues, it reports a –10401 error in the pipc.log file. See the section “Error and Informational Messages” for additional information on error messaging (p. 47).
Starting / Stopping the Interface
Starting the Interface interactively
To start the Interface interactively, open a Windows NT command prompt window and go to the directory where the pitcpresp.exe and pitcpresp.bat files are located. Then, run the command file. For example,
C:\program files\pipc\interfaces\tcpresp> pitcpresp.bat
To stop a copy of the interface that is currently running interactively, simply use Control-C.
Starting the Interface as a service
To start the Interface as a Windows NT service, open a Windows NT command prompt window and go to the directory where the pitcpresp.exe and pitcpresp.bat files are located. Then, use the –start parameter to pitcpresp.exe. For example,
C:\program files\pipc\interfaces\tcpresp> pitcpresp.exe -start
The Interface will then display a message informing you whether it has successfully started as a service. Even if the message indicates a successful startup, you should make sure the Interface is still executing by running the Services applet in the Control Panel.
If the Interface terminates for whatever reason, it does not display any error messages to the screen. You must consult the pipc.log file to see error messages. See the section “Appendix A: Error and Informational Messages,” (p. 2) for additional information.
Stopping the Interface running as a service
To stop the Interface when it is currently running as a Windows NT service, use the -stop parameter to pitcpresp.exe. For example,
C:\program files\pipc\interfaces\tcpresp> pitcpresp.exe -stop
The Interface will then display a message informing you whether it has terminated successfully.
Other service related commands
To determine whether the Interface is currently running as a Windows NT service, use the -query parameter to pitcpresp.exe. For example,
C:\program files\pipc\interfaces\tcpresp> pitcpresp.exe -query
The remove the Interface from Windows NT’s list of services, use the -remove parameter to pitcpresp.exe. For example,
C:\program files\pipc\interfaces\tcpresp> pitcpresp.exe -remove
Buffering
For complete information on buffering, please refer to the PI-API installation instructions.
PI Buffer Server (also known as Bufserv) is a utility program distributed with the PI-API. It provides the capability to store and forward events to the PI Universal Data Server. The primary purpose of Bufserv is to allow continuous data collection when communications between the PI-API node and the PI Universal Data Server is lost. Communications will be lost when network problems exist, or when the PI Universal Data Server is shut down because of maintenance, upgrades, backups, or unexpected failures.
Entries in a configuration file called piclient.ini control the operation of Bufserv. In particular, if this file indicates that Bufserv should not buffer data, then the Interface will send data directly to PI Universal Data Server, even though PI Buffer Server itself may be running. (On Windows NT, PI Buffer Server runs as a Windows NT service.)
Note: When buffering is configured to be on, the bufserv process must be started before other programs that use the PI-API so that these programs can access the shared buffering resources. Any program that makes a connection to PI Universal Server has this requirement (i.e., it must start after bufserv) even if it does not write data to PI Universal Data Server.
On Windows NT, the piclient.ini file is found in the dat subdirectory of the PIHOME directory. A typically location for this file is
c:\program files\pipc\dat\piclient.ini.
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 using a text editor such as Notepad.
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 PI |
| | | |Universal Data Server (seconds) |
|RETRYRATE |0 - 2,000,000 |120 |When the buffering process discovers the PI Universal |
| | | |Data Server 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 PI Universal Data Server (milliseconds) |
In addition to the [APIBUFFER] section, there is a [PISERVER] section that defines an optional time offset change that may occur between the PI-API node and the PI Server node.
|Keywords |Values |Default |Description |
|DSTMISMATCH |0 - 2,000,000 |0 |The allowable jump in time offset between the PI |
| | | |Server node’s local time and PI-API node’s local |
| | | |time. Typically set to 3600 if the nodes are in |
| | | |time zones whose DST rules differ (seconds) |
On Windows NT, the pilogin.ini file specifies the name of the PI Universal Data Server to which Bufserv sends data. The pilogin.ini file is located in the same directory as piclient.ini. The section [Defaults] together with the keyword PIServer indicate the default PI Universal Data Server.
Example piclient.ini file
On Windows NT, the contents of a piclient.ini file might look like:
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=100000
RETRYRATE=600
The BUFFERING=1 indicates that buffering is enabled. The value of 100,000 for the MAXFILESIZE entry specifies a maximum file size of 100,000 kilobytes (or 100 megabytes) for the storage of buffered data. (Note that commas or other separators are not used in the numeric entries.) The RETRYRATE of 600 means that Bufserv waits 600 seconds (or 10 minutes) after detecting the unavailability of PI Universal Data Server before trying to re-connect.
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 interface startup command line determines the ID identifier.
Message Logs
The name of the message log is PIHOME\dat\pipc.log. Messages 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, it writes messages to the log if there are problems with the configuration of the points.
Messages
The following is an example of a successful startup of the Interface:
14-Aug-01 15:46:12
PI-TCPResponse> C:\program files\PIPC\interfaces\tcpresp\pitcpresp.exe pitcpresp.exe
-ps=P -id=35 -host=localhost:5450 -f=00:10:00 -stopstat=Intf Shut -wt=10000
14-Aug-01 15:46:12
PI-TCPResponse> Starting interface as a service (pitcpresp), Point source: P
14-Aug-01 15:46:12
PI-TCPResponse> Uniint version>@(#)uniint.cxx 3.3.3
14-Aug-01 15:46:12
PI-TCPResponse> API version> 1.3.4
14-Aug-01 15:46:13
PI-TCPResponse> PI-SDK Version 1.1.0, Build 142
14-Aug-01 15:46:13
PI-TCPResponse> Setting PISDK Connection Timeout to 15 seconds for server localhost
14-Aug-01 15:46:13
PI-TCPResponse> Setting PISDK General Timeout to 60 seconds for server localhost
14-Aug-01 15:46:14
pitcpresp.exe>PI-API> Initial connection to [localhost:5450][1]
14-Aug-01 15:46:14
PI-TCPResponse> PIAPI successfully connected to piserver localhost:5450
14-Aug-01 15:46:14
PI-TCPResponse> Server Version: PI 3.3, Build 361.43
14-Aug-01 15:46:14
PI-TCPResponse> PIAPI explicit login succeeded
14-Aug-01 15:46:14
PI-TCPResponse> PISDK successfully connected to piserver localhost via port 5450
14-Aug-01 15:46:14
PI-TCPResponse 35> Starting PI-TCPResponse, version 0.0.7
14-Aug-01 15:46:14
PI-TCPResponse 35> info> wait timeout set to 10000 milliseconds
14-Aug-01 15:46:14
PI-TCPResponse 35> info> -exittime not specified; using default of 120 seconds
14-Aug-01 15:46:14
PI-TCPResponse 35> Uniint is running in Extended API Mode with options 0x89
14-Aug-01 15:46:14
PI-TCPResponse 35> Uniint was compiled to use the PI-SDK
14-Aug-01 15:46:14
PI-TCPResponse 35> Digital state caching initialized successfully
14-Aug-01 15:46:14
PI-TCPResponse 35> 1 Scan classes have been defined
14-Aug-01 15:46:14
PI-TCPResponse 35> Scan class 1, update period = 600.000000 seconds, unspecified
phase offset
14-Aug-01 15:46:14
PI-TCPResponse 35> 1 UNSOLICITED Scan class has been defined
14-Aug-01 15:46:20
PI-TCPResponse 35> 6 points found for point source N
14-Aug-01 15:46:20
PI-TCPResponse 35> 0 unique event classes have been established
14-Aug-01 15:46:20
PI-TCPResponse 35> 0 output points have been established
14-Aug-01 15:46:20
PI-TCPResponse 35> (UTC time on server node - UTC time on interface node) = 0
System errors and PI errors
Operating system errors are associated with positive error numbers. Errors related to the PI System are associated with negative error numbers.
You can obtain descriptions of operating system and PI System errors with the pidiag program found on the computer running PI Universal Data Server. This program is located in the adm subdirectory of the directory where PI Universal Data 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
Troubleshooting
Location5
A 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, you do not have to stop and re-start the interface to enable/disable these debugging messages. (However, you may have to wait up to 2 minutes for point changes to take effect.)
|Location5 |Meaning |
|0 |no debugging |
|1 |minimum debugging |
|2 |medium debugging |
|3 |full debugging |
The effects of the value of Location5 are cumulative. That is, a debug value of 2 causes the actions associated with a debug value of 1 also to be taken.
The examples below use a test point named tcpresp_test.
Location5 set to 1
A debugging value of 1 results in messages relating to whether the Interface has loaded or rejected the point. For example,
PI-TCPResponse 1> pt (tcpresp_test) LOADED
and
PI-TCPResponse 1> pt (tcpresp_test) 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. For ping points (Location2 set to 6), the Interface logs a message when it does not receive an ICMP_ECHOREPLY in response to the ping that it sent. For example,
PI-TCPResponse 1> pt (tcpresp_test) ICMP_ECHOREPLY not received
For other response time measurements, the Interface prints the message it receives from the underlying TCP/IP software. For example,
PI-TCPResponse 1> pt (tcpresp_test) connect() failed for 192.168.100.172:3389;
err:10061 Connection Refused; is the device listening on the specified port?
Location5 set to 3
A 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 ping response times,
PI-TCPResponse 1> pt (tcpresp_test), sentTicks=898939857 rcvTicks=898940017
elapsedTime=160
This message tells you that when the Interface sent the ping request, the internal clock of the interface node had a value of 89,8939,857 milliseconds. When the Interface received the reply message, the clock had a value of 89,8940,017 milliseconds. The measured ping response time is therefore 160 milliseconds (89,8940,017 minus 89,8939,857). The Interface uses the Microsoft Windows function GetTickCount() to retrieve the number of milliseconds.
PI-TCPResponse 1> pt (tcpresp_test) aMsg.rval is 160.00
PI-TCPResponse 1> pt (tcpresp_test) aMsg sent to queue
These messages tell you that the Interface has stored the value of 160.0 into its internal queue.
PI-TCPResponse 1> pt (tcpresp_test), found matching message in queue
PI-TCPResponse 1> pt (tcpresp_test), drval=160.00 returned to UniInt
These messages tell you 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 you do not see the message
PI-TCPResponse 1> pt (tcpresp_test), ... returned to UniInt
the reason is that the response time you are trying to measure is too long, and a timeout occurred.
In general, if the values for a point are not what you expect, set the point’s Location5 attribute to 3 and examine the message log. After you have finished, you can set Location5 back to 0 to prevent these debugging messages.
You should not have too many points with Location5 set to 3. Otherwise, the message log will become very large.
Common problems
Interface exits on startup
If the Interface immediately exits upon startup, the most likely cause is that required command line parameters are not specified. PI-TCPResponse requires both of the following command line parameters
• –ps= (point source character)
• –id= (interface identifaction number)
If you omit either of these parameters, the Interface exits.
No new value for a point
If 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 Universal Data 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 Universal Data Server v3.2) or the PI Trust Table (PI Universal Data Server v3.3).
Value of 0 for a point
A value of 0 for a point usually means that the measured response time is less than 10 milliseconds. This lower bound of 10 milliseconds is a limitation of the Windows NT operating system.
Value of Bad Input for a point
A 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, you want to measure the response time of the Web server named . Accordingly, you configure a point such that its Instrument Tag contains
device=
Before the Interface can send an HTTP request to , 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.
For points configured for the measurement of ping response times (Location2 equal to 6), the Interface writes Bad Input when it receives a reply message other than an ICMP_ECHO. In particular, if the Interface receives an ICMP_REDIRECT, it writes Bad Input to the point.
See the Technical Details section of this document for more reasons why the Interface writes Bad Input to a point. Also, you can set the point’s Location5 attribute to 3 to tell the Interface to print out the reason it is writing Bad Input.
Value of I/O Timeout for a point
A value of I/O Timeout for a point indicates that the Interface did not receive a response message within the time specified by the value of the –wt command line parameter. The units of the –wt parameter are in milliseconds.
If you did not use the –wt parameter, a value of I/O Timeout means that the Interface did not receive a response message within 5 seconds.
Technical Details
This section describes some of the technical details of the PI-TCPResponse Interface. It references standards documents such as RFCs (Request for Comments). RFCs are publicly available. For example, see
DNS server response (Location2 = 1)
PI-TCPResponse measures the response time of your default nameserver. To find out the IP address of this nameserver, use the nslookup at the Windows NT command prompt. For example,
C:> nslookup
Address: 192.168.100.45
If the device specified in the Instrument Tag attribute is an IP address, the Interface uses the function gethostbyaddr(). Otherwise, it uses the function gethostbyname().
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.
FTP server response (Location2 = 2)
PI-TCPResponse connects to the FTP port of the specified device. The FTP port is either the default (port number 21) or a user-specified (via port= in the Instrument Tag) port. After the connection is established, the Interface waits for the FTP server to send a message that contains the text:
220
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 response time measured by the Interface is the amount of time required, starting from the connection request, for the FTP server to send the message containing 220. If the Interface does not receive a message containing 220, it writes the value Bad Input.
HTTP server response (Location2 = 3)
PI-TCPResponse connects to the HTTP port of the specified device. The HTTP port is either the default (port number 80) or a user-specified (via port= in the Instrument Tag) port. After the connection is established, the Interface sends the following message to the HTTP server:
HEAD / HTTP/1.0
where is the carriage return character. It then waits for the HTTP server to send a message that contains the text:
200
The reason is that RFC 1945 defines a status code of 200 as okay.
The response time measured by the Interface is the amount of time required, starting from the connection request, for the HTTP server to send a response message containing 200. If the Interface does not receive a message containing 200, it writes the value Bad Input.
SMTP server response (Location2 = 4)
PI-TCPResponse connects to the SMTP port of the specified device. The SMTP port is either the default (port number 25) or a user-specified (via port= in the Instrument Tag) port. After the connection is established, the Interface waits for the SMTP server to send a message that contains the text:
220
The reason is that RFC 2821 defines a status code of 220 as Service Ready.
The response time measured by the Interface is the amount of time required, starting from the connection request, for the SMTP server to send the message containing 220. If the Interface does not receive a message containing 220, it writes the value Bad Input.
Generic TCP server response (Location2 = 5)
PI-TCPResponse connects to the user-specified (via port= in the Instrument Tag) port of the device. 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.
Ping response (Location2 = 6)
PI-TCPResponse uses the GetTickCount() function to set a timestamp. The Interface then sends an ICMP echo message to the device. After it receives an ICMP echo reply message, it calls GetTickCount() again to get another timestamp. The difference between these two timestamps is the response time measured by the Interface.
If PI-TCPResponse does not receive an ICMP echo reply message, it writes the value Bad Input. If the Interface does not receive a message from the device being pinged, but instead receives a message from an intermediate router, it writes the value of I/O Timeout.
POP3 server response (Location2 = 7)
PI-TCPResponse connects to the POP3 port of the specified device. The POP3 port is either the default (port number 110) or a user-specified (via port= in the Instrument Tag) port. After the connection is established, the Interface waits for the POP3 server to send a message that contains the text:
+OK
RFC 1939 indicates that +OK is a positive status indication.
The response time measured by the Interface is the amount of time required, starting from the connection request, for the POP3 server to send the message containing +OK. If the Interface does not receive a message containing +OK, it writes the value Bad Input.
IMAP server response (Location2 = 8)
PI-TCPResponse connects to the IMAP port of the specified device. The IMAP port is either the default (port number 143) or a user-specified (via port= in the Instrument Tag) port. After the connection is established, the Interface waits for the IMAP server to send a message that contains the text:
* OK
RFC 2060 indicates that "* OK" is a positive status indication.
The response time measured by the Interface is the amount of time required, starting from the connection request, for the IMAP server to send the message that contains "* OK". If the Interface does not receive a message containing "* OK", it writes the value Bad Input.
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.