cimplicity hmi - osisoftcdn.osisoft.com/interfaces/1015/pi_geci… · web view · 2012-05-11ge...

GE FANUC CIMPLICITY HMI Interface Documentation

Version 3.1.0Revision A

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 Web http://www.osisoft.com

Mail OSIsoftP.O. Box 727San Leandro, CA 94577-0427USA

OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1Deutschland

OSI Software, LtdP O Box 8256Symonds StreetAuckland 1035 New Zealand

OSI Software, Asia Pte Ltd152 Beach Road#09-06 Gateway EastSingapore, 189721

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.document.doc

2000-2002 OSI Software, Inc. All rights reserved777 Davis Street, Suite 250, San Leandro, CA 94577

http://www.osisoft.com/

mailto:[email protected]

Table of Contents

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

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

Diagram of Hardware Connection................................................................................5

Principles of Operation.................................................................................................7

Installation Checklist...................................................................................................11

Interface Installation....................................................................................................13Naming Conventions and Requirements....................................................................13

Microsoft DLLs............................................................................................................14

Interface Directories...................................................................................................14

Interface Installation Procedure..................................................................................15

Installing the Interface as an NT Service....................................................................15

Connection Tool...........................................................................................................19

Digital States................................................................................................................21

PointSource..................................................................................................................23

PI Point Configuration.................................................................................................25Point Attributes...........................................................................................................25

Output Points..............................................................................................................27

Performance Point Configuration...............................................................................29

I/O Rate Tag Configuration..........................................................................................31Monitoring I/O Rates on the Interface Node...............................................................31

Configuring I/O Rate Tags with PI-ICU (NT-Intel).......................................................31

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

Startup Command File.................................................................................................35Command-line Parameters.........................................................................................35

Sample PICimpi.bat File.............................................................................................37

Interface Node Clock...................................................................................................39

GE FANUC CIMPLICITY HMI Interface Documentation iii

Security.........................................................................................................................41

Starting / Stopping the Interface.................................................................................43Starting Interface as a Service...................................................................................43

Stopping Interface Running as a Service...................................................................43

Buffering.......................................................................................................................45Configuring Buffering with PI-ICU (NT-Intel)...............................................................45

Configuring Buffering Manually..................................................................................48

Sample PIClient.ini File..............................................................................................49

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

Messages...................................................................................................................51

System Errors and PI Errors.......................................................................................51

Revision History.............................................................................................................53

GE FANUC CIMPLICITY HMI Interface Documentation iv

IntroductionThe PI-GE FANUC CIMPLICITY HMI Interface (PI-CIMPI) provides the transfer of data between the GE FANUC CIMPLICITY system, version 4.01 and higher, and the Plant Information (PI) System. Two versions of the interface are shipped with the interface distribution, one for CIMPLICITY versions less than 5.5 and one for versions that are 5.5 or greater. The interface runs on a Windows NT or Windows 2000 Workstation or Server.

The interface is bi-directional. The interface reads data from a single project on one CIMPLICITY server and sends them to the PI server. Conversely the interface will output data to the single specified project as well. The interface may run on a CIMPLICITY View node or a CIMPLICITY server. The CIMPLICITY system supports a fail-over mechanism where a View Node can be configured to collect data from the active project on one of two CIMPLICITY servers configured for fail-over.

The interface obtains data from the CIMPLICITY server on an exception basis. The interface checks for new data at a configurable scan rate (default is 250ms). The user can choose to have the data time stamped in one of 3 ways: 1, the raw unadjusted time from the Cimplicity server; 2, the PI server time at which the event was received, or 3, the adjusted time from the Cimplicity server. If option 3 is used (the default), the PI-CIMPI interface queries the Cimplicity server for the current time and compares that with the current time from the PI server. It uses the difference between the two times to determine an offset. This offset is then used to adjust the time of the Cimplicity event to the PI time.

The interface will exit under certain situations that do not allow recovery by standard programmatic means. Because of this possibility, the PI-CIMPI interface is shipped with a separate program named WatchDog that will monitor the interface and restart the interface if it is not running. This scenario is discussed in The Principles of Operation section and the start-up command parameter /wd.

Version 3.x of the PI-CIMPI interface has been rewritten to be much more robust. Although the majority of the original functionality has been maintained with the older versions, versions 1.x and versions 2.x, there are some differences. These differences are:

