Uniint End User - OSIsoftcdn.osisoft.com/interfaces/348/PI_baSemAPI_1.3.4NT-1.2VMS-Rev… · Web viewIf the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy

Uniint End UserInterface to the PI System

Interface version 0.xUniint version 2.343.4 NT and greater

Version 1.2 VMS and greaterDocument Revision C

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 OSI Software, Inc.P.O. Box 727San Leandro, CA 94577-0427USA

OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1Deutschland

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

OSI Software, LtdP. O. Box 8256Level One, 6-8 Nugent StreetAuckland 3, New Zealand

Unpublished -- rights reserved under the copyright laws of the United States.RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX

and DEC Alpha are registered trademarks of the Digital Equipment Corporation. basemapi.doc

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

Supported Features......................................................................................................1

Diagram of Hardware Connection:...............................................................................4

Principles of Operation.................................................................................................5System Digital States Written to Tag............................................................................6

Interface Messages and Error Recovery......................................................................6

Installation Checklist.....................................................................................................7Windows NT.................................................................................................................7

VMS..............................................................................................................................7

Interface Installation on NT...........................................................................................9Naming Conventions and Requirements......................................................................9

Microsoft DLLs..............................................................................................................9

Interface Directories...................................................................................................10

The PIHOME Directory Tree...................................................................................10

Interface Installation Directory................................................................................10

Interface Installation...................................................................................................10

Interface Installation Procedure..................................................................................11

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

Interface Installation on VMS......................................................................................15Naming Conventions and Requirements....................................................................15

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

Testing Connection to ICI............................................................................................19

Point Source.................................................................................................................21

PI Point Configuration.................................................................................................23Point Attributes...........................................................................................................23

Tag.........................................................................................................................23

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

PI-Bailey semAPI Interface iii

PointType...............................................................................................................23

Location1................................................................................................................23

Location2................................................................................................................23

Location3................................................................................................................24

Location4................................................................................................................24

Location5................................................................................................................24

InstrumentTag........................................................................................................24

ExcDesc..................................................................................................................24

Bailey Point Types......................................................................................................26

Supported Input Point Types (Bailey Data to PI)....................................................26

Scan.......................................................................................................................28

Source Tag.............................................................................................................28

Other.......................................................................................................................29

Shutdown................................................................................................................30

Output Points..............................................................................................................30

Output Point Types (PI Data to Bailey)...................................................................31

Detail Description of the Point Types......................................................................31

Trigger Method 1 (Recommended).........................................................................43

Trigger Method 2....................................................................................................43

Tag Configuration from Bailey Database...................................................................45

Performance Point Configuration...............................................................................47

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

Configuring the PI Point on the PI Server..................................................................49

Configuring on the Interface Node.............................................................................49

Startup Command File.................................................................................................51

Interface Node Clock...................................................................................................59NT...............................................................................................................................59

VMS............................................................................................................................59

Security.........................................................................................................................61NT...............................................................................................................................61

VMS............................................................................................................................61

Starting / Stopping the Interface on NT......................................................................63Starting Interface as a Service...................................................................................63

PI-Bailey semAPI Interface iv

Stopping Interface Running as a Service...................................................................63

Starting / Stopping the Interface on VMS...................................................................65Starting a Detached Process......................................................................................65

Stopping.....................................................................................................................67

Buffering.......................................................................................................................69

Restrictions and Other Information............................................................................73

Appendix A Error and Informational Messages........................................................77Message Logs............................................................................................................77

Messages...................................................................................................................77

System Errors and PI Errors.......................................................................................77

PI-Bailey semAPI Interface v

IntroductionThe PI-Bailey semAPI interface provides bi-directional data transfer between a PI system and a Bailey Infi90 instrument system. The interface runs on Windows NT-Intel PC, DEC VAX and DEC Alpha computers.

This interface was developed to take advantage of Bailey's semAPI library. The semAPI software handles all of the Bailey communications protocol and thereby makes it possible for the PI interface to communicate to Bailey ICI modules via a variety of transport methods (serial, Ethernet, and SCSI). Currently, interface version 1.3 and greater is compatible with semAPI version 2.0 and greater. Interface version 1.2 is compatible with semAPI version 1.2. For version compatibity and other semAPI issues, see the restriction section at the end of the manual.

Communication using the semAPI software requires that the customer purchases the Bailey semAPI software and computer interface module as well as the PI interface software.

The interface works with the following Bailey computer interface modules:

INICI03, INFI-NET to Computer Interface.

The INICI03 supports serial and SCSI connection to the host computer. The module supports a maximum of 30,000 points. Each instance of the interface connects to one computer interface module.

Reference Manuals

OSI UniInt End User Document

PI Data Archive Manual

PI-API Installation Instructions

Vendor SemAPI Instruction Manual

Function Code Application Manual

PI-Bailey semAPI Interface 1

Supported FeaturesSupported Features

Platforms Vax VMS/Alpha VMS / NTI/NTA

PI Point Types Float32 / Float16 / Digital / Integer16 / Integer32

Sub-Second Timestamps No

Sub-Second Scan Classes No

Automatically Incorporates PI Point Attribute Changes

Yes

*Exception Reporting See Note

Outputs from PI Yes

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

Unsolicited

Maximum Point Count 30,000

Uses PI-SDK No

PINet to PI 3 String Support Yes / No

* Source of Timestamps PI server

* History Recovery No

* Failover Yes

* Uniint-Based Yes

* Vendor Software Required on PI-API / PINet Node

No

* Vendor Software Required on Foreign Device

Yes

* Vendor Hardware Required Yes

* Additional PI Software Included with Interface

No

* See paragraphs below for further explanation.

Note: The Bailey System sends data to the PI interface by exception. Hence, by default, the interface does not apply the PI tag’s exception reporting on top of the Bailey events. Also, this interface uses a modifed version of UniInt.

Source of TimestampsThe interface keeps tracks of the current time of the PI server. It applies that time to the timestamp of the exception-based event sent from Bailey.

History RecoveryHistory Recovery is not supported.


FailoverThe interface supports fail-over to provide redundant data collection on both VMS platform and on Windows NT platform. The fail-over setup involves two instances of the interface, one in primary data collection mode and one in secondary or standby data collection mode. Each interface communicates to a separate ICI module. The secondary interface would monitor the ICI module status of the primary interface. If the primary ICI module is not in EXECUTE mode, the secondary interface will start collecting data. When the primary ICI module comes back on-line, the secondary interface would go back to standby mode.

Since the fail-over mechanism depends on the ICI module, you should not set the ICI watch dog timer to 0 for the primary interface. Otherwise, the ICI module will continue to be in EXECUTE mode even if the primary interface stops communicating to the ICI module.

When installing the interface in fail-over setup, you should test the fail-over configuration by stopping the primary interface program and verifying that the secondary interface picks up data collection. If the secondary interface cannot read the module status of the primary ICI module within five minutes of the interface startup, the interface program will terminate, assuming the PCU address provided by the command file is incorrect. This safety check is designed to avoid having both instances of the interface collecting data at the same time.

UniInt-BasedUniInt stands for Universal Interface, and it is an OSI-developed template used to create many of our interfaces. UniInt is not a separate product or file, it is solely a template used by our developers, and is integrated into the 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. UniInt is constantly being upgraded with new options and features. In any UniInt interface, UniInt uses some of the supplied configuration parameters, and some parameters are interface-specific features of the interface.

The UniInt End User Document is a supplement to this manual.

Vendor Software RequiredThe interface needs the Bailey SemAPI to be installed on the interface node.

Vendor Hardware RequiredThe interface connects to ICI03 via SCSI or serial connection.


Introduction

Diagram of Hardware Connection:

4

Principles of OperationThe Uniint End User interface supports the major Bailey point types for reading data from the Infi90. It also supports data output to the Infi90 system via the Analog and Digital Report functions.

PI tag configuration is similar to prior versions of the PI-Bailey interface. All data read by the interface come from the Bailey system as exception reports. Bailey generates an exception report whenever the value or the status changes, or when a specific amount of time has elapsed since the last report (exception maximum time). Data is output to Bailey with any change in the related value or the event time in PI.

The most common network topology used by the interface is peer to peer. With this approach, the interface process and semAPI software reside on the same computer. This computer is physically connected via serial, SCSI or Ethernet cable to a Bailey communications module, which is itself, connected to the Bailey INFI90 network. The sequence of operation for the interface is as follows:

1. The interface retrieves all the tags for the specified point source and processes only those tags with matching ICI number. The interface builds the tags into a sequential list keyed by list index position

2. The interface attempts to initiate communication with the Bailey communications modules via calls to Bailey semAPI libraries. These, in turn, establish a device driver process to talk to the Bailey communications module. The Bailey device driver handles physical and low-level protocol communication.

3. Via the semAPI call, the interface then establishes the tags in the Bailey communications module point table. After all points are established and connected, the interface enters the data collection phase.

4. The interface keeps reading exception data from the Bailey communications module until the maximum number of exceptions specified in the interface startup parameters have been reached or ten read exception calls have been made.

5. The interface checks for output events to be processed. Whenever output tags are triggered within PI, data will be sent to the Bailey system.

6. If more than two minutes have been passed since the last point database check, the interface will check for point database changes. Tags are added, modified or deleted from the interface if necessary.

7. Steps 4 to 6 are repeated as long as the interface is running.

8. If the interface encounters ten consecutive errors when communicating with the semAPI, then it will go back to the start up phase at step 2.

Note: Since the ICI point table can only buffer off one exception for each point, it is possible for the interface to miss exception reports for Bailey tags that are changing values too rapidly. For example, if the control engineer has configured a RCM to reset itself after the operator has set the RCM to ‘on’ state, the PCU module will generate two exception report within a second. Most likely, the interface will not be able to catch the first exception report before it is over-written by the second exception on the ICI module.


System Digital States Written to TagDuring normal operation, the interface may set the status of PI tags to a series of digital states as follows:

All tags are set to I/O Timeout at interface shutdown.

When the interface fails to establish a point in the ICI module, the related PI tags are set to the digital state Configure.

When a tag is removed or deassigned from the interface, the tag status is set to NO DATA.

If there are 10 sequential failures in obtaining exception data from Bailey semAPI, the interface will set all tags to NO Data.

An input tag is set to BAD Input if Bailey BAD QUALITY flag is set or if a digital value is out of range for that tag

