Simca-Batch On-Line Interface to the PI System



Simca-Batch On-Line

Interface to the PI System

Version 1.0.0.1 and 2.1.0.0

Rev. A

How to Contact Us

|OSIsoft, Inc. |Worldwide Offices |

|777 Davis St., Suite 250 |OSIsoft Australia |

|San Leandro, CA 94577 USA |Perth, Australia |

| |Auckland, New Zealand |

|Telephone |OSI Software GmbH |

|(01) 510-297-5800 (main phone) |Altenstadt, Germany |

|(01) 510-357-8136 (fax) |OSI Software Asia Pte Ltd. |

|(01) 510-297-5828 (support phone) |Singapore |

| |OSIsoft Canada ULC |

|techsupport@ |Montreal, Canada  |

| |OSIsoft, Inc. Representative Office |

|Houston, TX |Shanghai, People’s Republic of China  |

|Johnson City, TN |OSIsoft Japan KK |

|Mayfield Heights, OH |Tokyo, Japan  |

|Phoenix, AZ |OSIsoft Mexico S. De R.L. De C.V. |

|Savannah, GA |Mexico City, Mexico  |

|Seattle, WA | |

|Yardley, PA | |

|Sales Outlets and Distributors |

|Brazil |South America/Caribbean |

|Middle East/North Africa |Southeast Asia |

|Republic of South Africa |South Korea |

|Russia/Central Asia |Taiwan |

| |

|WWW. |

|OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, |

|Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks |

|have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the |

|property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s |

|products or any affiliation with such party of any kind. |

| |

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

|Unpublished – rights reserved under the copyright laws of the United States. |

| |

|© 2001-2008 OSIsoft, Inc. PI_SimBatchOL.doc |

Table of Contents

Introduction 1

A Terminology Note 1

Reference Manuals 1

Supported Features 2

Principles of Operation 5

Modified Point Names 6

Installation Checklist 7

Interface Installation 9

Interface Directories 9

PIHOME Directory Tree 9

Interface Installation Directory 9

Interface Installation Procedure 9

PISBOL.ini Parameters 10

Interface Node Clock 11

Security 21

Appendix A: Error and Informational Messages 21

Message Log 23

Error and Informational Messages 23

Appendix B: Version 1.x.x.x 25

Introduction 25

A Terminology Note 25

Reference Manuals 25

Supported Features 26

Principles of Operation 28

Tags and Batch Ids 28

Truncated Server and Point Names 29

Modified Server and Point Names 29

Installation Checklist 30

Interface Installation 31

Interface Directories 31

Interface Installation Procedure 31

PISBOL.ini Parameters 32

Error and Informational Messages 33

Message Logs 33

Debug Messages 33

Error and Informational Messages 33

Revision History 36

Introduction

The PI SimBatchOL Interface provides connectivity between one or more PI servers and a single Simca-Batch On-line Data Server. The PI SimBatchOL Interface consists of a Windows 32-bit DLL which satisfies the Simca-Batch On-Line External Database API requirements. The file PISimBatchOL.dll is for version 2.x.x.x of this interface and will only work with SBOL version 3.1.0.1 or greater. The file simapi.dll is for version 1.x.x.x of this interface and will work with SBOL versions 1 and 2. See Appendix B for version 1.x.x.x information.

Note: This interface is different from other PI interfaces in that it is the Simca-Batch On-Line which makes calls to the commands contained in the interface dll to exchange data with the PI system.

This interface requires the following software be installed on the same machine as the interface:

• PI SDK version 1.3.4 or greater

The interface is only compatible with PI3 servers.

Both inputs to and outputs from PI are supported. Although the direction of data flow is bi-directional in nature, the primary purpose of this interface is to provide PI data to the Simca-Batch On-Line Server instead of providing external process data to PI.

It will operate with the Module DB and Batch DB of the PI Server 3.3.0 and higher.

A Terminology Note

This document refers to Servers and Points, Umetrics applications refer to Nodes and Tags.

The terms Server and Node are synonymous.

The terms Point and Tag are synonymous.

Reference Manuals

OSIsoft

• PI Server Manual

• PI API Installation Instructions

• PI SDK Installation Instructions

