Yokogawa YGW
Yokogawa YGW
Interface to the PI System
Version 1.4.2 and Greater
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|Internet |techsupport@ |
|World Wide Web | |
|Bulletin Board |(510) 895-9423 |
| |Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible) |
| |8 data bits, 1 stop bit, no parity, up to 14400 bps download |
| |protocols: Xmodem, Ymodem, Zmodem, Kermit |
|Mail |OSI Software, Inc. | |
| |P.O. Box 727 | |
| |San Leandro, CA 94577-0427 | |
| |USA | |
| | | |
| |OSI Software GmbH |OSI Software, Ltd |
| |Hauptstra(e 30 |P. O. Box 8256 |
| |D-63674 Altenstadt 1 |Level One, 6-8 Nugent Street |
| |Deutschland |Auckland 3, New Zealand |
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. 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.
ygw_int.doc
( 1997 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Communication Configuration 2
Yokogawa Gateway Setup Diagram 2
Hardware Configuration 2
Micro XL Ethernet Requirements 4
Outline of Operation 5
Input Tags 5
Output Tags 6
Tag Attributes Update 6
Event Counter Tags 6
Logging File 7
Error Handling 7
PI System Databases 9
Point Source (PI2 only) 9
Digital States 9
Tag Definition 11
Interface Files 15
Interface Program File 15
Interface Startup File 15
General Command Line Arguments 16
TCP/IP Command Line Arguments 21
TTY (RS-232) Command Line Arguments 22
Example Startup File 23
Interrupt Messages Switch File 23
Data I/O Type Filter File 23
Digital State String Translation File 24
Communication Testing Programs 24
Pre-Installation Checklist 26
VMS Installation 27
Basic Installation 27
Permanent Installation 28
Windows NT Installation 30
Basic Installation 30
Permanent Installation 30
Appendix — Error Messages 32
Revision History 36
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 Interface Startup File section on page 15.
A summary of the features of the interface is shown in the following table:
|Sign-up for updates |Yes |
|Exception reporting |Yes |
|PINet |Yes |
|Outputs |Yes |
|Vendor software required |Yes, for MicroXL TCP/IP |
|Failover |No |
|Maximum number of points |Depends on gateway |
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 Interface Startup File section on page 15 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 20) 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 Ethernet Requirements
The Micro XL DCS system has the following requirements to be able to communicate with the interface via the Ethernet using TCP/IP:
Yokogawa Products
• EN83 Ethernet communication card (the Ethernet card for MOPS or MOPL station).
• MAPF-S221 Ethernet card driver.
• MAPF-S311 Ethernet computer communications package (ECGW3 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 them. 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 has a revision number R1.A# (where # is a number). 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.
Outline 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 PI System Databases chapter on page 9.
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 Interface Startup File section on page 15. 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.
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 Interface Startup File section on page 17.
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 Tag Definition section on page 11.
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 Source heading of the Tag Definition section on page 11. 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 12.
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 Interface Startup File section on page 16 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” and “/df” in the Interface Startup File section on page 15.
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 Startup File section on page 17 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 Interface Startup File section on page 19 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 24). 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 Tag Definition section on page 11).
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.
PI System Databases
The interface collects data from the Yokogawa gateway via TCP/IP socket calls. For every Yokogawa point type that data is to be collected for, corresponding tags must be defined within PI. Data for Multiple Yokogawa tag types can be collected but each type must correspond to a single PI point. For example, FIC00413.PV, FIC00413.SP and FIC00413.LOOP can all be collected using three separate PI tags.
Each PI point has a set of fields that are used by the interface and need to be configured for the interface to operate correctly. Digital states should be defined for recording discrete data.
Point Source (PI2 only)
Select a point source that has not already been used by the PI system or by any other interfaces or PI client applications. Set the location parameter limits as follows:
| |Location1 |Location2 |Location3 |Location4 |Location5 |
|Minimum |0 |-20000000 |-20000000 |1 |-20000000 |
|Maximum |3 |20000000 |20000000 |200 |20000000 |
Digital States
PI digital states are discrete values represented by strings. These strings are organised differently for different versions of PI.
PI2 Digital State Table
Digital states are organised in PI2 in a digital state table. PI2 Digital tags use this table for its digital states. Each digital tag has a DIGSTARTCODE field and a DIGNUMBER field which it uses as a starting point and length (minus 1) in the digital state table for its “block” of digital states. For more information about PI2 digital tags and editing the digital state table, see the PI2 System manual, Part I, sections 3.2.2 and 3.3.4.
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 labelled 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.
PI2 SYSTEM DIGITAL STATES
The PI2 system reserves states between 193 and 320. This section 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 a Yokogawa 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.
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 labelled 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 Interface Startup File (see page 16 for more information).
PI3 Digital State Sets
Digital states are organised in PI3 in digital state sets. Each digital state set is a user-defined list of strings, enumerated from 1 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Data Archive Manual for Windows NT and Unix manual.
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. The sets must be defined as they appear in the tables labelled Loop Status and Alarm Status below. PI digital tags that store data for these Yokogawa data types must be assigned to one of these sets using the DigitalSet field.
PI3 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 a Yokogawa 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.
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 labelled 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 Interface Startup File (see page 16 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.
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 Interface Startup File section on page 20 for more information.
Tag Definition
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 PI2 Digital State Table section on page 9 for 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 PI3 Digital State Sets section on page 10 for more information about digital states.
ExDesc
This field is the extended descriptor of a tag. 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 5 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 recognised 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 Interface Startup File section on page 17 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 recognise only the EVENT ans /EPS 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 below.
InstrumentTag
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.
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 below 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.
Location4
This field is used to specify the scan class number (and, subsequently, the data access type) for an input tag. The scan period and data access type of each scan class is specified in the startup file. See the description of “/f” and “/g” in the Interface Startup File section on page 15. If a tag is to be read by PI exception, Location4 does not need to be configured. See the ExDesc section above for information about how to set up an exception point.
PointSource
A point source is a character defined in every tag to group together all tags collected from a collective source. The interface will look for all tags that have a particular point source defined. The PI tag’s point source must match the point source character defined by the “/ps” argument in the interface startup file (see “/ps” in the Interface Startup File section on page 19). The point source for character may be any printable ASCII character except C, Q, T, @ and ? are reserved for PI2 and C, L, R, T and 9 are reserved for PI3.
PointType
This field specifies the point type of a PI point. Use R (PI2) or Float64/Float32 /Float16 (PI3) for real data, I (PI2) or Int32/Int16 (PI3) for integer data, D (PI2) or Digital (PI3) for digital data and String (PI3) for string data.
For PI2, real data can stored in the archive as SCALED or FULL precision. For SCALED real data, the input value is stored as a scaled value between 0 and 32767 in the PI archive. FULL precision real data is saved as a 4 byte floating point value. For PI3, the equivalent of SCALED and FULL data types are Float16 and Float32, respectively. Values which can be less than 0 should be saved as real data since the range for PI integers is between 0 and 32767. If input value of integer point is minus, the digital state INT_MINUS will be written to PI. See the Digital States section on page 9 above for more information.
The interface supports Float64 data for PI3 input points only and not for output data to DCS. Float64 data is always put to snapshot thus no exception reporting is done.
Data retrieved from the DCS for a PI string tag will be stored in the archive as it was received. PI3 string tags are only valid for input tags.
Note: It is not necessary that the data type of a Yokogawa point match the data type of its corresponding PI tag. For example, a Yokogawa point of type real may correspond to a PI digital tag. To do conversions, however, the interface may need to truncate some values for PI to be able to store them.
Scan
The Scan flag is used by the interface to control processing of a PI tag. A tag with a scan value of ON will be serviced by the interface. Setting the scan field to OFF will cause the interface to delete that tag from its structure of tags. The digital state value of SCAN OFF will be written to the tag when its scan flag has been turned off. Change it back to ON to enable data collection for the tag to resume.
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 6.
Typical Value
This field is not used by the interface but must be set to a value that lies within the range of the tag. See the Zero/Span section below for more information about a tag’s range.
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 above 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.
Other Parameters
Other PI tag fields that need to be configured are listed below. The configuration of these fields is regardless to the interface. For information about configuring these fields, see the PI2 System manual, Part I or the PI Data Archive for Windows NT and Unix manual.
|Archiving |CompDev |CompDevPercent |
|CompMax |CompMin |Compressing |
|DataAccess |DataGroup |DataOwner |
|Descriptor |DeviationUnits |DisplayDigits |
|EngUnits |ExcDev |ExcDevPercent |
|ExcMin |ExcMax |PtAccess |
|PtGroup |Res (PI2) |Shutdown |
|Step (PI3) | | |
Interface Files
The interface uses the following files for its operation (where # represents a point source character):
|File name |Platform |Description |
|YGW_#.exe |All |Interface executable program file. |
|YGW_#.com |VMS |Interface startup file. |
|YGW_#.bat |NT |Interface startup file. |
|YGI_Test.exe |All |Gateway communication test program. |
|YGI_ |VMS |Interface TTY port settings command file. |
|YGW_Msg_#.txt |All |Interrupt messages switch file. |
|YGW_OItem_#.txt |All |Data I/O type filter file. |
|YGW_Sts_#.txt |All |Digital state string translation file. |
The interface also requires that the PI API be installed and DEC TCP/IP (UCX) be installed if using TCP/IP with VMS.
Interface Program File
Filename: YGW_#.exe
The interface executable file is the program that does the collecting of the data from the gateway and sends it to PI.
Interface Startup File
Filename: YGW_#.com
The interface startup file for VMS is a command file that starts a single instance of the interface. It contains the program’s startup arguments for configuring the interface.
Filename: YGW_#.bat
The interface startup file for Windows NT is an MS-DOS batch file that starts a single instance of the interface. It contains the program’s startup arguments for configuring the interface.
Following is a description of the arguments found in the interface startup file. They are arranged in alphabetical order. Arguments can be categorised into the following:
|Category |Optional |Recommended |Compulsory |
|General |/cl |/db |/dt |/ec |/ds |/f |
| |/id |/lg |/g |/q |/host |/mt |
| |/ms |/rc |/sn |/stopstat |/ps | |
| |/sc |/si |/to |/wt | | |
| |/perf | | | | | |
|TTY Serial |/par |/sb |/bps |/bs |/term | |
|TCP/IP |/iport | |/b | |/gw |/port |
General Command Line Arguments
/b Binary Mode /b
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 /cl
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 7.
/db Uniint Debug Level /db[=n]
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 7.
/ds Digital Start Code /ds=n
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 9 for more information about digital states. The default value is 1.
/dt Digital State Table (NT, PI3 only) /ds=n
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 24.
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.
/ec Event Counter Number /ec=n
This argument configures the interface to record the rate of certain events. This is done with event counters. The argument specifies the event counter numbers as defined in the IORates.dat file. It can occur on the command line multiple times but the interface will only register the first three. The first occurrence of this argument specifies one event counter, the second occurrence the next and so on. See the Event Counter Tags section on page 6 for a list of the events that the interface will register and for more information about setting up event counters.
/eps Extended Point Source /eps=n
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 Tag Definition section on page 11). 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=1” 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.(ex: /id=Y1)
/f Scan Class Period /f=hh:mm:ss[,hh:mm:ss]
The interface collects data at time intervals specified by scan classes. Each scan class is given a frequency period to start collecting data. Scan class 1 is defined by the first instance of the “/f” parameter, scan class 2 is defined by the second instance, etc. At least one scan class must be defined. The format hh:mm:ss specifies the hours, minutes and seconds for the frequency of a particular scan class. The addition of the second hh:mm:ss after the comma specifies the phase offset from midnight of the scan class. For example:
/f=01:30:00 will define a scan class to collect data every 90 minutes.
/f=01:00:00,7:00:00 will define a scan class to collect data every 60 minutes, starting at 7:00am.
Partial scan frequencies and phase offsets can be used. For example,
/f=30 will define a scan class to collect data every 30 seconds.
/f=5:00 will define a scan class to collect data every 5 minutes.
/f=3:00,1:00 will define a scan class to collect data every 3 minutes with a one minute phase offset.
Multiple scan classes may be defined with the same interval and offset. This allows some points to be read from the DCS by tag name and others in bulk by block number. See the “/g” argument below for a description of DCS block processing.
Each tag that is to use a scan class must be defined to use one by assigning the Location4 field of the tag to the scan class number.
Note: Even if every tag used by the interface is defined to be read by PI exception, at least 1 scan class must be defined for the interface to operate correctly.
/g Read Block Number /g=n
This argument specifies the data access type of each scan class defined by the “/f” argument. For each “/f” argument there must be a corresponding “/g” argument to determine whether or not to read the values from that scan class by block file number. Valid values are:
/g=0 Read tags in the corresponding scan class by their individual tag names.
/g=1 Read tags in the corresponding scan class by its block numbers.
The first occurrence of “/g” corresponds to the first occurrence of “/f”, the second occurrence of “/g” to the second “/f”, etc. The default value of “/g” is 0 (read by tag name) and is only needed as a place-holder when there is a /g=1 that corresponds to a later occurrence of “/f”. For example, if there were six scan classes defined using “/f” and only the third scan class was to be read by block number, the first two occurrences of /g=0 would be necessary to hold the place of the /g=1 but the last three would not be necessary.
/f=1 /f=2 /f=5 /f=10 /f=1:00 /f=15:00 /g=0 /g=0 /g=1
Reading tags by block number is recommended. Reading tags by block number has a much quicker response time than by individual tag name. If a scan class is set to be read by block number the interface automatically defines enough tag blocks for it in the gateway (provided there are sufficient blocks available). A block consists of 32 tags. For Centum V and Centum XL systems, 256 blocks can be defined on one system, making a total of 8192 potential tags to be read by block. For Micro XL the number of definable blocks depends on the actual system.
If more tags are defined for reading by block number than there are available, the interface rejects them and logs the error. If this occurs, a tag can still be read using the tag name option (/g=0) for another scan class (possibly of the same frequency). The number of tags that can be read by tag name is unrestricted.
/host PI Server Host Name /host=xxxx
This argument specifies the PI server’s machine name. If the interface is to run on the same computer as the PI server, then localhost can be used. If the interface is running on a PINet node, this argument is not needed unless it is connecting to a PI3 server. An IP address may also be used instead of a host name. It may be necessary to follow the host name by a the standard PI port number (545 if connecting to PI2 and 5450 if connecting to PI3) using the following format:
/host=:
For example,
/host=ourpiserver:5450
Access to the PI server is required to be able to send data to PI. Access is granted via a proxy mechanism because login access is inappropriate for the interface. A host name or an IP address is associated with a PI user account for which it grants the interface the same access rights. This association is defined in the PI proxy database and is necessary for the collection of data by the interface. See the PI Data Archive for Windows NT and Unix Manual for more details about proxy accounts.
/id Interface ID /id=xxxxx
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 7 for more information about the interface log file.
Note: The length of the string defined by this argument must not exceed 9 characters.
/lg Log Debug Messages /lg
This argument 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 7.
/ms Read Interrupt Messages /ms
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 below. 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 Machine Type /mt=xxxx
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.
/perf Set Performance Summary Interval /perf=n
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.
/ps Point Source /ps=x
This argument is a single letter that associates the interface with its PI tags. It is a mandatory argument and therefore has no default value. The interface will attempt to access all tags whose point source field matches this argument. It is helpful to make this point source a meaningful character so that it is easy to associate. For example, using
/ps=E for an ECGW3 gateway,
/ps=S for a CGWU (Serial) gateway or
/ps=M for a MicroXL system.
Multiple instances of the interface may be run by defining PI tags with different point sources.
/q Queue Input Data /q
The interface will normally send each exception for each point to the PI snapshot individually. If this causes network traffic to become excessive or the interface to slow down, this argument can be used to queue the exceptions locally. The size of the queue is 255 and when it is full, its entire contents are sent to PI. If the queue is not full at the completion of a scan class, it is flushed to ensure that all remaining exceptions are sent to PI before the next scan class commences.
/rc Communication Retry Count /rc=n
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 below.
/sio Suppress Initial Output /sio
When the interface initialises an output point it sends an initial value out to the DCS based upon the current snapshot of its source tag. This argument Suppresses this initial output.
/sc Send Continuous Count /sc=n
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.
/sn Snapshot Input Data /sn
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.
/stopstat Interface Stopped State /stopstat=xxxxx
Specifying this argument will direct the interface to clean up its tags before it exits. If the interface is stopped for any reason, the interface is given a chance to disconnect itself from the gateway and write a digital state to PI for all of its tags. If /stopstat is used by itself, the default digital state is I/O Timeout. A specific digital state can be specified by using /stopstat=xxxxx where xxxxx is the name of a digital state. For example,
/stopstat=Inf_Stopped
In this example, the Inf_Stopped state must exist in the digital state table(PI2) or in the system digital state set(PI3). The recommended digital state to use is Shutdown.
/stopstat=Shutdown
/to Communication Timeout /to=n
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 cancelling the call. The default timeout period is 10 seconds. The number of retries is dependant on the “/rc” argument, described above.
/wt Wait Time /wt=n
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.
TCP/IP Command Line Arguments
/gw Gateway Host Name /gw=xxxx
If communicating using TCP/IP, this argument specifies the Yokogawa gateway’s host name. If the gateway does not have a host name or it is not known, an IP address is sufficient. For example,
/gw=MG_ECGW3 or /gw=204.138.119.15
To specify the port number, use the “/iport” argument as described below.
/iport Interrupt Message Port /iport=n
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 above. If both the “/iport” and “/ms” arguments are specified, the “/ms” argument takes precedence.
/port Yokogawa Gateway Port Number /port=n
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 above.
TTY (RS-232) Command Line Arguments
/bps Bits Per Second (NT only) /bps=n
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) /bs=n
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 Parity (NT only) /par=x
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) /sb=x
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 Serial Port Name /term=xxxx
This argument specifies the machine’s TTY terminal name (VMS) or serial port (Windows NT) that the gateway is connected to. For example,
/term=TTA1: (Example of VMS terminal name.)
/term=COM1: (Example of Windows NT serial port name.)
Example Startup File
Windows NT Interface
Following is an example of a Windows NT interface startup batch file configured for a Centum XL DCS via a ECGW3 gateway using the TCP/IP protocol:
YGW_E.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 /g=0 /g=1 /g=1 /id=E /ps=E /ds=45 /dt /ec=22 /q /stopstat=Inf_Stopped /to=30
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 Logging File section on page 7). 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 Interface Startup File section on page 19. 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
When the interface receives a digital state string from the DCS it translates it using this table to a custom state string and send it to PI. See the description of the “/dt” argument on page 17 for more information about translating PI digital states to PI digital codes.
The purpose of this file is to be able to give Yokogawa digital state strings a more meaningful name in PI. It is also useful for translation to different languages where the DCS does not use the same language as the PI system users.
If the file cannot be found, the interface continues without it, logging a message similar to:
Wed Apr 14 10:12:22 1999
YGW D> file not found [YGW_Sts_Y.txt]
Communication Testing Programs
Filenames: Apisnap.exe, Ci-Test.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 interface startup file on page 16). 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 21 and 22) in the interface startup file. 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.
Pre-Installation Checklist
The following instructions apply to installing all interfaces. These instructions do not presume that the interface is running on the same platform as PI is. They should be performed before installing the interface.
1. Test the connection to the gateway using the test programs as described in the Communication Testing Programs section (p. 24).
1. Define a point source as specified in the Point Source (PI2 only) section (p. 9).
2. Define tags with the specifications as described in the Tag Definition section (p. 11)
3. Define digital states as specified in the Digital States section (p. 9).
4. If the interface is running on a PI API node, define a proxy account for the machine the interface is running on (PI3 only). See the PI Data Archive manual for details.
5. 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 .
6. 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).
7. Define an IORATE tag, e.g. SYYGWPSY (VAX and NT only) as described in the Event Counter Tags section (p. 6).
8. Stop and restart the IORates process (PI2 only).
VMS Installation
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 initialisation 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_#.
Basic Installation
The enclosed tape contains the backup save set Ygw_Int.bck which contains the interface. This saveset contains new object files. If the interface is being installed at the same time as PI, change the default directory to PIBuild: and proceed straight to step 6.
1. Unpack the saveset to a “safe” directory.
2. Go to the safe directory
3. Mount the tape by:
mount/over=id tape0:
or whatever the name of your tape drive is.
4. Copy the saveset from the tape to the safe directory by:
copy tape0:*.* *.*
5. Unpack the saveset by:
backup/verify/log ygw_int.bck/sav *.*
6. Execute the Ygw_ command file by:
@YGW_SETUP_#
where # is the point source to be used for the interface. This command file copies the necessary files 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 PIBuild: for each additional interface substituting for # with a different point source for each.
7. 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:.
8. Complete the point database configuration as specified in this document.
9. Modify a copy of PiSysExe:Ygw_#.com for each interface point source.
10. Verify the Yokogawa Gateway operations as described in this document.
11. 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_#.
12. 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.
13. 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.
14. 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.
15. 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.
16. 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.
Windows NT Installation
The interface may be run from either interactively from the DOS prompt or as an NT service. Either of these methods can be started automatically when PI is started if they are on the PIHome node.
Basic Installation
1. Create a subdirectory within the PI Interfaces directory called ygw_# where # is the point source for the interface. If running on the PI home node, this Interfaces directory should be in \Pi or wherever PI was installed. If running on a PI API node create an Interfaces and an Adm subdirectory within the \Pipc directory or wherever the PI API was installed.
2. Copy the interface files into this directory. They are the following:
|Ygw_#.bat |YGW_OItem_#.txt |Ygi_Test.exe |
|Ygw_#.exe |YGW_Msg_#.txt |Ygi_Testb.exe |
where # is the point source for the interface.
3. Modify a copy of startup file for each interface (Ygw_#.bat). Ensure that this file runs the interface with the correct point source.
4. Run the interface by executing the startup file Ygw_#.bat where # is the point source.
Permanent Installation
5. If the interface is running on the PI Home node, edit the following files in the \PI\Adm directory or wherever PI was installed.
PiSiteStart.bat
Place the following lines at the bottom of this file:
Echo Starting Yokogawa Gateway Interface
Start “Yokogawa Gateway Interface” /min ..\interfaces\ygw_#\ygw_#.bat
PiSrvSiteStart.bat
Add the following to the last line:
..\interfaces\ygw\ygw_#.exe -start
PiSrvSiteStop.bat
Insert the following before the line at the bottom of the file which contains “:theend”:
..\interfaces\ygw\ygw_#.exe -stop
6. Run the PiServiceInstall.bat file from a MS-DOS prompt to install the interface as a service:
PiServiceInstall -auto
The “-auto” option will instruct NT to start the interface service automatically on power-on.
7. Place a copy of YGW_OItem_#.txt and YGW_Msg_#.txt and YGW_Sts_#.txt in the System32 directory of the Windows directory (the name of the windows directory may vary) e.g. C:\Winnt\System32. This is where the current directory of the interface will default to when running as a service and it will look here for these files.
8. To start the interface interactively, go to the C:\Pipc\Interfaces\Ygw_# directory (or wherever you placed the interface) and run the file Ygw_#.bat where # is the point source for the interface.
9. To start the interface as a service, run the PiSrvSiteStart.bat file or start it manually from the “NT Services” dialog box in the NT control panel.
10. To stop the interface while it is running as a service, run the PiSrvSiteSopt.bat file or by typing the following at the command prompt:
\pi\interfaces\ygw_#\ygw_#.exe –stop
where # is the point source of the interface to be stopped. Do not stop the service using the Windows NT Services dialog box unless it will not stop any other way. Stopping the interface using the Windows NT Services dialog box will stop it immediately and prevent the interface from cleaning up after itself.
11. Check the log file to verify that the interface that is running is the correct version.
Appendix — Error 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 |
Revision History
|Revision |Change Date |Change Author |Comments |
|Number | | | |
|— |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 |
|Rev 4 |4 Apr 99 |RGM |Complete overhaul an reformat |
|Rev 5 |26 Jul 99 |RGM |Removed Unix installation, Added error messages |
|Rev 6 |3 Mar 00 |RGM |Added comments, added NT RS-232 support |
| | | | |
| | | | |
| | | | |
................
................
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.