An output tag is set to BAD Input if the PI value is a digital state code such as Shutdown or OverRange.

Interface Messages and Error RecoveryThe normal sequence of operations performed by the interface is already described in the introduction section at the beginning of the manual. At each phase of the operation, the interface writes a message to the PI system log file. On the VMS, the log file is in pisysmgr:pimesslog.txt as well as the interface log file as specified in the startup parameter. On Windows NT, the PI system log file is normally in c:\pipc\dat\pipc.log. The directory for the pipc.log is specified in the WINNT\pipc.ini file. Each message from the interface should be prefixed with “PBI” following with the interface number. These interface messages provide good troble shooting information about the interface.

When the interface encounters ten consecutive communication errors with the ICI, the interface will attempt to clear the error by going through the error recovery procedure. The error recovery starts with discconecting from the semAPI. Then the interface goes back to the startup phase of the operation, as described in the beginning of the manual. This auto error recovery feature normally clears problems caused by line noise. However, hardware failure will still required human intervention.


Installation ChecklistThis checklist should help you get the interface up and running. The steps should be followed in the order outlined below.

Windows NT

1. Install Bailey semAPI software as per Bailey Document E96-827-1, installation section.

2. Define a logical ICI for each ICI module with the program ICICONF.

3. After configuring the logical ICI, always test the communication to the ICI using the TALK90 program. TALK90 is an important communication trouble shooting tool. If TALK90 is having problem communicating to the ICI module, the PI interface cannot be expected to function properly. At least execute command 100(connect to ICI) and 19(restart ICI). Other commands to try are 43 (read time) and 84 (establish import point). Command 84 is on the second page of commands.

VMS

1. Install Bailey semAPI software as per Bailey Document E96-827-1. Link the programs DEVICE, ICICONF and TALK90. The link procedure will put the executables in the directory defined by ICI$EXE.

2. Define a logical ICI for each ICI module with the program ICICONF. The program will prompt for information about the type of connection between the semAPI software and the Bailey ICI. The ICI Network type is the network protocol between the ICI client(the PI interface in this case) and the semAPI software. If the interface is running in the same computer as the semAPI, then use “local” for the network type. The ICI physical properties describe the connection between the ICI module and the semAPI interface. The physical ICI is normally the port name connecting to the ICI module.

3. After configuration of the logical ICI, always test the communication to the ICI using the TALK90 program. TALK90 is an important communication trouble shooting tool. If TALK90 is having problem communicating to the ICI module, the PI interface cannot be expected to function properly. At least execute command 100(connect to ICI) and 19(restart ICI). Other commands to try are 43 (read time) and 84 (establish import point). Command 84 is on the second page of commands.

4. The semAPI installation procedure creates an user account called [ICI]. The [ICI] is created with quota sufficently large to run the semAPI applications. Since the PI interface is normally run under the [system] account, make sure the [system] account quotas are at least as large as those in the [ICI] account, specially the BYTLM, ENQLM, FILLM and PGFLQUO quotas.


Interface Installation on NTOSI recommends that interfaces be installed on API nodes instead of directly on the PI Server node. An 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 CPU time. 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 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 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. This typical scenario assumes that Bufserv is not enabled on the PI Server node. 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 blysem.exe and that the startup command file is called blysem.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 blysem1.exe and blysem1.bat for interface number 1, blysem2.exe and blysem2.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. OSI 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\blysem\

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


Interface InstallationNT-Intel Installation Disk File List

BLYSEM_V12.EXE PI Bailey semAPI Interface executable file for version 1.2, to be used with semAPI version 1.2

BLYSEM_V13.EXE PI Bailey semAPI Interface executable file for version 1.3, to be used with semAPI version 2.0 and greater

BLYSEM.BAT Startup command file

README.TXT Change to the interface from previous version

BASEMAPI.DOC This interface manual

At the time of the interface release 1.3, applications built with Bailey semAPI 2.0 and greater cannot work with semAPI 1.2. Therefore, we provide both versions 1.2 and 1.3 of the PI-Bailey semAPI interface on the distribution disk. Version 1.2 of the interface is compatible with Bailey semAPI 1.2. Version 1.3 of the interface is compatible with Bailey semAPI 2.0 and greater. Please find out the version of the semAPI installed on your system. Then copy the corresponding interface executable from the distribution disk to your computer as BLYSEM.EXE.

The installation can be done on either a PI home node (the node where the PI Data Archive resides) or on a PI API node (a node which communicates to the PI home node across a network). The installation procedure assumes the following:

1. You are installing the interface on the C drive. If you are installing the interface on a different drive than your C: drive, substitute the appropriate drive name in the procedure below.

2. Your floppy drive is the B drive. If your floppy drive is not your B: drive, substitute the appropriate drive name in the procedure below.

3. For a PI3 home node: The PI Firewall Database and the PI Proxy Database are 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. If the interface cannot write data to the PI Data Archive owing to permission problems, an error –10401 will occur. Note that /host=localhost:5450 in the blysem.bat file corresponds to the PI server on the same computer as the interface.

For a PI2 home node: The client must be allowed write access to the PI2 Data Archive. Read and write access is controlled in PI2 with the pisysdat:piserver.dat file.

Interface Installation ProcedureIn 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 c:\pipc\interfaces\blysem#\. Create the directory if necessary. where # should be replaced by a number between 1 and 99, inclusive. # should correspond to the interface number that is specified using the /id flag in the blsyem#.bat file. You should create one directory


PI Point Configuration

for each instance of the interface that he or she wishes to implement. For the semAPI, the number of simultaneous interfaces that can run is limited to the number ICI connecting to the computer.

Note: The interface does not enforce the blysem# naming convention for the executable file, the startup command file (batch file), or the directory. These can be given any legal name for the operating system. Also error messages in the pipc.log file will be prefixed by blysem #>, independent of the name of the executable file, batch file, and directory.

2. Insert the installation disk, and execute the following commands from an MSDOS prompt:copy b:\blysem.exe c:\PI\interfaces\blysem#\blysem#.execopy b:\blysem.bat c:\PI\interfaces\blysem#\blysem#.bat

As mentioned above, # should correspond to the interface number that is specified using the /id flag in the blysem#.bat file.

3. Modify the command-line arguments in your blysem#.bat file to customize your interface. For example, blysem1.exe /id=1 The command line must be on a single line and cannot exceed 1024 characters (1 kilobyte). This is a limitation set by the interface, not by the NT Operating system. The command-line arguments are discussed earlier in this manual..

4. Install Bailey semAPI software as per Bailey Document E96-827-1, installation section.

5. Define a logical ICI for each ICI module with the program ICICONF.

6. After configuring the logical ICI, always test the communication to the ICI using the TALK90 program. TALK90 is an important communication trouble shooting tool. If TALK90 is having problem communicating to the ICI module, the PI interface cannot be expected to function properly. At least execute command 100(connect to ICI) and 19(restart ICI). Other commands to try are 43 (read time) and 84 (establish import point). Command 84 is on the second page of commands.

7. After you have configure some test PI tags for the interface, you should test the interface operation by running the interface interactively on a MSDOS window. cd c:\PI\interfaces\blysem#blysem#.bat Note that you have to specify the bat file name rather than just blysem#. Otherwise, the executable will be run instead of the command batch file and no interface parameters will be passed to the program. As the interface begins to run, you should see several messages echoed to the screen. For example, the interface prints the version number at start up. Then as the interface completes an important stage in the operation, a message will be printed both to the screen and to the PI message log. Some of the important operation stage are: ICI restart, ICI point establishment and reading data from ICI. The interface can be stopped by typing CONTROL-C while the MsDos window is selected. You can use c:\PI\bin\apisnap.exe or Processbook to verify that data is being successfully transferred to the PI Data Archive.

Check whether there are any error messages to verify successful execution of the interface. Messages that are sent to the screen are also sent to the pipc.log file. Check the pipc.log file. Some messages are written to this file that are not echoed to

12

the screen when the interface is started up. Messages in the pipc.log file that pertain to the blysem interface will be prefixed by Blysem #>. The location of the pipc.log file is determined by the PIHOME entry in the pipc.ini file. The pipc.ini file is located in the Winnt directory. Usually, the pipc.log file will be placed in the c:\pipc\dat\ directory.

8. After you are satisfied with the operation of the interface, you can configure the full load of PI tags. Then stop the interactive session of the interface and configure the interface to run as a Windows NT service.

Installing the Interface as an NT ServiceThe interface should be configured to run as NT service so that the interface will be run automatically as the computer is booted up. This configuration will minimize loss of data collection during computer power trip.

The procedure for installing the Blysem interface as a service depends upon whether or not Bufserv is being used. Once the interface has been installed as a service, the procedure for starting, stopping, and removing the interface as a service is the same whether or not Bufserv is used. The purpose of the Bufserv utility is to continue to collect data from an interface in the event that the PI Data Archive is shut down for some reason. For example, if the Blysem interface is installed on an API node computer separated from the PI server and the PI Data Archive is shut down for an upgrade, the Bufserv utility on the API node will buffer the data in a file until the PI Data Archive is brought back online.

The procedure for installing the interface in conjunction with the Bufserv Utility assumes that the user has Bufserv 1.04 or higher because the procedure implicitly assumes that Bufserv will be installed as a service. The actual installation of the Bufserv Utility itself is not discussed. For these instructions, the user is referred to the PI-API Bufserv 1.x Release Notes. Also, the installation procedure below does not discuss the details related to shutdown events that the user should be aware of when the Bufserv Utility is used. Once again, refer to the PI-API Bufserv 1.x Release Notes for more information.

One can get help for installing the interface as a service at any time with the command:blysem.exe –help

Note: The –query flag that is described when help is invoked is not implemented at this time.

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

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

with Bufserv implemented

Manual service

blysem.exe –install –depend “tcpip bufserv”

Automatic service

blysem.exe –install –auto –depend “tcpip bufserv”

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

without Bufserv implemented


PI Point Configuration

Manual service

blysem.exe –install –depend tcpip

Automatic service

blysem.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 spin its wheels until it connects to PI.

Note: Interfaces are typically not installed as automatic services when the interface is installed on the PI Server node.

Check the Microsoft Windows NT services control panel to verify that the service was added successfully. One can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.

For more information on what DD_<device name> is, refer to the “Restrictions and Other Information” section.

