PI_WInTouch_1.4.74.0
PI_WInTouch_1.4.74.0
to the PI System
Interface to the PI System
Version 1.4.74.0
Rev E
How to Contact Us
Phone (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax (510) 357-8136
E-mail [email protected]
World Wide http://www.osisoft.com
Web
Mail OSIsoft OSI Software, Ltd
P.O. Box 727 P. O. Box 8256
San Leandro, CA 94577-0427 Level One, 6-8 Nugent Street
USA 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_W892288988.doc
Introduction.................................................................................................................... 1
Reference Manuals......................................................................................................1
Supported Features......................................................................................................1
Diagram of Hardware Connection................................................................................4
Principles of Operation.................................................................................................5
Installation Checklist.....................................................................................................7
Interface Installation......................................................................................................9
Naming Conventions and Requirements......................................................................9
Interface Directories...................................................................................................10
The PIHOME Directory Tree...................................................................................10
Interface Installation Directory................................................................................10
Interface Installation Procedure..................................................................................10
Installing the Interface as an NT Service....................................................................10
Installing the Interface Service with PI-Interface Configuration Utility....................10
Installing the Interface Service Manually................................................................13
PointSource.................................................................................................................. 15
PI Point Configuration.................................................................................................17
Point Attributes........................................................................................................... 17
Tag......................................................................................................................... 17
PointSource............................................................................................................ 17
PointType............................................................................................................... 17
Location1................................................................................................................ 17
Location2................................................................................................................ 17
Location3................................................................................................................ 18
Location4................................................................................................................ 18
Location5................................................................................................................ 18
InstrumentTag........................................................................................................18
ExDesc................................................................................................................... 18
Security......................................................................................................................... 41
Buffering....................................................................................................................... 45
Configuring Buffering with PI-ICU (NT-Intel)...............................................................45
Configuring Buffering Manually..................................................................................48
Sample piclient.ini File................................................................................................49
Revision History............................................................................................................. 53
Reference Manuals
OSIsoft
UniInt End User Document
PI Data Archive Manual
PI-API Installation Instructions
Vendor
The Extensibility Toolkit for InTouch User’s Guide
Supported Features
Feature Support
Part Number PI-IN-WW-INTCH-NT
Platforms NTI (4.0 / 2000 / XP)
APS Connector No
Point Builder Utility No
ICU Control Yes
Automatically Incorporates PI Point Yes
Attribute Changes
Exception Reporting Yes
Outputs from PI Yes
Inputs to PI: Scan-based / Unsolicited / Scan-based / Event Tags
Event Tags
Maximum Point Count Unlimited
Uses PI-SDK No
PINet to PI 3 String Support N/A
Source of Timestamps
When the value of a tag is read from InTouch, the PI server time is used as the event’s
timestamp. This timestamp may be adjusted using the /to=n argument. This
argument specifies the number of seconds (as a positive or negative number) to adjust
the timestamp by. This offset, when specified, applies to all tags and all scans.
There is also a mechanism for adjusting the timestamp of individual tags. This is
typically used when there is a significant delay between the value of a tag actually
being scanned in the field and the value being received by InTouch. For example, a
tag may be scanned in the field every 15 minutes but takes several minutes to reach
InTouch. In this case you would typically want the timestamp in PI to represent the
time the tag was scanned in the field rather than when it was written to InTouch. This
can be achieved by using a combination of scan class and Location2 settings. See the
section on Location2 on page 17 for more information.
The /tm argument tells the interface to output timestamp messages to the error log
file. This is useful for debugging any timestamp manipulation that is configured.
Failover
In a typical Wonderware InTouch - PI-InTouch application, there are three
components that can fail:
1. I/O Server (The means by which real-world data is brought into InTouch).
2. InTouch (The actual MMI product).
3. PI-InTouch (The interface used to exchange data between InTouch and PI).
The Failover mechanism built into the PI-InTouch Interface only applies to failure of
the I/O Server.
The failover mechanism in this interface is very simple and works with any number
of InTouch hosts. The interface simply examines a specified InTouch point, which
holds the name of the active/online I/O Server, and if it is not the current host (also
specified), then it does not scan that InTouch node for updated point values.
To operate using failover simply install and run the interface on the two or more
InTouch hosts, making sure to specify the /fp and /fs arguments in the startup
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an
OSIsoft-developed template used by our developers, and is integrated into many
interfaces, such as the PI-Wonderware InTouch interface. The purpose of UniInt is to
keep a consistent feature set and behavior across as many of our 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 End User Document is a supplement to this manual.
4
Principles of Operation
The PI-Wonderware InTouch interface is a console-based, UniInt-based, interface.
The interface starts by first searching the PI tag database for all tags whose PointSource
matches the interface’s PointSource as designated at startup. The interface then attempts
to make a connection to each of the associated tags within InTouch.
When the interface process has completed these initial tasks, it enters a permanent loop
in which it checks for the expiration of the update period for each scan class, and the
expiration of the tag attributes update period. This loop is repeated until the interface is
stopped.
The PI-Wonderware InTouch interface supports scan-based input tags, event-based input
tags, and output tags. The interface groups all the event-based tags having a common
event tag into a dynamic list for servicing together, so that all event-based tags in the list
are updated when their event tag has an exception.
The manner in which the interface manages the connection to InTouch is determined by
the /ws and the /ht flags that are specified in the startup command file. If the /ws flag
is not specified, the interface will exit when a connection attempt fails – this includes the
initial connection at startup. Otherwise, the value of the /ws argument is the number of
seconds to delay between reconnection attempts. This allows the interface to start before
InTouch does, in which case a connection will be attempted periodically until successful.
Also, if InTouch exits, the interface will continue to operate, attempting a connection
periodically until successful.
The /ht argument tells the interface to hold a tag connection open between scans. If this
is not specified, a tag connection is made, the tag is read, and then the tag is
disconnected, for each scan. This is obviously an inefficient way to process tags. For the
sake of efficiency this argument should be specified except when the system resources
are low and the interface becomes unstable.
The above lines define the \pipc directory as the root of the PIHOME directory tree on
the C: drive. OSIsoft recommends using \pipc as the root directory name. The
PIHOME directory does not need to be on the C: drive.
Service Name
The Service to Add box shows the name of the current interface service. This service
name is obtained from the interface executable.
Display Name
The 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 OSI suite of products.
Log on as
This text box is available only when the service does not yet exist. It allows users to set
what user account the interface service will use when they first create the interface
service. If this text box is left blank when the service is created, then LocalSystem is
used.
To edit the username after the service has been created, users need to use the Services
Applet.
Password
This text box is available only when the service does not yet exist. If the username
specified in the Log on as text box requires a password, this field is where the password
should be typed. If no password is required, this field can remain blank.
To edit the password after the service has been created, users need to use the Services
Applet.
Interface Dependencies
The Installed Services list is a list of the services currently installed on this machine.
Services upon which this Interface is dependant should be moved into the Interface
Dependencies list using the “Add>>” button. For example, if API Buffering is running,
then “bufserv” should be selected from the list at the right and added to the list on the
left. Often interface services also depend on a vendor program.
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 Operating System Event Logger for messages that
may indicate the cause for any server not running as expected.
Add
To add a dependency from the list of Installed Services, select the dependency name, and
click the Add button.
Remove
To remove a selected dependency, highlight the service name in the Installed
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.
12
Create or Remove Interface Service
Create
The 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.
Status of the
Interface
Service
When the interface is installed as a service on the PI Server node and when Bufserv is
not implemented, a dependency on the PI network manager is not necessary because the
interface will repeatedly attempt to connect to the PI Server until it is successful .
Note: Interfaces are typically not installed as automatic services when the interface is
installed on the PI Server node.
Check the Microsoft Windows NT services control panel to verify that the service was
added successfully. One can use the services control panel at any time to change the
interface from an automatic service to a manual service or vice versa .
14
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 example, one may choose the letter I to
identify points that belong to the PI-Wonderware InTouch interface. To implement this,
one would set the PointSource attribute to I for every PI Point that is configured for the
PI-Wonderware InTouch interface. Then, if one uses /ps=I on the startup-command line
of the PI-Wonderware InTouch interface, the PI-Wonderware InTouch interface will
search the PI Point Database upon startup for every PI point that is configured with a
PointSource of I. 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
argument.
PI 2 Server Nodes
The following point source characters are reserved on PI 2 systems and cannot be used as
the point source character for an interface: C, ?, @, Q, T. Also, if one does not specify a
point source character when creating a PI point, the point is assigned a default point
source character of L. Therefore, it would be confusing to use L as the point source
character for an interface.
Before a PI point with a given point source can be created, the point source character
must be added to the PI 2 point source table. For example, if point source I is not
defined in the PI 2 point source table, a point with a point source of I cannot be created.
This prevents the user from accidentally creating a point with an incorrect point source
character.
Point Attributes
Tag
A tag is a label or name for a point. Any tag name can be used in accordance to the
normal PI point naming conventions.
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 argument on page 30 and the “PointSource” section on page 15.
PointType
Typically, device point types do not need to correspond to PI point types. For example,
integer values from a device can be sent to floating point or digital PI tags. Similarly, a
floating-point value from the device can be sent to integer or digital PI tags, although the
values will be truncated.
PI 2 Server Nodes
Scaled real, full-precision real, integer, and digital point types are supported on
PI 2 Servers. For more information on the individual point types, refer to the
Data Archive (DA) section of PI System Manual I.
PI 3 Server Nodes
Float16, float32, float64, int16, int32, digital, and string point types are supported on
PI 3 Servers. For more information on the individual point types, see
PI Data Archive for NT and UNIX.
Location1
Location1 specifies the interface number. It identifies which points belong to a particular
interface when multiple copies of the interface program are running. This value must
match the /id=n number for the appropriate interface. With no /id= argument, this
field should be zero.
Location2
Location2 specifies the time offset in seconds. It adjusts the timestamp of a value to be
the previous offset. It is used in cases where InTouch may not receive a value until
sometime after it was actually recorded.
Location3
This value indicates whether a point is an input or an output point:
0 = input
1 = output.
Location4
Scan-based Inputs
For interfaces that support scan-based collection of data, Location4 defines the scan class
for the PI point. The scan class determines the frequency at which input points are
scanned for new values. For more information, see the description of the /f flag in the
section called “Command-Line Parameters” on page 30.
Location5
The Location5 attribute is not used by the PI-InTouch interface.
InstrumentTag
The instrument tag attribute is limited to 32 characters.
The instrument tag name specifies the InTouch point name associated with the PI tag.
ExDesc
This is the extended descriptor attribute. It is limited to 80 characters.
Performance Points
The extended descriptor is also checked for the string “PERFORMANCE_POINT”. If
this character string is found, this point is treated as a performance point. See the section
“Performance Point Configuration” on page 23 for more information.
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on
for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0
when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute
is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to
the PI point after the point edit is detected by the interface.
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.
Shutdown
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. For information
on configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of
PI System Manual I.
PI 3 Server Nodes
The shutdown attribute is used only if the server node is a PI 3 system.
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 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
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.
One can disable SHUTDOWN events from being written to PI when PI is restarted by
setting the Shutdown attribute to 0 for each point. Alternatively, one can change the
default behavior of the PI Shutdown Subsystem 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 Data Archive for NT and UNIX.
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.
SourceTag
Output points control the flow of data from the PI Data Archive to any destination that is
external to the PI Data Archive, such as a PLC or a third-party database. For example, to
write a value to a register in a PLC, one would use an output point. Each interface has its
own rules for determining whether a given point is an input point or an output point.
There is no de facto PI point attribute that distinguishes a point as an input point or an
output point.
Outputs are triggered for UniInt-based interfaces. That is, outputs are typically not
scheduled to occur on a periodic basis. There are two mechanisms for triggering an
output.
Trigger Method 2
For trigger method 2, a separate trigger point is not configured. To trigger an output,
write a new value to the Snapshot of the output point itself. The new value does not need
20
to be different than the previous value to trigger an output, but the timestamp of the new
value must be more recent than the previous value.
Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2
has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a
digital state that is indicative of the failure, which is very important for troubleshooting.
Convers
This attribute specifies the conversion factor that is used for scaling purposes. Scaling
can be configured in three ways:
Convers = 0. No scaling will take place.
Convers <> 0 for Input Tags. The value in Convers is interpreted as a straight
multiplier. This causes the input value from the WW InTouch server to be multiplied
by the value in Convers before being sent to PI.
Convers <> 0 for Output Tags. The value being sent from PI to the WW InTouch
server is divided by the value in Convers.
The default value of Convers in PI 3 and PI 2 is 1.
The right mouse menu provides options for creating and deleting Performance Points.
Create
To create a Performance Point, right mouse click the line belonging to the tag to be
created, and select Create.
Delete
To delete a Performance Point, right mouse click the line belonging to the tag to be
deleted, and select Delete.
Correct
If the “Status” of a point is marked “Incorrect”, the point configuration can be
automatically corrected by ICU by right mouse 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
Point Source Point Source for tags for this interface, as specified on the first tab
Compressing Off
Excmax 0
Descriptor Interface name + “ Scan Class # Performance Point”
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 Rates tags.
Tag Status
The Tag Status column indicates whether the IORates tag exists in PI. The possible
states are:
Created – This status indicates that the tag exist in PI
Not Created – This status indicates that the tag does not yet exist in PI
Deleted – This status indicates that the tag has just been deleted
Unknown – This status indicates that the ICU is not able to access the PI Server
In File
The In File column indicates whether the IORates tag listed in the tag name and the
event counter is in the IORates.dat file. The possible states are:
Yes – This status indicates that the tag name and event counter are in the
IORates.dat file
No – This status indicates that the tag name and event counter are not in the
IORates.dat file
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of the
interface. The command line equivalent is /ec=x, where x is the same number that is
assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the IORates tag.
Snapshot
The Snapshot column holds the snapshot value of the IORates tag, if the IORates tag
exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is
clicked, and when the interface is first loaded.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter
Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.
26
PI 3 Server Nodes
Create an I/O Rate Tag with the following point attribute values.
Attribute Value
PointSource L
PointType float32
Compressing 0
ExcDev 0
General Options
Failover
Enable Failover
If you are using failover nodes, checking this box will allow you to pass the required
parameters to the interface. Un-checking this box will remove all command-line
parameters relating to failover.
InTouch host
This specifies the name of the InTouch host that the interface is running on. This flag
should be specified if configuring failover. The command line equivalent is /fs.
Wonderware InTouch Interface to the PI System 29
Startup Command File
Timestamps
InTouch-specific Debugging
Additional Arguments
The Additional Arguments section is provided for any flags that may be required in the
future.
Command-line arguments can begin with a / or with a -. For example, the /ps=I and
-ps=I command-line arguments are equivalent.
Note: The UniInt End User Document includes details about other command line
parameters which may be useful.
30
Command-line Parameters
Parameter Description
/fp=pointname The /fp flag specifies the name of the point on InTouch, which
holds the name of the currently active server. The flag should be
Optional
specified if configuring failover. Refer to the InTouch User Guide,
Monitoring the status of an I/O conversation chapter, for details on
configuring this flag.
/fs=servername The /fs flag specifies the name of the InTouch host that the
interface is running on. The flag should be specified if configuring
Optional
failover.
When the value of pointname matches servername, then data
will be collected on this node. Refer to the InTouch Reference
Guide for information regarding the GetNodeName( ) system
function. This function returns the NetDDE node name to a string
variable.
/ws=n The /ws flag specifies the number of seconds to wait between
reconnection attempts. It allows the interface to start before InTouch
Optional
does, in which case a connection will be attempted periodically until
successful. Also, if InTouch exits, the interface will continue to
operate, attempting a connection periodically until successful.
The minimum period is 10 seconds and the maximum period is 600
seconds (10 minutes). If this argument is not specified then any
failure to make a connection or loss of an existing connection will
cause the interface to exit– this includes the initial connection at
startup.
/ht The /ht flag allows the interface to hold a tag connection open
Optional between scans. If this is not specified then a tag connection is made,
the tag is read, and the tag is disconnected, for each scan. This is
obviously an inefficient way to process tags. For the sake of
efficiency this argument should be specified except when the system
resources are low and the interface becomes unstable.
/to=n The /to flag causes the interface to adjust the timestamp associated
with scanned values by n seconds. This value can be a positive or
Optional
negative number of seconds. The PI server time is used as the base
of the event’s timestamp. See the section “Source of Timestamps”
on page 2 or the section on Location2 on page 17 for more
information.
/tm The /tm flag causes the interface to output additional debug
messages that are specifically associated with timestamps of scanned
Optional
values. This can be useful in situations where time issues may arise,
or when debugging any timestamp manipulation that is configured. .
/mt=n The /mt flag allows a limit to be placed on the number of tags that
the interface will process. /mt=10 forces the interface to only
Optional
process the first 10 tags found–all other tags are ignored. This is
useful for debugging.
/dd=n The /dd flag causes InTouch specific debugging messages to be
sent to the PI log file. N can be 0, 1 or 2, with 2 giving the most
Optional
verbose output, 0 being the same as if “/dd=n” was absent.
Parameter Description
/db The /db flag causes informative messages to be sent from the
Universal Interface core to the PI log file for debugging or
Optional
diagnostic purposes.
/ps=x The /ps flag specifies the point source for the interface. x is not
case sensitive and can be any single character. For example, /ps=I
Required
and /ps=i are equivalent.
The point source that is assigned with the /ps flag corresponds to
the PointSource attribute of individual PI Points. The interface will
attempt to load only those PI points with the appropriate point
source.
/id=x The /id flag is used to specify the interface identifier.
Optional The interface identifier is a string that is no longer than 9 characters
in length. UniInt concatenates this string to the header that is used to
identify error messages as belonging to a particular interface. See
the section called “Error and Informational Messages” for more
information on page 51.
UniInt always uses the /id flag in the fashion described above. This
interface also uses the /id flag to identify a particular interface
copy number that corresponds to an integer value that is assigned to
Location1. This allows multiple copies of the interface to run on the
same node and handle different sets of tags. X must be the same as
the Location1 field of each of the PI tags associated with this
interface copy.
The /id flag can also be useful in failover situations where
different tags may require different failover nodes.
For this interface, one should use only numeric characters in the
identifier. For example,
/id=1
32
Parameter Description
/f=SS The /f flag defines the time period between scans in terms of hours
or (HH), minutes (MM), and seconds (SS). The scans can be scheduled
/f=SS,SS to occur at discrete moments in time with an optional time offset
or specified in terms of hours (hh), minutes (mm), and seconds (ss). If
/f=HH:MM:SS HH and MM are omitted, then the time period that is specified is
or assumed to be in seconds.
/f=HH:MM:SS,hh:
mm:ss Each instance of the /f flag 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 flag on
Required 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:07
or, equivalently:
/f=60,5 /f=7
The 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 a large load, then some scans may occur late or be skipped
entirely. See the section called “Performance Point Configuration”
on page 23 for more information on skipped or missed scans.
Sub-second Scan Classes:
One can also specify sub-second scan classes on the command line
such as
/f=0.5 /f=0.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 seconds.
Similarly, sub-second scan classes with sub-second offsets can be
defined, such as
/f=0.5,0.2 /f=1,0
Parameter Description
/host=host:port The /host flag is used to specify the PI Home node. host is the
IP address of the PI Sever node or the domain name of the PI Server
Optional
node. port is the port number for TCP/IP communication. The
port is always 5450 for a PI 3 Server and 545 for a PI 2 Server. It is
recommended to explicitly define the host and port on the command
line with the /host flag. Nevertheless, if either the host or port is
not specified, the interface will attempt to use defaults.
Defaults:
The default port name and server name is specified in the
pilogin.ini or piclient.ini file. The piclient.ini file is ignored if
a pilogin.ini file is found. Refer to the PI-API Installation
Instructions manual for more information on the piclient.ini and
pilogin.ini files.
Examples:
The interface is running on an API node, the domain name of the PI
3 home node is Marvin, and the IP address of Marvin is
206.79.198.30. Valid /host flags would be:
/host=marvin
/host=marvin:5450
/host=206.79.198.30
/host=206.79.198.30:5450
/stopstat If the /stopstat flag is present on the startup command line, then
or the digital state I/O Timeout will be written to each PI Point when
/stopatat= the interface is stopped.
digstate
If /stopstat=digstate is present on the command line, then
Default: the digital state, digstate, will be written to each PI Point when
/stopstat= the interface is stopped. For a PI 3 Server, digstate must be in
”Intf shut” the system digital state table. For a PI 2 Server, where there is only
Optional one digital state table available, digstate must simply be
somewhere in the table. UniInt uses the first occurrence in the table.
If neither /stopstat nor /stopstat=digstate is specified
on the command line, then no digital states will be written when the
interface is shut down.
Examples:
/stopstat=”Intf shut”
The entire parameter is enclosed within double quotes when there is
a space in digstate.
/ec=x The first instance of the /ec flag on the command line is used to
specify a counter number, x, for an I/O Rate point. If x is not
Optional
specified, then the default event counter is 1. Also, if the /ec flag
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=x explicitly defined will write to the same
I/O Rate point. This means that one should either explicitly define
an event counter other than 1 for each copy of the interface or one
should not associate 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,” p. 25.
34
Parameter Description
/sio The /sio flag stands for “suppress initial outputs.” The flag applies
only for interfaces that support outputs. If the /sio flag is not
Optional
specified, the interface will behave in the following manner.
When the interface is started, the interface determines the current
Snapshot value of each output tag. Next, the interface writes this
value to each output tag. In addition, whenever an individual output
tag is edited while the interface is running, the interface will write
the current Snapshot value to the edited output tag.
This behavior is suppressed if the /sio flag is specified on the
command line. That is, outputs will not be written when the
interface starts or when an output tag is edited. In other words, when
the /sio flag is specified, outputs will only be written when they
are explicitly triggered.
/q When the /q flag is present, Snapshots and exceptions are queued
before they are sent to the PI Server node.
Optional
The maximum queue size is close to 4000 bytes. The queue is
flushed between scans if it is not filled.
36
System Variable Path
The InTouch directory must be added to the System Variable Path. To do this click on:
Start Settings Control Panel System Environment
Then highlight Path under System Variables and add the directory.
For Wonderware InTouch version 6.0b the directory to add to the path is usually:
C:\InTouch.32
For version 7.0 the directory is usually:
C:\Program Files\FactorySuite\InTouch.
For example, if the local version of InTouch is 6.0b, the path might be:
%SystemRoot%\system32;%SystemRoot%;c:\intouch.32
To Start or Stop the interface service, use the Start button and the Stop button on
the toolbar at the top of the PI-ICU. 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.
Status of the
Interface
Service
Service Tab
The Service tab allows for some API Buffering service configuration. For further
configuration changes, use the Services applet.
Service name
The Service name displays the name of the API Buffering Service.
Display name
The Display name displays the full name associated with the API Buffering service.
Password
If the username specified in the Log on as text box requires a password, this field is
where the password should be typed. If no password is required, this field can remain
blank.
Confirm password
The Confirm password text box is used to confirm the password typed into the Password
text box.
Dependencies
The Dependencies lists the Windows services on which the API Buffering service is
dependent.
Start / Stop
The Start / Stop buttons allow for the API Buffering service to be started and stopped.
After a change is made to any of the settings on the Settings tab, the Save button must be
clicked, and then the service must be stopped and restarted for the changes to be picked
up by bufserv.
Startup Type
The Startup Type indicates whether the 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 API Buffering service is set to start automatically.
Create / Remove
The Create button creates the API Buffering service with the specified Dependencies and
with the specified Startup Type.
The Remove button removes the API Buffering service. If the service is not currently
installed, or if the service is currently running, this button will be grayed out.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by API
Buffering. Default values are used if no other value is provided. The default value for
each parameter, as well as the range, is specified next to each parameter.
Send Rate
Send 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.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Pause Rate
When 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.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Retry Rate
When 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.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
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.
48
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)
MAXTRANSFEROBJ 1 - 2,000,000 500 Maximum number of events to send between
S 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
the default PI server and an optional time offset change that may occur between the client
and server.
Keywords Values Default Description
PIHOMENODE string None Only used on Unix. On Windows, default
server is in pilogin.ini
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)
50
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name is a
non-configurable identifier that is no longer than 9 characters . ID is a configurable
identifier that is no longer than 9 characters and is specified using the /id flag on the
startup command line.
Message Logs
The location of the message log depends upon the platform on which the interface is
running. See the UniInt End User Document for more information.
Messages are written to PIHOME\dat\pipc.log at the following times.
When the interface starts many informational messages are written to the log.
These include the version of the interface, the version of UniInt, the command-line
parameters used, and the number of points.
As the interface retrieves points, messages are sent to the log if there are any
problems with the configuration of the points.
If the /db is used on the command line, then various informational messages are
written to the log file.
Messages
InTouch is not running
Verify InTouch is running.