Version 3.x of the interface only supports communication to a single project. Users of version 1.x and 2.x of the interface will now need to run multiple copies of the interface to communicate to multiple projects.

Version 3.x of the interface now collects data from CIMPLICITY only by exception; i.e. CIMPLICITY will only send changed data to the interface. Versions 1.x and 2.x allowed for data collection by polling and event triggers. The user does not need to make any modifications to the point attributes because of this change.

Version 3.x of the interface has not implemented scaling which is when values of EU-converted points in CIMPLICITY are sent to PI as converted values. Please contact OSIsoft to discuss if you need this functionality added.

GE FANUC CIMPLICITY HMI Interface Documentation 1

Version 3.x of the interface has not implemented support for complex CIMPLITY inputs or outputs. Please contact OSIsoft to discuss if you need this functionality added.

Reference Manuals

OSIsoft UniInt End User Document

PI Data Archive Manual

PI-API Installation Instructions

Vendor GE Fanuc Automation, CIMPLICITY HMI for Windows NT and Windows 95, Base System, Users’s Manual, GFK-1108F, October 97

GE Fanuc Automation, CIMPLICITY HMI for Windows NT and Windows 95, Point Management API, Apllication Developer Guide, GFK-1201C, April 1997

Supported FeaturesFeature Support

Part Number PI-IN-GE-CIM-NT

Platforms Windows NTI and Windows 2000

PI Point Types PI3 Servers: Float16 / Float32 / Float64 / Int16 / Int32 / Digital / String

PI2 Servers: Real, Int16, Digital

Sub-Second Timestamps Yes

Sub-Second Scan Classes No

* Automatically Incorporates PI Point Attribute Changes

Yes

Exception Reporting Yes

Outputs from PI Yes

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

Unsolicited

Maximum Point Count Unlimited

Uses PI-SDK No

PINet to PI 3 String Support N/A

* Source of Timestamps CIMPLICITY server, PI Time, or adjusted

History Recovery No

Failover No


Feature Support

*UniInt-Based Yes

* Vendor Software Required on PI-API / PINet Node

Yes

Vendor Software Required on Foreign Device

No

Vendor Hardware Required No

* Additional PI Software Included with Interface

Yes

* Device Point Types Analog, Boolean, Text

* See paragraphs below for further explanation.

Automatically Incorporates PI Point Attribute ChangesFor a Cimplicity value that doesn’t change often, if the tag is removed from the interface, SCAN OFF will be written to the tag. If the tag is added back to the interface or if another PI tag is added with the same Cimplicity tag name, the value of the PI tag will NOT be updated until the value of the Cimplicity tag changes or the interface is restarted. This includes those Cimplicity tags with a “Bad Input” value. The reason for this is that the interface uses Cimplicity’s on-change API call to retrieve data and this call will send a static value the first time it is called for a point (at start-up), but it will not send another value until the value changes.

Source of TimestampsCIMPLICITY events come with time stamps from CIMPLICITY. The resolution of a time stamp from CIMPLICITY is to the millisecond. The user can choose to time stamp the data with the resolution to 1 second or with sub-second time stamps. The Cimplicity events can be time-stamped in one of 3 ways: 1, the raw unadjusted time from the Cimplicity server; 2, the PI server time at which the event was received, or 3, the adjusted time from the Cimplicity server. If option 3 is used (this is the default), the PI-CIMPI interface queries the Cimplicity server at start-up and then once every minute for the current time and compares the Cimplicity time with the current time from the PI server. It uses the difference between the two times to determine an offset. This offset is then used to adjust the time of the Cimplicity event to the PI time. A new offset will only be applied if it differs by more than 5 seconds from the last offset and a message will be printed when a new time offset will be used.

History RecoveryThe interface does not support history recovery.

Fail-overThe CIMPLICITY system supports a fail-over mechanism where a View Node can be configured to collect data from the active project on one of two CIMPLICITY servers configured for fail-over. The interface however, does not have a separate fail-over mechanism.


Introduction

UniInt-BasedUniInt 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-IN-GE-CIM-NT 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.

Vendor Software RequiredThe interface requires that the CIMPLICITY Point Management API be installed on the computer where the interface will run. This provides the functions required by the interface to access the CIMPLICITY database. To install the CIMPLICITY Point Management API, CIMPLICITY must be installed as a Viewer or as a Server on the interface node. When installing as a Viewer, the Point Management option must be checked.