Check the Microsoft Windows NT services control panel to verify that the service has been successfully added. One can use the services control panel at any time to change the blysem# service from an automatic service to a manual service or vice versa.

Once the blysem# service has been installed, the rest of the procedure is the same whether or not Bufserv has been implemented. The blysem# service can be started from the services control panel or by executing the following command from the blysem#\ directory:

blysem# -start

A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. If the service is successfully started, the interface will attempt to read the command-line arguments from the blysem#.bat file. For this to succeed, the root name (the part of the file name before the .exe and .bat extensions) of the batch file must be the same as the root name of the executable. Also, the batch file and the executable file must be in the same directory. If the interface is unable to read the command-line arguments or if the command-line arguments that the interface reads are invalid, the service will terminate with no error messages echoed to the screen. For this reason, the user MUST check the pipc.log file to verify that the interface is running correctly. In the pipc.log file, messages pertaining to the blysem interface will be prepended by Blysem #>. The location of the pipc.log file is determined by the PIHOME entry in the pipc.ini file. The pipc.ini file is located in the Winnt directory. Usually, the pipc.log file will reside in the c:\pipc\dat\ directory.

If the service was successfully started, the user can verify that the service is still running from the services control panel. If the service has been terminated, the reason for its termination will be given in the pipc.log file. If the service is still running, the user can use c:\PI\bin\apisnap.exe or Processbook to verify that data is being successfully transferred to the PI Data Archive.

The blysem# service can be stopped at any time by issuing the following command:

blysem# -stop

The blysem# service can be removed by

blysem# -remove

14

Interface Installation on VMSOne of the first issues that must be resolved is where the interface should be installed. Should the interface be installed on the PI Server node or on a remote PINet node? OSI recommends that the interface be installed on a PINet node. The primary function of the server node is to archive data and to service clients that request data. The PI Server should not need to compete with interfaces for CPU time. If the interface is installed on a PINet node, then PINet must be installed on that node before the interface is installed. Refer to the PI 2.1.x Installation and Upgrade Handbook for installation instructions.

If the interface runs on a PINet node, interfaces can communicate to either a PI 2 Server or a PI 3 Server. If the interface runs on a PI 2 Server, the interface can only communicate to the PI 2 Server.

On a PINet node, PISysExe, PISysMgr, and PISysDat are all aliases for the PINet directory, and PIBuild is an alias for the PINetBuild directory.

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that the interface executable is called blysem.exe, the startup command file for is called blysem.com, and the startup command file for detached processes is called blysemdetach.com.

Install the interface executable and command files in the PISysExe directory. If multiple instances of the interface must be run as interactive or detached processes, create multiply copies of the blysem.com file. For this purpose, it is customary to copy the blysem.com file to blysem1.com for instance 1, to blysem2.com for instance 2, and so on. The individual command files then need to be edited separately as appropriate.

Regardless of how many instances of the interface are running as interactive or detached processes, only one blysem.exe file and one blysemdetach.com file are needed.

When the interface is run as a detached process, interface-specific log files are created in the PISysExe directory. The interface log files are .out, .log, or .txt. The log files typically have names similar to blysem1.out, blysem2.out, and so on.

Note: The interface will always write error and information messages to the PISysMgr:PIMessLog.txt file.

Interface Installation ProcedureInterface files are installed and linked automatically as part of PI or PINet installations. If the interface has been automatically installed, skip to the “Starting and Stopping the Interface” section below. Sometimes, however, an interface needs to be installed or upgraded separately from the PI or PINet installation. This frequently needs to be done when a newer version of the interface is available than is distributed with the PI or PINet tape.

Interface files for VMS-based interfaces are now distributed on CD-ROM readable by NT or Windows machines. The appropriate files must be transferred over the network to the VMS node. The following files are distributed.


Distribution files

BLYSEM.DOC

Interface manual (Microsoft Word Document). The interface-specific installation procedure is in this manual.

BLYSEM_INSTALL.COM Installation command file for the Interface.

BLYSEM.BCK Saveset containing the interface files.

RELEASENOTES.TXT Release notes.

READBLOCK.README Readme file for REBLOCK.EXE.

REBLOCK.EXEThe interface backup saveset must be reblocked before the saveset can be unpacked. See the READBLOCK.README.

The following procedure is typical.

1. Transfer BLYSEM.BCK and REBLOCK.EXE to the VMS node by some sort of binary file transfer mechanism. For example, one could use binary ftp. Copy the files to a safe directory, one that will not be overwritten during an upgrade of PI or PINet.

2. Transfer BLYSEM_INSTALL.COM to the VMS node by some sort of ASCII file transfer mechanism. Copy the file to the safe directory.

3. Run REBLOCK.EXE on the BLYSEM.BCK file. Reblock corrects the block size of the BLYSEM.BCK file, which is altered during the binary file transfer. Binary file transfer does not affect the block size of the reblock executable itself. An example reblock session is given below.

$ run reblock

REBLOCK: Convert file to blocksize 32256

Filename ("\" to exit): blysem1.bck

Filename ("\" to exit): \

4. Install the interface files with the command:@blysem_install.comThe command file unpacks the backup saveset, copies the files to the appropriate directories, and links the interface executable. Files similar to the following are typically installed.

PIBuild directoryBLYSEM.OBJ Object file for the interface.

UNIINT.OBJ Object file for the interface

BLYSEM_LINK.COM Command procedure for re-linking the executable.


PISysExe directoryBLYSEM.EXE Interface executable.

BLYSEM1.COM Startup command file for interactive processes.

BLYSEMDETACH.COMStartup command file for detached processes (the command-line arguments are still defined in the BLYSEM1.COM file).


Testing Connection to ICIBailey created a connection test utility called Talk90. This utility was distributed with the runtime kit in the past but as of Bailey semAPI 2.0, it is no longer distributed in the runtime kit. It is still distributed with the supervisory control kit though.

The test utility looks like the following:

1-Establish Point 2-Establish Report 3-Output Miscellaneous4-Connect Point List 5-Disconnect Point List 6-Read Value List7-Read Status List 8-Read Exceptions 10-Output Value11-Output Status 12-Module Operation 13-Read Block14-Read Next Block 15-Read Default Block 16-Write Block17-Tune Block 18-Delete Block 19-ICI Restart20-Read Block Output 21-Read Misc Status List 22-Read Misc Stat Excep23-Disestablish Point 24-Read Excep Report Spec 26-Read Problem Report27-Demand Module Status 28-Regenerate Specs 29-Output General Msg33-Set ICI Status 34-Read Work Flag 35-Read Value Group36-Disconnect Point Group 37-Connect Point Group 38-Read Status Group39-Read Misc Status Group 40-Output Value Group 41-ICI Callup42-ICI Hangup 43-Read System Time/Date 44-ICI Online/Offline45-Output Misc Group 46-Read Ext Prob Report 47-Output Status Group100-Connect to ICI 101-Disconnect from ICI 102-ICI Management103-Quick Commands 104-Get Exceptions 105-ENet Commands106-Block I/O Commands 107-DBUS Commands 108-Firmware Commands109-Misc. Module Info 110-Decode Error Number777-Repeat Last Command 888-Next Page 999-Exit

Option : 100

Logical ICI: 1

Timeout is in seconds.

Timeout: 5

Valid Users:

0 = SHARED

1 = EXCLUSIVE

Type of User: 1

Tagnames: 0 = DO NOT RETURN TAGNAMES, 1 = RETURN TAGNAMES

Tagnames: 0

Option 100 should be used to make sure that at least a connection to the ICI can be made. If the connection is not successful, Bailey should be contacted.


Point SourceThe 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 B to identify points that belong to the Bailey semAPI interface. To implement this, one would set the PointSource attribute to B for every PI Point that is configured for the Random interface. Then, if one uses /ps=B on the startup-command line of the Random interface, the Random interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of B. 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=B and /ps=B 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 NodesThe 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 P is not defined in the PI 2 point source table, a point with a point source of P 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 1 0 0 1

Maximum 256 62500 31 65535 60


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.

For PI system version 3.X running on Unix or NT operating system, you do not have to define the point source prior to the configuration of the interface tags.

Also, you should add eight Digital states for Bailey Station status. For PI2 servers, the starting point is usually at 320 and the restrictions are that a)the starting point matches the setup of station status digital tags, b) the eight tags are contiguous, and c) the order of the digital status matches the description in section on Station Status (Bailey point type 6).

For PI3 servers, a digital state set should be created with the eight required digital states discussed eariler for Station Status (Bailey point type 6).


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. The default is B for the Bailey points. The user can specify the point source as a parameter to the interface.

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 NodesScaled 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, and string are supported on PI 3 Servers. For more information on the individual point types, see PI Data Archive for NT and UNIX.

Location1Location 1 is the interface number. Normally, the interface number should match the logical ICI Number used by the Bailey semAPI software; however, here the logical ICI Number is configured via the utility: [ICI.EXE]ICICONF.

Note: The Point Source and Location 1 parameters uniquely assign a given PI tag to a specific instance of the interface, a specific physical connection (or virtual in the case of TCP/IP connections), and a specific Bailey ICI.

Location2For inputs, Location 2 is the Infi90 Loop Number * 256 + the Infi90 PCU Number.


For outputs, Location 2 is the CIU index where the interface writes data. You must assign a unique CIU index for each output point. This index is used to compute the block number when configuring Infi90 PCU modules to read the output:

Block = index

Module = 2

PCU = node address of the ICI

For example, a PI tag with CIU index number 49 connecting to an ICI whose node address is 25 could be read from another node on the Bailey Loop with an analog input block (FC26) by:PCU-Module-Block = 25-2-49Index 2049 can be read as PCU-Module-Block of 25-2-2049.

Location3Location 3 is the Infi90 Module Number for inputs. For outputs, this should be 1.

Location4

Scan-Based InputsFor interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f flag in the section called “The Startup Command File”.

Trigger-Based Inputs, Unsolicited-Inputs, and Output PointsLocation 4 is the Infi90 Block Number for inputs.

For Station Blocks, use the block number of the Station block for all parameters for that block. A process variable, setpoint, mode, and control output would all have the same block number as far as the ICI is concerned. They would have different Infi90 point types (Location 5).

For outputs, Location 4 should be 1.

Location5Location 5 is the Bailey point type. This defines the kind of Bailey point sending or receiving the data. See list of available types in the Bailey Point Types section.