Umetrics

• Application Installation Instructions

Supported Features

|Feature |Support |

|Part Number |PI-IN-SIM-BO-NT |

|*Platforms |Windows 2000 / XP / Server 2003 |

|APS Connector |No |

|Point Builder Utility |No |

|ICU Control |No |

|PI Point Types |Float16, Float32, Float64, Int16, Int32, and Digital |

|Sub-Second Timestamps |No |

|Sub-Second Scan Classes |No |

|* Automatically Incorporates PI Point Attribute |No |

|Changes | |

|Exception Reporting |Only uses snapshot |

|Outputs from PI |Yes |

|* Inputs to PI: Scan-Based / Unsolicited / Event Tags|See below |

|Supports Questionable Bit |No |

|Supports Multi-character PointSource |No |

|Maximum Point Count |None |

|*Uses PI SDK |Yes |

|PINet String Support |N/A |

|* Source of Timestamps |Client Application |

|History Recovery |No |

|Failover |No |

|UniInt-Based |No |

|* Vendor Software Required on PI Interface Node / |Yes |

|PINet Node | |

|Vendor Software Required on Foreign Device |No |

|Vendor Hardware Required |No |

|Additional PI Software Included with Interface |No |

|Device Point Types |No |

* See paragraphs below for further explanation.

Platforms

The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater.

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

The data transfer between the PI server and the Simca-Batch On-Line client application is executed whenever the client application calls the PI SDK functions for data reading and writing.

Source of Timestamps

The client application provides timestamps for input data. PI provides timestamps for output data, but the client application may or may not use them.

Uses PI SDK

The PI SDK and the PI API are bundled together and must be installed on each PI Interface node.

Vendor Software Required on PI Interface Node / PINet Node

This interface is implemented as a DLL and thus loaded by the client application at run-time.

Principles of Operation

This Interface performs as an adapter between the requirements of the Umetrics Simca-Batch On-Line External Database API and the PI SDK.

It permits a Umetrics client application to:

• Query for information about the connected server and the available analog and digital points on the server.

• Read and write point snapshot data for multiple analog and digital points to and from one PI3 server.

• Read archive data for multiple analog and digital points from one PI3 server.

• Read batch data from the PI Batch DB.

Modified Point Names

Another restriction of Umetrics applications is that the colon character “:” is reserved and cannot be used in server or point names. Umetrics Simca-Batch On-Line automatically replaces colon characters “:” with the period character “.”. For instance, the point name “BA:Active.1” would display in the Umetrics Simca-Batch On-Line as “BA.ACTIVE.1”.

Thus, any point name will appear within the Umetrics application with colons replaced by periods.

It is unlikely, but possible, that these conversions result in two or more points having identical names and it will be necessary to make point names unique for correct operation.

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI SimBatchOL 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. Verify that the PI SDK has been installed. A PI Server is also required if the interface is running on the PI Home Node.

2. Install the interface.

3. Configure the PISBOL.ini file. A sample PISBOL.ini file called PISBOL.ini.sam is distributed with the interface.

4. Ensure that the PI servers specified in the PISBOL.ini file are in the Known Servers Table for PI SDK. Otherwise, the PI servers can not be connected from Umetrics applications. The PI servers can be added to the Known Servers Table via the AboutPI SDK program delivered with the PI SDK. Refer to the PI SDK manual for details. Furthermore, if a password is required for the PI user while connecting to a PI Server with AboutPI SDK, a trust entry for the node running the interface and the PI user should be added to the PITrust table on the PI Server. Refer to the PI Server manual for details about the PITrust table.

Interface Installation

OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server node. A PI Interface 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 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.

Interface Directories

PIHOME Directory Tree

The 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 %windir% 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 Directory

The interface install kit will automatically install the interface to:

PIHOME\Interfaces\SimBatchOL\

PIHOME is defined in the pipc.ini file.

Interface Installation Procedure

The PI Simca-Batch On-Line Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and greater operating systems. When running on Windows NT 4.0 systems, the PI Simca-Batch On-Line setup program will install the Windows Installer itself if necessary. To install from CD, run the setup.exe file. To install from the web distribution kit, run SimBatchOL_x.x.x.x.exe