Additional PI SoftwareBecause there are situations (viewer down on viewer node or project stopped on a project node) where the PI-CIMPI interface must shut down completely to recover and start collecting data from the Cimplicity API, the interface is shipped with a watchdog application to restart the interface if it is stopped. Please see the start-up parameter /wd for instructions on configuring the watchdog application.

Device Point TypesThe interface supports collecting data from Cimplicity analog, boolean, and string type tags.

4

Diagram of Hardware Connection


Principles of Operation

StartupUpon startup, the interface examines the command parameters passed to it. The interface will only communicate to a single project and will ignore multiple projects that are passed to it. The interface will exit if no project name has been passed to it and a message will be printed to the log file indicating that the interface has exited.

The interface then retrieves all of the points that match the Interface ID number and the Point Source from PI. Once all the points have initially been obtained the interface will set up a single CIMPLICITY shopping list for all points. A single PI tag can only point to a single CIMPLICITY tag. If a PI tag is remove from the interface, the interface does not remove the CIMPLICITY point from the shopping list and ignores any subsequent event data that is sent if it is an input or will not execute anymore outputs if it is an output tag. For this reason OSI recommends stopping and restarting the interface if a lot of tags are removed. The interface will continue to operate normally without being restarted, but those extra CIMPLICITY points will be consuming machine resources, both memory and clock cycles. New PI tags will be added dynamically to the shopping list. Upon addition of a new input tag, the interface will receive an initial value with a time-stamp for the point. If the time-stamp of the event is prior to the latest value contained in PI (because the value is static and hasn’t changed since the PI tag’s value), the value will be written to PI with the current time-stamp. This is to handle situations when PI or the PI-CIMPI interface writes a value to the tag such as PT CREATED or SCAN OFF. If the PI Point is created at 10:02, the last time the value changed in the Cimplicity server was 10:00, and the interface is started at 10:10, then the initial event received from the Cimplicity server would be prior to the PT CREATED value that exists in PI. If this situation occurs, the interface will write the value to PI at 10:10. This will not reflect the time the value actually changed to the current value, but it will reflect the current value of the Cimplicity point.

Data InputAll data from CIMPLICITY is collected via exception and checks for new exceptions are made at a rate determined by the start-up parameter /sr=rate where rate is in milliseconds (default = 250ms). Data will be sent to the interface if it changes by any amount. CIMPLICITY exception reporting does not allow the user to specify a dead-band for a given point like you can do in PI. It is up to the user to decide if further exception reporting for a point will be done in PI and if so, what the exception specs should be set at.

Since data comes into the interface via exception, some points may not get new values for a very long time. Therefore the interface will send a value to PI if it has not received a new value from CIMPLICTY within excmax (PI point attribute ExcMax) seconds. The time stamp used will be the CIMPLICITY time or the adjusted PI time. The user may wish to turn the STEP attribute on for points whose values will not change frequently so that a change in value will not show a ramp on the trend.


The interface will write the following digital states to input points to alert the user to problems with the point or with communication.

Bad Input is written to an input tag if it reads bad in CIMPLICITY; i.e. when viewed from the CIMPLICITY Point Control Panel the value of the tag shows ***.

I/O Timeout is written to all input tags if the interface is unable to communicate to the CIMPLICTY Viewer or Project.

Configure will be written to an output or input tag if the CIMPLICITY tag name specified in the Instrumenttag is invalid or missing.

Bad Input is written to all input tags if the interface is unable to communicate to the CIMPLCITY Project either because of a network connection problem or the Project is not running.

Note: Typically I/O Timeout would be written but the indication from the CIMPLICITY API of a network problem or the Project down is the same as when a tag reads bad in CIMPLICITY.

Data Output All the output points have a set point request added to the shopping list. When a value is to be sent to the CIMPLICITY, the set point value will be modified and the shopping list will be sent.

CIMPLICITY Fail-overThe interface can run on a CIMPLICITY Viewer Node or a CIMPLICITY Server. The CIMPLICITY system supports a fail-over mechanism where a Viewer Node can be configured to collect data from the active project on one of two CIMPLICITY servers that are configured for fail-over. Because of this functionality it is highly recommended that the interface run on a VIEW Node to take advantage of the fail-over capability provided by CIMPLICITY.

