opcarray data plug-in dll for opc da interface to...

OPCArrayData Plug-In DLLfor OPC DA

Interface to the PI System

Version 2.3.11.0Revision A

Copyright © 2006-2009 OSIsoft, Inc.

OSIsoft, Inc. 777 Davis St., Suite 250San Leandro, CA 94577 USA(01) 510-297-5800 (main phone)(01) 510-357-8136 (fax) (01) 510-297-5828 (support phone) http://[email protected], TX Johnson City, TN Longview, TX Mayfield Heights, OHPhiladelphia, PAPhoenix, AZ Savannah, GAYardley, PA

OSIsoft AustraliaPerth, AustraliaAuckland, New Zealand

OSI Software GmbH Altenstadt, Germany

OSIsoft Asia Pte Ltd.Singapore

OSIsoft Canada ULCMontreal, CanadaCalgary, Canada

OSIsoft, Inc. Representative OfficeShanghai, People’s Republic of China

OSIsoft Japan KKTokyo, Japan

OSIsoft Mexico S. De R.L. De C.V.Mexico City, Mexico

OSIsoft do Brasil Sistemas Ltda.Sao Paulo, Brazil

Sales Outlets/DistributorsMiddle East/North AfricaRepublic of South AfricaRussia/Central Asia

South America/CaribbeanSoutheast AsiaSouth Korea Taiwan

www.osisoft.comAll rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, Inc.

OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, PI Datalink, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI ManualLogger, PI ProfileView, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, Inc. All other trademarks or trade names used herein are the property of their respective owners.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph I(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

3

http://www.osisoft.com/

mailto:[email protected]

http://techsupport.osisoft.com/

Table of Contents

Introduction...............................................................................................................................1

Principles of Operation..............................................................................................................3

Types of Error Conditions..................................................................................................3

Frame Error Condition Tags..............................................................................................4

Measurement Error Condition Tags...................................................................................5

Array Index Tags...............................................................................................................6

Array Limit Tags.................................................................................................................7

Configuration.............................................................................................................................9

Examples................................................................................................................................11

Setup.......................................................................................................................................15

Step 1: Configure the PI Server node (i.e. machine) with the appropriate digital states.....15

Step 2: Create the ini configuration file................................................................................15

Step 3: Configure the OPC DA Interface to load the Plug-In and its configuration file........16

Step 4: Verify the PI Tag Configuration is Correct..............................................................16

Step 5: Verify the Plug-In is working properly......................................................................18

Command Line Parameters....................................................................................................21

Troubleshooting......................................................................................................................23

Appendix A: Adding SYSTEM Digital States for PI 3 Servers...............................................25

Appendix B: ABB Nexus Tag Definitions...............................................................................27

Example ABB Nexus Plug-In Configuration File..................................................................28

Appendix C: DaVinci Tag Definitions.....................................................................................29

DaVinci Plug-In Configuration.............................................................................................30

Revision History......................................................................................................................31

OPCArray Data Plug-In DLL for OPC DA Interface to the PI System iii

IntroductionThe OPC Array Data Plug-In DLL for the PI OPC DA Interface is a utility designed to provide processing of array data as it passes from an OPC Server to a PI Server via the PI OPC DA Interface. Typically the PI OPC DA Interface retrieves the data that is available from the OPC Server and stores this data directly in PI. The Array Data Plug-In is designed to apply processing to the array data based on a configuration file where the user can define a set of tags whose values affect the meaning of the array data being stored in PI. By applying status tag information to the array data received from the opcserver then more accurate array data can be stored in PI.

For example a paper machine can have multiple frames with each frame having multiple measurements. The array data comes from the measurement and is stored in PI but the values of the array data are affected by the status of the frame and measurement tags. The configuration file is used to tell the plug-in which tags hold information that affects the array data.

This plug-in supports processing of array data from the following gauging systems:

ABB Nexus

Honeywell Measurex Davinci

or any standard OPC Server which collects array data.

Neither this manual nor the plug-in dll are designed to be used as stand-alone products. They are to be used in conjunction with the PI OPC DA Interface.

OPCArray Data Plug-In DLL for OPC DA Interface to the PI System 1

Principles of OperationThe values received from an opc server for array data are typically read from the OPCServer and stored in PI with no adjustments made to the data itself. For paper machines, the values of the array data can become invalid for a variety of reasons. The frame can be in error, a measurement can be in error or the boundary conditions of the array can be invalid. In normal operation these values are written to PI and viewed by clients. By processing the array data before it is stored in PI then error conditions can be applied to the array data and clients can have a more accurate representation of the status of the system.

The Plug-In uses a configuration file to associate digital state values defined in PI with error condition values defined by the type of paper machine. If a given error condition is true then the Plug-In will update the appropriate array values to reflect that condition. If no error condition exists then the array data will be sent to PI with no modifications.

For the OPC Array Data Plug-In to process error conditions and array data in the correct order, the OPC DA Interface must be properly configured. All the tags for a measurement must belong to the same scan class (i.e. the status tags and the array). Frame tags should belong to a scan class that is updating more often than the measurement tags so that the correct frame information is applied to the correct set of array data. See the OPC DA Interface documentation for how to configure scan classes.

Types of Error ConditionsA frame can go bad for a variety of reasons such as sheetbreak, offline, standardize, and singlepoint. If a frame is offline then the opc server will stop sending data to the OPC DA Interface for the arrays on that frame. When the operator views the system they will only see the last set of good values written to PI. To handle this situation the Plug-In creates the array data with each element of the array containing the digital state value for the error and then sends that data set to PI through the PI OPC DA Interface.

A measurement can also go bad for a variety of reasons such as badprofile, offsheetedge, and outOfRange. Again the plug-in can be used to update the array data so that it more accurately reflects the current state of the measurement. If the measurement is bad then each element of the array for that measurement is set to the digital state representing the error.

Lastly some error conditions only apply to certain elements of the array such as offSheetEdge and outOfRange. If the frame status is good and the measurement status is good then the digital states that apply to specific array elements are evaluated and the data is updated appropriately.


Principles of Operation

The following sections describe each type of error condition tag and its configuration. The processing order of the status tags is also defined.

Frame Error Condition TagsTypically when a frame error occurs the opc server stops sending data to the OPC DA Interface and the array tags contain the last known good value. In this situation it is difficult for the operator to view the array data and determine the problem. The Plug-In is used to write a digital state value to each element of the array that reflects the current error condition.

The configuration file is used to define frame error conditions. The tags defined by the configuration file are the only tags used by the Plug-In for processing of array data. Three pieces of information are needed to define a frame error condition tag:

1. Name of the digital state used to represent the error condition

2. Name of the PI tag that stores the current condition of the frame.

3. Error condition value - either a numeric value or a bitmask definition that when true causes the array data to be set to the specified digital state value.

The digital state can be any state name in the PI Server SYSTEM state table. See appendix A for details on how to add states to the SYSTEM table. A typical set of digital states for a frame or sensor in a gauging system might include the following, Standardize, SheetBreak, SinglePoint, BufferedSinglePoint, Offline, and Maintenance.

The PI Tag Name is the name of a tag that is processed by the OPC DA Interface and is mapped to an OPC Server Item ID. This value will be sent from the opc server to the OPC DA Interface and used to apply error checking to the array data.

The error condition value is compared with the tags current value and when they are equal then the digital state associated with the error is applied to the array data. This error condition value can be a numeric value or a bitmask value. If it is a numeric value then it is a simple check to see if the values are equal. If it is a bitmask value then 2 bitmask definitions are required, the compare value and check value. When ANDed if the condition is true then the array data is updated to reflect the error condition.

There can be as few or as many error condition tags as needed.

An error condition value can be an individual check:

Standardize = {PM5-Standardize} == 1

The error condition value can be a combination of checks:

SinglePoint = {PM5-SinglePoint} == 1 || {PM5-BufferSinglePoint } == 1

The error condition value can be a bitmask definition:

Standardize = {PM1-Scan.RL.FRMSTAT} & 0x00080000 == 0x00080000

4

Example configuration file where PITag name is PM1-Scan.RL.FRMSTAT and the 2 bitmask definions have been specified:

[FRAME1]


SheetBreak = {PM1-Scan.RL.FRMSTAT} & 0x00800000 == 0x00800000

SinglePoint = {PM1-Scan.RL.FRMSTAT} & 0x00100000 == 0x00100000

FrameOffline = {PM1-Scan.RL.FRMSTAT} & 0x00020000 == 0x00000000

In this example, the value of PM1-Scan.RL.FRMSTAT would be ANDed with the first bitmask specified and if it equals the second bitmask definition then the array data will be updated with the specified digital state value.

If the Standardize, SheetBreak and SinglePoint checks passed and the FrameOffline check failed then the array data for this frame would contain the value FrameOffline. NOTE: FrameOffline would occur if the runtime value of PM1-Scan.RL.FRMSTAT ANDed with 0x00020000 equaled 0x00000000.

Another example would be a frame error where more than 1 tag is used to represent a specific state such as PM5-SinglePoint and PM5-BufferSinglePoint. In this case the definitions can be ORed together to create 1 digital state for a variety of tag errors.

[FRAME1]

Standardize = {PM5-Standardize} == 1

SheetBreak = {PM5-SheetBreak} == 1

SinglePoint = {PM5-SinglePoint} == 1 || {PM5-BufferSinglePoint } == 1

FrameOffline = {PM5-OffLine } == 1 || {PM5-OffSheet} == 1 ||

{PM5-Maintenance} == 1

In this example if either PM5-SinglePoint equals 1 or PM5-BufferSinglePoint equals 1 then the array data for that frame would be set to the digital state value of SinglePoint.

Measurement Error Condition TagsMeasurement error condition tags are processed second. Their values apply to the individual array defined for that measurement. The configuration of an error condition tag for a measurement is exactly the same as that for a frame: a digital state followed by the PI Tag name and the error condition value (numeric or bitmask). The only difference in measurement tags and frame tags is that measurement tags apply to one array and frame tags apply to all arrays configured for that frame.

Example measurement definition where PM1-Scan.RL.ASH0001.PV is the PI tag name of the first element of the array.

[FRAME1_MEAS1]



ARRAYTAG = {PM1-Scan.RL.ASH0001.PV}

ARRAYCOUNT = 500

ARRAYBASE = 0

BadProfile = {PM1-Scan.RL.ASH.VALID} == 0

In this case, if PM1-Scan.RL.ASH.VALID contained the value 0 then all 500 array elements PM1-Scan.RL.ASH0001.PV, PM1- PM1 -Scan.RL.ASH0500.PV would be updated with the digital state BadProfile.

In summary, measurement error condition values are processed second, frame errors are processed first. If the frame is not in error and the measurement is not in error then the array tags apply.

Array Index TagsArray index tags define the valid endpoints of the array. In a typical gauging system, a measurement array has a good starting point and a good ending point however the opc server will send the entire array to the OPC DA Interface. Using the plug-in, the array index values that fall outside the valid range can be replaced with a digital state.

Array index tags are configured in the file using the keyword ARRAYINDEX. To specify the lower array index value use the Less Than (<) sign. To specify the upper array index value use the Greater Than (>) sign.

Example1:

[FRAME1_MEAS1]

ARRAYTAG = {PM1-Scan.RL.MOIST0001.PV}

ARRAYCOUNT = 500

ARRAYBASE = 1

BadProfile = {PM1-Scan.RL.MOIST.VALID} == 0

OffSheetEdge = ARRAYINDEX < {PM1-Scan.RL.MOIST.SBOX} || ARRAYINDEX > {PM1-Scan.RL.MOIST.EBOX}

In this example the digital state OffSheetEdge is used to represent both cases - lower values out of range and upper values out of range. All array index values less than the runtime value of of the PI Tag PM1-Scan.RL.MOIST.SBOX will be marked as OffSheetEdge. All array index values greater than the runtime value of the PI tag PM1-Scan.RL.MOIST.EBOX will be marked as OffSheetEdge.

Example2:

[FRAME1_MEAS1]


ARRAYCOUNT = 500

ARRAYBASE = 1


OffSheetEdgeLower = ARRAYINDEX < {PM1-Scan.RL.MOIST.SBOX}

6

OffSheetEdgeUpper = ARRAYINDEX > {PM1-Scan.RL.MOIST.EBOX}

In this example two digital states are used to represent the invalid index values.

Array Limit TagsThe last set of tags used to process array data is the Array Limit Tags. Limit tags are calculated tags based on a set of inputs from the opcserver and a pre-defined equation. The result of the calculation is stored in the limit tag in PI and applied to the array data as it passes from the opcserver to PI.

Array limit tags are defined in the configuration file using the keyword ARRAYVAL. To specify the out of range lower limit value use the Less Than (<) sign. To specify the out of range upper limit value use the Greater Than (>) sign.

The exdesc field is used to define the equation for the limit tag and identifies this tag as a limit tag for the plug-in. All tags used in the equation must be tags whose point source is the OPC DA Interface so that the plug-in will receive their values at runtime. The limit value calculated by the plug-in will be written to PI.

The equation used by the limit tag is a standard PI calculated tag equation. See the PI Server Applications User Guide for details on how to write PI equations which can be specified in the exdesc field of the limit tag.

Format of exdesc field for limit tags used by the plug-in:

CALCTAG=(Equation with opc ‘pi tag names’ enclosed in single quotes)

There are two requirements for the exdesc field: keyword CALCTAG= must be specified first in the exdesc field and secondly the PI Tag Names must be enclosed in single quotes. The PI equation editor can be used to validate the equation during setup to confirm the equation is properly specified. To use the PI tag equation editor you would need to change the point source to ‘C’ (or whatever source is defined for the equation editor), verify the tag is working properly, then reset point source back to the opcint point source so that it can be used by the plug-in.

Example of exdesc field for a limit tag:

PI Tag Name: PM1-MOIST.LLIMIT_CALCTAG

ExDesc field for PI Tag PM1-MOIST.LLIMIT_CALCTAG:

CALCTAG= if 'PM1-MOIST.FRACTLIMITS' then 'PM1-MOIST.TAR' - 'PM1-MOIST.LOWLIMIT' else 'PM1-MOIST.TAR' - ('PM1-MOIST.TAR' * 'PM1-MOIST.LOWLIMIT')

Instrument Tag Field: blank – this tag does not point to an opcserver tag, it is a calculated tag based on the equation defined in the exdesc field. The PI Tags used by the equation have an instrument tag field set to a tag on the opcserver.

Configuration file example of defining limit tags:

[FRAME1_MEAS1]




ARRAYCOUNT = 500

ARRAYBASE = 1



OutOfRangeLower = ARRAYVAL < {PM1-MOIST.LLIMIT_CALCTAG}

OutOfRangeUpper = ARRAYVAL > {PM1-MOIST.ULIMIT_ CALCTAG}

In this example the PI Tag ‘PM1-MOIST.ULIMIT_ CALCTAG’ would be configured with exdesc set to CALCTAG=Equation and ‘PM1- MOIST.LLIMIT_ CALCTAG’ would also be configured with a CALCTAG= Equation value in the exdesc field. At runtime the plug-in would evaluate the equation, apply it to the array data values and store the result of the calculation in the PI Tags: PM1-MOIST.ULIMIT_ CALCTAG and PM1-MOIST.LLIMIT_ CALCTAG.

Similar to the ARRAYINDEX tags the ARRAYVAL tags can be ORed together as well.

[FRAME1_MEAS1]


ARRAYCOUNT = 500

ARRAYBASE = 1



OutOfRange = ARRAYVAL < {PM1-MOIST.LLIMIT_CALCTAG} || ARRAYVAL > {PM1-MOIST.ULIMIT_CALCTAG}

Point source of the limit tag and all tags used by the equation must be the OPC DA Interface. The exception and compression properties for the tags PM1-MOIST.ULIMIT_ CALCTAG and PM1-MOIST.LLIMIT_ CALCTAG should be set to zero.

After the limit values have been calculated by the Plug-In then they remain in effect until a tag used by the equation is updated on the opcserver. Every update of a tag used by the exdesc equation will cause the equation to be re-evaluated and if the new value is different than the previous value then it will be stored in PI. If for some reason a new value is received and the plug-in cannot properly evaluate the new set of limits then a message will be logged to the pipc log file and the existing limit values will remain in effect until the equation can be properly evaluated. Once the equation has been properly executed then a message will be logged to the pipc log.

NOTE: All tags used in the configuration file must have a pointsource of the OPC DA Interface including tags used by the equation defined in the exdesc field.

8

ConfigurationThe configuration file is used to configure status tags that apply to the processing of the array data as well as the array definition. Frame status tags, measurement status tags and array status tags (array index tags and array limit value tags) are defined in the .ini config file.

Format of the configuration file:

There are 2 keywords for specifying the sections in the configuration file:

1. [FRAMEx]

where x is the number of the frame starting at 1.

2. [FRAMEx_MEASn]

where x is the number of the frame starting at 1, and

n is the number of the measurement defined for that frame

Three pieces of information are required for status tags: a SYSTEM digital state name, a PI tag name and an expected error condition value. A digital state value must exist on the PI Server prior to running the interface. The PI Tag Name must be enclosed in curly braces ‘{}’. The error condition value must follow the ‘==’ sign and can either be a numeric value or a bitmask definition. If it contains a bitmask definition then it is configured using the ‘&’ sign and therefore requires both the bitmask definition and the error condition value.

There are 4 valid delimiters for specifying status tags:

1. curly braces ‘{}’: used to denote PI Tag Names.

2. ampersand ‘&’: used to denote bitmask definition for an error condition tag.

3. OR operator ‘||’: used to OR together PI Tag, Err condition value pairs to create a series of checks that represent the same digital state.

4. double equals operator ‘==’ is used to signify the error condition value.

Examples of status tag definitions (specified within the [FRAMEx] and [FRAMEx_MEASx] sections:

a. DigitalState = { PITagName } == ErrConditionVal

b. DigitalState = { PITagName } & 0x0n0n0n0n == 0x0n0n0n0n

where 0x0n0n0n0n is any bitmask definition.

c. DigitalState = {PITagName} == ErrConditionVal ||

{PITagName} == ErrConditionVal

where‘||” is used to combine definitions

There are 5 keywords used in a measurement section:


1. ARRAYTAG - PI tag name used to store the first element of the array

2. ARRAYCOUNT - Total number of array elements

3. ARRAYBASE - how the array is stored on the OPC Server:

ZERO based versus ONE based.

An array is mapped to PI starting at index 1.

4. ARRAYINDEX - Used to configure the valid index values of the array.

5. ARRAYVAL - Used to configure the valid data values within the array.

NOTE: When the PI OPC DA Interface is started, the Plug-In processes the configuration file. Any changes made to this file after initial startup will require a restart of the PI OPC DA Interface.


ExamplesValid:

[FRAME1]





Invalid:

[FRAME1]

Standardize = {PM1-Scan.RL.FRMSTAT} & 0x00080000 == 1

FrameOffline = {PM1-Scan.RL.FRMSTAT} & 0x00020000 == 0

NOTE: If the tag is a bitmask definition then the expected error condition value is also a bitmask definition.

Valid:

[FRAME1]



[FRAME2]



Invalid:

[FRAME1]



[FRAME2]



NOTE: A PI Tag can be used multiple times WITHIN a single frame definition however it cannot be used ACROSS frame definitions. The same is true for measurements. A Measurement tag can be used multiple times WITHIN a single measurement definition however it cannot be used ACROSS measurement definitions.

Valid:

[FRAME1_MEAS1]

ARRAYTAG = {PI Tag Name}

ARRAYCOUNT = 500


ARRAYBASE = 1

DigitalState = {PITagName} == ErrConditionVal

DigitalState = ARRAYINDEX < {PITagName} || ARRAYINDEX > {PITagName}

DigitalState = ARRAYVAL < {PITagName}

Invalid:

[FRAME1_MEAS1]

ARRAYCOUNT = 500

ARRAYBASE = 1

DigitalState = {PITagName} == ErrConditionVal

DigitalState = ARRAYINDEX < {PITagName} || ARRAYINDEX > {PITagName}

DigitalState = ARRAYVAL < {PITagName}

NOTE: name of the array must be specified otherwise there is no array data to process for the measurement.

Example of a frame definition with 2 error condition tags:

[FRAME1]

SheetBreak = {PM1-FramStat} & 0x00800000 == 0x00800000

FrameOffline = {PM1-FramStat} & 0x00080000 == 0x00080000

Example of a measurement definition with 1 error condition tag:

[FRAME1_MEAS1]


ARRAYCOUNT = 500

ARRAYBASE = 0

BadProfile = {PM1-Scan.RL.Validity} == 0 || { PM1-Scan.RL.Validity_Tag2 } == 0

Example of a measurement definition with an array index tag:

[FRAME1_MEAS1]


ARRAYCOUNT = 500

ARRAYBASE = 0



Example of a measurement definition with an array value tag (or limit tag):

[FRAME1_MEAS1]


ARRAYCOUNT = 500

ARRAYBASE = 0


OutOfRangeLower = ARRAYVAL < {PM1-Scan.RL.MOIST.LLIMIT_CALCTAG}

OutOfRangeUpper = ARRAYVAL > {PM1-Scan.RL.MOIST.ULIMIT_CALCTAG}


SetupBelow is a list of steps on how to configure the system to use the plug-in. This is a brief overview and details about each step can be found in the Principles of Operation and Configuration sections.

Step 1: Configure the PI Server node (i.e. machine) with the appropriate digital states.

See appendix A for more detailed instructions on how to configure digital states.

Copy the following list of files to your PI\adm directory on the PI Server node:

AddOPCPlugInStates.bat

NewStates.bat

AddStates.exe

MakeDumpSet.exe

Edit the file AddOPCPlugInStates.bat and add the digital states required for your system.

Before you edit the file it should look something like the following:

call newstates system BadProfile OffSheetEdge FrameOffline SinglePoint

Example - add the digital state OutOfRange and remove the digital state BadProfile.

call newstates system OffSheetEdge FrameOffline SinglePoint Standardize SheetBreak OutOfRange

Go to a DOS command prompt and execute the bat file:

C:\PI\adm\> AddOPCPlugInStates.bat

The required digital states should now be available on the PI Server node.

Step 2: Create the ini configuration file.

See the Principles of Operation and Configuration sections for more detailed information on how to create the ini configuration file.

[FRAME1]






[FRAME1_MEAS1]

ARRAYTAG = {PM1-Scan.RL.FRAME1.MOIST0001.PV}

ARRAYCOUNT = 380

ARRAYBASE = 0

BadProfile = {PM1-Scan.RL.FRAME1.MOIST.VALID} == 0

OffSheetEdge = ARRAYINDEX < { PM1-Scan.RL.FRAME1.MOIST.SBOX} || ARRAYINDEX > { PM1-Scan.RL.FRAME1.MOIST.EBOX}

OutOfRange = ARRAYVAL < {PM1-Scan.RL.FRAME1.MOIST.LowerLIMIT} || ARRAYVAL > { PM1-Scan.RL.FRAME1.MOIST.UpperLIMIT}

Step 3: Configure the OPC DA Interface to load the Plug-In and its configuration file.

The OPCArrayDataPlugIn is required to run on the same node (i.e. machine) as the OPC DA Interface. After a normal installation of the OPC DA Interface then the Plug-In directory should look like the following:

PIPC\Interfaces\OpcInt\Plug-Ins

The OPCArrayDataPlugIn.dll file should be in this directory (no additional steps for registration are required).

Add two command line options to the OPC DA Interface bat file to load the plug-in and the plug-ins configuration file.

The /dll option loads the plug-in and the /dllconfig loads the plug-ins configuration file.

Example:

/dll=”C:\Program Files\PIPC\Interfaces\OpcInt\Plug-Ins\OPCArrayDataPlugIn.dll”

/dllconfig=”C:\Program Files\PIPC\Interfaces\OpcInt\Plug-Ins\PlugInConfig.ini”

NOTE: PlugInConfig.ini is the file created above in step 2 and is written by the user and is specific for their system.

Step 4: Verify the PI Tag Configuration is Correct.Frame tags must be configured in the same scan class and must have an update rate faster than the measurement tags. All measurement tags both array and status tags must be configured in the same scan. This allows the plug-in to receive the values of the tags in the correct order so that the runtime processing of the data is correct. This configuration eliminates timing issues that could be associated with processing the data.

Verify the frame and measurement tags are configured properly.

PI Tag Name: UserInt1 Loc4

PM1-Scan.RL.FRMSTAT.Standardize 0 2

PM1-Scan.RL.FRMSTAT.Sheetbreak 0 2

PM2-Scan.RL.MOIST.SBOX 0 3

PM2-Scan.RL. MOIST.EBOX 0 3


PM2-Scan.RL.MOIST0001 1 3

...

PM2-Scan.RL.MOIST0600 600 3

PM2-Scan.RL.MOIST.VALID 0 3

PM2-Scan.RL.BWT.SBOX 0 4

PM2-Scan.RL.BWT.EBOX 0 4

PM2-Scan.RL.BWT0001 1 4

...

PM2-Scan.RL.BWT0400 400 4

PM2-Scan.RL.BWT.SBOX 0 4

PM2-Scan.RL.BWT.EBOX 0 4

By setting Loc4=2 for the frame tags and setting scan class 2 faster than scan class 3 and 4 then the frame tags can be processed first. By setting Loc4=3 for all measurement tags for moisture then the values that affect the processing of the moisture array and the array itself will be received by the Plug-In as one set of new data. The same is true for the base weight tags. They are all defined in scan class 4 therefore they will be processed correctly.

Verify the limit tags are configured properly.

PI Configuration fields and values:

tag PM1-Scan.RL.MOIST.LLimit_CALCTAG

compressing 0

instrumenttag <not used by plug-in for limit tags>

location1 must match array configuration for which limit value applies

location2 0

location3 must match array configuration for which the limit value applies

location4 must match scan class of array for which the limit value applies

location5 0

pointsource OPC DA Interface point source

exdesc CALCTAG=if 'PM1-Scan.RL.MOIST.VALID.FractLimits' then 'PM1-Scan.RL.MOIST.AVG' - 'PM1-Scan.RL.MOIST.VALID.LowLimit' else 'PM1-Scan.RL.MOIST.AVG' - ('PM1-Scan.RL.MOIST.AVG' * 'PM1-Scan.RL.MOIST.VALID.LowLimit')

NOTE: all tags used in the exdesc field must also be configured as tags for the OPC DA Interface and should be in the same scan class.


Setup

PITag Name: pointsource UserInt1 Loc4

PM1-Scan.RL.MOIST.VALID.FractLimits O 0 2

PM1-Scan.RL.MOIST.AVG O 0 2

PM1-Scan.RL.MOIST.VALID.LowLimit O 0 2

The value of PM1-Scan.RL.MOIST.LLimit_C will be written to PI every time the value of PM1-Scan.RL.MOIST.VALID.FractLimits, PM1-Scan.RL.MOIST.VALID.AVG, PM1-Scan.RL.MOIST.VALID.LowL, or PM1-Scan.RL.MOIST.VALID.HighL changes.

The exdesc field of a limit tag used by the Plug-In accepts any valid value that can be calculated by the PI Performance equation service. A tag whose point source is C is a PI Calculated Tag and will be evaluated by the PI Performance Equation Service. The limit tag point source is the OPC DA Interface point source. The limit tags used by the plug-in follow the same format as PI calculated tags used by the PI Performance equation editor.

See the PI Server Applications User Guide and the Performance Equation Editor documentation for more information on how to write the exdesc field of a limit tag used by the Plug-In. The PIServerApplicationsUserGuide defines the syntax used for PI Calculated tags and the Plug-In uses the same syntax.

Step 5: Verify the Plug-In is working properly.There should be statements in the pipc log indicating that the Plug-In and the Plug-In Configuration file have been properly loaded.

If the Plug-In encounters an error while processing the configuration file then an error message will be logged and the OPC DA Interface will shutdown.

If the Plug-In successfully parses the configuration file then debug levels can be used to verify the configuration is working properly. See the troubleshooting section for a list of valid debug levels and what information applies to each setting.

At startup you should see the current value of each OPC DA Interface tag written to the PI Server.

At runtime you should see the array data values being stored in PI. When an error condition evaluates to true then you should see the digital state associated with that error condition used as the value for the array elements where applicable.

Order or operation processing for tags:

#1. If the error condition specified for the frame is true then all array elements for that frame will be set to the digital state of the frame error

#2. If there are no frame errors then measurement tags are processed. If the error condition specified for the measurement is true then the individual array for that measurement will be set to the digital state of the measurement error.

#3. If there are no frame errors and no measurement errors then the Plug-In will look for ARRAYINDEX definitions. If they are in use and have been specified in the configuration file then their values will be applied now. If any array index element falls outside the valid range then that individual array element will be set to the digital state of the array index error.

#4. Once all frame tags, measurement tags and array index tags have been processed then the limit value tags are processed. If they have been specified in the configuration

18

file then their values will be applied now. If any array data value falls outside the valid range then that individual array element will be set to the digital state of the array value error.

NOTE: If a limit tag contains a calculation in the exdesc field then every time the plug-in evaluates the value of the limit tag then the result of the calculation will be stored in PI.

At shutdown you should see the normal expected behavior from opcint based on the opcint configuration.


Command Line ParametersThe DLL supports a few command-line parameters that are specific to this DLL. These parameters are different from interface specific parameters. When the DLL is loaded by the interface, the interface passes all command-line parameters. Some of the parameters that the interface uses are also used by the DLL. For example, /ID and /HOST.

DLL specific parameters:

Parameter Description

/DLLConfig=<filespec>

Required

Configuration file. This file defines how the interface recognizes data tags and the status tags which are applied to them. See the Configuration section for more details.

/DLLDB=# (Default: 0)Optional

Debug level (6-10). See Troubleshooting section for more details.


TroubleshootingIn addition to the /dll and /dllconfig options for opcint you can use /dlldb for your testing. /dlldb will write to both the output window and the pipc log file. If /dlldb=10 then you will get a print statement for every function that is called in the plug-in. Level 10 is the highest level and is a dump of everything and can fill up the log file. Level 1 is the simplest level and writes status tag values and limit tag values.

/dlldb=6: 6 is the runtime level used for inputs. Data flows from the opc server to the OPC DA Interface then to the plug-in as inputs. This logs the inputs received by the plug-in.

*This is typically the most useful setting to log user inputs, checks and error and current status of the tags. Debug levels higher than 6 can fill the log file with lots of data.

/dlldb=7: 7 will log all configuration information. If you are having trouble getting the configuration correct then set /dlldb=7 and you will get all file parsing errors and all file validation errors.

/dlldb=8: 8 will log all loading issues at startup. When the OPC DA Interface starts it passes the tags to the plug-in and they are loaded and ready to receive runtime inputs/outputs. By setting /dlldb=8 then you can verify all tags in the configuration file have been properly loaded.

/dlldb=9: 9 will log all remove tag calls which are unloaded from the plug-in. There are 2 ways for a tag to be unloaded by the plug-in: edits and deletes. If a PI Tag is edited then remove will be called follow by a call to load the tag. If a PI Tag is deleted then remove will be called.

/dlldb=10: 10 will log everything - configuration errors, runtime errors, load and remove errors and any other general information. Level 10 can fill up the log file quickly and should only be used during setup to get the system up and running.


Appendix A: Adding SYSTEM Digital States for PI 3 Servers

The plug-in requires digital states to be added to the PI’s SYSTEM digital state table. PI 3 allows automatic addition of states to the system table using an application called AddOPCPlugInStates, which should appear on your interface system after installation. The application consists of four files:AddOPCPlugInStates.bat

NewStates.bat

AddStates.exe

MakeDumpSet.exe

All of these files must be moved to the PI\adm directory of your PI 3 archive machine. They will not function unless moved to the PI archive machine, in the PI\adm directory.

There are 2 steps for adding the digital states to PI and 2 steps for verifying the states were properly added to the PI Server SYSTEM digital state table.

1.) If you are running a PI 3 Server then do the following. Open the PI System Management Tools application and select the item Points\Digital State Editor\SYSTEM. This is where the digital state set for the SYSTEM table is located. Go to the end of the table and notice the last entry and its values. Once you have properly configured the required digital states then you can come back to this table to confirm the addition was successful.

2.) Go to you PI\Adm folder in an Explorer window. Select the file AddOPCPlugInStates.bat and right click the file. Select the Edit menu item and the file should open in an editable format. The text should appear like the example below. Edit this file to create the digital states required for your system.

call newstates system BadProfile, OffSheetEdge, SheetBreak, Standardize, FrameOffline, SinglePoint

This is an example file for how to add new digital states to a PI 3 Server. The function newstates is called with the first parameter being the digital state table. For the PI Plug-In application you are required to add the digital states to the SYSTEM table. Following the keyword system is a list of the digital states that are needed in the PI Server for the PI Plug-In.

These states can be any name that does not already exist in the PI 3 Server. If the state already exists then it will be used. If it does not exist then the new state will be added at the end of the SYSTEM digital state table.

In this example the new digital states created by this file are BadProfile, OffSheetEdge, SheetBreak, Standardize, FrameOffline, and SinglePoint.

3.) Execute the bat file from a DOS command prompt. Log in as an administrator, go to Start\Run and type in cmd as the name of the Run application. This will open a DOS command line window. At the DOS prompt change directories from the currently directory to the PI\Adm directory.

C:\> cd C:\PI\adm


Make sure the PI Server is running and Invoke the AddOPCPlugInStates. bat application. C:\PI\adm\> AddOPCPlugInStates.batThe required states should be added to your PI System Digital State table.

4.) To confirm the states were properly added to the PI SYSTEM digital state table go back to the SMT Tools application and select Points\Digital State Editor\SYSTEM. Go to the end of the table and you should see the new states in the PI SYSTEM table. The value of the new digital state is dependent on the number of existing states in the SYSTEM table prior to running the AddOPCPlugInStates.bat file.


Appendix B: ABB Nexus Tag DefinitionsExample of a status tag defined on the opcserver for a Frame:

PMn.ac450b.FRAMEn.DYD.FRAMESTATUS

Example of a status tag defined on the opcserver for a measurement:

PMn.ac450b.FRAMEn.MEASUREMENTn.scnprof.ProfileValidity

Example of a measurement array defined on the opcserver:

PMn.ac450b.FRAMEn.(measurement).(SCNPROF/COMPROF).(ProfileArray)

Example of an array index tag defined on the opcserver:

PMn.ac450b.FRAMEn.MEASUREMENTn.scnprof.StartBox

PMn.ac450b.FRAMEn.MEASUREMENTn.scnprof.EndBox

Tags used by the limit calculation are tags whose point source is the opc server:

PM1-Scan.RL.Measurement.FractLimits

PM1-Scan.RL. Measurement.SetPoint

The limit tag is a PI tag whose exdesc uses the tags above to create a calculated value and then stores the result of the calculation in PI.


Example ABB Nexus Plug-In Configuration File[FRAME1]





[FRAME1_MEAS1]


ARRAYCOUNT = 500

ARRAYBASE = 0



OutOfRange = ARRAYVAL < {PM1-Scan.RL.LLIMIT_C} || ARRAYVAL > {PM1-Scan.RL.ULIMIT_C}

[FRAME1_MEAS2]

ARRAYTAG = {PM1-Scan.RL.BWT0001.PV}

ARRAYCOUNT =400

ARRAYBASE = 0

BadProfile = {PM1-Scan.RL. BWT.VALID} == 0

OffSheetEdge = ARRAYINDEX < {PM1-Scan.RL.BWT.SBOX} || ARRAYINDEX > {PM1-Scan.RL.BWT.EBOX}

OutOfRange = ARRAYVAL < {PM1-Scan.RL.BWT.LLIMIT_C} || ARRAYVAL > {PM1-Scan.RL.BWT.ULIMIT_C}


Appendix C: DaVinci Tag DefinitionsExample of a status tag defined on the opcserver for a Scanner (i.e. a Frame):

/scanner<n>/status/OffLine

/scanner<n>/status/OffSheet

/scanner<n>/status/Maintenance

Example of a status tag defined on the opcserver for a measurement:

/scanner<n>/measurements/<msmt name>/validity/valid status

Example of a measurement array defined on the opcserver:

/scanner<n>/measurements/<msmt name>/last scan/now/array

Example of a array index tags defined on the opcserver:

/Scanner 1/Measurements/<msmt name>/last scan/now /Minimum valid index

/Scanner 1/Measurements/<msmt name>/last scan/now /Maximum valid index

Tags used by the limit calculation are tags whose point source is the opc server

PM1-Scan.RL. <msmt name>.FractLimits

PM1-Scan.RL. <msmt name>.SetPoint

The limit tag is a PI tag whose exdesc uses the tags above to create a calculated value and then stores the result of the calculation in PI.


DaVinci Plug-In Configuration[FRAME1]

Standardize = {PM2T-Standardize} == 1

SheetBreak = {PM2T-SheetBreak} == 1

SinglePoint = {PM2T-SinglePoint} == 1 || {PM2T-BufferSinglePoint } == 1

FrameOffline = {PM2T-OffLine } == 1 || {PM2T-Maintenance} == 1

[FRAME1_MEAS1]

ARRAYTAG = {PM2T-Scan.RL.BWT0001.PV}

ARRAYCOUNT = 372

ARRAYBASE = 1

BadProfile = {PM2T-Scan.RL.BWT.VALID} == 1

OffSheetEdge = ARRAYINDEX < {PM2T-Scan.RL.BWT.SBOX} || ARRAYINDEX > {PM2T-Scan.RL.BWT.EBOX}

OutOfRange = ARRAYVAL < {PM2T-Scan.RL.BWT.LowerLimit} || ARRAYVAL > {PM2T-Scan.RL.BWT.UpperLimit}

[FRAME1_MEAS2]

ARRAYTAG = {PM2T-Scan.RL.MOIST0001.PV}

ARRAYCOUNT = 372

ARRAYBASE = 1

BadProfile = {PM2T-Scan.RL.MOIST.VALID} == 1

OffSheetEdge = ARRAYINDEX < {PM2T-Scan.RL.MOIST.SBOX} || ARRAYINDEX > {PM2T-Scan.RL.MOIST.EBOX}

OutOfRangeLower = ARRAYVAL < {PM2T-Scan.RL.MOIST.LowerLimit}

OutOfRangeUpper = ARRAYVAL > {PM2T-Scan.RL.MOIST.UpperLimit}


Revision HistoryDate Editor Comments

05-Jan-06 PSluder Added documentation for the existing functionality of the OSI PI Plug-In plus documentation for the new features - limit tags in PI and a configuration file

17-May-06

PSluder Rewrite of manual - simplify the text and add better examples.Added a Setup section that summarizes all the steps needed to configure the system. Added more detail on how to configure a limit tag.

29-Jan-07 PSluder Update manual with new limit tag design to support uniint level failover.

22-Feb-07 MKelly Version 2.3.4.0, Rev A: Updated formatting to current skeleton standard, fixed headers, footers, section break, rebuilt TOC.

23-Feb-07 Janelle Version 2.3.4.0, Rev B: fixed formatting for introduction, updated headers and footers.

16-Feb-09 PHawkins Updated manual for easier readability and better examples.

1-Jun-2009

LCraven Updated version, dlldb replaces dlldebug

4-Jun-2009

MKelly Version 2.3.11.0 Revision A, Fixed headers and footers, updated title and contact pages.


opcarray data plug-in dll for opc da interface to...

Documents