Moore APACS
Interface to the PI System
Version 1.4.5 and greater
Document revision A
1/28/2000 2:50 PM ii
Table of Contents
Introduction 4
Vendor Software Requirements 5
Interface Design Overview 6
Interface Point List 6
Output Data 6
Input Data 6
Scanning Principles 6
Timestamp 7
Point Configuration 8
Source Tag 8
Point Source 8
Point Type 8
Scan Flag 8
Convers 8
Instrument Tag 9
Extended Descriptor 9
Configuration Layers 9
Global Variables 9
Specification of Event based Scanning 9
Specification of Source Tag for Output Points 9
Location1 11
Location2 11
Location3 11
Location4 11
Location5 11
Other PI Point Configuration Parameters 11
Additional Point Parameters 12
PI Software Configuration 13
Point Source 13
Digital State Code 13
Network Environment 14
General Moore APACS Data Description 15
DataTag Structure 15
DataTag Access Method 15
Setting up the Interface 16
APACS Interface Environment 18
Starting and Stopping the Interface 18
Startup 18
Shutdown 18
Information and Error Messages 18
Installation 19
Appendix A. Input Tag Configuration 20
Scan-based List 20
Event-based List 22
Appendix B. Output Tag Configuration 23
PI Point with a Source Point 23
PI Point without Source Point 23
Appendix C. Intel PC Windows NT Platform 25
Interface Architecture 25
Software Requirements 26
Installation 26
Installation Requirements 26
Install the PI APACS Interface Toolkit 27
Configuring and Removing the Moore APACS Interface NT Service 27
Starting & Stopping the PI APACS Interface Process NT Service 27
Starting & Stopping the PI APACS Windows Application Interactively 27
Information and Error Messages 28
Network Environment 28
Specifying Hardware Environment 28
Appendix D. DEC VAX or Alpha Platform 30
Interface Architecture 30
Software Requirements 31
Installation 31
Installation Requirements 31
Interface Installallation 31
Software Configuration 32
Startup Procedure 32
Shutdown Procedure 32
Information and Error Messages 33
Re-Linking the PI-APACS Interface 33
Network Environment 33
Specifying Hardware Environment 33
Appendix E: Interface Distributions as Self-Extracting Executables 34
NT Installation 34
UNIX Installation 34
VMS Installation 34
Documentation Updates 34
Appendix F. File conversion utility for VMS save sets 35
Reblock 35
Installing REBLOCK 35
Useing REBLOCK 35
Sample Session on VMS node 36
VMS Set File Command 36
VMS BCK Save Set File 36
VMS Save Set .A or .B File 36
Appendix G: Communications Parameters 37
COMMUNICATIONS Heading 37
NETWORK Heading 38
MBUS_MNET Heading 39
Appendix H: APACS Data Type (Table 2) 40
Appendix I: PI Data Type / DataTag Type 42
Appendix J: APACS-API Utilities 44
DTAPI 44
DRAPI 47
Appendix K: Troubleshooting 48
Introduction
The PI Advanced Process Automation and Control System (APACS) Interface provides for the bidirectional transfer of data between APACS controller modules and the Plant Information (PI) System. The data connection and transfer between the PISystem and Moore APACS controller modules is made via either a Network Interface Module (NIM), a Rack-Mounted Network Interface (RNI), a MODULNET Interface (MNI) card, or a MODULBUS (MBI) card. A simple APACS architecture is shown in Figure 1.
Figure 1. APACS architecture
Note: Version 1.0.4+ of the interface runs with all versions of PI 2.x on an Alpha and only runs with PI 2.1.1 or greater on a VAX.
Supported Features /PI2 version / Yes
PI3 version / Yes
Sign up for Updates / Yes
Exception Reporting / Yes
Inputs (read) / Yes
Outputs (write) / Yes
Vendor Software Required / Yes[1]
Hardware Platforms / Windows NT-Intel, VAX VMS, Alpha VMS
Failover / No
Maximum Point Count / None
Vendor Software Requirements
The PI APACS Interface requires the PI-API Toolkit and the Moore APACS-API (Moore Products CO.).
Install the APACS-API on your platform by following the vendor installation procedure (see the Moore API toolkit software guide). Be sure to install the MBus version of the Moore software if you are using an MNI or an MBI card.
The PI APACS Interface is supported on the Windows NT Intel platform, and the OpenVMS VAX or Alpha platform. The PI APACS interface runs with an APACS System networked environment. The PI APACS program interface is linked with the APACS-API Toolkit library version 3.01 and higher, and with PI Toolkit library.
The PI APACS Interface can run either on the PI server node, a PINet node, or a PI API node.
Interface Design Overview
The PI APCS Interface consists of a single executable program and a number of utility programs for configuring, starting, and stopping the interface. The interface may be set either on a remote PC client or on the PI server node.
Interface Point List
At startup, the interface scans the PI Point Database for all associated points and builds its own point list. During runtime, the interface continues to check the PI Point Database each minute for point updates and modifies its point list accordingly.
Output Data
Output data occurs on a per tag basis. To improve performance, the data for an output comes from either a source tag or, if no source tag is specified, from an output tag. It is recommended that output tags derive their data from source tags.
If data from a source tag is used, the point type of the source tag must be the same as that for the output tag. If an output point has an associated source tag, it is recommended that exception reporting specifications of the output tag be the same as those for its source tag to ensure that the value for successful operations is written to the PI tag.
For output tags that specify a source tag, the results of the output operation, that is, the value successfully written or an error status, is saved in the snapshot of the output tag.
The source tag is used as the trigger, and if no source tag is specified, the output tag serves as the trigger. All events, whether changed or not, will be output.
If an output fails, BAD OUTPUT is written to the snapshot of the output tag if it has a source tag associated with it.
Input Data
The interface is designed to optimize data transfer and minimize communication traffic by collecting input data into groups. Grouping is determined by the interface at startup by taking points from the same memory region in the NIM or RNI with the same scan rate or trigger. The proper use of NIM or RNI memory can greatly enhance the efficiency and overall data throughput of the interface.
Scanning Principles
Input data is scanned at either a fixed scan rate or based on events of a trigger tag.
If fixed scanning is specified, the input data is scanned at a fixed scan class rate. The scan class is defined in the startup command file (see Section VII, Startup, Command File section); scan class defines an update period.
If a trigger tag is specified, it overrides the fixed scan rate.
If input data fails with an extended communication failure, the digital state I/O TIMEOUT is written to the Snapshot of the affected tags.
Scanning may be turned on and off with the Scan Code field in the Point Database. If a tag is set to SCAN OFF, the digital state SCAN OFF will be written to the tag if it is an input tag and to the output tag if the output tag has a source tag associated with it.
Timestamp
The PI APACS Interface will write all values to the snapshot using the System Time from the Operating System as the data's time stamp.
If the Interface program runs on a remote PC client, the interface will synchronize the data’s time stamp in accordance with the PI server node time.
Point Configuration
The following information is necessary for defining a PI point to be read from or written to an APACS controller module. Each PI point is associated with data in an APACS controller module, and each APACS controller module is accessed by a NIM or RNI name, unless an MNI/MBI is being used. Data on the APACS system is accessed by a named DataTag.
The format of the APACS DataTag name consists of text fields delimited by periods. Each field represents a configuration layer, the instance name of a derived function block or standard function block, and, ultimately, a variable name or function block element. Global variables can be defined within the APACS system. Global variables coming from an I/O card are referenced as %<variable name>; e.g. %D53F107C. Calculated global variables are referenced as | <variable name>|; e.g. | D53F107C|.
The APACS DataTag name in PI is composed of the “Extended Descriptor” and “Instrument Tag” parameters. The following are the PI point parameters specifically used by this interface.
Source Tag
The Source Tag may be any PI point whose snapshot value will serve as the value to be output.
Note: If you have PI 2.0 (or greater), the PI source tag attribute field must be used for source tag definition. If your PI version is lower than 2.0, you can specify the source tag in the extended descriptor as follows :
source =<any valid PI tag name>
Point Source
All points defined in the PI Database to be used by the PI APACS Interface must share a common point source. The point source is any one character variable, for example M. If using PI 2, the point source for the interface must be defined in the point source library before interface operation (see Section IV, Software Configuration).
Point Type
For PI 2, all three point types, real R, integer I, and discrete, are supported. String data is sent to the PI 2 event logger.
For PI 3, int16, int32, float16, float32, digital, and string point types are supported. String tags are supported for input PI points, but not for output PI points. That is, string data can be read from the APACS control module into PI but cannot be sent from PI to the APACS control module.
Scan Flag
The scan flag is used by the interface to determine if the interface should process values for a PI point. This allows the user to stop processing values for a point while the interface is online. The digital state SCAN OFF will be written to tags whose scan flag is off.
Convers
The convers tag attribute can be set to 0 to enable conversion of input values from percent of scan to Engineering Units.
Instrument Tag
The Instrument Tag defines the variable name, global variable name, or the function block element of the APACS DataTag name in an APACS Controller Module (ACM). The Instrument tag field is 32 characters long. An example (DataTag Name = RESOURCE1.PROG1.PV) with a APACS DataTag name for a variable PV calculated by a program named PROG1 in a controller module named RESOURCE1, is as follows:
Instrument Tag Field = PV
An example of an I/O global variable name (DataTag Name = RESOURCE1.D53F107C) is as follows:
Instrument Tag Field = %D53F107C
An example of a calculated global variable name (DataTag Name = RESOURCE1.D53F107C) is as follows:
Instrument Tag Field = |D53F107C|
Extended Descriptor
Configuration Layers
The extended descriptor is used to define the different configuration layers in an APACS controller module to attain the variable name or function block element (defined by the point Instrument Tag ). Each configuration layer consists of a text field; multiple configuration layers are delimited by periods. The Extended Descriptor field is 80 characters long.
An example (DataTag Name = RESOURCE1.PROG1.PV) of the APACS DataTag name for a variable PV calculated by a program named PROG1 in a controller module named RESOURCE1 is as follows :
Extended Descriptor Field = RESOURCE1.PROG1
Global Variables
For global variables, the Extended Descriptor only contains the RESOURCE name because the global variable name contains all the configuration layer information except for the resource name:
Extended Descriptor Field = RESOURCE1
Specification of Event based Scanning
The Extended Descriptor is also used to indicate if the value of the point will be obtained from the DCS when an event occurs; i.e., Event-Based Scanning. Event-based updates are useful for updating groups of PI tags after the occurrence of a significant process event, such as the end of a batch cycle.
This is specified by the string:
Event=<Tagname>,
where <Tagname> is the name of the event tag, followed by the configuration layer; for example:
Extended Descriptor Field = Event=SINUSOID|RESOURCE1.PROG1
Specification of Source Tag for Output Points
The Extended Descriptor is also used to specify a source tag for output points. This is specified by the string:
Source=<Tagname>,
where <Tagname> is the name of the source tag, followed by the configuration layer; for example:
Extended Descriptor Field = Source=SINUSOID|RESOURCE1.PROG1
Location1
1 Input from DCS
2 Output to DCS
Location2
This location code is not used by the interface.
Location3
This location code is only implemented if the interface is communicating to a PI 2 server.
Location3 is used to specify the Event Group for writing String Tags to the Event Logger (which is subsequently read by the PI Batch Module). Set the Event Group as follows:
6=Batch ID
7=Product ID
(* NOTE: Event Type must be specified as 31 in the Batch.cfg file)
Location4
Event-based points and output points do not use this location code. Set Location4 to 0 for these points.
Scan class number. Scan classes are defined in the interface startup file; each scan class defines an update period. This location code defines which scan class period is used to update the PI point group. For example, if the scan classes are specified in the interface startup command file as
/f=00:00:05 /f=00:01:00 /f=02:00:00
or, equivilantly, as
/f=5 /f=60 /f=7200
then Location4 = 1 indicates a scanning frequency of 5 seconds, Location4 = 2 indicates a scanning frequency of 1 minute, and Location4 = 3 indicates a scanning frequency 2 hours.
One can alter the above command-line parameters to specify the absolute time at which scans are scheduled. For example, if
/f=5,2 /f=60,3 /f=7200,30