In the event the primary Cimplicity server fails over to the secondary, the only lost of PI data will be the short time it takes for the secondary Cimplicity server to switch to the Primary and start collecting data.

Programmatic Stopping and Restarting of the InterfaceInterface Running on a View Node

The interface will be unable to recover if the CIMPLICITY VIEWER goes down. This is consistent with the behavior of the CIMPLICITY Point Control Panel where it shuts itself down when the VIEWER goes down.

Therefore the interface will shut itself down when the VIEWER goes down. There is an associated process called WatchDog that is shipped with the PI-CIMPI interface (please see the start-up parameter /wd for configuring the WatchDog). If the WatchDog is enabled, it will restart the interface if the interface shuts down due to a fatal CIMPLICITY error. The interface will then be in a position to resume communication with CIMPLICITY when the VIEWER comes back up.

Interface Running on the Project Node


The situation is very similar when running the PI-CIMPI interface on a CIMPLICITY project node. When the CIMPLICITY project is stopped, the CIMPLICITY API sends an error to the PI-CIMPI interface and then the PI-CIMPI interface is unable to recover. This is consistent with the behavior of the CIMPLICITY Point Control Panel where it shuts itself down when the Project is stopped. Therefore the interface will log the error and shut down. The WatchDog process will restart the interface and it will be ready to resume communication with the CIMPLICITY project when the project is restarted.


Installation ChecklistFor those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-CIMPI interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail.

1. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)

2. Verify that PI-API has been installed.

3. Install the PI-CIMPI interface.

Warning: Edit the Service Property log-on as to a valid CIMPLICITY user before running the service or it will hang in a CIMPLICITY API call.4. Install CIMPLICITY HMI, either Server or Viewer.

5. Start the CIMPLICITY Point Control Panel and verify it is able to collect data from the desired points.

6. Change the PI-CIMPI service log-on as property to a valid CIMPLICITY user.

7. Choose a point source. If PI 2 home node, create the point source.

8. Configure PI points. Location1 is the interface instance.Location2 is not used.Location3 is Input (0) or Output (1).Location4 is not used.Location5 is not used.exdesc is not used.instrumenttag is the name of the CIMPLICITY tag (not including project name).

9. Configure I/O Rate tag.

10. Edit startup command file./Project=Name defines the CIMPLICITY project to communicate with. The Project name will be pre-pended to the CIMPLICITY tag name to derive the Fully Qualified CIMPLICITY Tag Names.

11. Set interface and CIMPLICITY Server node clock. Setting the CIMPLICITY Server node and interface node clocks is very important if using the raw CIMPLICITY timestamps (/time=foreign). If the either time differs from the PI Server’s time, the timestamps will be off by one hour.

12. Set up security, both PI server security and CIMPLICITY security. When running as a service, it is very important to assign the log on as start-up parameter of service to a valid CIMPLICITY user. If the user starts under the normal system account or another account that does not have the proper CIMPLICITY privalegs, the PI-CIMPI interface can not determine this situation until the first CIMPLICITY add point call is made. Under these conditions, the CIMPLICITY add point call does not return and locks up the interface.

13. Start the interface without buffering.


14. Verify data.

15. Stop interface, start buffering, start interface.


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

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

In most cases, interfaces on PI-API nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt End User Document for special procedural information.

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that the name of the interface executable is picimpi.exe and that the startup command file is called pigecimpi.bat.

It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use pigecimpi1.exe and pigecimpi1.bat for interface number 1, pigecimpi2.exe and pigecimpi2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line arguments in a file that has the same root name.


Microsoft DLLsThe following Microsoft DLLs are distributed on the installation CD-ROM. Copy these files to the winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.

MSVCIRT.DLL

MSVCRT.DLL

MSVCRT40.DLL

MSVCP50.DLL

MSVCP60.DLL

The following additional Microsoft DLLs are also distributed on the CD-ROM. These DLLs are only used by a debug version of the interface. Copy these files to the Winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.

MSVCIRTD.DLL

MSVCRTD.DLL

MSVCP50D.DLL

MSVCP60D.DLL

Interface Directories

The PIHOME Directory TreeThe PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the WinNT directory. A typical pipc.ini file contains the following lines:[PIPC]PIHOME=c:\pipc

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.

