Ping Interface to the pi system

Digital States

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

Digital State Sets

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

The PI-Ping Interface does not support digital type points.

System Digital State Set

Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of point 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.

PointSource

The PointSource is a single, unique character that is used to identify a PI point as a point that belongs to a particular interface. For example, the letter J may be chosen to identify points that belong to the PI-Ping Interface. To implement this identification, set the PointSource attribute to J for every PI Point that is configured for the PI-Ping Interface. Then, when -ps=J is used on the startup-command line of the PI-Ping interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of J. 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 Interface Point Configuration section.

Case-sensitivity for PointSource Attribute

The 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=J and -ps=j are equivalent.

Reserved Point Sources

Several 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 L or Lab. Therefore, it would be confusing to use L or 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 Configuration

In the PI System, a 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 Attributes

Use the point attribute fields below to define the point configuration for the Interface, including specifically what data to transfer.

Tag

A 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 System documentation often uses the terms tag and point synonymously.

Length

The 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 explains this limitation in more detail. When the maximum possible lengths differ for the various installed software, the shortest length applies.

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

PointSource

The PointSource is a single, unique character 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.

PointType

PI-Ping supports the recording of ping response times into the following PI point types:

• 
  Int16
  
• 
  Int32
  
• 
  Float16
  
• 
  Float32
  
• 
  Float64
  

For more information on the individual point types, see the PI Server manuals.

Location1

Location1 indicates the copy of the Interface that the point belongs to. The value of this attribute must match the -id startup parameter.

However, if the startup command file does not contain the -id parameter, the Interface ignores the value in Location1 and attempts to services all point whose Point Source attribute matches the required –ps parameter.

Location2

The Location2 attribute specifies the number of pings that the Interface sends to the remote machine. The Interface waits for the reply of the most recently transmitted ping before sending the next one. Moreover, the Interface completes the measurement of the average response time for one point before starting on the next one.

If Location2 is 0, the Interface sends one ping to the remote machine.

Location3

The Location3 attribute specifies the minimum number of valid ping responses (i.e., non-timed out replies) that is required in order for the Interface to write a value to the PI point. For example, the user has configured a PI point to send 10 pings to the remote machine (i.e., Location2 set to 10). However, he wants the Interface to write the average ping response time to the PI point only if the remote machine replies to at least 8 of these pings. Therefore, he specifies this threshold number of 8 in Location3.

If Location3 is 0, the Interface requires a minimum number of valid ping responses that is equal to half of the Location2 value, rounded up to the nearest integer. (The exception is a Location2 value of 0, which requires one valid ping response.) For example,

Location3	Location2 (pings to send)	Minimum number of valid ping responses required
0	0	1
0	1	1
0	2	1
0	4	2
0	5	3

If the Interface does not receive the minimum number of valid ping responses, it writes I/O Timeout to the PI point.

OSIsoft recommends setting Location2 to 4 and Location3 to 1. These numbers represent a compromise between sending (a) too many pings that create unnecessary network traffic, and (b) too few pings that may lead to erroneous reports of I/O Timeout when the remote device is actually up.

Location4

Scan-based Inputs

The PI-Ping Interface supports scan-based (or more precisely, time-based) measurement of data. The Location4 attribute defines the scan class for the PI point. This scan class determines the frequency at which the Interface measures ping response times.

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

PIPing.exe –f=00:05:00 –f=00:10:00 –f=00:15:00 ...

then three scan classes are defined: 1, 2, and 3.

In the above example, for points with Location4 set to 1, PI-Ping measures ping response times once every 5 minutes (–f=00:05:00). For tags with Location4 set to 2, the Interface measures once every 10 minutes (–f=00:10:00).

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

Event-based Inputs

Location4 should be set to zero for these points.

Location5

The Location5 attribute specifies the debug level for the PI point. Currently, the Interface supports a single level of debugging. Please see the Troubleshooting section for more information.

The user should set Location5 to a non-zero value only at the request of OSIsoft’s Technical Support. Otherwise, the Interface will fill up the log file with extraneous messages.

