PI Interface for RDBMS User Guide

Transcription

1 PI Interface for RDBMS 3.22 User Guide

2 OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA USA Tel: (01) Fax: (01) Web: PI Interface for RDBMS 3.22 User Guide 2016 by 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, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services, OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API, PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Coresight, PI Data Archive, PI DataLink, PI DataLink Server, PI Developer s Club, PI Integrator for Business Analytics, PI Interfaces, PI JDBC driver, PI Manual Logger, PI Notifications, PI ODBC, PI OLEDB Enterprise, PI OLEDB Provider, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI Visualization Suite, PI Web API, PI Web Services, and RLINK 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. Version: 3.22 Published: June

3 Contents Introduction to PI Interface for RDBMS...1 Reference manuals... 1 Supported operating systems...1 Supported features... 2 Configuration diagram... 4 Principles of operation for RDBMS... 7 Loss of connectivity to RDBMS...8 Loss of connectivity to PI Server...8 Installation checklist... 9 Data collection steps... 9 Interface diagnostics (optional)...11 Advanced interface features (optional) Installation instructions Name conventions and requirements Interface directories...13 PIHOME Directory Tree PIHOME64 Directory Tree Interface Installation Directory Interface installation procedure Silent Installation Procedure PI trust for interface authentication Install Interface as Windows service Install interface service with PI Interface Configuration Utility (ICU) Install the interface service manually PI Point configuration...21 Point attributes Tag (PI point name) PointSource (point source) PointType (data type)...22 Location1 (interface instance)...22 Location2 (first row or all rows)...22 Location3 (distribution strategy)...22 Location4 (scan class) Location5 for RDBMS (data archiving and history recovery)...23 InstrumentTag (SQL query file) ExDesc (extended descriptor) SourceTag Scan...27 Shutdown DataSecurity PtSecurity ExcMax ExcMin and ExcDev (exception processing) Output Points...28 Output point whitelist PI Interface for RDBMS 3.22 User Guide iii

4 Contents Specify SQL queries...31 Query execution Stored procedures Checking query execution results...32 Checking whether tags are updated Placeholders for replaceable parameters Timestamp, value, status, and annotation placeholders definitions PI point data placeholders...35 Placeholder data types...37 Specifying result columns in SELECT statements Fixed-position result columns Aliased result columns Data type compatibility Handling NULLs Input tag and status mapping Timestamps Questionable flag Annotations Input processing: updating PI tags from an RDBMS Approaches to data retrieval (distribution strategies) Updating a single tag...45 Update a predetermined set of tags (tag groups) Reading target tag names from the database (distribution) Process only the most recent values Verify successful data distribution Update from multi-value rows containing name of target points (RxC)...49 Output processing: updating an RDBMS with PI data...51 Insert a row for a single PI point value whenever the source tag snapshot value changes Write multiple PI values to a single row in a timely manner...52 Recovering historical data...53 Input Recovery: RDBMS values to PI Data Archive Output recovery: PI Archive values to RDBMS Specify the recovery interval and step size in ICU Startup command file for PI Interface for RDBMS Configure the RDBMS interface with PI ICU Startup parameters tab for PI Interface for RDBMS File Locations DSN Settings Successful - Status Range Bad Input - Status Range Recovery parameters tab for PI Interface for RDBMS Recovery Mode...61 Input Processing Output Processing...62 Optional parameters tab for PI Interface for RDBMS Debug parameters tab for PI Interface for RDBMS iv PI Interface for RDBMS 3.22 User Guide

5 Contents Command line parameters for PI Interface for RDBMS Sample RDBMSPI.bat file Specific considerations for PI Interface for RDBMS...73 Oracle Microsoft SQL Server SQL examples for PI Interface for RDBMS SQL examples Example 1: Update a single tag with single value using static key matching Example 2: Update a single tag with most recent values from database...76 Example 3: Update three tags from a single row (group distribution)...77 Example 4: Update tags from more rows in table since last scan (distribution by tagname)...78 Example 5: Update tags from more rows in table reading the last hour each scan (distribution by alias) with the /RBO start-up param. set Example 6: Update tags from more rows in table considering just the newer timestamps since the last scan (distribution by alias) without the /RBO start-up parameter set Example 7: Update tags from more rows in table marking the already-read rows (distribution by alias) Example 8: Update points from more rows and columns (RxC row by column distribution using aliases) with SELECT list columns renamed Example 9: Single input with PI annotations Example 10: Single input with questionable flag Example 11: Event-based input Example 12: Event driven outputs to an RDBMS table Example 13: Scan based outputs to an RDBMS table Example 14: Multi-statement query Example 15: Stored procedure call Record PI Point database changes...89 Error and informational messages for PI Interface for RDBMS PI message logs for PI Interface for RDBMS Interface-specific output file for PI Interface for RDBMS...91 PI SDK options...93 Disable PI SDK...93 Use the Interface's default setting Enable PI SDK...93 Glossary Technical support and other resources...99 PI Interface for RDBMS 3.22 User Guide v

6 Contents vi PI Interface for RDBMS 3.22 User Guide

7 Introduction to PI Interface for RDBMS The PI Interface for Relational Databases enables you to transfer data between the PI Data Archive and any relational database management system (RDBMS) that supports Open Database Connectivity (ODBC) drivers. The interface runs on Microsoft Windows operating systems and can connect to any PI Server node available on the network. To read and write data, you define SQL queries in the ExDesc attribute of a PI tag or in text files. The interface provides the following capabilities: Update PI tags from data in an RDBMS Update an RDMBS with PI tag data Record changes to PI tag attributes in an RDBMS Reference manuals 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) RDBMS interface quick-start in the OSIsoft Knowledge Base YouTube videos in the OSIsoft Learning Channel Database vendor's ODBC driver manual Microsoft ODBC Programmer's Reference Supported operating systems Platforms: (32-bit or 64-bit) Windows Vista Windows 2008 and Windows 2008 R2 Server Windows 7 Windows 8 and 8.1 Windows 2012 Server Windows 10 PI Interface for RDBMS 3.22 User Guide 1

8 Introduction to PI Interface for RDBMS Supported features Feature Auto Creates PI Points Point Builder Utility ICU Control Support PI Point Types Float16 / Float32 / Float64 / Int16 / Int32 / Digital / String / Timestamp Sub-second Timestamps Sub-second Scan Classes Automatically Incorporates PIPoint Attribute Changes Exception Reporting Outputs from PI Data Archive *Read only interface available Inputs to PI Data Archive *Questionable Bit Support *PI Annotations Support Multi-character PointSource Maximum Point Count No No Yes Yes Yes Yes Yes Yes (event-based and scan-based) No Scan-based, unsolicited, and event points Yes Yes Yes Unlimited Required PI API Version *Uses PI SDK PINet String Support *Source of Timestamps *History Recovery *UniInt-based *Disconnected Startup *SetDeviceStatus *Failover Yes ( to access annotations and some point attributes) No RDBMS or PI Server, depending on how you define the query that updates the target. Yes Yes No Yes Interface level failover: UniInt Phase 2 Failover (cold) Server level failover: RDBMS Server-level failover for mirrored Microsoft SQL Servers only *Vendor Software Required on PI Interface Node / PINet Node Vendor Software Required on Foreign Device Vendor Hardware Required Additional PI Software Included with Interface *Device Point Types Yes Yes No No See note below. 2 PI Interface for RDBMS 3.22 User Guide

9 Introduction to PI Interface for RDBMS Serial-Based Interface No * See paragraphs below for further explanation. Platforms 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. Read-only Interface available A read-only version of this interface is NOT available because it does not implement any logic that would prevent users to specify SQL statements that could write to RDBMS. In order to enforce read only access to a database a user with read only privileges should be configured and used. Note: As a security best practice, OSIsoft recommends creating a database user with read only privileges and reference it through the /User_ODBC start-up parameter. Support for reading/writing to PI Questionable Flag and Annotation Next to the timestamp, value, and status, the RDBMSPI interface can write/read also to/from PI questionable flag and annotation. Uses PI SDK This Interface specifically makes PI SDK calls to access some of the PI Point attributes and read and write PI annotations. Source of Timestamps The interface can accept timestamps from the RDBMS or it can provide PI Server synchronized timestamps. History Recovery For output tags, the interface goes back in time and uses values stored in the PI Archive for outputting them through configured SQL statements (mostly INSERTs or UPDATEs). For input tags, history recovery often depends on the WHERE condition of a SELECT query. Moreover, the interface allows for chunking longer recovery intervals so that the memory is not taxed during the initial query. 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 UniInt supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features. The UniInt Interface User Manual is a supplement to this manual. PI Interface for RDBMS 3.22 User Guide 3

10 Introduction to PI Interface for RDBMS SetDeviceStatus The RDBMSPI Interface is built with health tags support. The following events will be written into the tag, which has in ExDesc =[UI_DEVSTAT] keyword defined. "0 Good " The interface is properly communicating and gets data from/to the RDBMS system via the given ODBC driver "3 1 device(s) in error " ODBC data source communication failure "4 Intf Shutdown " The interface was shut down Failover Note: Refer to the UniInt Interface User Manual for more information on how to configure health points. UniInt Failover Support This interface supports UniInt Phase 2, cold failover. This failover solution requires that two copies of the interface be installed on different interface nodes with one instance being active and the second in a passive mode. Phase 2 Failover also requires each interface have access to a shared data file. Failover operation is automatic and operates with no user interaction. Each interface participating in failover has the ability to monitor and determine liveliness and failover status. To assist in administering system operations, the ability to manually trigger failover to a desired interface is also supported by the failover scheme. The failover scheme is described in detail in the UniInt Interface User Manual, which is a supplement to this manual. Server-Level Failover The interface supports the FAILOVER_PARTNER keyword in the connection string when used with Microsoft SQL Server 2005 (and above) and the Native Client ODBC driver. In other words, in case the interface connects to the mirrored Microsoft SQL Servers and the connection gets broken, the interface will attempt to reconnect to the second SQL Server. Vendor Software Required The RDBMS specific ODBC driver must be installed and configured on the interface node. Device Point Types For full description of the ODBC supported data types see the ODBC Programmer's Reference available on ( The interface does some internal consideration in terms of mapping the RDBMS data types to PI data types and vice versa. Configuration diagram The following diagram displays the basic configuration of the hardware and software components in a typical scenario used with the interface. 4 PI Interface for RDBMS 3.22 User Guide

11 Introduction to PI Interface for RDBMS PI Interface for RDBMS 3.22 User Guide 5

12 Introduction to PI Interface for RDBMS 6 PI Interface for RDBMS 3.22 User Guide

13 Principles of operation for RDBMS To read data from an RDBMS into the PI Data Archive, you define input tags, which are associated with SELECT queries that return columns containing values for the following tag attributes: Timestamp Value Status Questionable (optional) Annotation (optional) To write data from the PI Data Archive to the RDBMS, you define output tags, which are associated with INSERT, UPDATE, or DELETE queries. Queries can contain placeholders for replaceable parameters. Placeholders are evaluated when the query is executed. For efficiency in reading data from the RDBMS and writing it to the PI Data Archive, the interface supports several distribution strategies, depending on the structure of the result rows returned by the SELECT query: One PI point value per row: Each row returned in the result set returned by the SELECT query contains a single timestamp, value, status and (optionally) questionable and/or annotation, but no PI tag name. For details, see Updating a single tag in this document. Multiple PI point values per row (the "tag group" approach): Each row in the result set contains values for more than one PI point. To associate a specific column with a PI point, you specify the column position in the Location3 point attribute. For details, see Update a predetermined set of tags (tag groups) in this document. Read the PI point name from the row: To handle result sets that include rows for multiple PI points, the interface provides the "tag distribution" and "RxC" (row by column) distribution approaches, depending on whether the row includes one value for one tag or values for multiple tags. For details, see Update from multi-value rows containing name of target points (RxC) in this document. Tags can be scanned or event-driven. Scanned tags are read or written at a regular interval that is defined by the scan class assigned to the tag. Event-driven tags are read or written when a specified trigger tag is updated. The interface provides several options for handling data that does not arrive in timestamp sequence (out-of-order data). Besides collecting data in real time, the interface can recover historical data from the PI Archive to an RDBMS or from the RDBMS to the PI Data Archive. You can configure the period to be restored, and after recovery is complete, the interface can either exit or begin collecting real- time data. The interface runs on Windows either as a console application or Windows service. It uses ODBC to connect to the RDBMS. For the ODBC connection, you define the data source name (DSN) using the Data Sources (ODBC) Windows control panel and configure the interface instance to connect to the database using the DSN. PI Interface for RDBMS 3.22 User Guide 7

14 Principles of operation for RDBMS Loss of connectivity to RDBMS If the interface loses the ODBC connection to the RDBMS, it closes any prepared SQL statements. If it is still connected to the PI System, the interface writes I/O Timeout to its points (unless you disable this feature) and loops, trying once a minute to reconnect. If it succeeds in connecting to the RDBMS, it reissues the query that preceded the "dropped connection" error. You can configure the number of ODBC errors that triggers a reconnection: in PI ICU, on the rdbodbc > Optional Parameters tab. The retry rate is not configurable. For output tags, when the interface loses connectivity to the RDBMS, placeholder values are retained. The interface does not empty the update-event queue for output tags, so events might be lost if the queue overflows. To recover such lost events manually, set the recovery parameters ( /OOO_Option ) and restart the interface, so as to reprocess the period when the interface was disconnected from the RDBMS. For details about recovery, see Recover historical data in this document. For details about increasing the size of the event queue, see the PI Server documentation. Loss of connectivity to PI Server If the interface loses its connection to the PI Server, it logs errors and continues running normally, attempting to restore the connection to the server. While the interface is disconnected from the PI Server, it cannot read values for the snapshot placeholders (TS,VL, SS_I, etc.) and the attribute placeholders (AT.xxx), which are used to specify values for replaceable parameters in SQL queries. If buffering is enabled, queries without placeholders continue collecting data, and queries with placeholders report an error. 8 PI Interface for RDBMS 3.22 User Guide