Interface Installation DirectoryPlace all copies of the interface into a single directory. The suggested directory is:PIHOME\interfaces\Cimplicity\

Replace PIHOME with the corresponding entry in the pipc.ini file.

Interface Installation Procedure


In the installation procedure below, assume that interface number 1 is being installed and that all copies of the interface will be installed in the same directory.

1. Copy the interface files from the installation media to PIHOME\interfaces\Cimplicity\. Create the directory if necessary.

2. If necessary, rename the command file so that it has the same root name of the executable.

3. Alter the command-line arguments in the .bat file as discussed in this manual.

4. Try to start the interface interactively with the command:pigecimpi.bat

If the interface cannot be started interactively, it will not be able to run as a service. It is easier to debug interactively started processes because error messages are echoed directly to the screen. Once the interface is successfully running interactively, it can be run as a service by following the instructions below.

Installing the Interface as an NT ServiceThe PI-CIMPI interface service can be created with the PI-Interface Configuration & Management Utility, or it can be created manually.

Installing the Interface Service with PI-Interface Configuration UtilityWarning: Edit the Service Property log-on as to a valid CIMPLICITY user before running the service or it will hang in a CIMPLICITY API call.The PI-Interface Configuration & Management Utility provides a user interface for creating, editing, and deleting the interface service:

Service Configuration

Service NameThe Service to Add box shows the name of the current interface service. This service name is obtained from the interface executable.


Interface Installation

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

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

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

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

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

Generally, interface services are set to start automatically.

Interface DependenciesThe 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.

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.

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

Create or Remove Interface Service

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

16

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.

Start or Stop ServiceThe Start / Stop section contains a Start button and a Stop button . If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

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

Installing the Interface Service ManuallyWarning: Edit the Service Property log-on as to a valid CIMPLICITY user before running the service or it will hang in a CIMPLICITY API call.Help for installing the interface as a service can be retrieved at any time with the command:pigecimpi.exe –help

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

NT Service Installation Commands on a PI-API node or a PI Server node

with Bufserv implemented

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

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

NT Service Installation Commands on a PI-API node or a PI Server node

without Bufserv implemented

Manual service pigecimpi.exe –install –depend tcpip

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

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.


Status of the Interface Service

Interface Installation

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.

18

Connection Tool The interface does not have its own connection tool. However, the user should run the COMPLICITY Point Control Panel on the node where the interface is being run, which will allow the user to verify that it is able to collect data from the CIMPLICITY project.


Digital StatesFor more information regarding Digital States, refer to the Data Archive Manuals.

PI 2 Home NodeDigital states are defined by running the Digtl Stat display from the PI menu. The states must be contiguous for each status type and may be anywhere within the Digital State Table outside of the range 193 - 320, which is reserved for OSIsoft. The digital states need to be defined prior to point configuration. The digital state sets described in the PI 3 sections below should be entered into the PI 2 Digital State Table.

For more information, see the DA manual.

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

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

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


PointSourceThe 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 F to identify points that belong to the PI-CIMPI interface. To implement this, one would set the PointSource attribute to F for every PI Point that is configured for the PI-CIMPI interface. Then, if one uses /ps=F on the startup-command line of the PI-CIMPI interface, the Random interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of F. 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.

Case-sensitivity for PointSource AttributesIf the interface is running on a PINet node and the Server node is a PI 3 system, use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining points. For all other scenarios, one does not need to be careful with the case of the PointSource.

In all cases, the point source character that is supplied with the /ps command-line argument is not case sensitive. That is, /ps=F and /ps=f are equivalent. One only needs to be careful with the case of the PointSource during point definition, and only if the interface will be running on a PINet node communicating to a PI 3 Server.

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 F is not defined in the PI 2 point source table, a point with a point source of F cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character.

Defining a Point Source Character in the PI 2 Point Source Table

1. Enter PI by typing the following command from a VMS command prompt: @pisysexe:pi

2. Select the PointSrc option from the menu.

3. Select New from the menu.

4. Assign a point source next to the Code: field. Also, assign minimum and maximum values for the Location1 to Location5 attributes.

Location1 Location2 Location3 Location4 Location5

Minimum 1 -20000000 0 -20000000 -20000000

Maximum 99 20000000 1 20000000 20000000


