CIMPLICITY HMI

GE FANUC CIMPLICITY HMI Interface to the PI System

Version 3.1.0

Revision A

How to Contact Us

Phone

(510) 297-5800 (main number)(510) 297-5828 (technical support)

Fax

(510) 357-8136

E-mail

techsupport@osisoft.com

World Wide Web

http://www.osisoft.com

Mail

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

OSI Software GmbH Hauptstra(e 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 LEGENDUse, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Trademark statementPI 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. HPUX 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_GECimpi.doc

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

Table of Contents

1Introduction

2Reference Manuals

2Supported Features

5Diagram of Hardware Connection

7Principles of Operation

11Installation Checklist

13Interface Installation

13Naming Conventions and Requirements

14Microsoft DLLs

14Interface Directories

15Interface Installation Procedure

15Installing the Interface as an NT Service

19Connection Tool

21Digital States

23PointSource

25PI Point Configuration

25Point Attributes

27Output Points

29Performance Point Configuration

31I/O Rate Tag Configuration

31Monitoring I/O Rates on the Interface Node

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

32Configuring I/O Rate Tags Manually

35Startup Command File

35Command-line Parameters

37Sample PICimpi.bat File

39Interface Node Clock

41Security

43Starting / Stopping the Interface

43Starting Interface as a Service

43Stopping Interface Running as a Service

45Buffering

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

48Configuring Buffering Manually

49Sample PIClient.ini File

51Appendix A: Error and Informational Messages

51Message Logs

51Messages

51System Errors and PI Errors

53Revision History

Introduction

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

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 ManualsOSIsoft

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, Userss 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 Features

Feature

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

*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 PIPoint Attribute Changes

For a Cimplicity value that doesnt 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 Cimplicitys 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 Timestamps

CIMPLICITY 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 Recovery

The interface does not support history recovery.

Fail-over

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 however, does not have a separate fail-over mechanism.

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-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 UniIntsupplied 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 Required

The 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 Software

Because 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 Types

The interface supports collecting data from Cimplicity analog, boolean, and string type tags.

Diagram of Hardware Connection

Principles of Operation

Startup

Upon 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 hasnt changed since the PI tags 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 Input

All 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-over

The 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 Interface

Interface 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 Checklist

For 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 Servers 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 Installation

OSIsoft recommends that interfaces be installed on PI-API nodes instead of directly on the PIServer node. A PI-API node is any node other than the PI Server node where the PIApplication Programming Interface (PI-API) has been installed (see the PIAPIInstallation Instructions manual). With this approach, the PI Server need not compete with interfaces for the machines resources. The primary function of the PIServer 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 PIAPInode (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 Requirements

In 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 DLLs

The 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\system32directory 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 Tree

The PIHOME directory tree is defined by the PIHOME entry in the pipc.iniconfiguration 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 PIHOMEdirectory does not need to be on the C: drive.

Interface Installation Directory

Place 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 Service

The 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 Utility

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.

The PI-Interface Configuration & Management Utility provides a user interface for creating, editing, and deleting the interface service:

Service Configuration

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.

Service Startup Type

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

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.

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

Log On As

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

Dependencies

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

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

Start / Stop Service

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.

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.

Enable API Buffering

Enables the API Buffering feature.

Maximum File Size

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

Primary Memory Buffer Size

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

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

Secondary Memory Buffer Size

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

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

Max Transfer Objects

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

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.

Max Theoretical Send Rate

This 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 Manually

Buffering 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.inifile in a text editor (Notepad on Windows) to the desired values.

The following settings are available for buffering configuration:

Keywords

Values

Default

Description

BUFFERING

0,1

0

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

PAUSERATE

0 - 2,000,000

2

When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds)

RETRYRATE

0 - 2,000,000

120

When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds)

MAXFILESIZE

1 - 2,000,000

100,000

Maximum buffer file size before buffering fails and discards events. (Kbytes)

MAXTRANSFEROBJS

1 - 2,000,000

500

Maximum number of events to send between each SENDRATE pause.

BUF1SIZE

64 - 2,000,000

32768

Primary memory buffer size. (bytes)

BUF2SIZE

64 - 2,000,000

32768

Secondary memory buffer size. (bytes)

SENDRATE

0 - 2,000,000

100

The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds)

In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define 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

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 File

On NT a piclient.ini file might look like:

[APIBUFFER]

BUFFERING=1

MAXFILESIZE=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 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 commandline 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 Errors

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

Error Descriptions on NT

On NT, descriptions of system and PI errors can be obtained with the pidiag utility:

\PI\adm\pidiag e error_number

Revision History

Date

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

Status of the Interface Service

i

UniInt End-User Interface to the PI System