PI Interface for Measurex MXO. Version x

Transcription

1 PI Interface for Measurex MXO Version x

2 OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA USA Tel: (01) Fax: (01) Web: OSIsoft Australia Perth, Australia OSIsoft Europe GmbH Frankfurt, Germany OSIsoft Asia Pte Ltd. Singapore OSIsoft Canada ULC Montreal & Calgary, Canada OSIsoft, LLC Representative Office Shanghai, People s Republic of China OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil OSIsoft France EURL Paris, France PI Interface for Measurex MXO Copyright: OSIsoft, LLC. All 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, LLC. OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Coresight, PI Data Services, PI Event Frames, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners. U.S. GOVERNMENT RIGHTS Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS , DFARS , FAR , FAR , as applicable. OSIsoft, LLC. Published: 12/2014

3 Table of Contents Chapter 1. Introduction... 1 Supported Measurex Systems... 1 MX Server to AM(s)... 1 HMX Application Manager (AM)... 1 HMX DaVinci... 1 ODX DaVinci... 2 MX Server to Data Freeway Nodes and Vision 2000 Systems... 2 Reference Manuals... 3 Supported Operating Systems... 3 Supported Features... 3 Connection Options... 5 Diagram of Hardware Connection... 5 Chapter 2. Principles of Operation... 7 Chapter 3. Installation Checklist... 9 Data Collection Steps... 9 Interface Diagnostics Chapter 4. Interface Installation Naming Conventions and Requirements Interface Directories PIHOME Directory Tree Interface Installation Directory Interface Installation Procedure PI Trust for Interface Authentication Installing Interface as a Windows Service Installing Interface Service with PI Interface Configuration Utility Service Configuration Installing Interface Service Manually Chapter 5. Digital States Chapter 6. PointSource Chapter 7. PI Point Configuration Point Attributes Tag PointSource PointType Location Location Location Location PI Interface for Measurex MXO iii

4 Table of Contents Location InstrumentTag ExDesc Scan Shutdown DataSecurity PtSecurity Output Points Trigger Method 1 (Recommended) Trigger Method Configuration Examples Profiles -- Unsolicited Event Input Single Variable -- Unsolicited Time Input Single Variable -- Solicited Time Input Profile Status Handling Chapter 8. Startup Command File Configuring the Interface with PI ICU Command-line Parameters Peer-to-peer Connections to Single HMX AM Node Peer-to-peer Connections through HMX Server Peer-to-many Connections through HMX Server Sample MXOpen.bat File Chapter 9. Interface Node Clock Chapter 10. Security Windows Authentication Authorization Chapter 11. Starting / Stopping the Interface Starting Interface as a Service Stopping Interface Running as a Service Chapter 12. Buffering Which Buffering Application to Use How Buffering Works Buffering and PI Data Archive Security Enabling Buffering on an Interface Node with the ICU Choose Buffer Type Buffering Settings Buffered Servers Installing Buffering as a Service Chapter 13. Interface Diagnostics Configuration Scan Class Performance Points Performance Counters Points Interface Health Monitoring Points I/O Rate Point iv

5 Interface Status Point Appendix A. Error and Informational Messages Message Logs Error Messages Error Modes Undefined Symbols Connections Incomplete Messages Loss of Data From One of Several Nodes Missing HMX Events Fatal Error Messages Link Status Messages Tag Configuration Messages System Errors and PI Errors Appendix B. PI SDK Options Appendix C. HMX DaVinci Issues Appendix D. Terminology Interface Specific Terms General Terms Appendix E. Technical Support and Resources Appendix F. Revision History PI Interface for Measurex MXO v

6

7 Chapter 1. Introduction The PI Interface for Measurex MXO connects the PI Data Archive to HMX LAN Devices that support HMX s ODX or MXOpen Server Protocols. The PI MXOpen interface allows PI Data Archives to access most data in nodes on HMX LANs. It also supports PI Data Archive outputs, which can be used to send data to the HMX nodes. Note: Historically, this interface has been referred to as: the Measurex HMX/ODX/MXOpen Interface to the PI System as well as the PI Honeywell MXOpen DaVinci Interface where HMX refers to Honeywell / Measurex. Supported Measurex Systems The supported system configurations are listed in the following sections: MX Server to AM(s) The PI MXOpen interface to the MX Server connection uses the ODX Protocol. The MX Server can then communicate with multiple AM s. HMX Application Manager (AM) AM release 1.0, 2.0 or higher, also referenced as MXOpen release 94 This is a Peer-to-peer connection in which the PI System communicates with only one HMX AM node per PI MXOpen interface. On some of the older units, memory mapping may be a problem for large amounts of profile tag retrieval. Measurex can possibly supply the customer a patch to solve the memory addressing of large amounts of profile data. HMX DaVinci The HMX gauging system controls operating on the Windows NT platform may or may not include AM s. In some cases, the AM logic is programmed to run on a Windows NT system that connects directly with the gauge. There are two scaled-down versions of DaVinci, HMX Proline and Micro CD Open. Proline communicates directly with the gauge and CD Open communicates via CD logic to foreign gauging systems (such as ABB s AccuRay). In both PI Interface for Measurex MXO 1

8 Introduction cases, the ODX protocol is available (MX Part Number: ODX Communication Software). Note: OPC is also supported by the DaVinci product line, but may require additional software from Honeywell. ODX DaVinci The ODX implementation on DaVinci is slightly different from the HMX implementation. The DaVinci system must be configured to handle event logic for the PI MXOpen interface. See section HMX DaVinci Issues. MX Server to Data Freeway Nodes and Vision 2000 Systems The MX Server communicates with its Data Freeway nodes through HMX's proprietary Data Freeway hardware and SCO Unix operating system. The MX Server converts the Data Freeway protocol to the MXOpen protocol in order to communicate with PI. Note: The value of [PIHOME] variable for the 32-bit interface will depend on whether the interface is being installed on a 32-bit operating system (C:\Program Files\PIPC) or a 64-bit operating system (C:\Program Files (x86)\pipc). The value of [PIHOME64] variable for a 64-bit interface will be C:\Program Files\PIPC on the 64-bit operating system. In this documentation [PIHOME] will be used to represent the value for either [PIHOME] or [PIHOME64]. The value of [PIHOME] is the directory which is the common location for PI client applications. Note: This interface has been built against a UniInt version ( and later) which now writes all its messages to the local PI Message log. Please see the document UniInt Interface Message Logging.docx in the %PIHOME%\Interfaces\UniInt directory for more details on how to access these messages. Note: OSIsoft is revising product documentation and other literature to reflect the evolution of the PI Server from a single server to a multi-server architecture. Specifically, the original historian core of the PI Server is now referred to as the PI Data Archive. 2 Originally, the PI Server was a single server that contained the PI Data Archive and other subsystems. To add features and improve scalability, the PI Server has evolved from a single server to multiple servers. While the PI Data Archive remains a core server of the PI Server product, the product name PI Server now refers to much more than the PI Data Archive. OSIsoft documentation, including this user manual, is changing to use PI Server in this broader sense and PI Data Archive to refer to the historian core.

9 Reference Manuals OSIsoft PI Data Archive manuals PI API Installation Instructions manual (%PIHOME%\bin\API_install.doc) PI Universal Interface (UniInt) User Guide (%PIHOME%\Interfaces\UniInt\UniInt Interface User Manual.pdf) UniInt Interface Message Logging for UniInt x and later Interfaces (%PIHOME%\Interfaces\UniInt\UniInt Interface Message Logging.pdf) PI Interface Configuration Utility user guide (%PIHOME%\ICU\PI Interface Configuration Utility.pdf) Supported Operating Systems Platforms 32-bit application 64-bit application Windows 2003 Server Windows Vista 32-bit OS Yes No 64-bit OS Yes No 32-bit OS Yes No 64-bit OS Yes (Emulation Mode) No Windows bit OS Yes No Windows 2008 R2 64-bit OS Yes (Emulation Mode) No Windows 7 32-bit OS Yes No 64-bit OS Yes (Emulation Mode) No Windows 8 and bit OS Yes No 64-bit OS Yes (Emulation Mode) No Windows bit OS Yes (Emulation Mode) No The interface is designed to run on the above mentioned Microsoft Windows operating systems and their associated service packs. Please contact OSIsoft Technical Support for more information. Security Note: We recommend installing all available updates from Windows Update service. We recommend the newest versions of Windows for latest security features. Supported Features Feature Support Interface Part Number PI-IN-MX-MXO-NTI Auto Creates PI Points No Point Builder Utility No ICU Control Yes PI Interface for Measurex MXO 3

10 Introduction Feature Support PI Point Types PI 3: Float16 / Float 32 / Int16 / Int32 / Digital / String PI 2: Float / Integer / Digital Sub-second Timestamps Sub-second Scan Classes Automatically Incorporates PI Point Attribute Changes Exception Reporting Inputs to PI Data Archive Outputs to data source Supports Questionable Bit Supports Multi-character PointSource Maximum Point Count No No Yes Yes Scan-based Yes No No * Uses PI SDK No PINet String Support Limited by capacity of HMX Node No * Source of Timestamps PI Data Archive History Recovery * UniInt-based * Disconnected Startup * SetDeviceStatus No Yes No No * Failover No * Vendor Software Required on Interface Node / PINet Node Vendor Software Required on Data Source Device Vendor Hardware Required Additional PI Software Included with interface Device Point Types Serial-Based interface No No No No REAL, DINT, UINT64, BOOL, INT No * See paragraphs below for further explanation. Uses PI SDK The PI SDK and the PI API are bundled together and must be installed on each interface node. This interface does not specifically make PI SDK calls. Source of Timestamps The interface uses PI time for the all data received from HMX. UniInt-based UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the 4

11 UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features. The PI Universal Interface (UniInt) User Guide is a supplement to this manual. Connection Options Connection HMX with AM MX Server TCP/IP Usage Requires HMX ODX software version 1.4 or higher. For use with the MX Server, it requires Server software version 1.2 or higher. Requires MX Server software version 1.2 or higher. TCP/IP support is required on the computer executing the interface. Diagram of Hardware Connection PI Interface for Measurex MXO 5

12 Introduction The following figure shows the connection topologies for PI MXOpen interface to HMX. PI to Measurex Interface PEER to PEER PI Tag Database Tag For One MX Node PI Host Process ODX Protocol Application Manager for PM1 PEER to MANY PI Tag Database Tag For Many MX Nodes through Single Server PI Host Process MX Server Protocol MX Server ODX Protocol Sample Measurex Network DataFreeway Protocol Data Freeway Node for Node 3 Application Manager for Node 1 Application Manager for Node 2 PEER to PEER Through Server PI Tag Database MX Server Tag For Single MX Node Tag For Single MX Node Tag For Single MX Node PI Host Process PI Host Process PI Host Process MX Server Protocol MX Server Protocol MX Server Protocol Application Manager for Node 1 Application Manager for Node 2 Data Freeway for Node 3 Sample Measurex Network 6

13 Chapter 2. Principles of Operation The PI MXOpen interface establishes the initial connection to PI Data Archive and reconnects to PI Data Archive in the event that the connection is lost for some reason. If the Interface is started while the PI Data Archive is down, the interface will periodically try to establish a connection until the PI Data Archive is up. After the successful connection to the PI Data Archive, the interface will attempt to make a connection to the MX Server. The startup process cannot complete if the service is unavailable so the interface will remain in the startup mode until it has successfully connected to the MX Server. If the initial connection attempt is unsuccessful, a reconnect will be attempted once every minute After successfully connecting to the MX Server, the interface will loop thru all of the PI points that are associated with the point source specified by the /ps startup parameter. After the PI points are loaded, the interface will poll the MX Server. The interface uses information stored in the PI point s location information to map MX Server data to points. PI Interface for Measurex MXO 7

14