5. Select “Save” from the menu.

PI 3 Server NodesNo point source table exists on a PI 3 Server, which means that points can be immediately created on PI 3 with any point source character. Several subsystems and applications that ship with PI 3 are associated with default point source characters. The Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use these point source characters or change the default point source characters for these applications. 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.


PI Point ConfigurationThe PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived. Use the point attributes below to define what data to transfer.

Point Attributes

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

PointSourceThe 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 and the “Point Source” section.

PointTypeTypically, 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 NodesFloat16, float32, int16, int32, digital, string, and blob point types are supported on PI 3 Servers. For more information on the individual point types, see PI Data Archive for NT and UNIX.

The interface does not support blobs.

Location1Location1 indicates to which copy of the interface the point belongs.

Location2The interface does not use this location.

Location30 = input

1 = output


Location4Since the interface only supports unsolicited inputs and outputs, the interface does not use this location.

Location5The interface does not use this location.

InstrumentTagThis field contains the exact CIMPLICITY point id.

Do not use fully qualified point ids (\\project\pointid for example) in this field. The interface generates fully qualified point IDs concatenating the “project” passed in the command-line parameter with the InstrumentTag.

Exception ParametersIn addition to the standard usage in PI, the excmax attribute is used for a special purpose in this interface. If a tag has not been updated for excmax time, the last value obtained from CIMPLICITY is sent to PI and time stamped with the current adjusted PI time or CIMPLICITY time depending upon which time basis the user has chosen to use.

An ExcMax value of 0 is used to indicate that only values obtained from CIMPLICITY are to be sent on to PI.

The other exception parameters are used normally by the interface as described in the PI Data Archive manual.

ExDescThe interface makes no special use of this field.

Performance PointsBecause the PI-CIMPI interface does not use scan classed, Performance Points are not supported.

Trigger-Based InputsThe PI-CIMPI interface does not support trigger-based inputs.

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 NodesThe 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 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Data Archive for NT and UNIX.

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.

Output PointsOutput 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 1 (Recommended)For trigger method 1, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any


PI Point Configuration

point source, including the point source of the interface. Also, the point type of the trigger point does not need to be the same as the point type of the output point.

The output point is associated with the trigger point by setting the SourceTag attribute of the output point equal to the tag name of the trigger point. An output is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous value that was sent to the Snapshot to trigger an output, but the timestamp of the new value must be more recent than the previous value. If no error is indicated, then the value that was sent to the trigger point is also written to the output point. If the output is unsuccessful, then an appropriate digital state that is indicative of the failure is usually written to the output point. If an error is not indicated, the output still may not have succeeded because the interface may not be able to tell with certainty that an output has failed.

Trigger Method 2For 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 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.

28

Performance Point ConfigurationBecause the PI-CIMPI interface does not use scan classes, performance points are not supported.


I/O Rate Tag ConfigurationAn I/O Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to PI by the interface. An exception is a value that has passed the exception specifications for a given PI point. Since 10-minute averages are taken, the first average is not written to PI until 10 minutes after the interface has started. One I/O Rate tag can be configured for each copy of the interface that is in use.

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

Configuring I/O Rate Tags with PI-ICU (NT-Intel)The PI-Interface Configuration & Management Utility (PI-ICU) provides a user interface for creating and managing IORates Tags.

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

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

Tag StatusThe 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 FileThe 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 CounterThe 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.

TagnameThe tag name listed under the Tagname column is the name of the IORates tag.

Right Mouse Button Menu OptionsCreateCreate the suggested IORates tag with the tag name indicated in the Tagname column.

DeleteDelete the IORates tag listed in the Tagname column.

RenameAllows the user to specify a new name for the IORates tag listed in the Tagname column.

Add to FileAdds the tag to the IORates.dat file with the event counter listed in the Event Counter Column.

SearchAllows the user to search the PI Server for a previously defined IORates tag.

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

Configuring the PI Point on the PI Server

PI 2 Server NodesA listing of the I/O Rate Tags that are currently being monitored can be obtained with the command:@PISysDat:IOMonitor.com

Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.


PI 3 Server NodesCreate an I/O Rate Tag with the following point attribute values.

Attribute Value

PointSource L

PointType float32

Compressing 0

ExcDev 0