Installing or Upgrading the Interface

If the interface is being installed as a replacement for an earlier version of the interface:

1. Shut down all Umetrics applications and services using the interface [PISimBatchOL.dll] to be replaced.

2. Run the SimBatchOL_x.x.x.x.exe file downloaded from the OSIsoft support web site or the setup.exe on the CD. This will place the new version of PISimBatchOL.dll into the interface directory. The copy of the PISBOL.ini file used by the previous interface version should be in the same directory as the new PISimBatchOL.dll.

3. Restart the Umetrics applications and services.

Install as Part of a Umetrics Product

If the interface is being installed as part of an installation of an Umetrics product:

1. When the Umetrics installation prompts for the location of PISimBatchOL.dll, provide the location of the interface.

2. Create a PISBOL.ini file in the same directory that the PISimBatchOL.dll is copied. See the section below for details. A sample PISBOL.ini file called PISBOL.ini.sam is installed by the setup kit.

PISBOL.ini Parameters

The ini file contains multiple lines of the format key=value. There are no spaces permitted either side of “=” character. Key = value is incorrect.

|Key |Value |

|Debug=x |Only the first character of the value is read and this must be a ‘t’, ‘T’ or ‘1’ to |

| |turn debugging on. Any other character will result in no debugging information. |

| |Debugging should generally be set to off. |

|Server=name |The value is the name of one PI server from which to obtain point data. |

| |This key can occur one or more times in one ini file. Examples of the use of this key:|

| |server=XXXXXX:5450 |

| |server=Maurice |

| |The portnum is ignored and does not need to be entered. |

| |Changes made to the server entries in the ini file will not be implemented whilst the |

| |adaptor is in use. This requires a reset of the Umetrics application. |

|Trim=x |Only the first character of the value is read and this must be a ‘t’, ‘T’ or ‘1’ to |

| |turn trim on. Any other character will result in no trimming. |

| |Trim on will trim white space from all string event values. This is used to resolve |

| |an issue with white space in batch id events. |

Digital States

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

Digital State Sets

PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.

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 Set

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

Performance Point Configuration

This Interface does not support Performance Points.

I/O Rate Tag Configuration

This Interface does not support I/O Rate Tag.

Interface Node Clock

Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,

[pic]

In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,

C:> set

Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.

Security

The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.

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 interface cannot write data to the PI 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.

PI Server v3.3 and Higher

Security configuration using piconfig

For PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:

C:\PI\adm> piconfig

@table pitrust

@mode create

@istr Trust,IPAddr,NetMask,PIUser

a_trust_name,192.168.100.11,255.255.255.255,piadmin

@quit

For the above,

Trust: An arbitrary name for the trust table entry; in the above example,

a_trust_name

IPAddr: the IP Address of the computer running the Interface; in the above example,

192.168.100.11

NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr

PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user

Security Configuring using Trust Editor

The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.

See the PI System Management chapter in the PI Server manual for more details on security configuration.

PI Server v3.2

For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:

C:\PI\adm> piconfig

@table pi_gen,piproxy

@mode create

@istr host,proxyaccount

piapimachine,piadmin

@quit

In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.

Appendix A:

Error and Informational Messages

Message Log

There is one message log:

pipc.log

This log is located in PIHOME\dat\ directory. In this log all messages are pre-pended with “PI SimBatchOL>.” Error, debug and informational messages are written to this log.

Error and Informational Messages

These messages are written to the logs at the following times:

• When the interface starts, the version of the interface is written.

• When the application calls the open function of the interface, the name of server found, and any problems or errors found are written.

• When the application calls other functions of the interface, if problems or errors occur, messages are written

Appendix B:

Version 1.x.x.x

Introduction

The PI SimBatchOL Interface provides connectivity between one or more PI servers and a single Simca-Batch On-line Data Server. The PI SimBatchOL Interface consists of a Windows 32-bit DLL which satisfies the Simca-Batch On-Line External Database API requirements.

Note: This interface is different from other PI interfaces in that it is the Simca-Batch On-Line which makes calls to the commands contained in the interface dll to exchange data with the PI system.

This interface requires the following software be installed on the same machine as the interface:

• PI API version 1.3.4 or greater

• PI SDK version 1.1.0 or greater

The interface is only compatible with PI3 servers.

Both inputs to and outputs from PI are supported. Although the direction of data flow is bi-directional in nature, the primary purpose of this interface is to provide PI data to the Simca-Batch On-Line Server instead of providing external process data to PI.

It will operate with the Module DB and Batch DB of the PI Server 3.3.0 and higher.

A Terminology Note

This document refers to Servers and Points, Umetrics applications refer to Nodes and Tags.

The terms Server and Node are synonymous.

The terms Point and Tag are synonymous.

Reference Manuals

OSIsoft

• PI Server Manual

• PI API Installation Instructions

• PI SDK Installation Instructions

Umetrics

• Application Installation Instructions

Supported Features

|Feature |Support |

|Part Number |PI-IN-SIM-BO-NT |

|*Platforms |Windows NTI / 2000 / XP |

|APS Connector |No |

|Point Builder Utility |No |

|ICU Control |No |

|PI Point Types |Float16, Float32, Float64, Int16, Int32, and Digital |

|Sub-Second Timestamps |No |

|Sub-Second Scan Classes |No |

|* Automatically Incorporates PI Point Attribute |Extended API function apiex_tagChange must be called by |

|Changes |client |

|Exception Reporting |Only uses snapshot |

|Outputs from PI |Yes |

|* Inputs to PI: Scan-Based / Unsolicited / Event Tags|See below |

|Supports Questionable Bit |No |

|Supports Multi-character PointSource |No |

|Maximum Point Count |None |

|*Uses PI SDK |Yes |

|PINet String Support |N/A |

|* Source of Timestamps |Client Application |

|History Recovery |No |

|Failover |No |

|UniInt-Based |No |

|* Vendor Software Required on PI Interface Node / |Yes |

|PINet Node | |

|Vendor Software Required on Foreign Device |No |

|Vendor Hardware Required |No |

|Additional PI Software Included with Interface |No |

|Device Point Types |No |

* See paragraphs below for further explanation.

Platforms

The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater.

Automatically Incorporates PI Point Attribute Changes

The interface does not automatically update the interface when there are PI point attribute changes. The extended PI API function, apiex_tagChange, must be called by the client in order for the interface to incorporate PI point modifications, additions, or deletions.

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

The data transfer between the PI server and the Simca-Batch On-Line client application is executed whenever the client application calls the PI API functions for data reading and writing.

Source of Timestamps

The client application provides timestamps for input data. PI provides timestamps for output data, but the client application may or may not use them.

Uses PI SDK

The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface specifically makes PI SDK calls to access PI Module Database and PI Batch Database.

Vendor Software Required on PI Interface Node / PINet Node

This interface is implemented as a DLL and thus loaded by the client application at run-time.

Principles of Operation

This Interface performs as an adapter between the requirements of the Umetrics Simca-Batch On-Line External Database API and the PI SDK/PI API.

It permits a Umetrics client application to:

• Query for information about connected servers and the available analog and digital points on each server.

• Read and write point snapshot data for multiple analog and digital points to and from one or more PI3 servers.

• Read archive data for multiple analog and digital points from one or more PI3 servers.

• Provide a batch identity from any PI analog or digital point by converting the current point value to a string.

• Provide a batch identity from a PI string point.

• Provide the batch identity for the current PI UnitBatch associated with a PIUnit in the PI Module Database provided that the PIUnit has a PI Point aliased to it.

Tags and Batch Ids

The interface supports three methods for generating batch ids from PI points.

Analog and Digital Points

The first method, which will work with any version of a PI3 Server, converts the current point value of an integer, real or digital point to an integer number and returns a string representation of this value.

For an integer point the string form of the current value is returned. For example, a current value of 27 is returned as “27.”

For a real point the string form of the rounded current value is returned. For example, a current value of 34.78 is returned as “35.”

For a digital point the string form of the index of the current state within the digital state set is returned. For a digital point with a digital set of “Auto”, “Manual”, “Cascade”, “Program” and “Auto-Program” a current value of “Cascade” is returned as “2.”

String Points