15 Chapter 3. Installation Checklist If you are familiar with running PI data collection interface programs, this checklist helps you get the interface running. If you are not familiar with PI interfaces, return to this section after reading the rest of the manual in detail. This checklist summarizes the steps for installing this interface. You need not perform a given task if you have already done so as part of the installation of another interface. For example, you only have to configure one instance of Buffering for every interface node regardless of how many interfaces run on that node. The Data Collection Steps below are required. Interface Diagnostics and Advanced Interface Features are optional. Data Collection Steps 1. Configure the HMX systems according to the HMX MX Server Manual if the MX Server is used 2. Confirm that you can use PI SMT to configure the PI Data Archive. You need not run PI SMT on the same computer on which you run this interface. 3. If you are running the interface on an interface node, edit the PI Data Archive s Trust Table to allow the interface to read attributes and point data. If a buffering application is not running on the interface node, the PI trust must allow the interface to write data. 4. Run the installation kit for the PI Interface Configuration Utility (ICU) on the interface node if the ICU will be used to configure the interface. This kit runs the PI SDK installation kit, which installs both the PI API and the PI SDK. 5. Run the installation kit for this interface. This kit also runs the PI SDK installation kit, which installs both the PI API and the PI SDK. 6. If you are running the interface on an interface node, check the computer s time zone properties. An improper time zone configuration can cause the PI Data Archive to reject the data that this interface writes. 7. Run the ICU and configure a new instance of this interface. Essential startup parameters for this interface are Point Source (/PS=x) Interface ID (/ID=#) PI Data Archive (/Host=host:port) Scan Class (/F=##:#) TCP/IP Link End Point (/IntfHost=host) Communication Watchdog Tag (/IntfTg=tagname) PI Interface for Measurex MXO 9

16 Installation Checklist Keep Alive Rate (/ka=#) HMX Node IP Address (/mxinet=x.x.x.x) Polling Rate (/poll=x) 8. Test the connection between the interface node and MX using ping from both endpoints. 9. If you will use digital points, define the appropriate digital state sets. 10. Build input tags and, if desired, output tags for this interface. Important point attributes and their purposes are: Location1 contains the Process Number and the HMX System number. Location2 contains the Variable Type, Data Type, and Array Element Number. Location3 used to set up Unsolicited Time. Location4 specifies the scan class. Location5 specifies the Input / Output Flag, the HMX Processor Number, and the BTI Number. ExDesc can be used to define trigger-based tags. InstrumentTag contains the HMX Symbol Name. PtSecurity must permit read access for the PI identity, group, or user configured in the PI trust that is used by the interface. DataSecurity must permit read access (buffering enabled) or read/write access (unbuffered) for the PI identity, group, or user configured in the PI trust that is used by the interface. Security Note: When buffering is configured, the DataSecurity attribute must permit write access for the buffering application s PI trust or mapping. DataSecurity write permission for the interface s PI trust is required only when buffering is not configured. 11. Start the interface interactively and confirm its successful connection to the PI Data Archive without buffering. (The DataSecurity attribute for interface points must permit write access for the interface s PI trust.) 12. Confirm that the interface collects data successfully. 13. If output points are required, confirm that output points update the correct values in the data source. 14. Stop the interface and configure a buffering application (either Bufserv or PIBufss). When configuring buffering use the ICU menu item Tools Buffering Buffering Settings to make a change to the default value (32678) for the Primary and Secondary Memory Buffer Size (Bytes) to This will optimize the throughput for buffering and is recommended by OSIsoft. 15. Start the buffering application and the interface. Confirm that the interface works together with the buffering application by physically removing the connection between the interface node and the PI Data Archive node. (The DataSecurity attribute for interface points must permit write access for the buffering application s PI trust or mapping. The interface s PI trust does not require DataSecurity write permission.) 16. Configure the interface to run as a Windows service. Confirm that the interface runs properly as a service. 10

17 17. Restart the interface node and confirm that the interface and the buffering application restart. Interface Diagnostics 1. Configure Scan Class Performance points. 2. Install the PI Performance Monitor Interface (Full Version only) on the interface node. 3. Configure Performance Counter points. 4. Configure UniInt Health Monitoring points 5. Configure the I/O Rate point. 6. Install and configure the Interface Status Utility on the PI Data Archive Node. 7. Configure the Interface Status point. PI Interface for Measurex MXO 11

18

19 Chapter 4. Interface Installation OSIsoft recommends that interfaces be installed on interface nodes instead of directly on the PI Data Archive node. An interface node is any node other than the PI Data Archive node where the PI Application Programming Interface (PI API) is installed (see the PI API manual). With this approach, the PI Data Archive need not compete with interfaces for the machine s resources. The primary function of the PI Data Archive is to archive data and to service clients that request data. After the interface has been installed and tested, buffering should be enabled on the interface node. Buffering refers to either PI API Buffer Server (Bufserv) or the PI Buffer Subsystem (PIBufss). For more information about buffering see the Buffering chapter of this manual. In most cases, interfaces on interface nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure. The guidelines are different if an interface is installed on the PI Data Archive node. In this case, the typical procedure is to install the PI Data Archive as an automatic service and install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. This typical scenario assumes that buffering is not enabled on the PI Data Archive node. Bufserv or PIBufss can be enabled on the PI Data Archive node so that interfaces on the PI Data Archive node do not need to be started and stopped in conjunction with the PI Data Archive, but it is not standard practice to enable buffering on the PI Data Archive node. The PI Buffer Subsystem can also be installed on the PI Data Archive. See the PI Universal Interface (UniInt) User Guide for special procedural information. Naming Conventions and Requirements In the installation procedure below, it is assumed that the name of the interface executable is mxo.exe and that the startup command file is called mxo.bat. When Configuring the Interface Manually It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, mxo1.exe and mxo1.bat would typically be used for instance 1, mxo2.exe and mxo2.bat for instance 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name. PI Interface for Measurex MXO 13

20 Interface Installation Interface Directories PIHOME Directory Tree The [PIHOME] directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory. For 32-bit operating systems, a typical pipc.ini file contains the following lines: [PIPC] PIHOME=C:\Program Files\PIPC For 64-bit operating systems, a typical pipc.ini file contains the following lines: [PIPC] PIHOME=C:\Program Files (X86)\PIPC The above lines define the root of the PIHOME directory on the C: drive. The PIHOME directory does not need to be on the C: drive. OSIsoft recommends using the paths shown above as the root PIHOME directory name. Security Note: Restrict the Windows accounts that can create or write files in the %PIHOME% folder and subfolders. Interface Installation Directory The interface install kit will automatically install the interface to: PIHOME\Interfaces\MXOpen\ PIHOME is defined in the pipc.ini file. Interface Installation Procedure The PI MXOpen interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and later operating systems. To install, run the appropriate installation kit. mxopen_#.#.#.#_.exe PI Trust for Interface Authentication A PI Interface usually runs on an interface node as a Windows service, which is a noninteractive environment. In order for an interface to authenticate itself to a PI Data Archive and obtain the access permissions for proper operation, the PI Data Archive must have a PI trust that matches the connection credentials of the interface. Determine if a suitable PI trust for the interface exists on the PI Data Archive. If a suitable PI trust does not exist, see the Security chapter for instructions on creating a new PI trust. 14

21 Installing Interface as a Windows Service The PI MXOpen interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually. Security Note: We recommend running the interface service under a nonadministrative account, such as a Windows built-in service virtual account, the builtin Network Service account, or a non-administrative account that you create. The advantage of running the interface service under an account with least privileges is improved security. The disadvantage of running the interface service with least privileges is that, depending on the account, the interface service may not be able to create performance counters. Since UniInt health points provide essentially the same information, you may not need performance counters. If so, configure the interface instance to disable UniInt performance counters. If performance counters are required, extra administrative actions are needed to create and maintain the performance counters. Since performance counters are associated with each scan class, performance counters for the interface instance must be created or deleted after adding or removing scan classes. Run the interface instance, at least for a short time, from an account that has sufficient privileges to create or delete performance counters. Installing Interface Service with PI Interface Configuration Utility The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service: PI Interface for Measurex MXO 15

22 Interface Installation Service Configuration Service name The Service name box shows the name of the current interface service. This service name is obtained from the interface executable. ID This is the service ID used to distinguish multiple instances of the same interface using the same executable. Display name The Display name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a PI- prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix PI- be appended to the beginning of the interface name to indicate that the service is part of the OSIsoft suite of products. Log on as The Log on as box shows the current Log on as Windows account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show LocalSystem. Users may specify a different Windows account for the service to use. Security Note: For best security, we recommend running this interface service under an account with minimum privileges, such as a Windows built-in service virtual account, the built-in Network Service account, or a non administrative account that you create. PI ICU versions earlier than x cannot create a service that runs as a Windows built-in service virtual account or the built-in Network Service or Local Service accounts. After ICU creates the interface service, you can change the account with a Windows administrative tool, such as Services on the Control Panel or the sc command-line utility. As discussed earlier, following the recommendation to run the interface service under a lowprivilege account may affect performance counters. Password If a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password. Confirm password If a password is entered in the Password text box, then it must be confirmed in the Confirm password text box. 16

23 Dependencies The Installed services list is a list of the services currently installed on this machine. Services upon which this interface is dependent should be moved into the Dependencies list using the button. For example, if API Buffering is running, then bufserv should be selected from the list at the right and added to the list on the left. To remove a service from the list of dependencies, use the Dependencies list. button, and the service name will be removed from the When the interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the interface service will not run. Note: Please see the PI Log and Windows Event Logger for messages that may indicate the cause for any service not running as expected. - Add Button To add a dependency from the list of Installed services, select the dependency name, and click the Add button. - Remove Button To remove a selected dependency, select the service name in the Dependencies list, and click the Remove button. The full name of the service selected in the Installed services list is displayed below the Installed services list box. Startup Type The Startup Type indicates whether the interface service will start automatically or needs to be started manually on reboot. If the Auto option is selected, the service will be installed to start automatically when the machine reboots. If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service. If the Disabled option is selected, the service will not start at all. Generally, interface services are set to start automatically. Create The Create button adds the displayed service with the specified Dependencies and with the specified Startup Type. PI Interface for Measurex MXO 17

24 Interface Installation Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out. Start or Stop Service The toolbar contains a Start button and a Stop button. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available. The status of the interface service is indicated in the lower portion of the PI ICU dialog. Status of the ICU Status of the Interface Service Service installed or uninstalled 18

25 Installing Interface Service Manually Help for installing the interface as a service is available at any time with the command: mxo.exe /help Open a Windows command prompt window and change to the directory where the mxo.1.exe executable is located. Then, consult the following table to determine the appropriate service installation command. Note: In the following Windows Service Installtation Commands you may use either a slash (/) or dash (-) as the delimiter. Windows Service Installation Commands on an Interface Node or a PI Data Archive Node with Bufserv implemented Manual service Automatic service *Automatic service with service ID mxo.exe /install /depend "tcpip bufserv" mxo.exe /install /auto /depend "tcpip bufserv" mxo.exe /serviceid X /install /auto /depend "tcpip bufserv" Windows Service Installation Commands on an Interface Node or a PI Data Archive Node without Bufserv implemented Manual service Automatic service *Automatic service with service ID mxo.exe /install /depend tcpip mxo.exe /install /auto /depend tcpip mxo.exe /serviceid X /install /auto /depend tcpip *When specifying service ID, the user must include an ID number. It is suggested that this number correspond to the interface ID (/id) parameter found in the interface.bat file. Check the Microsoft Windows Services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa. The service installation commands in this section always create an interface service that runs under the built-in Local System account. The Local System account is highly privileged and the interface does not need most of the Local System privileges to operate correctly. Security Note: For best security, we recommend running this interface service under an account with minimum privileges, such as a Windows service virtual account, the built-in Network Service account, or a non administrative account that you create. As discussed earlier, following the recommendation to run the interface service under a lowprivilege account may affect performance counters. The services control panel can change the account that the interface service runs under. Changing the account while the interface service is running does not take effect until the interface service is restarted. PI Interface for Measurex MXO 19

26

27 Chapter 5. Digital States For more information regarding Digital States, refer to the PI Data Archive documentation. Digital State Sets PI digital states are discrete values represented by strings. These strings are organized in the PI Data Archive as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital points and editing digital state sets, see the PI Data Archive manuals. An interface point that contains discrete data can be stored in the PI Data Archive as a digital point. A digital point associates discrete data with a digital state set, as specified by the user. System Digital State Set Similar to digital state sets is the system digital state set. This set is used for all points, regardless of type, to indicate the state of a point at a particular time. For example, if the interface receives bad data from the data source, it writes the system digital state Bad Input to the PI point instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients. Digital States are reserved for OSIsoft applications. The interface requires that the following digital states are defined in the System Digital State Set for a PI Data Archive. The default starting code is 550 if the /IOSTAT parameter is not passed in the start-up command file. The IOStatus Codes are shown in numerically increasing order. Thus, if IOStatus WaitScnr is entered in the Digital State Table at number 550, then IOStatus UndfSymMX is positioned at number 603. Reserved items can be left blank. Scanner/Profile Statuses Code State Description 550 WaitScnr Scanner waiting to move 551 BkgrdScnr Scanner in background mode 552 RefScnr Scanner in reference mode 553 SmplScnr Scanner in sample mode 554 StdzScnr Scanner in standardize mode 555 ScanScnr Scanner in scan mode 556 SnglPtScnr Scanner in single point mode 557 OffShtScnr Scanner in offsheet mode 558 EmrgOffScnr Scanner in emergency offsheet mode (probably because of sheet break) 559 2StrtScnr Scanner getting ready to start PI Interface for Measurex MXO 21

28 Digital States Code State Description 560 LimboScnr Scanner in limbo scan mode (usually locating sheet edges) 561 SmplGrdScnr Scanner in grade sample mode 562 OfflineScnr Scanner in offline mode 563 ProfCorScnr Scanner in profile correction mode 564 ReptScnr Scanner in repeat mode 565 GrdLdScnr Scanner in load grade data mode Data Value Statuses Code State Description 566 BadRdSnsr Sensor data reading is invalid 567 NoMsmtSnsr Sensor reading is beyond edges of sheet 568 Unavail Value invalid according to status of specified validity flag symbol 569 Unkn Status Unknown validity status if specified validity flag symbol is undefined 570 No Update No PI tag data update occurred within the expected time period 571 Msg Cancel Message for this PI tag is canceled 572 BdDataType MX Symbol Data type is not supported by PI (for ex: ASCII) 573 Reserved 574 Reserved 575 Reserved 576 Reserved 577 Reserved 578 Reserved 579 Reserved MX Server or ODX Errors Code State Description 580 2MnyNdRqMX MX Server: Message requests to too many nodes 581 IDNtActvMX Message ID not active 582 ProcOfflMX MX Server: HMX Process Node is offline 583 2MnyReqMX MX Server: Too many active message requests 584 ODXEFLWMX Communications Error with ODX 585 Reserved 586 Reserved 22

29 Code State Description 587 Reserved 588 Reserved 589 Reserved 590 BadHostMX MX Server: Bad Host Name 591 BadUsrIDMX Bad User ID 592 BadProcMX MX Server: Bad Process Name 593 BadEvSymMX MX Server: Bad Event Symbol 594 BadReqHdrMX MX Server: Bad Header in Request message 595 NoSymMX No Symbol specified in last message 596 DB ErrMX MX Server: Database error 597 NoProfilMX MX Server: Profile Not allowed 598 2MnyUndfMX Too Many Undefined Symbols in last message 599 2MnySymMX Too Many Symbols in Request 600 MsngDataMX Interface missing data in last message. 601 BdDataMX Interface received uninterpretable data from MX 602 BdTrgSymMX Bad Message Trigger Symbol 603 UndfSymMX Undefined Symbol PI Interface for Measurex MXO 23

30

31 Chapter 6. PointSource The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string Boiler1 may be used to identify points that belong to the MyInt interface. To implement this, the PointSource attribute would be set to Boiler1 for every PI point that is configured for the MyInt interface. Then, if /ps=boiler1 is used on the startup command-line of the MyInt interface, the interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of Boiler1. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps parameter. If the PI API version being used is prior to 1.6.x or the PI Data Archive version is prior to x, the PointSource is limited to a single character unless the SDK is being used. Case-sensitivity for PointSource Attribute The PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=p and /ps=p are equivalent. Reserved Point Sources Several subsystems and applications that ship with the PI System are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem for Alarm Tags, G for Group Alarms and Q for SQC Alarm Tags, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface. Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface. PI Interface for Measurex MXO 25

32

33 Chapter 7. PI Point Configuration The PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived. Point Attributes Use the point attributes below to define the PI point configuration for the interface, including specifically what data to transfer. This document does not discuss the attributes that configure UniInt or PI Data Archive processing for a PI point. Specifically, UniInt provides exception reporting and the PI Data Archive provides data compression. Exception reporting and compression are very important aspects of data collection and archiving, which are not discussed in this document. Note: See the UniInt Interface User Manual and PI Data Archive documentation for information on other attributes that are significant to PI point data collection and archiving. Tag The Tag attribute (or tag name) is the name for a point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms tag and point interchangeably. Follow these rules for naming PI points: Length The name must be unique on the PI Data Archive. The first character must be alphanumeric, the underscore (_), or the percent sign (%). Control characters such as linefeeds or tabs are illegal. The following characters also are illegal: *? ; { } [ ] \ ` ' " Depending on the version of the PI API and the PI Data Archive, this interface supports Tag attributes whose length is at most 255 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Data Archive versions. PI API PI Data Archive Maximum Length or higher x or higher 1023 PI Interface for Measurex MXO 27

34 PI Point Configuration PI API PI Data Archive Maximum Length or higher Earlier than x 255 Earlier than x or higher 255 Earlier than Earlier than x 255 If the PI Data Archive version is earlier than x or the PI API version is earlier than , and you want to use a maximum tag length of 1023, you need to enable the PI SDK. See Appendix B for information. PointSource The PointSource attribute contains a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the PointSource chapter. PointType Typically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating-point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated. PI3: Float16, float32, float 64, int16, int32, digital, and string PointTypes are supported. (String types are only supported when running the interface on Windows.) PI2: R, I, and D PointTypes are supported. For more information about the individual PointTypes, see the PI Data Archive manuals. Location1 The first location contains the Process Number (PP) and the HMX System Number (SSS) packed as: (PP * 1,000) + SSS That is: PPSSS Where: Process Number refers to the ordinal position of the ASCII name (See description of /proc=process Name in the startup parameters.) of the group of process equipment associated with this PI tag. When communication is via the ODX protocol, use PP=01 because there is only one Process Name per interface instance to communicate in a peer-to-peer topology with the AM nodes. HMX System Number matches the three-digit number in the startup parameter /mxo=sss. The specific usage of these items depends upon the nature of the connection with HMX and upon the startup file. 28

35 Location2 The second location specifies the Variable Type (V), the Data Type (D) and the Array Element Number (AAAA) packed as: (V * 100,000) + (D* 10,000) + AAAA That is where: VDAAAA Variable Type (V) specifies the type of variable referred to by the HMX symbol name (see the Instrument Tag below): Input Output 1 Single value Y Single value 2 Array: one element in a structure of equivalent values 3 ODX Scanning Display Profile Array: one element in a structure of equivalent values 4 ODX Scanning Reel Profile Array: one element in a structure of equivalent values 5 ODX Scanning Minislice Profile Array: one element in a structure of equivalent values 6 ODX Numbers stored in HMX (v2.14 and higher) 7 ASCII Strings (v4.09 and higher; PI3.x) Variable types 3 through 6 are supported only for Peer-to-peer Connections to HMX AM Nodes via ODX. Variable types 3-5 are provided for the special information embedded in scanner-based profiles (i.e., Scanner status, sensor status, and edge positions). In order to provide this additional information, the interface makes assumptions that the AM follows an HMX symbol-naming standard. See the section Profile Status Handling below for more information. Variable type 6 allows the interface to receive ASCII-numerical data from HMX and store it as a number in the PI database. Data Type (D) specifies the kind of data. Two data types are supported: Type Meaning 1 Numeric Value 2 Digital value (In HMX terminology, an Ordinal value) Array Element Number (AAAA) specifies the correspondence of this PI point with an element within an HMX array (Variable Type 2 to 5). The maximum Array Element Number for Variable Types 2 to 4 is now 256. For Variable Type 5, the maximum is For Variable Types 1, 6, and 7, set AAAA to PI Interface for Measurex MXO 29

36 PI Point Configuration 30 Location3 The third location is used to set up an UNSOLICITED TIME where HMX provides the time trigger: MX Trigger Time Rate (RRRRR) in seconds: That is where: RRRRR MX Trigger Time Rate (optional) specifies how often HMX should send the data for this PI tag. This attribute must be zero if Location4>0, or PI Event or HMX Event triggers are defined. A non-zero value for this attribute is required for UNSOLICITED TIME INPUT tags. Location4 Scan-based Inputs For interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f parameter in the Startup Command File chapter. Trigger-based Inputs, Unsolicited Inputs, and Output Points Location 4 should be set to zero for these points. Location5 Specifies the Input/Output Flag (F), the HMX Processor Number (M), and the BTI Number (BBBB) packed as: (F * 100,000) + (M * 10,000) + BBBB That is Where: FMBBBB Input /Output Flag 0 = Input 1 = Output HMX Processor Number (optional) defines the ASCII name of the HMX processor (LPN) associated with this point. It is used in conjunction with interface startup parameter /LPN=ProcessorName1, /LPN=ProcessorName2, and so forth. Processor Number references the nth item in the list of /LPN= startup parameters to provide the ASCII for the Processor name. If no ASCII name of the HMX processor is associated with this point, set M to zero. BTI Number (optional) defines the ASCII name of the HMX memory bank associated with this point. It is used in conjunction with interface startup parameter /BTI=BTIName1, /BTI=BTIName2, and so forth. BTI Number references the nth item in the list of /BTI= startup parameters to provide the ASCII for the BTI name. If no ASCII name of the HMX memory bank is associated with this point, set BBBB to 0000.

37 Notes: (1) The LPN and BTI numbers are usually not required unless the HMX symbol name is not unique within a HMX LPN. In practice, the symbols of interest to the PI Data Archive are not likely to be so defined. (2) If either LPN or BTI number is provided, then both must be provided. The interface log file will report an error if HMX cannot uniquely resolve the symbol name; that is, HMX system has more than one symbol with the same name. InstrumentTag Each PI tag must have a valid HMX Symbol Name in the InstrumentTag attribute. The PI MXOpen interface limits the InstrumentTag to 32 characters, whereas HMX allows up to 40 characters. Valid characters in symbol names are underscore (_), dollar sign ($), numbers (0-9), letters (a-z), and period (.). No embedded blanks are allowed. When the interface is connected to an AM node, it will report instances of undefined HMX symbol names. Symbols cannot be verified when the interface is communicating via the MX Server with Data Freeway because the MX Server does not support external symbol verification for Data Freeway. Thus, for Data Freeway nodes, the interface assumes all symbols to be properly defined in the MX Server. Note: The MX Server sometimes has problems when attempts are made to access undefined symbols on Data Freeway nodes. As a result, it is suggested that the user verify the accuracy of the symbols for Data Freeway nodes by trying them at the MX Server. If HMX symbols are not unique within a node and require LPNx\BTIDx type specifications, do not specify the full HMX variable in the InstrumentTag as LPNx\BTIx\Variable_Name. If the LPN and BTI are specified in Location5, the interface will automatically prepend the LPN and BTI specification to the symbol name specified in the InstrumentTag. Length Depending on the version of the PI API and the PI Data Archive, this interface supports an InstrumentTag attribute whose length is at most 32 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Data Archive versions. PI API PI Data Archive Maximum Length or higher x or higher or higher Earlier than x 32 Earlier than x or higher 32 Earlier than Earlier than x 32 Internal to the interface is a hard maximum length of 32. PI Interface for Measurex MXO 31

38 PI Point Configuration ExDesc Length Depending on the version of the PI API and the PI Archive, this interface supports an ExDesc attribute whose length is at most 80 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Data Archive versions. PI API PI Data Archive Maximum Length or higher x or higher or higher Earlier than x 80 Earlier than x or higher 80 Earlier than Earlier than x 80 Internal to the interface, ExDesc has a hard 80 maximum length. Unsolicited Event Input /Tx= specifies any defined HMX Ordinal Symbol Name of an HMX event trigger that is used to trigger transmission of unsolicited data to this PI tag. It has a maximum of 31 characters. This parameter is required for UNSOLICITED EVENT INPUT tags. The HMX Symbol must refer to a HMX Ordinal (i.e., digital flag). Where: Value /Tx= can have the values listed in the following table: Meaning /T0 = Trigger on 0 to 1 transition of HMX variable /T1 = Trigger on 1 to 0 transition of HMX variable /T2 = Trigger on any transition of HMX variable Validity of InstrumentTag /Vx= specifies any defined HMX Symbol Name of an HMX variable, which provides the validity of the HMX variable specified in the InstrumentTag attribute. It has a maximum of 31 characters. This is useful for attaching status to any given HMX value. HMX Symbol can refer to any numeric data value, where: /Vx= can have values listed in the following table: Value Meaning /V0 = Value is valid if the value referenced by this HMX symbol is 0 /V1 = Value is valid if the value referenced by this HMX symbol is not 0 SourceTag for Outputs source=source_tag_name can be used instead of the SourceTag PI point attribute to specify the source of the data to send to the Measurex tag. Performance Points For UniInt-based interfaces, the extended descriptor is checked for the string PERFORMANCE_POINT. If this character string is found, UniInt treats this point as a performance point. See the section called Scan Class Performance Points. 32

39 Scan By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the Scan attribute to 0 turns scanning off. If the Scan attribute is 0 when the interface starts, a message is written to the log and the point is not loaded by the interface. There is one exception to the previous statement. If any PI point is removed from the interface while the interface is running (including setting the Scan attribute to 0), SCAN OFF will be written to the PI point regardless of the value of the Scan attribute. Two examples of actions that would remove a PI point from an interface are to change the point source or set the Scan attribute to 0. If an interface-specific attribute is changed that causes the point to be rejected by the interface, SCAN OFF will be written to the PI point. Shutdown The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown Subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Data Archive manuals. Note: The SHUTDOWN events that are written by the PI Shutdown Subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=shutdown command-line parameter is specified. SHUTDOWN events can be disabled from being written to PI points when the PI Data Archive is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the Shutdown.dat file, as discussed in PI Data Archive manuals. Bufserv and PIBufss It is undesirable to write shutdown events when buffering is being used. Bufserv and PIBufss are utility programs that provide the capability to store and forward events to a PI Data Archive, allowing continuous data collection when the PI Data Archive is down for maintenance, upgrades, backups, and unexpected failures. That is, when the PI Data Archive is shutdown, Bufserv or PIBufss will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface. Disabling Shutdown is recommended when sending data to a Highly Available PI Data Archive Collective. Refer to the Bufserv or PIBufss manuals for additional information. DataSecurity The PI identity in the PI trust that authenticates the interface must be granted read access by the DataSecurity attribute of every PI point that the interface services. If the interface is used without a buffering application, write access also must be granted. (If the interface is used PI Interface for Measurex MXO 33

40 PI Point Configuration with a buffering application, the buffering application requires write access but the interface does not.) PtSecurity The PI identity in the PI trust that authenticates the interface must be granted read access by the PtSecurity attribute of every PI point that the interface services. Output Points Output points control the flow of data from the PI Data Archive to any destination that is external to the PI Data Archive, such as a PLC or a third-party database. For example, to write a value to a register in a PLC, use an output point. Each interface has its own rules for determining whether a given point is an input point or an output point. There is no de facto PI point attribute that distinguishes a point as an input point or an output point. Security Note: When output points are required, implement an output point whitelist, which provides a defense against accidental or malicious changes to the control system. Outputs are triggered for UniInt-based interfaces. That is, outputs are not scheduled to occur on a periodic basis. There are two mechanisms for triggering an output. As of UniInt 3.3.4, event conditions can be placed on triggered outputs. The conditions are specified using the same event condition keywords in the extended descriptor as described under Trigger-based Inputs. The only difference is that the trigger point is specified with the SourceTag attribute instead of with the event or trig keywords. Otherwise, the behavior of event conditions described under Trigger-based Inputs is identical for output points. For output points, event conditions are specified in the extended descriptor as follows: event_condition The keywords in the following table can be used to specify trigger conditions. Event Condition Anychange Increment Decrement Nonzero Description Trigger on any change as long as the value of the current event is different than the value of the previous event. System digital states also trigger events. For example, an event will be triggered on a value change from 0 to Bad Input, and an event will be triggered on a value change from Bad Input to 0. Trigger on any increase in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 0 to 1, but an event will not be triggered on a value change from Pt Created to 0. Likewise, an event will not be triggered on a value change from 0 to Bad Input. Trigger on any decrease in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 1 to 0, but an event will not be triggered on a value change from Pt Created to 0. Likewise, an event will not be triggered on a value change from 0 to Bad Input. Trigger on any non-zero value. Events are not triggered when a system digital state is written to the trigger point. For example, an event is triggered on a value change from Pt Created to 1, but an event is not triggered on a value change from 1 to Bad Input. 34

41 Trigger Method 1 (Recommended) For trigger method 1, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any point source, including the point source of the interface. Also, the point type of the trigger point does not need to be the same as the point type of the output point. The output point is associated with the trigger point by setting the SourceTag attribute of the output point equal to the tag name of the trigger point. An output is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous value that was sent to the Snapshot to trigger an output, but the timestamp of the new value must be more recent than the previous value. If no error is indicated, then the value that was sent to the trigger point is also written to the output point. If the output is unsuccessful, then an appropriate digital state that is indicative of the failure is usually written to the output point. If an error is not indicated, the output still may not have succeeded because the interface may not be able to tell with certainty that an output has failed. Trigger Method 2 For trigger method 2, a separate trigger point is not configured. To trigger an output, write a new value to the Snapshot of the output point itself. The new value does not need to be different than the previous value to trigger an output, but the timestamp of the new value must be more recent than the previous value. Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2 has a significant disadvantage. If the output is unsuccessful, there is no point to receive a digital state that is indicative of the failure, which is very important for troubleshooting. PI Interface for Measurex MXO 35

42 PI Point Configuration Configuration Examples The following PI point configuration examples explain the point attribute definitions specified above. Profiles -- Unsolicited Event Input PI tag for the 50th element of a HMX display profile named P11_BWAR, which is, triggered by the HMX event flag P1EOS.ORD ; Process #1, HMX #1. Location Location (Var Type 3 * 100,000 + Data Type 1 * 10,000 + Array Element 50) Location3, 4, and 5 0 InstrumentTag -- P11_BWAR ExDesc -- /T0=P1EOS.ORD (triggers on a 0 to 1 transition of HMX flag) Single Variable -- Unsolicited Time Input PI tag for the machine speed named P1SPEED to be transmitted by the HMX MX Server every 30 seconds; Process #1, HMX #1. Location Location (Var Type 1 * 100,000 + Data Type 1 * 10, ) Location (HMX Trigger rate [sec]) Location4 and Location5 0 InstrumentTag -- P1SPEED Single Variable -- Solicited Time Input PI tag for the machine speed named P1SPEED to be requested by PI every 30 seconds; Process #1, HMX #1. Location Location (Var Type 1 * 100,000 + Data Type 1 * 10, ) Location3 0 Location (Refers to the Scan Group number that was setup in the startup file MXO.com to have a repeat rate of 30 seconds) Location5 0 InstrumentTag -- P1SPEED 36

43 Profile Status Handling The PI MXOpen interface has a built-in capability for handling the special status requirements of scanning sensor-based profiles. In addition to values for each profile element, a profile has scanner status, sensor status, and sheet edge positions. For Variable Type Profile or Minislice Profile (Variable Type 3, 4, or 5 -- therefore, only for Application Manager systems), the interface obtains the correct scanner sensor status flags for the scanner and sensor specified by the HMX symbol in the InstrumentTag field. It also obtains the edge-of-sheet slice positions for each sensor. The interface assumes that the HMX symbol name for a profile variable has the following format: ProcessNameScanner#SensorIDProfileID. For example, the symbol of the scanner 1 basis weight profile is P11_bw1tp Where: P1 is the process name 1 is the scanner # bw1 is the sensor ID tp is the id for the display profile. The interface parses the HMX symbol name specified in the InstrumentTag to obtain the scanner number and sensor ID. Using these, the interface builds the HMX symbol names for the scanner status and sensor status as follows: Scanner Status P11SCRVMODE 1 is replaced by the appropriate scanner # Sensor Status P11bw1.badrd bw1 is replaced by the appropriate sensor ID High Edge P11bw1BTMSLx x is replaced by T, R and Z for types 3, 4, and 5 respectively High Edge P11bw1TOPSLx x is replaced by T, R and Z for types 3, 4, and 5 respectively In addition, the interface will make a special request for scanner status information if no profile data is received within the time period specified by the /POLL parameter in the startup file. This can be valuable if the scanner is offsheet due to a paper break, etc. In this situation, the PI tags for the profile will show a status of Emergency OFFSheet or OFFSheet. Note: If the Application Manager does not follow this convention for profile data, the user may want to ask HMX to make the required changes. PI Interface for Measurex MXO 37

44

45 Chapter 8. Startup Command File Command-line parameters can begin with a / or with a -. For example, the /ps=m and -ps=m command-line parameters are equivalent. For Windows, command file names have a.bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters. The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the interface startup command file. Configuring the Interface with PI ICU Note: PI ICU requires PI 3.3 or greater. The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface (mxo#.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file and the PI Module Database. The procedure below describes the necessary steps for using PI ICU to configure the PI MXOpen interface. From the PI ICU menu, select Interface, then NewWindows Interface Instance from EXE.A window such as the following opens: PI Interface for Measurex MXO 39

46 Startup Command File Browse to the mxo.exe executable file. Then, enter values for Host PI Server/Collective, Point Source, and Interface ID#. Interface name as displayed in the ICU (optional) will have PI- pre-pended to this name and it will be the display name in the services menu. Click Add. The following message should appear: Note that in this example the Host PI Data Archive is MKELLYD630W7. To configure the interface to communicate with a remote PI Data Archive, select Connections from the PI ICU Interface menu and select the default server. If the remote node is not present in the list of servers, it can be added. Once the interface is added to PI ICU, near the top of the main PI ICU screen, the interface Type should be mxopen. If not, use the drop-down box to change the interface Type to be mxopen. Click Apply to enable the PI ICU to manage this instance of the PI MXOpen interface. 40

47 The next step is to make selections in the interface-specific page (that is, mxopen ) that allows you to enter values for the startup parameters that are particular to the PI MXOpen interface. Since the PI MXOpen interface is a UniInt-based interface, in some cases you will need to make appropriate selections in the UniInt page, which configures UniInt features through the PI ICU. To set up the interface as a Windows service, use the Service page. This page allows configuration of the interface to run as a service as well as starting and stopping of the interface service. The interface can also be run interactively from the PI ICU. To do that, select Start Interactive on the Interface menu. For more detailed information on how to use the above-mentioned and other PI ICU pages and selections, please refer to the PI Interface Configuration Utility user guide. The next section describes the selections that are available from the PI MXOpen page. Once selections have been made on the PI ICU window, press the Apply button in order for PI ICU to make these changes to the interface s startup file. PI Interface for Measurex MXO 41

48 Startup Command File mxopen Interface Page Since the startup file of the PI MXOpen interface is maintained automatically by the PI ICU, use the mxopen page to configure the startup parameters and do not make changes in the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters. mxopen The PI Interface for Measurex MXO - ICU Control has three sections/tabs. A yellow text box indicates that an invalid value has been entered or that a required value has not been entered. Common HMX Node IP Address This is the IP address of the HMX node to which the interface is connection. If there is an MX Server, this is the IP address of the server, otherwise, it is the IP address of the AM node. (/mxinet=<ipaddress>, Default: None, Required) PI status code start no Starting number of PI System digital state where interface -specific states are located. (/iostat=#, Default: 550, Optional) 42

49 TCP/IP link end point Name of PI interface node connected to the HMX system. The name is used by HMX and the PI interface node to display in system and error messages. (/intfhost=<hostname>, Default: None, Required) Symbol verification delay The number of seconds to delay between symbol verification. This depends upon the capacity of MX AM to handle the CPU intensive symbol lookup. (/symdly=#, Default:0.5, Optional) Maximum HMX symbols in single data request The maximum number of HMX symbols to include in a single data request. (/mxsym=#, Default: 20, Range: 1-100, Optional) Time to wait between checks for runtime directives The number of seconds to wait between checks for runtime directives. (/MXRate=#, Default:120 sec, Optional) Maximum time allowed between data messages The maximum number of seconds allowed between data messages based upon the same MX Event before declaring a separate occurrence. This is used with unsolicited and event-driven messages. The default is for every message to be processed as a unique event. (/TMALN=#, Optional) DaVinci system / No verifying trigger symbols Indicated that the interface does not verify trigger symbols. This is important in communicating with a DaVinci system. (/notrgv, Optional) Communication watchdog tag This is the tag used to indicate if communication to the HMX is up or down. It will have a value of 1 if it is up and 0 if down. This tag is typically a digital tab, but can also be a numeric tag. It also does not use the PointSource of the interface. (/intftg=<tagname>, Default: None, Required) Additional Parameters This section is provided for any additional parameters that the current ICU Control does not support. Timing Parameters Keep Alive rate This is the rate in seconds that the interface queries the network connection to the HMX in order to verify the status. (/ka=#, Default: None, Required) PI Interface for Measurex MXO 43

50 Startup Command File Maximum time for HMX status response This is the maximum number of seconds to wait for a status response from the HMX. (/rspt=#, Default: 5, Optional) Polling Rate This is the rate in seconds at which to request Profile status updates from the HMX for variable types: 3, 4, and 5. (/poll=#, Default: None, Required) Connection 44 Architecture Connection to single HMX AM node This enables the configuration of the ODX Communications Protocol Settings. ODX Communications Protocol Settings User Name and Password Tells the interface to utilize the ODX communications protocol. Also provides the UserNaem and Password required to log on to the HMX AM. (/odx=<username:password>, Default: None, Required) Connection through HMX Server This enables the configuration of the HMX server settings.

51 Communications through server to HMX Data Freeway This is required if communicating through the server with HMX Data Freeway nodes. (/dfy, Default: None, Required) MX server configured with -date This is required if the MX Server was configured with the -date option. (/mxdate, Default: None, Sometimes required) Process Names Process name of the AM system which relates to the PP digits of the Location1 PI tag attribute. In this topology, there should only be one instance of this parameter in the startup file. Thus, PP in Location1 should be 01. (/proc=<processname>, Default: None, Required) HMX system number This 3-digit HMX System number is used to relate PI tags to this particular instance of the interface. It can be any value as long as it matches the last 3 digits of the Location1 tag attribute. If there are multiple instances of this interface, this number must be unique for each instance. (/mxo=sss, Default: None, Required) HMX Memory Bank Name Specify the HMX Memory Bank Name when the HMX symbol names are not unique across memory banks. (/BTI=<name>, Optional, sometimes required) Example: BTID2 HMX Process Name Specify the HMX Process Name when the HMX symbol names are not unique across HMX processes. (/LPN=<name>, Optional) Example: LPN1 There may be multiple /lpn parameters in the start-up file; they are referenced by their enumerated position, similarly to /proc. PI Interface for Measurex MXO 45

52 Startup Command File Troubleshooting 46 Logfile name This is the name and location of an auxiliary log file into which the interface will place its troubleshooting and normal message output. (/out=<filename>, Default: None, Optional) Real-time switch file This is the name and location of a file containing real-time switch settings to be sent to the interface. (/msgfl=<filename>, Default: None, Optional) Run-time directives file This parameter may be used in conjunction with the/msgfl parameter, or the path to the file with run-time directives may be included in that parameter. (/MSGDir=<filename>, Default: None, Optional) Troubleshooting Tags This is the name of a PI tag for which troubleshooting information will be printed to the interface log file. When a tag is specified, the interface will print all I/O communications and messages to PI that refer to this tag. Multiple tags can be monitored by adding a /MON="tagname" for each tag that is monitored. (/mon="<tagname>", Default: None, Optional) Turn on additional debug messages Turns on additional interface messaging. It is useful for trouble-shooting the interface and network communications. When it is set, all network messages between the interface and

53 HMX will be recorded in the interface log file. It may be set in the start-up file or in the file for runtime directives (see /msgfl). Note: This interface does not have different debug levels, as /db does not take a value. PI Interface for Measurex MXO 47

54 Startup Command File Command-line Parameters Note: The PI Universal Interface (UniInt) User Guide includes details about other command-line parameters, which may be useful. Parameter /db Optional /ec=# Optional /f=ss.## or /f=ss.##,ss.## or /f=hh:mm:ss.## or /f=hh:mm:ss.##, hh:mm:ss.## Required for reading scanbased inputs Description Turns on additional interface messaging. It is useful for troubleshooting the interface and network communications. When it is set, all network messages between the interface and HMX will be recorded in the interface log file. It may be set in the start-up file or in the file for runtime directives (see /msgfl). Note: This interface does not have different debug levels, as /db does not take a value. The first instance of the /ec parameter on the command-line is used to specify a counter number, #, for an I/O Rate point. If the # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, every interface that is running without /ec=# explicitly defined will write to the same I/O Rate point. Either explicitly define an event counter other than 1 for each instance of the interface or do not associate any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in the section called I/O Rate Point. For interfaces that run on Windows nodes, subsequent instances of the /ec parameter may be used by specific interfaces to keep track of various input or output operations. Subsequent instances of the /ec parameter can be of the form /ec*, where * is any ASCII character sequence. For example, /ecinput=10, /ecoutput=11, and /ec=12 are legitimate choices for the second, third, and fourth event counter strings. The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), seconds (SS) and sub-seconds (##). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), seconds (ss), and sub-seconds (##). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds. Each instance of the /f parameter on the command-line defines a scan class for the interface. There is no limit to the number of scan classes that can be defined. The first occurrence of the /f parameter on the command-line defines the first scan class of the interface; the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on. Two scan classes are defined in the following example: /f=00:01:00,00:00:05 /f=00:00:07 or, equivalently: /f=60,5 /f=7 The first scan class has a scanning frequency of 1 minute with an 48

55 Parameter /host=host:port Required Description offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans occur at discrete moments in time according to the formula: scan times = (reference time) + n(frequency) + offset where n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:07:05, the second scan would be at 05:08:05, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined. The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section Logging hit, missed and skipped scan in the PI Universal Interface (UniInt) User Guide for more information on skipped or missed scans. Sub-second Scan Classes Sub-second scan classes can be defined on the command-line, such as /f=0.5 /f=00:00:00.1 where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 of a second. Similarly, sub-second scan classes with sub-second offsets can be defined, such as /f=0.5,0.2 /f=1,0 Wall Clock Scheduling Scan classes that strictly adhere to wall clock scheduling are now possible. This feature is available for interfaces that run on Windows and/or UNIX. Previously, wall clock scheduling was possible, but not across daylight saving time. For example, /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight saving time), use /f=24:00:00,00:08:00,l. The,L at the end of the scan class tells UniInt to use the new wall clock scheduling algorithm. The /host parameter specifies the PI Data Archive node. Host is the IP address or the domain name of the PI Data Archive node. Port is the port number for TCP/IP communication. The port is always It is recommended to explicitly define the host and port on the command-line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults. Examples: The interface is running on a interface node, the domain name of the PI Data Archive is Marvin, and the IP address of Marvin is Valid /host parameters would be: /host=marvin /host=marvin:5450 /host= /host= :5450 PI Interface for Measurex MXO 49

56 Startup Command File Parameter /id=x Highly Recommended /intfhost=host Required /intftg=tagname Required /iostat=# Optional Default: /iostat=550 /ka=# Required /msgdir=path Optional Default: None /msgfl=filename Optional Default: None /mxrate=# Optional Default=120 /mon=tagname Optional Description The /id parameter is used to specify the interface identifier. The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See Appendix A Error and Informational Messages for more information. UniInt always uses the /id parameter in the fashion described above. Name of PI interface node connected to the HMX system. The name is used by HMX and the P interface node to display in system and error messages. Tag with value 1 or 0 if communication to HMX node is up or down, respectively. This tag is typically a digital lab tag, but can also be a numeric lab tag. It does not use the PointSource of the interface. Starting number of PI System digital state where interface-specific states are located. Rate in seconds at which the interface queries the network connection to HMX in order to verify the status. For MX Server operation, it can be set to 40 seconds. For operation with ODX, the value should be set to 5 seconds less than the value defined in the HMX configuration file IDSERVER.CFG file located in the HMX system C:\VISION directory. If this file is missing, set the Keep Alive rate to 25 seconds. This file should only be changed by certified MX personnel and requires an MX reboot to take effect. This parameter may be used in conjunction with the/msgfl parameter, or the path to the file with run-time directives may be included in that parameter. Name and location of a file containing real-time switch settings to be sent to the interface. The interface will check every 2 minutes for the existence of this file. If it exists, it will parse the file for the new switch settings contained in this file and then delete this file. Currently, this file can be used to turn trouble-shooting on or off without having to restart the interface. To turn on debugging, create a file with the specified filename and put /DB in line one column one. To turn off debugging, put /NODB in line one column one. Number of seconds to wait between checks for runtime directives. Name of a PI Tag for which troubleshooting information will be printed to the interface log file. When a tag is specified, the interface will print all I/O communications and messages to PI that refer to this tag. Multiple tags can be monitored by adding a /MON="tagname" for each tag that is monitored. If the tagname contains spaces, be sure to enclose it in quotation marks. This can be used as an alternative to the full trouble-shooting switch, /db. When /db is used, some troubleshooting information will be written for all tags; however, /MON writes some additional information. /MON does not need the /db flag to be present. 50

57 Parameter /mxinet=ip address Required /mxsym=# Optional Default: /mxsym=20 /nioto Optional /out=filename Optional /poll=# Required /ps=x Required /rspt=# Optional Default: /rspt=5 Description IP address of the HMX node to which the interface is connecting (in dot format i.e., ). If there is an MX Server, this is the IP address of the server; otherwise, it is the IP address of the AM node. Note 1: Make sure the MX configuration file also has the TCP/IP address of the PI interface node. The name of this file is: /database/host_sys.conf Note 2: Normally the MX nodes do not communicate with nodes outside their subnet. The MX node O/S does not perform routing by default. However, routing to specified IP addresses in different subnets may be possible; this should be worked out ahead of time with a Measurex professional or Honeywell tech support. Maximum number of HMX symbols to include in a single data request. Default is 20; maximum is 100. This limit does not apply to array type symbols. IO Timeout digital values, caused by temporary communication outage, will not be written to the tags. Name and location of an auxiliary log file into which the interface will place its troubleshooting and normal message output. This file rolls over daily (at 12:10 A.M.) into a new file. The new file that is created will be called filename_datetime.out where the current date and time is appended to the file name specified with /out. Be aware that this file can get very large. If this parameter is not defined, the interface will send all troubleshooting and normal message output to the PI Message Log system. # is the rate in seconds at which to request Profile status updates from HMX for variable types 3, 4, and 5. The /ps parameter specifies the point source for the interface. X is not case sensitive and can be any multiple character string. For example, /ps=p and /ps=p are equivalent. The length of X is limited to 100 characters by UniInt. X can contain any character except * and?. The point source that is assigned with the /ps parameter corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source. If the PI API version being used is earlier than 1.6.x or the PI Data Archive version is earlier than x, the PointSource is limited to a single character unless the SDK is being used. # is the maximum number of seconds to wait for status response from HMX. The default of 5 seconds is adequate for most situations. PI Interface for Measurex MXO 51

58 Startup Command File Parameter /sio Optional /sn Optional /stopstat=digstate or /stopstat /stopstat only is equivalent to /stopstat="intf Shut" Optional Default = no digital state written at shutdown. /symdly=# Optional Default: /symdly=0.5 /tmaln=# Optional /to Optional Default: /to=2 Description The /sio parameter stands for suppress initial outputs. The parameter applies only for interfaces that support outputs. If the /sio parameter is not specified, the interface will behave in the following manner. When the interface is started, the interface determines the current Snapshot value of each output point. Next, the interface writes this value to each output point. In addition, whenever an individual output point is edited while the interface is running, the interface will write the current Snapshot value to the edited output point. This behavior is suppressed if the /sio parameter is specified on the command-line. That is, outputs will not be written when the interface starts or when an output point is edited. In other words, when the /sio parameter is specified, outputs will only be written when they are explicitly triggered. The interface overrides exception reporting with snapshot reporting. This means that exception specifications are bypassed and data is put in the archive when the compression specifications are exceeded. If compression is also turned off, data is put in the archive as it is received. If /stopstat=digstate is present on the command line, then the digital state, digstate, will be written to each PI point when the interface is stopped. For a PI3 Data Archive, digstate must be in the system digital state table. UniInt will use the first occurrence of digstate found in the table. If the /stopstat parameter is present on the startup command line, then the digital state Intf Shut will be written to each PI point when the interface is stopped. If neither /stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down. Examples: /stopstat=shutdown /stopstat="intf Shut" The entire digstate value must be enclosed within double quotes when there is a space in digstate. # is the number of seconds to delay between symbol verification. This depends upon the capacity of MX AM to handle the CPUintensive symbol lookups. Default is 0.5 second. # is the maximum number of seconds allowed between data messages based upon the same MX Event before declaring a separate occurrence. This is used with unsolicited and event-driven messages. The default is for every message to be processed as a unique event. /to is a read timeout command line argument. The default timeout is 2 seconds. 52

59 Peer-to-peer Connections to Single HMX AM Node The following parameters are used in addition to the common parameters. Parameter /mxo=sss Required /odx=name:password Required /proc=process Name Required Description SSS is the 3-digit HMX System number used to relate PI tags to this particular instance of the interface. It can be any value as long as it matches the last 3 digits of the Location1 tag attribute. If there are multiple instances of this interface, this number must be unique for each instance. Tell the interface to utilize the ODX communications protocol. Also, provides the UserName and Password required to log on to the HMX AM. This name and password must be known to the HMX system. These are defined in the HMX file IDSERVER.CFG. In addition, this file defines access privileges for each UserName as FULL or PARTIAL. The FULL privilege allows reading or writing data from/to the HMX system. The PARTIAL allows only reading data from the HMX system. Example: /ODX=user0001:pass01 Process name of the AM System which relates to the PP digits of the Location1 PI tag attribute. In this topology, there should only be one instance of this parameter in the startup file. Thus, PP in Location1 should be 01. Note: The interface uses the HMX System number in Location1 to map a particular tag to a specific instance of the interface and thereby to a particular HMX AM node. Peer-to-peer Connections through HMX Server The parameters listed in the following table are used in addition to the common parameters. With this topology, a single instance of the PI MXOpen interface is communicating with only one MX Node through the MX Server. Parameter /dfy Required for HMX Data Freeway nodes. /mxdate Sometimes required /mxo=sss Required Description Required if this instance of the interface is communicating through the server with HMX Data Freeway nodes. Note: If the MX Server is communicating with both HMX Data Freeway and Application Manager nodes, use multiple interface instances and dedicate one process to communicate through the MX Server to the Data Freeway nodes and one to each Application Manager Node. Required if the MX Server was configured with the -date option. When the MX Server uses the -date option in its startup file, the MX Server will include both date and time stamps in its messages; otherwise it includes only the time. SSS is the 3-digit HMX System number used to relate PI points to this particular instance of the interface. It can be any value as long as it matches the last 3 digits of the Location1 tag attribute. If there are multiple instances of this interface, this number must be unique for each instance. PI Interface for Measurex MXO 53

60 Startup Command File Parameter /proc=process Name Required Description Use multiple /proc parameters to specify the process names of the HMX nodes connected to the MX Server. These process names should match those defined in the MX Server configuration files and should be the same for all instances of the interface communicating with this MX Server. A specific Process Name is referenced in the PP digits of Location1 by its enumerated position in the startup file. Thus, if the start-up file contains three Process Names as follows (/PROC=PM1 /PROC=COATER1 /PROC=PM2), then PM1 is Process 1 because it is the first in the list; Coater 1 is Process 2; and PM2 is Process 3, etc. Note: The interface uses the HMX System number in the Location1 attribute to map a particular point to a specific instance of the interface and thereby to a particular MX Server. The Process Number in Location1 maps a particular point to a specific MX Node attached to the MX Server. Peer-to-many Connections through HMX Server The parameters listed in the following table are used in addition to the common parameters. With this topology, a single PI MXOpen interface instance is communicating with many MX Nodes through the MX Server. Parameter /bti=hmx memory bank name Sometimes required /dfy Required for HMX Data Freeway nodes. /lpn=hmx Processor Name Sometimes required /mxdate Sometimes required /mxo=sss Required Description Specify the HMX Memory Bank Name when the HMX symbol names are not unique across memory banks. Example: BTID2 Required if this instance of the interface is communicating through the server with HMX Data Freeway nodes. Note: If the MX Server is communicating with both HMX Data Freeway and Application Manager nodes, use multiple interface instances and dedicate one process to communicate through the MX Server to the Data Freeway nodes and one to each Application Manager Node. Specify the HMX Process Name when the HMX symbol names are not unique across HMX processes. Example: LPN1 There may be multiple /lpn parameters in the start-up file; they are referenced by their enumerated position, similarly to /proc. Required if the MX Server was configured with the -date option. When the MX Server uses the -date option in its start-up file, the MX Server will include both date and time stamps in its messages; otherwise it includes only the time. SSS is the 3-digit HMX System number used to relate PI tags to this particular instance of the interface. It can be any value as long as it matches the last 3 digits of the Location1 tag attribute. If there are multiple instances of this interface, this number must be unique for each instance. 54

61 Parameter /proc=process Name Required Description Use multiple /proc parameters to specify the process names of the HMX nodes connected to the MX Server. These process names should match those defined in the MX Server configuration files and should be the same for all instances of the interface communicating with this MX Server. A specific Process Name is referenced in the PP digits of Location1 by its enumerated position in the startup file. Thus, if the start-up file contains three Process Names as follows (/PROC=PM1 /PROC=COATER1 /PROC=PM2), then PM1 is Process 1 because it is the first in the list; Coater 1 is Process 2; and PM2 is Process 3, etc. Note: The interface uses the HMX System number in Location1 to map a particular tag to a specific instance of the interface and thereby to a particular MX Server. The Process Number in Location1 maps a particular tag to a specific MX Node attached to the MX Server. PI Interface for Measurex MXO 55

62 Startup Command File Sample MXOpen.bat File The following is an example file: REM======================================================================= REM REM mxo.bat REM REM Sample startup file for the PI Interface for Measurex MXO REM REM======================================================================= REM REM OSIsoft strongly recommends using PI ICU to modify startup files. REM REM Sample command line REM MXO.exe ^ /mxdate ^ /ps=m ^ /id=1 ^ /ec=7 ^ /sn ^ /out=c:\mxo\mxo.out ^ /host=pltal1:545 ^ /intfhost=namebywhichmxlistsus ^ /mxo=1 ^ /mxinet= ^ /ka=20 ^ /rspt=30 ^ /poll=120 ^ /proc=gppm6 ^ /iostat=-700 ^ /f=00:00:12 /f=00:00:05 /f=00:00:31 REM REM End of mxo.bat File 56

63 Chapter 9. Interface Node Clock Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes daylight saving time, check the Automatically adjust clock for daylight saving changes box. For example, In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is, C:> set Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment Variables button under the Advanced tab, and remove TZ from the list of environment variables. PI Interface for Measurex MXO 57

64

65 Chapter 10. Security Windows The PI Firewall Database and the PI Trust Database must be configured so that the interface is allowed to write data to the PI Data Archive. The Trust Database, which is maintained by the PI Base Subsystem, replaces the Proxy Database used prior to PI Data Archive version 3.3. The PI Trust Database maintains all the functionality of the proxy mechanism while being more secure. See Manage Interface Authentication with PI Trusts in the chapter Manage Security of the PI Server Introduction to System Management Guide. If the interface cannot write data to the PI Data Archive because it has insufficient privileges, a error will be reported in the log file. If the interface cannot send data to a PI2 Data Archive, it writes a -999 error. See the section Appendix A: Error and Informational Messages for additional information on error messaging. Authentication Interface instances are usually configured to run as Windows services. Since a service runs in a non-interactive context, a PI trust is required to authenticate the interface service to the PI Data Archive. A PI trust is associated with one PI identity, PI user, or PI group. When an interface successfully authenticates through a trust, the interface is granted the access rights for the associated identity, user, or group. OSIsoft discourages using highly-privileged identities, users, or groups in PI trusts for interfaces. Security Note: Avoid using the piadmin super-user and piadmins group. The recommended best practice for PI Data Archive security is to create an identity, user, or group that has only the access rights which are necessary for the interface to operate. I Data Archive v3.3 and Later Security Configuration using Trust Editor The Trust Editor plug-in for PI System Management Tools edits the PI trust table. See the Manage Interface Authentication with PI Trusts section in the PI Server Introduction to System Management manual for more details on security configuration. PI Interface for Measurex MXO 59

66 Security Security configuration using piconfig For PI Data Archive v3.3 and higher, the following example demonstrates how to edit the PI trust table with piconfig: C:\PI\adm> Trust,IPAddr,NetMask,PIUser For the preceding example, Trust: An arbitrary name for the trust table entry; in the above example, a_trust_name IPAddr: the IP address of the computer running the interface; in the above example, NetMask: the network mask; specifies an exact match with IPAddr PIUser: the PI identity, user, or group the interface is entrusted as; in the example, trust_identity PI Data Archive v3.2 For PI Data Archive v3.2, the following example demonstrates how to edit the PI Proxy table: C:\PI\adm> host,proxyaccount In place of piapimachine, put the name of the interface node as it is seen by the PI Data Archive. Authorization For an interface instance to start and write data to PI points, the following permissions must be granted to the PI identity, user, or group in the PI trust that authenticates the interface instance. Database Security Permission Notes PIPOINT r Point Database Permission Notes PtSecurity r DataSecurity r,w Unbuffered r Buffered (the buffering application requires r,w for the interface points) 60

67 The permissions in the preceding table must be granted for every PI point that is configured for the interface instance. Observe that buffering on the interface node is significant to PI point permissions. When the interface instance is running on an unbuffered interface node, the interface instance sends PI point updates directly to the PI Data Archive. Therefore, the DataSecurity attribute must grant write access to the PI identity, user, or group in the PI trust that authenticates the interface instance. When the interface instance is running on a buffered interface node, the interface instance sends PI point updates to the local buffering application, which relays the PI point updates to the PI Data Archive. The buffering application is a separate client to the PI Data Archive and, therefore, authenticates independently of the interface instances. The DataSecurity attribute must grant write access to the PI identity, user, or group in the PI trust that authenticates the buffering application. PI Interface for Measurex MXO 61

68

69 Chapter 11. Starting / Stopping the Interface This section describes starting and stopping the interface once it has been installed as a service. Starting Interface as a Service If the interface was installed as service, it can be started from PI ICU, the Services control panel or with the command: mxo.exe /start [ /serviceid id ] To start the interface service with PI ICU, use the button on the PI ICU toolbar. A message will inform the user of the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated.bat file. Verify that the root name of the.bat file and the.exe file are the same, and that the.bat file and the.exe file are in the same directory. Further troubleshooting of services might require consulting the log file, Windows Event Viewer, or other sources of log messages. See the section Appendix A: Error and Informational Messages for additional information. Stopping Interface Running as a Service If the interface was installed as service, it can be stopped at any time from PI ICU, the Services control panel or with the command: mxo.exe /stop [ /serviceid id ] To stop the interface service with PI ICU, use the The service can be removed by PI ICU or with the command: mxo.exe /remove [ /serviceid id ] button on the PI ICU toolbar. PI Interface for Measurex MXO 63

70

71 Chapter 12. Buffering This interface is not compatible with OSIsoft s standard buffering mechanisms, PI API Buffer Server (Bufserv) and the PI Buffer Subsystem (PIBufss). Instead, the interface Buffering refers to an interface node s ability to temporarily store the data that interfaces collect and to forward these data to the appropriate PI Data Archives. OSIsoft strongly recommends that you enable buffering on your interface nodes. Otherwise, if the interface node stops communicating with the PI Data Archive, you lose the data that your interfaces collect. The PI SDK installation kit installs two buffering applications: the PI Buffer Subsystem (PIBufss) and the PI API Buffer Server (Bufserv). PIBufss and Bufserv are mutually exclusive; that is, on a particular computer, you can run only one of them at any given time. If you have PI Data Archives that are part of a collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Data Archives in a collective. (Bufserv also supports n-way buffering, but OSIsoft recommends that you run PIBufss instead.) Which Buffering Application to Use You should use PIBufss whenever possible because it offers better throughput than Bufserv. In addition, if the interfaces on an interface node are sending data to a PI Data Archive collective, PIBufss guarantees identical data in the archive records of all the PI Data Archives that are part of that collective. You can use PIBufss only under the following conditions: the PI Data Archive version is at least x; and all of the interfaces running on the interface node send data to the same PI Data Archive or to the same collective. If any of the following scenarios apply, you must use Bufserv: the PI Data Archive version is earlier than x; or the interface node runs multiple interfaces, and these interfaces send data to multiple PI Data Archives that are not part of a single collective. If an interface node runs multiple interfaces, and these interfaces send data to two or more PI Data Archive collectives, then neither PIBufss nor Bufserv is appropriate. The reason is that PIBufss and Bufserv can buffer data only to a single collective. If you need to buffer to more than one collective, you need to use two or more interface nodes to run your interfaces. It is technically possible to run Bufserv on the PI Server node. However, OSIsoft does not recommend this configuration. PI Interface for Measurex MXO 65

72 Buffering How Buffering Works A complete technical description of PIBufss and Bufserv is beyond the scope of this document. However, the following paragraphs provide some insights on how buffering works. When an interface node has buffering enabled, the buffering application (PIBufss or Bufserv) connects to the PI Data Archive. It also creates shared memory storage. When an interface program makes a PI API function call that writes data to the PI Data Archive (for example, pisn_sendexceptionqx()), the PI API checks whether buffering is enabled. If it is, these data writing functions do not send the interface data to the PI Data Archive. Instead, they write the data to the shared memory storage that the buffering application created. The buffering application (either Bufserv or PIBufss) in turn reads the data in shared memory, and if a connection to the PI Data Archive exists, sends the data to the PI Data Archive; or if there is no connection to the PI Data Archive, continues to store the data in shared memory (if shared memory storage is available) or writes the data to disk (if shared memory storage is full). When the buffering application re-establishes connection to the PI Data Archive, it writes to the PI Data Archive the interface data contained in both shared memory storage and disk. (Before sending data to the PI Data Archive, PIBufss performs further tasks such as data validation and data compression, but the description of these tasks is beyond the scope of this document.) When PIBufss writes interface data to disk, it writes to multiple files. The names of these buffering files are PIBUFQ_*.DAT. When Bufserv writes interface data to disk, it writes to a single file. The name of its buffering file is APIBUF.DAT. As a previous paragraph indicates, PIBufss and Bufserv create shared memory storage at startup. These memory buffers must be large enough to accommodate the data that an interface collects during a single scan. Otherwise, the interface may fail to write all its collected data to the memory buffers, resulting in data loss. The buffering configuration section of this chapter provides guidelines for sizing these memory buffers. When buffering is enabled, it affects the entire interface node. That is, you do not have a configuration where the buffering application buffers data for one interface running on an interface node but not for another interface running on the same interface node. Buffering and PI Data Archive Security After you enable buffering, it is the buffering application and not the interface program that writes data to the PI Data Archive. If the PI Data Archive s trust table contains a trust entry that allows all applications on an interface node to write data, then the buffering application is able to write data to the PI Data Archive. 66

73 However, if the PI Data Archive contains an interface-specific PI trust entry that allows a particular interface program to write data, you must have a PI trust entry specific to buffering. The following are the appropriate entries for the Application Name field of a PI trust entry: Buffering Application PI Buffer Subsystem PI API Buffer Server Application Name field for PI Trust PIBufss.exe APIBE (if the PI API is using 4 character process names) APIBUF (if the PI API is using 8 character process names) To use a process name greater than 4 characters in length for a trust application name, use the LONGAPPNAME=1 in the PIClient.ini file. See the Security chapter for additional information. Enabling Buffering on an Interface Node with the ICU The ICU allows you to select either PIBufss or Bufserv as the buffering application for your interface node. Run the ICU and select Tools > Buffering. Choose Buffer Type To select PIBufss as the buffering application, choose Enable buffering with PI Buffer Subsystem. To select Bufserv as the buffering application, choose Enable buffering with API Buffer Server. If a warning message such as the following appears, click Yes. PI Interface for Measurex MXO 67

74 Buffering Buffering Settings There are a number of settings that affect the operation of PIBufss and Bufserv. The Buffering Settings section allows you to set these parameters. If you do not enter values for these parameters, PIBufss and Bufserv use default values. PIBufss For PIBufss, the paragraphs below describe the settings that may require user intervention. Please contact OSIsoft Technical Support for assistance in further optimizing these and all remaining settings. Primary and Secondary Memory Buffer Size (Bytes) This is a key parameter for buffering performance. The sum of these two memory buffer sizes must be large enough to accommodate the data that an interface collects during a single scan. A typical event with a float32 point type requires about 25 bytes. If an interface writes data to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of data in one scan. As a result, the size of each memory buffer should be 62,500 bytes. The default value of these memory buffers is 32,768 bytes. OSIsoft recommends that these two memory buffer sizes should be increased to the maximum of for the best buffering performance. 68

75 Send rate (milliseconds) Send rate is the time in milliseconds that PIBufss waits between sending up to the Maximum transfer objects (described below) to the PI Data Archive. The default value is 100. The valid range is 0 to 2,000,000. Maximum transfer objects Maximum transfer objects is the maximum number of events that PIBufss sends between each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000. Event Queue File Size (Mbytes) This is the size of the event queue files. PIBufss stores the buffered data to these files. The default value is 32. The range is 8 to MB (up to a maximum of 128 GB). Please see the section entitled "Queue File Sizing" in the PIBufss.chm file for details on how to appropriately size the event queue files. Event Queue Path This is the location of the event queue file. The default value is [PIHOME]\DAT. For optimal performance and reliability, OSIsoft recommends that you place the PIBufss event queue files on a different drive/controller from the system drive and the drive with the Windows paging file. (By default, these two drives are the same.) Bufserv For Bufserv, the paragraphs below describe the settings that may require user intervention. Please contact OSIsoft Technical Support for assistance in further optimizing these and all remaining settings. PI Interface for Measurex MXO 69

76 Buffering Maximum buffer file size (KB) This is the maximum size of the buffer file ([PIHOME]\DAT\APIBUF.DAT). When Bufserv cannot communicate with the PI Data Archive, it writes and appends data to this file. When the buffer file reaches this maximum size, Bufserv discards data. The default value is 2,000,000 KB, which is about 2 GB. The range is from 1 to 2,000,000. Primary and Secondary Memory Buffer Size (Bytes) This is a key parameter for buffering performance. The sum of these two memory buffer sizes must be large enough to accommodate the data that an interface collects during a single scan. A typical event with a float32 point type requires about 25 bytes. If an interface writes data to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of data in one scan. As a result, the size of each memory buffer should be 62,500 bytes. The default value of these memory buffers is 32,768 bytes. OSIsoft recommends that these two memory buffer sizes should be increased to the maximum of for the best buffering performance. Send rate (milliseconds) Send rate is the time in milliseconds that Bufserv waits between sending up to the Maximum transfer objects (described below) to the PI Data Archive. The default value is 100. The valid range is 0 to 2,000,000. Maximum transfer objects Max transfer objects is the maximum number of events that Bufserv sends between each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000. Buffered Servers The Buffered Servers section allows you to define the PI Data Archives or PI Data Archive collective that the buffering application writes data. PIBufss PIBufss buffers data only to a single PI Data Archive or a single PI Data Archive collective. Select the PI Data Archive or the collective from the Buffering to collective/server drop down list box. The following figure shows that PIBufss is configured to write data to a standalone PI Data Archive named starlight. Notice that the Replicate data to all collective member nodes check box is not available because this PI Data Archive is not part of a collective. (PIBufss automatically detects whether a PI Data Archive is part of a collective.) 70

77 The following figure shows that PIBufss is configured to write data to a PI Data Archive collective named admiral. By default, PIBufss replicates data to all collective members. That is, it provides n-way buffering. You can override this option by clearing the Replicate data to all collective member nodes check box. Then, select (or clear) the collective members as desired. PI Interface for Measurex MXO 71

78 Buffering Bufserv Bufserv buffers data to a standalone PI Data Archive or to multiple standalone PI Data Archives. (If you want to buffer to multiple PI Data Archives that are part of a collective, you should use PIBufss.) If the PI Data Archive to which you want Bufserv to buffer data is not in the Server list, enter its name in the Add a server box and click the Add Server button. This PI Data Archive name must be identical to the API Hostname entry: The following screen shows that Bufserv is configured to write to a standalone PI Data Archive named etamp390. You use this configuration when all the interfaces on the interface node write data to etamp390. The following screen shows that Bufserv is configured to write to two standalone PI Data Archives, one named etamp390 and the other one named starlight. You use this configuration when some of the interfaces on the interface node write data to etamp390 and some write to starlight. 72

79 Installing Buffering as a Service Both the PIBufss and Bufserv applications run as a Windows Service. PI Buffer Subsystem Service Use the PI Buffer Subsystem Service page to configure PIBufss as a Service. This page also allows you to start and stop the PIBufss service. PIBufss does not require the logon rights of the local administrator account. It is sufficient to use the LocalSystem account instead. Although the screen below shows asterisks for the LocalSystem password, this account does not have a password. PI Interface for Measurex MXO 73

80 Buffering API Buffer Server Service Use the API Buffer Server Service page to configure Bufserv as a service. This page also allows you to start and stop the Bufserv service Bufserv version 1.6 and later does not require the logon rights of the local administrator account. It is sufficient to use the LocalSystem account instead. Although the screen below shows asterisks for the LocalSystem password, this account does not have a password. 74

81 PI Interface for Measurex MXO 75

82

83 Chapter 13. Interface Diagnostics Configuration The PI Point Configuration chapter provides information on building PI points for collecting data from the device. This chapter describes the configuration of points related to interface diagnostics. Note: The procedure for configuring interface diagnostics is not specific to this interface. Thus, for simplicity, the instructions and screenshots that follow refer to an interface named ModbusE. Some of the points that follow refer to a performance summary interval. This interval is 8 hours by default. You can change this parameter via the Scan performance summary box in the UniInt Debug parameter category page: Scan Class Performance Points This interface does not support Scan Class Performance Points. Performance Counters Points This interface does not support Performance Counters Points. PI Interface for Measurex MXO 77

84 Interface Diagnostics Configuration Interface Health Monitoring Points This interface does not support interface Health Montoring Points. I/O Rate Point An I/O Rate point measures the rate at which the interface writes data to its input points. The value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the interface sends to the PI Data Archive. When the interface starts, it writes 0 to the I/O Rate point. After running for ten minutes, the interface writes the I/O Rate value. The interface continues to write a value every 10 minutes. When the interface stops, it writes 0. The ICU allows you to create one I/O Rate point for each copy of this interface. Select this interface from the Interface list, click IO Rate in the parameter category pane, and select Enable IORates for this interface. As the preceding figure shows, the ICU suggests an Event Counter number and a Tagname for the I/O Rate point. Click the Save button to save the settings and create the I/O Rate point. Click the Apply button to apply the changes to this copy of the interface. You need to restart the interface in order for it to write a value to the newly created I/O Rate point. Restart the interface by clicking the Restart button: 78 (The reason you need to restart the interface is that the PointSource attribute of an I/O Rate point is Lab.) To confirm that the interface recognizes the I/O Rate point, look in the log for a message such as: PI-ModBus 1> IORATE: tag sy.io.etamp390.modbuse1 configured.

85 To see the I/O Rate point s current value (snapshot), click the Refresh snapshot button: Enable IORates for this Interface The Enable IORates for this interface check box enables or disables I/O Rates for the current interface. To disable I/O Rates for the selected interface, clear this box. To enable I/O Rates for the selected interface, select this box. Event Counter The Event Counter correlates a point specified in the iorates.dat file with this copy of the interface. The command-line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file. Tagname The tag name listed in the Tagname box is the name of the I/O Rate point. Tag Status The Tag Status box indicates whether the I/O Rate point exists in the PI Data Archive. The possible states are: In File Created This status indicates that the point exist in the PI Data Archive Not Created This status indicates that the point does not yet exist in the PI Data Archive Deleted This status indicates that the point has just been deleted Unknown This status indicates that the PI ICU is not able to access the PI Data Archive The In File box indicates whether the I/O Rate tag in the Tagname box and the number in the Event Counter box are in the IORates.dat file. The possible states are: Yes This status indicates that the tag name and event counter are in the IORates.dat file No This status indicates that the tag name and event counter are not in the IORates.dat file PI Interface for Measurex MXO 79

86 Interface Diagnostics Configuration Snapshot The Snapshot column holds the snapshot value of the I/O Rate point, if the I/O Rate point exists in the PI Data Archive. The Snapshot box is updated when the IORate page is selected and when the interface is first loaded. Create/Save Create the suggested I/O Rate point with the tag name indicated in the Tagname box. Or, save any changes for the tag name indicated in the Tagname box. Delete Delete the I/O Rate point listed in the Tagname box. Rename Change the tag name for the I/O Rate point listed in the Tagname box. Add to File Add the tag name to the IORates.dat file with the event counter listed in the Event Counter box. Search Search the PI Data Archive for a previously defined I/O Rate point. Interface Status Point The PI Interface Status Utility (ISU) alerts you when an interface is not currently writing data to the PI Data Archive. This situation commonly occurs if the monitored interface is running on an interface node, but the interface node cannot communicate with the PI Data Archive; or the monitored interface is not running, but it failed to write at shutdown a system state such as Intf Shut. The ISU works by periodically looking at the timestamp of a watchdog point. The watchdog point is a point whose value a monitored interface (such as this interface) frequently updates. The watchdog point has its ExcDev, ExcMin, and ExcMax point attributes set to 0. So, a nonchanging timestamp for the watchdog point indicates that the monitored interface is not writing data. Please see the Interface Status Utility Interface for complete information on using the ISU. PI Interface Status Utility Interface runs only on a PI Data Archive node. If you have used the ICU to configure the PI Interface Status Utility Interface on the PI Data Archive node, the ICU allows you to create the appropriate ISU point. Select this interface from the Interface list and click Interface Status in the parameter category pane. Right-click on a point in the Interface Status Utility Tag Definition list to open the shortcut menu: 80

87 Click Create to create the ISU point. Use the Tag Search button to select a watchdog point. (Recall that the watchdog point is one of the points for which this interface collects data.) Select a Scan frequency from the list box. This Scan frequency is the interval at which the ISU monitors the watchdog point. For optimal performance, choose a Scan frequency that is less frequent than the majority of the scan rates for this interface s points. For example, if this interface scans most of its points every 30 seconds, choose a Scan frequency of 60 seconds. If this interface scans most of its points every second, choose a Scan frequency of 10 seconds. If the Tag Status indicates that the ISU point is Incorrect, right-click to open the shortcut menu and select Correct. Note: The PI Interface Status Utility Interface and not this interface is responsible for updating the ISU point. So, make sure that the PI Interface Status Utility Interface is running correctly. PI Interface for Measurex MXO 81

88

89 Appendix A. Error and Informational Messages A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id parameter on the startup command-line. Message Logs The location of the message log depends upon the platform on which the interface is running. For more information about logs for interfaces running on Windows, see UniInt Interface Message Logging for UniInt x and later Interfaces or knowledge base article 401 on the OSIsoft technical support web site. Messages are written to the log file at the following times. When the interface starts, many informational messages are written to the log. These messages include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points. As the interface loads points, messages are sent to the log if there are any problems with the configuration of the points. If the UniInt /dbuniint parameter is found in the command-line, then various informational messages are written to the log file. Error Messages The major kinds of messages that could appear in the log file include Error Modes, Fatal Error Messages, Link Status Messages, and Tag Configuration Messages. The messages have the following format: <Interface Name> <Subroutine Name> Message. Error Modes Undefined Symbols When the interface is communicating with a HMX AM node, it can detect if a PI point references an undefined HMX symbol. If the symbol name is accurate, define it on the HMX system. To force the PI System to be respond to this change, edit the PI point on the PI Interface for Measurex MXO 83

90 Error and Informational Messages PI Data Archive using the Point Edit display (without making an actual change) or restart the interface. A simple way to locate them in the log file is to use the SEARCH command on the log file for the string undefined. Search can operate on a file while the interface process locks it. Connections The interface checks the integrity of the communications connection with the HMX MX Server or ODX every Keep Alive rate seconds (/KA). If the interface does not receive a response to its message, it executes the routine DoMLIShutdown which marks all interface tags as I/O Timeout. The interface then attempts to re-establish the connection with HMX. The interface prints a message to the MXO.OUT log file whenever there is a status change to the connection. Incomplete Messages Occasionally, the HMX sends an incomplete message to the PI MXOpen interface. This may occur with extremely long messages (usually over 8000 bytes) when the HMX system breaks the message into blocks of 4096 bytes. HMX may send the first and second blocks but not the third, etc. This may happen if the HMX system does not acknowledge rapidly enough (usually within 2 seconds) from the TCP/IP System software layer. The causes of these timing glitches can be one of the following: an extremely busy network a network with some hardware problems, or a very busy Host. The symptoms of this type of problem appear in the archive and/or in interface log file as follows: I/O Timeout status occurs every now and then in the archive for the interface tags. The interface log contains messages similar to Didn t Get Whole Message or Missing Func_ID. The interface log contains messages similar to Missing Data or Bad Data Block. In addition, the archive shows the status Missing Data for the interface tags. When the above conditions occur, the interface log shows that the interface executed the routine DoMLIShutdown followed by reconnection to the HMX. Loss of Data From One of Several Nodes When the interface is used in a Peer-to-many Configuration in which the MX Server is connected to Data Freeway nodes, the shutdown of single Data Freeway nodes can cause the loss of interface data from other nodes. If this occurs, it is suggested to reconfigure PI tag and interface setup to utilize the Peer-to-peer configuration through the MX Server. 84

91 Missing HMX Events Occasionally, data triggered by HMX events can be missing. This is caused when the MX System is either too busy to pick up the event or the event does not last long enough in the HMX system. The HMX engineer should analyze and fix the problem. Fatal Error Messages These are messages that are recorded before the interface shuts itself down. When the interface shuts itself down, it is designed to mark all of the points handled by the interface with the IOStatus of I/O Timeout. The interface shuts itself down in the event of memory allocation failures, illegal pointers, or grossly uninterpretable messages received from the HMX systems. Take the following action: Restart the interface Table of fatal error messages <BuildIOMsgList> <TListAddNode> Overflow TList max size 10000: HALT The most likely cause of the interface exiting is due to solicited tags, even if there is only 1 solicited tag configured for the interface. If that 1 solicited tag is being scanned too quickly (e.g. a 1 second scan class), then the interface may eventually fall behind causing the interface to exit. The interface appears to be coded correctly for unsolicited tags, which means that requests cannot build up for unsolicited tags even if there are many more unsolicited tags for the interface than solicited tags (see PLI 5567OSI8). PI Interface for Measurex MXO 85

92 Error and Informational Messages Link Status Messages The following messages might indicate overloaded Windows or HMX CPU s, TCP/IP problems or keep alive rate that is too slow. <DoReportMLIStatus> Disconnected: Can t talk to MX ODX <DoReportMLIStatus> Lost Socket Connection to MX <DoReportMLIStatus> No Keep Alive Response from MX ODX/Server <DoHandleMLIStatus> DoHandleLogOn: Can t Wake Up ODX/Server <DoVerifyMXDataSymNode> NO ODX/Server response to Symbol Request: Reinit Interface <DoBuildInputMsgQueue> Not receiving complete messages from Peer <DoSendOutputMsg> Lost IOConnection The following messages are logged when they represent a change from the past condition. <DoReportMLIStatus> Socket Connected to MX <DoReportMLIStatus> Logged on to MX Server/ODX <DoReportMLIStatus> Getting Keep Alive from MX Server/ODX The following message indicates that there was a problem with a previously received message. The interface is trying to start over again and reinitialize. If this occurs frequently, it probably indicates a TCP/IP problem. <DoHandleMsgList> Full or Partial Reinit is requested Tag Configuration Messages HMX symbol in the PI Instrument Tag field does not follow the proper syntax for a profilerelated variable: <IsGoodProfileSetUp> MX symbol %s doesn t contain a legal 3 char sensor id <IsGoodProfileSetUp> MX symbol %s doesn t contain a legal scanner number PI event specified for this tag does not exist. <GetEventNumber> Warning, event tag %s does not exist, pt %s: Can t get event number <load_dev_structure> Check zeros and oohs in /T of Extended Descriptor <load_dev_structure> Check zeros and oohs in /V of Extended Descriptor HMX System number specified for this tag (part of the location 1 parameter) does not match the system number given in this interface s MXO.COM start-up file (s/u = startup). <load_dev_structure> Tag s MxOpen Sys # doesn t match s/u parameter Variable type or Data type specified which is out of bounds. <load_dev_structure> Invalid Var Type <load_dev_structure> Invalid Data Type Array element number was specified for a single valued variable. <load_dev_structure> VarType:Sngl: Invalid Array Elem # Invalid Array element number was specified for this type of array or profile. <load_dev_structure> Invalid Array Elem # Value should be 1 or 0. <load_dev_structure> Invalid HMX Trigger Time <load_dev_structure> Invalid Input/Output flag 86

93 Tag refers to a LPN list number that was not defined in startup parameters. <load_dev_structure> Unknown LPN List # Tag refers to a BTI list number that was not defined in startup parameters. <load_dev_structure> Unknown BTI List # Full HMX symbol representation (i.e., including LPN and BTI) is not allowed in PI Tag Instrument name. <load_dev_structure> Explicit LPNx\BTIxx not allowed in Instrument Name for PI Tag <load_dev_structure> Explicit LPNx/BTIxx not allowed in MX Event Symbol for PI Tag Explicit LPNx/BTIxx not allowed in MX Validity Symbol for PI Tag Instrument name has non-alphanumeric characters (i.e., no embedded blanks are allowed) Only _, $, 0-9, a- Z, and. are allowed characters. <load_dev_structure> Illegal Chars in Instrument Name for PI Tag <load_dev_structure> Illegal Chars in MX Event Symbol for PI Tag <load_dev_structure> Illegal Chars in MX Validity Symbol for PI Tag Output point requires a HMX Symbol in the Instrument Tag field. <load_dev_structure> Invalid Output Pt: Need Instrument Symbol for PI tag Items not allowed with Output points. <load_dev_structure> Invalid Output Pt: Arrays not supported for PI tag <load_dev_structure> Invalid Output Pt: MX Trigger Rates not allowed for PI tag <load_dev_structure> Invalid Output Pt: MX Trigger Symbols not allowed for PI tag <load_dev_structure> Invalid Output Pt: MX Validity Symbol not allowed for PI tag <load_dev_structure> Invalid Output Pt: PI Event Tags are not allowed for PI tag <load_dev_structure> Invalid Output Pt:\n\tPI Scan Group not allowed for PI tag Input point configuration errors. <load_dev_structure> Invalid Input Pt:\n\tNeeds Instrument Symbol for PI tag <load_dev_structure> Invalid Input Pt:\n\tPI Src Pt not allowed for PI Input tags: Tag <load_dev_structure> Invalid Input Pt:\n\tPI Src Pt not allowed for PI Input tags: Tag Solicited Input point configuration errors. <load_dev_structure> Invalid Input Pt:\n\tPI Src Pt not allowed for PI Input tags: Tag <load_dev_structure> Invalid Solicited Input Pt:\n\tBad PI event tag %s for PI tag <load_dev_structure> Invalid Solicited Input Pt:\n\tPI Scan Group or Event reqd for PI tag Unsolicited Input point configuration errors. <load_dev_structure> Invalid UNSOL Input Pt:\n\tMX Trigger (event or time) required for PI tag <load_dev_structure> Invalid UNSOL Input Pt:\n\tOnly 1 MX Trigger Type (event or time) allowed for PI tag <load_dev_structure> Invalid UNSOL Input Pt:\n\tPI Event or Scan Group not allowed for PI tag. PI Interface for Measurex MXO 87

94 Error and Informational Messages System Errors and PI Errors System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers. Error Descriptions Descriptions of system and PI errors can be obtained with the pidiag utility: \PI\adm\pidiag /e error_number 88

95 Appendix B. PI SDK Options To access the PI SDK settings for this interface, select this interface from the Interface list and click UniInt PI SDK in the parameter category pane. Disable PI SDK Select Disable PI SDK to tell the interface not to use the PI SDK. If you want to run the interface in disconnected startup mode, you must choose this option. The command line equivalent for this option is /pisdk=0. Use the Interface s default setting This selection has no effect on whether the interface uses the PI SDK. However, you must not choose this option if you want to run the interface in disconnected startup mode. Enable PI SDK Select Enable PI SDK to tell the interface to use the PI SDK. Choose this option if the PI Data Archive version is earlier than x or the PI API is earlier than , and you want to use extended lengths for the Tag, Descriptor, ExDesc, InstrumentTag, or PointSource point attributes. The maximum lengths for these attributes are: Attribute Enable the Interface to use the PI SDK Tag Descriptor ExDesc InstrumentTag PointSource PI Data Archive earlier than x or PI API earlier than , without the use of the PI SDK However, if you want to run the interface in disconnected startup mode, you must not choose this option. The command line equivalent for this option is /pisdk=1. PI Interface for Measurex MXO 89