yokogawa ygw interface to the pi system -...

Yokogawa YGWInterface to the PI System

1.8.0.1

How to Contact Us

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

Fax (510) 357-8136

E-mail [email protected]

World Wide Web http://www.osisoft.com

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

OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1Deutschland

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

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

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

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

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

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

1997 - 2005 OSIsoft, 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......................................................................................................2

Communication Configuration......................................................................................3Yokogawa Gateway Setup Diagram............................................................................4

Hardware Configuration................................................................................................4

Micro XL Communication Requirements......................................................................5

Ethernet Communication..........................................................................................5

Serial Communication...............................................................................................6

Principles of Operation.................................................................................................7Gateway Failover.........................................................................................................7

Input Tags....................................................................................................................8

Output Tags..................................................................................................................8

Tag Attributes Update..................................................................................................9

Event Counter Tags.....................................................................................................9

Logging File..................................................................................................................9

Error Handling............................................................................................................10

Installation Checklist...................................................................................................13

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

Interface Directories...................................................................................................15

The PIHOME Directory Tree...................................................................................15

Interface Installation Directory................................................................................16

Interface Installation Procedure..................................................................................16

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

Installing the Interface Service with PI-Interface Configuration Utility....................17

Installing the Interface Service Manually................................................................19

Yokogawa YGW Interface to the PI System iii

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

Interface Installation Procedure..................................................................................22

Permanent Installation............................................................................................24

Communication Testing Programs............................................................................25

Digital States................................................................................................................27

PointSource..................................................................................................................31

PI Point Configuration.................................................................................................33Point Attributes...........................................................................................................33

Tag.........................................................................................................................33

PointSource............................................................................................................33

PointType...............................................................................................................33

DigStartCode, DigNumber (PI2 only)......................................................................33

DigitalSet (PI3 only)................................................................................................34

Location1................................................................................................................34

Location2................................................................................................................34

Location3................................................................................................................34

Location4................................................................................................................34

Location5................................................................................................................35

InstrumentTag........................................................................................................35

ExDesc...................................................................................................................35

Scan.......................................................................................................................36

Shutdown................................................................................................................36

SourceTag..............................................................................................................37

Zero/Span...............................................................................................................37

Performance Point Configuration...............................................................................39Configuring Performance Points with PI-ICU (NT-Intel).............................................39

Configuring Performance Points Manually.................................................................40

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

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

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

Configuring the PI Point on the PI Server...............................................................45

Yokogawa YGW Interface to the PI System iv

Configuration on the Interface Node.......................................................................45

Startup Command File.................................................................................................47Configuring the Interface with PI-ICU.........................................................................47

ygw Interface Tab...................................................................................................52

Command-Line Parameters.......................................................................................64

Sample YGW.bat File.................................................................................................79

Interrupt Messages Switch File..................................................................................81

Data I/O Type Filter File.............................................................................................81

Digital State String Translation File............................................................................82

Interface Node Clock...................................................................................................85NT...............................................................................................................................85

VMS............................................................................................................................85

Security.........................................................................................................................87NT...............................................................................................................................87

VMS............................................................................................................................87

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

Stopping Interface Running as a Service...................................................................89

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

Stopping.....................................................................................................................93

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

Configuring Buffering Manually..................................................................................99

Example piclient.ini File............................................................................................100

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

Messages.................................................................................................................101

System Errors and PI Errors.....................................................................................104

Revision History...........................................................................................................107

Yokogawa YGW Interface to the PI System v

IntroductionThe Yokogawa YGW interface provides communication between PI and Yokogawa CGWU, EGCW3 and ECGW* gateways and the Micro XL DCS. It is an OSI Software standard Universal Interface (Uniint).

Note: All mention of the above four Yokogawa systems will be referred to, hereafter in this manual, as “the gateway”. If, however, information in this manual refers to a specific gateway, the actual gateway name will be used.Data is transferred between the gateway and the interface via RS-232 Serial TTY communication or TC/PIP socket calls. Data is transferred between the interface and PI via the PI API. The PI API is necessary for the interface to run and is not included with the interface. The minimum requirements for the interface are given in the following table:

Platform OS Version PI System PI API

VAX/Alpha VMS All 2.1.1 N/A

Intel Windows NT 3.51 3.1 1.2

Alpha Windows NT

4.0 3.1 1.2

The interface supports input tags (from Yokogawa to PI) and output tags (from PI to Yokogawa). It counts the events to and from these tags, including exception tests, and sends its totals periodically to PI. Data from the gateway is received at cyclic frequencies or by exception in the data. The frequency of the cycles is configured by the user and controlled by the interface. The number of tags that the interface is capable of servicing is unlimited.

Changes that are made to the PI point database are reflected in the interface. This includes the adding, editing and deleting of tags.

All error information and some summary information are output to a log file. The amount of summary information that is output is configurable by the user and is minimal by default. For information about configuring information messages, see the “/db”, “/lg” and “/cl” headings of the Command-Line Parameters section on page 60

Reference Manuals

OSIsoft PI Server manuals

PI-API manual

UniInt End User Document

Yokogawa YGW Interface to the PI System 1

Supported FeaturesFeature Support

Part Number PI-IN-YO-YGWPlatforms VMS / Alpha VMS / NTI (4, 2000, XP) APS Connector NoPoint Builder Utility NoICU Control YesPI Point Types Real, digital, int16, int32, float16, float32,

float64, stringSub-second Timestamps NoSub-second Scan Classes NoAutomatically Incorporates PI Point Attribute Changes

Yes

Exception Reporting YesOutputs from PI YesInputs to PI: Scan-based / Unsolicited / Event Tags

Scan-based, Event tags

Maximum Point Count Limited only by YGW gatewayUses PI-SDK NoPINet to PI 3 String Support NoSource of Timestamps PI ServerHistory Recovery NoFailover No* UniInt-based YesVendor Software Required on PI-API / PINet Node

No

* Vendor Software Required on Foreign Device

Yes, only for Micro XL. See Micro XL Communication Requirements section below.

* Vendor Hardware Required Yes, only for Micro XL. See Micro XL Communication Requirements section below.

* Additional PI Software Included with Interface

Yes, YGI_Test.exe and YGI_TestB.exe connection test programs

Device Point Types INT, FLT, CHR

* See paragraphs below for further explanation.

UniInt-basedUniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by our developers, and is integrated into many interfaces, such as the PI-Yokogawa YCG interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

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


Vendor Software RequiredVendor software is required only if the interface is connecting to a MicroXL Device. This is described below in the Micro XL Communication Requirements section below.

Vendor Hardware RequiredA network interface card is required on the gateway (or MicroXL device) if the interface is to be connected using Ethernet TCP/IP. This card is supplied by Yokogawa and is sometimes provided with the device by default..

Additional PI SoftwareSee section Communication Testing Programs on page 25 for explanation.

Communication ConfigurationThe interface supports communication to a variety of Yokogawa systems using different communication protocols. The following table indicates which protocols are supported for each Yokogawa system:

DCS System Communication Gateway Interface

Platform

Centum V RS-232C TTY CGWU VMS, Windows NT

Centum XLRS-232C TTY

ECGW* VMS, Windows NT

ECGW2 VMS, Windows NT

ECGW3 VMS, Windows NT

Ethernet TCP/IP ECGW3 VMS, Windows NT

Micro XLRS-232C TTY No Gateway VMS, Windows

NT

Ethernet TCP/IP Software Emulator VMS, Windows NT

Note: If the interface is running on VMS, DEC TCP/IP software (UCX) is required to be able to use the TCP/IP protocol.


Introduction

Yokogawa Gateway Setup Diagram

Hardware ConfigurationTo be able to communicate with the gateway, the correct protocol parameters must be set up on the DCS.

Ethernet TCP/IPThe following information must be specified at the DCS:

Character Mode Binary Mode (ECGW3 only)

Communication Text Character Mode Binary Mode

Delimiter Character CR-LF None

Sequence Numbers Yes Yes

Interrupt Message Mode Character Mode Character Mode

See the Command-Line Parameters section on page 60 for information about how to match the interface with these parameters.

Text can be sent continuously to gateway without waiting for reply. The maximum text count that can be sent in sequence depends on the configuration of each gateway. The continuous text count is specified in the interface startup file using the “/sc” argument (see page 60) and should not exceed the limits of the DCS.

4

RS-232 Serial CommunicationThe following information must be specified on the DCS and in the interface port settings file, PISysExe:Ygi_Setterm.com (VMS only) or the interface startup file command line arguments (NT only). The protocol does not accept sending text continuously. The settings marked (opt) are optional but must match between the DCS and the port settings.

DCS Settings VMS Port Settings

NT Command Line

arguments

Communication Rate 9600 bps (opt) 9600 bps (opt) /bps=9600

Communication Code 8 bit (opt) 8 bit (opt) /bs=8

Parity Even (opt) Even (opt) /par=E

Stop Bit 1 bit N/A /sb=1

Text ASCII N/A N/A

XON/XOFF Yes N/A N/A

Sequence Numbers Yes N/A N/A

Other Settings N/ANoWrap,

NoType_Ahead, NoModem

N/A

Micro XL Communication RequirementsThe MicroXL does not have a gateway through which to collect data (see the Yokogawa Gateway Setup Diagram above). Communication is done via a communication interface card, it’s driver and some additional communications software. All of these are installed on the MicroXL. The communication software provides an interface to the MicroXL that gives it the appearance of an ECGW3 gateway. Thus the interface can send and receive its normal protocol as if it were connected to a gateway.

The requirements for serial communication and Ethernet communication are as follows:

Ethernet CommunicationYokogawa Products

EN83 Ethernet communication card (the Ethernet card for the MIGHTY station).

MAPF-S221 Ethernet card driver.

MAPF-S311 Ethernet computer communications package (ECGW3 protocol emulation software).

Third Party Products


Introduction

Transceiver and cable converter from AUI port to the physical network.

The MOPS and MOPL stations must be upgraded to MIGHTY stations (Y211). The setup will not function on standard (S211), advanced (A211) or enhanced (E211) systems. These systems may have an EN82 Ethernet card but MAPF-S311 emulation software will not work with it.

To be sure of what version the station is currently running, reboot the operator station, press the S2 key and check the operating system revision number at the top of the screen. The MIGHTY software will display “R1.A#” (where # is the revision number). The revision number itself is not important (R1.A6 is the Y2K compliant revision but subsequent revisions may have been released since), as long as the revision label is R1.A on the S2 screen. If the station is not a MIGHTY station then the revision label will display “Rev.#” or something similar.

The station can also be checked for its version by looking at the CPU card (it is a CP81 card). A card of type CP81*E is a MIGHTY type card. Cards of type CP81*A through to CP81*D are not.

Station Type Station Number Y2K Revision CPU Card

Standard S211 Rev.26 CP81*A

Advanced A211 Rev.26 CP81*B

Enhanced E211 Rev.26 CP81*C

Power Rev.26 CP81*D

MIGHTY Y211 R1.A6 CP81*E

Performance is most reliable when the Ethernet card is in the engineering station (or wherever the system is configured from). The MOPS or MOPL station must be given a fixed IP address because DHCP is not supported.

Serial Communication RS81 serial communication card (the Serial card for MOPS or MOPL stations).

MSPF-C011 serial communication card driver.

MAPF-S031 serial computer communications package (ECGW3 protocol emulation software).

The serial port settings must match those in the table in the RS-232 Serial Communication section above.

6

Principles of OperationWhen the interface starts up, it receives several parameters from the interface startup file. These parameters define the PI Point Source code and the set of Scan Class time periods to be available and other parameters as described in the Command-Line Parameters section on page 60.

Log messages are recorded either in the PI log file or the PI application log file. The PI log file is named PI\PILog\pimsg_yymmdd.dat and is renewed daily. Its information is more about the status of PI than the interface. The status of the interface is recorded in the PI application log file Pipc\Dat\Pipc.log. This file is never renewed and is the responsibility of the system administrator to handle its backing up and/or deleting.

The interface begins by searching the PI Point Database for all tags configured with the PointSource code specified in the interface startup file. It records these tags in dynamic group structures in computer memory based on logical grouping (for example, one list per scan class, per point type). If any tag makes reference to a PI tag that is not present in the PI point database, a message indicating this is logged and the tag is rejected by the interface.