InstrumentTag

Length

The 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 explains this limitation in more detail. When the maximum possible lengths differ for the various installed software, the shortest length applies.

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	32
Below 1.6	3.4.370.x or higher	32
Below 1.6	Below 3.4.370.x	32

The instrument tag contains the IP address or the name of the machine whose ping response time PI-Ping will measure. The following are examples of values for the InstrumentTag attribute:

192.168.55.78

remoteOfficeRouter

ExDesc

Length

The 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 explains this limitation in more detail. When the maximum possible lengths differ for the various installed software, the shortest length applies.

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	80
Below 1.6	3.4.370.x or higher	80
Below 1.6	Below 3.4.370.x	80

Data Size

PI-Ping sends an ICMP echo request packet whose Data field is 56 bytes. To use a data size that is different from this number, specify the DATASIZE keyword. For example,

DATASIZE=20;

tells PI-Ping to send an ICMP echo request packet that contains a Data field size of 28 bytes.

Note: As indicated in the previous example, there is an 8 byte difference between the number indicated by DATASIZE= and the size of the Data field in the ICMP packet. The reason for this difference is because of backwards compatibility issues.

Interface Node with Multiple IP Addresses

A PI Interface node on which PI-Ping runs may have multiple network interface cards, and hence, multiple IP addresses. Normally, these IP addresses are on separate networks; for example a machine may have addresses 192.168.10.100 as well as 208.242.148.10. The Windows operating system will use the appropriate network card for sending pings. For example, in order for the Interface to ping 192.168.10.101, Windows will use the network card with address 192.168.10.100. Likewise, in order for the Interface to ping 208.242.148.11, Windows will use the network card with address 208.242.148.10.

However, there may be instances where multiple IP addresses are on the same network; for example, a machine may have addresses 192.168.10.100 and 192.168.10.102. For such a situation, the user may explicitly specify an IP address that the Interface will use to ping the remote device. He indicates so via the OUTADDR keyword. For example,

OUTADDR=192.168.10.100;

tells the Interface to use the network card whose IP address is 192.168.10.100.

Note: The Windows IPHLPAPI.DLL and ICMP.DLL libraries do not support the transmission of pings from a particular network card. Thus, if the user specifies the OUTADDR keyword, the Interface uses raw sockets to send the ping. However, the ping times obtained via this method often do not agree with those obtained via the Windows "ping" command. Thus, the user should not use the OUTADDR keyword unless absolutely necessary.

Performance Points

The PI-Ping Interface checks the extended descriptor for the string "PERFORMANCE_POINT." If it finds this character string, the Interface treats this point as a performance point. See the section called "Performance Points."

Event-based Inputs

For the Interface to measure ping response times based on an event (rather than based on a periodic time interval), specify the following in the ExDesc attribute:

Event=PItag;

Here, PItag is the tag name for the event point. The Interface must be connected to the PI Server to receive the notifications of new values for PItag.

An input for the interface point is triggered when a new value is sent to the Snapshot of the event point. The new value for the event point does not need to be different than the previous Snapshot value to trigger the input. However, the timestamp of the new value must be greater than (i.e., more recent than) or equal to the timestamp of the previous value.

Alternatively, conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows:

Event='trigger_tag_name'

The trigger tag name must be in single quotes, and is one of the conditions from the table below. 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 PI Ping will write SCAN OFF to an interface point. If a point that is currently loaded by the Interface is edited so that the point is no longer valid for the Interface, PI Ping removes the point from service, and writes SCAN OFF to the point. For example, if a user changes the PointSource of a point that is currently loaded by PI Ping, the Interface will no longer service the point and write SCAN OFF to it.

Shutdown

The 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 starts. 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 in the event of a power failure. For additional information on shutdown events, refer to the PI Server manuals.

Note: The SHUTDOWN events that the PI Shutdown subsystem writes are independent of the SHUTDOWN events that the Interface writes when the user specfies the  stopstat=Shutdown command-line parameter.

SHUTDOWN events can be disabled from being written to PI when PI restarts 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 shuts down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.