The second method works with PI string points in any version of PI3 Server. The interface simply returns the value of a PI string point as the batch id.

Aliased Points

The third method is for use with the PI Server and the Batching functionality it provides. The interface obtains the Batch IDs of the current PI UnitBatches contained in the PI Module Databases.

The requirement is to associate a PI point with the PIUnit through which the required PI UnitBatch information is being retrieved. This is done by creating a PIAlias for the point in the PIUnit. The interface searches the Module Databases of all servers on initialization for PIUnits and any associated PIAliases. By requesting the batch identity via an aliased PI point, the Batch ID of the current PI UnitBatch contained in the PIUnit under which the point is aliased will be returned as the batch identity. If there is no current PI UnitBatch found in the PIUnit, no valid Batch ID will be obtained.

The type of the point is irrelevant for aliased points.

It is essential that only one Point be a PIAlias for only one PIUnit

It is essential that the numeric option is NOT checked in the Umetrics Dialog Box when using Aliased Points to obtain the Batch IDs of the current PI UnitBatches. Otherwise, as described in the first and second methods, the point value or its string representative will be returned, depending on the point type.

Read the PI Server manual for an understanding of the details of Batches and the PI Server and for information on PIAliases

Truncated Server and Point Names

Some Umetrics applications that can be used with this interface have restricted lengths for the names of servers and points, and this length depends upon the application. Whenever this interface must truncate a name in order to satisfy the requirements of the connected application, the information is written into the message logs [see Appendix A, Message Logs]. For instance, a limit of eight characters on server names would result in the server “PLANTMONITOR1” being returned as “PLANTMON”, it would appear as “PLANTMON” within the Umetrics application, and the log file would contain the message:

Name “PLANTMONITOR1” truncated to “PLANTMON” [8 characters].

Note: This raises the possibility of two or more servers (or points) being truncated to the same non-unique name, PLANTMONITOR2 would also become PLANTMON. Should this be the case, it will be necessary to make server and point names unique within the restricted length for correct operation.

Modified Server and Point Names

Umetrics applications are not case-sensitive and all server and point names are converted to upper-case by the interface.

Another restriction of Umetrics applications is that the colon character “:” is reserved and cannot be used in server or point names. The interface automatically replaces colon characters “:” with the underscore character “_”. For instance, the point name “BA:Active.1” would automatically become “BA_ACTIVE.1”.

Thus, any server or point name will appear within the Umetrics application as uppercase with colons replaced by underscores.

It is unlikely, but possible, that these conversions result in two or more points or two or more servers having identical names and it will be necessary to make server and point names unique for correct operation. This will result in an error message of:

Point “PointName” already exists

or

Server “ServerName already exists.

appearing in the message logs.

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI SimBatchOL 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.

5. Verify that the PI SDK and PI API have been installed. A PI Server is also required if the interface is running on the PI Home Node.

6. Install the interface.

7. Configure the PISBOL.ini file. A sample PISBOL.ini file called PISBOL.ini_sam is distributed with the interface by the installation kit.

8. Ensure that the PI servers specified in the PISBOL.ini file are in the Known Servers Table for PI SDK. Otherwise, the PI servers can not be connected from Umetrics applications. The PI servers can be added to the Known Servers Table via the AboutPI SDK program delivered with the PI SDK. Refer to the PI SDK manual for details. Furthermore, if a password is required for the PI user while connecting to a PI Server with AboutPI SDK, a trust entry for the node running the interface and the PI user should be added to the PITrust table on the PI Server. Refer to the PI Server manual for details about the PITrust table.

Interface Installation

OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server node. A PI Interface 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 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.

Interface Directories

PIHOME Directory Tree

The 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 %windir% 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 Directory

The interface install kit will automatically install the interface to:

PIHOME\Interfaces\SimBatchOL\

PIHOME is defined in the pipc.ini file.

Interface Installation Procedure

The PI Simca-Batch On-Line Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and greater operating systems. When running on Windows NT 4.0 systems, the PI Simca-Batch On-Line setup program will install the Windows Installer itself if necessary. To install from CD, run the setup.exe file. To install from the web distribution kit, run SimBatchOL_x.x.x.x.exe