15 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 Procedure 1. 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. 2. 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. 3. 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. 4. Run the installation kit for this interface. The kit also runs the PI SDK installation kit which installs both the PI API and the PI SDK if necessary. 5. 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. 6. 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=##:##:##,offset) 7. Use an ODBC based connection tool, such as ODBCTest.exe ( msdn.microsoft.com/en-us/library/ms712676(v=vs.85).aspx), to confirm connection between the interface node and RDBMS works. 8. If you will use digital points, define the appropriate digital state sets. 9. If needed, add the desired system states to the system digital state set. PI Interface for RDBMS 3.22 User Guide 9

16 Installation checklist 10. Build input tags and, if desired, output tags for this interface. Important point attributes and their purposes are: Point Attribute Location1 Location2 Location3 Location4 Location5 ExDesc InstrumentTag SourceTag Purpose Interface instance ID Bulk or non-bulk reading Data acquisition strategy Scan class Specifies how the data is sent to PI (snapshot, archive write, etc). Parameters and placeholders for SQL queries The name of the file that stores the SQL file Trigger tag for output tags 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. 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. It is recommended to test the connection between the interface node and the RDBMS using any third-party ODBC based application. For example the ODBC Tester app. from Microsoft or any other tool that works with ODBC data sources. Verify that the SQL queries are syntactically correct and they deliver data from/to the above mentioned third-party ODBC based applications. 12. Take one, (ideally) simple SQL statement, which has been tested in the third party tool and configure an interface tag, which will use it. 13. 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.) 14. Confirm that the interface collects data successfully. 15. If output points are required, confirm that output points update the correct values in the data source. Create an output point whitelist file for the interface instance. 16. Stop the interface and configure a buffering application (either Bufserv or PIBufss). 17. Start the buffering application and the interface. Confirm that the interface works together with the buffering application by either physically removing the connection between the interface node and the PI Data Archive node, or follow the procedures described in Knowledge Base article KB00300 ( KB00300) on the Tech Support Site. Note: 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. 10 PI Interface for RDBMS 3.22 User Guide

17 Installation checklist 18. Configure the interface to run as a Windows service, dependent on the PI buffering service. 19. Restart the interface node and confirm that the interface and the buffering application restart. Interface diagnostics (optional) Procedure 1. Configure Scan Class Performance points. 2. Install the PI Interface for Performance Monitor 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. Advanced interface features (optional) Configure UniInt failover; see the corresponding chapter in UniInt Interface User Manual for details related to configuring the interface for failover. PI Interface for RDBMS 3.22 User Guide 11

18 Installation checklist 12 PI Interface for RDBMS 3.22 User Guide

19 Installation instructions 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). 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. Note: By default, 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. Name conventions and requirements In the installation procedure below, it is assumed that the name of the interface executable is <interface name>.exe (e.g., RDBMSPI.exe) and that the startup command file is called <interface name.bat (e.g., RDBMSPI.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, RDBMSPI1.exe and RDBMSPI1.bat would typically be used for instance 1, RDBMSPI2.exe and RDBMSPI2.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. Interface directories PI Interface for RDBMS 3.22 User Guide 13

20 Installation instructions PIHOME Directory Tree 32-bit Interfaces 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. Note: Restrict the Windows accounts that can create or write files in the %PIHOME% folder and subfolders. PIHOME64 Directory Tree 64-bit Interfaces The [PIHOME64] directory tree is defined by a System Environmental Variable called PIHOME64. A typical value for this environmental variable is C:\Program Files\PIPC\. The above lines define the \Program Files\PIPC directory as the root of the PIHOME64 directory tree on the C: drive. OSIsoft recommends using \Program Files\PIPC as the root directory name. The PIHOME64 directory does not need to be on the C: drive. Note: Restrict the Windows accounts that can create or write files in the %PIHOME% folder and subfolders. Interface Installation Directory The installation kit for the read/write version will automatically install the interface to: PIHOME\Interfaces\<interface name>. For example: PIHOME\Interfaces\RDBMSPI\ PIHOME is defined in the pipc.ini file. 14 PI Interface for RDBMS 3.22 User Guide

21 Installation instructions Interface installation procedure The RDBMSPI interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows operating systems. To install, run the appropriate installation kit. 32-bit Interface RDBMSPI _#.#.#.#_.exe 64-bit Interface RDBMSPI _#.#.#.#_x64_.exe Silent Installation Procedure To launch a silent installation, type: Setup.exe -f silent.ini The silent.ini file is included in the interface installation kit. You can make site-specific alterations to the file as needed. See the silent.ini file for further information and descriptions of available arguments. Note: Please note all other modules in the interface installation kit are configured to be installed by default. 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. Install Interface as Windows service The RDBMSPI interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually. Note: For improved security, we recommend running the interface service under a nonadministrative account, such as a Windows built-in service virtual account, the built in Network Service account, or a non-administrative account that you create. PI Interface for RDBMS 3.22 User Guide 15

22 Installation instructions Install interface service with PI Interface Configuration Utility (ICU) Service Configuration The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service: 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 16 PI Interface for RDBMS 3.22 User Guide

23 Installation instructions 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 NT Service account, the Log on as will have selected "NT Service." Users may specify a different Windows account for the service to use. 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 NT 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. 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. 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 enabled, then Bufserv or PIBufss 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 button, and the service name will be removed from the Dependencies list. 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. PI Interface for RDBMS 3.22 User Guide 17

24 Installation instructions 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. 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. Ready - Status of the ICU Stopped - Status of the Interface Service RDBMSPI1 - Installed - Service installed or uninstalled Install the interface service manually Help for installing the interface as a service is available at any time with the command: RDBMSPI.exe /help Procedure 1. Open a Windows command prompt window and change to the directory where the RDBMSPI.exe executable is located. Then, consult the following table to determine the appropriate service installation command. Note: In the following Windows service installation 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 RDBMSPI.exe /install /depend "tcpip bufserv" 18 PI Interface for RDBMS 3.22 User Guide

25 Windows Service Installation Commands on an Interface Node or a PI Data Archive Node with Bufserv implemented Automatic service Installation instructions RDBMSPI.exe /install /auto /depend "tcpip bufserv" *Automatic service with service ID RDBMSPI.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 RDBMSPI.exe /install /depend tcpip RDBMSPI.exe /install /auto /depend tcpip *Automatic service with service ID RDBMSPI.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. 2. 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 create an interface service that runs under a low-privilege built-in account. On Windows 7 and Server 2012 and later, the service logs on as the service virtual account. For earlier versions of Windows, the service logs on as Network Service. 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. 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 RDBMS 3.22 User Guide 19

26 Installation instructions 20 PI Interface for RDBMS 3.22 User Guide

27 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 or PIBufss provides data compression. Exception reporting and compression are very important aspects of data collection and archiving, which are not discussed in this document. Note: Depending on the configuration, your interface may not contain all the point attributes in this section. Note: See the UniInt Interface User Manualand PI Data Archive documentation for information on other point attributes that are significant to PI point data collection and archiving. Tag (PI point name) 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 Data Archive documentation uses the terms "tag" and "point" interchangeably. Follow these rules for naming PI points: The name must be unique in 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: * '? ; { } [ ] \ ` ''"" Tag Length 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 later x or later or later Earlier than x 255 Earlier than x or later 255 PI Interface for RDBMS 3.22 User Guide 21

28 PI Point configuration PI API PI Data Archive Maximum Length Earlier than Earlier than x 255 PointSource (point source) PointSource is an identifier that associates a PI point with a PI interface instance, enabling the interface to query the PI Data Archive for the points that it updates. This field is not casesensitive. In the interface batch startup file, the point source is specified using the /PS command-line parameter. The following point sources are reserved. Do not configure them for interface instances. Point Source T G R Reserved By Totalizer Subsystem Alarm subsystem Random interface 9 RampSoak interface C Performance equations subsystem PointType (data type) PointType specifies the data type of the point. Typically, item data types do not need to match PI tag data types exactly, but the data types must be compatible. 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 might be truncated. Location1 (interface instance) Location1 specifies the instance of the interface to which the PI point belongs. The value of this attribute must match the ID configured for the interface instance. This setting plus PointSource identify the interface instance that writes to a particular point. ( /ID). Location2 (first row or all rows) To retrieve only the first row that matches the criteria of a SELECT query, set Location2 to 0. To retrieve all rows that match the query criteria, set Location2 to 1. For tag groups, the tag, which executes the query (master tag), sets this option for all the tags in its group; it is not possible to read only the first record for one group tag member and all records for another group tag member. For tag distribution, the interface always examines the whole result set, regardless of the Location2 setting. Location3 (distribution strategy) For input points, Location3 configures how retrieved data is to be assigned to the tag. 22 PI Interface for RDBMS 3.22 User Guide

29 PI Point configuration Distribution strategy Column number of the result to be assigned to this tag (tag group strategy) SQL query populates a single tag 0 Tag distribution (Tag name or alias in result set) -1 RxC (row by column) distribution (Multiple tag names or aliases in result set) Location3 Positive number -2 Location4 (scan class) The scan class determines the frequency at which input points are scanned for new values. Set to 0 for event-based (trigger) tags, unsolicited inputs, and output points. For auditing changes to points, set to -1 to record the short-form version of tag attribute changes or -2 to record the long-form version. For details about the deprecated auditing feature, refer to Record PI Point database changes for PI Interface for RDBMS. Location5 for RDBMS (data archiving and history recovery) The Location5 attribute configures exception reporting and the handling of events with duplicate timestamps. For output points, it configures how events are recovered from the PI Archive to an RDBMS. For details about recovery, see Recover historical data in this document. Tags and queries that include PI annotations bypass exception reporting and are written directly to the archive, regardless of their Location5 attribute setting. Note that the interface also performs recovery during startup in real-time mode, to ensure that it captures any events that occurred during its downtime. Input points To configure handling of out-of-order data for an input point, set Location5 as follows: Value Description 0 Enable standard exception reporting and out-oforder data handling for a tag. If the PI Archive already contains an event with the same timestamp as the incoming event, the archived event is not replaced with the incoming event. 1 Disable exception handling and send all incoming values to the snapshot. For out-of-order data, existing events are replaced and new events are added. 2 Archive all incoming out-of-order values. Be aware that if you set Location5 to 2, there can be multiple events with the same timestamp. 3 For the tag distribution and strategy, forward to PI only newer events than PI snapshot. PI Interface for RDBMS 3.22 User Guide 23

30 PI Point configuration InstrumentTag (SQL query file) The InstrumentTag attribute specifies the file that contains the SQL statements that determine the data to be read from or written to the RDBMS. The query is executed when the tag gets executed and whenever one of its attributes is changed. To configure the folder where query files are stored, use PI ICU (go to the rdbodbc -> Startup Parameters tab and set the SQL Files Directory field.) As an alternative to specifying queries in text files, you can specify the query in the tag's ExDesc attribute. Note that, if you change the query associated with a PI tag, you do not need to restart the interface to enable it to execute the revised query. 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. PI API PI Data Archive Maximum Length or later x or later or later Earlier than x 32 Earlier than x or later 32 Earlier than Earlier than x 32 ExDesc (extended descriptor) The ExDesc attribute configures a variety of run-time settings, as described in the following table. Keywords must be specified in upper case. Keyword Description Example ALIAS Map PI point names to corresponding names in the RDBMS. Case-sensitive. For details about configuring aliases, see Reading target tag names from the database (distribution) in this document. /ALIAS=Level123 or /ALIAS="Level 123" 24 PI Interface for RDBMS 3.22 User Guide

31 PI Point configuration Keyword Description Example GETPOINTS At startup, cache only those points, that pass the filter defined by this keyword. The SQL statement, defined in the Extended Descriptor of the tags with Location4=-1 or -2, will only be executed when an attribute had changed for the cached points. See Record PI Point database changes for PI Interface for RDBMS in this document. If no /GETPOINTS keyword found, the interface will cache points with point source, the given instance runs with. REM: The filter syntax complies with the WHERE condition syntax the PI SDK's GetPoints () method accepts. /GETPOINTS=tag='abc*' (React onto PiPoint attribute changes for points their names start with abc only.) PERFORMANCE_POINT SQL TRANSACT When set, such point stores the amount of time, in seconds, that it takes an interface to complete a scan for a particular scan class. The lower the scan time, the better the performance. Specify the query for the tag. Enclose the query in double quotes and terminate it with a semicolon, followed by any placeholders, separated by white space. For details examples of queries, see SQL examples in this document. If more than one SQL statement is specified for the tag, the queries are executed as a single transaction (committed or rolled back together). PERFORMANCE_POINT For details, refer to the UniInt Interface User Manual. /SQL="SELECT timestamp, value, status FROM table1 WHERE timestamp >? ORDER BY timestamp ASC;" P1=TS /TRANSACT PI Interface for RDBMS 3.22 User Guide 25

32 PI Point configuration Keyword Description Example TRIG or EVENT For event-driven input points: each time the specified point changes, the SQL query is executed. If the point name contains spaces, you must enclose it in single quotes. If there are subsequent parameters, you must specify a comma after the /EVENT specification. Valid conditions: anychange increment decrement nonzero For details about defining eventdriven points, refer to the UniInt Interface User's Guide. /EVENT=sinusoid, or /EVENT=sinusoid anychange, To assign values to replaceable parameters in SQL queries, you specify placeholders in the ExDesc attribute. Replaceable parameters in queries are indicated by question marks. ExtendedDescriptor Length Depending on the version of the PI API and the PI Data 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 PI API PI Data Archive Maximum Length or later x or later or later Earlier than x 80 Earlier than x or later 80 Earlier than Earlier than x 80 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. SourceTag For output tags (points that write data to the RDBMS), this attribute specifies the PI tag that triggers query execution and from which the data is read (unless the output tag's query uses placeholders to derive the data from other tags). 26 PI Interface for RDBMS 3.22 User Guide

33 PI Point configuration 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 following commandline parameter is specified: /stopstat=shutdown 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 the 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. PI Interface for RDBMS 3.22 User Guide 27

