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