Installing or Upgrading the Interface

If the interface is being installed as a replacement for an earlier version of the interface:

4. Shut down all Umetrics applications and services using the interface [simapi.dll] to be replaced.

5. Run the SimBatchOL_x.x.x.x.exe file downloaded from the OSIsoft support web site or the setup.exe on the CD. This will place the new version of simapi.dll into the interface directory. The copy of the PISBOL.ini file used by the previous interface version should be in the same directory as the new simapi.dll.

6. Restart the Umetrics applications and services.

Install as Part of a Umetrics Product

If the interface is being installed as part of an installation of an Umetrics product:

3. When the Umetrics installation prompts for the location of simapi.dll, provide the location of the interface.

4. Create a PISBOL.ini file in the same directory that the simapi.dll is copied. See the section below for details. A sample PISBOL.ini file called PISBOL.ini_sam is installed by the setup kit.

PISBOL.ini Parameters

The ini file contains multiple lines of the format key=value. There are no spaces permitted either side of “=” character. Key = value is incorrect.

|Key |Value |

|Debug=x |Only the first character of the value is read and this must be a ‘t’, ‘T’ or ‘1’ to |

| |turn debugging on. Any other character will result in no debugging information. |

| |The ini file is re-read approximately every ten minutes. This value can be edited |

| |whilst the server is running and the new state will be implemented within ten minutes.|

| | |

| |Debugging should generally be set to off. |

|Server=name |The value is the name of one PI server from which to obtain point data. |

| |This key can occur one or more times in one ini file. Examples of the use of this key:|

| |server=localhost:5450 |

| |server=Maurice |

| |The :portnum is ignored and does not need to be entered. |

| |Changes made to the server entries in the ini file will not be implemented whilst the |

| |adaptor is in use. This requires a reset of the Umetrics application. |

Error and Informational Messages

Message Logs

There are two message logs:

pipc.log

This log is located in PIHOME\dat\ directory. In this log all messages are pre-pended with “PI SimBatchOL>.” Error and informational messages are written to this log. Debugging messages are not written to this log.

PISBOL.log

This log is located in the same directory as the copy of the running interface. Error, informational and debugging messages are written to this log. The current log is always called PISBOL.log. Once the log size exceeds 1Mb, the log is shifted to a backup log and a new PISBOL.log created. The previous ten backup logs (named PISBOL0.log to PISBOL9.log) are retained. When a shift occurs and ten backup logs already exist, the oldest is overwritten.

Debug Messages

Debug messages are only written to the PISBOL.log in the same directory as the adaptor dll. These messages are written when the debug entry in the PISBOL.ini file is set to “t,” ”T,” or ‘1.’ Changes to this entry are implemented within ten minutes.

Error and Informational Messages

These messages are written to the logs at the following times:

• When the interface starts, the version of the interface is written.

• When the application calls the open function of the interface, the versions of the PI API and PI SDK, the names and versions of servers found, and any problems or errors found are written.

• When the application calls other functions of the interface, if problems or errors occur, messages are written

Some Messages may be pre-pended by one of the following texts:

API Error: The interface is returning a status value other than API_OK to the application. The full format for this message is:

API Error: error name function name

Any preceding entries may give an indication of the problem.

NOTE: If debugging is enabled, then messages will be written to the PISBOL.log for every function call, even those that return API_OK.

PI Error: A call to the PI API unexpectedly returned an error value. The full format for this message is:

PI Error: [error number] error description – api function called, additional text – calling function

SDK Error: A call to the PI SDK unexpectedly returned an error value. The full format for this message is:

SDK Error: [error number] error description – sdk method called, additional text – calling function/method

Other Messages

Already Open

Error: The interface is currently open as a result of another call to api_open.

API Version: “x.x.x”; Minimum Required Version is “y.y.y”

Error: The version of the PI API installed on this computer is earlier than the version required by the interface.

Batch Server “ServerName” Not Found

Error: The server[node] specified for the batch id tag could not be found. Has the name been mistyped?

CoInitialize Failed

Error: An error occurred initializing the Windows COM system.

Error Resizing Point Vector

Error: Memory could not be allocated to store necessary information about points [tags].