InstrumentTagThis attribute is not used for this interface.

ExcDescThis is the extended descriptor attribute. For a PI 2 Server, the extended descriptor is limited to 80 characters. For a PI 3 Server, the extended descriptor is limited to 80 characters if UniInt was not compiled to use the PI-SDK and to 1 Kilobyte if UniInt was compiled to use the PI-SDK.

Some Bailey function types provide multiple fields of information (e.g. RCM's, Device Drivers). It is possible to retrieve any subset or all of these fields of information into a


single PI tag or into multiple PI tags. The fields can be retrieved into a single PI tag in any order. The user specifies the field number and the extraction order by using the keyword “/BLY=” in the Extended Descriptor of the PI tag. Data retrieved in this manner are referred to as extended attributes in the rest of this manual. Here are a few examples:

Case 1: Single PI tag retrieving multiple fields from a DAANG blockTo get the fields in this specific order of Auto/Manual, Alarm Level, High Alarm, Low Alarm, High Deviation Alarm, Location 5 would be 29 and the following configuration would be added to the extended descriptor: /BLY=7, 4, 2, 3, 17 where the field definitions are as follows:

Field 7: Auto/Manual

Field 4: Alarm Level

Field 2: High Alarm

Field 3: Low Alarm

Field 17: High Deviation Alarm

The resultant value would be built from the values of data piece's field or fields. Additionally, the place value assigned to each data piece depends upon its position in the extended descriptor parameter list. Thus, assuming that the Alarm Level has a value of 3, and the High Deviation alarm is ON, and therefore the value sent to the PI tag would be as follows:

Data Field Field Length ExampleBailey Value Pos inPIVal PIVal

Auto/Manual 1 0 bit 0 0

AlarmLeve1 2 3 Bits 1, 2

6

High Alarm 1 0 bit 3 0

Low Alarm 1 0 bit 4 0

High DeviationAlarm

1 1 bit 5 32

Value for this PI Tag

38

The sum of the bit length for all the extracted fields can not exceed 15 for each tag. An error will be printed in the log file if more than that is specified. Specific data fields may be duplicated within a single tag.

Case 2: Multiple PI tags for this Bailey Block Address and Point TypeEach tag retrieves single or multiple fields from a DAANG block. The location parameters for each of these tags will be the same; however, they will have different extended descriptors. For example, tag 1 might have an extended descriptor /BLY=7,17, and tag 2 might have an extended descriptor, /BLY=4,2,3.

Note: Even though there are multiple PI tags, the interface will only retrieve the data once from Bailey and push the correct values into the correct tag.


Tag Configuration from Bailey Database

Bailey Point TypesAnalog data from Bailey should be defined in the PI system as a real point (point type R). If the Quality of the value is good, the floating point value from Bailey is stored in the PI System. If the passed Quality is bad, the digital code for Bad Input is stored for that tag. Other Bailey status information such as alarm fields are not used by the interface except in the case of extended attributes specified in the extended descriptor.

If a Bailey analog point is defined as a digital point in the PI system, the value is interpreted as the offset from the digital starting code of the point. Any value out of the range of 0 and the number of digital states minus one is stored as "Bad Input".

For most point types, the interface supports the retrieval of additional attributes from the exception reports. Thus, the user can define more than one PI tag pointing to the same Bailey block and extract different pieces of information from the same exception report.

For all Bailey data, the interface always checks the Quality of the Bailey value. If the Quality is bad, no further processing is done and the digital state Bad Input is put into the PI value. This Quality check also applies to PI tags retrieving extended attributes from the Bailey values.

Note: If the Bailey Quality is bad, the interface will not retrieve other fields or fields within the Bailey Exception Report.

The supported Bailey point types are listed in the following tables and further described below:

26

Supported Input Point Types (Bailey Data to PI)Bailey Point Type

Description Data Type

Bailey Function Code

OIS Type Name Extended Attribute

1 Process Variable

A note 1 Station No

2 Set Point Read

A note 1 Station No

3 Control Output Read

A note 1 Station No

4 Ratio Index Read

A 80, 23 Station No

5 Analog Read A 30 Analog Yes

6 Station Status

D note 1 Station Yes

7 Digital Read

D 45 Digital No

14 Module Status

D No

15 RCM Read D 62 RCM Yes

19 RMSC Read A 68 RMSC Yes

21 4-byte Analog Read

A Yes

29 DAANG A Yes

30 ASCII string

S No

51 MSDD D 129 Yes

52 DD D 123 Yes

53 RMC D Yes

54 DADIG D Yes

60 Text Selector

I No

70 Harmony Analog Input

A Yes

71 Harmony Analog Output

A Yes

72 Harmony Digital Input

D Yes

73 Harmony Digital Output

D Yes



Note: For Station points, the Bailey function code can be 80, 21, 22 or 23. You should use the same Bailey address for the PV, SP and CO of the station point.

The Harmony point types (70-73) are supported only for interface version 1.3 running on the Windows NT at the time of this manual’s release. The Bailey point types specifications for this interface are almost the same as those in the PI-BA-I90, the serial communication based interface. For those customers who will convert from the serial based Infi90 interface to the semAPI, NO changes to the location parameters are required except for Bailey point type 15. The serial based interface uses a point type of 15 to get data from RCM, MSDD, and DD point types. The semAPI interface uses 15 for RCM, 51 for MSDD, and 52 for DD point types.

Performance PointsFor UniInt-based interfaces, the extended descriptor is checked for the string “PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a performance point. See the section called “Performance Points.”

Trigger-Based InputsFor trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form:keyword=trigger_tag_name

where keyword is replaced by “event” or “trig” and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute.

An input 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 Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value.

Scan This is the UniInt use of Scan. If your interface works differently, you need to change this.

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.

28

Source TagSource Tag is used only for the output points. It is the PI tag from which the output points get the values to send to Infi90. For example, the source tag can be a performance equation calculation tag or a lab (manual input) tag.

When the source tag is not defined for an output point, the interface will get the output value from the output tag snapshot. In this case, the user is responsible for updating the value directly.

Note: The source tag should have the same PI point type as the output tag in order to assure that the correct value is sent to Bailey. However, it is not necessary that the tag be a real (integer or digital) type in order to send analog or digital data to Bailey, respectively.

OtherIn addition to the attributes listed above, the following PI point attributes (specified by PIDIFF keyword names) apply to Bailey Net/Infi90 points:

All Tags

Tag ARCHIVING COMPMIN

Descriptor COMPRESSING COMPMAX

Typicalvalue RES DISPLAYDIGITS

ENGUNITS Scan DISPLAYGROUP

POINTTYPE COMPDEV LONGNAME

Real tags only

ZERO SPAN PRECISION

Digital tags only

DIGSTARTCODE DIGNUMBER

Optional Fields (user description)

ExcDev ExcMin ExcMax

Extended Descriptor

Bailey Infi90 communication supports exception reporting. Exception reporting specification is configured in the Bailey modules. Since the default Bailey exception reporting parameters are adequate in data filtering, the interface has another option to bypass the exception reporting function on PI. This option “/sn” is configurable by the user in the interface startup command procedure. Specifying the “/sn” option requests the interface to ignore PI exception attributes and writes all the Bailey exceptions to PI snapshot. If the “/sn” option is removed in the startup command, then the interface will apply exception reporting based on the PI tags’ exception parameters on top of the Bailey exception report events.

The following PI point attributes do not apply to Bailey points:



Fields not used by Bailey semAPI interface

SquareRoot TotalCode Convers

ExpressStr EventStr FilterStr

SchedType Period Offset

GroupSize Clamp

For general descriptions of any point attributes, refer to the PI System Manual, volume 1, section DA. Some attributes for points are newly added to PI and are documented in the software release notes found in a file of the PI System: PIBuild:V2.0. For PI3 servers please refer to the PI-Data Archive for Windows NT and UNIX manual.

Shutdown

PI 2 Server NodesThe 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 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.

BufservIt 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 shutdown, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.

30

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.

Output Point Types (PI Data to Bailey)Bailey Point Type Description Data Type Extended Attributes12 Analog Report Analog No

13 Digital Report Digital No

22 4-byte Analog Report

Analog No

After the output tags are defined on PI, you can read the data from the ICI into any Bailey Node as Analog point or Digital Point. Use function code 26 to read point type 12 (Analog Report). Use function code 42 to read point type 13 (Digital Report). The address used in the function code 26 or 42 can be calculate from the location 2 parameter of the PI tag as described earlier in the manual under the location 2 point attribute.

Detail Description of the Point Types

Process Variable (Bailey point type 1)This is the process variable of a control Station block (Bailey function code 80, 21, 22 or 23). The block address should be that of the Station block. The alarm attributes for the station can be accessed through the extended attributes of the station status. See point type 6.

Setpoint Read (Bailey point type 2)This is the set point of a control Station block. See point type 1.

Control Output Read (Bailey point type 3)This is the control output of a control Station block. See point type 1.

Ratio Index Read (Bailey point type 4)This is the ratio index of a ratio control Station block. See point type 1.



Analog Read (Bailey point type 5)This get the value from an analog block (function code 30) on the Infi90 system.

The status of the analog value can be accessed through the following extended attributes:

Code Field length Description

1 1 Quality (q)

2 2 Limit Alarm (la)

3 2 Deviation Alarm (da)

4 1 Red Tagged Status(rt)

5 1 Point Tracking(pt)

6 1 Calibration(ccv)

Station Status (Bailey point type 6)By default, the interface extracts only the fields indicating the Station mode and combines them into an eight-state status, even though the Station status contains other information.

A PI tag for the Station Status is normally defined as a digital point (D) in the PI system. Codes 320-327 in the PI Digital States Table describe these states.

Note: This is an extension of the states utilized in prior versions of the PI/Bailey interface since the interpretation of the Bailey lock/unlock field has changed.)

When the point is defined, the starting digital number should be 320 and the digital number (number of states minus one) should be 7.

Different digital strings may be used to represent the station status. Use a starting digital pointer other than 320 when the point is defined. Then edit the digital state table on PI to put in the desired strings for describing the Station status at the new digital states.

For PI 3 server, use a digital set with 8 states to represent the station status. The eight states of the station status are:

Manual (unlocked)

Auto (unlocked)

Cascade (unlocked)

Digital Station Failure

Manual (locked)