Data is retrieved from the gateway upon request. The conditions under which this happens are specified either by individual PI tags or by the interface startup file as described in the Command-Line Parameterssection on page 60.See, also, the Input Tags section below. When the interface receives data it is filtered through the exception and compression criteria of each PI tag.

When the interface process has completed these initial tasks, it enters a permanent loop in which it processes input and output tags. This loop is repeated until the interface is stopped. The actions taken within this loop are described below.

Gateway FailoverThe interface is able to maintain connection information for multiple gateways. If the connection to a gateway fails, the interface will be able to connect to a different gateway.

The interface maintains information about each gateway in a list. This gateway information is specified in the interface startup file. Each gateway in the list may be of a different type and/or connection type, provided the interface can support it. See the “/gw” argument on page Error: Reference source not found and the “/term” argument on page Error: Reference source not found for information about how to configure the interface for each gateway.

When the interface attempts to make a connection, it starts with the first gateway in its list and attempts to connect to it. If this fails, it tries the second gateway, then the third, until all of the gateways that have been specified in the interface startup file have failed.

Note: The interface can maintain information for a maximum of 10 different gateway connections.

When the interface encounters a connection failure during operation it will attempt to reconnect by starting at the beginning of its gateway list. This occurs even if it was connected to a gateway that is second or later in the list. For this reason, the gateway that is considered to be the primary source of data collection for the interface (the one that is


used under normal circumstances) should be the first in the list. Other gateways are considered merely as backup and should be placed in the list according to their appropriate priorities. This way, the interface will reconnect to its preferred gateway if it is available—especially if the connection was lost only temporarily.

Note: The interface will not automatically switch to another gateway that has a higher priority just because that gateway is made available. The current connection must be broken before the interface will attempt to reconnect. For example, the connection to gateway 1 is lost and the interface finds a connection to gateway 2, it will not switch back to gateway 1 until the connection to gateway 2 is broken.

Some useful applications of this functionality are:

If a gateway needs to be taken offline or shut down for a long period of time, the interface can still collect data without the need for human interaction and reconfiguration.

If the there is a network problem and the Ethernet connection fails, the interface can connect to the same gateway using RS-232 via a serial line.

Input TagsInput tags are serviced by the interface to collect data from the gateway and send it to PI. They can either be scan-based or event-based. Scan based tags are serviced regularly at a pre-defined time interval. Event based tags are serviced when a change occurs in a separate PI tag.

Scan-BasedAn input tag can be configured to be updated at a regular time interval specified by any one of a set of user-defined scan classes. The interval of each scan class is based from and controlled by the interface. When a scan class’s time interval expires, the data for the tags that are configured for that scan class is requested. 32 tags for a particular scan class are retrieved from the gateway at a time, until all tags for that scan class are collected. For information about defining scan-based input tags, see the description of “/f” in the Command-Line Parameters section on page Error: Reference source not found .

Event-BasedAn input tag can be configured to send data to PI on an event, based on the exception of the data from a separate PI point. When the value of this separate PI point changes, the data for the actual tag is requested from the gateway. For information about setting up an exception tag, see the ExDesc heading of the PI Point Configuration section on page 33

Output TagsOutput tags are serviced by the interface to collect data from PI and send it to the gateway based on the exception of a separate PI tag (referred to as a “source” tag). When the value of this source tag changes, it is sent both to the gateway and to the output tag itself. This keeps a record of data that was sent to the gateway. For more information about setting up an output tag, see the SourceTag heading of the PI Point Configuration section on page 35 . If a tag is defined to be an output tag, its settings override any settings that apply to input tags.


If an output tag requires the destination tag to be a PI tag, the PI Performance Equation utility should be used (see the PI2 System manual, Part I or the PI Data Archive for Windows NT and Unix manual).

Note: A PI tag cannot be configured as an output tag to a Yokogawa PV variable. See page 32 .

Tag Attributes UpdateApproximately every two minutes the interface checks for any messages from PI indicating that a PI tag has been added to, edited in or deleted from the PI point database. It then makes appropriate changes to its own tag lists. An edited tag in PI is handled within the interface by deleting the tag from its tag list and adding it back in with the new tag definition. The updated information comes into effect from that time onward, without having to stop the interface.

Event Counter TagsAn event counter (also known as an IORates counter) can be used to monitor data being processed within the interface. Each event counter counts the number of times a particular event occurs, calculates a rate and sends it to PI. The rate is based on a 10-minute average and represents the number of events per minute. The interface increments the event counters assigned to it whose definitions are located in the file Pipc\Dat\IoRates.dat. This file is used by multiple PI client applications for similar purposes. The format of the file is as follows: Comment lines preceded by a *

* RampSoak interface exceptions IORate tagRmpSk_Exc, 27** PI-YGW interface exceptions IORate tagYGW_Except, 22** PI-YGW input data received IORate tag

Each entry must have a PI tag name and a unique counter number (counters 35-50 are reserved for system applications). The interface will use the tag in this file whose event counter matches the event counter number passed by the “/ec” option in the interface startup file. Although Uniint supports multiple uses of this argument, it can only be used once for this interface.

For example, if IORates.dat file was defined as it is in the example above and the first occurrence of “/ec” in the interface startup file was /ec=22, the interface would use the PI tag “YGW_Except” to store its rate of exceptions. See the description of the “/ec” argument in the Command-Line Parameters section on page Error: Reference source not found for more information.

The tag specified in the IORates.dat file must be defined in PI and use a different point source than that of the interface (the default point source L is adequate).

Logging FileError and warning messages are logged to the Pipc.log file located in the Pipc\Dat directory of the PC that the interface is running on. The interface has the option of


Principles of Operation

writing debugging and information messages to this log file. For more information about configuring the interface to do this, see the description of “/db” in the Command-Line Parameters section on page 60 .

Each message is preceded by the local timestamp of the computer it is running on. The file is used by multiple PI client applications for similar purposes as the interface. To distinguish which messages are from the interface each message is preceded by a header. The format of such a message is

dd-mmm-yy hh:mm:ssYGW Id_String> Message

where Id_String is the string passed to the interface by the “/id” command line argument. See the Error: Reference source not found section on page Error: Reference source not found for more details. Following is an example of a message in the log file from the interface that uses the command line argument /id=Tower.

31-Jul-98 09:05:03YGW Tower> Hardware initialization error, Intf halted

Note: If the interface is configured to accept interrupt messages, these messages will be logged in Pipc.log. These are not errors, only reports of these messages. See the Command-Line Parameters section on page Error: Reference source not found for more information.

Error Handling

1. The integrity of the point configuration is checked during the interface startup and when new points are added to PI system. If an error is detected, corresponding error messages are logged to the log file and the point is not added to the interface point list.

2. A point will receive a status of BAD_INPUT for the following reasons:

An error value (-99999999) was returned from the DCS system.

An obstruction occurred on the DCS system.

An error will occur if the specified instrument tag does not exist on the Yokogawa DCS system.

The error return code is in the log file. If this error occurs, verify the point definition of the tag in question.

3. R_OVER_DIG is written to a PI2 digital tag if the value from the DCS is not between the starting digital state code and the number of digital states. R_OVER_DIG is written to a PI3 digital tag if the value from the DCS is greater than the number of digital states defined in the digital state set for that tag. BAD_DIGSTATE is written when the digital state string from the DCS does not exist in the digital state table (PI2) or the digital state set for that tag (PI3).

4. IO_TIMEOUT is written to a tag if a time out is detected between the interface and the DCS system. CONN_CLOSED is written when the connection with the gateway is closed. In this case, the interface logs an error message in the log files and stops retrieving data for the scan class which the error occurred on. The interface then resumes scanning starting with the next scan class. The interface will try to initialise the communication after a time out has been detected or the communication with DCS system is closed. Unless there are the obstructions, if the interface detects a

10

connect error it will write CONN_CLOSED for TCP/IP communication. Correspondingly, if the interface detects an initialisation error, INIT_ERROR will be written for TTY.

5. When the interface can not communicate with DCS system, the interface must be restarted after the reasons for the communication failure have been resolved. You can use the test programs to make sure that the path of communication is open prior to starting the interface (see page 25). YGI_Test.exe is used if communication is TTY or via TCP/IP in character mode. YGI_TestB.exe is used if communication is via TCP/IP in binary mode.

6. For Centum V and Centum XL the user can define a maximum of 8192 points to blocks for one Yokogawa DCS system (maximum of 32 points per block and a maximum of 256 blocks). For Micro XL the maximum number of blocks definable depends on the memory available on the DCS. If the user tries to define more than the maximum number of points to blocks, the interface will write NO_BLOCK to all points exceeding the limit. The interface will refuse those points and the data of these points will not be retrieved. The interface uses a single block with a single scan class. BAD_BLOCK is written to a point if an error has occurred in its block definition.

7. When the integer value from the DCS system is less than 0, the status INT_MINUS is written to the point. The point should be defined as point type Real and high precision if there is a possibility that values will be less than 0. This will result in the value instead of the digital state INT_MINUS being stored in PI (see the PI Point Configuration section on page 31).

8. If an output point is set to a value outside of its digital state range, the interface will not output the value to the DCS and instead writes NOT_OUTPUT to the PI point. NOT_OUTPUT is only written if it has an associated source tag.

9. The interface only will output data to the DCS if its data type has been specified in the file YGW_OItem_#.txt. The interface checks the value in the location 1 parameter to determine whether to update the DCS or not. If the interface cannot output the value to the DCS, NOT_OUTPUT is written to the output point if it has an associated source tag.

10. If the interface fails to update DCS data, it writes OUTPUT_ERR when a communication error has occurred and it writes FAILED when the DCS system has returned an error. Again, these states are only written to the point if it has an associated source tag.


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

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

2. Verify that PI-API has been installed.

3. Install the interface.

4. Test the connection to the gateway using the test programs as described in the Communication Testing Programs section on page 25.

5. Four additional steps are required to ensure this interface is started and stopped with the PI system automatically.

a. Insert a new Setterm command after each stop command that refers to an interface using TTY serial communication.

@PISysExe:YGI_Setterm xxxx

where xxxx is the terminal name for that interface.

b. Add a new line for each process required, supplying the point source as a parameter.

@PISysExe:YGW_Detach #

where # is the point source of the interface to start.

c. Edit PISysMgr:SiteStop.com by inserting a new stop command line for each process

@PISysExe:Stop YGW_INT_#

where # is the point source of the interface to start.

d. Insert a new Unsetterm command for after each stop command that refers to an interface using TTY serial communication.

@PISysExe:YGI_UnSetterm xxxx

where xxxx is the terminal name for that interface. 6. Define digital states as specified in the Digital States section (p. 27).

On and Off are required in the System Digital State Table.

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

8. Configure PI points. Location1 is the type of point Input or OutputLocation2 is not used.Location3 is not used.Location4 is the scan class (and, subsequently, the data access type)Location5 is not used.ExDesc is used for event triggered tags and extended point source.InstrumentTag is used for defining the Yokogawa point to read.


9. When the PI2 system is shutdown, the points coming into the system should receive shutdown events. Modify the argument list for the program ShutdownEvents, which is executed from files ShutdownEvents.com and CheckForCrash.Com.

10. If the interface is running on a PI API node, set the ‘Shutdown’ field to OFF (0) for ALL of the tags defined for this interface (PI3 only).

11. Configure performance points.

12. Configure I/O Rate tag , e.g. SYYGWPSY (VAX and NT only) as described in the Event Counter Tags section (p. 9).

13. Stop and restart the IORates process (PI2 only).14. Configure the interface using the PI-ICU utility or edit startup command file manual.

It is recommended to use PI-ICU whenever possible.

15. Set interface node clock if running on NT.

16. Set up security. If the interface is running on a PI API node, define a proxy account or trust for the machine the interface is running on (PI3 only). See the PI Data Archive manual for details.

17. Start the interface without buffering.

18. Verify data.

19. Stop interface, start buffering, start interface if running on NT.


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

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

In most cases, interfaces on PI Interface 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 YGW.exe and that the startup command file is called YGW.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 YGW1.exe and YGW1.bat for interface number 1, YGW2.exe and YGW2.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.

Interface Directories

The PIHOME Directory TreeThe PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located


