Yokogawa Gateway
Interface to the PI System

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
Internet /
World Wide Web /
Bulletin Board / (510) 895-9423
Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible)
8 data bits, 1 stop bit, no parity, up to 14400 bps download
protocols: Xmodem, Ymodem, Zmodem, Kermit
Mail / OSI Software, Inc.
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland /
OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand

Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

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

 1997 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

9/19/1997 8:27 AM1

Table of Contents

Introduction......

Point Database......

Point Source (PI2 only)

Digital State Table (PI2) Digital State Sets (PI3)

Point Definition

Functional Overview......

Hardware Configuration

Software Configuration

Data I/O

Interrupt Messages

Testing of Communication

Timeout Processing

Interface Files

Interface Processing......

Event Counter Tag (PI2 Only)

Logging File

Error Handling

Pre-Installation Checklist......

VMS Installation......

Basic Installation

Stopping the Interface

Permanent Installation

Windows NT Installation......

Basic Installation

Permanent Installation

Unix Installation......

Prerequisites......

PI Interfaces......

Stopping the Interface......

Permanent Installation......

Appendix......

Yokogawa Gateway Document

Interface Messages

Digital States List

January 9, 19971

Introduction

The Yokogawa Gateway Interface provides communication between PI and the Yokogawa CentumXL, CentumV and MicroXL DCS systems. Communication is done as follows:

  • CentumXL – through the Yokogawa ECGW3 Gateway via TCP/IP or through the Yokogawa ECGW* gateway via RS-232.
  • CentumV – through the Yokogawa CGWU gateway via RS-232.
  • Micro-XL – direct connection via TCP/IP or RS-232. An Ethernet card and vendor software are required for TCP/IP

Note This interface supports the above DCSs via RS-232 on VMS only. If running on other platforms, a protocol converter from TCP/IP to RS-232 can be used.

DCS System / Communication / Protocol / Gateway
CentumXL / Ethernet / TCP/IP / ECGW3
CentumXL / RS-232C / TTY / ECGW*
CentumV / RS-232C / TTY / CGWU
MicroXL / Ethernet / TCP/IP / Vendor Software
MicroXL / RS-232C / TTY / none

The interface can run on the PI home node, a PINet node or a PI-API node. VMS systems require DEC TCP/IP (UCX) for the TCP/IP protocol.

The features supported by the interface are the following:

Supported Features
Sign-up for updates / Yes
Exception Reporting / Yes
PINet / Yes
Outputs / Yes
Vendor Software required / Only for MicroXL TCP/IP
Failover / No
Maximum points / Depends on Gateway

Figure 1 Installation Diagram for VMS

Figure 2 Installation Diagram for NT, Unix if using a protocol converter

Point Database

The interface uses “Tag number and data type” to specify the instrument tag on the DCS. PI tags should specify Yokogawa DCS tagnames. The interface cannot request data by point number (station, unit number, and loop number).

The interface collects input data either on a given scan frequency or when a specified event occurs. Output data is output to the DCS on event basis.

Input / time / PI data updated based on scan class period
event / PI data updated based on event point
Output / event / Yokogawa data updated based on source point

The interface requires an event counter tag (also called an I/O rate counter tag) to be specified. Additionally, it is necessary to define the loop status and the alarm status digital states in the PI digital state table. These requirements are discussed below.

Point Source (PI2 only)

Select a point source code which has not been used by the PI system or any other interfaces and set the location parameter limits as shown below.

Location1 / Location2 / Location3 / Location4 / Location5
Minimum / 0 / -* / - / 1 / -
Maximum / 3 / - / - / x** / -

-* = not used.

x** = maximum number of scan classes that is user configurable.

Digital State Table (PI2)Digital State Sets (PI3)

Digital states specific to an interface must be entered into the digital state table (PI2) or individual digital state sets (PI3) prior to starting the interface. For VMS use any digital states within the PI system except for the states between 193 and 320 which are reserved. For PI3 this restriction applies only to the system digital state set.

When the data type of a tag is either a loop status (LS), alarm status (AS) or a sub status (LOOP,ALRM), its value is saved as digital state. These tags must be created as digital PI points and have the required digital states entered into the digital state table (PI2) or digital state sets (PI3). The Interface Status is used when a point is in a state that is not a valid value and is not a standard PI system digital state.

The following tables show the list of digital states that must be entered into the digital state table (PI2) or individual digital state sets (PI3) for Loop Status and Alarm Status points and also the interface status. For PI3, the interface status set must be added to the system digital state set and NOT be defined as a separate set. The starting digital code for the interface point status is specified by the “/ds” in the interface startup file PISysExe:Ygw_#.com (VMS) or Ygw_#.bat (NT) or ygw_#.sh (Unix) where # represents the point source character used by the interface.

CentumXL MicroXL
MAN / AUT / CAS / PRD / DDC / SPC / CBM / CBA
LOOP STATUS / CBC / BUM / BUA / OOP / SEMI / LS01 / LS02 / LS03
LS04 / LS05 / CLP+ / CLP- / CND / STOP / RUN / HOLD
SUB1 / SUB2 / SUB3 / SUB4 / SUB5 / LOCK / OFF
NR / +DV / -DV / HI / LO / BPRE / BEND / NPLS
VEL / IOP / HH / LL / MHI / MLO / CAL / OOP
ALARM STATUS / ANS+ / ANS- / TRIP / PERR / ALM / HDV / LDV / ALM1
ALM2 / ALM3 / ALM4 / ALM5 / ALM6 / LEAD / PRE / END
AOF / INT / ERR / ANS1 / ANS2 / ANS3 / ANS4 / ANS5
ANS6 / PAUS
CentumV
OOP / BUM / BUA / MAN / MAN+ / MAN- / MANC / AUT
AUT+ / AUT- / AUTC / CBM / CBM+ / CBM- / CBMC / CBA
LOOP STATUS / CBA+ / CBA- / CBAC / PRD / PRD+ / PRD- / PRDC / CAS
CAS+ / CAS- / CASC / SPC / SPC+ / SPC- / SPCC / DDC
DDC+ / DDC- / DDCC / CBC / CBC+ / CBC- / CBCC / CMP
ALARM STATUS / CAL / IOP / HI / LO / +DV / -DV / VEL / MHI
MLO / NR / ON / OFF
Interface Use
INTERFACE / NO_BLOCK / BAD_BLOCK / R_OVER_DIG / BAD_DIGSTATE
STATUS / INT_MINUS / CONN_CLOSED / INIT_ERROR / NOT_OUTPUT
OUTPUT_ERR

Point Definition

Point Source

This should match the point source created for this interface. Specify this point source using “/ps” in the interface startup file PISysExe:Ygw_#.com (VMS) or Ygw_#.bat (NT) or ygw_#.sh (Unix) where # represents the point source character used by the interface.

Instrument Tag

This field contains the name of the Yokogawa tag name to be accessed. The acceptable tag formats for the Yokogawa systems are uppercase, alphanumeric characters combined with optional character “–”. Additionally, the data type should separated from the tag number by a “,”. If a point has an invalid definition in the instrument tag, the interface writes a message to the log file and will not add it to its point list.

Note Lowercase is invalid for this system.

Source Tag

This field is used only for output points. This field specifies the PI point that is the data source for the output data. If no source tag is specified the Yokogawa output point itself is used as the data source. Data is output to the DCS on an exception basis (when the value of the data source is an exception) and at interface startup.

Extended Descriptor

For input points, this field can be used to specify a PI event tag which will trigger data collection for the point. When value of the event tag has changed, the interface accesses the DCS and reads in a new value for the point. When an event tag is specified, the scan class specified in location 4 is ignored.

/event=PI point name

Scan Flag

The Scan flag is used by the interface to control processing of a point. A value of ON for the point indicates that it should be serviced by the interface, Edit the point attributes to set scan OFF to make the interface delete it from its list of points. The value of SCANOFF will be written to the point when its scan flag has been turned off. Change it back to ON when data collection for the point is to resume.

Point type, Precision

This field specifies the point type of a PI point. Use R (PI2) or Float32/Float16 (PI3) for real data, I (PI2) or Int32/Int16 (PI3) for integer data and D (PI2) or Digital (PI3) for digital data.

For PI2, real data can stored in the archive as SCALED or FULL precision. For SCALED real data, the input value is stored as a scaled value between 0 and 32767 in the PI archive. FULL precision real data is saved as a 4 byte floating point value. For PI3, the equivalent of SCALED and FULL data types are Float16 and Float32, respectively. Values which can be less than 0 should be saved as real data since the range for PI integers is between 0 and 32767. If input value of integer point is minus, the digital state INT_MINUS will be written to PI.

Location 1

This field determines whether the point is an input or output . Use 0 for input points and 1, 2 or 3 for output points. 1 means the interface updates the DCS without checking the validity of the value. 2 means the interface updates the DCS only if the value is within the PI range of the point. An error message is logged if the value is out of range and no output is done. 3 means the interface will clamp the value sent to the DCS if it is outside of the PI range for the point. If the value exceeds the high range the value output to the DCS will be the high range. If the value is less than the low range the value output to the DCS will be the low range. Values within the high and low range for the point will be sent out as received.

Location 4

This field is used to specify the scan class number. The period of each scan class is specified in the startup file PISysExe:Ygw_#.com (VMS) or Ygw_#.bat (NT) or ygw_#.sh (Unix) where # represents the point source character used by the interface.

Along with each scan class frequency chosen (/f), an associated data access type (/g) must be specified for each scan frequency. The choices are:

  • TAG GET (0)
  • BLOCK GET (1)

BLOCK GET is recommended because it results in a much more rapid response from the gateway than TAG GET. If BLOCK GET is specified for a scan class, the interface automatically creates tag groups. A block consists of 32 points. For CentumXL and CentumV 256 blocks can be defined in one DCS system (max. 8192 points). For MicroXL the number of definable blocks may vary depending on the available memory.

If you define more points than the maximum allowable number of points, the interface rejects them and writes out an error message for each tag over the limit. If this occurs then these points can then be read using the TAG GET option with one or more other scan classes. The number of tags that can be read using TAG GET is not restricted.

Zero/Span

This field specifies the range of the point’s zero and span. If the value of a SCALED real or float16 point is outside of the specified range of the point, either the digital state UnderRange or OverRange will be written to the point. If the point is specified as a FULL or Float32 precision point, the input value is written to PI even if it is out of range.

Digital Start Code/Digital Number (PI2 only)

For digital points, the starting digital state code and number of digital states correspond to the zero and span for real or integer points. It is necessary that the digital states be defined in the digital state table in advance. The starting digital state code and number digital states of the point should be matched with those that are in the digital state table.

Digital Set (PI3 only)

For digital points, the digital set contains the name of a digital state set that contains the possible digital states for that a point. It is necessary that the digital states sets be defined in advance. More than one point may refer to a single digital state set.

Other Parameters

Other parameters that are used by interface:

  • Tag Name
/
  • Exception Min Time
/
  • Compress Min Time

  • Descriptor
/
  • Exception Max Time
/
  • Compress Max Time

  • Typical Value
/
  • Archiving Flag
/
  • Resolution Code

  • Engineering Units
/
  • Compression Flag

  • Exception Deviation
/
  • Compress Deviation

Parameters that are not used by interface:

  • Filter Code
/
  • Conversion Factor
/
  • Location 3

  • Square Root Code
/
  • Long Tag Name
/
  • Location 5

  • Totalization Code
/
  • Location 2

Functional Overview

Hardware Configuration

The interface runs under VAX & Alpha OpenVMS, AIX Unix, HPUX Unix and Intel NT. The computer must be connected to the Yokogawa DCS system by the communication protocol as described in the introduction.

The setting of the DCS system and the interface are as follows:

TCP/IP

The name of the host computer where the interface will run and its corresponding IP address must be specified on the DCS.

The following items must also be defined.

  • communication text = character mode/binary mode
  • delimiter character = CR-LF(character mode)/none(binary mode)
  • sequence numbers = yes
  • interrupt message mode = character mode

In the interface startup file PISysExe:Ygw_#.com (VMS) or Ygw_#.bat (NT) or ygw_#.sh (Unix) the gateway host name, IP address of the gateway, and Ethernet port number are specified.

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 and should not exceed the limits of the DCS.

[TTY] (VMS only)

The following suggested settings should be specified on the DCS system.

  • communication rate = 9600 bps
  • communication code = 8 bit
  • parity = even
  • stop bit = 1 bit
  • text = ASCII
  • XON/XOFF control = yes
  • sequence number = yes

The interface requires that port settings be specified. This is done in the command file PISysExe:Ygi_Setterm.com.

The following settings are suggestions but they must match the settings specified on the DCS. The protocol does not support sending text continuously.

  • communication rate = 9600 bps
  • communication code = 8 bit
  • parity = even
  • nowrap
  • notype_ahead
  • modem/nomodem(correspond to DCS system

Software Configuration

If running under VMS, the interface requires DEC TCP/IP (UCX). The DCS system must support the protocol chosen for communication to the interface; i.e. either TCP/IP or RS-232.

Data I/O

The interface supports both data input from the DCS system and data output to the DCS system.

There are two ways to input data from the DCS to PI. The interface initiate reads to the DCS based either on a scan class period or on an event tag. If an event tag is specified, PI data is updated when value of the event tag has changed.

Output data sent to the Yokogawa DCS system is output on an event. It is sent to the DCS when the value of the data source tag has changed. The point itself is regarded as a source tag if no other PI source tag has been defined. If the output point contains a source point, the interface will update this tag with the value output to the DCS, or an error status if an error occurred during the write operation.

The allowable DCS data types that the interface can output to are restricted to those listed in the file ygw_oitem_#.txt. The user can modify the file if necessary. The default data types contained in the file are listed below:

List Of Output Data Type
HH,LL,PH,PL,VL,DL,MH,ML,P,I,D

Be careful not to loose precision and overflow because the length of output data depends on that of DCS tags. The data may overflow or loose precision if it is over that of DCS tags.

Interrupt Messages

The interface can read specified messages from the DCS system. The messages that can be read are specified in the file ygw_msg_#.txt. This file can be edited by the user to specify which messages the interface will receive from 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 log files and to the PI event log.

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

Testing of Communication

The communication between the DCS and the host computer where the interface runs should be verified prior to starting the interface. Confirmation of the connection with the gateway can be made by using PING or executing the test program ygi_test if the communication is via TCP/IP in character mode. If communication is via TCP/IP in binary mode then verification can be done using PING or by executing the test program ygi_testb. For TTY communication, execute the test program Ygi_Test (VMS only). Execute the test programs as follows:

YGI_TEST

VMSExecute PISysExe:Ygi_Test.exe from the RUN command.
NTExecute Ygi_Test.exe from the DOS prompt.
UnixExecute ygi_test from the shell.