Moore APACSInterface to the PI System

Version 1.4.5 and greaterDocument revision A

Table of ContentsIntroduction...............................................................................................................................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....................................................................................................................................................8Point Source..................................................................................................................................................8Point Type.....................................................................................................................................................8Scan Flag.......................................................................................................................................................8Convers.........................................................................................................................................................8Instrument Tag..............................................................................................................................................9Extended Descriptor......................................................................................................................................9

Configuration Layers........................................................................................................................................9Global Variables................................................................................................................................................9Specification of Event based Scanning.............................................................................................................9Specification of Source Tag for Output Points.................................................................................................9

Location1.....................................................................................................................................................11Location2.....................................................................................................................................................11Location3.....................................................................................................................................................11Location4.....................................................................................................................................................11Location5.....................................................................................................................................................11

Other PI Point Configuration Parameters.......................................................................................................11Additional 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

05/07/23 4:47 AM 1

Setting up the Interface...........................................................................................................16

APACS Interface Environment............................................................................................18

Starting and Stopping the Interface.....................................................................................18

Startup.............................................................................................................................................................18Shutdown.........................................................................................................................................................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...................................................................................................................................26Installation...........................................................................................................................26

Installation Requirements................................................................................................................................26Install the PI APACS Interface Toolkit..........................................................................................................27Configuring and Removing the Moore APACS Interface NT Service...........................................................27Starting & Stopping the PI APACS Interface Process NT Service................................................................27Starting & 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................................................................................................................................31Interface 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

05/07/23 4:47 AM 2

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......................................................................................................................................35Useing REBLOCK..........................................................................................................................................35Sample Session on VMS node........................................................................................................................36

VMS Set File Command......................................................................................................36

VMS BCK Save Set File.................................................................................................................................36VMS 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

05/07/23 4:47 AM 3

IntroductionThe PI Advanced Process Automation and Control System (APACS) Interface provides for the bi-directional transfer of data between APACS controller modules and the Plant Information (PI) System. The data connection and transfer between the PI System 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.

NIM

ACM

I/O

I/O

MODULRAC 1

Networking Link

Platform Running PI APACS Interface

FIGURE 1Figure 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.

05/07/23 4:47 AM 4

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 Yes1

Hardware Platforms Windows NT-Intel, VAX VMS, Alpha VMS

Failover No

Maximum Point Count None

Vendor Software RequirementsThe 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.

1 Vendor software is required for the APACS API Toolkit (contact Moore Products CO.).

05/07/23 4:47 AM 5

Interface Design OverviewThe 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 ListAt 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 DataOutput 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 DataThe 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 PrinciplesInput 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.

05/07/23 4:47 AM 6

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.

TimestampThe 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.

05/07/23 4:47 AM 7

Point ConfigurationThe 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.

05/07/23 4:47 AM 8

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

05/07/23 4:47 AM 9

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 ID7=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:00or, 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

then Location4 = 1 indicates a scanning frequency of 5 seconds beginning at (5n + 2) seconds after the hour (where n is an integer), Location4 = 2 indicates a scanning frequency of 1 minute beginning (60n+3) seconds after the hour, and Location4 = 3 indicates a scanning frequency 2 hours beginning at (7200n+30) seconds after midnight (the reference frame of an hour does not make sense when the period between scans is greater than 1 hour) .

One can also specify sub-second scan classes on the command line such as /f=0.5 /f=0.1

05/07/23 4:47 AM 10

or, similarly, sub-second scan classes with sub-second offsets can be defined, such as /f=0.5,0.2 /f=1,0

Location5

Bit extraction code. Location5 is used for extracting specific bits from the value returned by the APACS system. If no bit extraction is required, this location code should be set to 0. Location5 is significant only for the input PI point types integer I or discrete D. Location5 is ignored with PI point type real.

The format for extracting bits is XXYY, where YY is the first bit to be extracted and XX is the last bit to be extracted. The bit numbering is 01 to 32 (right to left), with 01 the least significant bit.

An example of bit extraction is show below. The variable PV, of APACS DataTag name RESOURCE1.PROG1.PV is an APACS IEC data type double integer (4 bytes). In the variable PV, the first bit (01) is required for the PI point PI:VALVE1 and the 10th through 3rd bits are required for the PI point PI:TEMP7. The Location5 for both points are as follows:

For the PI point PI:VALVE1, Location5 is set to 0101 (XX=YY= 01).

For the PI point PI:TEMP7, Location5 is set to 1003 (YY= 03, XX=10).

Note See Appendix A and Appendix B for examples of input and output PI point configuration.

Other PI Point Configuration ParametersThere are additional point parameters that apply to points updated by this interface. See the PI Data Archive Manual for information on these parameters:

Additional Point Parameters Tagname

Description

Point Source

Typical Value

PI 2 Starting Digital Code and Number of Digital States (point type D). PI 3 digital state set (point type digital).

Zero and Span (PI 2 point types R and I; PI 3 point types int16, int32, float16, and float32)

Engineering Units

Compression Specifications

Archiving Flags

Filter Code

Point Type

Resolution Code

Scan

Exception Reporting Specifications

05/07/23 4:47 AM 11

The following tag configuration parameters do not apply to this interface: Square Root Code

Totalization Code

UserInt1 & UserInt2

UserReal1 & UserReal2

05/07/23 4:47 AM 12

PI Software ConfigurationIn addition to the PI Point Definition, the Point Source, the I/O Rate Counter (only supported on the VAX or Alpha platforms), and the Interface Configuration files should be specified.

Point SourceThe point source may be any alpha character not currently used by another process or interface. PI 2: the point source may be defined by running the PointSrc display on the PI Menu, choosing a blank field from the point source list, and entering the following location parameter limits:

Location 1 Location 2 Location 3 Location 4 Location 5

1 -20000000 0 1 0

2 20000000 99 99 2 3131 (last bit)

PI 3: there is no Point Source configuration for PI 3.

Digital State CodeIn the PI 2 Digital State Table, check that the following code are defined. This only applies to PI2 systems. These states are already present in PI3 systems.

Digital State Code Digital State String

237 Bad Output

238 Scan Off

239 Scan On

246 I/O Timeout

251 Under Range

252 Over Range

255 Bad Input

299 Invalid Data

2 Limited by the startup command line, 256 characters maximum

05/07/23 4:47 AM 13

Network EnvironmentThe PI APACS interface is connected to the Moore APACS System via either a Network Interface Module (NIM), a Rack-Mounted Network Interface (RNI), a MODULNET Interface (MNI) card, or a MODULBUS (MBI) card. The NIM, RNI, MNI, or MBI software handles this communication.

The processing load on the NIM/RNI is determined by the number of computers (or workstations) connecting to the NIM/RNI, the number of concurrent applications running on each computer (or workstation), the amount of data that is requesting by each application, and the amount of network traffic in general.

Please refer to the appropriate Appendix in accordance with your platform for more detail.

05/07/23 4:47 AM 14

General Moore APACS Data Description

Data on the APACS system is accessed by an APACS DataTag name. The format of the APACS DataTag name consists of text fields delimited by periods, where each field represents a configuration layer. Each field can be up to 16 characters in length.

DataTag Structure The APACS data type can be any IEC standard type, as listed in Table 2 in Appendix H. The size and contents of the APACS data value is dependent on the data type.

Table 3 in Appendix I describes a matrix that illustrates the correlation between the PI type data and the APACS DataTag type. Cells that contain a solid symbol generally indicate a one-for-one correspondence for Read/Write access between the PI data type and APACS data type.

DataTag Access Method Data on the ACM (APACS Controller Module) is accessed by an APACS DataTag name. The format of APACS DataTag name is as follows :ResourceName.ProgramName.FunctionBlockName.<...>BlockElementName

orResourceName.ProgramName.DerivedName.<...>VariableName

An array of DataTags may be manipulated by the APACS interface. Individual APACS DataTags may be created for the individual array elements or the individual array elements may be added to a group (list) of tags. In this case, the individual array elements are manipulated the same as any other APACS DataTag name. All of the individual array elements must be included in a same DataTag group.

The syntax for creating an individual array element DataTag is :ResourceName.ProgramName.DerivedName.<...>ArrayName[Index1,Index2,...]

05/07/23 4:47 AM 15

Setting up the InterfaceAfter configuring the hardware and software, and after developing the PI Points associated with the PI APACS Interface, the interface may be started. The interface may be run manually; or, preferably, it should be configured to start and stop automatically with the starting and stopping of the PI System. Refer to the appropriate Appendix for your platform.

There are several option parameters in the piapacs.bat (WinNT), and piapacs.com (VMS) which control the operation of the interface program. Some of the parameters are optional. The parameters are described in the table below:

Parameter Description

/ps= The point source defines which PI points the interface will load at startup. The point source is defined with /ps=X, where X is the point source that was defined in the PI System for this interface. The point source is any one-character value used by the PI APACS Interface only, for example M.

/host= • For PI 2 server

The host argument defines the active PI Server node where the PI data for the subsequent input or output calls will be resolved. The APACS Interface connects to a PI Server node, which is defined with the /host=argument, where argument is the logical name of the active PI Server Node.

• For PI 3 server

The host argument defines the host TCP/IP port corresponding to pinetmgr (PI Network Process Manager) host TCP/IP port number. The host argument default is:

localhost:5450

Localhost is always set to the local machine. If the interface is not running on the PI3 server, the host argument should be specified as: host:5450, where host is the name of the PI3 server. :5450 tells the interface to connect to port 5450. If the pinetmgr process is configured to listen on a different port, change 5450 appropriately. For example, if you configured pinetmgr to listen on port 545, change the host argument to: localhost:545

/id= The interface number is specified by the /id= startup parameter, and is used to associate informational and error messages in the log file with the copy of the PIAPACS interface by which they are written.

/f= Specifies the scan period and phase. The period is the amount of time between scan. The phase is the time to start the first scan specified as offset from midnight.

The period and phase are supplied in the format of hh:mm:ss. A comma should separate the period and the phase. If the phase is not defined, the interface will start the scan cycle for this class as soon as possible.

You can define as many scan class as need.

/ec= The PI System maintains event counters to keep track of I/O rates of most of the PI processes. One of the counters may be assigned to the interface. The syntax to define the event counter is /ec=x, where x is the event counter number. The number can be any unused counter between 1-35 and 51-200.

05/07/23 4:47 AM 16

Parameter Description

The I/O Rate Counter measures the rate at which the interface sends values to the PI Snapshot, i.e. it serves as a measure of the data input load (it does not consider output load). To use the I/O Rate counter, a rate tag should first be configured, such as SY:PIAPACS.01, by copying the point definition information from another rate tag, for example, SY:SNP001. The interface rate tag should then be added to the I/O Rate List (PISysDat:IORates.dat file on VAX or Alpha machines, or \pipc\dat\iorates.dat file NT machines), by adding the entry "SY:PIAPACS.01,x", where x is the IO rate counter number.

For this new entry to take effect the IORate process must be stopped and restarted. For additional information see Data Rate Monitoring in the Interface Standard chapter of the PI Interface Manual (vol. 3) or the IORates sections in the PI Data Archive Manual (vol. 1).

/sn Tells the interface to ignore the exception specifications of the tag and put all the input events into the PI snapshot. By default, the SN flag is not used to reduce data traffic.

/db The interface will print out more messages if /db is specified on the interface startup command line. Note that during normal operation, it is best not to use the /db option, to keep the log files from growing too large.

/nim The NIM name (or RNI name) is the name that is configured on the computer running the APACS system. Many NIMs or RNIs may be necessary to communicate with the APACS Controller Module (ACM). This is defined as follows: /NIM=hostname, where hostname refers to the logical NIM or RNI host name.

Note: On a PC running Intel Windows/NT, the NIM or RNI name and the corresponding IP address are configured in HOSTS file (see Appendix C, PC Intel NT for more detail). The number of NIMs connected to the PC running the APACS interface is limited to a maximum of 10 NIMs.

/local Indicates the interface will communicate with the APACS via a MODULNET (MNI) card or a MODULBUS (MBI) card. Either /nim, /rni or /local must be specified on the command line.

/stopstat If the /stopstat command line parameter is specified, the interface writes I/O timeout to all INPUT points (not OUTPUT), zeros the event counters, and disconnects from the PI server.

/sio When the /sio flag is specified, the outputs are no longer written at startup or when points are edited.

/q Tells the interface to queue up events before putting the data into the PI system. The q version is more efficient if the interface is on a separate computer from the PI Server. However, it will slightly delay the update of the snapshot value if the data rate is low. The buffer size of the event queue for the interface is 128 events.

/orq Tells the interface to read data for tags even when the Data Quality is DATA_QUESTIONABLE or DATA_UNAVAILABLE. Default (and original) interface behavior is to write Bad Input when Data Qualitiy is anything other than DATA_GOOD. Option added because the Moore API utilities read data tag values as long as the Data Quality is not DATA_BAD, not just when it is DATA_GOOD.

/noou Tells the interface to suppress writing OVERRANGE and UNDERRANGE digital states for values that are under or over zero or span, respectively. (1.4.5)

The following is a sample interface startup command file.

05/07/23 4:47 AM 17

APACS Interface EnvironmentTo run this interface, a number of support files are required by the communication system. These files are supplied with the APACS-API. Refer to the appropriate Appendix for your platform.

Starting and Stopping the Interface

StartupA startup procedure is provided to start the PI APACS Interface. Refer to the appropriate Appendix in accordance with your computer running this interface.

ShutdownA Shutdown procedure is provided to stop the PI APACS Interface. Refer to the appropriate Appendix in accordance with your computer running this interface.

Information and Error MessagesThe PI APACS Interface provides a comprehensive information and error-messaging scheme. The interface will create and maintain a log file where all operational information, warnings, and errors will be maintained. Refer to the appropriate Appendix for your platform running this interface.

05/07/23 4:47 AM 18

InstallationWhen installing a PI APACS Interface, all of the necessary files will be linked and placed in the appropriate directory. First refer to the appropriate Appendix for your platform, and follow the specific installation procedure. Then take the following steps:

1. Choose a Point Source character for the PI APACS Interface Points. If you are using PI 2, define the point source using the PointSrc screen on the PI 2 Menu. PI 3 does not support a PointSrc definition menu at this time.

2. Configure Points for the PI APACS Interface.

3. Create I/O Rate Tags for each interface as desired (not supported on Windows NT.)

4. Modify the PI startup procedure and PI shutdown procedure.

5. Start the interface manually or automatically.

05/07/23 4:47 AM 19

Appendix A. Input Tag ConfigurationPI points can be read from the APACS system either at a specified scan frequency or when a specified event occurs (event-based updating). A scan-based list exists for each scan class defined in the command line arguments, and these lists are updated at the frequencies specified on the command line.

An event-based list is established for each unique event point specified in the Extended Descriptor field. If an event point is specified, any scan class specified in Location4 is ignored. The event point is monitored for exceptions; the list for an event point is updated when an exception occurs. If the APACS system indicates the read was not successful, BAD INPUT (digital state code 255) is sent to the PI point. Location1 must be set to 1 to indicate an input.