in the WinNT directory. A typical pipc.ini file contains the following lines:[PIPC]PIHOME=c:\pipc

The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.

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

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

Interface Installation ProcedureThe PI-Yokogawa YGW interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0 systems, the PI-Yokogawa YGW setup program will install the Windows Installer itself if necessary. To install, run the YGW_x.x.x.x.exe installation kit.

Installing the Interface as an NT ServiceThe PI-Yokogawa YGW interface service can be created, preferably, with the PI-Interface Configuration Utility, or can be created manually.


Installing the Interface Service with PI-Interface Configuration UtilityThe PI-Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:

Service Configuration

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

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

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

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

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

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

Generally, interface services are set to start automatically.

DependenciesThe Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependent should be moved into the Dependencies


Interface Installation on NT

list using the button. For example, if API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. Often interface services also depend on a vendor program, such as the Fisher-Rosemount

chipservice. To remove a service from the list of dependencies, use the button, and the service name will be removed from the “Dependencies” list.

When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.

Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.

- Add ButtonTo add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove ButtonTo remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.

The full name of the service selected in the Installed services list is displayed below the Installed services list box.

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

Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.

Start or Stop ServiceTo Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

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

18

Status of the ICU Status of the

Interface Service

Service installed or uninstalled

Installing the Interface Service ManuallyOne can get help for installing the interface as a service at any time with the command:YGW.exe –help

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

NT Service Installation Commands on a PI Interface Node or a PI Server node

with Bufserv implementedManual service YGW.exe –install –depend “tcpip bufserv”Automatic service YGW.exe –install –auto –depend “tcpip bufserv”

NT Service Installation Commands on a PI Interface Node or a PI Server node

without Bufserv implementedManual service YGW.exe –install –depend tcpipAutomatic service YGW.exe –install –auto –depend tcpip

When the interface is installed as a service on the PI Server node and when Bufserv is not implemented, a dependency on the PI network manager is not necessary because the interface will repeatedly attempt to connect to the PI Server until it is successful.

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

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


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? OSIsoft 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 the machine’s resources. 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.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 YGW_Int.exe, the startup command file for interactive processes is called YGW_#.com, and the startup command file for detached processes is called YGW_Detach.com.

The following OBJ files are provided for building the interface and the associated test programs: YGW_FUNC.OBJ YGW_FMT.OBJ YGI_COMMON.OLBYGI_UNIINT.OBJ YGI_TEST.OBJ YGI_TESTB.OBJ

YGW_Setup.comThis command file will copy all the necessary files to their appropriate places in PIBuild: and PISysExe:. It takes one argument which specifies the point source to set up certain files with. This is done so that each point source has a unique startup command file and unique initialization files. The files Ygw__.com, YGW_OItem__.com and YGW_Msg__.com are copied to Ygw_#.com, YGW_OItem_#.com and YGW_Msg_#.com, where # is the point source. If these files already exist on the PI disk they will not be written over.

PIBuild:Link_YGW.comThese link the object files to form the following executables:

Ygw_Int.exeYgi_Test.exeYgi_TestB.exe


PISysExe:YGI_Setterm.comThis file sets up the serial port for TTY communication. It should be executed before starting the interface and supply a point source as a command line argument. Edit this file if you want to change the communication rate, parity or communication code.

PISysExe:YGI_UnsetTerm.comThis file resets the serial port to its default state. Specify a port number when executing it.

PISysExe:YGW_Detach.comThis file starts the interface as a detached process of PI. It checks a condition before and interface startup. The point source must be passed as a parameter to specify which PISysExe:Ygw_#.com file to execute. The name of the created process is YGW_INT_#.

Regardless of how many instances of the interface are running as interactive or detached processes, only one YGW_Int.exe file and one YGW_Detach.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 YGW_1.out, YGW_2.out, and so on.

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

If you choose to change the YGW’s to an abbreviation of your interface you must be consistent and do so throughout the document. Amend this section as necessary to fit your interface.

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, p. 83. Sometimes, however, an interface needs to be installed or upgraded separately from the PI or PINet installation. This procedure is frequently done when the available version of the interface is newer than that which is included with the PI or PINet distribution.

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

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

YGW_Setup.COM Installation command file for the Interface.YGW_Int.BCK Saveset containing the interface files.PI_YGW_1.8.0.0.TXT Release notes.REBLOCK.README Readme file for REBLOCK.EXE.

REBLOCK.EXE The interface backup saveset must be reblocked before the saveset can be unpacked. See the REBLOCK.README.

The following procedure is typical.


1. Transfer YGW_INT.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 YGW_Setup.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 YGW_INT.BCK file. Reblock corrects the block size of the YGW_INT.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): YGW_INT.bck

Filename (“\” to exit): \

4. Install the interface files with the command:@YGW_Setup.com #

where # is the point source to be used for the interface. The command file copies the necessary file from the default directory to PIBuild: and then adds the point source to certain files before copying them to PISysExe: directory.

If more than one copy of the interface will be running, execute this command once from the PIBUILD: for each additional interface substituting for # with a different point source for each. Files similar to the following are typically installed.

PIBuild DirectoryYGW.OBJ Object file for the interface.UNIINT.OBJ Object file for the interfaceLINK_YGW.COM Command procedure for re-linking the executable.

PISysExe DirectoryYGW_INT.EXE Interface executable.YGW1.COM Startup command file for interactive processes.

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

5. Change the default directory to PIBuild: and link the interface by:

@YGW_Link

The executables YGW_INT.exe, YGW_Test.exe and YGW_TestB.exe will then get copied to PISysExe:

6. Complete the point database configuration as specified in this document.


Interface Installation on VMS

7. Modify a copy of PISysExe:YGW_#.com for each interface point source.

8. Verify the Yokogawa Gateway operations as described in this document.

9. Start the interface by executing the command file

@PISysExe:YGW_Detach #

Passing it the interface point source #.

This executes the command file PISysExe:YGW_#.com and creates a detached process called YGW_INT_#.

10. Verify that the interface version number in YGI_#.out matches the version shown on the tape containing the interface.

Stopping the InterfaceYou can stop the interface by executing the command file@PiSysExe:Stop YGI_Int_#where # is the point source for the interface.

Permanent InstallationFour additional steps are required to ensure this interface is started and stopped with the PI system automatically.

1. Insert a new Setterm command after each stop command that refers to an interface using TTY serial communication.@PISysExe:YGI_Setterm xxxxwhere xxxx is the terminal name for that interface.

2. Add a new line for each process required, supplying the point source as a parameter.@PISysExe:YGW_Detach #where # is the point source of the interface to start.

3. Edit PISysMgr:SiteStop.com by inserting a new stop command line for each process@PISysExe:Stop YGW_INT_#where # is the point source of the interface to start.

4. Insert a new Unsetterm command for after each stop command that refers to an interface using TTY serial communication.@PISysExe:YGI_UnSetterm xxxxwhere xxxx is the terminal name for that interface.

24

Communication Testing ProgramsFilenames: Apisnap.exe

Before attempting to run the interface, a connection test should be done individually to both PI and the gateway. If a test program is run that makes reference to only one system, any problems that occur with the communication will be specific to the system being connected to; thus problems can be found and corrected more efficiently. Once connection has been established and confirmed using the test programs described below, the connection specifications for both PI and the gateway that have been set up will function equally well for the interface.

Testing the Connection to PIPI is supplied with a test program, Snap.exe (PI2) or ApiSnap.exe (PI3), which makes a connection only to PI, eliminating any potential problems connecting to the gateway. For more information about this program see the PI2 System manual, Part I, section 3.6.1 or the PI Data Archive for Windows NT and Unix manual.

Testing the Connection to the Yokogawa GatewayThe interface is supplied with a program, Ygi_Test.exe that connects only to the gateway. This test program connects to the gateway in exactly the same way as the interface does. It eliminates PI from the equation during any connection problems that may occur because it makes no reference to the PI system.

If using TCP/IP with an ECGW3 gateway that has the ability to communicate in binary mode, use the Ygi_TestB.exe program if it is intended that the interface use this binary mode (see “/b” argument of the Command-Line Parameters section on page 60). Commands are input into the binary test program in the same way as with the text-based test program. The program will do the necessary conversion to binary.

The programs are run from a VMS terminal using the RUN command or from a Windows NT MS-DOS command prompt.


When started, the program will prompt for a protocol. Depending on the protocol, the interface will ask for connection details. For TCP/IP it will ask for a host name and a port number. These should be entered the same as they are defined using the “/gw” and “/port” arguments (see pages Error: Reference source not found and Error: Reference source not found) in the Command-Line Parameters section. Following is an example of this:*** Yokogawa Gateway Interface Test Program ***

Protocol (0:TCP/IP, 1:TTY) ->0Host Name ->localhostPort No (Space:Default 31000) ->31000Input Command (Option) #A: Show ASCII Code #N: Return Normal Mode NULL: Exit->G01 TG 2 FIC-001,PV FIC-002,PVA01 TG 2 120.1 10.5...

Note: IF TCP/IP is used, the PING command may be used to verify a physical connection to the gateway.


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

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

Two blocks of digital states must be defined in the digital state table specifically for the Yokogawa LS, LOOP, AS, and ALARM tag data types. These must be defined exactly as they appear in the tables labeled Loop Status and Alarm Status below. PI digital tags that store data for these Yokogawa data types must have their DIGSTARTCODE and DIGNUMBER assigned for one of these “blocks” of states.

The interface uses several states that are not defined as part of the standard PI system digital state set. They are defined in the table below labeled Interface States. These states must be entered somewhere in the digital state table where there is at least nine unused states in a row. For the interface to be able to use these states, it must be given the state number of the first state NO_BLOCK using the “/ds” argument in the Startup Command File(see page 61 for more information).

For more information, see the DA manual.

PI 3 Home Node

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

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

A Yokogawa tag that contains discrete data can be stored in PI using a digital tag. A Digital tag associates discrete data with the digital state strings contained in a digital state set, as specified by the user. In addition to any digital state sets defined for use with discrete numerical data, two sets must be defined specifically for the Yokogawa LS, LOOP, AS, and ALARM tag data types. PI digital tags that store data for these Yokogawa data types must be assigned to one of these sets using the DigitalSet field.

The states in these digital state sets must be defined as they appear in the tables labeled Loop Status and Alarm Status below unless the digital state translation table is being used. The digital state translation table is represented in the ACG_sts_#.txt file. For more information about how this file is used and configured, see the Digital State String Translation File section on page 75.

The interface uses several states that are not defined as part of the standard PI system digital state set. They are defined in the table below labeled Interface States. These


states must be entered somewhere in the system digital state set where there is at least nine unused states in a row. For the interface to be able to use these states, it must be given the state number of the first state NO_BLOCK using the “/ds” argument in the Startup Command File (see page 61 for more information). An unused state is identified by a label ?# where # is the number of the unused state; for example, if state 100 is unused it will have ?100 as its label.

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

Digital State Definitions

LOOP STATUS

CENTUM V

OOP BUM BUA MAN MAN+ MAN- MANC AUTAUT+ AUT- AUTC CBM CBM+ CBM- CBMC CBACBA+ CBA- CBAC PRD PRD+ PRD- PRDC CASCAS+ CAS- CASC SPC SPC+ SPC- SPCC DDCDDC+ DDC- DDCC CBC CBC+ CBC- CBCC CMP

CENTUM XL MICRO XL

MAN AUT CAS PRD DDC SPC CBM CBACBC BUM BUA OOP SEMI LS01 LS02 LS03LS04 LS05 CLP+ CLP- CND STOP RUN HOLDSUB1 SUB2 SUB3 SUB4 SUB5 LOCK OFF

ALARM STATUS

CENTUM V CAL IOP HI LO +DV -DV VEL MHIMLO NR ON OFF

CENTUM XLMICRO XL

NR +DV -DV HI LO BPRE BEND NPLSVEL IOP HH LL MHI MLO CAL OOPANS+ ANS- TRIP PERR ALM HDV LDV ALM1ALM2 ALM3 ALM4 ALM5 ALM6 LEAD PRE ENDAOF INT ERR ANS1 ANS2 ANS3 ANS4 ANS5ANS6 PAUS