Configuration on the Interface NodeFor the following examples, assume that the name of the PI tag is cimpi001, and that the name of the I/O Rate on the home node is cimpi001.

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

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

Add a line in the iorates.dat file of the form:cimpi001, x

where cimpi001 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x flag in the startup command file. x can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.

2. Set the /ec=x flag on the startup command file of the interface to match the event counter in the iorates.dat file.

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


Startup Command FileCommand-line arguments can begin with a / or with a -. For example, the /ps=M and -ps=M command-line arguments are equivalent.

For NT, command file names have a .bat extension. The NT continuation character (^) allows the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum length of each flag is 1024 characters.

If the Interface Configuration Utility is used to configure the PI-CIMPI interface, the interface specific start-up up parameters should be written in the additional parameters list of the Interface tab (shown below).

Command-line ParametersParameter Description

PI-CIMPI Specific parameters

/project=name

Required

The /project flag specifies the name of the CIMPLICITY project this instance of the interface will communicate with.

/sr=rate

Optional

Default = 250

The /sr flag specifies the rate at which the PI-CIMPI interface requests the exception based data from the CIMPLICITY server. Rate is in milliseconds and the minimum allowable value is 10 and the maximum is 1000.

/timeout=sec

Optional

Default = 0

The /timeout flag specifies the number of seconds the interface will wait before writing IOTIMEOUT to the PI tags. At start-up, the interface will try to communicate to the CIMPLICITY project and if it is unsuccessful, the interface will wait sec seconds before writing IOTIMEOUT. This is to allow the CIMPLICITY project to come up fully and start communicating to the interface. If the value is 0 or if the /timeout flag is not found in the start-up parameters, then IOTIMOUT will never be written to the PI tags.

/time=source

Optional

Default = Adjusted

The /time flag specifies the source of the timestamps used for the data. There are 3 valid values for source: Foreign, Server, and Adjusted. Foreign instructs the interface to use the raw time received from CIMPLICITY. Server instructs the interface to use the PI time the event was received. Adjusted instructs the interface to use the adjusted time from the CIMPLICITY. The PI-CIMPI interface queries the CIMPLICITY server at start-up and then once every minute for the current time


Parameter Description

and compares the CIMPLICITY time with the current time from the PI server. The interface uses the difference between the two times to determine an offset. This offset is then used to adjust the time of the CIMPLICITY event to the PI time. A new offset will only be applied if it differs by more than 5 seconds from the last offset and a message will be printed when a new time offset will be used.

/wd=”exe service [service]”

Optional

Default = None

The /wd flag specifies the complete path, including the executable name, and the name of the service(s) to monitor. The watchdog application provided with the PICIMPI interface will check once every minute to determine if the service(s) is running. If the service(s) is not running, the watchdog application will send a service control request to start the service.

The quotation marks surrounding the exe name and the names of the services to monitor are very important. If the quotation marks are left off, the standard parsing algorithm treats each service name as a separate parameter.

The name of the exe should be the entire path to the executable including the .exe. The watchdog app creates a log file with the same path and name as the executable with the .exe change to .log.

If multiple copies of the interface are being run, only on instance of the watchdog can be run. Just put the multiple service names in the /wd flag in one instance of the interface.

Example:

/wd=”C:\PIPC\Cimpi\WatchDog.exe PICIMPI1 PICIMPI2”

/subsec=yes

Optional

Default = no

The /subsec flag specifies the whether or not sub-second timestamps will be used. The two valid values for the /subsec flag are yes and no.

Common Interface parameters

/ps=x

Required

The /ps flag specifies the point source for the interface. x is not case sensitive and can be any single character. For example, /ps=P and /ps=p 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

Required

The /id flag is used to specify the interface identifier.

The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See the section called “Error and Informational Messages” for more information, 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


Parameter Description

is assigned to Location1. For this interface, use only numeric characters in the identifier. For example,

/id=1

/host=host:port

Optional

Default = default PI server

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

/ec=x

Optional

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

/q

Optional

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

Extended API mode behavior:

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

Sample PICimpi.bat FileThe following is an example file:REM PICIMPI.batREM --------------------------------------------------------------REM


Startup Command File

REM Sample startup file for the PI-CIMPI Interface to the PI System