Control station bypassed

Auto (locked)

Cascade (locked)

Note: This order is consistent with other versions of OSI Software Bailey interfaces.

Station status is processed one field at a time according to the following order. If any field is set, the evaluation is stopped at that field and the digital state is set.

32

Processing Order For Station Status

IF (QUALITY field is set) THEN Tag Digital State is BADINPUTSTAT (BAD QUALITY mode)

ELSE IF (BYPASS field is set) THENTag Digital State is #325 (BYPASS mode)

ELSE IF (DIGITAL STATION FAILURE field is set) THENTag Digital State is #323 (FAIL mode)

ELSE IF (CASCADE RATIO field is set) THENIF (MANUAL INTERLOCK field is set) THEN

Tag Digital State is #327 (locked CASCADE mode)ELSE

Tag Digital State is #322 (unlocked CASCADE mode)ELSE IF (AUTO MODE field is set) THEN

IF (MANUAL INTERLOCK field is set) THEN Tag Digital State is #326 (locked AUTO mode)

ELSE Tag Digital State is #321 (unlocked AUTO mode)

ELSE IF (MANUAL INTERLOCK field is set) THENTag Digital State is #324 (locked MANUAL mode)

ELSE Tag Digital State is #320 (unlocked MANUAL mode)

Also, you can access the following attributes of the Station Status through the use of the extended attributes:


1 1 Quality (q)



4 1 Red Tagged Status (rt)

5 1 Point Tracking (spt)

6 1 Station Bypass (byp)

7 1 Manual Interlock (mi)

8 1 Output Tracking (ot)

9 1 Digital Station Failure (dsf)

10 1 Computer OK (cok)

11 1 Computer Control Level (lev)

12 1 Cascade/Ratio Mode (crn)

13 1 Auto Mode (am)

Digital Read (Bailey point type 7)These points should be defined as type digital (D) in the PI system. If the Quality of the exception report is good, the interface extracts the value field of the report into the PI system. Otherwise, “Bad Input” is reported.



Analog Report (Bailey point type 12)This is one of the point types for writing from the PI system to Infi90. Infi90 real points are in the range -9.2E18 to 9.2E18. The output is set to BAD QUALITY and the value 0 is sent to Infi90 when the PI value is a digital state code (such as Shutdown or Over Range) and the source tag PI point type is R or I.

If the source PI point is defined as a digital point type, the interface will convert the absolute digital state to an offset to the digital starting code of the point and send the offset as an analog value to the Infi90.

Digital Report (Bailey point type 13)This is another point type for sending data from the PI system to Infi90. A source tag for the digital output can be either a real, integer, or digital point in the PI database. BAD QUALITY status is sent to Infi90 when the PI value is a digital state for real or integer source points. For a digital source point, a digital state out of the point’s range is considered BAD QUALITY.

For conversion of PI values to Infi90 values, a status of 1 is sent if the source PI value is not equal to 0. Otherwise 0 is sent. For PI source tag with point type D, the PI value is converted to a digital offset before sending to the Infi90.

Module Status (Bailey point type 14)A module status should be defined as a digital (D) point in the PI system. By default, the interface only extracts the module mode from the module status. The module mode can have four states, corresponding to digital codes 240-243 in the PI Digital States Table on VMS PI. When the point is defined, the starting digital number should be 240 and the digital number (number of states minus one) should be 3. Different digital strings may be used to represent the module status. Use a different starting digital pointer when the PI tag is defined. Then the digital state table should be edited so that it contains the desired strings for describing the module modes.

On the PI 3 server, use a digital set with 4 states to represent the module status. The four states of the Module status are:

Configure Failed Error ExecuteThe block number (Location 4) should be 0 for this point type.

RCM Read (Bailey point type 15)An RCM (function code 62) has many attributes that could be of interest to the user. By default, the interface extracts only the output field into the PI value for PI tags with location 5 set to 15. To get the other attributes, use the extended descriptor keyword /BLY=x,y,etc. followed by the attributes code as described below:

34


1 1 Quality (q)

2 1 Alarm (alm)

3 1 block tagged (tag)

4 1 output value (ov)

5 1 logic set input received (si)

6 1 set permissive input received (sp)

7 1 logic reset input received (ri)

8 1 override (or)

9 1 feedback (fb)

10 1 set command received (sc)

11 1 reset command received (rc)

RMSC Read (Bailey point type 19)The conversion is the same as the other analog point types. (RMSC is function code 68.) The status of the analog value can be accessed through the following extended attributes:


1 1 Quality (q)






4-byte Analog Read (Bailey point type 21)It is handled like other analog point types except that the precision is higher (about 7 significant digits) and the range is larger (-3.4E38 to 3.4E38). The status of the analog value can be accessed through the following extended attributes:




1 1 Quality (q)






4-byte Analog Report (Bailey point type 22)This is one of the point types for sending data from the PI system to Infi90. 4-byte analog reports are processed in the same way as the 3-byte analog report (type 12) except that the 4-byte analog points have greater range and higher precision. They are in the range of -3.4E38 to 3.4E38.

DAANG (Bailey point type 29)The data acquisition analog block has many attributes that may be of interest to the user. By default, the interface extracts the analog output value of the block into the PI value for PI tags with location 5 set to 29. To get the other attributes, use the extended descriptor keyword /BLY=x,y,etc. followed by the attributes code as described below:

36

Code Field Length Description

1 1 Quality (q)

2 1 high alarm (ha)

3 1 low alarm (la)

4 2 alarm level (al)

5 1 (x)

6 1 block tagged (tag1)

7 1 auto/manual (am1)

8 1 constant value 1 (constant_1)

9 1 block tagged (tag3)

10 1 hardware fault/bad input (fq3)

11 1 out of range (or)

12 1 limited (lim)


14 1 calculated value (cal3)

15 1 Quality override (qo)

16 1 off scan (ss)

17 1 high deviation alarm (hda)

18 1 low deviation alarm (lda)

19 1 high rate (hr)

20 1 low rate (lr)

21 1 variable alarms (va)

22 1 alarm suppression indication (asi)

23 1 in re-alarm (ra)

24 1 permit input select (pis)

25 1 constraints enabled (ce)

26 1 calculated value (cal5)

27 1 hardware fault/bad input (fq5)

28 1 multilevel alarming (ma)


String (Bailey point type 30)For the VMS version of the interface, the interface will obtain the ASCII string data from the Bailey system and place it in the PI Event Logger with the group and type specified by the startup parameters /evtg and /evt. (If they are not specified, default group and type 4 and 11 will be used, respectively.)

The ascii string is prefixed by the Time stamp, PI Tag Name and a quality flag (0 for good quality and 1 for bad quality) before it is sent to the Event Logger. Also, the interface will send a value of 0.0 or the digital status “Bad Input” to the archive for the PI



Tag, depending on whether the bailey string is good quality. If compression for the PI tag is turned off, this can be used as a way to record when PI receives a new ascii string.

For the NT version of the interface talking to a PI 3 server, the user has the option of putting the string data to string tags or into the Event Logger. If the PI tag is of point type String, then the string data from Bailey will be put into the string tag directly, else the string data will be put into the PI Event logger. If the PI tag is configured as string type, the Bailey string is put into the PI tag without the prefix of time stamp, tag name and quality flag like the data going into the Event Logger. If the Bailey string has bad quality, the digital string “bad input” will be written to the PI string tag.

Since Bailey will transmit exception reports (on a rate) for the ascii data even if it doesn't change, the interface provides a rudimentary filtering function. The interface will send the data to the Event Logger or PI string tags only if the ascii string or status of the related PI tag have changed.

Note: The VMS PINet nodes older than version 2.11 do NOT support event logger write to the home node.

MSDD (Bailey point type 51)The multi-state device driver (Bailey function code 129) has many attributes that could be of interest to the user. By default, the interface extracts only the output field into the PI value for PI tags with location 5 set to 51. To get the other attributes, use the extended descriptor keyword /BLY=x,y,etc. followed by the attributes code as described below:


1 1 Quality (q)

2 1 Alarm (alm)

3 1 status override value (sor)

4 1 control override value (cor)

5 1 operation mode (m)


7 1 command output value (co)

8 1 feedback state 1 (fb1)




12 2 good state table (gs)

13 2 requested state table (rs)

DD (Bailey point type 52)The device driver (Bailey function code 123) has many attributes that could be of interest to the user. By default, the interface extracts only the output field into the PI value for PI tags with location 5 set to 52. To get the other attributes, use the extended descriptor keyword /BLY=x,y,etc. followed by the attributes code as described below:

38


1 1 Quality (q)

2 1 Alarm (alm)





7 1 feedback status (fs)

8 1 override value (or)

9 2 operation mode (mode)

RMC (Bailey point type 53)The remote motor control block has many attributes that could be of interest to the user. By default, the interface extracts only the output field into the PI value for PI tags with location 5 set to 53. To get the other attributes, use the extended descriptor keyword /BLY=x,y,etc. followed by the attributes code as described below:


1 1 Quality (q)

2 1 Alarm (alm)





7 1 bad start (bs)

8 1 fault (f)

9 1 start permissive state 1 (sp1)

10 1 start permissive state 2 (sp2)

11 4 error code for bad start (rmc_err)

DADIG (Bailey point type 54)The data acquisition digital block has many attributes that could be of interest to the user. By default, the interface extracts only the output field into the PI value for PI tags with location 5 set to 54. To get the other attributes, use the extended descriptor keyword /BLY=x,y,etc. followed by the attributes code as described below:




1 1 Quality (q)

2 1 Alarm (alm)

3 1 time in alarm re-alarm (field is toggled) (realm)

4 1 alarms suppressed (sup)

5 1 output suspect (os)

6 1 point off scan (nr)



9 1 extended status transition latched (lat)

10 1 Quality override (qo)

11 1 set permissive (sp)

12 1 primary input selected (pi)

13 1 alternate input selected (ai)

Text Selector (Bailey point type 60)The text selector returns a message code number to PI. User can define the PI tag as digital point and put the corresponding message text in the digital state table or define the PI tag as integer point.

Harmony Analog Input (Bailey point type 70)This point type is supported only through Bailey semAPI version 2.0 and greater, which necessitates PI-semAPI interface version 1.3 or greater. The conversion is the same as the other analog point types. The status of the analog value can be accessed through the following extended attributes:

40