Interface StatesNO_BLOCK BAD_BLOCK R_OVER_DIG BAD_DIGSTATEINT_MINUS CONN_CLOSED INIT_ERROR NOT_OUTPUTOUTPUT_ERR

I/F_Stopped State

This is a digital state that indicates that the interface was not running at a particular time. This state can be entered into the PI2 digital state table or the PI3 system digital state set as any string but must match the “/stopstat” argument in the interface startup file. See the /stopstat heading of the Command-Line Parameters section on page Error: Reference source not found for more information.


PointSourceThe PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For example, one may choose the letter E to identify points that belong to the YGW interface. To implement this, one would set the PointSource attribute to E for every PI Point that is configured for the YGW interface. Then, if one uses /ps=E on the startup-command line of the YGW interface, the YGW interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of E. 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=E and /ps=e 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 E is not defined in the PI 2 point source table, a point with a point source of E 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 0 -20000000 -20000000 1 -20000000

Maximum 3 20000000 20000000 200 20000000

5. Select “Save” from the menu.

PI 3 Server NodesNo point source table exists on a PI 3 Server, which means that points can be immediately created on PI 3 with any point source character. Several subsystems and applications that ship with PI 3 are associated with default point source characters. The Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use these point source characters or change the default point source characters for these applications. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.


PI Point ConfigurationThe PI point is the basic building block for controlling data flow to and from the PI Server. 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 with the normal PI point naming conventions.

PointSourceThe PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line argument and the “Point Source” section.

PointTypeTypically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated.

PI 2 Server Nodes Scaled real, full-precision real, integer, and digital point types are supported on PI 2 Servers. For more information on the individual point types, refer to the Data Archive (DA) section of PI System Manual I.

This interface support Scaled real, full-precision real, integer and digital.

PI 3 Server NodesFloat16, float32, float64, int16, int32, digital, string, and blob point types are supported on PI 3 Servers. For more information on the individual point types, see PI Server manuals.

This interface supports Float16, float32, float64, int16, int32, digital and string.

DigStartCode, DigNumber (PI2 only)If the tag is of type D. these fields specify where its corresponding digital state strings are located in the PI2 digital state table. The DigStartCode specifies the position in the table of the first digital state is. The DigNumber specifies the number of further states in the table that are to be associated with the tag. For example, if a the digital state table contained four states in a row from 22 to 25 that were to be associated with a tag, that tag’s DigStartCode and DigNumber would be set to 22 and 3, respectively. See the PI 2 Home Node section on page 27for more information about digital states.


DigitalSet (PI3 only)If the tags is of type Digital, this field specifies which digital state set it corresponds to. The digital states that will be used for this tag are those found in the specified digital state set. See the PI 3 Home Node section on page 27 for more information about digital states.

Location1This field is used to specify whether a PI tag is an input tag (from Yokogawa to PI) or an output tag (from PI to Yokogawa). Valid values are from 0 to 3 and are described in the following table:

I/O Location1 Action of Interface

Input 0 Sends all data to PI.

Output

1 Updates the DCS without checking the range of the value.

2 Updates the DCS only if the value lies within the PI range of the tag.

3 Updates the DCS, clipping the value to fall within the PI range of the tag.

A clipped value is forced to be within the bounds of the PI range by setting values that are outside the range of the PI tag to the limit of the range. For example, if the Zero and Span of a tag were 50 and 200, and the output value was 270, it would be changed to 250. If the value for the same tag was 20, it would be changed to 50. See the Zero/Span section on page 35 for more details about the range of a PI tag.

Note: Output tags cannot be configured for Yokogawa PV variables because the DCS does not accept writes to them. For example, FIC0417.PV cannot be configured for output.

Location2This attribute is not use for the Yokogawa YGW interface.


Location4This field is used to specify the scan class number for an input tag. The scan period for each scan class is specified in the startup file. See the description of “/f” parameter in the Command-Line Parameters section on page 60. If a tag is to be read by PI exception, Location4 does not need to be configured. See the ExDesc section for information about how to set up an exception point.



InstrumentTagFor a PI 2 Server, the instrument tag attribute is limited to 32 characters. For a PI 3 Server, the instrument tag is limited to 32 characters if UniInt was not compiled to use the PI-SDK and to 1024 characters if UniInt was compiled to use the PI-SDK.

This field contains the full name of the Yokogawa point with which a PI tag is associated, including the Yokogawa data type. The data type must be separated from the tag name by a comma. For example, FIC0417,PV. For input tags, this represents the Yokogawa point that the data is to be collected from. For output tags, it represents the Yokogawa point that data is to be written to. Lower-case letters are not valid for an instrument tag.

ExDescThis 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 1024 characters if UniInt was compiled to use the PI-SDK.

It is used for defining the source of an event for event-based input tags. The Event-Based heading of the Input Tags section on page 8 describes the operation of event-based tags. The tag that is monitored for the event is specified here in the following format:

EVENT=<PI_Tag>For example,

EVENT=CTD158Here, the interface will request data for the tag only when the PI tag CDT158 receives an exception. Only the occurrence of the exception is recognized by the interface and the actual value of CDT158 is ignored.

The Extended Descriptor can also be used to specify an extended point source. Insert “eps=n” to indicate the extended point source of the tag where n is an integer from 1 to 99. It is used in conjunction with the “/eps=” command line argument in the interface startup file. See the “/eps=” heading of the Command-Line Parameters section on page 62 for more information.

If it is necessary to include other information in the ExDesc field, this can be separated from the event keyword using a comma. For example, if the ExDesc contained

EVENT=CDT158,EPS=3,Changed by JBQ 17-Nov-98The interface would then recognize only the EVENT and PS keywords and the comment would be ignored.

Note: If the ExDesc field is used for specifying that a tag is event-based, it will override scan class information specified by Location4. See the Location4 section on page 32.


PI Point Configuration

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

Scan By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface.

There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.

Shutdown

PI 2 Server Nodes The Shutdown attribute is not used if the server node is a PI 2 system. For information on configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of PI System Manual I.

PI 3 Server NodesThe shutdown attribute is used only if the server node is a PI 3 system.

The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.

Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=Shutdown command-line argument is specified.

One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.

Bufserv It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server,

34

allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.

SourceTag

This field is used for defining the source of an event for event-based output tags. When the value of the PI tag specified in this field changes, it is sent both to the current tag and out to its corresponding Yokogawa point. For more information about the operation of output tags, see the Output Tags section on page 8.

Zero/SpanThis field specifies the range of the PI tag’s zero and span.

For input tags, if the value of a Float16 or Int16 tag is outside of its specified range, either the digital state UnderRange or OverRange will be written to the tag. If the tag is specified as a Float32 or Int32, the input value is written to PI even when it is out of range.

For output tags, the value being sent to the DCS can be checked and changed according to the range of the tag. See the Location1 section on page 32 for more information about output tag values.

This range is also used to determine the compression dead-band width in engineering units when using the CompDev or CompDevPercent(PI3) or DeviationUnits (PI2) field. For more information about these fields, see the PI2 System manual, Part I or the PI Data Archive for Windows NT and Unix manual.


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

Configuring Performance Points with PI-ICU (NT-Intel)The PI-Interface Configuration Utility (PI-ICU) provides a user interface for creating and managing Performance Points.

CreateTo create a Performance Point, right-click the line belonging to the tag to be created, and select Create.

DeleteTo delete a Performance Point, right-click the line belonging to the tag to be deleted, and select Delete.

CorrectIf the “Status” of a point is marked “Incorrect”, the point configuration can be automatically corrected by ICU by right-clicking on the line belonging to the tag to be corrected, and selecting Correct. The Performance Points are created with the following PI attribute values. If ICU detects that a Performance Point is not defined with the following, it will be marked Incorrect:

Attribute DetailsTag Tag name that appears in the list boxPoint Source Point Source for tags for this interface, as specified on the first tabCompressing Off


Excmax 0Descriptor Interface name + “ Scan Class # Performance Point”

RenameTo rename a Performance Point, right-click the line belonging to the tag to be renamed, and select “Rename”.

Status

The Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in column 2.

Created – Indicates that the Performance Point does exist

Not Created – Indicates that the Performance Point does not exist

Deleted – Indicates that a Performance Point existed, but was just deleted by the user

Scan Class

The Scan Class column indicates which scan class the Performance Point in the Tagname column belongs to. There will be one scan class in the Scan Class column for each scan class listed in the Scan Classes combo box on the Uniint Parameters tab.

Tagname

The Tagname column holds the Performance Point tag name.

Snapshot

The Snapshot column holds the snapshot value of each Performance Point that exists in PI. The Snapshot column is updated when the Performance Points/Counters tab is clicked, and when the interface is first loaded.

Configuring Performance Points ManuallyPerformance 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 PI 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 I/O Rate Tags with PI-ICU (NT-Intel)The PI-Interface Configuration Utility (PI-ICU) provides a user interface for creating and managing IORates Tags.

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

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

Tag StatusThe Tag Status column indicates whether the IORates tag exists in PI. The possible states are:

Created – This status indicates that the tag exist in PI

Not Created – This status indicates that the tag does not yet exist in PI

Deleted – This status indicates that the tag has just been deleted

Unknown – This status indicates that the ICU is not able to access the PI Server


In FileThe In File column indicates whether the IORates tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:

Yes – This status indicates that the tag name and event counter are in the IORates.dat file

No – This status indicates that the tag name and event counter are not in the IORates.dat file

Event CounterThe Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.

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

SnapshotThe Snapshot column holds the snapshot value of the IORates tag, if the IORates tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the interface is first loaded.

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

DeleteDelete the IORates tag listed in the Tagname column.

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

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

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

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

1. Configuring the PI Point on the PI Server

2. Configuration on the Interface Node


Configuring the PI Point on the PI Server

PI 2 Server Nodes A 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 ValuePointSource LPointType float32Compressing 0ExcDev 0

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

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:YGW001, x

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


I/O Rate Tag Configuration

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:YGW001, xwhere YGW 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

42

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

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.

The PI-Interface Configuration Utility (PI-ICU) provides a tool for configuring the Interface startup command file.

Configuring the Interface with PI-ICU

Note: PI-ICU requires PI 3.3 or greater.

The PI-Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI-ICU, the interface batch file (ygw.bat) will be maintained by the PI-ICU and all configuration changes will be kept in that file. Once you have used the PI-ICU to configuring the interface, you should not make changes to the interface batch file manually.

The procedure below describes the necessary steps for using PI-ICU to configure a new instance of the PI-Yokogawa YGW Interface.

From the PI-ICU menu, select Interface, New, and then Browse to the appropriate executable, ygw.exe. A window such as the following results:

Enter values for Interface name as displayed in the ICU (optional), Point Source and Interface ID# and if necessary select a Host PI System

Interface name as displayed in the ICU (optional)


This field if specified will be used in two places within the PI-ICU program. First it will be used as the Interface name followed by -> and the “Host PI system” entered. Second it will have PI- pre-pended to this name and it will become the display name on the service tab.

Point sourceThe point source is used to identify points for this interface and must match the pointsource attribute of individual PI points for this interface. The interface will attempt to load only those PI points with the appropriate point source. The point source is generally a single character and is case insensitive. The command line equivalent is /ps=x.

Interface ID #The Interface ID# is either a number or text identifier for this particular instance of the interface. Messages from this instance of the interface in the pipc.log file will be prefixed by “YGW” plus the Interface ID#. (Note that the Yokogawa YGW interface does not use the interface ID# to identify tags for a particular instance of the instance. It uses the interface specific parameter, Extended Point Source, for this purpose.) The command line equivalent of Interface ID # is /id=x.

Host PI System

This is the PI server node to which the interface will send data. If you have your Loading option on the Tools menu set to ‘Load server from default PI server only’, then the default PI server will already be selected and the text box disabled. If your Loading option is set to load interfaces for more than one PI server, then you will need to select the PI server from the drop down list. If the server is not listed in the drop down list, use the triple dot button to browse to the Connections Dialog and add the server. The added server will then be available in the drop down list. The command line equivalent of Host PI System is /host=hostname[:port].

Click on Add. You should then see a display such as the following:

Once you add the interface to PI-ICU, near the top of the main PI-ICU screen, the Interface Type should be ygw.

If not, use the drop-down box to change the Interface Type to ygw.