The APACS point database is arranged in groups of tags. Each group of tags is read in a rapid fashion to provide fast updating of large collections of data. Therefore, the following are some general rules applied by the interface to improve performance :

All DataTag in a group should come from the same APACS controller resource. If a group contains DataTags from different resources, the amount of time to read the data is no faster than the slowest controller.

A small number of groups, each containing a large number of tags, is more efficient than a large number of groups, each containing a small number of tags. This is mainly due to the communication overhead per group.

DataTags of similar dynamics or similar scan requirements should be grouped together in the same group.

Scan-based ListThe APACS interface schedules the updates of the scan class lists. When a scan period for a particular scan class has expired, this list is read from the APACS system. A list is composed of one or more groups of APACS DataTags.

An example with three different resources (ACM1, ACM2 and ACM3) is as follows :

From resource1 (ACM1) : The user defines a list of DataTags, named List1 (DataTag1 to DataTag12).

From resource2 (ACM2) : The user defines a list of DataTags, named List2 (DataTag1 to DataTag20).

From resource3 (ACM3) : The user defines a list of DataTags, named List3 (DataTag1 to DataTag30).

The user defines 2 scan class definition with periods of 5 seconds (Scan class F1) and 1 minute (Scan class F2).

05/07/23 4:47 AM 20

Scan F1Grp 1

Scan F1Grp 2

Scan F2Grp 3

Scan F1Grp 4

Scan F2Grp 5

DataTag1

DataTag 12

DataTag1

DataTag 10 DataTag 20

DataTag1

DataTag 25

DataTag26

DataTag 30

DataTag11

ACM1 Resource1 ACM2 Resource2

NIM

ACM

I/O

I/O

ACM3 Resource3

SCAN

CLASS DEFINITION

PC Running APACS Interface

NIM

ACM

I/O

I/O

NIM

ACM

I/O

I/O

DataTag1

DataTag20

F2F1

DataTag1

DataTag30

F2F1

List2 List3DataTag1

DataTag12

F1

List1

The user distributes each DataTag in an appropriate scan period, for example :

For ACM1, all DataTags in List1 are read with period of 5 seconds (Scan F1). The Location4 is set to 1 for all PI points defined in the List1.

For ACM2, DataTag1 to DataTag10 are read with period of 5 seconds (Scan F1) and DataTag11 to DataTag20 are read with period of 1 minute (Scan F2). The Location4 is set to 1 (F1) for all PI points read with period of 5 seconds and Location4 is set to 2 (F2) for all PI points read with period of 1 minute.

For ACM3, DataTag1 to DataTag25 are read with period of 5 seconds (Scan F1) and DataTag26 to DataTag30 are read with period of 1 minute (Scan F2). The Location4 is set to 1 (F1) for all PI point read with period of 5 seconds and Location4 is set to 2 (F2) for all PI points read with period of 1 minute.

When the scan class1 period has expired, Grps 1, 2, 4 are read from ACM1 (Grp 1), ACM2(Grp2) and ACM3 (Grp 4). When the scan class2 period has expired, the Grps 3 and 5 are read from ACM2 (Grp 3) and ACM3 (Grp 5).

An example showing PI point configuration associated with DataTag1 in a controller module named Resource1 is as follows :

Source Tags Not Used

Point Source = M Example: M for Moore PI APACS Interface)

Point Type = R Real

Scan Flag = ON

Instrument Tag = DataTag1

Extended Descriptor = Resource1

Location1 = 1 Read

Location2 = 0 0=read D,R,I,float16,float32,int16,int32,digital

05/07/23 4:47 AM 21

Source Tags Not Used

1=read string tag

Location3 = 0 Event Group for writing APACS String Tags to the Event Logger to be read by the PI Batch Module: 6=Batch ID; 7=Product ID

Location4 = 1 Scan F1

Location5 = 0 No mask

Event-based List When an exception report is received for the event point, all PI points associated with this event are read from the APACS system. Location4 is ignored. The general suggestions about arrangement of DataTags in groups are also appropriate for an event-based list.

An example PI point configuration for an event point named PI:EVENT1, associated with a DataTag named DTEVENT in a controller module named RESOURCE is as follows :

Source tags not used

Point source = m Example: M like Moore PI APACS Interface

Point source = m

Point type = i Integer

Scan flag = on

Instrument tag = dtevent

Extended Descriptor = event=PI:EVENT1|RESOURCE

Location1 = 1 Read

Location2 = 0 Not used

Location3 = 0 Not used

Location4 = 0 Ignored

Location5 = 0 No mask

05/07/23 4:47 AM 22

Appendix B. Output Tag ConfigurationPI points written to the APACS system are treated as special event-based points. The source tag point may used to specify a source point that will be monitored for exception reports. If a source point is not specified, the PI point is monitored for exception reports.

On an exception report, the value of the source point or PI point (if no source point is defined) is written to the APACS system. If the APACS system indicates the write was successful, and a source point was defined, the value of the source point is also sent to the PI point. If the APACS system indicates the write was not successful, and a source point was defined, BAD_OUTPUT (digital state code 237) is sent to the PI point. Location1 must be set to 2 to indicate an output.

PI Point with a Source PointSource points apply to output points only. The source point supplies the data to be written to the APACS data controller module. Any valid PI point can be a source point (See the DA manual for more information on this parameter).

An example of PI point configuration for an output point associated with a source point named SOURCEDATA is shown below. The PI point will write to the DataTag named DataTagOutput in a controller module named RESOURCE.

Source Tag = SOURCEDATA

Point Source = M (Moore APACS System)

Point Type = I (Integer)

Scan Flag = ON

Instrument Tag = DataTagOutput

Extended Descriptor = RESOURCE

Location1 = 2 (write)

Location2 = 0 (not used)

Location3 = 0 (not used)

Location4 = 0 (ignored)

Location5 = 0 (ignored)

PI Point without Source PointAn example of PI point configuration for an output point defined with a DataTag named DataTagOutput in a controller module named RESOURCE.

Source Tag not used

Point Source = M (Moore APACS System)

Point Type = R (Real)

05/07/23 4:47 AM 23

Scan Flag = ON

Instrument Tag = DataTagOutput

Extenuated Descriptor = RESOURCE

Location1 = 2 (write)

Location2 = 0 (not used)

Location3 = 0 (not used)

Location4 = 0 (ignored)

Location5 = 0 (ignored)

05/07/23 4:47 AM 24

Appendix C. Intel PC Windows NT PlatformInterface Architecture

The PI APACS interface uses the APACS API and the PI API to exchange data between a PI system and an APACS system. All communication functions provided by this interface support communication with either an APACS Network Interface Module (NIM), the APACS Rack-Mounted Network Interface (RNI), a MODULNET Interface (MNI) card, or a MODULBUS (MBI) card.

The PI APACS interface uses TCP/IP protocol to communicate with each ACM (APACS Controller Module) via the NIM or RNI.

Where:

NIM represents the Network Interface Module or the Rack-Mounted Network Interface (RNI).

ACM represents the APACS Controller Module.

I/O represents a series of modules acting as interfaces between control modules and field termination signals.

For a connection to a TCP/IP network , the PC communication includes the appropriate TCP/IP card in your PC and the MODULRAC (module rack) includes a Network Interface Module (NIM), a Rack-Mounted Network Interface (RNI), a MODULNET Interface (MNI) card, or a MODULBUS (MBI) card. This arrangement allows a variety of cabling options to be used and opens the system to support a connection to an existing plantwide network.

05/07/23 4:47 AM 25

Software RequirementsThe PI APACS Interface uses the PI-API Toolkit and the APACS-API.

Install the APACS API (Moore Products CO.) on your NT platform by following the vendor installation procedure (see the Moore APACS API 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. The APACS interface runs on a networked PC environment on which the dynamic linked libraries PIAPI32.DLL and MSVCRT.DLL (Microsoft Visual C++ Run Time library) are used.

The APXAPIWX.DLL is provided by Moore Products Co. This library uses TCP/IP communication software to communicate with the Network Interface Module (NIM), the Rack-Mounted Network Interface (RNI), a MODULNET Interface (MNI) card, or a MODULBUS (MBI) card on the APACS System. The PIAPI32.DLL for Intel Windows NT requires TCP/IP network communication software (WinSock).

The PI APACS program interface is linked with the APACS-API Toolkit library version 3.01 or greater and with PI Toolkit library (PI API for Windows NT is required).

The PI APACS Interface can run either on the PI server node or on a PI remote PC client. For either, the APACS Interface is delivered by a floppy diskette as follows:

PI APACS Interface software package:PIAPACS.EXE: PI APACS Interface executable filePIAPACS.BAT: Startup command filePIAPACS_xx.txt: Release notes, where xx indicates the versionDTAPI.EXE: Utility to test communications with the APACSDRAPI.EXE: Utility to test what Moore Nodes, Racks, and Slots

are visible from the PCPIAPACS.DBG: Debug Symbols

The debug symbols file needs to be copied to the \winnt\symbols\exe directory. If this directory does not exist, it needs to be created.

With Intel NT, it is possible to configure your system so that PI APACS Interface process is run as an NT service, which automatically starts when the NT system is started.

Installation

Installation RequirementsIf PI APACS Interface runs on the PI server node, make sure that PI 3 Data Archive is correctly installed (refer to the PI Data Archive for Windows NT and UNIX manual).

Or

If PI APACS Interface runs on a PI remote PC client, make sure that PI API package is correctly installed (refer to the PI API manual Appendix B).

Each NIM/RNI uses TCP/IP network protocol. TCP/IP must be installed and configured on the computer running the interface.

05/07/23 4:47 AM 26

Install the PI APACS Interface ToolkitThe following files should be copied to a directory structure similar to the one below:

PI HOME DIRECTORY\

INTERFACES\

PIAPACS\

PIAPACS.EXE

PIAPACS.BAT

Configuring and Removing the Moore APACS Interface NT Service

To configure the PI Moore APACS interface to run as a service, from the interface directory, execute:PIAPACS –install –depend tcpip

To configure the PI Moore APACS interface to run as a service and restart automatically on reboot, from the interface directory, execute:PIAPACS –install –auto –depend tcpip

To configure the PI Moore APACS interface to run as a service, restart automatically on reboot and run with API Buffering, from the interface directory, execute:PIAPACS –install –auto –depend “tcpip bufserv”

To remove the PI Moore Service:PIAPACS –remove

Starting & Stopping the PI APACS Interface Process NT ServiceBefore working with service, make sure that the PI APACS Interface process is stopped.

Start the PI APACS service either by typing PIAPACS –start in the Interfaces installation directory or from the Services Applet.

Note When the piapacs service will start successfully, the Status of the service will set to Started (show up in the list of the services from the Services program).

To stop the PI APACS Interface you can click the Stop button in the Services program located in your Windows Control Panel or by type PIAPACS –stop in the Interface installation directory.

Starting & Stopping the PI APACS Windows Application InteractivelyAfter configuring the hardware (APACS System) and software (PI system), and after developing the PI points associated with the PI APACS Interface, the interface may be started. It is possible to configure your system so that the PI APACS Interface process is run as NT service which automatically start when the NT system is started. It is easier to troubleshoot the PI APACS Interface when the process is started manually like a windows application, so configuring the NT services is best done after the PI installation or upgrade is verified to be working correctly. If you do not configure the software to run as a service, you can startup the system manually by typing:

05/07/23 4:47 AM 27

PIAPACS.BAT

at the command prompt. If you are not currently in the same directory where the interface program resides, you need to specify the full path name of the command file. Also, you may want to specify the full path name for the interface program in the command file.

To stop the PI APACS Windows application, follow this procedure:

1. Double click (maximize the windows) on the PI APACS windows to stop.

2. Press the “CTRL C” sequence inside of the PI APACS windows.

3. Waiting for the MS-DOS prompt and type exit and <Enter Key>.

Information and Error MessagesThe PI APACS Interface provides information and error messages in a local log file. The PI APACS Interface sends all status, warning, and error messages to the local log file. The local log file is called pipc.log and is located in the \DAT directory (pointing by the PIHOME entry, such as c:\PIPC\dat\pipc.log ). Typical messages sent to this file include startup configuration, number of points loaded, point load errors and warnings, and network communication problems. If the interface stops unexpectedly or if other problems are suspected, this file should be viewed.

Network EnvironmentThe Networked PI PC (on server node or remote PC client) makes a connection to the NIM/RNI(s) by utilizing the HOSTS file. This file contains the names and IP addresses of the NIM/RNI(s) to which the PC will attempt to connect. The HOSTS file itself can be modified using a text editor such as NOTEPAD. Further, the HOSTS file should be saved in a backup file prior to making any changes.

If a NIM or RNI is added to the HOSTS file, the APACS interface application must be restarted with the appropriate command line for the new NIM or RNI argument. Usually this file is located in the \WINNT\SYSTEM32\DRIVERS\ETC directory.

The HOSTS file is used by Microsoft TCP/IP for Windows NT. This file contains the mappings of IP addresses to host names. Each entry should be kept on an individual line. The IP address should be placed in the first column followed by the corresponding host name. The IP address and the host name should be separated by at least one space. The # sign is the comment character. Everything following the comment character will be ignored.

Example line in HOSTS file:

102.54.94.97 NIMPLANT1 # Res. ACM1/MODULRAC1

The APACS interface in the PC can connect to up to 10 NIMs. Each NIM, however, has a limit of 5 connections (31 connections for Release 3).

Specifying Hardware EnvironmentAPACS.INI is the APACS initialization file, located in the C:\ETC directory. It contains all the specifics of the hardware environment.

Note: This file will be created by default when you will run your PI APACS Interface program for the first time. The APACS.INI file itself can be modified using a text editor such as NOTEPAD. Further, the existing APACS.INI file should be saved in a backup file prior to making any changes.

05/07/23 4:47 AM 28

The APACS.INI file is used by the APACS interface application and contains various parameters that affect communication performance. If any of the parameter values are changed, the APACS interface application must be restarted for the new parameter values to take effect.

All parameters are described and listed in Appendix F.

05/07/23 4:47 AM 29

Appendix D. DEC VAX or Alpha PlatformInterface Architecture

The PI APACS interface uses the APACS API and the PI API to exchange data between a PI system and an APACS system. All communication functions provided by this interface support communication with an APACS Network Interface Module (NIM), or Rack-Mounted Network Interface (RNI), a MODULNET Interface (MNI) card, or a MODULBUS (MBI) card.

NIM

ACM

I/O

I/O

MODULRAC 1

Networking

PI Running APACS Interface

MODULRAC n (n<=10)

FIGURE 1

NIM

ACM

I/O

I/O

DEC Platform

Where:

NIM represents the Network Interface Module or the Rack-Mounted Network Interface (RNI).

ACM represents the APACS Controller Module.

I/O represents a series of modules acting as interfaces between control modules and field termination signals.

For a connection to a TCP/IP network, the VAX/Alpha machine requires the appropriate TCP/IP card in your DEC platform and the MODULRAC (module rack) includes a Network Interface Module (NIM), a Rack-Mounted Network Interface (RNI), a MODULNET Interface (MNI) card, or a MODULBUS (MBI) card. This arrangement allows a variety of cabling options to be used and permits the system to support a connection to an existing plantwide network.

05/07/23 4:47 AM 30

Software RequirementsThe PI APACS Interface uses the PI-API toolkit and the APACS-API.

The PI APACS Interface is supported on the OpenVMS VAX or Alpha platform. The PIAPACS interface runs with an APACS System networked environment. The PI APACS program interface is linked with the APACS-API Toolkit library version 3.03 and with PI Toolkit library.

The PI APACS Interface can run either on the PI server node or on a PINet node.

The APACS Interface is delivered separately on a diskette and contains the following files:

PIAPACS Interface software package:PIAPACS.OBJ : PI APACS Interface object fileUNIINT.OBJ : Universal Interface object filePIAPACS.COM: Startup command filePIAPACSLINK.COM: Build the PI APACS Interface.PIAPACSDETACH.COM: Detach the PI APACS Interface program.

And PIAPACS Interface support files:REBLOCK.EXE : Reblock utility for VAX VMSREBLOCK_ALPHAVMS.EXE : Reblock utility for Alpha VMSREBLOCK.README : Instructions on using Reblock utilityDTAPI.EXE : Utility to test communications with the APACSDRAPI.EXE : Utility to test what Moore Nodes, Racks, and Slots

are visible from the PC

Installation

Installation Requirements1. Install the APACS API (Moore Products CO.) on your platform by following the vendor

installation procedure (see the Moore APACS API software guide).

2. Before installing the PI or PINet System, you must create a logical name to reach the APACS API library (LIBAPXAPI_E.OLB file) by entering from the DCL prompt:$DEFINE PIAPACS_LIB_DIR NameDisk::<apacsapi.lib>where: NameDisk is the disk name where APACS API is installed.

Interface InstallallationThe Moore APACS Interface is now being shipped on floppy diskette. The enclosed diskette contains the backup save set PIAPACS.BCK, which contains the PI-Moore APACS Interface, and its support files.

1. FTP the PIAPACS.BCK file and the REBLOCK files from your PC to your VMS machine.

2. Run Reblock on the save set, or on VMS nodes running VMS 6.0 or greater, use the VMS Set File command to reformat the file internally to the correct VMS save set standard block size of 32356. For more information on Reblock and the VMS Set File command, see Appendix E.

3. Unpack the saveset to a “safe” directory by:backup/verify/log piapacs.bck/sav *.*

05/07/23 4:47 AM 31

2. Copy the files contained in PIAPACS.BCK to PIBuild: and go to that directory.

3. Link the interface by executing @ piapacslink. The executable piapacs.exe will then get copied to pisysexe.

Software ConfigurationIn addition to the PI Point Definition, the PIPACS interface is started by executing the startup file PISysExe:PIAPACS.COM. PIAPACS interface will have its own startup file, in which the point source (/ps=), event counter (/ec=), NIM Names or RNI Names (/NIM= or /RNI) or /LOCAL, and the Scan Class Definition (/f=). The startup file should be kept in the PISysExe: directory. The following is an example interface startup file, which may be modified:$! PIAPACS.COM file$!$! PIAPACS Startup Command File $! 03/20/96 JYG Oil System Software$!$!Location of the PIAPACS executable file$ piapx :== $pisysexe:piapacs.exe$!$! Startup Parameters$ piapx /ps=A /ec=20 /f=00:00:10 /f=00:00:30 /NIM=LOCALHOST

_ /pihome=2 /id=1$ exit[End of file]

Startup ProcedureAfter configuring the hardware (APACS System) and software (PI or PINet system), and after developing the PI points associated with the PI APACS Interface, the interface may be started. The Interface may be run manually, or, preferably, it should be configured to start and stop automatically with the starting and stopping of the PI system.

The PIAPACS Interface is started by running from the DCL prompt:$@PISysExe:PIAPACSDetach

This command file presumes that the file PISySExe:PIAPACS.com has been configured. To automate the interface startup, just add the above run line to the file PISysMgr:SiteStart.com.

Shutdown ProcedureTo stop the PIAPACS Interface, execute the following command:$@PISysExe:Stop PIAPACS

Stopping an interface in this manner does not place shutdown events in the Snapshot. To automate the shutdown, add the above line for PIAPACS interface to PISysMgr:SiteStop.com file.

When the PI System is shutdown, the points coming into the system should receive shutdown events. Modify the argument list for program ShutdownEvents, which is executed from files ShutdownEvents.com and CheckForCrash.com. These files are all located in PISysExe.

05/07/23 4:47 AM 32

Information and Error MessagesThe PI APACS Interface provides information and error messages in a local log file. The PI APACS Interface sends all status, warning and error messages to the local log file. The local log file is called PISysExe:PIAPACS.OUT

In addition, the interface will forward all important announcements to the PI Message Log. Typical messages sent to this file include startup configuration, number of points loaded, point load errors and warnings, and network communication problems. If the interface stops unexpectedly or if other problems are suspected, this file should be reviewed.

Re-Linking the PI-APACS InterfaceTo re-link the PI APACS Interface,$ set def pibuild:$ @PIAPACSLINK.COM

Network EnvironmentThe APACS interface can connect to up to 10 NIMs. Each NIM, however, has a limit of 5 connections (31 connections for Release 3). Networked DEC (VAX or Alpha) platform make their connections to the NIM(s) by utilizing the HOSTS file. This file contains the names and addresses of the NIM(s) to which the DEC platform will attempt to connect.

Specifying Hardware EnvironmentAPACS.INI is the APACS initialization file, located in the Sys$Common:[APACS] directory. It contains all the specifics of the hardware environment.

Note The APACS.INI file itself can be modified using a text editor such as EDIT. The existing APACS.INI file should be saved in a backup file prior to making any changes.

The APACS.INI file is used by the APACS interface application and contains various parameters that affect communication performance. If any of the parameter values are changed, the APACS interface application must be restarted for the new parameter values to take effect.

All parameters are described and listed in Appendix G.

05/07/23 4:47 AM 33

Appendix E: Interface Distributions as Self-Extracting Executables

PI Interfaces are now being shipped on floppy diskette, or are available for download via the OSI FTP server. Either method provides a Windows NT/9x self-extracting executable zip file that contains zipped files for the platform on which your interface is intended to run.

1. Copy or move the distribution .exe file from diskette or the OSI FTP server to your PC (running Windows NT or Windows 9x).

2. Unpack the .exe file by clicking on it from Windows Explorer, or from running the executable from the command prompt. You will be prompted for where to unzip the files. Be sure to unzip to a safe directory, so as not to over-write any existing configuration files.

NT Installation3. Move the distribution files to the correct directory, and follow the setup instructions in the corresponding interface manual.

UNIX Installation3. Ftp the distribution files from your PC to your UNIX node, and follow the setup instructions in the corresponding interface manual.

VMS Installation3. FTP the interface .BCK save set file and the REBLOCK files from your PC to your VMS machine.

4. Run Reblock on the save set, or on VMS nodes running VMS 6.0 or greater, use the VMS Set File command to reformat the file internally to the correct VMS save set standard block size of 32356. For more information on Reblock and the VMS Set File command, see the section below on File Conversion Utilities for VMS Save Sets.

5. Unpack the save set to a “safe” directory by:backup/verify/log savesetname.bck/sav *.*6. Follow the installation instructions on linking in the corresponding interface manual.7. Follow the setup instructions in the corresponding interface manual.

Documentation UpdatesInterface manuals should now be, or will soon be included in the interface distribution. For interface manual updates, you can view or download the latest documentation from our Support Web:

http://support.osisoft.com

After registering the first time, go to the PI Interfaces link and then view the spreadsheet from the Documentation link

05/07/23 4:47 AM 34

Appendix F. File conversion utility for VMS save sets

There are two options for internally reformatting the interface VMS save sets bck files to the correct VMS save set standard block size of 32356. The internal block size gets restructured when ftp’ing files from non-VMS computers.

ReblockThis utility allows you to convert VMS save sets back to their original internal format after downloading them in binary mode from the FTP server to your VAX or Alpha.

In binary file transfer mode, FTP imposes a maximum record size of 512 bytes. Since the standard record length of a VMS save set is 32256 bytes, FTP breaks the records apart during the upload. When you download the file, the record size is still 512 bytes.

REBLOCK reorganizes the file so that the standard VMS save set record format is restored. You can download executable versions of REBLOCK for both VAX/VMS and Alpha/VMS. A VMS executable has a record size of 512 bytes, so it is ready to use as soon as it is downloaded.

This utility is also available in the 'pub/reblock' directory of the FTP server at OSI Software, Inc. It is offered without warranty.

Installing REBLOCK1. Switch to binary mode using the command 'bin'.

2. Move the correct executable to your VMS node via FTP:

VAX/VMS : get reblock.exe reblock.exe

Alpha/VMS: get reblock_alphavms.exe reblock.exe

REBLOCK is ready to use.

Useing REBLOCK1. Type RUN REBLOCK at the "$" prompt. You are prompted for a filename.

Enter the name of the save set downloaded from the FTP server and hit return.

2. When REBLOCK has processed the file, the filename prompt reappears again.

REBLOCK does NOT create a new file version; it reorganizes the existing file.

05/07/23 4:47 AM 35

3. You may process other files, or type "\" to exit.

Sample Session on VMS node$ run reblock

REBLOCK: Convert file to blocksize 32256

Filename ("\" to exit): savesetname.bck

Filename ("\" to exit): \

VMS Set File Command

VMS BCK Save Set FileThere is a VMS command available with VMS 6.0 and later.$ Set File/attribute=(lrl:32256) savesetname.bck

Set File does the same thing as the REBLOCK program does, but from the operating system level.

VMS Save Set .A or .B FileIf you have downloaded a VMSInstal save set with a “.A” or a “.B” file extension that was not wrapped in a .bck file, and you have VMS 6.0 or later, you can recover the “.A” and “.B” VMSInstal save sets with the following command:$ Set File/attribute=(lrl:9216) savesetname.A

$ Set File/attribute=(lrl:9216) savesetname.B

This will re-order the VMSInstal save set to the non-standard block size required by VMSInstall.com

05/07/23 4:47 AM 36

Appendix G: Communications Parameters

The APACS.INI file is used by all PIAPACS Interfaces and contains various parameters that affect communications performance. These parameters are listed in the APACS.INI file under two or three headings (COMMUNICATIONS and NETWORK for Ethernet communications, COMMUNICATIONS, NETWORK, and MBUS_MNET for MBUS communications). Any changes made to the APACS.INI file require a stop and restart of the PIAPACS interface to take effect.

COMMUNICATIONS HeadingThe COMMUNICATION heading contains parameters that are used whenever communication functions are performed.

The MBUS_RETRY_ADDER value is a number that is added to the general communication retry count (1), and the resulting sum is the total number of retries used by the MODULBUS-based APACS interface when sending a message requiring a response. Increasing this value may delay the detection of faulty communications, while decreasing this value may result in flagging valid communications as faulty. It has a setting range of 0 to 65535 and a default setting of 3. The total timeout period for a single message is the total number of retries (one plus MBUS_RETRY_ADDER) times the total message timeout value (2000 plus MBUS_TIMEOUT_ADDER).

The MBUS_TIMEOUT_ADDER value is the number of milliseconds that is added to the general communication timeout value (2000 milliseconds), and the resulting sum is the total message timeout value used by the MODULBUS-based APACS interface when sending a message requiring a response. Increasing this value may delay the detection of faulty communication while decreasing this value may result in flagging valid communication as faulty. It has a setting range of 0 to 65535 milliseconds and a default setting of 0 milliseconds. The total timeout period for a single message is the total number of retries (one plus MBUS_RETRY_ADDER) times the total message timeout value (2000 plus MBUS_TIMEOUT_ADDER).

The NET_RETRY_ADDER value is a number that is added to the general communication retry count (1), and the resulting sum is the total number of retries used by the network-based APACS interface when sending a message requiring a response. Increasing this value may delay the detection of faulty communications, while decreasing this value may result in flagging valid communications as faulty. It has a setting range of 0 to 65535 and a default setting of 2. The total timeout period for a single message is the total number of retries (one plus NET_RETRY_ADDER) times the total message timeout value (2000 plus NET_TIMEOUT_ADDER).

The NET_TIMEOUT_ADDER value is the number of milliseconds that is added to the general communication timeout value (2000 milliseconds), and the resulting sum is the total message timeout value used by the network-based APACS interface when sending a message requiring a response. Increasing this value may delay the detection of faulty communication while decreasing this value may result in flagging valid communication as faulty. It has a setting range of 0 to 65535 milliseconds and a default setting of 1000 milliseconds. The total

05/07/23 4:47 AM 37

timeout period for a single message is the total number of retries (one plus NET_RETRY_ADDER) times the total message timeout value (2000 plus NET_TIMEOUT_ADDER).

Note Generally, increasing these values will make the communications more robust, but may cause slower operation. Decreasing these values will cause faster operation, but may make communications less robust. If values are increased too much, the detection of faulty communications may be delayed. However, if values are decreased too much, perfectly valid communications may be flagged as faulty.

The following table (Table: Total Timeout Periods) shows the total communication timeout periods (in milliseconds) possible for various X_RETRY_ADDER and X_TIMEOUT_ADDER values (X is either MBUS or NET).

X_RETRY_ADDER

X_TIMEOUT_ADDER 0 1 2 3 4 5

0 4000 6000 8000 10000 12000 14000

1000 6000 9000 12000 15000 18000 21000

2000 8000 12000 16000 20000 24000 28000

3000 10000 15000 20000 25000 30000 35000

4000 12000 18000 24000 30000 36000 42000

5000 14000 21000 24000 35000 42000 49000

Total Timeout Periods in Milliseconds

The PBREAD_MESSAGE_LIMIT value is the maximum number of outstanding messages that can be transmitted by the APACS interface to any controller module. Decreasing this value may result in an increase of time required to read a DataTag list. Conversely, increasing this value may result in a decrease of time required to read a DataTag list with the potential that at some point this benefit is outweighed by the increase of communication resources (memory) needed for reading the DataTag list. It has a setting range of 1 to 1000 and a default setting of 10.

The CLAIM_RESPONSE_TIMEOUT value specifies the timeout period for the purging of responses in this APACS interface. If the APACS interface is running slowly, increasing this value can result in messages not being sent due to a starvation of communication resources. If the value is decreasing, responses may be purged before they are processed and communications will appear to be intermittent. It has a setting range of 0 to 65535 milliseconds and a default setting of 10000 milliseconds.

NETWORK HeadingThe NETWORK heading contains parameters that are used only on network-based computers.

The TCP_CONNECTION_RETRYS value is the total number of times a network-based APACS interface will attempt to connect to a NIM. The total timeout period is the number of connection retries times the connection timeout value. It has a setting range of 10 to 65535 and a default setting of 10.

The TCP_CONNECTION_TIMEOUT value is the number of seconds that a network-based APACS interface waits for a response to a connection request to a NIM. The total timeout period is the number of connection retries times the connection timeout value. It has a setting range of 30 to 65535 seconds and the default setting of 30 seconds.

05/07/23 4:47 AM 38

The UDP_TIMEOUT value is the number of seconds of inactivity allowed before timing out and automatically closing the connection to the NIM. It and has a range of 1 to 65535 seconds and a default setting of 300 seconds.

The MIN_NIM_NAMES_SEARCH and MAX_NIM_NAMES_SEARCH values are used to limit the number of hosts to which an Ethernet application sends a request to resolve the hsot addresses to and IP address. These values are the first and last NIM names to search. The default MIM_NIM_NAMES_SEARCH value is 1. The default and maximum MAX_NIM_NAMES_SEARCH value is 64. Both values must be at least 1 and the MAX_NIM_NAMES_SEARCH value must be equal to or grather than the MIN_NIM_NAMES_SEARCH value. The optimum values are the number range of current and projected NIMs in the system. For examle, adding the following lines will restrict the search to nim3, nim4, and nim5:

MIN_NIM_NAMES_SEARCH=3MAX_NIM_NAMES_SEARCH=5

MBUS_MNET HeadingThe MBUS_INTERRUPT_LEVEL parameter is the MODULBUS interrupt number. For ICM- or PC/MBI-based applications, this parameter contains the interrupt number for the MODULBUS controller chip. For an ICM, the default is 9, and for a PC/MBI, the default is 10. This parameter is not needed for network-based applications.

05/07/23 4:47 AM 39

Appendix H: APACS Data Type (Table 2)

APACS NAME DESCRIPTION NB BYTES

SINT Short Integer 1

USINT Unsigned Short Integer 1

INT Integer 2

UINT Unsigned Integer 2

DINT Double Integer 4

UDINT Unsigned Double Integer 4

BYTE (1) Bit String of 8 bits 1

WORD Bit String of 16 bits 2

DWORD (1) Bit String of 32 bits 4

TIME Time (duration) 4

REAL Real 4

TIMEOFDAY Time of Day 4

DATE Date 4

DATETIME Date and Time of Day 4

LREAL (1) Long Real 8

STRING String variable (2)

LINT (1) Long Integer 8

ULINT (1) Unsigned Long Integer 8

LWORD (1) Bit String of 64 bits 8

BYTEARRAY (1) Byte Array variable

BOOL Boolean 2

(1) : Not implemented by Moore Products Co.(2) : NULL-terminated; requires single quotes

Three point types exist in the PI 2 system:

Type R is used for real or floating point values (4 bytes),

Type I is used for points whose values are always positive integers (0-32767),

Type D is used for points whose value can only be one of several discrete states (see DA manual, digital state table).

05/07/23 4:47 AM 40

Five point types exist in the PI 3 system (see Data Archive Manual for more details):

Type float16 is used for floating point numbers (2 bytes)

Type float32 is used for single precision floating point numbers (4 bytes)

Type int16 is used for points whose integer values are always positive integers (0-32767)

Type int32 is used for points whose integer values are signed (-2147450880 to 2147483647)

Type digital is used for points whose value can be one of several discrete states (see PI Data Archive Manual, digital state sets).

05/07/23 4:47 AM 41

Appendix I: PI Data Type / DataTag Type

Read / Write PI DATA TYPE

DATATAG TYPE Integer & int16(0-32767)

Digital(1-32000)

Real & float32float (32 bits)

SINT 2 / 3 2 / 3 2 / 3

USINT 2 / 3 2 / 3 2 / 3

INT 2 / 3 2 / 3 2 / 3

UINT 2 / 3 2 / 3 2 / 3

DINT 1 / 1 1 / 1 2 / 3

UDINT 3 / 2 3 / 2 2 / 3

BYTE 2 / 3 2 / 3 2 / 3

WORD 2 / 3 2 / 3 2 / 3

DWORD 3 / 2 3 / 2 2 / 3

TIME X/X X/X X/X

REAL X/X X/X 1 / 1

TIMEOFDAY X/X X/X X/X

DATE X/X X/X X/X

DATETIME X/X X/X X/X

LREAL 3 / 2 3 / 2 3 / 2

STRING X/X X/X X/X

LINT 3 / 2 3 / 2 3 / 2

ULINT 3 / 2 3 / 2 3 / 2

LWORD 3 / 2 3 / 2 3 / 2

BYTEARRAY X/X X/X X/X

BOOL 4 / 3 4 / 3 4 / 3

This table describes a matrix that illustrates the correlation between the PI type data and the APACS DataTag type. Cells that contain a solid symbol generally indicate a one-for-one correspondence for Read/Write access between the PI data type and APACS data type.

05/07/23 4:47 AM 42

1 : This value is the full range and precision method (preferred method).

2: This value is the full range and precision method.

3: This value is the partial range or precision method.

4: This value is 0 for FALSE, 1 for TRUE.

X: Conversion not supported.

05/07/23 4:47 AM 43

Appendix J: APACS-API UtilitiesNote that these utilities are now shipping with the PI APACS Interface distribution.

DTAPISample CLIB Test Application. This program now ships with the PI APACS Interface, and is located in the PIAPACS Interfaces installation path. It is called DTAPI.EXE. It can be run to test communication with the Moore, test for values coming from the Moore, and test the APACS DataTag name for configuration.

NOTE: This utility cannot be run at the same time while the PI APACS Interface is running.

Example APACS Data Tag:DIGESTER.PURGE_WATER.TIC1026_03.PV

Extended Descriptor: DIGESTER.PURGE_WATER

Instrument Tag: TIC1026_03.PV

Example DTAPI Session, using the DOS based version of the Utility:C:\pipc\interfaces\piapacs>dtapi.exe M-NET Data Services Demonstration Program -----------------------------------------

1 .... Initialize NimNamesTable 4 .... Get Next NimName 2 .... Add NimName 5 .... Reset NimName Table 3 .... Delete NimName 6 .... Get APACS Driver Label 7 .... Set Local Resource Name 8 .... START COMMUNICATIONS 0 .... Exit the Program Enter Choice : 1 M-NET Data Services Demonstration Program ----------------------------------------- 1 .... Initialize NimNamesTable 4 .... Get Next NimName 2 .... Add NimName 5 .... Reset NimName Table 3 .... Delete NimName

05/07/23 4:47 AM 44

6 .... Get APACS Driver Label 7 .... Set Local Resource Name 8 .... START COMMUNICATIONS 0 .... Exit the Program Enter Choice : 2 Enter the Nim Name:NIM1 NIM1 has been added to the NimName Table M-NET Data Services Demonstration Program ----------------------------------------- 1 .... Initialize NimNamesTable 4 .... Get Next NimName 2 .... Add NimName 5 .... Reset NimName Table 3 .... Delete NimName 6 .... Get APACS Driver Label 7 .... Set Local Resource Name 8 .... START COMMUNICATIONS 0 .... Exit the Program Enter Choice : 8 M-NET Data Services Demonstration Program ----------------------------------------- 1 .... Single Tag Functions 2 .... Client List Functions 3 .... Server List Functions 4 .... Maintenance Functions 0 .... SHUTDOWN COMMUNICATIONS Enter Choice : 1 M-NET Data Services Demonstration Program ----------------------------------------- 1 .... Create Single Tag 5 .... Enable Single Tag 2 .... Delete Single Tag 6 .... Disable Single Tag 3 .... Read Single Tag 7 .... Access Data Value 4 .... Write Single Tag 8 .... Put Data Value 0 .... Return to Main Menu Enter Choice : 1

05/07/23 4:47 AM 45

Enter Tag:DIGESTER.PURGE_WATER.TIC1026_03.PV Tag = DIGESTER.PURGE_WATER.TIC1026_03.PV : Data

Uninitialized M-NET Data Services Demonstration Program ----------------------------------------- 1 .... Create Single Tag 5 .... Enable Single Tag 2 .... Delete Single Tag 6 .... Disable Single Tag 3 .... Read Single Tag 7 .... Access Data Value 4 .... Write Single Tag 8 .... Put Data Value 0 .... Return to Main Menu Enter Choice : 3 V Tag = DIGESTER.PURGE_WATER.TIC1026_03.PV : 110.032 , E- M-NET Data Services Demonstration Program ----------------------------------------- 1 .... Create Single Tag 5 .... Enable Single Tag 2 .... Delete Single Tag 6 .... Disable Single Tag 3 .... Read Single Tag 7 .... Access Data Value 4 .... Write Single Tag 8 .... Put Data Value 0 .... Return to Main Menu Enter Choice : 0 V DataTag Deleted M-NET Data Services Demonstration Program ----------------------------------------- 1 .... Single Tag Functions 2 .... Client List Functions 3 .... Server List Functions 4 .... Maintenance Functions 0 .... SHUTDOWN COMMUNICATIONS Enter Choice : 0 M-NET Data Services Demonstration Program ----------------------------------------- 1 .... Initialize NimNamesTable 4 .... Get Next NimName 2 .... Add NimName 5 .... Reset NimName Table 3 .... Delete NimName

05/07/23 4:47 AM 46

6 .... Get APACS Driver Label 7 .... Set Local Resource Name 8 .... START COMMUNICATIONS 0 .... Exit the Program Enter Choice : C:\APACS\APIKIT32\SAMPLES\dtapi>

DRAPIDirectory Services API Sample Program. This program now ships with the PI APACS Interface, and is located in the PIAPACS Interfaces installation path. It is called DTAPI.EXE. It can be run to test what Moore Nodes, Racks, and Slots are visible from the PC.

05/07/23 4:47 AM 47

Appendix K: Troubleshooting1. If the interface starts but does not connect to the Moore APACS software, check the

Moore to make sure that it is allowing connections. You must be able to ping the Moore from the Interface platform, and ping the Interface platform from the Moore. If either is not seeing the other, check the hosts file on each to be sure that the other is listed. If you are using a DNS, make sure the computers can see each other.

2. Unable To Locate DLL. Make sure that the DLLs APXAPIWX.DLL is in the path. APXAPIWX.DLL should be installed by the Moore APACS-API installation.

3. The Moore APACS communications showed multiple symptoms: PI APACS interface halted after 2 minutes of operation APACS 4-mation software stalled for a minute or two every 5 to 10 minutes APACS 4-mation downloaded failed to complete successfully

This is a known RNI (remote network interface) problem with the SMC Ethernet card. You need to contact Moore Products, and get the new Intel Ethernet card and software.

4. Check the Connection to the APACS software with the DTAPI test programs explained in Appendix J above. If the DTAPI program is unable to connect to or resolve the Resource name(s), then the Interface will not be able to connect to or resolve the Resource name(s).

5. If you receive the error:Load Failed unknown value in location1 for Tag xxxand have set location 1 to either 0 or 1 for the tags in question, then you are running version 1.0.4 of the Moore APACS Interface, and need to contact OSI immediately for an upgrade. This is a known bug.

6. If you receive an error stating

Unable to locate DLL

The dynamic link library ELOGGR32.dll could not be found in the specified path

Solution is to either copy ELOGGR32.dll to a directory that is in the path, such as \winnt\system32, or to put the directory that the dll is in into the path.

7. If you are having frequent communication problems between the interface and you are using a NIM (not an RNI), check the ethernet tranceiver on the transition board. Make sure that it is solidly mounted.

8. If you receive the error:Error 12 from function ReadTagListUpgrade to PI APACS Interface version 1.2.9.

9. As stated in the APACS API version 4.30 Release notes, when running version 4.30, there are possible problems when running on Ethernet with the Local Logger Utility. There may be communication problems, such as an excessive mount of time-outs, when the Local Logger Utility is running at the same time other APACS communication programs (such as the APACS+ Realtime I/O Server or the API) are executing. It occurs mainly when an older version of a driver for an SMC Ethernet card is being used. If this occurs,

05/07/23 4:47 AM 48

either rename the Local Logger Utility so it will not be automatically executed, move it to a different directory, or exit the utility as soon as it starts executing.MBus local logger utility: llogmbus.exeMNet local logger utility: llogenet.exe

10. Unresolved external symbols when linking APACS API library on VMS platforms. Linking the APACS API library for VMS/Alpha workstations results in the following unresolved external symbol:CXX$TmSyncCndtonStrng14S3ier6g5Linking on VMS/VAX workstations results in the following unresolved external symbols:CXX$PrcssRspns22SystmTmC003se2sCXX$Prodc22SystmTmCmmSrv0i61jicCXX$TmSyncCndtonStrng14S3ier6g5These unresolved external symbol warnings can be safely ignored.

05/07/23 4:47 AM 49

Revision HistoryDate Author Comments

12/15/95 Jyg After Installation

02/27/96 Jyg Installation Procedures as NT services

04/01/96 Jyg Installation Procedures on VAX/Alpha side

21-Jun-96 JFZ minor corrections, ready for distribution

20-Sep-96 JFZ modifed install procedure for VAX and ALPHA platforms

13-Mar-97 HAO added PI 3 specifics, minor corrections

21-May-97 HAO Added NT install info, v1.1.0 APACS string tag

03-Nov-97 HAO Clarified explanation of Instrument tag and Exdesc fields

09-Apr-98 HAO Clarified explanation of startup paramters

22-May-98 HAO Added doc on /sio, DTAPI example, ELOGGR32 error info

02-Jul-98 HAO Added two entries to Troubleshooting section

09-Jul-98 HAO Added to Troubleshooting on unresolved symbols on VMS

25-Aug-98 HAO Added references to RNI

09-Sep-98 HAO Added section on how to do VMS install from distribution diskette; Appendix on Reblock.

10-Sep-98 HAO Added info on VMS Set File Command for reblocking; APACS API Local Logger bug communication bug.

5-Nov-98 HAO Built against APXAPI 4.30 with new calling convention, include /ec and iorates on NT.

17-Nov-98 HAO Now shipping dtapi and drapi with interface.

03-Dec-98 HAO Added Appendix on .exe distributions; modified Appendix on VMS Save Set file conversions.

14-Jan-99 HAO Set convers to 0 to convert input vals from % to EU; attempted to fix TOC again by copying doc to new doc.

18-Feb-99 HAO Added to troubleshooting

08-Mar-99 HAO Added /orq switch

04-Apr-99 HAO Corrected references to installing only the enet Moore API (1.3.0)

21-Jul-99 HAO Added doc on .dbg debug symbols file (1.4.5)

27-Jul-99 HAO Clarified MBI/MNI issues. (1.4.5, doc rev A)

05/07/23 4:47 AM 50

05/07/23 4:47 AM 51