1 1 Quality (uc_q)

2 1 high Alarm (uc_h_alrm)

3 1 low Alarm (uc_l_alrm)

4 1 Status errors are inhibited (uc_sei)

5 1 Simulated (uc_sim)

6 1 Overridden value (uc_oe)

7 1 Value is suspect (uc_susp)

8 1 Propagated quality (uc_pq)

9 1 Extended range (uc_er)

10 1 Configuration error exists (uc_cerr)

11 2 Channel condition (uc_range)

12 1 Readback status (uc_rbst)

13 1 Reference status (uc_ref)

14 1 Calibration status (uc_cal)

Harmony Analog Output (Bailey point type 71)This point type is supported only through Bailey semAPI version 2.0 and greater, which necessitates PI-semAPI interface version 1.3 or greater. The conversion is the same as the other analog point types. The status of the analog value can be accessed through the following extended attributes:




1 1 Quality (uc_q)

2 1 high Alarm (uc_h_alrm)

3 1 low Alarm (uc_l_alrm)



6 1 Overridden value (uc_oe)



9 1 Extended range (uc_er)




13 1 Reference status (uc_ref)

14 1 Calibration status (uc_cal)

Harmony Digital Input (Bailey point type 72)This point type is supported only through Bailey semAPI version 2.0 and greater, which necessitates PI-semAPI interface version 1.3 or greater. These points should be defined as type digital (D) or integer (I) in the PI system. If the Quality of the exception report is good, the interface extracts the value field of the report into the PI system. Otherwise, “Bad Input” is reported. Also, the rest of the status attribute can be accessed through the following extended attributes:


1 1 Quality (uc_q)

2 1 Alarm (uc_alm)



5 1 Overridden value (uc_ovvl)






11 1 value (uc_val)

42

Harmony Digital Output (Bailey point type 73)This point type is supported only through Bailey semAPI version 2.0 and greater, which necessitates PI-semAPI interface version 1.3 or greater. These points should be defined as type digital (D) or integer (I) in the PI system. If the Quality of the exception report is good, the interface extracts the value field of the report into the PI system. Otherwise, “Bad Input” is reported. Also, the rest of the status attribute can be accessed through the following extended attributes:


1 1 Quality (uc_q)

2 1 Alarm (uc_alm)



5 1 Overridden value (uc_ovvl)






11 1 value (uc_val)

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

44

Tag Configuration from Bailey DatabaseThe Bailey MCS Operator Console configuration contains much of the information needed for the PI Point database. The MCS can be configured from DBASE files on a personal computer. It is possible to create text files for PIDIFF or PIConfig from the DBASE files created for the MCS.

Start by entering DBASE and creating a new database with several of the same fields as the MCSTAG.dbf file. The following PI attributes can be extracted.

PI Attributes

Tag The field name in the MCS database is TAGNAME. The MCS field is 14 characters long so some conversion may be necessary.

Descriptor The field name in the MCS database is TAGDESC. The MCS field is 32 characters long. The PI Descriptor is only 26 characters long.

EngUnits The field name in the MCS database is EUDESC. Note The Engineering Unit strings must be configured in PI before configuring points that will use them.

Zero The field name in the MCS database is VAL0.

Span The field name in the MCS database is SPAN.

DigStCode The MCS database field ZEROSTATE points to a string in the MCS state table.

PI2 Server: The ZeroState could be replaced with PI digital state code numbers. Note Most Infi90 digital points represent two state devices, thus the DigNumber for these points in PI would be 1. The PI digital state table can be configured to have similar strings. These digital state strings should be configured before building PI points.

PI3 Server: PI3 requires that a unique digital state set be defined for each unique set of digital states. The digital state set should be defined before building PI points.

Location2 This is 256 times the MCS field LOOP plus the MCS field PCU.

Location3 This is the MCS field MOD.

Location4 This is the MCS field BLOCK.

Location5 The field name in the MCS database is TAGTYPE. The MCS field has string descriptions of the type (e.g., ANALOG, RCM) rather than the number of the CIU point type. These can be converted with DBASE or a text editor.


Performance Point ConfigurationOne can configure performance points to monitor the amount of time in seconds that it takes an interface to complete a scan for a particular scan class. The closer the scan time is to 0 seconds, the better the performance. The scan time is recorded to millisecond resolution

Performance point configuration is the same on all operating system platforms. Performance points are configured as follows.

1. Set the extended descriptor to:PERFORMANCE_POINTor to:PERFORMANCE_POINT=interface_idwhere interface_id corresponds to the identifier that is specified with the /id flag on the startup command line of the interface. The character string PERFORMANCE_POINT is case insenstive. The interface_id does not need to be specified if there is only one copy of an interface that is associated with a particular point source.

2. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the /f flag for a description of scan classes.

3. Set the PointSource attribute to correspond to the /ps flag on the startup command line of the interface.

4. Set the PointType attribute to float32.


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. For Open VMS nodes, the rate (events/minute) can be monitored with the PISysExe:IOMonitor.exe program or with another client program such as Process Book. The IOMonitor program is discussed on page DA-71 of PI System Manual I.

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

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

NT Nodes1. 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:

blysem001, x

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

Open VMS NodesI/O Rates are discussed on page DA-59 of PI System Manual I.

To implement an I/O Rate tag, perform the following steps:

1. Add a line to the PISysDat:IORates.dat file of the form:blysem001, xwhere blysem, is an abbreviation for the interface and x corresponds to the event counter specified by the first instance of the /ec=x flag in the startup command file of the interface. x can be any number between 1 and 34 or between 51 and 200, inclusive. However, it is best to use an event counter, x, that is not equal to 1 because 1 is the default event counter for UniInt-based interfaces. The event counter, /ec=x, should be unique for each copy of the interface.

Note: The PISysDat:IORates.dat file must be edited on the node where the interface is running. That is, if the interface is running on a PINet node, then the PISysDat:IORates.dat file on the PINet node must be edited, not the PISysDat:IORates.dat file on the home node.

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

3. Stop and start the I/O Rates process with the following commands so that the changes take effect:@PISysExe:stop iorates@PISysExe:iorates.com

Startup Command FileThe Bailey SemAPI interface on Windows has an ICU Control that will aid in configuring the BASEMAPI interface startup command file:


The BASEMAPI control for PI-ICU has six sections. A yellow text box indicates that an invalid value has been entered, or that a required value has not been entered.

Behavior

Enable exception screeningThis option controls the exception screening behavior of the ICI module. With exception screening option enabled, the INFI90 sends only deviation exceptions, no maximum time exceptions. Though this feature will significantly reduce the communications traffic, it can prevent the PI system from reconstructing the data between two exception reports accurately.For example: if a value changes slowly, then Bailey would not send the change until the total change exceeded the deviation limit. Therefore, one cannot distinguish a step change from a linear change. Hence, this option is set to 0 by default. The EF option is primarily used for system with mostly digital or discrete data. The command line equaivalent is /ef.

Enable outputsEnable outputs from PI to Bailey. The command line equaivalent is /of.

Communication timeoutThis option specifies the ICI module watch dog timer. If the interface stops communicating with the ICI module for a period longer than the specified watch dog timer, the ICI module will go off-line, setting all the output points (PI to Bailey) bad quality. For systems using PI values in the Bailey control loops, the watch dog timer will prevent old value from being used in the control loop. Also, you should not set the watchdog timer to 0 if the interface is set up as fail over primary interface. Otherwise, the secondary interface will not pick up data collection when the primary interface stops communicating with the ICI module. See the FailOver Operation section for details. The command line equivalent is /to.

Bailey logical ICI numberBailey logical ICI number, set to interface ID number if not defined. The command line equivalent is /ici=x.


Buffering

Time syncThis option controls the time synchronization behavior between Bailey and PI systems. Note that the interface cannot change the PI system time if the interface is running on a VMS PINET node or when the interface is running on Windows NT. Also, if the interface is linked to a Data Acquisition version of semAPI, the interface cannot set the time on the Bailey System. When you specify VMS as the time master, additional configuration is required. The time master of the loop is determined by the time accuracy factor on each node. Hence, you need to set the time accuracy to 15 or greater on the CIU module through the CIU utilities by connecting a terminal to the CIU termination unit. See the CIU manual for details on how to use the CIU utilities.

/ts=0 disables timesync

/ts=1 sets PI time as the master time

/ts=-1 sets Bailey time as the master time

Data Retrieval

Seconds between get exceptionsDelay in seconds between bailey get exceptions. The default is one second. The command line equivalent is /dl=x.

Maximum exceptions per iterationMaximum number of exceptions per iteration. The default is 2500. The command line equivalent is /me=x.

Maximum points for interfaceThe maximum number of points for this interface. The default is 30000. The command line equivalent is /mp=x.

FailoverA detailed discussion of failover can be found later in this manual in a section titled “Failover”.

Enable failoverThis option controls the fail-over mode of the interface. Specify /FM=1 for the primary interface and /FM=2 for the secondary interface. Also, for the secondary interface, you need to supply the PCU number of the ICI mode communicating to the primary interface. The details of the fail-over mechanism are described in FailOver Operation section. The command line equivalent is /fm=x.

Primary PCU addressThe failover primary PCU address is required only if failover is used, and this is the secondary interface. The command line equivalent is /fp=x.

Debug

Connect to ICI with shared accessEven though the Bailey semAPI is designed to handle multiple user clients, PI-Bailey semAPI interface expects exclusive control of the ICI device, specially the configuration of the point table on the ICI. If the interface is started in trouble-shooting mode (/ICDB),

52

the user can simultaneously communicate with the ICI via Bailey's TALK90 program. This can be a useful debugging tool for determining the current condition of the ICI. During normal operation, this option should not be checked. The command line equivalent is /icdb.

Data Handling

Analog filter limit and Digital codeEnables analog filter parameters. /FV specifies a limit. If the analog values from Bailey are greater than this value, they will be replaced by a digital state code (specified by /FS) by the interface. The FV parameter has to be greater than 1000 to be considered valid by the interface. If /FV is not specific, no analog filter checking will be performed by the interface (even if /FS is specified). If /FS is omitted, the interface will default to NODATA(code 248) as the digital state to substitute the analog value over the filter limit. The Analog filter check is supported starting in version 1.3.1 of the interface. The command line equivalent is /fv=x for the Analog filter limit and /fs=x for the Digital code.