Click on Apply to enable the PI-ICU program to manage this copy of the PI Yokogawa YGW Interface.


The General tab on the PI-ICU should now look similar to this:

The next step is to configure at least one scan class.


Startup Command File

Scan classesScan classes determine the frequency of data collection. At least one scan class must be defined. The scan class is specified as the period followed by an optional phase offset in the format hh:mm:ss,hh:mm:ss. The phase offset indicates when to start the first data collection and the period indicates how often thereafter to collect data.

To create a new scan class press the new scan class button and enter the desired scan class value in the field provided and hit enter. To delete a scan class, select it from the

list and press the delete button .

The scan class number corresponds to the value of the Location 4 parameter of tags that use this scan class. To adjust the order of the scan classes, select a scan class and move it

up or down using the arrow keys . The command line equivalent is /f=HH:MM:SS,hh:mm:ss.

UniInt TabSince the PI Yokogawa YGW interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI-ICU and to make changes to the behavior of the interface.

46

Additional optional parameters that can be configured on the Uniint tab shown above include:

Performance and Behavior - Scan performance summaryBy default, every 8 hours the interface will log a performance summary. This summary provides information about how many scan classes were scanned late and how many were missed because of a back-log of late scans. This parameter specifies the frequency of performance summary logs. To change the frequency of performance summaries from the default of 8 hours enter the frequency in hours. To prevent performance summaries from being written to the log file enter 0. The command line equivalent is /perf=n.

Data Handling - Queue data (for active interfaces)Checking ‘Queue data’ causes the interface to queue up events locally before sending the data to PI, rather than sending exceptions one at a time. This can make the interface more efficient if it is on a separate computer from the PI Server. However, it will slightly delay the update of the snapshot value if the data rate is low. The command line equivalent for enabling this option is /q.

Data Handling - Suppress initial outputsWhen the interface initializes an output point it sends an initial value out to the DCS based upon the current snapshot of its source tag. This parameter suppresses this initial output.

The command line equivalent for enabling this option is /sio.

Data Handling - Bypass exceptionThe interface will normally perform standard exception tests on all tags and send only the exceptions to the PI snapshot. Checking ‘Bypass exception’ parameter will cause the interface to send all data values straight to the snapshot without performing exception tests. The command line equivalent fro this option is /sn.

Data Handling - Write status to tags on shutdownSelect this option to have a digital state written to all interface tags when the interface is stopped and select the digital state you want to be written from the dropdown box.

Debug LevelsThe Uniint Debug Level specifies the level of debug messaging specific to the standard OSI universal interface (Uniint) that the interface will log. You can choose the types of messages to log by checking the appropriate checkboxes or choose to log all messages by checking Maximum.

During normal operation all of the Uniint Debug Level check boxes should be left unchecked to prevent an excess of messages being written to the pipc.log file. The command line equivalent is /dbuniint=#.

Service Tab If you want to set up the interface as a Windows Service, you can do that by using the Service tab. This tab allows you to configure the interface to run as a service as well as



to start and stop the interface. You can also run the interface interactively from the PI-ICU. To do this go to the menu, select the Interface item and then Start Interactive.

For more detailed information on how to use the above mentioned and other PI-ICU tabs and selections, please refer to the PI-Interface Configuration Utility User Manaul.

ygw Interface TabSelect the ygw tab to configure startup parameters that are particular to the PI-Yokogawa YGW Interface.

GatewaysThe Gateways tab shown below consists of a grid for configuring a primary Yokogawa gateway and up to 5 additional gateways for gateway failover. There are two types of communication protocols used by gateways. Either Ethernet (TCP/IP) or Serial (TTY RS-232).

48

Machine Type:To configure the type of gateway one must first selects a machine type. There are 5 specific types and one Not Specified type. Choosing a machine type will determine which type of gateway communication the interface will use either TCP/IP or TTY (RS-232). The following table show what type will be selected based on the machine type.


Machine Type Communication Protocol

Not Specified TCP/IP or TTY (RS-232)

CGWU TTY (RS-232)

ECGWT TTY (RS-232)

ECGWE TCP/IP

MICROXLT TTY (RS-232)

MICROXLE TCP/IP


TCP/IPChoosing the MICROXLE machine type results in a display similar to the following.

Gateways - Gateway This parameter specifies the Yokogawa gateway’s host name. If the gateway does not have a host name or it is not known, an IP address is sufficient. At least one gateway must be specified. To add a new gateway enter the host name in the first enabled text box in the gateway list.

The preferred connection (primary gateway) should appear as the first gateway in the list. Failover gateways should appear in the order that you wish failover to occur. In the example shown below YGW1 is the primary gateway. If connection to YGW1 is lost, the interface would attempt to connect to YGW2 and if that failed, it would attempt to connect to YGW3.

You can remove a gateway from the list using the button and move a gateway up or

down in the list using the buttons. The blue rectangle indicates the selected gateway that will be deleted or moved.

The command line equivalent for this parameter is /gw=xxxxx.

50

Gateways – Data Port This parameter specifies the port number of the Yokogawa gateway. The interface requires that a port parameter is used for each gateway. The port number should always be 31000, and this value will be entered automatically in the grid for each gateway added to the gateway list. The command line equivalent for this parameter is /port=n.

Gateways – Interrupt PortThe gateway uses an extra port number, 31001, to read interrupt messages. This optional parameter instructs the interface to read these interrupt messages via this interrupt message port.

Gateways - Read Interrupt Messages from (Data Port or Interrupt Port)To read interrupt message from the Data Port check the Data Port check box in the row for the gateway. The command equivalent for this parameter is /ms.

To read interrupt message from the Interrupt Port check the Interrupt Port check box in the row for the gateway. The port number 31001 will be entered automatically in the grid for each gateway where this box is checked. The command equivalent for this parameter is /iport=31001.



TTY (RS-232)Choosing the CGWU machine type results in a display similar to the following.

Gateways – Serial PortThis parameter specifies the machine’s TTY terminal name (VMS) or serial port (Window) that the gateway is connected to. For example,

/term=TTA1: (Example of VMS terminal name.)

/term=COM1: (Example of Windows serial port name.)

At least one serial port must be specified. To add additional serial ports enter the serial port name in the first enabled text box in the serial port list.

The preferred connection (primary gateway) should appear as the first serial port in the list. Failover gateways should appear in the order that you wish failover to occur. In the example shown below COM1 is the primary gateway. If connection to COM1 is lost, the interface would attempt to connect to COM2 and if that failed, it would attempt to connect to COM3.

52

You can remove a serial port from the list using the button and move a serial port up

or down in the list using the buttons. The blue rectangle indicates the selected serial port that will be deleted or moved.

The command line equivalent for this parameter is /term=xxxxx.

Gateways – Baud RateThis parameter specifies the RS-232 baud rate that will be used for communication. This must match the baud rate that the gateway is set at. The default is 9600. The command line equivalent is /bps=#.

Gateways – Byte SizeThis parameter specifies the byte size that will be used for communication. This must match the byte size that the gateway is set at. This must be in the range of 4 to 8 with the default being 8. The command line equivalent is /bs=#.



Gateways – ParityThis parameter specifies the RS-232 parity that will be used for communication. This must match the parity that the gateway is set at. Valid values are given in the table below.

Gateways – Stop BitsThe parameter specifies the stop bits that will be used for communication. This must match the stop bits that the gateway is set at. This must be 1, 1.5 or 2 with the default being 1. The command line equivalent is /sb=#.

Gateways - Read Interrupt Messages from Data PortTo read interrupt message from the Data Port check the Data Port check box in the row for the gateway. The command equivalent for this parameter is /ms.

54

Parameter Setting

Definition

/par=E Even Parity

/par=M Mark Parity

/par=N No Parity

/par=O Odd Parity

/par=S Space Parity

Other Tab

General - Extended point sourceThe extended point source can be used to distinguish tags for multiple instances of the interface using the same point source. It is used in conjunction with “eps=” in the extended descriptor of the tag. If the extended point source of both the command line parameter and the extended descriptor match, the tag will be accepted by the interface. Valid extended point source values are integers from 1 to 99. The command line equivalent for this parameter is /eps=#.

General - Interface text file pathWhen the interface starts, it loads the following files for configuration:



File Name Required File purpose

Ygw_Msg_#.txt Yes For specifying which Yokogawa messages to receive.

Ygw_Oitem_#.txt

Yes For specifying Yokogawa types for output points.

Ygw_Sts_#.txt No For translating Yokogawa digital state strings.

The Interface text file path specifies the path the interface will use to load these files. By default, the interface will search only in its local directory. To specify the path, type the path in the Interface text file path text box or browse to the directory containing these files using the button. The command line equivalent for this parameter is /path=x.

General - Use look up table for digital statesCheck this option to instruct the interface to use a lookup table for PI digital states. When initializing PI digital tags, the interface will then create a lookup table of the required digital state codes. When a digital state string is received from the gateway, the interface will translate it into a PI3 digital state code using this lookup table, rather than making a call to PI to do the translation. This option is useful when the interface is running on an interface node separate from the PI server as it makes the calls to PI only at initialization rather than every time a digital state needs translating, therefore reducing network traffic. Furthermore, if Buffering is being used. and the interface node becomes disconnected from PI, the interface can still translate digital state strings. The command line equivalent for this parameter is /dt.

Gateway Logging - Communication Check ‘Communication’ in the Gateway Logging section to log debug messages specific to communicating with the gateway and processing data. The command line equivalent for this option is /lg.

Gateway Logging - Protocol stringsCheck the ‘Protocol strings’ option in the Gateway Logging section to log the communication protocol text strings that are sent to and received from the gateway. The command line equivalent for this option is /cl.

It is recommended that for normal operation of the interface that these gateway logging options not be used. They are only intended for supplying extra information for solving a problem should one occur.

Communication - TimeoutThe interface monitors the amount of time it takes for the DCS system to respond to a command issued by the interface. This optional parameter specifies the number of seconds the interface will wait for communication with the gateway before canceling the call. The default timeout period is 10 seconds. The command line equivalent for this parameter is /to=#.

56

Communication – Communication Retry countThis optional parameter specifies the number of times the interface will retry to communicate with the gateway after it has timed out. The default retry count is 0. If the interface fails to communicate with the gateway after the retry count has been reached it will abandon the call and continue. The command line equivalent is /rc=#.

Communication – Send Continuous countThis optional parameter specifies how many text strings to send to the gateway at a time. The default value is 1. The maximum number of strings that can be sent continuously depends on the configuration of the gateway. The command line equivalent for this parameter is /sc=#.

Communication – Wait Time between calls:This optional parameter specifies the number of seconds to wait between calls to the gateway. It is not usually needed unless communicating with a CGWU gateway. The CGWU gateway can sometimes fail to communicate correctly if there is not a small amount of time between calls. If it is used, a typical value for this parameter is 1 seconds. The command line equivalent for this parameter is /wt=#.

Communication - Wait on startupCheck ‘Wait on startup’ if you want the interface to retry to connect to the gateway after an initial failure to connect on startup. Then enter the number of minutes for the interface to wait between the attempts to connect. If ‘Wait on startup’ is not checked the interface does not retry the connection at startup but stops instead. The command line equivalent is /wc=#.

Communication – Use binary modeSome ECGW3 gateways have a special function which allows them to communicate in binary mode. If so, this parameter will use this binary mode. Communicating in binary mode is approximately 20% faster than communicating using the standard text mode. If the gateway does not have a binary mode function, the reception and transmission of data will fail if this parameter is selected. If this parameter is not specified, the interface will communicate using the standard text mode. The command line equivalent for this parameter is /b.



Digital States and Data Tab

The following parameters can be configured on the Digital States and Data tab shown above:

Digital States – Suppress the digital states You can prevent the interface from writing digital states to PI tags. To suppress a particular state check the appropriate box listed under ‘Digital states’ frame. To suppress all states, check the All box. The command line equivalent for this parameter is /sds to suppress all digital states and /sds=[#] to suppress a particular digital state. See the section Suppress Digital State(s) on page 65.

Digital Start Code - Digital start code This optional parameter provides the location in the system digital state table of ten digital states used by the interface that are not defined as part of the standard PI system digital state set. These states must be entered somewhere in the system digital state set where there is at least ten consecutive unused states. The digital start code is the state number of the first state in this series of ten states. The default value is 1. The command line equivalent is /ds.

58

Additional ParametersThis text box is included so that any additional parameters added to the interface in the future can be configured before the ICU supports them. Parameters should be entered in command line format with each parameter starting with a space followed by either a / or - character.

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



Command-Line ParametersParameter Description

/bOptional Binary Mode

Some ECGW3 gateways have a special function which allows them to communicate in binary mode. If so, this argument will use this binary mode. Communicating in binary mode is approximately 20% faster than communicating using the standard text mode. If the gateway does not have a binary mode function, the reception and transmission of data will fail. If this argument is not specified, the interface will communicate using the standard text mode.

/clOptional Communication Log Messages

This argument causes the interface to log the communication protocol text strings that are sent to and received from the gateway. It is recommended that for normal operation of the interface that this argument not be used. It is only intended to supply extra information for solving a problem should one occur. For other types of debug messages, see the “/db” and “/lg” arguments. For information about message logs, see the Logging File section on page 9.

/db[=#]Optional Uniint Debug Level

This causes debug messages to be logged specific to the standard OSI universal interface (Uniint) template that the interface is based on. Various levels can be specified which display different types of messages. They are as follows:

/db or /db=1 all messages/db=2 initialisation/db=3 tag building and updates/db=8 exit handling

It is recommended that for normal operation of the interface that this argument not be used. It is only intended to supply extra information for solving a problem should one occur. For other types of debug messages, see the “/cl” and “/lg” arguments. For information about message logs, see the Logging File section on page 9.

60

Parameter Description/ds=# Optional Digital Start Code

This argument specifies where in the PI2 digital state table or the PI3 system digital state set the interface’s status strings can be found. When the interface or one of its tags enters a state not defined in the default state set of the PI system, it uses one of nine states that are defined in the setup process of the interface. In order to use these nine states it must know what position in the set of system states the first one is located. See the Digital States section on page 27 for more information about digital states. The default value is 1.

/dt=# Optional Digital State Table (NT, PI3 only)

This argument instructs the interface to use a lookup table for PI3 digital states. When the interface initialises a PI digital tag, it will create a lookup table of corresponding digital state codes for the digital state set that the tag has assigned to it (unless a table for that set has already been created). When a digital state is received from the gateway in string form, the interface will translate it into a PI3 digital state code using this lookup table. If this argument is not used, the interface makes a call to PI to do the translation. See, also, the Digital State String Translation File section on page 75.

This is argument is particularly useful when the interface is running on a separate computer that the PI system it is connected to (API node). If it is used, the interface only makes the calls to PI at initialisation and not every time a digital state needs translating. Thus, network traffic is reduced.

This argument is also useful when the interface is running on an API node and API Buffering is being used. The API buffering utility does not currently have the ability to translate digital state strings into digital state codes. Thus, if the API node becomes disconnected with PI, the interface can still translate digital state strings. For more information about API Buffering, see Chapter 7 of the PI-Application Programming Interface Manual.



Parameter Description/eps=# Optional Extended Point Source

The extended point source is option which distinguishes multiple instances of the interface using the same point source. It is used in conjunction with “eps” in the extended descriptor of the tag (see the ExDesc heading of the PI Point Configuration section on page 33)If the “/eps” of both the command line argument and the extended descriptor match, the tag will be accepted by the interface. For example if /eps= was defined in the command line and the following tags were definded:

Tag Name PointSource ExDesc

TagA Y eps=1

TagB Y eps=2

TagC Y Not defined

only TagA would be accepted by the interface.

Valid extended point source values are integers from 1 to 99. When the extended point source, is used it is recommended that the “/id=” parameter in startup file match the “/ps” and the “/eps” for identification in log file (for example, /id=Y1).

/lg Optional Log Debug Messages

This parameter causes debug messages to be logged that are specific to communicating with the gateway and processing data. It is recommended that for normal operation of the interface that this argument not be used. It is only intended to supply extra information for solving a problem should one occur. For other types of debug messages, see the “/cl” and “/db” arguments. For information about message logs, see the Logging File section on page 9.

62

Parameter Description/ms Optional Read Interrupt Messages

This argument instructs to the interface to read interrupt messages from the gateway. Messages are read before every data request. The ECGW3 gateway has a TCP/IP port for reading interrupt messages that is separate from its main data access port. Specifying this argument forces the interface to read interrupt messages via the data access port instead of the interrupt message port. To make the interface read interrupt messages via the interrupt message port, use the “/iport” argument, described on page Error: Reference source not found. If both the “/ms” and “/iport” arguments are specified, the “/ms” argument takes precedence.

Messages will appear in the interface log file in a form similar to the following:

16-Feb-00 09:30:21YGW E> from DCS : FM M1 21GD004 PV = 25.01956749 HI

/mt=xxxxx Optional Machine Type

This argument specifies the Yokogawa machine type that the interface is to communicate with. The valid options for this argument are:

Argument Setting Gateway/DCS Communication Type

/mt=CGWU CGWU RS-232 Serial TTY

/mt=ECGWTECGW*, ECGW2, ECGW3

RS-232 Serial TTY

/mt=ECGWE ECGW3 Ethernet TCP/IP

/mt=MICROXLT Micro XL RS-232 Serial TTY

/mt=MICROXLE Micro XL Ethernet TCP/IP

The machines in the table are all very similar in the way they communicate with the interface but each has its slight differences and the interface acts to these accordingly. This argument is not required and its default value is none of the above machines but if not specified, the interface may not run correctly or as efficiently as it should.



Parameter Description/path=x Optional Set Interface Text File Path

When the interface starts, it loads the following files for configuration:

File Name Required File purpose

Ygw_Msg_#.txt Yes For specifying which Yokogawa messages to receive.

Ygw_Oitem_#.txt Yes For specifying Yokogawa types for output points.

Ygw_Sts_#.txt No For translating Yokogawa digital state strings.

For more information about these files, see their descriptions on pages 75–75.

The /path argument will specify the path the interface will use to load these files. By default, the interface will search only in its local directory. If it is running interactively, these files will probably be in the same directory as the interface. If it is running as a service, the local directory will most likely be the \Winnt\System32 directory.

The path does not need a trailing backslash. If it contains a space, it can be placed within double quotes (“…”). For example,

/path="C:\Program Files\Pipc\Interfaces\Ygw"The main purpose of this argument is so that when the interface is running as a service, it can load the same files which are loaded when it is run interactively. To have two copies of this file is potentially confusing. Also, keeping all of the interface files together makes for good housekeeping (the exception to this is the Pipc.log which is kept elsewhere because it is used by multiple PI client applications).

/perf=# Optional Set Performance Summary Interval

By default, every 8 hours the interface will log a performance summary. This summary provides information about how may scan classes were scanned late and how many were missed because of back-log of late scans. This argument specifies the frequency of performance summary logs. For example,

/perf=0 will suppress performance summaries logs.

/perf=1.5 will log performance summaries every hour and a half.

/perf=12.0 will log performance summaries every 12 hours.

64

Parameter Description/rc=# Optional Communication Retry Count

This argument specifies the number of times the interface will retry to communicate with the gateway after it has timed out. The default retry count is 0. If the interface fails to communicate with the gateway after the retry count has been reached it will abandon the call and continue. The retry count applies to individual calls to the gateway, rather than accumulating over multiple calls. In effect, the interface will try to communicate with the gateway rc+1 times before timing out. See, also, the “/to” argument described on page Error: Reference source not found.

/sc=# Optional Send Continuous Count

If using TCP/IP, this argument specifies how many text strings to send to the gateway at a time. Valid values for this argument range from 1 to 8. Some ECGW3 gateways and some Micro XL systems can receive text without a need to reply immediately. Thus, up to eight strings can be sent asynchronously and the replies received in any order. The default value is 1.

/sds[=#]Optional Suppress Digital State(s)

Under certain circumstances the interface will write a digital state to a PI tag instead of a value. For example, CONN_CLOSED will be written to all tags if the connection to the gateway closes. These digital states can be suppressed so that PI does not receive them. This is done by using one instance of “/sds” for each state to be suppressed.

If all states are to be suppressed, the “/sds” argument can be used without assigning it a number. This has the added effect of removing other digital states that the interface may have inserted, such as Bad Input. There are exceptions to this is such as the I/O Timeout state. Also, there are digital states that are not set by the interface (such as Shutdown, Under Range, Over Range, etc.) which cannot be suppressed.

The following table shows the states that can be suppressed:

Arg Setting Suppressed StateArg Setting

Suppressed State

/sds All Digital States /sds=4 INT_MINUS

/sds=0 NO_BLOCK /sds=5 CONN_CLOSED

/sds=1 BAD_BLOCK /sds=6 INIT_ERROR

/sds=2 R_OVER_DIG /sds=7 NOT_OUTPUT

/sds=3 BAD_DIGSTATE /sds=8 OUTPUT_ERR



Parameter Description/to=# Optional Communication Timeout

The interface monitors the amount of time it takes for the DCS system to respond to a command issued by the interface. When there has been no reply from DCS system within a specified timeout period, the interface stops scanning the current scan class and starts scanning the next scan class. The interface writes IO_TIMEOUT to the PI point on which time out occurred and logs an error message to log file.

This argument specifies the number of seconds the interface will wait for communication with the gateway before canceling the call. The default timeout period is 10 seconds. The number of retries is dependant on the “/rc” argument, described on page Error: Reference source not found.

/wc=# Optional Wait Count

This argument specifies the number of minutes to wait between attempts to connect to the gateway at interface startup. For example,/wc=1Means wait 1 minute between attempts to connect.

If this argument is not used, the interface does not retry the connection at startup but stops instead. This was the default behavior before this argument was introduced in version 1.7.0.0.

/wt=# Optional Wait Time

This argument specifies the number of seconds to wait between calls to the gateway. It is not usually needed unless communicating with a CGWU gateway. The CGWU gateway can sometimes fail to communicate correctly if there is not a small amount of time between calls. If it is used, a typical value for this argument is 1 second./wt=1If this argument is not used the wait time defaults to 0 seconds.

66

Parameter Description/gw=xxxxx Required only if using Ethernet TCP/IP

Gateway Host NameIf communicating using TCP/IP, this argument specifies the Yokogawa gateway’s host name. If the gateway does not have a host name or it is not known, an IP address is sufficient. For example,

/gw=MG_ECGW3 or /gw=204.138.119.15To specify the port number, use the “/port” argument as described on page Error: Reference source not found

Gateway Failover

To specify multiple gateways for gateway failover, use multiple instances of this argument (or the “/term” argument). See Gateway Failover on page 7 and “/term” on page Error: Reference source not found

Each use of this argument must be followed by a corresponding “/port” (the arguments that correspond to “/term” are optional but if specified, must be placed after the “/term”). As each “/gw” or “/term” argument is encountered, a new gateway is assumed. For “/gw” this applies whether a “/port” argument was found or not; thus “/port” and “/iport” must be placed in the command line after the “/gw”.

For backward compatibility with previous versions of the interface, the first instance of “/port”, “/iport” or “/bps”, “par”, etc. may be placed anywhere in relation to the “/gw” or “/term” but must be placed before the next instance of “/gw” or “/term”.

\For example, if two gateways, Gateway1 and Gateway2, were available and Gateway1 had both serial and Ethernet capabilities , the command line could be as follows:

… /port=31000 /gw=gateway1 /iport=31001 /gw=gateway2 /port=31000 /term=gateway1 /bps=19200…

In this example, if the preferred connection (Gateway1 via Ethernet) is lost, the interface would attempt to connect to Gateway2 via Ethernet and if that failed, it would attempt to connect to Gateway1 again but via serial line. Note that the first “/port” occurs before the first “/gw” (not as a necessity but as an example) but the second “/port” appears after the “/gw” and the “/bps” occurs after the “/term”.

Note: It is recommended that the first “/gw” or “/term” be placed in the command line before its corresponding arguments (“/port”, “/iport”, “/bps”, etc.) to increase readability. The backward compatibility exists only to allow upgrades to be done from older interface versions without the need to modify the startup file.



Parameter Description/iport=# Optional Interrupt Message Port

If communicating using TCP/IP, the ECGW3 gateway uses an extra port number, 31001, to read interrupt messages. This argument instructs to the interface to read these interrupt messages via this interrupt message port. To make the interface read interrupt messages via the main data access port, use the “/ms” argument, described on page Error: Reference source not found. If both the “/iport” and “/ms” arguments are specified, the “/ms” argument takes precedence.

/port=# Optional Yokogawa Gateway Port Number

If communicating using TCP/IP, this argument specifies the port number of the Yokogawa gateway. This port number should always be 31000, as the following:/port=31000The gateway’s host name is specified using the “/gw” argument, described on page Error: Reference source not found.

/bps=# Optional Bits Per Second (NT only)

This argument specifies the RS-232 baud rate that will be used for communication. This must match the baud rate that the gateway is set at. Default = 9600.

/bs=# Optional Byte Size (NT only)

This argument specifies the byte size that will be used for communication. This must match the byte size that the gateway is set at. This must be in the range of 4 to 8. Default = 8.

/par=x Optional Parity (NT Only)

This argument specifies the RS-232 parity that will be used for communication. This must match the parity that the gateway is set at. Valid values are given in the table below:

Argument Setting Definition/par=E Even Parity

/par=M Mark Parity

/par=N No Parity

/par=O Odd Parity

/par=S Space Parity

The default = N.

68

Parameter Description/sb=# Optional Stop Bits (NT only)

This argument specifies the stop bits that will be used for communication. This must match the stop bits that the gateway is set at. This must be 1, 1.5 or 2. Default = 1.

/term=xxxx Required if using RS-232 serial communication

Serial Port NameThis argument specifies the machine’s TTY terminal name (VMS) or serial port (Windows NT) that the gateway is connected to. For example,

/term=TTA1: (Example of VMS terminal name.)/term=COM1: (Example of Windows NT serial port name.)

If Gateway failover is required, multiple instances of this argument (with the appropriate corresponding arguments “/bps”, “/par”, etc) may be used to specify multiple gateways to connect to in the even of connection loss. See the description of the “/gw” argument on page Error: Reference source not found for details.

/ps=xRequired Point Source

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=xOptional Interface Identifier

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.This argument serves to give extra information about the identity of the interface. All PI clients use the same log file to log messages. The interface will identify itself by preceding its messages with the keyword YGW. If multiple copies of the interface are running on the same computer, each interface’s log messages are distinguished by this argument. For example, /id=Ewould produce messages in the log such as:

31-Jul-98 09:05:03YGW E> Hardware initialization error, Intf halted

The E could be used to indicate in the log file that the message was written by the interface using point source E. See the Logging File section on page 9 for more information about the



Parameter Descriptioninterface log file.

Note: The length of the string defined by this argument must not exceed 9 characters.

/f=SSor/f=SS,SSor /f=HH:MM:SSor/f=HH:MM:SS,hh:mm:ss

Required for reading scan-based inputs. At least one scan class must be defined for the interface to operate correctly.

Scan ClassThe /f flag defines the time period between scans in terms of hours (HH), minutes (MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), and seconds (ss). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds. Each instance of the /f flag on the command line defines a scan class for the interface. There is no limit to the number of scan classes that can be defined. The first occurrence of the /f flag on the command line defines the first scan class of the interface; the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on. Two scan classes are defined in the following example:/f=00:01:00,00:00:05 /f=00:00:07or, equivalently:/f=60,5 /f=7The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans occur at discrete moments in time according to the formula:scan times = (reference time) + n(frequency) + offsetwhere n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:06:10, the second scan would be at 05:07:10, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined.The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section called “Performance Point Configuration” for more information on skipped or missed scans.Sub-second Scan ClassesOne can also specify sub-second scan classes on the command line such as/f=0.5 /f=00:00:00.1where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 of a second.Similarly, sub-second scan classes with sub-second offsets can be defined, such as/f=0.5,0.2 /f=1,0

70

Parameter DescriptionWall Clock Scheduling

Scan classes that strictly adhere to wall clock scheduling are now possible. This feature is available for interfaces that run on NT and/or UNIX. Previously, wall clock scheduling was possible, but not across daylight savings time. For example, /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Savings Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight savings time), one should use /f=24:00:00,00:08:00,L. The ,L at the end of the scan class tells UniInt to use the new wall clock scheduling algorithm .

/host=host:portOptional Host:Port

The /host flag is used to specify the PI Home node. Host is the IP address of the PI Sever node or the domain name of the PI Server 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 manual for more information on the piclient.ini and pilogin.ini files.Examples:The interface is running on a PI Interface Node, the domain name of the PI 3 home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host flags would be:/host=marvin /host=marvin:5450 /host=206.79.198.30/host=206.79.198.30:5450

/stopstator/stopatat=digstateDefault:/stopstat=”Intf shut”Optional

Shutdown Digital StateIf the /stopstat flag is present on the startup command line, then the digital state Intf shut 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=”Intf shut” The entire parameter is enclosed within double quotes when there is a space in digstate.



Parameter Description/ec=xOptional Event Counter

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

/sioOptional Suppress Initial Outputs

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.

/qOptionalnot implemented for interfaces on VMS nodes

Queue Snapshots and ExceptionsWhen the /q flag is present, Snapshots and exceptions are queued before they are sent to the PI Server node. Extended API mode behavior:The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it is not filled.Non-Extended API mode behavior: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.

/snOptional Snapshot Input Data

The interface will normally perform standard exception tests on all tags and send only the exceptions to the PI snapshot. This argument will cause the interface to send all data values straight to the snapshot without performing exception tests.

72

Sample YGW.bat FileThe following is an example file:REM

---------------------------------------------------------------------

REM This command procedure passes the required parameters to REM initialize the Yokogawa YGW interface.REMREM Required Command-Line Arguments REM /ps=x Point source character. Default is noneREM /f=HH:MM:SS Scan class definitionsREM /gw=host(TCP/IP) The gateway name or IP addressREM /term=x(RS-232) The name of the terminal (VMS) or REM port (Win) for serial comm.REMREM Optional Command-Line ArgumentsREM /host=host:port Name of PI home node:port number.REM Default is localhost:5450REM For a PI2 server, port is 545REM For a PI3 server, port is 5450REM /b Communicate to the gateway in binary modeREM Default is FalseREM /cl Write communication text protocol to pipc logREM /db[=#] UnitInt debug levelREM /ds=# Digital start code for interfac-specific system REM digital statesREM Default=1REM /dt=# Use digital state lookup tableREM /ec=# Event count numberREM /eps=# Extended point sourceREM /id=# Interface ID that is logged for each message inREM pipc logREM /lg Gateway communication debug messagesREM /ms Read interrupt messages (from data port)REM /mt=xxxxx Machine typeREM /path=dir Sets the interface text file pathREM /perf=# Hours between performance monitor summaries REM (0=off)REM /q Queue data inputREM /rc=# Number of times to retry if interface fails to REM connect to gatewayREM /sio Suppress initial outputREM /sc=# Max number of strings to send to gateway REM at a timeREM /sds[=#] Suppress interface-specific system digital

state REM (0=NO_BLOCK)REM /sn Snapshot input dataREM /stopstat=digstateDigital state to write to point when interface REM is stoppedREM /to=# The gateway communications timeout in seconds. REM Default=10REM /wc=# Wait count. The number of seconds between REM connection retries.REM /wt=# Wait time. The number of seconds between callsREM to gatewayREM REM Optional arguments for Ethernet TCP/IPREM /port=# Port number used to connect to gateway.



REM Default is 20005.REM /iport=# Use interrupt message port for messages. REM Ignored if /ms is specifiedREM REM Optional arguments for RS-232 SerialREM /bps=# Bits per second (similar to baud). REM Default is 9600.REM /bs=# Byte size (4-8). Default is 8.REM /par=# Parity (E,M,N,O,S). Default is N.REM /sb=# Stop bits (1,1.5,2). Default is 1.REM REM The command line parameters need a space between argumentsREM No spaces within argument.REMREM

---------------------------------------------------------------------

REM Revision HistoryREM Date Author CommentREM 18-May-05 RGM -- Initial version --REM

---------------------------------------------------------------------

REMREM Sample command lineREMYGW.exe /host:ourpiserver:5450 /gw=204.138.119.15 /port=31000 ^/mt=ECGWE /f=1 /f=10 /f=1:00 /f=5:00 /f=30:00 /f=8:00:00,6:00:00 ^/ps=E /id=1 /ds=45 /dt /ec=22 /q ^/stopstat="Inf Shut" /to=30REMREM end of YGW.bat

74

Interrupt Messages Switch FileFilename: YGW_Msg_#.txt

The interface can read specified messages from the DCS system. This file contains a list of the different Yokogawa interrupt message numbers that the interface will request from the DCS (process alarms and sequence messages) by specifying the message number. Refer to the gateway manual concerning the message numbers. The interface writes the messages to the log file (see the Error: Reference source not found section on page 9). When the interface initialises itself it reads this file to determine which messages to request. An example of this file follows:

1 ON2 OFF3 ON7 ON

There are eleven types of message that can be retrieved from the gateway, ranging from 0 to 10 but not all of these need be included in the file. Sometimes not all of them are supported by the DCS (which depends on the individual DCS setup). If a message number does not appear in this file it defaults to OFF and a message is logged similar to:

14-Apr-99 10:32:23YGW M> [MN] not supported number (1)

If communication is via TCP/IP, the interface reads the messages via an interrupt port that is specified in the interface startup command file. Refer to the parameters “/ms” and “/iport” in the Command-Line Parameters section on page 60.The interface can also receive the messages via a data access port if the gateway has a special function. For TTY communication, the interface can only read the messages via a data access port.

Data I/O Type Filter FileFilename: YGW_OItem_#.txt

This file contains a list of the Yokogawa data types that are permitted to be updated in the DCS data by the interface’s output tags. When the interface initialises itself it reads this file to determine which Yokogawa data types it should update in the DCS. The file is distributed with ten data types:

HH LL PH PL DL VL MH ML P I DEach of these data types are on a different line in the file. If a particular data type does not appear in this file, Yokogawa points of that type will not be updated in the DCS. The DCS does not accept writes to PV variables. For example, FIC0417.PV cannot be configured for output.

Note: Precision and overflow may be lost because the length of the output data is dependant on the actual tags.

Digital State String Translation FileFilename: YGW_Sts_#.txt



This file contains translation strings for Yokogawa digital states. When the interface initialises itself it searches for this file. The file has the following format:

<DCS_State_String>,<Custom_State_String><DCS_State_String>,<Custom_State_String><DCS_State_String>,<Custom_State_String>...

As the interface reads the file it creates a table to use for lookup while the interface is running. The file need not contain all digital states that will be used—only those that are deemed necessary by the PI system manager. The <DCS_State_String> represents the digital state string as it is received from the DCS. The <Custom_State_String> represents a digital state string in the PI2 digital state table or a PI3 digital state set. For example,

MAN,ManualAUT,AutoCAS,Cascade

The corresponding PI digital state sets should contain the custom state string. For example, if the YGW_sts_#.txt file contained the three-line example above, then the LOOP_STATUS digital state set in PI should be defined as the following:

CENTUM XL MICRO XL

Manual Auto Cascade PRD DDC SPC CBM CBACBC BUM BUA …

When the interface receives a digital state string from the DCS it translates it using this ACG_sts_#.txt table to a custom state string, converts it to a PI digital code and sends it to PI. See the description of the “/dt” argument on page 61 for more information about converting PI digital states to PI digital codes.

The purpose of this file is to be able to give Yokogawa digital state strings a more meaningful name in PI. It is also useful for translation to different languages where the DCS does not use the same language as the PI system users.

If the file cannot be found, the interface continues without it, logging a message similar to:

Wed Apr 14 10:12:22 1999YGW D> file not found [YGW_Sts_Y.txt]

76

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 Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.

Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.

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

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

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 (or the PI Trust Table, respectively) 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 Server manuals. For PI 3.3 or higher, see “Trust Login Security” in the chapter “PI System Management” of the PI Server manuals.

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 NT This 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 PI-ICU, the services control panel or with the command:YGW.exe –start

To start the interface service with PI-ICU, use the button on the PI-ICU toolbar.

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 “Appendix A: 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 PI-ICU, the services control panel or with the command:YGW.exe –stopThe service can be removed by:YGW.exe –remove

To stop the interface service with PI-ICU, use the button on the PI-ICU toolbar.


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 YGW_detach.com command file. Typically, the YGW_detach.com file does not need to be edited, because the command-line parameters are edited in the associated YGW_#.com file. However, in some cases it may be necessary to edit the YGW_detach.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 YGW_detach.com file.

$! 09-Apr-99 GWM OSI SOFTWARE, INC

$!

$! Ifc_detach.com starts the YGW interface as a detached process

$! By detaching the command file YGW_#.com.

$!

$! The following parameters must be passed to YGW_detach.com:

$! 1 – interface number (1-99)

$ if (‘P1’ .eq. “”) then goto BadParameter

$!

$ if (f$search(“pisysexe:YGW_’’P1’.com”) .nes. “”) then goto Next

$ goto BadFile

$!

$ Next:

$ if (f$search(“pisysexe:YGW_’’P1’.out”) .nes. “”) then –

purge/keep=3 pisysexe:YGW_’P1’.out

$!

$ run/detach/uic=[system]/proc=”YGW_INT_‘’P1’”/priority=4 –

/input=pisysexe:YGW_’P1’.com –

/output=pisysexe:YGW_’P1’.out-

/working_set=512/maximum_work=1024/extent=2048 –

/pagefile=10000/buffer=20480 sys$system:loginout

$ exit

$!

$ BadParameter:


$ write sys$output “The Interface # Must Be Passed”$ exit

$!

$ BadFile:

$ write sys$output “YGW_’’P1’.Com does NOT Exist...”

$ exit

$! End of File

$

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:YGW_detach 1The name of the process will be “YGW_INT_#” as defined by the /proc flag to the run command in the above command file

The example YGW_detach.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 YGW_detach.com. If it is not passed, the command file will terminate with the error message:The Interface point source # must be passed.

2. YGW_detach.com searches for the existence of the PISysExe:YGW_E.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:Ifc1.com does not exist.

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

4. The YGW_INT_E process is started with the run command. Several actions are performed by the run command:

The name of the process is set to YGW_INT_E 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:YGW_E.com by the /input flag.

The standard output from the interface is redirected to the PISysExe:YGW_E.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 YGW_INT_EWhere E is the point source of the interface for this process.


BufferingFor complete information on buffering, please refer to the PI-API Installation Instruction..

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

Note: Change the Local Security Policy on Windows XP. 1. Open "Administrative Tools" from the control panel. 2. Open "Local Security Policy" from administrative tools. 3. Browse to "Security Options" under "Local Policies." 4. Double click on "System Objects: Default owner for objects created by members of the Administrators group." 5. Change the dropdown from "Object Creator" to "Administrators group."

The behavior of Bufserv should now be the same on XP as it was for NT4 and 2000.

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

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


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

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

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

Log On AsLog on as indicates the Windows user account under which the API Buffering service is setup to start automatically on reboot, or manually.

PasswordPassword is the name of the password for the Windows user account entered in the Log on as:above.

Confirm passwordYou must reenter the password again to verify you have typed it correctly both times.

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

Dependent ServicesThe Dependent services area lists the Windows services that depend on bufserv to function correctly.

Start / Stop ServiceThe Start / Stop buttons allow for the API Buffering service to be started and stopped. If the service is not created this box will show Not Installed.

After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv.

Service Startup TypeThe Startup Type indicates whether the API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.


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

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

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

Generally, the API Buffering service is set to start automatically.

Create/Remove ServiceThe Create / Remove buttons allow for the creation or removal of the API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.

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

Enable BufferingEnables the API Buffering feature.


Buffering

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

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

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


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


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


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


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


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


90

Max Theoretical Send RateThis is the theoretical max send rate which is calculated like this:max = MAXTRANSFEROBJS / SENDRATE * 1000Default value is 5000. This value is automatically calculated for the user and can not be changed.

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

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

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

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

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

The following settings are available for buffering configuration:

Keywords Values Default DescriptionBUFFERING 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


Buffering

(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 DescriptionPIHOMENODE string none Windows default server is in

pilogin.iniDSTMISMATCH 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)

Example piclient.ini File

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

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

92

Appendix A:Error and Informational Messages

A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id flag on the startup command line.

Message LogsThe location of the message log depends upon the platform on which the interface is running. See the UniInt End User Document for more information.

Messages are written to PIHOME\dat\pipc.log at the following times.

When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points.

As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.

If the /db is used on the command line, then various informational messages are written to the log file.

MessagesThe following error messages may appear in the PI application log file Pipc\Dat\Pipc.log:

Binary mode is invalid when TTY protocolAn attempt was made to use the “/b” command line argument for binary communication with RS-232 (TTY) serial communication. Binary mode can only be used with TCP/IP when communicating with an ECGW3 gateway (only if the gateway has this functionality).

Buffer allocation failedThe interface has run out of memory.

Can not output because of invalid data type [PI tag]The PI tag has been defined to output to a Yokogawa tag data type that has not been defined in the YGW_Oitem_#.txt file. See the YGW_Oitem_#.txt section above. This error is accompanied by a NOT_OUTPUT digital state for the PI tag.

Can not output because of invalid dig code [PI tag]The value of the digital output tag has not been written to the DCS because the code to be written is invalid for the tag. Consult OSI Technical Support for assistance. This error is accompanied by a NOT_OUTPUT digital state for the PI tag.

Can not output because of invalid point def [PI tag]The PI tag has been defined as a digital tag with a Location1 value of 3 (clip the value being written to the DCS if it is out of range). The value being written to the


DCS is out of range and clipping digital tags is inappropriate. This error is accompanied by a NOT_OUTPUT digital state for the PI tag.

Can not output because of invalid point status [PI tag]The value of the output tag has not been written to the DCS because its istat value is invalid. If the PI tag is a digital tag, the digital state that is to be written to the DCS is not valid for the PI tag (PI2 only—the state that was found must be in the digital state table between the zero and the span of the digital PI tag). If the PI tag is a numeric tag (PI2 or PI3), the value to be written is not valid (has an Istat value < 0). This error is accompanied by a NOT_OUTPUT digital state for the PI tag.

Can not output because out of range [PI tag]The value of the output tag has not been written to the DCS because the value is outside the range of the tag. This error only occurs for output tags that have a Location1 value of 2 (output tag with range checking). This error is accompanied by a NOT_OUTPUT digital state for the PI tag.

Connected to gateway successfullyThe interface has reconnected successfully to the gateway after a disconnect had previously been detected.

Digital state not found [Digital state string]The interface could not find the digital state string in PI. Check that the definitions of the LOOP and ALARM status digital states are defined correctly in PI.

Digital state not found [Digital state string(Converted digital state string)]The interface could not find the converted digital state string in PI. The converted digital state string applies to the strings defined in the YGW_STS_#.txt file (see the description of the “/dt” command line argument). Check that the definitions of the LOOP and ALARM status digital states are defined correctly in PI.

File not found [Filename]The interface cannot find the file specified. Ensure that the file exists and is in the proper location. For VMS, this is the same location as the interface program. For NT it is either in the same location as the interface program (when run interactively) or in the Windows system directory (when run as a service).

Initalize connection successfullyA connection has been made to the gateway successfully.

Invalid communication modeAn attempt to use a communication protocol other than RS-232 (TTY) or TCP/IP was made.

Invalid machine typeThe machine type specified by the “/mt” command line argument is invalid. Valid values are those specified in the description of “/mt” above.

Invalid retry countThe retry count specified by the “/rc” command line argument is invalid. A valid value is greater than or equal to 0.

Invalid starting digital state codeThe digital start code specified by the “/ds” command line argument is invalid. A valid value is greater than 0.


Invalid text sending countThe send text continuous count specified by the “/sc” command line argument is invalid. A valid value is greater than 0.

Invalid timeout periodThe timeout period specified by the “/to” command line argument is invalid. A valid value is greater than or equal to 0.

Invalid waiting timeThe wait time specified by the “/wt” command line argument is invalid. A valid value is greater than 0.

Not defined TAG GET or BLOCK GETThe interface cannot determine whether to read the scan class in BLOCK_GET mode or TAG_GET mode. Consult OSI Technical Support for assistance.

Output data type not definedThe interface has no valid output data types defined. The most likely reason for this is that the YGW_OItem_#.txt file contains no output type entries. See the YGW_Oitem_#.txt section above.

Output failed [PI tag]The value of the output tag could not be written to the DCS because the attempt to write it failed. This is either because the transmission from the DCS was corrupted or there was a Yokogawa data error. Data errors can be caused by three things: a) the specified tag does not exist, b) the transmission to the DCS was corrupted or c) the DCS is not in ready status. Data corruption is usually caused by hardware error.

Pi-api : PI API function error (API return code)A call to the PI API has failed. This error only occurs in conjunction with a PI Float64 tag.

Point definition error [PI tag] extended point type PI type code not supportedThis error only occurs if with PI3. A PI tag is being used that is of a type not supported by the interface. Supported types are: float16, float32, float64, int16, int32 and digital. PI type codes are as follows:

PI_Type_null 0 PI_Type_uint32 7 PI_Type_PI2 14

PI_Type_bool 1 PI_Type_int32 8 PI_Type_digital 101

PI_Type_uint8 2 PI_Type_uint64 9 PI_Type_blob 10

2

PI_Type_int8 3 PI_Type_int64 10 PI_Type_Pistring

105

PI_Type_char 4 PI_Type_float16 11 PI_Type_bad 25

5

PI_Type_uint16 5

PI_Type_float32 12

PI_Type_int16 6 PI_Type_float64 13


Appendix A: Error and Informational Messages

Point definition error [PI Tag] invalid Instrument tag [Current value]The Instrumenttag field of the PI tag contains invalid characters. Valid characters are those found on a computer keyboard except <SPACE> and lowercase alphabet characters.

Point definition error [PI Tag] invalid Location 1 (Current value)The Location1 field of the PI tag is invalid. Valid values range from 0 to 3.

Point definition error [PI Tag] invalid Location 4 (Current value)The Location4 field of the PI tag is invalid. Valid values range from 1 to the number of scan classes defined by the “/f” command line argument.

Point definition error [PI Tag] no Instrument tagThe Instrumenttag field of the PI tag is empty. It must contain the name of a Yokogawa tag (including data field).

Point definition error [PI Tag] Only input is supported for float64The PI tag is a float64 tag that has been designated to be an output tag (Location1 = 1,2 or 3). Float64 tags can only be used for input tags (from the DSc to PI).

Putsnapx error PI API return status, tag: PI Tag, pt: PI tag’s point ID, cstat: PI Tag’s IstatThe interface failed to write the value to the snapshot of the PI tag (pisn_putsnapshotx() function of the PI API failed).

Putsnapx system error PI API return status, Previous PI API return statusThe interface failed to write the value to the snapshot of the PI tag because of a system error (pisn_putsnapshotx() function of the PI API failed).

YGIConnect failed (Failed status)Attempts to make a connection to the gateway failed. The failed status is indicated by the following table:

-1 Sending -2 Receiving

-3 No data to receive -4 Protocol error (received "ER")

-5 Timeout -6 Incorrect terminate characters

-7 Failed to receive -8 Failed to send

-9 Mismatch data size -10 Port closed

-11 Overflow error -12 Invalid port

-13 Connection failed -14 Set communication state failed

-15 Set communication mask failed -16 Communications setup

failed

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

96

Error Descriptions on NTOn NT descriptions of system and PI errors can be obtained with the pidiag utility:

NT:\PI\adm\pidiag –e error_number


Revision HistoryDate Author Comments

3-Jan-97 MMG Modified for PI 3 on NT and Unix11-Jun-97 RGM Updated6-Aug-97 RGM Updated to include NT, HPUX and AIX4-Apr-99 RGM Complete overhaul and reformat26-Jul-99 RGM Removed Unix Installation, Added error messages3-Mar-00 RGM Added comments, added NT RS-232 support11-May-05 MPK Put into Interface_Manual_Skeleton.doc V1.15

format.18-May-05 MPK Fixed headers and footers and TOC.28-Jul-05 MPK Removed all references to /g command line

parameter. This is not supported. Added section on configuring the interface using the PI-ICU.


yokogawa ygw interface to the pi system -...

Documents