Failed to Insert Server into Server Map

Error: Memory could not be allocated to store necessary information about servers [nodes].

Invalid Handle

Error: The handle supplied with this function call is not valid.

Name “FullName” Truncated to “ShorterName” [x characters]

Warning: The point [tag] or server [node] name specified by FullName has been shortened to ShorterName, which is x characters long. See the section Truncated Server and Point Names for the significance of this message.

No Current Unit Batch Found for Point “PointName” on Server “ServerName”

Error: There is no unit batch current for the point [tag] from which to obtain a batch id.

No Servers in Collection

Error: There are no servers [nodes] to work with.

Are any servers specified in the PISBOL.ini file and is it in the same directory as the copy of the DLL being executed?

Are the servers specified in the PISBOL.ini file in the Known Servers Table, i.e., are they connected via PI SDK?

Is there a network problem?

No Valid Current Value for Point “PointName” on Server “ServerName”

Error: There is no valid value for the point [tag] from which to generate a batch id.

Open Not Called

Error: The interface has not been opened with a call to api_open or api_close has been called.

Point is “PointName”

Informational: The preceding message refers to this point [tag].

Point “PointName” Already Exists

Error: A point with the same name already exists for the server in this interface. See the section Modified Server and Point Names for the probable cause of this error.

Point “PointName” Not Found on Server “ServerName”

Error: Either there is no point [tag] with the specified name on the specified server [node] or the point does not meet the requirements to supply a batch id. See section Tags and Batch Ids.

SDK Version: “x.x.x”; Minimum Required Version is “y.y.y”

Error: The version of the PI SDK installed on this computer is earlier than the version required by the interface.

Server “ServerName” Already Exists

Error: A server with the same name already exists in the interface. See the section Modified Server and Point Names for the probable cause of this error.

Server “ServerName” Contains No Points or Batch Units

Warning: The server specified does not contain any analog or digital points [tags] neither does it contain any PIAliases for PIUnits. A server must have at least one point [tag] to be included in the collection

Server “ServerName” Not Found

Error: The server name specified in the PISBOL.ini file is not registered with PI. Has the name been mistyped?

ServerSnapshotReader::Add: point == 0 or iCount >= iSize.

Error: A point has not registered successfully for a current value read.

ServerSnapshotReader::FindPoint called !!

Warning: Point ids are being returned out of order and a point search is required.

Unable to Set Server “ServerName” as Active Server

Error: The specified server was not set as the active server and reads and writes to the PI database can not be made.

Error Descriptions on Windows

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

\PI\adm\pidiag –e error_number

Revision History

|Date |Author |Comments |

|8-Oct-2001 |NC |Document for V1.1.0, uses skeleton document v1.09 |

|10-Jan-2003 |DChen |Use skeleton v1.11. Change the interface name to PI-SBOL v1.0.0 |

|11-April-2003 |DChen |Change the version from 1.0.0 to 1.0.0.0 and change the name from |

| | |SBOL to SimBatchOL |

|21-May-2003 |DChen |Update “Security” section to include PI Trust Database. Add the |

| | |server connection via PI SDK into the installation check list. |

|1-July-2003 |DChen |Add string points for Batch ID and clarify the aliased points for |

| | |batch id. |

|28-Aug-2003 |DChen |Update the manual using skeleton document v1.12 |

|04-Sep-2003 |CGoodell |Some reformatting; clarified Supported Features table |

|08-Sep-2003 |HBeeson |Added setup info (1.0.0.0,doc rev A). |

|11-Apr-2006 |DChen |Change the document version from 1.0.0.0 to 1.0.0.1 |

|25-Apr-2006 |MKelly |Version 1.0.0.1 Rev A: Updated to current interface skeleton |

| | |manual v2.4, fixed headers and footers, updated How to Contact Us |

| | |page, copyright date, supported features. |

|18-Mar-2008 |OAcevedo |Document for V2.1.0.0, uses skeleton document v2.5.6 |

|24-Mar-2008 |MKelly |Version 1.0.0.1 and 2.1.0.0 Rev A; fixed headers and footer, page |

| | |setup, made minor formatting changes and wording. Saved as Final.|

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download