Enable range checkingRange Checking enabled at interface level. All analog values above (Zero + Span) will be replaced with digital state OverRange. All analog values below Zero will be replaced with digital state UnderRange. The command line equivalent is /rc.

Additional ArgumentsThe Additional Arguments section is provided for any flags that may have been required in the future.

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

Notes for NTFor NT, command file names have a .bat extension. The NT continuation character (^) allows one to use 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.

Notes for VMSFor VMS, command file names have a .com extension. The VMS continuation character (-) allows one to use multiple lines in the command file. However, the maximum number of characters in a single or multi-line command is 256 characters. That is, adding continuation characters may make the command file easier to read, but they do not extend the 256-character limitation. The 256-character limitation can be overcome by putting the arguments in a separate argument file. See the /argfile command-line parameter in The UniInt End User Document for details.

Note: The UniInt End User Document includes details about other command line parameters which may be useful.


Buffering

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

UniInt always uses the /id flag in the fashion described above. This interface also uses the /id flag to identify a particular interface copy number that corresponds to an integer value that is assigned to one of the Location code point attributes, most frequently Location1. For this interface, one should use only numeric characters in the identifier. For example,

/id=1

/host=host:port

optional for NT and UNIX

Not implemented for VMS interface nodes

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 an API node, the domain name of the PI 3 home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host flags would be:

54

/host=marvin /host=marvin:5450 /host=206.79.198.30/host=206.79.198.30:5450

/stopstator/stopatat=digstate

default:/stopstat=shutdown

optional

If the /stopstat flag is present on the startup command line, then the digital state I/O Timeout will be written to each PI Point when the interface is stopped.

If /stopstat=digstate is present on the command line, then the digital state, digstate, will be written to each PI Point when the interface is stopped. For a PI 3 Server, digstate must be in the system digital state table. For a PI 2 Server, where there is only one digital state table available, digstate must simply be somewhere in the table. UniInt uses the first occurrence in the table.

If neither /stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down.

Examples:/stopstat=shutdown

The entire parameter is enclosed within double quotes when there is a space in digstate.

There is some debate as to the recommended usage of the /stopstat parameter. To many, the default digital state, I/O Timeout, implies that there is some communication problem with the interface, not that the interface has stopped. There is also a problem with /stopstat=shutdown because shutdown is written to PI Tags when the PI Server is shut down. This makes it impossible to tell whether the shutdown digital state is from the interface shutting down or from PI shutting down. Unfortunately, there is no digital state that clearly indicates that an interface has been shut down. One solution is for the user to add an appropriate digital state, such as Inf Down, to the PI 3 system digital state table or the PI 2 digital state table. Editing the PI 2 digital state table is straightforward. Editing the PI 3 digital state table must be done using the piconfig utility. The piconfig utility is described in PI Data Archive for NT and UNIX.


Buffering

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

For interfaces that run on NT nodes, subsequent instances of the /ec flag may be used by specific interfaces to keep track of various input or output operations. One must consult the interface-specific documentation to see whether subsequent instances of the /ec flag have any effect. Subsequent instances of the /ec flag can be of the form /ec*, where * is any ASCII character sequence. For example, /ecinput=10, /ecoutput=11, and /ec=12 are legitimate choices for the second, third, and fourth event counter strings.

/sio

optional

If interface doesn’t have outputs, this flag should be deleted.

The /sio flag stands for “suppress initial outputs.” The flag applies only for interfaces that support outputs. If the /sio flag is not specified, the interface will behave in the following manner.

When the interface is started, the interface determines the current Snapshot value of each output tag. Next, the interface writes this value to each output tag. In addition, whenever an individual output tag is edited while the interface is running, the interface will write the current Snapshot value to the edited output tag.

This behavior is suppressed if the /sio flag is specified on the command line. That is, outputs will not be written when the interface starts or when an output tag is edited. In other words, when the /sio flag is specified, outputs will only be written when they are explicitly triggered.

56

/q

optional for NT and UNIX

not implemented for interfaces on VMS nodes

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

The maximum queue size is 255 bytes for a PI 3 Server and 36 bytes for a PI 2 Server. For example, if the interface is running on a UNIX node and is communicating to a PI 2 Server, then the maximum queue size is 36. The queue is flushed between scans if it is not filled.

When the /q flag is specified in non-extended API mode, the PI-API sends integer values as 16-bit integers instead of 32-bit integers. Therefore, integer points will be limited to values between 0 and 32767. Values higher than 32767 need to be sent to floating-point PI tags.

/FM=0

optional

This option controls the fail-over mode of the interface. Specify /FM=1 for the primary interface and /FM=2 for the secondary interface. Also, for the secondary interface, you need to supply the PCU number of the ICI mode communicating to the primary interface. The details of the fail-over mechanism are described in FailOver Operation section.

/TO=90

optional

This option specifies the ICI module watch dog timer. If the interface stops communicating with the ICI module for a period longer than the specified watch dog timer, the ICI module will go off-line, setting all the output points (PI to Bailey) bad quality. For systems using PI values in the Bailey control loops, the watch dog timer will prevent old value from being used in the control loop. Also, you should not set the watchdog timer to 0 if the interface is set up as fail over primary interface. Otherwise, the secondary interface will not pick up data collection when the primary interface stops communicating with the ICI module. See the FailOver Operation section for details.


Buffering

/EF =0

optional

This option controls the exception screening behavior of the ICI module. With exception screening option enabled, the INFI90 sends only deviation exceptions, no maximum time exceptions. Though this feature will significantly reduce the communications traffic, it can prevent the PI system from reconstructing the data between two exception reports accurately.For example: if a value changes slowly, then Bailey would not send the change until the total change exceeded the deviation limit. Therefore, one cannot distinguish a step change from a linear change. Hence, this option is set to 0 by default. The EF option is primarily used for system with mostly digital or discrete data.

/TS=0

optional

This option controls the time synchronization behavior between Bailey and PI systems. Note that the interface cannot change the PI system time if the interface is running on a VMS PINET node or when the interface is running on Windows NT. Also, if the interface is linked to a Data Acquisition version of semAPI, the interface cannot set the time on the Bailey System. When you specify VMS as the time master, additional configuration is required. The time master of the loop is determined by the time accuracy factor on each node. Hence, you need to set the time accuracy to 15 or greater on the CIU module through the CIU utilities by connecting a terminal to the CIU termination unit. See the CIU manual for details on how to use the CIU utilities.

/ts=0 disables timesync

/ts=1 sets PI time as the master time

/ts=-1 sets Bailey time as the master time

/EVG= and /EVT= optional

Define the Event Logger group and type to be used when ascii data (type 30) is sent to the Event Logger.

/FV= and /FS

optional

Analog filter parameters. /FV specific a limit. If the analog values from Bailey are greater than this value, they will be replaced by a digital state code (specified by /FS) by the interface. The FV parameter has to be greater than 1000 to be considered valid by the interface. If /FV is not specific, no analog filter checking will be performed by the interface (even if /FS is specified). If /FS is omitted, the interface will default to NODATA(code 248) as the digital state to substitute the analog value over the filter limit. The Analog filter check is supported starting in version 1.3.1 of the interface.

58

/RC

optional

Range Checking enabled at interface level. All analog values above (Zero + Span) will be replaced with digital state OverRange. All analog values below Zero will be replaced with digital state UnderRange.

The interface takes a number of optional parameters to control its operation. You can specify these parameters in the interface command file blysem#.bat. The complete list of parameters as seen in the blysem.bat in the distribution disk is provided below:

The following is an example file:rem BLYSEM.bat 11/11/98 OSIsoftware Inc.rem command file to start the PI/Bailey semAPI Interfacerem rem Parameters:rem Universal Interface parameters (in any order )rem /host=X ! specifies host name of PIserver if it is not the rem default server defined in pilogin.ini.rem /id=X ! interface ID number, Required rem /ps=X ! point source for interface. Requiredrem /ec=X ! IO rate counterrem /sn ! Overrides exception reporting to use snapshottingremrem Interface Specific parameters (in any order )rem /in=X ! Interface number, should match location1 of PI tags,rem if not defined, generated from interface ID string.rem /ici=X ! Bailey logical ICI number, set to interface ID number rem if not definerem /icdb=X ! interface specific debug level, 0 [def]rem /to=X ! ICI timeout (ICI goes offline after not receiving rem messages from interface for the timeout period), rem 90 [def], 0 for no timeout. Maximun timeout is rem 240 second. Also, interface will restart itself if rem getting consecutive errors exceeding the timeout rem period.rem /fm=X ! failover mode, 0[def] for no failover, 1 for primary, rem 2 for secondaryrem /fp=X ! failover Primary PCU address. Required for secondaryrem /dl=X ! delay [sec] between bailey get exceptions: rem default one secondrem /me=X ! Max exceptions per iteration: default is 2500 [def]rem /mp=X ! Max number of points for this interface, 30000 [def]rem /ef=X ! Exception screening 0=none [def], else 1rem /of=X ! Outputs to Bailey allowed if 1, else 0 [default]rem /ts=X ! Time sync [0] default no timesync; 1 -> pi master, rem -1 -> bailey masterrem /EVG=X ! Event logger group number for ASCII eventrem /EVT=X ! event logger type number for ASCII eventremrem Version 1.3.1 new parametersrem /fv=X ! Analog filter limit (mininum 1000)rem /fs=X ! Analog filter digital status code(positive or negative)rem /rc ! Range checking at interface level


Buffering

Blysem.exe /ps=B /sn /id=1 /of=1

60

Interface Node Clock

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

VMSBy default, the system time of a PINet node is synchronized with the system time on the PI Server node once every hour by the PINETSYNC program. The behavior of the PINETSYNC program can be altered by editing the PINet:PINetSync1.com file. The synchronization interval can be changed, a time offset between the PINet node and the server node can be applied, and/or time synchronization can be disabled. The command-line parameters for implementing these changes are described in the PINet:PINetSync1.com file itself.


Security

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

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 2 or PI 3 Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. See the section Error and Informational Messages for additional information on error messaging.

VMS If the interface runs on a PINet node and communicates to a PI 3 Server, make sure that the PI Firewall Database and the PI Proxy Database are configured so that the PINet node is allowed to write data to the Archive. For more information, see “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive manual.

If the interface runs on a PINet node and communicates to a PI 2 Server, make sure that the PINet node has read/write permission to the PI 2 Archive by checking the configuration 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 Server.