34 PI Point configuration 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 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. ExcMax ExcMin and ExcDev (exception processing) Exception reporting enables you to capture the minimum amount of data required to meaningfully represent a trend. The following parameters configure exception reporting in the PI interface. ExcMax: The maximum time period allowed between sending values to the PI Data Archive. ExcMin : The minimum time period between values sent to the PI Data Archive. ExcDev: The minimum change from the last value sent to the PI Data Archive required for the interface to send a new value. Exception processing is not performed for queries that include PI annotations: all data retrieved by such queries is archived. To further filter the amount of data that is captured, you can configure a tag's compression settings so that only meaningful deviations are archived. For more information about exception processing and compression, see the UniInt Interface User Manual. 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. Note: If outputs to the data source device (RDBMS) are NOT needed, specify a database user with read-only privileges and reference it through the /User_ODBC start-up parameter. Alternatively, implement an explicite output point whitelist, which provides a defense against accidental or malicious changes to a database. 28 PI Interface for RDBMS 3.22 User Guide

35 PI Point configuration Output point whitelist For enhanced security, create a "whitelist" of output points. When this feature is enabled, the interface verifies that an output point is in the whitelist before updating the data source. The whitelist file is a.csv (comma-separated values) file that contains a list of approved output PI points and the attributes that associate the PI point with a writable value in the data source. For this interface, the following attributes must be in the whitelist file to secure the output points: Tag InstrumentTag ExDesc Location2 Location3 Location5 The whitelist feature also supports range checking of output values. The Zero and Span attributes in the whitelist file specify the minimum (zero) and maximum (sum of zero and span) allowed for the output value. To create and configure an output point whitelist, see the UniInt Interface User Manual PI Interface for RDBMS 3.22 User Guide 29

36 PI Point configuration 30 PI Interface for RDBMS 3.22 User Guide

37 Specify SQL queries The SQL query that is associated with a tag determines how data is written to PI tags or to the RDBMS tables. SQL queries can be specified in either of two ways: In the extended descriptor (ExDesc) attribute of a PI tag. To specify a query in the extended descriptor attribute, precede it with the /SQL keyword, terminate it with a semicolon, and enclose it in double quotes. (You must specify the /SQL keyword in uppercase letters.) For example: ExDesc: /SQL="SELECT timestamp, value, status FROM table1 WHERE timestamp >? ORDER BY timestamp ASC;" P1=TS In text files residing in a query files directory. This directory is configured for the interface instance using PI ICU. Typically, query files have a.sql extension, but there is no required naming convention. To associate a query file with a tag, specify the name of the file in the InstrumentTag attribute and specify placeholders for replaceable parameters in the ExDesc attribute. For example: MYQUERY.SQL is a text file that contains the following query: SELECT timestamp, value, status FROM table1 WHERE timestamp >? ORDER BY timestamp ASC; InstrumentTag: MYQUERY.SQL ExDesc: P1=TS Note: The PI Data Archive expects data to arrive in chronological sequence. To ensure that data arrives in chronological sequence use the ORDER BY clause to sort by timestamp. To specify multiple SQL statements, separate them with semicolons. Following the query, specify any placeholders for replaceable parameters. For example: /SQL="SELECT timestamp, value, status FROM table1 WHERE timestamp >? ORDER BY timestamp ASC; DELETE FROM table1 WHERE timestamp < GETDATE()-1;" P1=TS Note: For input tags, when multiple SQL statements are specified, make sure there is only one SELECT statement among them. Use the UNION ALL construct if more than one SELECT is needed. Query execution Before a query is executed, the interface checks its syntax. If the syntax is invalid, the interface logs a Tag refused message describing the problem. To ensure that the syntax of a query is PI Interface for RDBMS 3.22 User Guide 31

38 Specify SQL queries valid, test the query using a third-party ODBC query tool (for instance, the Microsoft ODBC Test application). The queries executed by your tags can contain single or multiple SQL statements, each terminated by a semicolon. Each statement is committed after execution (AUTOCOMMIT) unless you enable transaction semantics for the tag by specifying the /TRANSACT keyword in the ExDesc tag attribute. If all statements succeed, the transaction is committed. If any statement fails, all statements are rolled back. The following SQL statements are permitted: SELECT INSERT UPDATE DELETE {CALL} Note: Proprietary language constructions such as T-SQL and PL/SQL are not guaranteed to work. For example, the MS SQL Server's T-SQL is supported for use with the MS SQL ODBC driver, but similar constructions fail with an Oracle ODBC driver. If you require logic to control the flow of execution, use stored procedures. To optimize performance, the interface executes SQL queries using prepared execution. SQL queries are compiled the first time they are executed, and the compiled queries are used for subsequent executions. Some ODBC drivers limit the number of prepared statements permitted. If your ODBC driver enforces a maximum, you can disable prepared execution using PI ICU: Go to the rdbodb > Optional Parameters tab and check Direct SQL execution. If the query fails the first time it is executed, the tag is removed from processing. For output tags, if the query fails, the output tag is assigned the Bad Output state. Stored procedures Queries can execute previously-defined stored procedures. Stored procedure calls can use placeholders (input parameters) in their argument lists. To call a stored procedure, use the following syntax: {CALL procedure-name[([parameter][,[parameter]] )]} Output parameters are not supported. Stored procedures are therefore mainly useful for complex actions that cannot be expressed using the SQL syntax that the interface supports. For an example of the use of stored procedures, see the SQL examples section in this document. Checking query execution results To detect whether a query succeeded, check the following TRUE if query succeeded (all values written to PI Data Archive), FALSE if query FALSE if query succeeded, TRUE if query failed 32 PI Interface for RDBMS 3.22 User Guide

39 Specify SQL queries You can define an IF statement that conditionally issues a single SQL statement depending on the state of the variable. For example: You can define an IF statement that conditionally issues a single SQL statement depending on the state of the variable. For example: SELECT timestamp, value, 0 FROM table1 WHERE timestamp >? ORDER BY timestamp ASC; INSERT INTO table2 (timestamp, tagname, error_message) VALUES (?,?, 'Query failed'); Note that the interface does not support an ELSE clause for the IF statement. Checking whether tags are updated To determine whether PI tags were successfully updated by a query, check the value of either of the following TRUE if query succeeded (all values written to PI Data Archive), FALSE if update FALSE if query succeeded, TRUE if it failed. These variables are set when the first query is executed. You can define an IF statement that conditionally issues a single SQL statement depending on the state of the variable. For example, to determine whether rows in the RDBMS have been successfully written to tags and can therefore be deleted from the RDBMS, use the following logic: SELECT timestamp, value, 0 FROM table1 WHERE timestamp >? ORDER BY timestamp; DELETE FROM table1 WHERE timestamp <=?; To determine whether tag distribution succeeded, you must use variable. For details, see Verifying successful data distribution. Placeholders for replaceable parameters Placeholders define the values to be assigned to replaceable parameters in SQL queries. Replaceable parameters in queries are specified using question marks. The value of a placeholder is determined when the query is executed. Specify placeholders in a tag's ExDesc attribute, separated by whitespace, for example: P1=TS P2=SS_I P3=AT.TAG Note that the placeholders are numbered and must be specified in ascending order. The next example illustrates how data from events in the PI Archive are transferred through placeholders to an RDBMS table for various PI data types. The example is based on the following query: /SQL="INSERT INTO table1 (name, instant, column_num, status_num, status) VALUES (?,?,?,?,?);"P1=AT.TAG P2=TS P3=VL P4=SS_I P5=SS_C Values are assigned in order: the first replaceable parameter is assigned the value of the placeholder assigned to P1, the second replaceable parameter is assigned the value of the placeholder assigned to P2, and so on. PI Interface for RDBMS 3.22 User Guide 33

40 Specify SQL queries Specify placeholders in the tag that executes the query, as follows: Data handling method Single Distribution Group RxC Tag that defines placeholders Single tag Distributor tag Master tag Tag list For string constant placeholders, specify the argument in double quotes; for example: P1="any_string" If the same placeholder definition is used multiple times in a query, it is possible to shorten the definition string using a back-reference; for example: P5=P3 To derive data from a tag other than the tag associated with the query, you can qualify a placeholder with the name of the tag. For example, to derive the value from another tag, precede the VL placeholder with the name of the tag in single quotes as follows: P1='sinusoid'/VL The following table shows how the interface evaluates placeholders for output tags. Values from digital PI tags must correspond to string columns in the RDBMS. PI point data type Event state Plac SS_Ieholders Float, Timestamp, Integer, String Digital VL SS_I SS_C No error <Value> 0 "O.K." Error < Previous Value> <Digital State String> Digital state is in the range of success statuses Digital state is in the range of "bad" statuses <Digital State String> <Digital State String> 0 "O.K." <Digital State String> 1 "Bad Value" To configure the value to be used when no value exists at the specified timestamp, set the mode parameter as follows: P1='sinusoid'/VL('timestamp',mode) For output tags, the timestamp is usually the time from the source tag event. If a value exists at the specified timestamp, the value is used. Valid values for the mode parameter are as follows: Mode Previous Next Interpolated Value used The first value before the specified time The first value after the specified time. Specified time cannot exceed snapshot time. Interpolated value at the specified time 34 PI Interface for RDBMS 3.22 User Guide

41 Specify SQL queries Timestamp, value, status, and annotation placeholders definitions The following tables list the placeholders supported by the interface. For placeholders that accept a tag name argument, specify the tag name in single quotes preceding the placeholder, as shown in the following table. Placeholder keywords for ExDesc (Pn=) Description ANN_C and 'tagname' /ANN_C Annotation number (varchar) Max characters ANN_I and 'tagname' /ANN_I ANN_R and 'tagname' /ANN_R ANN_TS and 'tagname' /ANN_TS QE LET LST SS_C and 'tagname' /SS_C SS_I and 'tagname' /SS_I ST TE TS and 'tagname' /TS VL and 'tagname' /VL ('timestamp', mode ) Annotation number (integer) Annotation number (float) Annotation timestamp Questionable bit (number). Non-zero when set. Last execution time Input: Time when the query finished execution. The time difference between LST and LET can be significant in the case of a long-running query. Last scan time Current status digital code string. For valid events, SS_C is set to "O.K." Max. 79 characters Current status integer representation Scan time Input: Start of new scan for a scan class Output: Time of output event Timestamp end. Used in recovery mode Timestamp. For input tags, the timestamp is taken from the interface's internal snapshot Current value Digital tags: max 79 characters. String tags: max 977 characters The mode parameter indicates the value to be used when no value exists at the specified timestamp. Valid values for mode: previous next interpolated Note: The ('*', mode ) syntax can also be used with the SS_I and SS_C placeholders, and the annotation-related placeholders (ANN_*). PI point data placeholders The following placeholders return information about points and data from PI point attributes. Placeholder keywords for ExDesc (Pn=) AT.TAG AT.DESCRIPTOR Description Tag name of the current tag Max characters Descriptor of the current tag Max characters PI Interface for RDBMS 3.22 User Guide 35

42 Specify SQL queries Placeholder keywords for ExDesc (Pn=) Description AT.EXDESC Extended descriptor of the current tag Max characters AT.ENGUNITS Engineering units for the current tag Max. 13 characters AT.ZERO AT.SPAN AT.TYPICALVALUE AT.DIGSTARTCODE AT.DIGNUMBER AT.POINTTYPE Zero of the current tag Span of the current tag TypicalValue of the current tag Digital start code of the current tag Number of digital states of the current tag Point type of the current tag Max. 1 character AT.POINTSOURCE Point source of the current tag Max characters AT.LOCATION1 AT.LOCATION2 AT.LOCATION3 AT.LOCATION4 AT.LOCATION5 AT.SQUAREROOT AT.SCAN AT.EXCDEV AT.EXCMIN AT.EXCMAX AT.ARCHIVING AT.COMPRESSING AT.FILTERCODE AT.COMPDEV AT.COMPMIN AT.COMPMAX AT.TOTALCODE AT.CONVERS AT.CREATIONDATE AT.CHANGEDATE AT.CREATOR AT.CHANGER AT.RECORDTYPE AT.POINTNUMBER AT.DISPLAYDIGITS AT.SOURCETAG Location1 of the current tag Location2 of the current tag Location3 of the current tag Location4 of the current tag Location5 of the current tag SquareRoot of the current tag Scan flag of the current tag Exception deviation of the current tag Exception minimum time of the current tag Exception maximum time of the current tag Archiving flag of the current tag Compression flag of the current tag Filter code of the current tag Compression deviation of the current tag Compression minimum time of the current tag Compression maximum of the current tag Total code of the current tag Conversion factor of the current tag Creation date of the current tag Change date of the current tag Creator of the current tag, specified as the PI user's numeric ID. Max. 8 characters Changer of the current tag. REM: See also AT.CREATOR Max. 8 characters Record type of the current tag Point ID of the current tag Display digits after decimal point of the current tag Source tag of the current tag Max characters AT.INSTRUMENTTAG Instrument tag of the current tag Max characters 36 PI Interface for RDBMS 3.22 User Guide

43 Specify SQL queries Placeholder keywords for ExDesc (Pn=) AT.USERINT1,2 AT.USERREAL1,2 Description UserInt1, UserInt2 UserReal1, UserReal2 Placeholder data types When populating values configured using placeholders, the interface uses the data types listed in the following table. The ODBC driver attempts to bind using the most compatible data type. If the binding does not succeed, the interface tries again using the second- and third-choice data types, if indicated. Point attributes placeholders Attribute AT.ATTRIBUTE AT.CHANGER AT.CREATOR AT.DESCRIPTOR AT.ENGUNITS AT.EXDESC AT.INSTRUMENTTAG AT.NEWVALUE AT.OLDVALUE AT.POINTSOURCE AT.POINTTYPE AT.SOURCETAG AT.TAG "any_string" SQL Data Type SQL_VARCHAR PI Interface for RDBMS 3.22 User Guide 37

44 Specify SQL queries Attribute AT.DIGSTARTCODE AT.DIGNUMBER AT.LOCATION1 AT.LOCATION2 AT.LOCATION3 AT_LOCATION4 AT.LOCATION5 AT.SQUAREROOT AT.SCAN AT.EXCMIN AT.EXCMAX AT.ARCHIVING AT.COMPRESSING AT.FILTERCODE AT.RES AT.COMPMIN AT.COMPMAX AT.TOTALCODE AT.RECORDTYPE AT.POINTNUMBER AT.DISPLAYDIGITS AT.USERINT1 AT.USERINT2 SQL Data Type First choice: SQL_INTEGER Second choice: SQL_FLOAT Third choice: SQL_DOUBLE Snapshot Placeholders Placeholder SQL (ODBC) Data Type First choice ST,TS, LET,LST, ANN_TS SQL_TIMESTAMP VL floating point and timestamp tags SQL_DOUBLE Second choice SQL_FLOAT integer tags SQL_INTEGER SQL_FLOAT digital tags SQL_VARCHAR string tags SQL_VARCHAR QE SQL_INTEGER SQL_FLOAT SS_I, ANN_I SQL_INTEGER SQL_FLOAT SS_C, ANN_C SQL_VARCHAR ANN_R SQL_REAL SQL_FLOAT 38 PI Interface for RDBMS 3.22 User Guide

45 Specify SQL queries Specifying result columns in SELECT statements The SELECT statements that you define to retrieve RDBMS data into PI tags must specify result columns for tag value and status. In addition, the result set can include columns for timestamp, questionable and annotations. There are two options for specifying the result columns in the SELECT statement: fixed position or aliased. Fixed-position result columns If you omit result column aliases, you must retrieve result columns in timestamp/value/status sequence. For example: SELECT timestamp, value, status FROM table1 The timestamp column is optional. If you omit the timestamp, the value is written using the interface node system time. If the source table does not include a status column, you can specify a numeric value in the query (0 indicates good data): SELECT timestamp, value, 0 FROM table1 Aliased result columns As an alternative to fixed positions, you can use aliases to assign result columns to tag attributes. Aliases must be specified in upper case, as shown. The following aliases are supported: PI_TAGNAME PI_TIMESTAMP PI_VALUE PI_STATUS PI_QUESTIONABLE PI_ANNOTATION For example: SELECT timestamp AS PI_TIMESTAMP, value AS PI_VALUE, status AS PI_STATUS, flag AS PI_QUESTIONABLE, annotation AS PI_ANNOTATION FROM table1 When you use aliases, the columns in the SELECT statement can be specified in any order they are not required to be in the timestamp/value/status sequence required by the fixed position approach. When the columns in the SELECT list are aliased, the status column is not mandatory. If status is omitted, the interface writes a status of 0 (Good) to the tag. The same is true for the questionable and annotation columns; that is, if these columns are omitted the questionable bit is not set and the event is not annotated. If the query retrieves multiple tag values from a single row, you can use numbered aliases to assign the results columns to target tags. The number of the alias corresponds to the value that you specify in the Location3 attribute of the target tag. For details, see Update a predetermined set of tags (tag groups). PI Interface for RDBMS 3.22 User Guide 39

46 Specify SQL queries Data type compatibility The data type of your result columns must be compatible with the data types supported by the PI data archive. To ensure compatibility, use the ANSI CAST() function or the ODBC CONVERT() function. The syntax for CONVERT() is as follows: {Fn CONVERT(value_exp,data_type)} Where value_exp is a column name, result of a scalar function, or a literal, and data_type specifies a valid ODBC data type. For example, the following expression converts the output of the MS SQL Server GETDATE() function to a string: {Fn CONVERT({Fn GETDATE()},SQL_CHAR)} For details about CONVERT(), refer to the MSDN Library or your ODBC driver documentation. The syntax for CAST() is as follows: CAST ( { expression NULL } AS data_type [(length)] ) For example, the following expression converts the selected value to a string: SELECT timestamp, CAST(value AS Varchar(255)), status FROM table1 For details about CAST(), refer to your RDBMS vendor's SQL reference guide. For a full description of the ODBC-supported data types, see the ODBC Programmer's Reference. To ignore null values for tags populated using the tag group and RxC distribution strategies, enable the Ignore Nulls option on the PI ICU rdbodbc > Optional Parameters tab. Handling NULLs When updating PI tags with data from the RDBMS, the interface handles NULLs as follows: Timestamp: If the timestamp is NULL, the current execution time is used. Value and Status: If the value column is not NULL, the value is valid, even if status is NULL. If both value and status are NULL, the No Data digital state is written to the tag, as shown in the following figure. To ignore null values for tags populated using the tag group and RxC distribution strategies, enable the Ignore Nulls option on the PI ICU rdbodbc > Optional Parameters tab. 40 PI Interface for RDBMS 3.22 User Guide

47 Specify SQL queries Input tag and status mapping Your input queries deliver data, which are stored in the following PI data archive columns: Timestamp Tag value Status Questionable (optional) Annotations (Optional) To ensure that SQL data types are compatible with data types supported in PI Data Archive, cast the result columns to a compatible data type. Note: The interface does not support Unicode. If a SELECT query returns a NVARCHAR (Unicode) result column, the interface logs an error message such as the following: Point - MyTag : Unsupported RDB column MyColumn type -9. To avoid such errors, cast Unicode result columns to an equivalent non-unicode data type. Timestamp - The result column must have a data type of DateTime, Date, or a compatible data type, depending on your RDBMS. Tag name - The result column must be a string type such as CHAR or VARCHAR. Tag value - For input points, the interface casts results from the RDBMS to compatible PI data types as follows: ODBC data type Approximate (floating point) Exact (integer) Character RDBMS data type SQL_NUMERIC SQL_DECIMAL SQL_REAL SQL_FLOAT SQL_DOUBLE SQL_TINYINT SQL_SMALLIN T SQL_INTEGER SQL_BIGINT SQL_BIT SQL_CHAR SQL_VARCHA R SQL_LONGVA RCHAR Target PI point data type Float Integer Digital String Cast to the corresponding floating-point type. Cast to the particular floating-point type. Converted to double, then cast to the PI floating-point type. Cast to integer. Cast to the particular integer type. Converted from string to integer and cast to integer PI data type. Cast to integer and interpreted as pointer to digital state set. Interpreted as pointer to digital state set. Checked against digital state set. Converted from floatingpoint to string. Converted from integer to string. Retrieved number of bytes copied. Status - The status field indicates the state of the target tag. To map the values in the RDBMS to valid PI status values, use PI ICU to configure the following settings on the rdbodbc -> Startup Parameters tab: PI Interface for RDBMS 3.22 User Guide 41

48 Specify SQL queries Successful - Status Range Bad Input - Status Range The data type of the status column determines how the interface handles it, as follows. String status values If the status from the result set is NULL or falls in the specified success range, the tag status is set to 0 (Good) and the value is written to the tag. If the status falls in the bad input range, the corresponding system digital state is written to the tag. Evaluation of status strings is case-insensitive. If the status value does not reside in either range, the tag is assigned Bad Input status. The following figure shows example definitions in the PI System digital set table for success and bad input ranges. Numeric status values Numeric status columns are handled as follows: Zero or NULL: Value is written to tag Positive value: Bad Input status is written to tag Negative value: Corresponding system digital state is written to tag Digital PI tag Any non-zero status indicates Bad Input. The following figure shows database table rows containing status values and the corresponding PI tag statuses. Timestamps TS placeholders initialization after start-up When the interface starts, all TS placeholders are populated with the current snapshot timestamps of individual PI points. 42 PI Interface for RDBMS 3.22 User Guide

49 Specify SQL queries Interface internal snapshot To ensure that all values added to a table since the last successful scan are returned, use the TS placeholder in combination with ordering the result-set by the timestamp column (ASCending). The majority of SELECT query examples in this manual have it so. Periodical execution of such queries enables reading data from RDBMS tables in ordered chunks and makes sure the interface can be temporarily stopped without losing data, because the very first execution of such SELECTs "recovers" all rows since the last successful scan. Note: The interface internal snapshot represent the timestamp of the last row returned in a result-set. It does not have to be the PI snapshot, because due to exception reporting, not all rows from a result-set are guaranteed to be forwarded to PI. Binding to ODBC SQL_TIMESTAMP data type The implementation of the timestamp type varies among the database vendors. Fortunately, the ODBC layer nicely hides these implementation variances and offers the SQL_TIMESTAMP data type, which enables the interface handles timestamps consistently without regard for the underlying RDBMS. All timestamp related placeholders, that is: TS, ST, LET, as well as columns in the SELECT list, which end up as PI timestamps, are bound to this type. That means that there is no need to cast anything to text and deal with various timestamp formats. UTC timestamps The interface can handle UTC timestamps from both the RDBMS and the PI System. If the timestamps in the RDBMS are stored as UTC data, enable UTC handling using PI ICU: go to the rdbodbc > OptionalParameters tab and check Times are UTC. Future timestamps The PI Data Archive rejects timestamps that are more than ten minutes ahead of its system time, unless the new PIPoint attribute future (introduced in PI Server 2015) is set. To prevent this problem, make sure that the system time on the PI Server and RDBMS host computers are synchronized and, if necessary, define queries that return only rows that are timestamped less than ten minutes ahead. The following two examples illustrate this approach; sysdate is Oracle's "current time" function, and "10*60./86400." is an expression for ten minutes: SELECT timestamp, value, status FROM table1 WHERE timestamp BETWEEN? AND sysdate+10*60./ ORDER BY timestamp ASC; The same ten-minute safe-guard with the MS SQL Server's getdate() "current time" function: SELECT timestamp, value, status FROM table1 WHERE timestamp BETWEEN? AND getdate()+10*60./ ORDER BY timestamp ASC; Since PI Server 2015, the points with future attribute set to one can accept future timestamps and the considerations described above do not apply. The interface does not have any restrictions towards points with future=1. Timestamp precision The PI System can handle timestamps with precision up to 100 microseconds. For example, 20-Mar :10: is a valid PI timestamp. However, the maximum precision of PI Interface for RDBMS 3.22 User Guide 43

50 Specify SQL queries timestamps obtained through ODBC calls is one millisecond. To work-around this, the interface recognizes the "numeric timestamps"; that is, accepts a column containing the number of seconds since 01-Jan-1970 (Unix timestamps) where the decimal part of this number represents the 100 microseconds and translates it to PI timestamp. Note that such numeric timestamp column must be explicitly aliased by the PI_TIMESTAMP keyword: SELECT timestamp_double AS PI_TIMESTAMP, value AS PI_VALUE, 0 AS PI_STATUS FROM table1 WHERE timestamp_double > DATEDIFF(s,'01-Jan :00:00',?) + timestamp_double - CAST(timestamp_double AS int); Questionable flag The Questionable flag is mapped to numeric data types from RDBMS. If the PI_QUESTIONABLE column is not zero, the questionable flag is set for the given event. Annotations The interface treats the column that contains annotations as one of the following data types: DateTime (timestamp) Approximate (floating-point) Exact (integer) String (varchar) The interface assigns it to PI annotations accordingly. 44 PI Interface for RDBMS 3.22 User Guide

51 Input processing: updating PI tags from an RDBMS To update PI tags with values retrieved from the RDBMS, you define a SELECT query or stored procedure that returns result rows from the RDBMS, and, if necessary, configure the target tags that are to be updated with the data returned by the query. When you update tags, you write a value, timestamp and status (and, optionally, the questionable flag and annotations). You can configure updates as either scan- or event-based. Scan-based updates occur when the tag is scanned, while event-based updates are triggered by changes to a point referenced by the /EVENT or /TRIG keywords. When data is written to a tag, the tag stores a value only if the status is good. If the status is anything other than good, only the status is stored. Approaches to data retrieval (distribution strategies) The interface provides several strategies for retrieving data, depending on the format of the result rows that your query returns, which in turn depends on the structure of the RDBMS tables that you are querying. The various strategies enable you to keep the impact of the interface on the RDBMS to a minimum by writing the maximum amount of data using the smallest possible number of queries. Data retrieval strategies provided by the interface are as follows: If the result rows contain timestamp, value, and/or status, use single strategy. If result rows contain a single timestamp, tag name, and value, use distribution. If result rows contain multiple values and no target tag names, use tag groups. If result rows contain multiple values and tag names, use RxC For distribution and RxC, you define a distributor tag, which executes a query that retrieves values to be written to target tags but does not receive any retrieved value itself. The distributor tag must have a string or numeric data type (Float16, Float32, Float64, Int16, Int32), and its timestamp is always the current time. After its query is executed and the results are distributed to target tags, the distributor tag is updated with two events indicating the results of the operation: The number of events that were successfully distributed to target tags The number of rows in the query result set Both entries are timestamped with the current time, and appear in the PI archive at the same timestamp. To optimize the performance of the interface, choose an approach that retrieves the maximum amount of data using the fewest queries possible. Updating a single tag The simplest approach is to define a query that retrieves a single value, timestamp and value. For example: SELECT timestamp, value, status FROM table1 PI Interface for RDBMS 3.22 User Guide 45

52 Input processing: updating PI tags from an RDBMS The timestamp is optional; if omitted, the interface uses the time of query execution. Status is required, and can either be retrieved from the RDBMS or specified as a literal. For example: SELECT value, 0 FROM table1 Result columns must be specified in "timestamp, value, status" order or aliased using the following "PI_" alias keywords: PI_TIMESTAMP, PI_VALUE, PI_STATUS, PI_QUESTIONABLE, PI_ANNOTATION. For example: SELECT value AS PI_VALUE, status AS PI_STATUS, timestamp AS PI_TIMESTAMP, annotation AS PI_ANNOTATION, flag AS PI_QUESTIONABLE FROM table1 For details, see Aliased result columns under Specifying result columns in SELECT statements. For efficiency, try to issue the minimum number of queries: a single query that returns multiple rows is always more efficient than multiple queries that return one row each. Update a predetermined set of tags (tag groups) To update a predetermined set of tags using a single query, set the tags' InstrumentTag attribute to the path and name of the file that contains the query. This approach is referred to as a tag group. All target tags in the group refer to the same query file and receive the same timestamp when data is returned to them. When defining a tag group, you configure a master tag; that is, a tag, which executes the query, as follows: Location2: To process only the first row returned by the query, set Location2 to 0. To process all rows returned by the query, set Location2 to 1. Location3: Set to 2 if the first column returned by the query is a timestamp; otherwise set to 1. Placeholders: In the ExDesc field of the master tag, define the placeholders required by the query. To specify the value to be assigned to the tag, set each tag's Location3 attribute to the ordinal number of the column returned by the query. For example, define a query that returns the following columns: Timestamp Value1 Status1 Value2 Status2 To update Tag1 with the first value and status and Tag2 with the second value and status, configure the tags as follows: 1. Define a text file containing the query; for example: SELECT timestamp, value1, status1, value2, status2 FROM table1 WHERE timestamp >? ORDER BY timestamp ASC; In the query, each value column must be followed by its associated status. If the RDBMS table does not contain status columns, you can specify the status as a literal ( SELECT timestamp, value1, 0 as status1 ). 2. In each target tag, set its attributes as follows: 46 PI Interface for RDBMS 3.22 User Guide

53 Input processing: updating PI tags from an RDBMS InstrumentTag: Path and name of query file. (Must be the same in all tags in the group.) Location3: Column number from which value is to be read. (Specify 2 for Tag1, and 4 for Tag2.) ExDesc: In the ExDesc attribute of the tag with the lowest Location3, define the placeholders used in the query (e.g. P1=TS) You can also map result columns to tags by specifying aliases in the query, which enables you to order the result columns without maintaining a strict positional correspondence with the value you specify in Location3. The aliases end in a numeric value that corresponds to the value you specify in Location3, but the result column can appear in any position in the query. You can specify the following aliases (where n indicates the numeric value in Location3. PI_VALUEn PI_STATUSn PI_QUESTIONABLEn PI_ANNOTATIONn PI_TIMESTAMPn (use when each value in the result table has its own timestamp column) For example, in the following query, VALUE2 appears before VALUE1. Aliases are used to ensure that each is assigned to the correct PI tag: SELECT timestamp AS PI_TIMESTAMP, value2 AS PI_VALUE2, value1 AS PI_VALUE1, 0 AS PI_STATUS1, 0 AS PI_STATUS2 FROM table1 WHERE timestamp >? ORDER BY timestamp ASC; Reading target tag names from the database (distribution) If the result rows include columns containing the name of the target tags as well as values, you can define a query that updates those tags. This approach is called distribution. In this approach, a distributor tag executes the query, which returns the names of target tags and corresponding values, timestamps, and optionally, status. The target tags are updated with the data from the result set. To configure the distributor tag, you specify its query in the InstrumentTag attribute, placeholders in the ExDesc attribute, and set Location3 to -1. For example, if the database table is composed of the following columns: Timestamp TagName Value Status The following query updates the target tag specified in the TagName column: SELECT timestamp, tagname, value, status FROM table1 WHERE timestamp >? ORDER BY timestamp; If the tag name stored in the RDBMS does not match the name of the target tag in the PI Data Archive, you can map them by specifying the /ALIAS flag in the ExDesc attribute of the target tag. For example, if the result row contains "Tank1" in its "Device" column and you want to store the data from the row in a PI point named "Unit1_Tank1," specify /ALIAS="Tank1". Note that tag name comparisons are not case-sensitive, but aliases are case- sensitive. Distributor and target tags must be in the same scan class unless you specify an alias (using the /ALIAS parameters), in which case the target tag can be assigned to a scan class different PI Interface for RDBMS 3.22 User Guide 47

54 Input processing: updating PI tags from an RDBMS from that of the distributor tag. If the distributor tag is event-based, the scan class (Location4) of all target tags must be set to 0. After the query is executed, the interface sends two events to the distributor tag: The number of events successfully distributed to target tags The number of rows in the result set Both entries are timestamped with the current time; that is, both events appear in the PI archive with the same timestamp. Note: To refer to tags with points sources other than the one specified for the RDBMS interface instance, use PI ICU to enable the Distribute Outside Point Source option on the rdodbc > Optional Parameters tab. Note: For information on PI Point naming conventions, see the Tag (PI point name) section in this document. Process only the most recent values Frequently you want to retrieve only rows that have been added to the table after the last scan was performed. Typically you select timestamps greater than the TS placeholder (the interface's cached value for time of last scan). This works nicely for single and group strategies. For distribution, however, the distributor tag is timestamped with current time, so the comparison does not work with the TS placeholder. If you are using the distribution approach and need to determine whether a row has been processed, you can use one of the approaches shown in the SQL examples section of this document. Verify successful data distribution To verify that all result rows were successfully distributed to the corresponding target tags, check the state of the variable. If the variable is TRUE, one or more tag updates failed. The interface stores the undelivered data, and you can write it to the RDBMS as follows: SELECT timestamp AS PI_TIMESTAMP, name AS PI_TAGNAME FROM table1 WHERE timestamp > GETDATE()-1 ORDER BY name, timestamp; INSERT INTO table2 (name, timestamp, value) VALUES (?,?,?) LOOP; Note: variable is supported only for tag distribution. 48 PI Interface for RDBMS 3.22 User Guide

55 Input processing: updating PI tags from an RDBMS Update from multi-value rows containing name of target points (RxC) To handle result rows that contain data that must be written to several different tags, use the RxC ("row by column") approach, which is a combination of the tag group and distribution strategies. Following is a basic example of a multi-value row, containing one timestamp followed by a series of tag name/value/status sets for each target tag: Timestamp,Name1,Value1,Status1,Name2,Value2,Status2, Multi-value rows might contain a different timestamp for each target tag; for example: Timestamp1,Name1,Value1,Status1,Timestamp2,Name2,Value2,Status2, To distribute the data from such rows to the target tags, you define an RxC distributor tag, setting its Location3 attribute to -2, and define the required SQL query using positional aliases for result columns ( PI_TIMESTAMPn, PI_TAGNAMEn, PI_VALUEn, PI_STATUSn, PI_QUESTIONABLEn, PI_ANNOTATIONn ). If the result row contains only one timestamp, use PI_TIMESTAMP. Distributor and target tags must be in the same scan class unless you specify an alias (using the /ALIAS parameters). After the query is executed, the interface sends two events to the distributor tag: The number of events successfully distributed to target tags The number of rows in the result set Both entries are timestamped with the current time; that is, both events appear in the PI archive with the same timestamp. The following example query returns a result row that can be distributed to target tags that track level, temperature and density for individual tanks: SELECT timestamp AS PI_TIMESTAMP1, 'tag1' AS PI_TAGNAME1, [level] AS PI_VALUE1, 0 as PI_STATUS1, sampletime AS PI_TIMESTAMP2, 'tag2' AS PI_TAGNAME2, temperature AS PI_VALUE2, temperature_status AS PI_STATUS2, sampletime AS PI_TIMESTAMP3,'tag3' AS PI_TAGNAME3, density AS PI_VALUE3, density_status AS PI_STATUS3 FROM table1 WHERE timestamp >? AND key1 = 'Tank1'; Note: To configure the interface to ignore NULLs for the tag group and RxC strategies, go to the PI IUC rdbodbc > Optional Parameters tab and check Ignore Nulls. PI Interface for RDBMS 3.22 User Guide 49

56 Input processing: updating PI tags from an RDBMS 50 PI Interface for RDBMS 3.22 User Guide

57 Output processing: updating an RDBMS with PI data To write values from the PI Data Archive to RDBMS tables, you define output tags, which execute an SQL query or stored procedure containing INSERT, UPDATE or DELETE statements. Output tags can be scanned (Location4 is set to a scan class) or event-driven (SourceTag specifies a tag which, when changed, triggers execution of the query.) For an event-driven output tag, if the query succeeds, the output tag s value is set to the value of its source tag. If the query fails, its value is set to the "Bad Output" digital state. To insert a row to a table, create an output tag with an INSERT query that specifies the target table and a set of placeholders. The OSIsoft Random Simulator interface, which is installed with the PI Server, is a useful source of test data. Insert a row for a single PI point value whenever the source tag snapshot value changes The following example shows how to configure an output tag that takes sine wave values generated by the Random Simulator interface, and inserts a row containing of the timestamp, value and status to a database table. To configure this example, perform the following steps. Procedure 1. To ensure that test data is generated rapidly, launch PI ICU on the PI Server and set scan class 1 of the Random interface to a frequency of five seconds. 2. In your target relational database, create a table called "table1" containing the following columns: Column Name timestamp value status SQL Data Type DateTime Float Int 3. Launch PI System Management Tools, choose Points > PI Point Builder, and define a point called "SINUSOID_TO_RDBMS". Configure its settings as follows: Point Attribute ExDesc Setting /SQL="INSERT INTO table1 (timestamp, value, status) VALUES (?,?,?);" P1=TS P2=VL P3=SS_I Location4 0 SourceTag SINUSOID 4. Start the RDBMS interface and check the log output to verify that your output tag is properly defined. If there are no errors in the point definition, check the RDBMS to verify that values are being written to the table. PI Interface for RDBMS 3.22 User Guide 51

58 Output processing: updating an RDBMS with PI data Write multiple PI values to a single row in a timely manner The interface can output more than one value to a single database row. To configure it, define an INSERT query that takes snapshot values of various tags. Use the 'tagname'/vl placeholder format. For example, the following query takes snapshot values from three different PI Random Simulator interface tags and inserts them to a table for each scan. INSERT INTO table1 (timestamp, value1, value2, value3) VALUES (?,?,?,?); Point Attribute ExDesc Setting /SQL="INSERT INTO table1 (timestamp, value1, value2, value3) VALUES (?,?,?,?);" P1=ST P2='sinusoid'/VL P3='sinusoidu'/VL P4='cdt158'/VL Location4 1 The preceding query writes the following row to a table: Timestamp SINUSOID Value1 SINUSOIDU Value2 CDT158 Value3 01-Oct :00: Oct :15: Oct :30: PI Interface for RDBMS 3.22 User Guide

59 Recovering historical data The RDBMS interface enables you to recover historical data from RDBMS tables to PI tags (input recovery) as well as to send PI Archive data through output tags to tables in RDBMS (output recovery) starting at the specified time. When configured, the interface performs both types of recovery during startup. In addition, you can run the interface in pure recovery mode, specifying the time period for which you want to recover the data; that is, specifying the start and end recovery times. In this mode, the interface reads the source for the specified period, updates the targets by executing the queries and then exits. Input Recovery: RDBMS values to PI Data Archive To copy bulk data from RDBMS tables to PI, you can run the interface in the recovery mode specifying the recovery start time. To ensure that system resources (CPU and memory) are not taxed by queries that retrieve potentially huge amounts of historical data, it is recommended that you specify the Input Recovery Step to let the interface read data in chunks rather than return back one (huge) result set. The following example shows the principle: SELECT timestamp, value, 0 FROM table1 WHERE timestamp >? AND timestamp <=? ORDER BY timestamp ASC; P1=TS P2=TE If the Recovery End Time is left empty, the interface processes the period since the Recovery Start Time till current time and then continues in normal data collection. If the Recovery End Time is populated, the interface processes the interval (for all input points) end then exits. Note: During recovery, provided the Recovery Step is specified, the TS and TE placeholders are dynamically calculated. If the interface continues running after it finished the recovery, the TE placeholder is populated by current time. The next figure shows how the recovery proceeds applying the recovery step. PI Interface for RDBMS 3.22 User Guide 53

60 Recovering historical data Output recovery: PI Archive values to RDBMS To recover data from PI to RDBMS, run the interface in output recovery mode, specifying the Recovery Start Time since when you want to recover the historical events. If the Recovery End Time is specified, the interface exits after it output the data to RDBMS. If no Recovery End Time is entered, the interface recovers the historical events and then continues operating normally. Specify the recovery interval and step size in ICU To configure settings for the data to be recovered, launch PI ICU and go to the rdbodbc >Recovery Parameters tab. Choose input or output processing and specify settings as follows: Recovery Mode: Choose TimeStamp. Recovery Start Time : Specify the beginning of the period to be recovered. Recover End Time: Specify the end of the period to be recovered. If you omit end time, the interface recovers data from the specified start time to the present time and then starts normal data collection. If you specify an end time, the interface recovers data and then exits. Input Recovery Step: To control memory consumption, specify the timespan to be processed as a chunk. The default step size is one day (1d). (Input recovery only) 54 PI Interface for RDBMS 3.22 User Guide

61 Recovering historical data Recovery start and end times can be specified as either absolute or relative times, or you must use the same format for both start and end time; in other words, you cannot specify a relative start time with an absolute end time. To specify an absolute time, use the following format: start-time [, end-time] Where the start and end timestamps are specified in the following format: DD-MMM-YY hh:mm:ss If you omit the end-time, all data up to the present is recovered. Default end time = "*" To specify a relative time, use the following format: [+ -] #units Where units is one of the following: y: years mo: months w: weeks d: days h: hours m: minutes s: seconds t: today at midnight (00:00:00) *: now (current date and time) To configure Input Recovery Step, specify units using the #units syntax. For example, to recover one week at a time, specify 1w. Following are examples of recovery time specifications. Recovery start time Recovery end time Input recovery step Description 01-Jan-00 None specified 30d Absolute start time: recovery starts with data timestamped Jan 1, 2000 and continues to the present time. Data is processed in 30-day chunks. 01-Jan Jan-09 30d Absolute start and end times: data from Jan 1, 2000 through Jan 1, 2009 is recovered in 30- day chunks. *-365d None specified 1d Relative start time: data for the last year is recovered. PI Interface for RDBMS 3.22 User Guide 55

62 Recovering historical data *-365d *-1h 1d Relative start time, relative end time: data for the last year is recovered, stopping an hour before the current time and the interface continues executing the query in real-time operations. As an alternative to specifying an absolute or relative time, you can specify the name of a PI timestamp tag. The snapshot value of the tag is used for the start or end time. RecoveryStart RecoveryEnd 24h Name of the timestamp tags: the snapshot value of the tags is used as the start and end time. The tag must be a timestamp tag. Data is recovered in 24-hour chunks. 56 PI Interface for RDBMS 3.22 User Guide

63 Startup command file for PI Interface for RDBMS Command-line parameters can begin with a forward slash ( /) or with a dash ( -). For example, the /PS=M and -PS=M command-line parameters are equivalent. Configure the RDBMS interface with PI ICU Note: PI ICU requires PI 3.3 or later. 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 ( RDBMSPI.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 RDBMSPI Interface. Procedure 1. From the PI ICU menu, select Interface, then New Windows Interface Instance from EXE, and then Browse to the rdbmspi.exe executable file. Then, enter values for Host PI Data Server, Point Source and Interface ID#. A window such as the following results: 2. Browse to the RDBMSPI.exe executable file. Then, enter values for Host PI Server/ Collective, Point Source, and Interface ID#. Interface name as displayed in the ICU PI Interface for RDBMS 3.22 User Guide 57

64 Startup command file for PI Interface for RDBMS (optional) will have PI- pre-pended to this name and it will be the display name in the services menu. Note: in this example the host PI Data server is martinfrpc2. To configure the interface to communicate with a remote PI Data server, select Connections on 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 window, the interface Type should be rdbodbc. If not, use the dropdown box to change the interface Type to rdbodbc. 3. Click Apply to enable the PI ICU to manage this instance of the RDBMSPI interface. 4. Configure interface-specific settings on the rdbodbc tab, shown in the following figure. A yellow field indicates that an invalid value has been entered, or that a required value has not been entered. 58 PI Interface for RDBMS 3.22 User Guide

65 Startup command file for PI Interface for RDBMS Startup parameters tab for PI Interface for RDBMS File Locations Field Interface Log File SQL Files Directory Global Variables Files Description Full path to the interface specific log file. (/OUTPUT) Required Directory of the SQL statement files. (/SQL) Optional Full path to the global SQL variable file. (/GLOBAL) Optional DSN Settings Field DSN Username Description Data Source Name (/DSN) Required Username for access to RDBMS (/User_ODBC) Required PI Interface for RDBMS 3.22 User Guide 59

66 Startup command file for PI Interface for RDBMS Field Password Description Password for access to RDBMS (/Pass_ODBC). The password is encrypted and stored locally in the directory configured for interface log files (See the /OUTPUT keyword) To enter a new password, click. Successful - Status Range Specify the range of digital states indicating success from the system digital state table. Field Start Code End Code Description Enter the starting location in the system digital state table. (/SUCC1=#) Optional Enter the ending location in the system digital state table (/SUCC2=#) Optional Bad Input - Status Range Specify the range of digital states indicating Bad Input from the system digital state table. Field Start Code End Code Description Enter the starting location in the system digital state table. (/BAD1=#) Optional Enter the ending location in the system digital state table (/BAD2=#) Optional 60 PI Interface for RDBMS 3.22 User Guide

67 Startup command file for PI Interface for RDBMS Recovery parameters tab for PI Interface for RDBMS Recovery Mode Enable/disable recovery mode. Input Processing Field Recovery Start Time Recovery End Time Input Recovery Step Description Specifies the point in time at which recovery begins. Can be an absolute time, a relative time, or the name of a PI timestamp tag. (/Recovery_Time) Optional Specifies the point in time at which recovery ends. Can be an absolute time, a relative time, or the name of a PI timestamp tag. (/Recovery_Time) Optional Specifies the size of chunk in which data is read during recovery, to avoid taxing system resources. Default is one day. Optional PI Interface for RDBMS 3.22 User Guide 61

68 Startup command file for PI Interface for RDBMS Output Processing Field Recovery Start Time Recovery End Time Out of Order Options Description Specifies the point in time at which recovery begins. (/Recovery_Time) Optional Specifies the point in time at which recovery ends. (/Recovery_Time) Optional Specifies how out-of-order data is to be handled, for tags with Location5 set to 1. (/OOO_Options) Optional Optional parameters tab for PI Interface for RDBMS 62 PI Interface for RDBMS 3.22 User Guide

69 Startup command file for PI Interface for RDBMS Field Write Size Cache (# of Events) Write Delay (milliseconds) Maximum Log (# of Files) Maximum Log File Size (mb) Consecutive Errors to Reconnect Failover Timeout (seconds) Direct SQL Execution Laboratory Caching Times are UTC No Input Errors Description When laboratory caching is enabled (/LB), specifies the maximum number of values written in one (bulk) call to the PI Archive; default is events per bulk. This parameter can be used to tune (throttle) the load on the PI Server. /WS=# Default: 10240, Optional) When laboratory caching is enabled (/LB), specifies the write delay (in milliseconds) between bulk writes to the PI archive. Default is 10ms. Used to tune the load on the PI System and the network. (/WD=#, Default: 10, Optional) Maximum number of log files in the circular buffer. The interface starts overwriting the oldest log files when the MAXLOG has been reached. By default, log files are never overwritten. (/MaxLog=#, Optional) Maximum size of the log file in MB. If this parameter is omitted, the default maximum is 20 MB. (/MaxLogSize=#, Default: 20, Optional) Number of consecutive errors that causes the interface to deallocate all ODBC statements and attempt to reconnect to the RDBMS. (/ERC=#, Optional) Specifies how long to wait for query results to return before failing over to the secondary RDBMS server. (/Failover_Timeout=#, Optional) All SQL statements are prepared, bound and executed each time they are scheduled for execution. By default, statements are prepared and bound only once, before the first execution. /ExecDirect Optional Bulk-write events directly to PI Archive. When this option is enabled, the Location5 setting is ignored. Event handling is faster when this option is enabled, and archive mode is ARCREPLACE. (/lb, Optional) Handle timestamps as UTC. If the timestamps in the RDBMS are stored in UTC format, you must enable this setting.(/utc, Optional) Disable writing of the BAD_INPUT, IO_TIMEOUT digital states when an error occurs. /NO_INPUT_ERROR Optional PI Interface for RDBMS 3.22 User Guide 63

70 Startup command file for PI Interface for RDBMS Field Read Before Overwrite Description Check the archive to see if value already exists at the same timestamp. If so, do not overwrite with new value. Affects only points with Location5=1. /RBO Optional Exit Before Reconnect Distribute Outside Point Source Ignore Nulls Scan Class - I/O Rate Tag Exit if connection error occurs. By default, the interface tries to reconnect. (/EBR, Optional) Enable interface to update points with point source other than the one configured for the interface instance. (/DOPS, Optional) Ignore events retrieved from the RDBMS if value is NULL.Prevents writing of the "No Data" system digital state for tag group and RxC distributions when the value column is NULL. (/Ignore_Nulls, Optional) Configure an I/O rate tag and assign a scan class to it. (/TF, Optional) fields 64 PI Interface for RDBMS 3.22 User Guide

71 Startup command file for PI Interface for RDBMS Debug parameters tab for PI Interface for RDBMS Field Debug Settings Additional Parameters Description Specifies level of detail to be logged. (/DEB) This section is provided for any additional parameters that the ICU does not explicitly support. PI Interface for RDBMS 3.22 User Guide 65

72 Startup command file for PI Interface for RDBMS 66 PI Interface for RDBMS 3.22 User Guide

73 Command line parameters for PI Interface for RDBMS The following table lists the interface-specific command line parameters used in the interface startup batch file to configure settings. These parameters are provided for debugging purposes, to help you read the file. To ensure a correctly-formatted file, use the PI Interface Configuration Utility to configure the interface. In addition to interface specific parameters, all UniInt interfaces support a common set of parameters. For details, refer to the PI Universal Interface (UniInt) User Guide ( techsupport.osisoft.com/downloads/all-downloads/all-groups/all-products/all-categories/ Current-Version/uniint/). Parameter /BAD1= # Default: 0 (Optional) /BAD2= # Default: 0 (Optional) /DEB= # Default: 1 (Optional) /DOPS (Optional) Description The beginning of the range in the system digital state table that contains Bad Input status strings. The end of the range in the system digital state table that contains Bad Input status strings. Set logging (debugging) level. The message in the file is prefixed with the [DEB- # ] marker where # is the debug level. Error and warning messages are always printed, regardless of logging level. Use with caution, as verbose logging can bloat log files. Valid levels: 0: No debug output. 1: (Default) Log information about the interface operation, PI and ODBC connections, defined SQL queries, actions taken during the ODBC link re-creation, output tags recovery, and so on. 3: Log raw values received by ODBC fetch calls per tag and scan, to help trace data type conversion issues. 4: Log the actual values just before sending them to PI. Enables the interface to distribute events to tags with point sources other than the point source configured for the instance. By default, rows with tag names that are different from the point source are skipped. Applies only to the tag distribution and RxC strategies. Does not process any alias configured in the ExDesc tag attribute. PI Interface for RDBMS 3.22 User Guide 67

74 Command line parameters for PI Interface for RDBMS Parameter /DSN= dsn_name (Required) Description ODBC data source name. If the interface is installed as a Windows service, you must specify a SYSTEM data source, not a FILE data source. On 64-bit operating systems for 32-bit RDBMSPI, the DSN must be configured using the 32-bit ODBC Administrator, which is located in the following directory: %systemroot%\syswow64\odbcad32.exe For 64-bit RDBMSPI, use the 32-bit ODBC Administrator: %systemroot%\system32\odbcad32.exe /EBR (Optional) /ERC= # (Optional) /ExecDirect (Optional) /Failover_Timeout= # (Optional) /Global= FilePath (Optional) /HOST= host:port (Required) /Ignore_Nulls (Optional) /LB (Optional) Exit if connection problem occurs, do not loop trying to reconnect. By default, the interface attempts to reconnect once a minute. If Windows Services Recovery is enabled, the operating system automatically restarts the interface and the interface performs history recovery to collect any missed data. This approach avoids event queue overflow if the RDBMS is unavailable for long time. However, output recovery reads compressed values from the PI Archive, not snapshots, which means that fewer events are forwarded than during normal data collection. Configures the interface to close all ODBC statements and attempt to re-create the whole ODBC link if the specified number of consecutive errors occurs. Implemented because of the inconsistent behavior of some ODBC drivers with regard to error codes returned. Execute queries using direct execution. If this option is enabled, all SQL statements are prepared and bound before each execution. By default, queries are prepared and bound once. Specify query timeout: fail over to secondary RDBMS if query execution takes longer than the specified time. Specify the file that contains the definitions of the global variables. (Optional) Specifies the host and port of the PI Server to which the interface sends data. Host: Node name of the host node Port: 5450 Do not write the No Data system digital state for tags populated through the tag group and RxC distribution strategies. By default, the interface writes the No Data state if the value column is null. Bulk-write events to PI Archive. More efficient than per-event writing, which is the default, but exception reporting is not performed. 68 PI Interface for RDBMS 3.22 User Guide

75 Command line parameters for PI Interface for RDBMS Parameter /MaxLog= # (Optional) /MaxLogSize= # Default: 20 (Optional) /No_Input_Error (Optional) /OOO_Option=" optionlist " (Optional) /Output= UNC_Path (Required) /Pass_ODBC= password (Optional) /RBO (Optional) Description Specifies the maximum number of log files. When the specified number of files has been created, the interface starts overwriting the oldest log files. By default, there is no limit on the number of log files. Maximum size of the log file in MB. When the log file grows to the specified maximum, a new log file is created. Suppresses writing IO_TIMEOUT and BAD_INPUT status for input tags when a runtime error occurs or the ODBC connection is lost. By default, the interface writes I/O Timeout and uses the current time as the timestamp. Ensures that the interface can use the last timestamp to recover data written after the last scan. For output tags, specifies what kind of out-of-order events trigger SQL query execution. Valid options are append, replace and remove. Specify multiple options as a comma-separated list; for example: /OOO_Option="append,replace" The remove option functions only during interface start-up, not during normal operation. Specify the interface log file name, including its full path. If the path contains spaces, specify the argument in double quotes. /Output="c:\program files\... \rdbmspi.log" To avoid overwriting log files from previous sessions, the interface renames the previous log file to log-file.log;n during startup. To conserve disk space, periodically delete old log files. Specify the password for the ODBC connection. If no password is configured, the user is prompted to enter it before the interface connects to the data source. The password is encrypted and stored locally. To ensure that the password file is loaded, start the interface interactively before configuring it as a Windows service. If the RDBMS does not require a username/password login (for example Microsoft Access), configure a dummy password. Read Before Overwrite: Overwrite existing event with same timestamp only if the new value is different. Tag must have Location5 set to 1. PI Interface for RDBMS 3.22 User Guide 69

76 Command line parameters for PI Interface for RDBMS Parameter /Recovery_Step= # unit Default: 1d (Optional) /Recovery_Time=start-time [,end-time ] /Recovery_Time=start-tag [, end-tag] (Optional) /Recovery= option Default: NO_REC (Optional) Description To manage workload when performing input recovery, specifies the length of time for each chunk that is to be recovered. Specify as a number following by unit (d=days, h=hours, m=minutes, s=seconds). Default is one day. Examples: 10d 5h 30m For recovery, specifies the oldest (and, optionally, the most recent) timestamp to be retrieved from the archive. Specify absolute or relative time in PI format. Enclose in double quotes if the string contains spaces. You can use PI tags to specify start and end times. Examples: /Recovery_Time="*-8 h" /Recovery_Time=*-1d /Recovery_Time=*-1h,* /Recovery_Time="01-Jan-05 15:00:00, 31-Jan-05 15:00:00" Specifies how to handle output tags during startup, if recovery is enabled. Valid options are as follows: TS: Depends on how out-of-order recovery is configured for tag: Location5=0: Perform in-order recovery.starts the recovery from /Recovery_Time="stime time" or from the last snapshot of the output tag, whichever is later. Location5=1: Perform enhanced out-of-order recovery. Recovery starts from the time specified by /Recovery_Time and the interface compares the source and output tag values looking for additions, changes and deletions to the SourceTag. The /OOO_Option parameter specifies the types of SourceTag modifications that are to be processed. NO_REC: No recovery is performed (Default) Note: Editing an output tag triggers recovery for the tag. 70 PI Interface for RDBMS 3.22 User Guide

77 Command line parameters for PI Interface for RDBMS Parameter /SQL= Filepath (Optional) /SUCC1= # Default: 0 (Optional) /SUCC2= # Default: 0 (Optional) /User_ODBC= username (Optional) /UTC (Optional) /WD= # Default: 10 (Optional) /WS= # Default: (Optional) Description Specifies the location of the SQL statement files. If there are spaces in the file path, specify it in double quotes. If this parameter is omitted, the interface requires the query to be specified in the ExDesctag attribute. Specifies the beginning of the range in the system digital state table that contains the "OK value" strings. Specifies the end of the range in the system digital state table that contains the "OK value" strings. Specifies the username for the ODBC connection. If the RDBMS does not require login (for example, Microsoft Access), specify a dummy user name. Handle timestamps using UTC (Universal Time Coordinated) format. If bulk writing (/LB) is enabled, how many milliseconds, to wait between bulk writes to the PI archive. Used for performance tuning. If bulk writing (/LB) is enabled, the maximum number of values writing in a single bulk write to PI archive. Used for performance tuning. Sample RDBMSPI.bat file The following is an example file: REM===================================================================== ====== REM REM RDBMSPI.BAT REM REM Sample startup file for the Relational Database (RDBMS via ODBC) Interface REM REM ========================================================================= == REM REM OSIsoft recommends using PI ICU to modify startup files. REM REM Sample command line REM RDBMSPI.exe PI Interface for RDBMS 3.22 User Guide 71

78 Command line parameters for PI Interface for RDBMS /ps=rdbmspi ^ /id=1 ^ /DSN=Oracle11 ^ /User_ODBC=system ^ /host=piserver1:5450 ^ /f=00:00:05 ^ /f=00:00:10 ^ /f=00:00:15 ^ /Output="C:\Program Files\PIPC\Interfaces\RDBMSPI\Log\RDBMSPI.out" ^ /SQL="C:\Program Files\PIPC\Interfaces\RDBMSPI\SQL\" ^ /DEB=1 ^ /Recovery=TS ^ /Recovery_Time=*-5m REM REM End of RDBMSPI.bat 72 PI Interface for RDBMS 3.22 User Guide

79 Specific considerations for PI Interface for RDBMS Despite the use of ODBC to insulate the interface from variations in RDBMS implementations, some differences occur. ODBC drivers differ in their implementation of the standard, and relational databases differ in functionality, data type support, SQL syntax and so on. Known RDBMS-specific considerations are discussed, but be advised that other differences are certain to exist. Oracle The caveats in this section are known to apply to Oracle7.0; Oracle 8.x, 9i, 10g, 11g; and Oracle RDB. Open statements limitation Some versions of Oracle permit a maximum of 100 open concurrently-prepared statements. The RDBMS issues one SQL statement per tag, so each interface instances can service 100 tags concurrently. If the limit is exceeded, the following error is logged: [S][HY000]: [Oracle][ODBC][Ora]ORA-01000: maximum open cursors exceeded The limit can also be exceeded by cursors that are opened in stored procedures. You can increase this limit for your Oracle server by editing the INIT.ORA file and setting OPEN_CURSORS. However, this is a server-level configuration change, so undertake it with care. As an alternative, consider the following approaches: Use tag grouping. Run multiple instances of the interface. Enable direct execution: In PI ICU, on the rdbodbc >Optional Parameters tab, check Direct SQL Execution. Limiting the number of rows returned To reduce CPU usage, you can limit the number of rows returned by a query using the LIMIT TO clause. For example: Oracle RDB SELECT timestamp,value,status FROM table1 LIMIT TO 10 ROWS; SELECT timestamp,value,status FROM table1 LIMIT TO 10 ROWS WHERE timestamp >? ORDER BY timestamp; Oracle 8.0 (NT) and above SELECT timestamp,value,status FROM table1 WHERE ROWNUM<11; Returning results from stored procedures To create a stored procedure that returns results, you must create the stored procedure and a package, as follows: Create the package PI Interface for RDBMS 3.22 User Guide 73

80 Specific considerations for PI Interface for RDBMS To define a package, issue the CREATE PACKAGE statement. For example: CREATE OR REPLACE PACKAGE mytestpackage IS TYPE gen_cursor IS REF CURSOR; END mytestpackage; Create the stored procedure The following example stored procedure selects rows with a timestamp later than the date argument specified as an input parameter. CREATE OR REPLACE PROCEDURE mytestproc (cur OUT mytestpackage.gen_cursor, ts IN date) IS res mytestpackage.gen_cursor; BEGIN OPEN res FOR SELECT pi_time,pi_value,0 FROM pi_test1 WHERE pi_time > ts; cur := res; END mytestproc; Call the stored procedure To execute the stored procedure, issue the following query: {CALL mytestproc(?)}; P1=TS Microsoft SQL Server Use the DateTime data type For PI timestamps, use the DateTime data type. Do not use the SQL Server Timestamp data type, which is a database-wide unique number that cannot be bound to the interface timerelated placeholders such as TS, LST, and so on. Limiting the number of rows returned To specify the maximum number of rows to be returned, include the TOP clause. For example: SELECT TOP 10 timestamp, value, status FROM table1; Stored procedures: avoiding Invalid Cursor State Error If a stored procedure contains more complex code, such as a combination of INSERT and SELECT statements, issue the SET NOCOUNT ON statement before issuing the queries, to ensure that queries return only data, minus the status information that is usually included. By default, statements like INSERT, UPDATE, DELETE, {CALL} return the number of affected rows, which, when combined with the result set from a SELECT statement, can cause the following errors: "[S][24000]: [Microsoft][ODBC SQL Server Driver]Invalid cursor state" "[S][HY000]: [Microsoft][ODBC SQL Server Driver]Connection is busy with results for another hstmt" Example: CREATE PROCEDURE sp_rdbmspi1 (@name varchar(30),@ts datetime) AS SET NOCOUNT ON INSERT table1 SELECT timestamp, value,0 FROM table2 WHERE Tagname and timestamp 74 PI Interface for RDBMS 3.22 User Guide

81 SQL examples for PI Interface for RDBMS The example suite below shows various approaches for transferring data between the PI Data Archive and an RDBMS. Examples are illustrative and are not installed as part of the interface. To implement the examples: Procedure 1. Store the SQL queries in a text file in a directory that is configured for SQL files on the PI ICU rdbodbc > Startup Parameters tab; alternatively, define the SQL queries in the ExtendedDescriptor of a PI tag. 2. Create the PI points, setting the example-specific attributes as described in the example. 3. For all points in these examples, the following settings apply: Point attribute Location1 Location2 Location3 Location4 Location5 InstrumentTag PointSource SourcePoint Description Interface instance ID 0: Processes only the first row 1: Processes all rows Data distribution strategy: 0: Single -1: Tag Distribution -2: RxC (Row x Column) Scan class number 0: Exception reporting is enabled 1: Exception reporting is turned off 2: Add the same timestamp 3: For tag distribution and RxC - process only newer data Name of the query file Matches point source configured for interface instance For output tags - name of the tag that triggers the execution if its snapshot value changed 4. Create the RDBMS table as specified and populate the table with sample data. In the examples, note that the name of the SQL query files, RDBMS tables, and table column names is up to you. Note: In some examples, the semantic meaning of columns in the SELECT list is predetermined and the interface assumes the first column is a timestamp, second is a value, and third is status. If every column in the SELECT list is aliased using the set of the "PI_" keywords, the meaning of individual columns is determined according to these keywords. PI Interface for RDBMS 3.22 User Guide 75

82 SQL examples for PI Interface for RDBMS SQL examples Example 1: Update a single tag with single value using static key matching This query updates a PI point by reading the first row from a table that contains "Key123" in the key1 column. To ensure that only the first row of the result set is used, set Location2 to 0. SELECT timestamp, value, 0 FROM table1 WHERE key1 =? ORDER BY timestamp ASC; Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options P1="Key123" Location2 First row/all rows 0 (Processes only the first row) Location3 Data distribution strategy 0 (Single) Location4 Scan class 1 Location5 Exception reporting 0 (Exception reporting is enabled) InstrumentTag Name of the query file Example1.SQL PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type timestamp DateTime Date/Time Microsoft Access data type value Real Number-Single Precision key1 Varchar(50) Text(50) Example 2: Update a single tag with most recent values from database This query retrieves all values written to the RDBMS after the last time that values were read. SELECT timestamp, value, 0 FROM table2 WHERE timestamp >? ORDER BY timestamp ASC; Configure the target PI point with the following settings. Point Attribute Description Setting ExDesc Placeholders and options P1=TS Location2 First row/all rows 1 (Processes all rows) Location3 Data distribution strategy 0 (Single) Location4 Scan class 1 Location5 Exception reporting 0 (Exception reporting is enabled) InstrumentTag Name of the query file Example2.SQL 76 PI Interface for RDBMS 3.22 User Guide

83 SQL examples for PI Interface for RDBMS Point Attribute Description Setting PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type Microsoft Access data type timestamp DateTime Date/Time value Real Number-Single Precision Example 3: Update three tags from a single row (group distribution) The following example updates three PI points from a single database row that contains columns with different values. SELECT timestamp, temperature, 0, pressure, 0, level, 0 FROM table3 WHERE key1 LIKE 'Tank1' AND timestamp >? ORDER BY timestamp ASC; Configure the target PI points with the following settings. Point Attribute Description Setting ExDesc Placeholders and options P1=TS Location2 First row/all rows 1 (Processes all rows) Location3 Data distribution strategy Point Tank1_Temperature: 2 Location4 Scan class 1 Point Tank1_Pressure: 4 Point Tank1_Level: 6 Location5 Exception reporting 0 (Exception reporting is enabled) InstrumentTag Name of the SQL file Example3.SQL PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type timestamp Datetime Date/Time Microsoft Access data type temperature Real Number-Single Precision pressure Real Number-Single Precision level Real Number-Single Precision key1 Varchar(255) Text(255) If the query returned two rows contining values (42, 20, 300) and (43, 21, 310), the following table shows how the values get assigned to PI points. PI Interface for RDBMS 3.22 User Guide 77

84 SQL examples for PI Interface for RDBMS Timestamp Point Tank1_Temperature Point Tank1_Pressure 20-Oct :15: Oct :30: Point Tank1_Level Example 4: Update tags from more rows in table since last scan (distribution by tagname) In this example, the database table includes a column (alias) specifying the PI point that is to be updated with the value. SELECT timestamp, alias, value, status FROM table4 WHERE timestamp >? AND key1 LIKE 'Tank1' ORDER BY alias, timestamp; Configure the target PI point with the following settings. Point Attribute Description Setting ExDesc Placeholders and options Distributor point: P1=LST Location2 First row/all rows N/A for distribution Location3 Data distribution strategy Distributor point: -1 Target points: 0 Location4 Scan class 1 Location5 Exception reporting 0 (Exception reporting is enabled) InstrumentTag Name of the SQL file Example4.SQL PointType Data type of PI points Float32 In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type timestamp DateTime Date/Time Microsoft Access data type value Real Number-Single Precision status Smallint Number (Whole Number) alias, key1 Varchar(255) Text(255) Example result set: timestamp alias value status 20-Oct :15:00 Tank1_Temperature 42 NULL 20-Oct :15:00 Tank1_Pressure 20 NULL 20-Oct :15:00 Tank1_Level 300 NULL Given this result set, the interface assigns values to PI points as follows: 78 PI Interface for RDBMS 3.22 User Guide

85 SQL examples for PI Interface for RDBMS Point Value assigned Tank1_Temperature 42 Tank1_Pressure 20 Tank1_Level 300 Example 5: Update tags from more rows in table reading the last hour each scan (distribution by alias) with the /RBO start-up param. set In this example, the database table includes a column (alias) specifying the PI point that is to be updated with the value. In the ExDesc of each target point, there must be the /ALIAS=alias keyword defined. SELECT timestamp, alias, value, status FROM table5 WHERE timestamp > GETDATE() - 1./24. AND key1 LIKE 'Tank1' ORDER BY alias, timestamp; Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options Target points: /ALIAS=T1_Temp /ALIAS=T1_Press /ALIAS=T1_Lev Location2 First row/all rows N/A for distribution Location3 Data distribution strategy Distributor tag: -1 Target points: 0 Location4 Scan class 1 Location5 Exception reporting 1 (Exception reporting is disabled) InstrumentTag Name of the SQL file Example5.SQL PointType Data type of PI points Float32 In the RDBMS, create a table formatted as follows. Column name timestamp value status alias, key1 SQL Server data type DateTime Real Smallint Varchar(255) Example result set: timestamp alias value status 20-Oct :15:00 T1_Temp 42 NULL PI Interface for RDBMS 3.22 User Guide 79

86 SQL examples for PI Interface for RDBMS timestamp alias value status 20-Oct :15:00 T1_Press 20 NULL 20-Oct :15:00 T1_Lev 300 NULL Given this result set, the interface assigns values to PI points as follows: Point Value assigned Tank1_Temperature 42 Tank1_Pressure 20 Tank1_Level 300 Example 6: Update tags from more rows in table considering just the newer timestamps since the last scan (distribution by alias) without the /RBO start-up parameter set In this example, the database table includes a column (alias) specifying the PI point that is to be updated with the value. In the ExDesc of each target point, there is the /ALIAS=alias keyword defined. SELECT timestamp, alias, value, status FROM table6 WHERE timestamp > GETDATE() - 1./24. AND key1 LIKE 'Tank1' ORDER BY alias, timestamp; Configure the target PI point with the following settings. Point Attribute Description Setting ExDesc Placeholders and options Target points: /ALIAS=T1_Temp /ALIAS=T1_Press /ALIAS=T1_Lev Location2 First row/all rows N/A for distribution Location3 Data distribution strategy Distributor point: -1 Target points: 0 Location4 Scan class 1 Location5 Exception reporting Distributor tag: 1 Target points: 3 InstrumentTag Name of the SQL file Example6.SQL PointType Data type of PI points Float32 In the RDBMS, create a table formatted as follows. Column name timestamp value SQL Server data type DateTime Real 80 PI Interface for RDBMS 3.22 User Guide

87 SQL examples for PI Interface for RDBMS Column name status alias, key1 SQL Server data type Smallint Varchar(255) Example result set: timestamp alias value status 20-Oct :15:00 T1_Temp 42 NULL 20-Oct :15:00 T1_Press 20 NULL 20-Oct :15:00 T1_Lev 300 NULL Given this result set, the interface assigns values to PI points as follows: Point Value assigned Tank1_Temperature 42 Tank1_Pressure 20 Tank1_Level 300 Configure the target PI point with the following settings. Example 7: Update tags from more rows in table marking the already-read rows (distribution by alias) This example reads only previously-unread rows from the database. After reading the rows, it sets the table s rowread column to 1 to indicate the rows have been read. In the ExDesc of each target tag, there is the /ALIAS=alias keyword defined. SELECT timestamp, alias, value, status FROM table7 WHERE rowread = 0 ORDER BY alias, timestamp; UPDATE table1 SET rowread = 1 WHERE (rowread = 0 OR rowread IS NULL); Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options Target points: /ALIAS=T1_Temp /ALIAS=T1_Press /ALIAS=T1_Lev Location2 First row/all rows N/A for distribution Location3 Data distribution strategy (distributor) tag only) Location4 Scan class 1 Distributor point: -1 Target points: 0 Location5 Exception reporting 0 (Exception reporting is enabled) PI Interface for RDBMS 3.22 User Guide 81

88 SQL examples for PI Interface for RDBMS Point attribute Description Setting InstrumentTag Name of the SQL file Example7.SQL PointType Data type of PI points Float32 In the RDBMS, create a table formatted as follows. Column name timestamp alias value rowread SQL Server Data Type DateTime Varchar(255) Real SmallInt Example 8: Update points from more rows and columns (RxC row by column distribution using aliases) with SELECT list columns renamed In this approach, each row contains the timestamped sample data for temperature, pressure and level. The individual rows are distributed according to the corresponding alias column. The distributor tag executes the query that retrieves the data and updates the target points. To indicate that the tag is a distributor tag, set Location3 to -2. SELECT timestamp AS PI_TIMESTAMP, aliastemp AS PI_TAGNAME1, temperature AS PI_VALUE1, 0 AS PI_STATUS1, aliaspress AS PI_TAGNAME2, pressure AS PI_VALUE2, 0 AS PI_STATUS2, aliaslev AS PI_TAGNAME3, level AS PI_VALUE3, 0 AS PI_STATUS3 FROM table8 WHERE timestamp >? AND key1 LIKE 'Tank1' ORDER BY timestamp ASC; Configure the target PI point with the following settings. Point Attribute Description Setting ExDesc Placeholders and options Distributor point: P1= ' Tank1_Temperature1 ' /TS Target points: /ALIAS=T1_Temp1 /ALIAS=T1_Press1 /ALIAS=T1_Lev1 /ALIAS=T1_Temp2 /ALIAS=T1_Press2 /ALIAS=T1_Lev2 Location2 First row/all rows N/A for RxC Location3 Data distribution strategy RxC Distributor point: -2 Target points: 0 Location4 Scan class 1 Location5 Exception reporting 0 (Exception reporting is enabled) InstrumentTag Name of the SQL file Example8.SQL 82 PI Interface for RDBMS 3.22 User Guide

89 SQL examples for PI Interface for RDBMS Point Attribute Description Setting PointType Data type of PI points Float32 In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type timestamp DateTime Date/Time Microsoft Access data type temperature Real Number-Single Precision pressure Real Number-Single Precision level Real Number-Single Precision aliastemp, aliaspress, aliaslev, key1 Example result set: Varchar(255) Text(255) PI_TIME STAMP PI_ TAGNA ME1 PI_ VALUE1 PI_ STATUS 1 PI_ TAGNA ME2 PI_ VALUE2 PI_ STATUS 2 PI_ TAGNA ME3 PI_ VALUE3 PI_ STATUS Oct :15:0 0 T1_Tem p T1_Pres s T1_Lev Oct :30:0 0 T1_Tem p T1_Pres s T1_Lev Given this result set, the interface assigns values to PI points as follows: Point Timestamp Value assigned Tank1_Temperature1 20-Oct :15:00 42 Tank1_Pressure1 20-Oct :15:00 20 Tank1_Level1 20-Oct :15: Tank1_Temperature2 20-Oct :30:00 43 Tank1_Pressure2 20-Oct :30:00 22 Tank1_Level2 20-Oct :30: Example 9: Single input with PI annotations The following example updates the point with annotations, timestamp and value read from an RDBMS table. SELECT timestamp AS PI_TIMESTAMP, value AS PI_VALUE, annotation AS PI_ANNOTATION FROM table9 WHERE timestamp >? ORDER BY timestamp ASC; PI Interface for RDBMS 3.22 User Guide 83

90 SQL examples for PI Interface for RDBMS Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options P1=TS Location2 First row/all rows 1 (All rows are processed) Location3 Data distribution strategy 0 (Single) Location4 Scan class 1 Location5 Exception reporting 1 (Exception reporting is turned off) InstrumentTag Name of the SQL file Example9.SQL PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type timestamp DateTime Date/Time Microsoft Access data type value Real Number-Single Precision annotation Varchar(255) Text(255) Note: For storing result sets with annotations, enable PI SDK by setting the interface start-up parameter /PISDK=1. Example 10: Single input with questionable flag The following example updates a point with timestamp, value, status, quality (mapped to the PI questionable flag), and annotation read from an RDBMS table. SELECT timestamp AS PI_TIMESTAMP, value AS PI_VALUE, quality AS PI_QUESTIONABLE FROM table10 WHERE timestamp >? ORDER BY timestamp ASC; Configure the target PI point with the following settings. Point Attribute Description Setting ExDesc Placeholders and options P1=TS Location2 First row/all rows 1 (All rows are processed) Location3 Data distribution strategy 0 (Single) Location4 Scan class 1 Location5 Out-of-order data handling 1 (Exception reporting is turned off) InstrumentTag Name of the SQL file Example10.SQL PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. 84 PI Interface for RDBMS 3.22 User Guide

91 SQL examples for PI Interface for RDBMS Column name Column data type SQL Server data type Microsoft Access data type timestamp Datetime Date/Time value Real Number-Single Precision status Smallint Number-Whole Number quality Smallint Number-Whole Number Example 11: Event-based input The query for this example is executed when the SINUSOID point is changed. To configure an event-based tag, specify the /EVENT=tagname definition in the ExDesc attribute. SELECT timestamp, value, 0 FROM table11 WHERE timestamp >? ORDER BY timestamp; Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options /EVENT=sinusoid, P1=TS Location2 First row/all rows 1 (All rows are processed) Location3 Data distribution strategy 0 (Single) Location4 Scan class 0 (Event driven execution) Location5 Exception reporting 1 (Exception reporting is turned off) InstrumentTag Name of the SQL file Example11.SQL PointType Data type of PI points Float32 In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type timestamp DateTime Date/Time Microsoft Access data type value Real Number-Single Precision Example 12: Event driven outputs to an RDBMS table This example updates the RDBMS when the SINUSOID point receives a new value. INSERT INTO table12 (timestamp, value, status) VALUES (?,?,?); Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options P1=TS P2=VL P3=SS_I Location2 First row/all row N/A for outputs Location4 Scan class 0 (Event driven execution) InstrumentTag Name of the SQL file Example12.SQL PI Interface for RDBMS 3.22 User Guide 85

92 SQL examples for PI Interface for RDBMS Point attribute Description Setting Location5 Exception reporting 1 (Exception reporting is turned off) PointType Data type of PI point Float32 SourceTag Triggering tag SINUSOID In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type timestamp DateTime Date/Time Microsoft Access data type value Real Number-Single Precision status Smallint Number-Whole Number Example 13: Scan based outputs to an RDBMS table To periodically write values to an RDBMS table, use the 'tagname'/vl placeholder. INSERT INTO table13 (alias, timestamp, value, status, quality, annotation) VALUES (?,?,?,?,?,?); Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options P1=" sinusoid " P2= 'sinusoid'/ts P3= 'sinusoid'/vl P4= 'sinusoid'/ss_i P5= 'sinusoid'/qe P6= 'sinusoid'/ann_c Location2 First row/all rows 1 (All rows are processed) Location4 Scan class 1 Location5 Exception reporting 1 (Exception reporting is turned off) InstrumentTag Name of the SQL file Example13.SQL PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. Column name Column data type SQL Server data type timestamp DateTime Date/Time Microsoft Access data type value Real Number-Single Precision status Smallint Number-Whole Number questionable Smallint Number-Whole Number 86 PI Interface for RDBMS 3.22 User Guide

93 SQL examples for PI Interface for RDBMS Column name Column data type SQL Server data type annotation Varchar(255) Text(255) Microsoft Access data type Note: For outputting annotations, enable PI SDK by setting the interface start-up parameter: /PISDK=1 Example 14: Multi-statement query This query maintains one day (GETDATE()-1) of sinusoid events in an RDBMSPI table. At the same time, this point records the number of rows in the given table (COUNT(*)). INSERT INTO table14 (alias, timestamp, value, status, quality) VALUES (?,?,?,?,?); SELECT GETDATE(), COUNT(*), 0 FROM table14; DELETE FROM table14 WHERE timestamp < GETDATE()-1; Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options P1=" sinusoid " P2= 'sinusoid'/ts P3= 'sinusoid'/vl P4= 'sinusoid'/ss_i P5= 'sinusoid'/qe Location2 First row/all rows 1 (All rows are processed) Location3 Data distribution strategy 0 (Single) Location4 Scan class 1 Location5 Exception reporting 1 (Exception reporting is turned off) InstrumentTag Name of the SQL file Example14.SQL PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. Column name timestamp value status quality alias, annotation Column data type SQL Server data type DateTime Real Smallint Smallint Varchar(255) PI Interface for RDBMS 3.22 User Guide 87

94 SQL examples for PI Interface for RDBMS Example 15: Stored procedure call The following query calls a stored procedure instead of directly executing a SELECT statement. Stored procedure: Stored procedure: CREATE PROCEDURE DateTime AS BEGIN SET NOCOUNT ON SELECT timestamp, value, status FROM table15 WHERE timestamp ORDER BY timestamp ASC END Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options /SQL= "{CALL StoredProcedure1(?,?)};" P1=LST P2=ST Location2 First row/all rows 1 (All rows are processed) Location3 Data distribution strategy 0 (Single) Location4 Scan class 1 Location5 Exception reporting 1 (Exception reporting is turned off) InstrumentTag Name of the SQL file Example15.SQL PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. Column name timestamp value status Column data type SQL Server data type DateTime Real Smallint 88 PI Interface for RDBMS 3.22 User Guide

95 Record PI Point database changes The interface can record changes made to the PI Point Database. The managing tag is triggered by modification of a point attribute. The managing point is configured by setting Location4 to either -1or -2. Note: OSIsoft recommends using the PI System auditing features to audit changes to points, rather than this interface. Short form configuration - recording current and previous PI point attribute values When a point with Location4 set to -1 is recognized, the interface expects a subset of the AT.* placeholders in its ExDesc. The INSERT query is executed whenever there was a point attribute change. The keyword /GETPOINTS =pattern (in the ExDesc of the managing point) specifies for which subset of points the changes will be recorded. The pattern syntax follows the one PI SDK's GetPoints () method recohnizes. For example: /GETPOINTS="pointsource='RDBMS*' AND location1='1'" or /GETPOINTS="pointsource='P' OR tag='p2p*'" By default, the interface checks for attribute changes every two minutes. If an attribute is changed twice within two minutes ending with its original value, the interface will NOT record any change. Since RDBMSPI 3.11, the two-minute interval can be modified by specifying the start-up parameter /UPDATEINTERVAL. Short form example: INSERT INTO pi_attributes_modified (tagname, attribute, changedate, changer, newvalue, oldvalue) VALUES (?,?,?,?,?,?); Configure the target PI point with the following settings. Point attribute Description Setting ExDesc Placeholders and options P1=AT.TAG P2=AT.ATTRIBUTE P3=AT.CHANGEDATE P4=AT.CHANGER P5=AT.NEWVALUE P6=AT.OLDVALUE /GETPOINTS=tag='ABC*' Location4 Recording PIPoint changes -1 (Short form) InstrumentTag Name of the SQL file AttributeChanges.SQL PointType Data type of PI point Float32 In the RDBMS, create a table formatted as follows. PI Interface for RDBMS 3.22 User Guide 89

96 Record PI Point database changes Column name tagname attribute changedate changer newvalue oldvalue Column data type SQL Server data type Varchar(1024) Varchar(1024) DateTime Varchar(1024) Varchar(1024) Varchar(1024) Long form configuration Location4= -2 indicates that all AT.* placeholders can be employed. In this mode, the interface does not remember what the previous attribute value was and forwards only the current PI point attributes state to the corresponding RDB table. The overall principles are the same as with the short form. 90 PI Interface for RDBMS 3.22 User Guide

97 Error and informational messages for PI Interface for RDBMS A string RDBMSPI id is pre-pended to error messages written to the message log. RDBMSPI 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. PI message logs for PI Interface for RDBMS 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, refer to UniInt Interface Message Logging or navigate to KB00401 ( 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. Interface-specific output file for PI Interface for RDBMS The interface start-up parameter /OUTPUT=log-file-path redirects the relevant operational information to an interface specific log-file. Together with the specified log-file, the operational messages will always be stored in the PI Message Log on the interface node. Note: If the interface is configured to run under the least-privileged account, make sure the / OUTPUT=log-file-path points to a directory where the least-privileged account has enough rights to create the file. Otherwise the operational messages end up in the PI Message Log only. PI Interface for RDBMS 3.22 User Guide 91

98 Error and informational messages for PI Interface for RDBMS 92 PI Interface for RDBMS 3.22 User Guide

99 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. 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. 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 PI Interface for RDBMS 3.22 User Guide 93