REMREM --------------------------------------------------------------REMREM Required command-line parametersREM /ps=x Point SourceREM /id=x Identifier and instance number REM /Project=name Name of the Cimplicity projectREMREM Optional command-line parametersREM /sr=rate Rate at which exception data is requested.REM /timeout=sec Number of seconds before IOTIMEOUT REM is written, 0 = neverREM /time=source Source of timestamps. valid values SERVER, REM FOREIGN, ADJUSTED.REM /wd="exe serv" Start the WatchDog application designated REM by exe to monitor serv serviceREM /cimpidbg=lev Designates the debug information to be REM printed.REM /subsec=yes Use sub-second timestamps. REM valid values YES, NOREM /host=host:port PI server designationREM /ec=x Event Counter designationREM /q queue values before sending them REM across the networkREMREM Sample command lineREM PICimpi.exe /ps=F /id=1 /Project=cimpiproj /timeout=20 ^REM /CimpiDbg=0x00 ^REM /sr=500 /host=cantelelaptop:5450 /time=server^REM /wd="D:\PIPC\Interfaces\Cimplicity\WatchDog.exe ^REM PICimpi1 PICimpi2"REM --------------------------------------------------------------REM Revision HistoryREM Date Author CommentREM 25-Nov-02 JAC Written REM --------------------------------------------------------------

38

Interface Node ClockThe correct settings for the time and time zone should be set in the Date/Time control panel. If local time participates in Daylight Savings, from the control panel, configure the time to be automatically adjusted for Daylight Savings Time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node.

Make sure that the TZ environment variable is not defined. The currently defined environment variables can be listed by going to Start | Settings | Control Panel, double clicking on the system icon, and selecting the environment tab on the resulting dialog box. Also, make sure that the TZ variable is not defined in an autoexec.bat file. When the TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as being defined in the System control panel even though the variable is defined. Admittedly, autoexec.bat files are not typically used on NT, but this does not prevent a rogue user from creating such a file and defining the TZ variable unbeknownst to the System Administrator.


SecurityIf the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Data Archive. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive Manual.Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.

If the home node is a PI 2 Server, the read/write permissions should be set appropriately in the pisysdat:piserver.dat file on the PI 2 home node. For more information on setting permissions on PI 2, see the pibuild:piserver.txt file on the PI 2 home node.

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


Starting / Stopping the InterfaceThis section describes starting and stopping the interface once it has been installed as a service. See the UniInt End User Document to run the interface interactively.

Starting Interface as a ServiceIf the interface was installed a service, it can be started from the services control panel or with the command:PIGECimpi.exe –startA message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. Even if the message indicates that the service started successfully, make sure that the service is still running by checking in the services control panel. There are several reasons that a service may immediately terminate after startup. One is that the service may not be able to find the command-line arguments in the associated .bat file. For this to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory. If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file for error messages. See the section “Appendix A: Error and Informational Messages.”

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


BufferingFor complete information on buffering, please refer to the CIMPLICITY HMI .

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

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

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

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

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

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


Log On AsLog on as indicates the Windows user account under which the API Buffering service is setup to start automatically on reboot, or manually. To modify the user account or password under which bufserv runs, use the Microsoft Windows “Services” applet.

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

Service Startup TypeThe 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.

Start / Stop ServiceThe 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.

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


Enable API BufferingEnables the API Buffering feature.

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

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

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


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


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


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


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


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



Buffering

Max Theoretical Send RateThis is the theoretical max send rate is calculated like this:max = MAXTRANSFEROBJS / SENDRATE * 1000Default value is 5000.

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

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

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

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

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

The following settings are available for buffering configuration:

Keywords Values Default Description

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

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

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

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

MAXTRANSFEROBJS

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

48


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.


PIHOMENODE string none 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)

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

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


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 LogsThe 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

System Errors and PI ErrorsSystem errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions on NTOn NT, descriptions of system and PI errors can be obtained with the pidiag utility:\PI\adm\pidiag –e error_number


Revision HistoryDate Author Comments

10-Oct-02 JFZ Using Skeleton version 1.11

Initial write up for version 3.0.9 of PI-GE Cimplicity interface

24-Nov-02 JAC Initial release of interface and manual for version 3.1

26-Nov-02 CG Renamed executable to pigecimpi; fixed headers & footers


cimplicity hmi - osisoftcdn.osisoft.com/interfaces/1015/pi_geci… · web view · 2012-05-11ge...

Documents