If the interface cannot write data to a PI 2 or PI3 Server owing to permission problems, error –10401 will be written to the PISysMgr:PIMesslog.txt file.


Starting / Stopping the Interface on NTThis 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:blysem.exe –start

A 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 “Error and Informational Messages” for additional information.

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:blysem.exe –stopThe service can be removed by:blysem.exe –remove


Starting / Stopping the Interface on VMS This section describes starting and stopping the interface as a detached process. See the UniInt End User Document to run the interface interactively.

Starting a Detached ProcessThe interface is started as a detached process with the blysemdetach.com command file. Typically, the blysemdetach.com file does not need to be edited, because the command-line parameters are edited in the associated blysem#.com file. However, in some cases it may be necessary to edit the blysemdetach.com file to increase quotas such as the page file size. Detached processes continue running after the user who started the process logs off.

The following is an example of an blysemdetach.com file.

$! BLYSEMDetach.COM$! Generic command file to start the Bailey PI$! interface program$! as detached process$! Copyright$! DBSudikoff, Informatics Controls Inc. 1992-1996$! $! Modifications:$! 950716 DBS File Name Change$! 960305 DBS Add Parameter for Interface number$! 960628 LFM use system as the uicreq instead of osi$! 960813 LFM check system arch to determine pagefile requirement$! 960813 LFM Last Modification$! ---------------------------------------------------$! ---------------------------------------------------$!$ privreq = "SYSPRV,SETPRV,CMKRNL,CMEXEC,SYSNAM,GRPNAM,DETACH,"$ privreq = privreq + "PRMCEB,PRMMBX,PSWAPM,ALTPRI,TMPMBX,WORLD,OPER,"$ privreq = privreq + "EXQUOTA,NETMBX,PRMGBL,SYSGBL,PFNMAP,SHMEM,SYSLCK,"$ privreq = privreq + "SHARE,GRPPRV,LOG_IO,READALL"$ uicreq = "SYSTEM"$ pagereq = 60000$ if (F$GetSYI("ARCH_NAME") .eqs. "Alpha") then pagereq = 120000$!$!$ privsav = f$setprv( privreq )$ uicsav = f$user( )$ ON CONTROL_Y then goto restore$!$!$! 1 - interface number (1-99)$ if (P1 .eqs. "") then goto BadParameter


$!$ If F$Search("PISysEXE:BLYSEM_I'P1'.out") .nes. "" then - Purge/keep=3 PISysEXE:BLYSEM_I'P1'.out$!$! On Some PINet nodes:$! The Run/Detach command might not function as written. You can change it$! to /PageFile=50000 or /PageFile=100000/Authorize$! $ Run/Detach/UIC=['uicreq']/Proc="BLYSEM_I''P1'" - /Input=PISysEXE:BLYSEM_I'P1'.com/Output=PISysEXE:BLYSEM_I'P1'.out - /Working_Set=4096/Maximum_Work=12000/Extent=8192/PageFile='pagereq' - /Buffer=20480 - Sys$System:LogInOut$ goto restore$BadParameter:$ write sys$output "The Interface Number Must Be Passed as a Parameter"$restore:$! set uic 'uicsav'$ discard = f$setprv( privsav )$ EXIT$

Assuming that the example command file is used to start the interface, the following command will start instance 1 of the interface as a detached process:@PISysExe:blysemdetach 1The name of the process will be “PI-BLYSEM-1” as defined by the /proc flag to the run command in the above command file

The example blysemdetach.com command file performs the following tasks in the order listed.

1. The command file checks whether the interface number is passed as a command-line parameter to blysemdetach.com. If it is not passed, the command file will terminate with the error message:The Interface # must be passed.

2. Blysemdetach.com searches for the existence of the PISysExe:blysem1.com file, which is the file where the command-line parameters for the interface are set. If the file does not exist, the command file will terminate with the error message:Blysem1.com does not exist.

3. Blysemdetach.com searches for the existence of the PISysExe:blysem1.out interface-specific log file. If the file exits, the command file executes the purge command to eliminate all but the last three versions of this file.

4. The PI-BLYSEM-1 process is started with the run command. Several actions are performed by the run command:

The name of the process is set to PI-BLYSEM-1 by the /proc flag.

The UIC of the process is set to the system account by the /uic flag.

The priority of the process is set to 4 by the /priority flag.

The input command file for the process is set to PISysExe:blysem1.com by the /input flag.


The standard output from the interface is redirected to the PISysExe:blysem1.out file by the /output flag.

The remaining parameters, /working_set, /maximum_work, /extent, /pagefile, and /buffer, are used to adjust the resources that are available to the interface.

StoppingTo stop the interface, issue the following command:

@PISysExe:stop PI-BLYSEM-1

Where 1 is the instance number of the process.


BufferingFor complete information on buffering, please refer to the Uniint End User.

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. 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:\Program Files\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.

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 Default server for UNIX. 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)

A piclient.ini file might look like:[PISERVER]PIHOMENODE=MYNTSERVER; DSTMISMATCH=0


[TCP/IP]PORT=5450[APIBUFFER]BUFFERING=1MAXFILESIZE=100000; the PI-API connection routines have 1 minute default timeoutRETRYRATE=600

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. The [PISERVER] and [TCP/IP] sections are used to define the default connection. On Windows NT the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. Comment lines begin with a semicolon.


Restrictions and Other Information Even though the Bailey semAPI is designed to handle multiple user clients, PI-

Bailey semAPI interface expects exclusive control of the ICI device, specially the configuration of the point table on the ICI. If the interface is started in trouble-shooting mode (/ICDB), the user can simultaneously communicate with the ICI via Bailey's TALK90 program. This can be a useful debugging tool for determining the current condition of the ICI.

Applications developed with the semAPI version 2.0 and greater are not compatible with older versions of the semAPI. Hence, PI-Bailey semAPI interface version 1.2 can only work with semAPI version 1.2 while interface version 1.3 and greater can only work with semAPI version 2.0 and greater.

We have noticed that the interface someimes loss communication with the OSM01. In most case, the interface process cannot re-establish communication automatically. The cause of the loss of communication is still unknown at this point. Also, we notice that the OSM01 will take ten times as long to establish equal number of point as compare with direct SCSI connection with ICI03. For these reasons, currently, we are not recommending using OSM01 with the PI-semAPI interface.

Running with semAPI version 1.2 on Windows NT, if the SCSI connection between the host computer and the ICI03 was disconnected for a short while (one minute for example) and then re-connected, subsequent calls to the semAPI would result in error. The problem would not go away unless the Bailey device driver process was stopped. The same problem was also observed if the ICI module was reset. These problems are fixed with semAPI version 2.0 and greater.

For some system with a lot of points on Bailey loop different from where the ICI is located, it could take more than 90 seconds to connect these points. However, the ICI watch dog timer is activated as soon as the connect point command is received by the ICI. So it is possible for the ICI to time out in the middle of processing the connect point command. In this case, the /TO parameter has to be increase to work around the problem.

Per Bailey, customers should use the Adaptec 2940 U SCSI, 50 pin card with the ICI03. Additionally they should order the 18foot SCSI cable from Bailey, part no. AI1758-18.

With SEMAPI 2.0 and later, the interface has been known to have problems working when the user logs off of an NT machine. After a user logs off, the semAPI device driver stops running and therefore our interface loses the connection to the ICI. To fix this problem, the semAPI device driver must be installed as a service. The following are the steps:


1) Install semAPI with custom installation and make sure to install the DEVICE files.

2) From the installation directory, run “DeviceAsService DD_<device name> -i”

3) Configure in Control Panel for auto start

4) Uninstall Blysem service with blysem -remove command

5) Reinstall Blysem service with blysem -install -auto -depend “tcpip DD_<device name> bufserv”

The <device name> is the ICI device name specified in the ICICONF utility. For instance, if COM1 is specified then the command would be:

DeviceAsService DD_COM1 -i

If the interface reports “Invalid security device present”, the user string or software key have not been entered or are incorrect. The software key is a long alphanumeric string and the user string is usually “LICENSE01”. Both of these strings are furnished from Bailey. These strings need to be entered in three places. The software key needs to be entered into the LICENTRY utility. However, the user string needs to be entered in BOTH the LICENTRY and the ICICONF utility. Without correct user/software key strings entered, neither the talk90 program nor the interface will be able to connect to the ICI.

ICICONF Utility:


LICENTRY Utility:


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

MessagesPBI 1> <semAPI Err>Fatal 204 (ICI): Invalid security device present.

License Parameters are not setup correctly in Bailey semAPI software. Please refer to Restrictions and other Information section for details on how to fix this.

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 NT and UnixOn NT, descriptions of system and PI errors can be obtained with the pidiag utility:

\PI\adm\pidiag –e error_number


Revision HistoryDate Author Comments

Apr 96 DBS First version for Beta release

1 Jul 96 LFM Modified installation section. Add information about semAPI linking. Changed link option to SC and DA instead of VAX and ALPHA. Add description of link warning messages related to UCX.

7 Oct 96 LFM Added fail over description, new extended attributes for analog points and station status. Removed time alias discussion. Editing station points is no longer a problem.

30 Jan, 98 LFM Added NT section.

30 Sep, 98 LFM Support for Harmony points in version 1.3. Added description of known semAPI problems.

14 Oct, 98 LFM Changed description of converting CIU output index to Bailey block address

17 May, 99 LFM Fixed typo in Introduction section. Removed ref. to OSM

2 Jun,99 JK Fixed typo on page 24 regarding version compatibility

22 Nov,99 LFZ Added clarification in intro that customer purchases semAPI software and computer interface module from Bailey and interface software from OSI

6 Jan, 00 JK Added /rc flag description, gave more detail on /ts flag, change to support for SEMAPI 2.0 and greater

4 May, 00 JK Added some troubleshooting tips

20-Jan-00 AKF Updated manual to Skeleton 1.04

05-Jul-01 HAB Added section on ICU control. Doc rev A

05-Sep-01 HAB Updated section on ICU control. Doc rev B

14-Apr-04 HAB Updated section on ICU control. Doc rev C


Documents

Uniint End User - OSIsoftcdn.osisoft.com/interfaces/348/PI_baSemAPI_1.3.4NT-1.2VMS-Rev… · Web viewIf the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy