Yokogawa YGW Interface to the PI System
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@ |
|World Wide Web | |
|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
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
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
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 NT |4.0 |3.1 |1.2 |
The interface supports input tags (from Yokogawa to PI) and output tags (from PI to Yokogawa). It counts the events to and from these tags, including exception tests, and sends its totals periodically to PI. Data from the gateway is received at cyclic frequencies or by exception in the data. The frequency of the cycles is configured by the user and controlled by the interface. The number of tags that the interface is capable of servicing is unlimited.
Changes that are made to the PI point database are reflected in the interface. This includes the adding, editing and deleting of tags.
All error information and some summary information are output to a log file. The amount of summary information that is output is configurable by the user and is minimal by default. For information about configuring information messages, see the “/db”, “/lg” and “/cl” headings of the Command-Line Parameters section on page 50
Reference Manuals
OSIsoft
• PI Server manuals
• PI-API manual
• UniInt End User Document
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 Attribute Changes |Yes |
|Exception Reporting |Yes |
|Outputs from PI |Yes |
|Inputs to PI: Scan-based / Unsolicited / Event Tags |Scan-based, 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 / PINet Node |No |
|* Vendor Software Required on Foreign Device |Yes, only for Micro XL. See Micro XL Communication |
| |Requirements section below. |
|* Vendor Hardware Required |Yes, only for Micro XL. See Micro XL Communication |
| |Requirements section below. |
|* Additional PI Software Included with Interface |Yes, YGI_Test.exe and YGI_TestB.exe connection test |
| |programs |
| Device Point Types |INT, FLT, CHR |
* See paragraphs below for further explanation.
UniInt-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:
|DCS System |Communication |Gateway |Interface Platform |
|Centum V |RS-232C TTY |CGWU |VMS, Windows NT |
|Centum XL |RS-232C TTY |ECGW* |VMS, Windows NT |
| | |ECGW2 |VMS, Windows NT |
| | |ECGW3 |VMS, Windows NT |
| |Ethernet TCP/IP |ECGW3 |VMS, Windows NT |
|Micro XL |RS-232C TTY |No Gateway |VMS, Windows NT |
| |Ethernet TCP/IP |Software Emulator |VMS, Windows NT |
Note: If the interface is running on VMS, DEC TCP/IP software (UCX) is required to be able to use the TCP/IP protocol.
Yokogawa Gateway Setup Diagram
[pic]
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 Mode |Character Mode |Character Mode |
See the Command-Line Parameters section on page 50 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 50) and should not exceed the limits of the DCS.
RS-232 Serial Communication
The following information must be specified on the DCS and in the interface port settings file, PISysExe:Ygi_ (VMS only) or the interface startup file command line arguments (NT only). The protocol does not accept sending text continuously. The settings marked (opt) are optional but must match between the DCS and the port settings.
| |DCS Settings |VMS Port Settings |NT Command Line arguments |
|Communication Rate |9600 bps (opt) |9600 bps (opt) |/bps=9600 |
|Communication Code |8 bit (opt) |8 bit (opt) |/bs=8 |
|Parity |Even (opt) |Even (opt) |/par=E |
|Stop Bit |1 bit |N/A |/sb=1 |
|Text |ASCII |N/A |N/A |
|XON/XOFF |Yes |N/A |N/A |
|Sequence Numbers |Yes |N/A |N/A |
|Other Settings |N/A |NoWrap, 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
• Transceiver and cable converter from AUI port to the physical network.
The MOPS and MOPL stations must be upgraded to MIGHTY stations (Y211). The setup will not function on standard (S211), advanced (A211) or enhanced (E211) systems. These systems may have an EN82 Ethernet card but MAPF-S311 emulation software will not work with it.
To be sure of what version the station is currently running, reboot the operator station, press the S2 key and check the operating system revision number at the top of the screen. The MIGHTY software will display “R1.A#” (where # is the revision number). The revision number itself is not important (R1.A6 is the Y2K compliant revision but subsequent revisions may have been released since), as long as the revision label is R1.A on the S2 screen. If the station is not a MIGHTY station then the revision label will display “Rev.#” or something similar.
The station can also be checked for its version by looking at the CPU card (it is a CP81 card). A card of type CP81*E is a MIGHTY type card. Cards of type CP81*A through to CP81*D are not.
|Station Type |Station Number |Y2K Revision |CPU Card |
|Standard |S211 |Rev.26 |CP81*A |
|Advanced |A211 |Rev.26 |CP81*B |
|Enhanced |E211 |Rev.26 |CP81*C |
|Power | |Rev.26 |CP81*D |
|MIGHTY |Y211 |R1.A6 |CP81*E |
Performance is most reliable when the Ethernet card is in the engineering station (or wherever the system is configured from). The MOPS or MOPL station must be given a fixed IP address because DHCP is not supported.
Serial Communication
• RS81 serial communication card (the Serial card for MOPS or MOPL stations).
• MSPF-C011 serial communication card driver.
• MAPF-S031 serial computer communications package (ECGW3 protocol emulation software).
The serial port settings must match those in the table in the RS-232 Serial Communication section above.
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 50.
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 50.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 58 and the “/term” argument on page 60 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 61 .
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 37
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 39 . 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 36 .
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 64 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 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 50 .
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 Interface Identifier section on page 61 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 53 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 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 27). 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 35).
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 27.
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: by inserting a new stop command line for each process
@PISysExe:Stop YGW_INT_#
where # is the point source of the interface to start.
d. Insert a new Unsetterm command for after each stop command that refers to an interface using TTY serial communication.
@PISysExe:YGI_UnSetterm xxxx
where xxxx is the terminal name for that interface.
6. Define digital states as specified in the Digital States section (p. 29).
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.
Location3 is not used.
Location4 is the scan class (and, subsequently, the data access type)
Location5 is not used.
ExDesc is used for event triggered tags and extended point source.
InstrumentTag is used for defining the Yokogawa point to read.
9. When the PI2 system is shutdown, the points coming into the system should receive shutdown events. Modify the argument list for the program ShutdownEvents, which is executed from files and .
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. 11).
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:
[pic]
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 list using the [pic] 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 [pic] 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.
[pic] - Add Button
To add a dependency from the list of Installed services, select the dependency name, and click the Add button.
[pic] - 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 [pic] and a Stop button [pic] 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.
[pic]
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_.
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_
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_
These link the object files to form the following executables:
Ygw_Int.exe
Ygi_Test.exe
Ygi_TestB.exe
PISysExe:YGI_
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_
This file resets the serial port to its default state. Specify a port number when executing it.
PISysExe:YGW_
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_ 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. 77. 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_ |Installation command file for the Interface. |
|YGW_Int.BCK |Saveset containing the interface files. |
|PI_YGW_1.8.0.0.TXT |Release notes. |
|REBLOCK.README |Readme file for REBLOCK.EXE. |
|REBLOCK.EXE |The interface backup saveset must be reblocked before the saveset can be |
| |unpacked. See the REBLOCK.README. |
The following procedure is typical.
1. Transfer YGW_INT.BCK and REBLOCK.EXE to the VMS node by some sort of binary file transfer mechanism. For example, one could use binary ftp. Copy the files to a safe directory, one that will not be overwritten during an upgrade of PI or PINet.
2. Transfer YGW_ 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_ #
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_ |Command procedure for re-linking the executable. |
|PISysExe Directory |
|YGW_INT.EXE |Interface executable. |
| |Startup command file for interactive processes. |
|YGW_ |Startup command file for detached processes (the command-line |
| |arguments are still defined in the 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
@PISysExe:YGW_Detach #
Passing it the interface point source #.
This executes the command file PISysExe:YGW_#.com and creates a detached process called YGW_INT_#.
10. Verify that the interface version number in YGI_#.out matches the version shown on the tape containing the interface.
Stopping the 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
where xxxx is the terminal name for that interface.
2. Add a new line for each process required, supplying the point source as a parameter.
@PISysExe:YGW_Detach #
where # is the point source of the interface to start.
3. Edit PISysMgr: by inserting a new stop command line for each process
@PISysExe:Stop YGW_INT_#
where # is the point source of the interface to start.
4. Insert a new Unsetterm command for after each stop command that refers to an interface using TTY serial communication.
@PISysExe:YGI_UnSetterm xxxx
where xxxx is the terminal name for that interface.
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 50). 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 58 and 59) 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 51 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 68.
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 51 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 |
|CENTUM V |
|CENTUM V |
|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 63 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 29for 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 29 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. |
|Output |1 |Updates the DCS without checking the range of the value. |
| |2 |Updates the DCS only if the value lies within the PI range of the tag. |
| |3 |Updates the DCS, clipping the value to fall within the PI range of the tag. |
A clipped value is forced to be within the bounds of the PI range by setting values that are outside the range of the PI tag to the limit of the range. For example, if the Zero and Span of a tag were 50 and 200, and the output value was 270, it would be changed to 250. If the value for the same tag was 20, it would be changed to 50. See the Zero/Span section on page 39 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
This attribute is not use for the Yokogawa YGW interface.
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 48. 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
This attribute is not use for the Yokogawa YGW interface.
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 10 describes the operation of event-based tags. The tag that is monitored for the event is specified here in the following format:
EVENT=
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 52 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 36.
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, 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 10.
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 36 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.
[pic]
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.
[pic]
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
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:
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:
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:
[pic]
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:
[pic]
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.
[pic]
The General tab on the PI-ICU should now look similar to this:
[pic]
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 [pic] 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 [pic].
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 [pic]. 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.
[pic]
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).
[pic]
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 |
[pic]
TCP/IP
Choosing the MICROXLE machine type results in a display similar to the following.
[pic]
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 [pic]button and move a gateway up or down in the list using the [pic] buttons. The blue rectangle indicates the selected gateway that will be deleted or moved.
The command line equivalent for this parameter is /gw=xxxxx.
[pic]
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.
[pic]
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.
You can remove a serial port from the list using the [pic]button and move a serial port up or down in the list using the [pic] 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.
[pic]
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 Setting |Definition |
|/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.
Other Tab
[pic]
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_#.txt |Yes |For specifying Yokogawa types for output points. |
|Ygw_Sts_#.txt |No |For translating Yokogawa digital state strings. |
The Interface text file path specifies the path the interface will use to load these files. By default, the interface will search only in its local directory. To specify the path, type the path in the Interface text file path text box or browse to the directory containing these files using the [pic] 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=#.
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
[pic]
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 70.
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.
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 |Binary Mode |
|Optional |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 |Communication Log Messages |
|Optional |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 11. |
|/db[=#] |Uniint Debug Level |
|Optional |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 11. |
|/ds=# |Digital Start Code |
|Optional |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 29 for more information about digital |
| |states. The default value is 1. |
|/dt=# |Digital State Table (NT, PI3 only) |
|Optional |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 68. |
| |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=# |Extended Point Source |
|Optional |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 37)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 |Log Debug Messages |
|Optional |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 11. |
|/ms |Read Interrupt Messages |
|Optional |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 59. 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 |Machine Type |
|Optional |This argument specifies the Yokogawa machine type that the interface is to communicate |
| |with. The valid options for this argument are: |
| | |
| |Argument Setting |
| |Gateway/DCS |
| |Communication Type |
| | |
| |/mt=CGWU |
| |CGWU |
| |RS-232 Serial TTY |
| | |
| |/mt=ECGWT |
| |ECGW*, ECGW2, ECGW3 |
| |RS-232 Serial TTY |
| | |
| |/mt=ECGWE |
| |ECGW3 |
| |Ethernet TCP/IP |
| | |
| |/mt=MICROXLT |
| |Micro XL |
| |RS-232 Serial TTY |
| | |
| |/mt=MICROXLE |
| |Micro XL |
| |Ethernet TCP/IP |
| | |
| | |
| |The machines in the table are all very similar in the way they communicate with the |
| |interface but each has its slight differences and the interface acts to these |
| |accordingly. This argument is not required and its default value is none of the above |
| |machines but if not specified, the interface may not run correctly or as efficiently as |
| |it should. |
|/path=x |Set Interface Text File Path |
|Optional |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 67–68. |
| |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=# |Set Performance Summary Interval |
|Optional |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. |
|/rc=# |Communication Retry Count |
|Optional |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 56. |
|/sc=# |Send Continuous Count |
|Optional |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[=#] |Suppress Digital State(s) |
|Optional |Under certain circumstances the interface will write a digital state to a PI tag instead |
| |of a value. For example, CONN_CLOSED will be written to all tags if the connection to the|
| |gateway closes. These digital states can be suppressed so that PI does not receive them. |
| |This is done by using one instance of “/sds” for each state to be suppressed. |
| |If all states are to be suppressed, the “/sds” argument can be used without assigning it |
| |a number. This has the added effect of removing other digital states that the interface |
| |may have inserted, such as Bad Input. There are exceptions to this is such as the I/O |
| |Timeout state. Also, there are digital states that are not set by the interface (such as |
| |Shutdown, Under Range, Over Range, etc.) which cannot be suppressed. |
| |The following table shows the states that can be suppressed: |
| |Arg Setting |
| |Suppressed State |
| |Arg Setting |
| |Suppressed State |
| | |
| |/sds |
| |All Digital States |
| |/sds=4 |
| |INT_MINUS |
| | |
| |/sds=0 |
| |NO_BLOCK |
| |/sds=5 |
| |CONN_CLOSED |
| | |
| |/sds=1 |
| |BAD_BLOCK |
| |/sds=6 |
| |INIT_ERROR |
| | |
| |/sds=2 |
| |R_OVER_DIG |
| |/sds=7 |
| |NOT_OUTPUT |
| | |
| |/sds=3 |
| |BAD_DIGSTATE |
| |/sds=8 |
| |OUTPUT_ERR |
| | |
| | |
|/to=# |Communication Timeout |
|Optional |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 55. |
|/wc=# |Wait Count |
|Optional |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=# |Wait Time |
|Optional |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. |
|/gw=xxxxx |Gateway Host Name |
|Required only if using |If communicating using TCP/IP, this argument specifies the Yokogawa gateway’s host name. |
|Ethernet TCP/IP |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 59 |
| |Gateway Failover |
| |To specify multiple gateways for gateway failover, use multiple instances of this |
| |argument (or the “/term” argument). See Gateway Failover on page 9 and “/term” on page 60|
| |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=# |Interrupt Message Port |
|Optional |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 53. If both the |
| |“/iport” and “/ms” arguments are specified, the “/ms” argument takes precedence. |
|/port=# |Yokogawa Gateway Port Number |
|Optional |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 58. |
|/bps=# |Bits Per Second (NT only) |
|Optional |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=# |Byte Size (NT only) |
|Optional |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 |Parity (NT Only) |
|Optional |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. |
|/sb=# |Stop Bits (NT only) |
|Optional |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 |Serial Port Name |
|Required if using RS-232 |This argument specifies the machine’s TTY terminal name (VMS) or serial port (Windows NT)|
|serial communication |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 58 for details. |
|/ps=x |Point Source |
|Required |The /ps flag specifies the point source for the interface. X is not case sensitive and |
| |can be any single character. For example, /ps=P and /ps=p are equivalent. |
| |The point source that is assigned with the /ps flag corresponds to the PointSource |
| |attribute of individual PI Points. The interface will attempt to load only those PI |
| |points with the appropriate point source. |
|/id=x |Interface Identifier |
|Optional |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 11 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 |Scan Class |
|or |The /f flag defines the time period between scans in terms of hours (HH), minutes (MM), |
|/f=SS,SS |and seconds (SS). The scans can be scheduled to occur at discrete moments in time with an|
|or |optional time offset specified in terms of hours (hh), minutes (mm), and seconds (ss). If|
|/f=HH:MM:SS |HH and MM are omitted, then the time period that is specified is assumed to be in |
|or |seconds. |
|/f=HH:MM:SS,hh:mm:ss |Each instance of the /f flag on the command line defines a scan class for the interface. |
| |There is no limit to the number of scan classes that can be defined. The first occurrence|
|Required for reading |of the /f flag on the command line defines the first scan class of the interface; the |
|scan-based inputs. At least |second occurrence defines the second scan class, and so on. PI Points are associated with|
|one scan class must be defined|a particular scan class via the Location4 PI Point attribute. For example, all PI Points |
|for the interface to operate |that have Location4 set to 1 will receive input values at the frequency defined by the |
|correctly. |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 |
| |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 |Host:Port |
|Optional |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 |Shutdown Digital State |
|or |If the /stopstat flag is present on the startup command line, then the digital state Intf|
|/stopatat= |shut will be written to each PI Point when the interface is stopped. |
|digstate |If /stopstat=digstate is present on the command line, then the digital state, digstate, |
|Default: |will be written to each PI Point when the interface is stopped. For a PI 3 Server, |
|/stopstat= |digstate must be in the system digital state table. For a PI 2 Server, where there is |
|”Intf shut” |only one digital state table available, digstate must simply be somewhere in the table. |
|Optional |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 |Event Counter |
|Optional |The first instance of the /ec flag on the command line is used to specify a counter |
| |number, x, for an I/O Rate point. If x is not specified, then the default event counter |
| |is 1. Also, if the /ec flag is not specified at all, there is still a default event |
| |counter of 1 associated with the interface. If there is an I/O Rate point that is |
| |associated with an event counter of 1, each copy of the interface that is running without|
| |/ec=x explicitly defined will write to the same I/O Rate point. This means that one |
| |should either explicitly define an event counter other than 1 for each copy of the |
| |interface or one should not associate any I/O Rate points with event counter 1. |
| |Configuration of I/O Rate points is discussed in the section called “I/O Rate Tag |
| |Configuration.” |
|/sio |Suppress Initial Outputs |
|Optional |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 |Queue Snapshots and Exceptions |
|Optional |When the /q flag is present, Snapshots and exceptions are queued before they are sent to |
|not implemented for interfaces|the PI Server node. |
|on VMS 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 |Snapshot Input Data |
|Optional |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. |
| | |
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
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 Gateway Host Name
section on page 11). 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 50.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:
,
,
,
...
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 represents the digital state string as it is received from the DCS. The 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 MICRO XL |
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_ 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_. If it is not passed, the command file will terminate with the error message:
The Interface point source # must be passed.
2. YGW_ searches for the existence of the PISysExe:YGW_ 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:
does not exist.
3. YGW_ 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_ 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:
[pic]
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.
[pic]
Enable Buffering
Enables the API Buffering feature.
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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
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) |
|MAXTRANSFEROBJS |1 – 2,000,000 |500 |Maximum number of events to send between each SENDRATE |
| | | |pause. |
|BUF1SIZE |64 – 2,000,000 |32768 |Primary memory buffer size. (bytes) |
|BUF2SIZE |64 – 2,000,000 |32768 |Secondary memory buffer size. (bytes) |
|SENDRATE |0 – 2,000,000 |100 |The time to wait between sending up to MAXTRANSFEROBJS to |
| | | |the server (milliseconds) |
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.
|Keywords |Values |Default |Description |
|PIHOMENODE |string |none |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
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. This error is accompanied by a NOT_OUTPUT digital state for the PI tag.
Can not output because of invalid point def [PI tag]
The PI tag has been defined as a digital tag with a Location1 value of 3 (clip the value being written to the DCS if it is out of range). The value being written to the DCS is out of range and clipping digital tags is inappropriate. This error is accompanied by a NOT_OUTPUT digital state for the PI tag.
Can not output because of invalid point status [PI tag]
The value of the output tag has not been written to the DCS because its istat value is invalid. If the PI tag is a digital tag, the digital state that is to be written to the DCS is not valid for the PI tag (PI2 only—the state that was found must be in the digital state table between the zero and the span of the digital PI tag). If the PI tag is a numeric tag (PI2 or PI3), the value to be written is not valid (has an Istat value < 0). This error is accompanied by a NOT_OUTPUT digital state for the PI tag.
Can not output because out of range [PI tag]
The value of the output tag has not been written to the DCS because the value is outside the range of the tag. This error only occurs for output tags that have a Location1 value of 2 (output tag with range checking). This error is accompanied by a NOT_OUTPUT digital state for the PI tag.
Connected to gateway 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 | PI_Type_uint32 |7 | PI_Type_PI2 |14 |
| PI_Type_bool |1 | PI_Type_int32 |8 | PI_Type_digital |101 |
| PI_Type_uint8 |2 | PI_Type_uint64 |9 | PI_Type_blob |102 |
| PI_Type_int8 |3 | PI_Type_int64 |10 | PI_Type_Pistring |105 |
| PI_Type_char |4 | PI_Type_float16 |11 | PI_Type_bad |255 |
| PI_Type_uint16 |5 | PI_Type_float32 |12 | | |
| PI_Type_int16 |6 | PI_Type_float64 |13 | | |
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 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 |
|-3 |No data to receive |-4 |Protocol error (received "ER") |
|-5 |Timeout |-6 |Incorrect terminate characters |
|-7 |Failed to receive |-8 |Failed to send |
|-9 |Mismatch data size |-10 |Port closed |
|-11 |Overflow error |-12 |Invalid port |
|-13 |Connection failed |-14 |Set communication state failed |
|-15 |Set communication mask failed |-16 |Communications setup failed |
System Errors and PI Errors
System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.
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. |
| | | |
| | | |
-----------------------
Service installed or uninstalled
Status of the Interface Service
Status of the ICU
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- why the school system is bad
- is the education system broken
- the school system is broken
- the education system is failing
- why the education system is good
- changing the school system essay
- the college system is broken
- calculator with the pi button
- how to cleanse the lymphatic system naturally
- the planets of the solar system song
- the organs in the circulatory system include
- label the conduction system of the heart