Pi - Ygw - 1.8.0.1 3

Yokogawa YGW
Interface 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 techsupport@osisoft.com
World Wide Web http://www.osisoft.com
Mail OSIsoft OSI Software, Ltd

P.O. Box 727 P O Box 8256
San Leandro, CA 94577-0427 Symonds Street
USA Auckland 1035 New Zealand
OSI Software GmbH OSI Software, Asia Pte Ltd

Hauptstrae 30 152 Beach Road
D-63674 Altenstadt 1 #09-06 Gateway East
Deutschland Singapore, 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 reserved

777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction.................................................................................................................... 1
Reference Manuals......................................................................................................1
Supported Features......................................................................................................2
Communication Configuration......................................................................................3
Yokogawa Gateway Setup Diagram............................................................................4
Hardware Configuration................................................................................................4
Micro XL Communication Requirements......................................................................5
Ethernet Communication..........................................................................................5
Serial Communication...............................................................................................6
Principles of Operation.................................................................................................7
Gateway 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.........................................................................................15

Naming 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......................................................................................21
Naming Conventions and Requirements....................................................................21
Interface Installation Procedure..................................................................................22
Permanent Installation............................................................................................24
Communication Testing Programs............................................................................25
Digital States................................................................................................................ 27
PointSource.................................................................................................................. 31
PI Point Configuration.................................................................................................33
Point 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...............................................................................39

Configuring Performance Points with PI-ICU (NT-Intel).............................................39
Configuring Performance Points Manually.................................................................40
I/O Rate Tag Configuration..........................................................................................43

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

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

NT............................................................................................................................... 85
VMS............................................................................................................................ 85
Security......................................................................................................................... 87
NT............................................................................................................................... 87
VMS............................................................................................................................ 87
Starting / Stopping the Interface on NT......................................................................89

Starting Interface as a Service...................................................................................89
Stopping Interface Running as a Service...................................................................89
Starting / Stopping the Interface on VMS...................................................................91

Starting a Detached Process......................................................................................91
Stopping..................................................................................................................... 93
Buffering....................................................................................................................... 95
Configuring Buffering with PI-ICU (NT-Intel)...............................................................95
Configuring Buffering Manually..................................................................................99
Example piclient.ini File............................................................................................100
Appendix A: Error and Informational Messages.....................................................101

Message Logs.......................................................................................................... 101
Messages.................................................................................................................101
System Errors and PI Errors.....................................................................................104
Revision History........................................................................................................... 107
Yokogawa YGW Interface to the PI System v

Introduction
The 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 4.0 3.1 1.2
NT
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 62
Reference Manuals
OSIsoft
 PI Server manuals
 PI-API manual
 UniInt End User Document
Yokogawa YGW Interface to the PI System 1

Supported Features
Feature Support
Part Number PI-IN-YO-YGW
Platforms VMS / Alpha VMS / NTI (4, 2000, XP)
APS Connector No
Point Builder Utility No
ICU Control Yes
PI Point Types Real, digital, int16, int32, float16, float32,
float64, string
Sub-second Timestamps No
Sub-second Scan Classes No
Automatically Incorporates PI Point Yes
Attribute Changes
Exception Reporting Yes
Outputs from PI Yes
Inputs to PI: Scan-based / Unsolicited / Scan-based, Event tags
Event Tags
Maximum Point Count Limited only by YGW gateway
Uses PI-SDK No
PINet to PI 3 String Support No
Source of Timestamps PI Server
History Recovery No
Failover No
* UniInt-based Yes
Vendor Software Required on PI-API / No
PINet Node
* Vendor Software Required on Foreign Yes, only for Micro XL. See Micro XL
Device Communication Requirements section
below.
* Vendor Hardware Required Yes, only for Micro XL. See Micro XL
Communication Requirements section
below.
* Additional PI Software Included with Yes, YGI_Test.exe and YGI_TestB.exe
Interface connection test programs
Device Point Types INT, FLT, CHR
* See paragraphs below for further explanation.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an
OSIsoft-developed template used by our developers, and is integrated into many
interfaces, such as the PI-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 Required
Vendor 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 Required

A 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 Software
See section Communication Testing Programs on page 25 for explanation.
Communication Configuration
The 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:
Communicatio Interface
DCS System Gateway
n Platform
VMS, Windows
Centum V RS-232C TTY CGWU
NT
VMS, Windows
ECGW*
NT
VMS, Windows
RS-232C TTY ECGW2
NT
Centum XL
VMS, Windows
ECGW3
NT
VMS, Windows
Ethernet TCP/IP ECGW3
NT
VMS, Windows
RS-232C TTY No Gateway
NT
Micro XL
VMS, Windows
Ethernet TCP/IP Software Emulator
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 Configuration
To be able to communicate with the gateway, the correct protocol parameters must be set
up on the DCS.
Ethernet TCP/IP
The 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
Character Mode Character Mode
Mode
See the Command-Line Parameters section on page 62 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 62) and should not exceed the limits of the DCS.
4
RS-232 Serial Communication
The 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.
NT Command
VMS Port
DCS Settings Line
Settings
arguments
Communication
9600 bps (opt) 9600 bps (opt) /bps=9600
Rate
Communication
8 bit (opt) 8 bit (opt) /bs=8
Code
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
Yes N/A N/A
Numbers
NoWrap,
Other Settings N/A NoType_Ahead, N/A
NoModem
Micro XL Communication Requirements

The 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 Communication
Yokogawa 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
Station Type Y2K Revision CPU Card
Number
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 Operation
When 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 62.
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 62.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 Failover
The 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 Tags
Input 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-Based
An 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-Based
An 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 Tags
Output 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 Update

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

An 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 tag
RmpSk_Exc, 27
*
* PI-YGW interface exceptions IORate tag
YGW_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 File
Error 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 62 .
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:ss
YGW 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:03
YGW 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 Checklist
For 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_#
d. Insert a new Unsetterm command for after each stop command that refers to
an interface using TTY serial communication.
@PISysExe:YGI_UnSetterm xxxx
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 Output
Location2 is not used.
Location4 is the scan class (and, subsequently, the data access type)
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 NT
OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly
on the PI Server node. A PI Interface Node is any node other than the PI Server node
where the PI Application Programming Interface (PI-API) has been installed (see the
PI-API manual). With this approach, the PI Server need not compete with interfaces for
the machine’s resources. The primary function of the PI Server is to archive data and to
service clients that request data.
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 Requirements

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

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

in the 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 Directory

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

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

The 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 Utility
The PI-Interface Configuration Utility provides a user interface for creating, editing, and
deleting the interface service:
Service Configuration
Service Name
The Service to Add box shows the name of the current interface service. This service
name is obtained from the interface executable.
Display Name
The Display Name text box shows the current Display Name of the interface service. If
there is currently no service for the selected interface, the default Display Name is the
service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft
suggests that the prefix “PI-” be appended to the beginning of the interface to indicate
that the service is part of the OSI suite of products.
Service Type
The 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.
Dependencies
The 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 Button
To add a dependency from the list of Installed services, select the dependency name, and
click the Add button.
- Remove Button
To 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.
Create
The 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 Service

To 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.
Status of
the ICU Status of the Service
Interface installed or
Service uninstalled
18
Installing the Interface Service Manually
One 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 implemented
Manual 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 implemented
Manual service YGW.exe –install –depend tcpip
Automatic 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 VMS
One 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 Requirements

In 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.OLB
YGI_UNIINT.OBJ YGI_TEST.OBJ YGI_TESTB.OBJ
YGW_Setup.com
This 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.com
These link the object files to form the following executables:
Ygw_Int.exe
Ygi_Test.exe
Ygi_TestB.exe

PISysExe:YGI_Setterm.com
This 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.com
This file resets the serial port to its default state. Specify a port number when executing
it.
PISysExe:YGW_Detach.com
This 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 Procedure

Interface 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. 85. 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.
The interface backup saveset must be reblocked before the
REBLOCK.EXE
saveset can be unpacked. See the REBLOCK.README.
The following procedure is typical.
22
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 Directory
YGW.OBJ Object file for the interface.
UNIINT.OBJ Object file for the interface
LINK_YGW.COM Command procedure for re-linking the executable.
PISysExe Directory
YGW_INT.EXE Interface executable.
YGW1.COM Startup command file for interactive processes.
Startup command file for detached processes (the
YGW_DETACH.COM 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.

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

You can stop the interface by executing the command file
@PiSysExe:Stop YGI_Int_#
where # is the point source for the interface.
Permanent Installation
Four 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 xxxx
2. Add a new line for each process required, supplying the point source as a parameter.
3. Edit PISysMgr:SiteStop.com by inserting a new stop command line for each process
@PISysExe:Stop YGW_INT_#
4. Insert a new Unsetterm command for after each stop command that refers to an
interface using TTY serial communication.
@PISysExe:YGI_UnSetterm xxxx
24
Communication Testing Programs
Filenames: 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 PI

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

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

0
Host Name ->
localhost
Port No (Space:Default 31000) ->
31000
Input Command
(Option) #A: Show ASCII Code
#N: Return Normal Mode
NULL: Exit
->
G01 TG 2 FIC-001,PV FIC-002,PV
A01 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 States
For more information regarding Digital States, refer to the PI Server documentation.
PI 2 Home Node
Digital 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 63 for more information).
For more information, see the DA manual.
PI 3 Home Node
Digital State Sets

PI digital states are discrete values represented by strings. These strings are organized in
PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated
from 0 to n to represent different values of discrete data. For more information about
PI digital tags and editing digital state sets, see the PI Server manuals.
An interface point that contains discrete data can be stored in PI as a digital tag. A
Digital tag associates discrete data with a digital state set, as specified by the user.
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 77.
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 63 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 Set

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

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

PointSource
The 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 Attributes

If 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 Nodes
The 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 Nodes
No 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 Configuration
The 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
Tag
A tag is a label or name for a point. Any tag name can be used in accordance with the
normal PI point naming conventions.
PointSource
The 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.
PointType
Typically, 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 Nodes
Float16, 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.
Location1
This 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.
Updates the DCS without checking the range of the
1
value.
Updates the DCS only if the value lies within the PI
Output 2
range of the tag.
Updates the DCS, clipping the value to fall within the
3
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.
Location2
This attribute is not use for the Yokogawa YGW interface.
Location3
Location4
This 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 62. 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.

Location5
InstrumentTag
For 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.
ExDesc
This 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=CTD158
Here, 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
64 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-98
The 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 Points
For 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 Nodes
The 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/Span
This 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 Configuration
One 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.
Create
To create a Performance Point, right-click the line belonging to the tag to be created, and
select Create.
Delete
To delete a Performance Point, right-click the line belonging to the tag to be deleted, and
select Delete.
Correct
If 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 Details
Tag Tag name that appears in the list box
Point Source Point Source for tags for this interface, as specified on the first tab
Compressing Off

Excmax 0
Descriptor Interface name + “ Scan Class # Performance Point”
Rename
To 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 Manually

Performance point configuration is the same on all operating system platforms.
Performance points are configured as follows.
1. Set the extended descriptor to:
PERFORMANCE_POINT
or to:
PERFORMANCE_POINT=interface_id
where 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 Configuration
An 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 Node

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

The 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 Status
The 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 File
The 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 Counter
The 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.
Tagname
The tag name listed under the Tagname column is the name of the IORates tag.
Snapshot
The 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 Options

Create
Create the suggested IORates tag with the tag name indicated in the Tagname column.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter
Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
Configuring I/O Rate Tags Manually

There are two configuration steps.
1. Configuring the PI Point on the PI Server
2. Configuration on the Interface Node
42
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 Nodes
Create an I/O Rate Tag with the following point attribute values.
Attribute Value
PointSource L
PointType float32
Compressing 0
ExcDev 0
Configuration on the Interface Node

For 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 Nodes
1. 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.

Open VMS Nodes

I/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, x
where 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
44
Startup Command File
Command-line arguments can begin with a / or with a -. For example, the /ps=M and –
ps=M command-line arguments are equivalent.
Notes for NT
For 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 source
The 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.
46
The General tab on the PI-ICU should now look similar to this:
The next step is to configure at least one scan class.

Scan classes
Scan 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 Tab
Since 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.
48
Additional optional parameters that can be configured on the Uniint tab shown above
include:
Performance and Behavior - Scan performance summary

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

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

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

Select 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 Levels
The 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 Tab

Select the ygw tab to configure startup parameters that are particular to the PI-Yokogawa
YGW Interface.
Gateways
The 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).
50
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/IP
Choosing 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.
52
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 Port

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

This 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.
54
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 Rate

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

This 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 – Parity
This 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.
Parameter Definition
Setting
/par=E Even Parity
/par=M Mark Parity
/par=N No Parity
/par=O Odd Parity
/par=S Space Parity

Gateways – Stop Bits
The 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 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.
56
Other Tab
General - Extended point source

The 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 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_#.t Yes For specifying Yokogawa types for output points.
xt
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 states

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

Check 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 - Timeout
The 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=#.
58
Communication – Communication Retry count
This 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 count

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

Check ‘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 mode

Some 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 67.
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.
60
Additional Parameters
This 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 VMS

For 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 Parameters
Parameter Description
/b
Optional 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.
/cl
Optional 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.
62
/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 77.
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.

/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.
64
/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:21
YGW 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
ECGW*,
/mt=ECGWT ECGW2, RS-232 Serial TTY
ECGW3
/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.

/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 77–77.
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.
66
/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
Arg Setting Suppressed State Suppressed State
Setting
/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

/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=1
Means 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=1
If this argument is not used the wait time defaults to 0 seconds.
68
/gw=xxxxx
Required only if using Gateway Host Name
Ethernet TCP/IP If 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.15
To 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.

/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=31000
The 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.
70
/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- Serial Port Name
232 serial This argument specifies the machine’s TTY terminal name
communication (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=x
Required 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=x
Optional 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=E
would produce messages in the log such as:
31-Jul-98 09:05:03
YGW 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
interface log file.

Note: The length of the string defined by this argument must not
exceed 9 characters.
/f=SS
or Scan Class
/f=SS,SS The /f flag defines the time period between scans in terms of hours
or (HH), minutes (MM), and seconds (SS). The scans can be scheduled to
/f=HH:MM:SS occur at discrete moments in time with an optional time offset
or specified in terms of hours (hh), minutes (mm), and seconds (ss). If
/f=HH:MM:SS,hh:
HH and MM are omitted, then the time period that is specified is
mm:ss
assumed to be in seconds.
Each instance of the /f flag on the command line defines a scan class
Required for reading
scan-based inputs. At for the interface. There is no limit to the number of scan classes that
least one scan class can be defined. The first occurrence of the /f flag on the command
must be defined for line defines the first scan class of the interface; the second occurrence
the interface to defines the second scan class, and so on. PI Points are associated with
operate correctly. 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:07
or, equivalently:
/f=60,5 /f=7
The 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) + offset
where 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 Classes
One can also specify sub-second scan classes on the command line
such as
/f=0.5 /f=00:00:00.1
where 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
Wall Clock Scheduling
72
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:port
Optional 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
/stopstat
or Shutdown Digital State
/stopatat= If the /stopstat flag is present on the startup command line, then
digstate the digital state Intf shut will be written to each PI Point when the
Default: interface is stopped.
/stopstat= If /stopstat=digstate is present on the command line, then the
”Intf shut” digital state, digstate, will be written to each PI Point when the
Optional 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.

/ec=x
Optional 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.”
/sio
Optional 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.
/q
Optional Queue Snapshots and Exceptions
not implemented for When the /q flag is present, Snapshots and exceptions are queued
interfaces on VMS before they are sent to the PI Server node.
nodes 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.
/sn
Optional 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.
74
Sample YGW.bat File
The following is an example file:
REM
--------------------------------------------------------------------
-
REM This command procedure passes the required parameters to
REM initialize the Yokogawa YGW interface.
REM
REM Required Command-Line Arguments
REM /ps=x Point source character. Default is none
REM /f=HH:MM:SS Scan class definitions
REM /gw=host(TCP/IP) The gateway name or IP address
REM /term=x(RS-232) The name of the terminal (VMS) or
REM port (Win) for serial comm.
REM
REM Optional Command-Line Arguments
REM /host=host:port Name of PI home node:port number.
REM Default is localhost:5450
REM For a PI2 server, port is 545
REM For a PI3 server, port is 5450
REM /b Communicate to the gateway in binary mode
REM Default is False
REM /cl Write communication text protocol to pipc log
REM /db[=#] UnitInt debug level
REM /ds=# Digital start code for interfac-specific system
REM digital states
REM Default=1
REM /dt=# Use digital state lookup table
REM /ec=# Event count number
REM /eps=# Extended point source
REM /id=# Interface ID that is logged for each message in
REM pipc log
REM /lg Gateway communication debug messages
REM /ms Read interrupt messages (from data port)
REM /mt=xxxxx Machine type
REM /path=dir Sets the interface text file path
REM /perf=# Hours between performance monitor summaries
REM (0=off)
REM /q Queue data input
REM /rc=# Number of times to retry if interface fails to
REM connect to gateway
REM /sio Suppress initial output
REM /sc=# Max number of strings to send to gateway
REM at a time
REM /sds[=#] Suppress interface-specific system digital
state
REM (0=NO_BLOCK)
REM /sn Snapshot input data
REM /stopstat=digstateDigital state to write to point when interface
REM is stopped
REM /to=# The gateway communications timeout in seconds.
REM Default=10
REM /wc=# Wait count. The number of seconds between
REM connection retries.
REM /wt=# Wait time. The number of seconds between calls
REM to gateway
REM
REM Optional arguments for Ethernet TCP/IP
REM /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 specified
REM
REM Optional arguments for RS-232 Serial
REM /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 arguments
REM No spaces within argument.
REM
REM
--------------------------------------------------------------------
-
REM Revision History
REM Date Author Comment
REM 18-May-05 RGM -- Initial version --
REM
--------------------------------------------------------------------
-
REM
REM Sample command line
REM
YGW.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=30
REM
REM end of YGW.bat
76
Interrupt Messages Switch File
Filename: 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 ON
2 OFF
3 ON
7 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:23
YGW 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 62.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 File

Filename: 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 D
Each 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 File

Filename: 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>
...
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,Manual
AUT,Auto
CAS,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 Manual Auto Cascade PRD DDC SPC CBM CBA

MICRO XL CBC 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 63 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 1999
YGW D> file not found [YGW_Sts_Y.txt]
78
Interface Node Clock
NT
The 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.
VMS
By 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.95.
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 Service

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

If 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 –stop
The 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 Process

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

Stopping
To stop the interface, issue the following command:
@PISysExe:stop YGW_INT_E
Where E is the point source of the interface for this process.

Buffering
For 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 Tab
The Service tab allows for some API Buffering service configuration. For further
configuration changes, use the Services applet.
Service Name
The Service name displays the name of the API Buffering Service.
Display Name
The Display name displays the full name associated with the API Buffering service.
Log On As
Log on as indicates the Windows user account under which the API Buffering service is
setup to start automatically on reboot, or manually.
Password
Password is the name of the password for the Windows user account entered in the Log
on as:above.
Confirm password
You must reenter the password again to verify you have typed it correctly both times.
Dependencies
The Dependencies lists the Windows services on which the API Buffering service is
dependent.
Dependent Services
The Dependent services area lists the Windows services that depend on bufserv to
function correctly.
Start / Stop Service

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

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

 If the Auto option is selected, the service will be installed to start automatically
when the machine reboots.
 If the Manual option is selected, the interface service will not start on reboot, but
will require someone to manually start the service.
 If the Disabled option is selected, the service will not start at all.
Generally, the API Buffering service is set to start automatically.
Create/Remove Service
The 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 Tab
The Settings tab allows for configuration of the 7 configurable settings used by API
Buffering. Default values are used if no other value is provided.
Enable Buffering
Enables the API Buffering feature.

Buffering
Maximum File Size

Maximum buffer file size in kilobytes before buffering fails and discards events. Default
value is 100,000. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value,
click the Apply button.
Send Rate
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server
(milliseconds). Default value is 100. Range is 0 to 2,000,000.
Primary Memory Buffer Size

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

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

Max transfer objects is the maximum number of events to send between each
SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.
Pause Rate
When buffers are empty the buffering process will wait for this number of seconds before
attempting to send more data to the home node. Default value is 2. Range is 0 to
2,000,000.
Retry Rate
When the buffering process discovers the home node is unavailable it will wait this
number of seconds before attempting to reconnect. Default value is 120. Range is 0 to
2,000,000.
92
Max Theoretical Send Rate
This is the theoretical max send rate which is calculated like this:
max = MAXTRANSFEROBJS / SENDRATE * 1000
Default 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 Manually

Buffering is enabled through the use of a configuration file, piclient.ini. Unless this
file is modified to explicitly enable buffering, the PI-API will not buffer data, sending
data directly to the home node.
There are no additional steps needed to install buffering after installing the PI-API. The
delivered PI-API library supports both buffered and un-buffered calls.
Note: When buffering is configured to be on, the bufserv process must be started
before other programs using the PI-API, so that these programs can access the shared
buffering resources. Any program that makes a connection to a PI Server has this
requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The

file is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat)
under Windows NT. This file follows the conventions of Microsoft Windows
initialization files with sections, keywords within sections, and values for keywords. All
buffering settings are entered in a section called [APIBUFFER]. To modify settings,
simply edit the piclient.ini file in a text editor (Notepad on Windows) to the
desired values.
The following settings are available for buffering configuration:
Keywords Values Default Description
BUFFERING 0,1 0 Turn off/on buffering. OFF = 0, ON = 1,
PAUSERATE 0 – 2,000,000 2 When buffers are empty the buffering
process will wait for this long before
attempting to send more data to the home
node (seconds)
RETRYRATE 0 – 2,000,000 120 When the buffering process discovers the
home node is unavailable it will wait this
long before attempting to reconnect
(seconds)
MAXFILESIZE 1 – 2,000,000 100,000 Maximum buffer file size before buffering
fails and discards events. (Kbytes)
MAXTRANSFEROBJ 1 – 2,000,000 500 Maximum number of events to send between
S each SENDRATE pause.
BUF1SIZE 64 – 32768 Primary memory buffer size. (bytes)
2,000,000
BUF2SIZE 64 – 32768 Secondary memory buffer size. (bytes)
2,000,000
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 Description
PIHOMENODE string none Windows default server is in
pilogin.ini
DSTMISMATCH 0 – 2,000,000 0 The time that the server and client
local time offset is allowed to jump.
Typically, 3600 if the nodes are in time
zones whose DST rules differ (seconds)
Example piclient.ini File
NT
On Windows NT the default server information is stored in the pilogin.ini file so the
piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1
indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to
100 Megabytes of data storage. Do not use commas or other separators in the numeric
entries. The retry rate is set to 600 seconds, meaning “Wait 10 minutes after losing a
connection before retrying”.
On NT a piclient.ini file might look like:
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=100000
; The PI-API connection routines have a 1 minute default timeout.
RETRYRATE=600
94
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name is a
non-configurable identifier that is no longer than 9 characters. ID is a configurable
identifier that is no longer than 9 characters and is specified using the /id flag on the
startup command line.
Message Logs
The location of the message log depends upon the platform on which the interface is
running. See the UniInt End User Document for more information.
Messages are written to PIHOME\dat\pipc.log at the following times.
 When the interface starts many informational messages are written to the log.
These include the version of the interface, the version of UniInt, the 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.
Messages
The following error messages may appear in the PI application log file Pipc\Dat\
Pipc.log:
Binary mode is invalid when TTY protocol
An 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 failed
The 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.
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).
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 successfully
The 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 successfully
A connection has been made to the gateway successfully.
Invalid communication mode
An attempt to use a communication protocol other than RS-232 (TTY) or TCP/IP
was made.
Invalid machine type
The machine type specified by the “/mt” command line argument is invalid. Valid
values are those specified in the description of “/mt” above.
Invalid retry count
The 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 code
The digital start code specified by the “/ds” command line argument is invalid. A
valid value is greater than 0.

Invalid text sending count
The send text continuous count specified by the “/sc” command line argument is
invalid. A valid value is greater than 0.
Invalid timeout period
The timeout period specified by the “/to” command line argument is invalid. A valid
value is greater than or equal to 0.
Invalid waiting time
The wait time specified by the “/wt” command line argument is invalid. A valid
value is greater than 0.
Not defined TAG GET or BLOCK GET
The 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 defined
The 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 supported
This 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 7 PI_Type_PI2 14
PI_Type_uint32
10
PI_Type_bool 1 PI_Type_int32 8 PI_Type_digital
1
10
PI_Type_uint8 2 9 PI_Type_blob
PI_Type_uint64 2
10
PI_Type_int8 3 PI_Type_int64 10
PI_Type_Pistring 5
25
PI_Type_char 4 11 PI_Type_bad
PI_Type_float16 5
5 12
PI_Type_uint16 PI_Type_float32
PI_Type_int16 6 13
PI_Type_float64

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 tag
The 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 float64
The 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 Istat
The 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 status
The 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
Protocol error (received
-3 No data to receive -4
"ER")
Incorrect terminate
-5 Timeout -6
characters
-7 Failed to receive -8 Failed to send
-9 Mismatch data size -10 Port closed
-11 Overflow error -12 Invalid port
Set communication state
-13 Connection failed -14
failed
Set communication mask Communications setup
-15 -16
failed failed
System Errors and PI Errors

System errors are associated with positive error numbers . Errors related to PI are
associated with negative error numbers.
98
Error Descriptions on NT
On NT descriptions of system and PI errors can be obtained with the pidiag utility:
NT: \PI\adm\pidiag –e error_number

Revision History
Date Author Comments
3-Jan-97 MMG Modified for PI 3 on NT and Unix
11-Jun-97 RGM Updated
6-Aug-97 RGM Updated to include NT, HPUX and AIX
4-Apr-99 RGM Complete overhaul and reformat
26-Jul-99 RGM Removed Unix Installation, Added error messages
3-Mar-00 RGM Added comments, added NT RS-232 support
11-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.

Pi - Ygw - 1.8.0.1 3

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Pi - Ygw - 1.8.0.1 3

Uploaded by

Copyright:

Available Formats

Yokogawa YGW

Interface to the PI System

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

Mail OSIsoft OSI Software, Ltd

OSI Software GmbH OSI Software, Asia Pte Ltd

 1997 - 2005 OSIsoft, Inc. All rights reserved

Interface Installation on NT.........................................................................................15

Yokogawa YGW Interface to the PI System iii

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

Performance Point Configuration...............................................................................39

I/O Rate Tag Configuration..........................................................................................43

Yokogawa YGW Interface to the PI System iv

Startup Command File.................................................................................................47

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

Starting / Stopping the Interface on NT......................................................................89

Starting / Stopping the Interface on VMS...................................................................91

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

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

Yokogawa YGW Interface to the PI System v

Platform OS Version PI System PI API

Yokogawa YGW Interface to the PI System 1

Yokogawa YGW Interface to the PI System 2

Vendor Hardware Required

Yokogawa YGW Interface to the PI System 3

Yokogawa Gateway Setup Diagram

Character Mode Binary Mode (ECGW3 only)

Micro XL Communication Requirements

Yokogawa YGW Interface to the PI System 5

Yokogawa YGW Interface to the PI System 7

Yokogawa YGW Interface to the PI System 8

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

Tag Attributes Update

Event Counter Tags

Yokogawa YGW Interface to the PI System 9

Yokogawa YGW Interface to the PI System 11

Yokogawa YGW Interface to the PI System 13

Yokogawa YGW Interface to the PI System 14

Naming Conventions and Requirements

The PIHOME Directory Tree

Yokogawa YGW Interface to the PI System 15

Interface Installation Directory

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

Interface Installation Procedure

Installing the Interface as an NT Service

Yokogawa YGW Interface to the PI System 16

Yokogawa YGW Interface to the PI System 17

Start or Stop Service

Yokogawa YGW Interface to the PI System 19

Naming Conventions and Requirements

Yokogawa YGW Interface to the PI System 21

Interface Installation Procedure

The following procedure is typical.

Filename (“\” to exit): YGW_INT.bck

4. Install the interface files with the command:

Yokogawa YGW Interface to the PI System 23

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

Stopping the Interface

Testing the Connection to PI

Testing the Connection to the Yokogawa Gateway

Yokogawa YGW Interface to the PI System 25

Protocol (0:TCP/IP, 1:TTY) ->

Yokogawa YGW Interface to the PI System 26

Digital State Sets