PI Interface for Relational Databases (PI RDBMS)

User Guide
OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com

PI Interface for Relational Databases (PI RDBMS) User Guide

© 2006-2018 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, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset
Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI
BatchView, PI Coresight, PI Data Services, PI Event Frames, PI Manual Logger, PI ProfileView, PI WebParts,
ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks
of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective
owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC
license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as
applicable. OSIsoft, LLC.
Version: 3.21.4
Published: 25 March 2018
Contents

Introduction to the PI RDBMS interface....................................................................... 1

Related manuals.............................................................................................................................................. 1
Supported operating systems..........................................................................................................................1

How the PI RDBMS interface works............................................................................. 3

Loss of connectivity to the RDBMS..................................................................................................................4
Loss of connectivity to the PI Server................................................................................................................4
Error logging................................................................................................................................................... 5

Installing and configuring the PI RDBMS interface........................................................ 7

Prerequisites................................................................................................................................................... 7
Installing the interface.....................................................................................................................................8
Configuring the interface................................................................................................................................ 8
Create trusts................................................................................................................................................8
Create and configure the interface instance............................................................................................... 10
Verify interface startup.............................................................................................................................. 11
Configure the Windows service.................................................................................................................. 11
Enable buffering........................................................................................................................................ 12
Optional configuration...............................................................................................................................12

Configuring PI points for the PI RDBMS interface........................................................ 13

Point attributes.............................................................................................................................................. 13
Tag (PI point name).................................................................................................................................... 13
PointSource (point source)......................................................................................................................... 13
PointType (data type).................................................................................................................................14
Location1 (interface instance).................................................................................................................... 14
Location2 (first row or all rows)..................................................................................................................14
Location3 (distribution strategy)................................................................................................................ 14
Location4 (scan class)................................................................................................................................ 15
Location5 (data archiving and history recovery)......................................................................................... 15
InstrumentTag (SQL query file).................................................................................................................. 16
ExDesc (extended descriptor).................................................................................................................... 16
SourceTag.................................................................................................................................................. 17
Scan........................................................................................................................................................... 17
Shutdown.................................................................................................................................................. 18
ExcMax ExcMin and ExcDev (exception processing)...................................................................................18
Event-based input......................................................................................................................................... 18
Digital tags.................................................................................................................................................... 18

Specifying SQL queries............................................................................................. 21

Query execution............................................................................................................................................ 21
Stored procedures..................................................................................................................................... 22
Checking query execution results...............................................................................................................22
Checking whether tags are updated...........................................................................................................23
Placeholders for replaceable parameters....................................................................................................... 23
Time stamp, value, status, and annotation placeholders definitions...........................................................25
PI point data placeholders..........................................................................................................................25
Placeholder data types...............................................................................................................................27

PI Interface for Relational Databases (PI RDBMS) User Guide iii

Contents

Specifying result columns in SELECT statements.......................................................................................... 29

Fixed-position result columns.................................................................................................................... 29
Aliased result columns...............................................................................................................................29
Data type compatibility................................................................................................................................. 30
Handling NULLs........................................................................................................................................ 30
Annotations............................................................................................................................................... 31
Input tag value and status mapping............................................................................................................... 31
Time stamps.................................................................................................................................................. 33

Input processing: updating PI tags from an RDBMS.................................................... 35

Approaches to data retrieval (distribution strategies).................................................................................... 35
Updating a single tag..................................................................................................................................... 35
Updating a predetermined set of tags (tag groups)........................................................................................36
Reading target tag names from the database (distribution)........................................................................... 37
Processing only the most recent values......................................................................................................38
Verifying successful data distribution.........................................................................................................38
Updating from multi-value rows containing name of target points (RxC)....................................................... 39

Output processing: updating an RDBMS with PI data ................................................. 41

Recovering historical data.........................................................................................43

Input processing: RDBMS to PI System..........................................................................................................43
Output processing: PI Archive to RDBMS...................................................................................................... 45
Recovering out-of-order data........................................................................................................................ 46
Handling events by type................................................................................................................................ 47
Specifying the recovery interval and step size................................................................................................47

Features supported by the PI RDBMS interface .......................................................... 51

Installation checklist for the PI RDBMS interface ........................................................55

Prerequisites................................................................................................................................................. 55
Install and configure the interface instance....................................................................................................55
Create PI points and SQL queries...................................................................................................................55
Configure interface diagnostics (optional)..................................................................................................... 56

PI ICU reference for the PI RDBMS interface .............................................................. 57

Startup Parameters tab................................................................................................................................. 57
Recovery Parameters tab.............................................................................................................................. 59
Optional Parameters tab............................................................................................................................... 60
Debug Parameters tab.................................................................................................................................. 62

Command-line parameters for the PI RDBMS interface .............................................. 63

RDBMS-specific considerations ................................................................................ 69

Oracle........................................................................................................................................................... 69
Microsoft SQL Server.................................................................................................................................... 70

SQL examples..........................................................................................................71
Example 1: Update a single tag with single value using key matching.............................................................71
Example 2: Update a single tag with most recent values from database.........................................................72
Example 3: Update three points from a single row......................................................................................... 72

iv PI Interface for Relational Databases (PI RDBMS) User Guide

 Contents

Example 4: Determining target tag from RDBMS...........................................................................................73

Example 5: RxC (row by column) distribution................................................................................................. 74
Example 6: Single input with PI annotations.................................................................................................. 75
Example 7: Event-based writes to RDBMS..................................................................................................... 75
Example 8: Scan-based writes to RDBMS...................................................................................................... 76
Example 9: Event-based multiple-value write to RDBMS............................................................................... 77
Example 10: Event-based write of annotation data to RDBMS....................................................................... 77
Example 11: Field name aliases...................................................................................................................... 78
Example 12: Tag group fixed column positions...............................................................................................78
Example 13: Tag group arbitrary column position (aliases)............................................................................. 79
Example 14: Tag distribution retrieving target tag name from database........................................................ 80
Example 15: Tag distribution search according to tag's alias.......................................................................... 80
Example 16: Tag distribution marking rows read............................................................................................81
Example 17: Tag distribution storing the latest snapshot................................................................................82
Example 18: Retrieve values for the last hour................................................................................................. 83
Example 19: Tag distribution with aliases in column names........................................................................... 83
Example 20: RxC (row by column) distribution...............................................................................................84
Example 21: RxC (row by column) distribution using a single time stamp.......................................................85
Example 22: Event-based input..................................................................................................................... 85
Example 23: Multi-statement query...............................................................................................................85
Example 24: Stored procedure call................................................................................................................ 86
Example 25: Event-based output................................................................................................................... 87
Example 26: Event-based output write another tag’s data............................................................................. 87
Example 27: Using global variables to set placeholders..................................................................................88
Example 28: Maintain most recent hour of PI point data................................................................................88

Recording PI point database changes........................................................................ 91

Technical support and other resources....................................................................... 93

PI Interface for Relational Databases (PI RDBMS) User Guide v

Contents

vi PI Interface for Relational Databases (PI RDBMS) User Guide

Introduction to the PI RDBMS interface
The PI Interface for Relational Databases enables you to transfer data between the PI System
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
For efficiency, the interface supports several approaches for retrieving data. For details, see
Approaches to data retrieval (distribution strategies).

Related manuals
• RDBMS interface quickstart in the OSIsoft Knowledge Base
• PI Server manuals
• PI API and SDK help
• YouTube videos in the OSIsoft Learning Channel
• Database vendor’s ODBC driver manual
• UniInt Interface User Manual
• Microsoft ODBC Programmer's Reference

Supported operating systems

Platforms: (32-bit or 64-bit in emulation mode)

• Windows XP SP3 and later

• Windows 2003 Server
• Windows Vista
• Windows 2008 and Windows 2008 R2 Server
• Windows 7
• Windows 8
• Windows 2012 Server
No 64-bit builds of the interface are available.

PI Interface for Relational Databases (PI RDBMS) User Guide 1

Introduction to the PI RDBMS interface

2 PI Interface for Relational Databases (PI RDBMS) User Guide

How the PI RDBMS interface works
To read data from an RDBMS into the PI System, you define input tags, which are associated
with SELECT queries that return columns containing values for the following tag attributes:

• Timestamp
• Value
• Status
• Annotation (optional)
To write data from the PI System 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 System, 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 time stamp, value, status and (optionally) annotation, but no PI tag
name. For details, see Updating a single tag.
• 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 Updating
a predetermined set of tags (tag groups)
• 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 Updating from multi-value rows containing name of target
points (RxC).
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 System. 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. The following figure illustrates a typical
configuration, with the PI Server, RDBMS and interface running on different nodes.

PI Interface for Relational Databases (PI RDBMS) User Guide 3

How the PI RDBMS interface works

Loss of connectivity to the 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 Recovering
historical data. For details about increasing the size of the event queue, see the PI Server
documentation.

Loss of connectivity to the 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

4 PI Interface for Relational Databases (PI RDBMS) User Guide

 How the PI RDBMS interface works

replaceable parameters in SQL queries. If buffering is enabled, queries without placeholders

continue collecting data, and queries with placeholders report an error.

Error logging
Messages are logged to the local PI message log during interface startup, data collection and
recovery. Additional messages are logged if you enable debugging. The log also lists messages
from the UniInt framework and PI API (on which this interface is based), and from the
buffering program. To view the message log, use the PI System Management Tools (PI SMT)
Operation > Message Logs feature.
For detailed information about interface logging, see the following OSIsoft Knowledge Base
topic How to read new UniInt 4.5.0.x and later Interface message logs (now in PI Message Log,
not PIPC.log) (https://customers.osisoft.com/s/knowledgearticle?
knowledgeArticleUrl=KB00401).
For details about managing the error logging process, see the PI API Installation Instructions
(https://customers.osisoft.com/s/productcontent?id=a7R1I000000XyTuUAK) user guide.

PI Interface for Relational Databases (PI RDBMS) User Guide 5

How the PI RDBMS interface works

6 PI Interface for Relational Databases (PI RDBMS) User Guide

Installing and configuring the PI RDBMS interface
This section provides detailed instructions for installing and configuring the interface. A
minimum functional configuration is described, which you can adjust according to your
requirements. For details about features that are common to all UniInt interfaces, refer to the
UniInt Interface User Manual.
To maximize performance and minimize contention for system resources, install the interface
on a dedicated node, running as a Windows service. Alternately, consider running the interface
on the computer where the RDBMS is running. This configuration ensures that the interface
cannot lose its connection to the RDBMS as the result of network issues. If you install the
interface on a PI Server node, configure the interface service to depend on the PI Update
Manager and PI Network Manager services. Buffering is not typically enabled on the PI Server
node, but you can enable it so that interfaces running on the PI Server node do not need to be
started and stopped in conjunction with the PI Server.
For maximum efficiency in handling a mixture of input points and output points (that is, points
that update the PI System from an RDBMS and vice versa), configure separate interface
instances, one for inputs and another for outputs.

Prerequisites
Before installing and configuring, ensure that the following requirements are met.
OSIsoft prerequisites

• Verify that the PI Server is up and running.

• Confirm that you can use PI SMT to configure the PI Server. You need not run PI SMT on the
same computer on which you run this interface.
• Verify that the system time and time zones settings for the interface node, RDBMS host and
PI Server host are correct.
• On the interface node, install the following:
◦ PI Prerequisites
◦ PI Interface Configuration Tool (ICU)
◦ ODBC driver for the target RDBMS
◦ Microsoft Data Access Components (MDAC). Ensure that the most recent version is
installed on the interface node. To download MDAC, go to the Microsoft Developers
network web site: http://msdn.microsoft.com.
• If you require support for PI annotations, enable the PI SDK using PI ICU (go to the UniInt >
PI SDK tab) and define an SDK trust for the interface.
RDBMS prerequisites

• Verify that the RDBMS is running, populated with any required data, and is accessible using
ODBC. To test connectivity and validate the syntax of SQL queries, you can use the Microsoft
ODBC Test application.
• Ensure that the ODBC driver is correctly configured, as follows:

PI Interface for Relational Databases (PI RDBMS) User Guide 7

Installing and configuring the PI RDBMS interface

◦ The ODBC driver, client and any necessary database client software must be configured
in the system path.
◦ The ODBC driver must support Level 1 API conformance, which consists of the Core
interface conformance level functionality plus additional features such as transactions
that are usually available in an OLTP relational DBMS.
◦ The ODBC data source must be defined as a system data source name. On 64-bit
operating systems, configure the DSN using the 32-bit ODBC Administrator, which is
located in %systemroot%\syswow64\odbcad32.exe.

Installing the interface

To install the interface, download the interface setup kit from the OSIsoft web site and run it on
the computer where you intend to run the interface. To avoid contention for system resources,
install the interface on a dedicated computer other than the PI Server node. By default, the
interface is installed in the %PIHOME%\Interfaces\RDBMSPI\ directory. The %PIHOME%
directory, which is the root directory under which OSIsoft products are installed, is defined by
the PIHOME entry in the pipc.ini configuration file in the %windir% directory. To override the
default locations, edit the pipc.ini configuration file.
Note:
Reserve the C: drive for the operating system and install the interface on another drive.
For details about features that are common to all UniInt interfaces, refer to the UniInt Interface
User Guide.

Configuring the interface

The following sections describe in detail the tasks necessary to configure the PI RDBMS
interface.

Create trusts
To provide the interface with access to the PI Server, you must define trusts. When creating
trusts for PI interfaces, you have many options. For detailed information about trusts and PI
System security, refer to the PI Server System Management Guide.
Following is a simple and secure approach, creating a trust for the following applications:

• RDBMSPI interface
• PI Interface Configuration Utility (ICU)
• Buffering
To create each of these trusts using PI System Management Tools, connect to the PI Server and
perform the following steps:

Procedure
1. Click Security and choose Mappings & Trusts.
2. On the Trusts tab, right-click and choose New Trust. The Add Trust wizard is launched.

8 PI Interface for Relational Databases (PI RDBMS) User Guide

 Installing and configuring the PI RDBMS interface

3. Specify a meaningful name and description.

4. Configure settings as follows: For the PI user associated with a trust, you can maximize
security by assigning them the minimum PI Server permissions required to run the
application.
Trusts Type Application Network path PI user
information:
name
PI RDBMS PI-API application RDBME (default) Fully qualified Data owner of the
interface name of the PI RDBMS tags
interface node or ◦ Write
IP address plus permissions:
netmask If buffering
255.255.255.255 is not
enabled,
assign
DataSecurity
write
permission.
(If buffering
is enabled,
assign no
write
permission.)
◦ Read
permissions:
Assign
PIPOINT
DBSecurity
and
PtSecurity
read
permissions.
If the
interface
maintains
output
points, also
assign
DataSecurity
read
permission.
PI ICU PI-API application PI-ICU.exe Fully qualified Dedicated PI
name of the identity
interface node or
Required
IP address plus
permissions:
netmask
255.255.255.255 ◦ database
read access
◦ read
ptsecurity
◦ read-write
for relevant
points

PI Interface for Relational Databases (PI RDBMS) User Guide 9

Installing and configuring the PI RDBMS interface

Trusts Type Application Network path PI user

information:
name
Buffering PI-API application BufServ: APIBE Fully qualified Data owner of the
name of the PI RDBMS tags
PIBufss:
interface node or ◦ Write
PIBufss.exe
IP address plus permissions:
netmask If buffering
255.255.255.255 is enabled,
assign
DataSecurity
write
permission.
◦ Read
permissions:
None

Create and configure the interface instance

For each RDBMS server intended to exchange data with the PI System, you must create at least
one instance of the interface. For each instance you create, settings are stored in a separate
Windows command file (a .bat file) in the interface installation directory.
Note:
If you require multiple instances of the interface, configure them with unique interface
IDs and point sources, to ensure that you know where the data written to the PI server
originated and to more easily trace any problems that arise. This approach also speeds up
interface startup.
To create an instance of the interface, perform the following steps:

Procedure
1. Launch PI ICU.
2. Choose Interface > New Windows Interface Instance from BAT File. The Open Interface
Configuration File dialog is displayed.
3. Browse to the directory where the interface is installed (the default is %PIPC%\Interfaces
\RDBMSPI), select RDBMSPI.bat_new and click Open. The Select PI Host Server dialog is
displayed.
4. Specify the PI Server and click OK. ICU displays the settings of the new instance of the
interface.
5. On the General tab, edit the basic settings as follows.
◦ Point source: "RDBMS" or a point source not already in use
◦ Interface ID: 1 or a numeric ID not already in use
◦ Scan class: Configure desired scan frequency. Note that, when defining scan classes, you
can spread the server workload using offsets, to ensure that all scans do not occur at the
same time.
6. Configure interface-specific settings on the rdbodbc tab. See PI ICU reference for the PI
RDBMS interface for more information.

10 PI Interface for Relational Databases (PI RDBMS) User Guide

 Installing and configuring the PI RDBMS interface

Verify interface startup

You can use the message log to check for proper startup of the interface.

Procedure
1. To display the message log, launch PI System Management Tools and choose the Operation
> Message Logs menu option.
2. To start the interface using PI ICU, choose Interface > Start Interactive.
PI ICU displays a command window and invokes the startup batch file, and you can observe
progress as the interface attempts to initialize and run.
3. Watch log for messages indicating success or errors.
4. To stop the interface, close the command window.

Configure the Windows service

To ensure that the interface restarts when the interface node is restarted, configure it as a
Windows service. To install the interface as a service using PI ICU, perform the following steps:

Procedure
1. Launch PI ICU and click the Service tab in the PI ICU window.
2. Set Startup Type to Auto.
3. Set the fields as described in the following table.
Field Description
Service name Descriptive name of the interface service.
ID Numeric ID of the interface instance. Must be unique for each instance.
Display name The service name displayed in the Windows Services control panel. The default
display name is the service name with a PI- prefix. You can override the default. To
ensure that OSIsoft-related services are sorted together in the Services control
panel, retain the PI- prefix.
Log on as The Windows account associated with the service. Set password expiration to
Never.
Password Password, if any, for the preceding user.
Dependencies Any services that the interface depends on. The only dependency is the TCP/IP
service, which is pre-configured. If buffering is enabled, you are prompted to create
a dependency on the buffering service.
Startup type Specifies whether the interface service starts automatically when the interface node
is restarted. Generally, interface services are set to start automatically.

4. To create the service, click Create.

5. To start the service, click .

PI Interface for Relational Databases (PI RDBMS) User Guide 11

Installing and configuring the PI RDBMS interface

Enable buffering
This is a summary of how to start buffering. For detailed information about buffering, refer to
the PI Buffering User’s Guide.

Procedure
1. In ICU, choose Tools > Buffering. The Buffering dialog is displayed.
2. Click Enable buffering with PI Buffer Subsystem, then click Apply.
3. To start the buffering service, click PI Buffer Subsystem Service, then click .

4. To verify that buffering starts successfully, check the message log for messages indicating
that the buffering application connected to the PI Server. To verify that the configuration is
working as intended, reboot the interface node and confirm that the interface service and
the buffering application restart.

Optional configuration
The following are useful, but not required:
Note:
For details, consult the UniInt Interface User’s Guide.

• Configure diagnostics
Diagnostic PI points enable you to track the activity and performance of the interface.
• Configure disconnected startup
Disconnected startup enables the interface to start and collect data if the PI server is not
available.
• Configure failover
Failover enables the PI System to switch to another copy of the interface if the currently-
running instance fails.
• Install the PI Interface Status Utility
This utility enables you to monitor the state of the interface. For details, see the PI Interface
Status Utility (ISU) User Manual.

12 PI Interface for Relational Databases (PI RDBMS) User Guide

Configuring PI points for the PI RDBMS interface
The PI tag (also called a "point") is a time-stamped record of a single set of measurements (for
example, the temperature of tank 100, recorded at five-minute intervals). If the value is not
good, the point is assigned a digital state that reflects the problem with the data instead. If you
need to record both the value and this state, use two tags.
To create and edit tags, use PI Point Builder, one of the options in PI System Management Tools.
For creating large numbers of tags, use the PI Tag Configurator add-in for Microsoft Excel.

Point attributes
The point attributes are used to indicate how the interface uses the point. You set them when
configuring points to be read or written by the interface. For example point configurations,
refer to SQL examples.

Tag (PI point name)

When assigning names to PI points, follow these rules:

• The point name must be unique.

• The first character must be alphanumeric, underscore (_), or percent sign (%).
• Control characters such as linefeeds or tabs are illegal, as are the following characters:
* ’ ? ; { } [ ] | \ ` ‘ "
The following table indicates the maximum length of the length attribute, which depends on
the combination of PI API and PI Server that you have installed.
PI API PI Server Maximum Length
1.6.0.2 or higher 3.4.370.x or higher 1023
1.6.0.2 or higher Below 3.4.370.x 255
Below 1.6.0.2 3.4.370.x or higher 255
Below 1.6.0.2 Below 3.4.370.x 255

If your PI Server is earlier than version 3.4.370.x or the PI API version is earlier than 1.6.0.2
and you want to create points with names that exceed 255 characters, you must enable the PI
SDK.
Note:
If the source point name length exceeds 80 characters, you must use the UserInt1
attribute for source point mapping, due to a limitation of the PI API.

PointSource (point source)

PointSource is an identifier that associates a PI point with a PI interface instance, enabling
the interface to query the PI Server for the points that it updates. This field is not case-

PI Interface for Relational Databases (PI RDBMS) User Guide 13

Configuring PI points for the PI RDBMS interface

sensitive. 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 Reserved By
T Totalizer Subsystem
G and @ Alarm subsystem
R 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 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. For details about these data distribution strategies, see Approaches to
data retrieval (distribution strategies).

Location3 (distribution strategy)

For input points, Location3 configures how retrieved data is to be assigned to the tag.
Distribution strategy Location3
Column number of the result to be assigned to this tag Positive number
(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 -2
aliases in result set)

14 PI Interface for Relational Databases (PI RDBMS) User Guide

 Configuring PI points for the PI RDBMS interface

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 Recording PI point database changes.

Location5 (data archiving and history recovery)

The Location5 attribute configures exception reporting and the handling of events with
duplicate time stamps. For output points, it configures how events are recovered from the PI
Archive to an RDBMS. For details about recovery, see Recovering historical data.
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-of-
order data handling for a tag. If the PI Archive
already contains an event with the same time
stamp 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. If you
set Location5 to 2, you risk the possibility of
multiple events with the same time stamp.

• Output points
To configure handling of out-of-order data for an output point, set Location5 as follows:
Value Description
-1 Disable out-of-order data recovery for a tag
(query is not executed)
0 Enable out-of-order data handling and output
recovery for new events. Out of order data errors
are logged as -109 errors in the PI message log.
1 Enable enhanced out-of-order data processing
(per-event-type handling)

• Events

PI Interface for Relational Databases (PI RDBMS) User Guide 15

Configuring PI points for the PI RDBMS interface

To enable out-of-order data handling for specific types of events, set the desired options
using PI ICU, on the rdbodbc > Recovery Parameters tab. To define queries that handle
events according to their type, define the query using the @source options for new,
replacement and deletion events. For example:
IF @source_appended INSERT INTO table (…);
IF @source_replaced UPDATE table SET column1 = ? …;
IF @source_removed DELETE table WHERE column1 <= ?;

The @source options are supported only for output tags. For details about handling events
on a per-type basis, see Handling events by type.
The interface recovers events from the archive during startup and output recovery. By
default, only new events are recovered. To enable recovery of replacement and deletion
events using PI ICU, set the desired options on the rdbodbc > Recovery Parameters tab. In
real-time mode, deletion events are not processed.

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.
Note:
The maximum length of the InstrumentTag attribute depends on the versions of the PI
Server and API in use. If PI API is version 1.6.0.2 or higher and PI Server is 3.4.370.x or
higher, the maximum length is 1023. For all lower versions, the maximum is 32. If the PI
Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and
you require more characters, enable the PI SDK.

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 /ALIAS=Level321_inor/
names in the RDBMS. Case-sensitive. ALIAS="Tag123 Alias"
For details about configuring aliases,
(Use double quotes for names that
see Reading target tag names from
contain spaces)
the database (distribution).
SQL Specify the query for the tag. Enclose /SQL="SELECT Timestamp,
the query in double quotes and Value, status FROM Table
terminate it with a semicolon, WHERE Timestamp >?;" P1=TS
followed by any placeholders,
separated by white space. For details
examples of queries, see SQL
examples.

16 PI Interface for Relational Databases (PI RDBMS) User Guide

 Configuring PI points for the PI RDBMS interface

Keyword Description Example

TRANSACT If more than one SQL statement is /TRANSACT
specified for the tag, the queries are
executed as a single transaction
(committed or rolled back together).
TRIGorEVENT For event-driven input points: each /EVENT=sinusoid, …
time the specified point changes, the
or
SQL query is executed. If the point
name contains spaces, you must /EVENT=sinusoid anychange, …
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 event-
driven points, refer to the UniInt
Interface User’s Guide.

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. For a
detailed explanation, see Placeholders for replaceable parameters.
To designate a performance point, set ExDesc to PERFORMANCE_POINT. For details, refer to the
PI Interface for Performance Monitor user’s guide.
Note:
The maximum length of the ExDesc attribute depends on the versions of the PI Server
and API in use. If PI API is version 1.6.0.2 or higher and PI Server is 3.4.370.x or higher,
the maximum length is 1023. For all lower versions, the maximum is 80. If the PI Server
version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you
require more characters, enable the PI SDK.

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

Scan
This attribute enables or disables data collection for the PI point. By default, data collection is
enabled (Scan is set to 1). To disable data collection, set Scan to 0. If the Scan attribute is 0
when the interface starts, the interface does not load or update the point. If you enable
scanning while the interface is running, the time required for data collection to start depends
on how many points you enable, because they are processed in batches. For efficiency, if you
need to enable scanning for a large number of points, stop and restart the interface. If a point
that is loaded by the interface is subsequently edited so that the point is no longer valid, the
point is removed from the interface and SCAN OFF is written to the point.

PI Interface for Relational Databases (PI RDBMS) User Guide 17

Configuring PI points for the PI RDBMS interface

Shutdown
By default, the PI Shutdown subsystem writes the SHUTDOWN digital state to all PI points when
PI Server is started. The time stamp that is used for the SHUTDOWN events is retrieved from a
file that is updated by the snapshot subsystem. The time stamp is usually updated every 15
minutes, which means that the time stamp for the SHUTDOWN events is accurate to within 15
minutes in the event of a power failure. For additional information on shutdown events, refer
to PI Server 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.
To prevent SHUTDOWN events from being written when PI Server is restarted, set the Shutdown
attribute to 0. To configure the PI shutdown subsystem to write SHUTDOWN events only for PI
points that have their Shutdown attribute set to 1, edit the \\PI\dat\Shutdown.dat file, as
described in PI buffering documentation.

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 Server.
• ExcMin: The minimum time period between values sent to the PI Server.
• ExcDev: The minimum change from the last value sent to the PI Server 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.

Event-based input
Input points can be event-based: whenever the snapshot value of a trigger tag changes, an
event is generated and the SQL statement gets executed. To configure the trigger tag, specify /
EVENT=TagName or /TRIG=TagName in the input tag's extended descriptor attribute. For
details about defining trigger tags and specifying conditions for them, refer to UniInt Interface
User’s Guide.

Digital tags
To store values from a digital output tag in the RDBMS, you must define the target column
using a string data type. The following table shows how value placeholders for a digital tag are
evaluated:

18 PI Interface for Relational Databases (PI RDBMS) User Guide

 Configuring PI points for the PI RDBMS interface

Digital state in range of bad VL Field type string SS_I integer or float SS_C field type string
inputs?
No <Digital State String> 0 "O.K."
Yes <Digital State String> 1 "Bad Value"

PI Interface for Relational Databases (PI RDBMS) User Guide 19

Configuring PI points for the PI RDBMS interface

20 PI Interface for Relational Databases (PI RDBMS) User Guide

Specifying SQL queries
The SQL query that is associated with a tag determines how data is written to PI tags or the
RDBMS. SQL queries can be specified in either of two ways:

• In the extended descriptor (ExDesc) attribute of a PI tag.

• In text files residing in a query file directory that is configured for the interface instance
using PI ICU. To specify a query in the extended descriptor attribute, precede it with
the /SQL flag, terminate it with a semicolon, and enclose it in double quotes. (You must
specify the /SQL keyword in uppercase letters.) Typically, query files have a .SQL extension,
but there is no required naming convention.
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 Table
WHERE Timestamp > ?
ORDER BY Timestamp;" P1=TS

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. In query files,
omit the /SQL flag. For example:

• MYQUERY.SQL is a text file that contains the following query:

SELECT Timestamp, Value, Status
FROM Table
WHERE Timestamp > ?
ORDER BY Timestamp;
• InstrumentTag: MYQUERY.SQL
• ExDesc: P1=TS
Note:
The PI System expects data to arrive in chronological sequence. To ensure that data
arrives in chronological sequence, use the ORDER BY clause to sort by time stamp.
To create output tags, specify an INSERT, UPDATE or DELETE query. The following example
shows a query that creates a row containing the tag’s name, time stamp and value:
INSERT INTO TestTable (tag,time,value) VALUES (?,?,?);
P1=AT.TAG P2=TS P3=VL

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

PI Interface for Relational Databases (PI RDBMS) User Guide 21

Specifying SQL queries

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.
By default, each statement in a multi-statement query is committed separately (AUTOCOMMIT).
To execute all statements in a single transaction, specify the /TRANSACT keyword in the
ExDesc attribute. If all statements succeed, the transaction is committed. If any statement fails,
all statements are rolled back.
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 Example 24: Stored procedure call.

Checking query execution results

To detect whether a query succeeded, check the following variables:

• @query_success: TRUE if query succeeded (all values written to PI System), FALSE if query
failed
• @query_failure: FALSE if query succeeded, TRUE if query failed
You can define an IF statement that conditionally issues a single SQL statement depending
on the state of the variable. For example:

22 PI Interface for Relational Databases (PI RDBMS) User Guide

 Specifying SQL queries

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 Table WHERE Timestamp > ? ORDER BY Timestamp;
IF @query_failure
INSERT INTO Table2 (Timestamp, Tag, 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 variables:

• @write_success: TRUE if query succeeded (all values written to PI System), FALSE if update
failed.
• @write_failure: 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 Table WHERE Timestamp > ? ORDER BY Timestamp;
P1=TS
IF @write_success DELETE FROM Table WHERE Timestamp <= ?;

To determine whether tag distribution succeeded, you must use the @rows_dropped 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 Table
(name, instant, ColFloat, 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. When specifying placeholders, separate them with
spaces or tabs (white space); for example:

PI Interface for Relational Databases (PI RDBMS) User Guide 23

Specifying SQL queries

P1=TS P2=VL P3=ANN_C

Specify placeholders in the tag that executes the query, as follows:

Data handling method Tag that defines placeholders
Single Single tag
Distribution Distributor tag
Group Master tag
RxC Tag list

For string constant placeholders, specify the argument in double quotes; for example:
P1="MYTAGNAME"

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 define frequently-used placeholders or to define a large number of placeholders, you can
create a global variables file. To use PI ICU to configure the name of the global variables file to
be used by the interface instance, go to the rdbodbc > Startup Parameters tab and set the
Global Variables File field. The syntax of global variables is the same as local placeholders, but
global placeholder names start with G instead of P.
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 Placeholders
VL SS_I SS_C
Float, Timestamp, No error <Value> 0 "O.K."
Integer, String Error < Previous Value> <Digital State String> <Digital State String>
Digital Digital state is in the <Digital State String> 0 "O.K."
range of success
statuses
Digital state is in the <Digital State String> 1 "Bad Value"
range of "bad"
statuses

To configure the value to be used when no value exists at the specified time stamp, set the mode
parameter as follows:
'tagname'/VL('timestamp',mode)

For output tags, the time stamp is usually the time from the source tag event. If a value exists at
the specified tim estamp, the value is used. Valid values for the mode parameter are as follows:
Mode Value used
Previous The first value before the specified time
Next The first value after the specified time. Specified time
cannot exceed snapshot time.
Interpolated Interpolated value at the specified time

24 PI Interface for Relational Databases (PI RDBMS) User Guide

 Specifying SQL queries

Time stamp, 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. 1023
characters
ANN_I and 'tagname' /ANN_I Annotation number (integer)
ANN_R and 'tagname' /ANN_R Annotation number (float)
ANN_TS and 'tagname' /ANN_TS Annotation time stamp
LET 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.
LST Last scan time
SS_C and 'tagname' /SS_C Current status digital code string. For valid events,
SS_C is set to "O.K." Max. 79 characters
SS_I and 'tagname' /SS_I Current status integer representation
ST Scan time
Input: Start of new scan for a scan class
Output: Time of output event

TE Time stamp end. Used for recovery mode

TS and 'tagname' /TS Time stamp. For input tags, the timestamp is taken
from the interface’s internal snapshot
VL and 'tagname' /VL(‘timestamp’, mode) 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 () Description
AT.TAG Tag name of the current tag Max. 1023 characters
AT.DESCRIPTOR Descriptor of the current tag Max. 1023 characters

PI Interface for Relational Databases (PI RDBMS) User Guide 25

Specifying SQL queries

Placeholder keywords for ExDesc () Description

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

26 PI Interface for Relational Databases (PI RDBMS) User Guide

 Specifying SQL queries

Placeholder keywords for ExDesc () Description

AT.USERINT1,2 UserInt1, UserInt2
AT.USERREAL1,2 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 SQL Data Type
AT.ATTRIBUTE SQL_VARCHAR
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"

PI Interface for Relational Databases (PI RDBMS) User Guide 27

Specifying SQL queries

Attribute SQL Data Type

AT.DIGSTARTCODE First choice: SQL_INTEGER
AT.DIGNUMBER Second choice: SQL_FLOAT
AT.LOCATION1 Third choice: SQL_DOUBLE
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

Snapshot Placeholders
Placeholder SQL (ODBC) Data Type
First choice Second choice
ST SQL_TIMESTAMP
TS
LET
LST ANN_TS

VL floating point and time SQL_DOUBLE SQL_FLOAT

stamp tags
integer tags SQL_INTEGER SQL_FLOAT
digital tags SQL_VARCHAR
string tags SQL_VARCHAR
SS_I, ANN_I SQL_INTEGER SQL_FLOAT

28 PI Interface for Relational Databases (PI RDBMS) User Guide

 Specifying SQL queries

Placeholder SQL (ODBC) Data Type

SS_C, ANN_C SQL_VARCHAR
ANN_R SQL_REAL SQL_FLOAT

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 time stamp
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 time stamp/value/status
sequence. For example:
SELECT Timestamp, Value, Status FROM Table…

The time stamp column is optional. If you omit the time stamp, 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 Table…

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_TIMESTAMP
• PI_VALUE
• PI_STATUS
• PI_ANNOTATION
For example:
For example:
SELECT Timestamp AS PI_TIMESTAMP, Value AS PI_VALUE, Status AS PI_STATUS,
Annotation AS PI_ANNOTATION FROM…

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.
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 Updating a
predetermined set of tags (tag groups).

PI Interface for Relational Databases (PI RDBMS) User Guide 29

Specifying 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:
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 SQL data type.
For example, the following expression converts the output of the CURDATE() function to a
string:
{Fn CONVERT({Fn CURDATE()},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(64)), Status FROM…

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, which is
available from the MSDN web site (http://msdn.microsoft.com/en-us/library/
ms714177.aspx).

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.

30 PI Interface for Relational Databases (PI RDBMS) User Guide

 Specifying SQL queries

Annotations
PI annotations can handle any data type returned by a query. The interface treats the column
that contains annotations as one of the following data types:

• DateTime (time stamp)

• Approximate (floating-point)
• Exact (integer)
• String (characters)

Input tag value and status mapping

Your input queries deliver data, which are stored in the following PI data archive columns:

• Time stamp
• Tag value
• Status
• Annotations
To ensure that SQL data types are compatible with data types supported in PI Server, 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.

• Time stamp
The result column must have a data type of DATETIME 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 RDBMS data Target PI point data type
type type
Float Integer Digital String

PI Interface for Relational Databases (PI RDBMS) User Guide 31

Specifying SQL queries

ODBC data RDBMS data Target PI point data type

type type
Approximate SQL_NUMERIC Cast to the Cast to integer. Cast to integer Converted from
(floating corresponding and floating-point to
SQL_DECIMAL
point) floating-point interpreted as string.
SQL_REAL type. pointer to
digital state
SQL_FLOAT set.
SQL_DOUBLE

Exact SQL_TINYINT Cast to the Cast to the Interpreted as Converted from

(integer) particular particular pointer to integer to string.
SQL_SMALLIN
floating-point integer type. digital state
T
type. set.
SQL_INTEGER
SQL_BIGINT
SQL_BIT

Character SQL_CHAR Converted to Converted Checked Retrieved

double, then from string to against digital number of bytes
SQL_VARCHAR
cast to the PI integer and state set. copied.
SQL_LONGVAR floating-point cast to integer
CHAR type. PI data type.

• 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:

◦ 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:

32 PI Interface for Relational Databases (PI RDBMS) User Guide

 Specifying SQL queries

▪ 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
For a , any non-zero status indicates Bad Input.
The following figure shows database table rows containing status values and the
corresponding PI tag statuses.

Time stamps
The implementation of the timestamp data type varies among vendors, so the interface uses
the ODBC SQL_TIMESTAMP data type, which enables the interface to handle time stamps
consistently without regard for the underlying RDBMS. The interface can handle UTC
timestamps from both the RDBMS and the PI System. If the time stamps 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.
Time stamps must specify both date and time of day. The interface does not provide any
defaults for either value. The PI Server rejects time stamps that are more than ten minutes
ahead of its system time. 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 time stamped less than ten minutes ahead. The following example
illustrates this approach; sysdate is Oracle's "current time" function, and "10*60/86400" is an
expression for ten minutes:
SELECT Timestamp,Value,0
FROM TestTable
WHERE Timestamp > ? AND Timestamp < sysdate+10*60/86400
ORDER BY Timestamp; P1=TS

When the interface starts, all time stamp placeholders are populated with the current snapshot
time stamp, to ensure that all values added to the table since the last successful scan are
returned by queries like the following:
SELECT Timestamp, Value, Status
FROM TestTable
WHERE Timestamp > ?
ORDER BY Timestamp; P1=TS

• Time stamps in SELECT statements

PI Interface for Relational Databases (PI RDBMS) User Guide 33

Specifying SQL queries

The interface caches the most recent timestamp returned by the last-executed query and
uses it as the value for the TS placeholder. This approach has the following effects on
subsequent SELECT queries that use the TS placeholder to retrieve newly-arrived data:
◦ If buffering is enabled, the interface can execute the query even if it loses connectivity to
the PI Server.
◦ Regardless of whether exception reporting is enabled, newly-arrived rows are always
returned by the query.
Queries that are intended to retrieve newly-arrived rows must sort results by time stamp.
For example:
SELECT … FROM … WHERE timestamp > ? ORDER BY timestamp; P1=TS

To retrieve the time stamp of the system time on the RDBMS host computer, specify the
ODBC function {Fn NOW()} or use the appropriate database-specific function. For example:
SELECT {Fn NOW()},Value, Status FROM Table WHERE …;

To select the current time from an Oracle database:

SELECT sysdate, Value, Status FROM Table WHERE …;

To select current time from an SQL Server database:

SELECT getdate(),Value, Status FROM Table WHERE …;

If a SELECT statement omits the timestamp column, the interface uses the system time from
the interface node when the query is executed.
• Time stamp precision
The PI System can handle time stamps with precision up to 100 microseconds. For example,
20-Mar-2013 11:10:01.1234 is a valid PI time stamp. However, the maximum precision of
time stamps in the RDBMS might differ from the PI System maximum. Current time stamps
generated by the interface always contain the millisecond part.
• Numeric time stamps
In SELECT statements, you can specify time stamps using the SQL_TIMESTAMP data type or
as a DOUBLE or INTEGER column containing the number of seconds since 01-Jan-1970 (Unix
time stamps). Unlike SQL_TIMESTAMP, numeric time stamps can specify sub-millisecond
time stamps. To specify time stamp columns using a numeric data type, you must use the
"PI_TIMESTAMP" alias or cast the numeric column to a valid time stamp. The following
example query illustrates the use of a numeric column as a time stamp. (Note that the
to_date function is Oracle-specific.)
SELECT Time-as-number AS PI_TIMESTAMP, Value AS PI_VALUE, 0 AS PI_STATUS
FROM TestTable
WHERE (to_date('01-Jan-1970') + Time-as-number/(24*3600)) > ?; P1=TS

To use numeric time stamps in the WHERE clause or with placeholders, you must cast them
to a time stamp data type. For example:
SELECT Time-as-number AS PI_TIMESTAMP, Value AS PI_VALUE, 0 AS PI_STATUS
FROM Table
WHERE (to_date('01-Jan-1970') + Time-as-number/(24*3600)) > ?; P1=TS

When the value is cast to a time stamp, any milliseconds in the numeric time stamp are
truncated in the resulting time stamp.

34 PI Interface for Relational Databases (PI RDBMS) User Guide

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, time stamp and status (and, optionally, 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 source point.
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 result rows contain multiple values and no target tag names, use tag groups.
• If result rows contain a single time stamp, tag name, and value, use distribution.
• 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 time stamp 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 time stamped with the current time, and appear in the PI archive at the same
time stamp.
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, time stamp and value.
For example:
SELECT Timestamp, Value, Status FROM Table…

PI Interface for Relational Databases (PI RDBMS) User Guide 35

Input processing: updating PI tags from an RDBMS

The time stamp 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 Table…

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_ANNOTATION.
For example:
SELECT Value AS PI_VALUE, Status AS PI_STATUS, Timestamp AS PI_TIMESTAMP,
Annotation AS PI_ANNOTATION FROM …

For details, see Aliased result columns.

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.

Updating 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
time stamp when data is returned to them.
When defining a tag group, you configure a master tag 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 time stamp; 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:

36 PI Interface for Relational Databases (PI RDBMS) User Guide

 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 one of the target tags, specify the placeholders used
in the query (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_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 PI_TIMESTAMP, VALUE2 AS PI_VALUE2, VALUE1 AS PI_VALUE1, 0 AS PI_STATUS1,
0 AS PI_STATUS2 FROM T3_3 WHERE PI_TIMESTAMP > ? ORDER BY PI_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, time stamps 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 Table
WHERE Timestamp > ?;

If the tag name stored in the RDBMS does not match the name of the target tag in the PI
System, you can map them by specifying the /ALIAS flag in the ExtendedDescriptor 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 "Unit10_Tank01," 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
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.

PI Interface for Relational Databases (PI RDBMS) User Guide 37

Input processing: updating PI tags from an RDBMS

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 time stamped with the current time; that is, both events appear in the PI
archive with the same time stamp.
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.

Processing 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 time stamps greater than the TS placeholder (the
interface's cached value for time of last scan). However, the distributor tag is timestamped with
current time, so the comparison does not work for the distribution approach. If you are using
the distribution approach and need to determine whether a row has been processed, you can
use one of the following approaches:
• Define a column in the RDBMS that is set to indicate whether the row has been read, for
example, 0 if not read, 1 if read.
• Create a two-column RDBMS "snapshot" table that tracks the last time a value was sent
(columns are TagName and Time). The query associated with a tracked tag must join the
data table with this status table to determine whether that tag has been processed and, after
processing, issue an UPDATE query that updates the row with the new timestamp.
• Limit the result rows to a window of time, such as the last hour or minute, and set the /RBO
start-up parameter.

Verifying successful data distribution

To verify that all result rows were successfully distributed to the corresponding target tags,
check the state of the Boolean @rows_dropped 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 Timestamp, Name;

WHILE @ROWS_DROPPED
INSERT INTO Table2 (Name, Time, Value)
VALUES (?,?,?) LOOP; P1=AT.TAG P2=TS P3=VL

Note:
The @rows_dropped variable is supported only for tag distribution.

38 PI Interface for Relational Databases (PI RDBMS) User Guide

 Input processing: updating PI tags from an RDBMS

Updating 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 time stamp
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 time stamp 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_ANNOTATIONn). If the result row contains only one time stamp, 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 time stamped with the current time; that is, both events appear in the PI
archive with the same time stamp.

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 sampletime 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 TestTable
WHERE sampletime > ? AND tank = '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 Relational Databases (PI RDBMS) User Guide 39

Input processing: updating PI tags from an RDBMS

40 PI Interface for Relational Databases (PI RDBMS) User Guide

Output processing: updating an RDBMS with PI data
To write values from the PI System to an RDBMS, you define output tags, which execute an SQL
query or stored procedure containing INSERT, UPDATE or DELETE statements that update the
RDBMS. 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 output tag’s query.)
For an event-driven output tag, if the query succeeds, its value is set to the value of its source
tag. If the query fails, its value is set to the "Bad Output" digital state.

• Insert a single database row for a single PI point value

To add a single-value database row for each PI point value, create an output tag with an
INSERT query that specifies the target table and data to be written. Output tags are typically
event-based, sending values when a source tag is updated.
The OSIsoft Random Simulator interface, which is installed with the PI Server, is a useful
source of test data. The following example creates an output tag that reads a PI point called
"SINUSOID," which contains sine wave values generated by the Random Simulator interface,
and writes the point’s timestamp, value and status to a database table called "sinusoid-out".
To configure this example output tag, perform the following steps.

a. 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.
b. In your target relational database, create a table called "sinusoid-out" containing the
following columns:
Column Name SQL Data Type
your_timestamp DATETIME
your_value FLOAT
your_status INT

c. Launch PI System Management Tools, choose Points > PI Point Builder, and define a point
called "SINUSOID_TO_RDBMS". Configure its settings as follows:
ICU Tab Field Setting
PointSource RDBMSPI (or whatever setting
you configured for the
interface instance when you
defined it)
ExDesc /SQL="INSERT INTO
sinusoid-out
(your_timestamp,
your_value, your_status)
VALUES (?,?,?);" P1=TS
P2=VL P3=SS_I
SourceTag SINUSOID
Archive Compressing Off
ExcDev 0

PI Interface for Relational Databases (PI RDBMS) User Guide 41

Output processing: updating an RDBMS with PI data

ICU Tab Field Setting

Classic Location1 ID of the interface instance
(default is 1)
Location4 Not applicable (tag is triggered
by changes to source tag)

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 sinusoid-out table.
• Writing multiple PI values to a single row
If your RDBMS table stores values from different points in a single row, define an INSERT
query that assigns the values using the 'tagname'/VL placeholder. For example, the
following query writes values from three different PI Random Simulator interface tags to
the same database row:
INSERT INTO multicol (timestamp, val1, val2, val3, status)
VALUES (?,?,?,?,?); P1=TS P2=VL P3='SINUSOIDU'/VL
P4='CDT158'/VL P5=SS_I

The preceding query writes the following row to the RDBMS:

Timestamp SourceTag Value SINUSOID Value CDT158 Value

42 PI Interface for Relational Databases (PI RDBMS) User Guide

Recovering historical data
The RDBMS interface enables you to recover historical data from an RDBMS to PI tags (input
processing) and to send PI Archive data for output tag to an RDBMS (output processing). The
interface performs data recovery during startup, before it begins its normal data collection. In
addition, you can run the interface in pure replication mode, specifying the time period for
which you want to recover data. In pure replication mode, the interface scans the source for
data from the specified time period, updates the target by executing the queries that you
define, then exits.

Topics in this section

• Input processing: RDBMS to PI System
• Output processing: PI Archive to RDBMS
• Recovering out-of-order data
• Handling events by type
• Specifying the recovery interval and step size

Input processing: RDBMS to PI System

To write data from an RDBMS to PI tags, you configure the tags that are to be recovered with
SELECT queries that retrieve the desired data, then run the interface in recovery mode,
specifying the time span for the events that you want to recover. In input recovery mode, the
interface retrieves the data and updates the tags. If an end time is specified, the interface exits
after recovery. If no end time is specified, the interface recovers the data and then starts real-
time data collection. To ensure that system resources (CPU and memory) are not taxed by a
query that retrieves a huge amount of historical data, you can specify a time span (step) to be
used to retrieve the data in chunks rather than in one huge result set.
The queries used to recover data are no different than queries used to update tags from the
RDBMS in real time, as described in previous sections. You can use any of the data distribution
strategies provided by the interface (tag groups, distribution, and RxC). Typically you define a
query that specifies start and end time for the period to be recovered. To ensure that the data
arrives in time stamp sequence, specify the ORDER BY clause. For example:
SELECT Timestamp, Value, 0 FROM SourceTable
WHERE Timestamp > ? AND Timestamp <= ?
ORDER BY Timestamp ASC;
P1=TS P2=TE

The query must include start and end time placeholders (TS and TE). The placeholders are
resolved at run time to the start time and end time that you specify when you run the interface
in recovery mode. You specify start and end time using PI ICU, on the rdbodbc > Recovery
Parameters tab, as shown in the following figure.

PI Interface for Relational Databases (PI RDBMS) User Guide 43

Recovering historical data

Specify recovery start and end time as an absolute time (for example, 01-Jan-2000) or a
relative time (for example, *-8h), or specify the name of a PI time stamp tag that contains the
start or end time. For details about specifying time in the PI System, refer to the Data Archive
Manual. If you omit the end time, the interface performs recovery and then begins real-time
data collection. If you specify end time, the interface recovers data and then exits.
Note:
Regardless of whether UTC handling is enabled, you must specify the start and end times
in PI time format, not UTC.
To mitigate the server workload when recovering large amounts of data , specify Input
Recovery Step, which configures the size of the increments in which the interface reads data
from the PI Server.
To recover data, start the interface using PI ICU. To view the messages issued by the interface
during recovery, display the log in the Log subdirectory of the interface installation directory.
After recovery, check the target PI Server to verify that the desired data has been recovered.
For example, the following figure shows how recovery proceeds if you specify a start time of
March 25, 2013 at 1:50 PM, an end time of March 25, 2013 at 1:50:20 PM, and a step size of 10
seconds. The query is as follows:
SELECT Timestamp,Value,0 FROM Table
WHERE Timestamp >= ? AND Timestamp < ?
ORDER BY Timestamp; P1=TS P2=TE

44 PI Interface for Relational Databases (PI RDBMS) User Guide

 Recovering historical data

Output processing: PI Archive to RDBMS

To update an RDBMS with historical data from the PI archive, you define output tags. You can
specify logic that executes different queries depending on the nature of the value from the PI
archive. To recover data to the RDBMS, run the interface in output recovery mode, specifying
the period for which you want to recover data. If an end time is specified for recovery, the
interface exits after recovering data. If no end time is specified, the interface recovers data,
then starts processing real-time data.
For each tag you want to recover to the RDBMS, you must define a corresponding output tag. To
configure an output tag for recovery to an RDBMS:

• Set its Location5 attribute to the desired option for recovering out-of-order data. For
details, see Recovering out-of-order data.
• Set the SourceTag attribute to the name of the PI tag from which archive data is to be read.
• Specify the query and placeholder definitions in the tag’s Exdesc attribute or store the
query in a text file, specifying the query file name in the tag’s InstrumentTag attribute and
defining the placeholders in the tag’s Exdesc attribute
For example, the following simple INSERT query, specified in full in the tag’s ExDesc attribute,
updates the RDBMS with values and time stamps from the archive for the specified source tag:
/SQL="INSERT INTO SINUS_OUTPUT VALUES (?,?);" P1=TS P2=VL

PI Interface for Relational Databases (PI RDBMS) User Guide 45

Recovering historical data

By default, placeholder data for scanned output tags comes from the tag itself and placeholder
data for triggered output tags comes from the source tag, unless the placeholder includes a
'tagname’' argument.

Recovering out-of-order data

The PI Server expects data to arrive in chronological order, with each new event time stamped
later than the preceding one. Data that arrives with a time stamp that is earlier than the
preceding event is referred to as "out-of-order" data. For details about configuring the handling
of out-of-order data, see Location5 (data archiving and history recovery).
The following show the effect of out-of-order data on a trend if the PI server receives two
values while the interface is stopped, and how recovery corrects the sequence of data and
restores accuracy to the trend. Before recovery, the two trends differ, but after the sequence of
the data is corrected by recovery, the trends are identical.

OutputTag (blue) synchronized with SourceTag (green).

46 PI Interface for Relational Databases (PI RDBMS) User Guide

 Recovering historical data

Handling events by type

Events in the PI Archive can be new events, replacements of a previously-existing event, or
deletions of previously archived events. By default, only new (appended) events are recovered.
In PI ICU, you can configure the types of events to be recovered on the rdbodbc > Recovery
Parameters tab, in the Out of Order Options field. To define logic to execute different queries
depending on the nature of the event, specify the logic using "@source" clauses as follows:
IF @source_appended INSERT INTO table (…);
IF @source_replaced UPDATE table SET …;
IF @source_removed DELETE table WHERE …;

Following is an example of a query that specifies logic for each type of event.
IF @SOURCE_APPENDED
INSERT INTO RDBMSPI_Table_1 (tag, timestamp, value)
VALUES (?,?,?);
IF @SOURCE_REPLACED
UPDATE RDBMSPI_Table_1 SET Tag=?, Value=?
WHERE Tag=? AND Timestamp=?;
IF @SOURCE_REMOVED DELETE RDBMSPI_Table_1
WHERE Tag=? AND Timestamp=?;

Placeholder definitions:
P1=AT.TAG P2=TS P3=VL P4=P1 P5=P3 P6=P1 P7=P2 P8=P1 P9=P2

In the following figure, a SINUSOID event in the PI Archive was changed to Bad Input (-255),
so the interface executes the UPDATE query specified in the @SOURCE_REPLACEDclause

Specifying the recovery interval and step size

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.

PI Interface for Relational Databases (PI RDBMS) User Guide 47

Recovering historical data

• 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)
Recovery start and end times can be specified as either absolute or relative times, and 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 [, end]

Where the start and end time stamps are specified in the following format:
DD-MMM-YY hh:mm:ss

If you omit 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
time stamped Jan 1, 2000
and continues to the
present time. Data is
processed in 30-day
chunks.
01-Jan-00 01-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.

48 PI Interface for Relational Databases (PI RDBMS) User Guide

 Recovering historical data

Recovery start time Recovery end time Input recovery step Description
*-365d *-1h 1d Relative start time, relative
end time: data for the last
year is recovered, stopping
an hour before the current
time.
RecoveryStart RecoveryEnd 24h Name of the time stamp
tags: the snapshot value of
the tags is used as the start
and end time. The tag must
be a time stamp tag. Data is
recovered in 24-hour
chunks.

As an alternative to specifying an absolute or relative time, you can specify the name of a PI
time stamp tag. The snapshot value of the tag is used for the start or end time.

PI Interface for Relational Databases (PI RDBMS) User Guide 49

Recovering historical data

50 PI Interface for Relational Databases (PI RDBMS) User Guide

Features supported by the PI RDBMS interface
This interface is based on UniInt, an OSIsoft framework template used by interface developers
to ensure a consistent feature set and behavior across OSIsoft’s interfaces. For details, refer to
the UniInt Interface User Manual, which is installed with the interface.
The interface supports the following features:
Data handling Read point data (time stamp, value, status, and
annotations) from PI System and write to RDBMS,
and vice versa.
Ability to retrieve data for single points, multiple
points, and multiple points using a point name key
Millisecond and sub-millisecond timestamp
resolution
Scan- or event-based input and output
Access to all PI point attributes (classic point class)
through placeholders
History recovery for input and output points
Support for Time zone/DST settings that differ
from the PI Server setting
UTC time stamps
SQL Features Support for SELECT INSERT, UPDATE and DELETE
queries and stored procedures calls
Support of multiple SQL statements per point,
include transaction semantics
Support of SQL replaceable parameters using
runtime placeholders

Note:
If you are running the interface against PI Servers with high availability features, and PI
SDK buffering is not enabled, SQL queries containing PI annotations bypass exception
reporting and deliver events to the primary PI Server.

Feature Support
Auto Creates PI Points No
Point Builder Utility No
ICU Control Yes
PI Point Types Float16 / Float32 / Float64 / Int16 / Int32 /
Digital / String / Timestamp
Sub-second Timestamps Yes
Sub-second Scan Classes Yes
Automatically Incorporates PIPoint Attribute Yes
Changes
Exception Reporting Yes
Outputs from PI Yes (event-based and scan-based)

PI Interface for Relational Databases (PI RDBMS) User Guide 51

Features supported by the PI RDBMS interface

Feature Support
Inputs to PI Scan-based, unsolicited, and event points
Questionable Bit Support No
PI Annotations Support Yes
Multi-character PointSource Yes
Maximum Point Count Unlimited
Required PI API Version 1.6.0+
Uses PI SDK Yes ( to access annotations and some point
attributes)
PINet String Support No
Source of Time stamps RDBMS or PI Server, depending on how you define
the query that updates the target.
History Recovery Yes
UniInt-based Yes
Disconnected Startup No
SetDeviceStatus Yes
Failover UniInt Phase 2 Failover (cold); RDBMS Server-level
failover for Microsoft SQL Server only
Vendor Software Required on PI Interface Node / Yes
PINet Node
Vendor Software Required on Foreign Device Yes
Vendor Hardware Required No
Additional PI Software Included with Interface No
Device Point Types See note below.
Serial-Based Interface No

For information on how to configure health points, refer to the UniInt Interface User Guide.

History Recovery
For output points, the interface reads historical data from the PI Archive. For input points,
history recovery depends on the WHERE condition of the associated SELECT query.

Source Device Status

To track the status of the RDBMS, the PI RDBMS interface uses a health point with the ExDesc
point attribute set to [UI_DEVSTAT]. Status is report as follows:
Status Description
0 | Good | The interface is properly communicating with the
RDBMS system using the ODBC driver
3 | 1 device(s) in error | ODBC data source communication failure
4 | Intf Shutdown | The interface was shut down

52 PI Interface for Relational Databases (PI RDBMS) User Guide

 Features supported by the PI RDBMS interface

RDBMS Server Failover

For Microsoft SQL Server 2005 (and above) using the Native Client ODBC driver, the interface
supports configuring a mirror server using the FAILOVER_PARTNER keyword in the connection
string. If the connection to SQL Server is lost, the interface attempts to connect to the mirror
server.

Interface Failover
This interface supports UniInt phase 2 cold failover. For details about configuring interface
failover, consult the UniInt Interface User Manual. Unlike data sources that emit real-time data,
data in an RDBMS is usually persistent. As a result, configuring interface failover is less likely to
be critical (unless the data in your RDBMS is volatile and it's essential to historize it in real
time). If the interface fails, you can restart it and it will recover data from the downtime.

PI Interface for Relational Databases (PI RDBMS) User Guide 53

Features supported by the PI RDBMS interface

54 PI Interface for Relational Databases (PI RDBMS) User Guide

Installation checklist for the PI RDBMS interface
This checklist summarizes the steps for installing this interface. This checklist is intended for
people who are familiar with installing and configuring PI interfaces. If you are new to the
process, refer to the detailed procedure in Installing and configuring the PI RDBMS interface.

Prerequisites
• PI Prerequisites
• PI Interface Configuration Tool (ICU)

Install and configure the interface instance

If you are running the interface on an interface node, define a trust to permit the interface to
write data to the PI Server.

Procedure
1. Install the RDBMS interface on the interface node.
2. Launch the ICU and configure a new instance of this interface. Essential startup parameters
for this interface are:
◦ Point source
◦ Interface ID
◦ PI Server
◦ Scan class
◦ Data source name (source/target ODBC data source name)
◦ Interface log file
3. Start the interface interactively and verify that it can connect to the PI Server and the
RDBMS.
4. Stop the interface and configure a buffering application. To optimize buffering throughput,
sert the primary and secondary memory buffer size to 2000000. (In PI ICU, choose Tools >
Buffering… and go to the Buffering Settings page.)
5. Start the buffering application and the interface. Confirm that buffering works by
disconnecting the interface node from the PI Server or by stopping the PI Server.
6. Configure the interface to run as a Windows Service. Confirm that the service runs properly.
7. Restart the interface node and confirm that the interface and the buffering services start.

Create PI points and SQL queries

If you require digital points, define the appropriate digital state sets.

PI Interface for Relational Databases (PI RDBMS) User Guide 55

Installation checklist for the PI RDBMS interface

Procedure
1. Build input tags and, if desired, output tags for this interface. Important point attributes and
their purposes are:
◦ Location1: Interface instance ID
◦ Location2: Bulk or non-bulk reading
◦ Location3: Data acquisition strategy
◦ Location4: Scan class
◦ Location5: Specifies how the data is sent to PI (snapshot, archive write, etc).
◦ ExDesc: Parameters and placeholders for SQL queries
◦ InstrumentTag: The name of the file that stores the SQL file.
◦ SourceTag: Trigger tag for output tags.
2. Test the connection between the interface node and the RDBMS using an application such as
Microsoft® ODBC Test.
3. Define the queries required to update the RDBMS or PI points according to your
requirements. Verify that the SQL queries are syntactically correct and return data as
expected.
4. Configure a test tag to use a query as described in this guide, and verify that data is read or
written as expected.

Configure interface diagnostics (optional)

The following steps are optional tasks that enable you to monitor the status and performance
of the interface. For details about interface diagnostics, refer to the UniInt Interface User
Manual.

Procedure
1. Configure scan class performance points.
2. Install the full version of the PI Performance Monitor Interface on an interface node.
3. Configure performance counter points.
4. Configure UniInt health monitoring points
5. Configure the I/O rate point.
6. Configure the interface status point.

56 PI Interface for Relational Databases (PI RDBMS) User Guide

PI ICU reference for the PI RDBMS interface
You 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.

Startup Parameters tab

File Locations
Field Description
Interface Log File Full path to the interface specific log file. (/
OUTPUT) Optional
SQL Files Directory Directory of the SQL statement files. (/SQL)
Optional
Global Variables Files Full path to the global SQL variable file. (/GLOBAL)
Optional

PI Interface for Relational Databases (PI RDBMS) User Guide 57

PI ICU reference for the PI RDBMS interface

DSN Settings
Field Description
DSN Data Source Name (/DSN) Required
Username Username for access to RDBMS (/USER_ODBC)
Required
Password Password for access to RDBMS (/PASS_ODBC). The
password is encrypted and stored locally in the
directory configured for interface log files (/
OUTPUT). To enter a new password, click .

Successful - Status Range

Specify the range of digital states indicating success from the system digital state table.
Field Description
Start Code Enter the starting location in the system digital
state table. (/SUCC1=#) Optional
End Code 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 Description
Start Code Enter the starting location in the system digital
state table. (/BAD1=#) Optional
End Code Enter the ending location in the system digital
state table (/BAD2=#) Optional

58 PI Interface for Relational Databases (PI RDBMS) User Guide

 PI ICU reference for the PI RDBMS interface

Recovery Parameters tab

• Recovery Mode
Enable/disable recovery mode.
• Input Processing
Field Description
Recovery Start Time 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)
Recovery End Time 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)
Input Recovery Step Specifies the size of chunk in which data is read
during recovery, to avoid taxing system
resources.

• Output Processing

PI Interface for Relational Databases (PI RDBMS) User Guide 59

PI ICU reference for the PI RDBMS interface

Field Description
Recovery Start Time Specifies the point in time at which recovery
begins. (/RECOVERY_TIME)
Recovery End Time Specifies the point in time at which recovery
ends.(/RECOVERY_TIME)
Out of Order Options Specifies how out-of-order data is to be handled,
for tags with Location5 set to 1. (OOO_OPTIONS)

Optional Parameters tab

Field Description
Write Size Cache (# of Events) When laboratory caching is enabled (/LB),
specifies the maximum number of values written
in one (bulk) call to the PI Archive; default is
10240 events per bulk. This parameter can be used
to tune (throttle) the load on the PI Server. (/
WS=#, Default: 10240, Optional)
Write Delay (milliseconds) 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)

60 PI Interface for Relational Databases (PI RDBMS) User Guide

 PI ICU reference for the PI RDBMS interface

Field Description
Maximum Log (# of Files) 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 Log File Size (mb) Maximum size of the log file in MB. If this
parameter is omitted, the default maximum is 20
MB. (/MaxLogSize=#, Default: 20, Optional)
Consecutive Errors to Reconnect Number of consecutive errors that causes the
interface to deallocate all ODBC statements and
attempt to reconnect to the RDBMS. (/ERC=#,
Optional)
Failover Timeout (seconds) Specifies how long to wait for query results to
return before failing over to the secondary RDBMS
server. (/Failover_Timeout=#, Optional)
Direct SQL Execution 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)
Laboratory Caching 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)
Times are UTC Handle timestamps as UTC. If the timestamps in
the RDBMS are stored in UTC format, you must
enable this setting.(/UTC, Optional)
No Input Errors Disable writing of the BAD_INPUT, IO_TIMEOUT
digital states when an error occurs. (/
NO_INPUT_ERROR, Optional)
Read Before Overwrite 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 Exit if connection error occurs. By default, the
interface tries to reconnect. (/EBR, Optional)
Distribute Outside Point Source Enable interface to update points with point
source other than the one configured for the
interface instance. (/DOPS, Optional)
Ignore Nulls 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)
Scan Class – I/O Rate Tag fields Configure an I/O rate tag and assign a scan class to
it. (/TF, Optional)

PI Interface for Relational Databases (PI RDBMS) User Guide 61

PI ICU reference for the PI RDBMS interface

Debug Parameters tab

Field Description
Debug Settings Specifies level of detail to be logged. (/DEB)
Additional Parameters This section is provided for any additional
parameters that the ICU does not explicitly
support.

62 PI Interface for Relational Databases (PI RDBMS) User Guide

Command-line parameters for the PI RDBMS
interface
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 UniInt Interface User Manual.
Parameter Description
/BAD1=# The beginning of the range in the system digital
state table that contains Bad Input status strings.
Default: 0 (Optional)

/BAD2=# The end of the range in the system digital state

table that contains Bad Input status strings.
Default: 0 (Optional)

/DEB=# Set logging (debugging) level. The message in the

file is prefixed with the [DEB- # ] marker where
Default: 1 (Optional) # 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.
/DOPS Enables the interface to distribute events to tags
with point sources other than the point source
(Optional) configured for the instance. By default, rows with
tag names or aliases different from the point
source are skipped. Applies only to the tag
distribution and RxC strategies.

PI Interface for Relational Databases (PI RDBMS) User Guide 63

Command-line parameters for the PI RDBMS interface

/DSN=dsn_name ODBC data source name. If the interface is installed

as a Windows service, you must specify a SYSTEM
(Required) data source, not a FILE data source. On 64-bit
operating systems, the DSN must be configured
using the 32-bit ODBC Administrator, which is
located in the following directory:
%systemroot%\syswow64\odbcad32.exe
You cannot use the PI ODBC driver to configure a
data source.
/EBR Exit if connection problem occurs, do not loop
trying to reconnect. By default, the interface
(Optional) 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.
/ERC=# Configures the interface to close all ODBC
statements and attempt to re-create the whole
(Optional) 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.
/ExecDirect Execute queries using direct execution. If this
option is enabled, all SQL statements are prepared
(Optional) and bound before each execution. By default,
queries are prepared and bound once.
/Failover_Timeout=# Specify query timeout: fail over to secondary
RDBMS if query execution takes longer than the
(Optional) specified time.

/Global= FilePath Specify the file that contains the definitions of the
global variables. (Optional)
(Optional)

/HOST=host:port Specifies the host and port of the PI Server to

which the interface sends data.
(Required) • Host: Node name of the host node
• Port: 5450
/Ignore_Nulls Do not write the No Data system digital state for
tags populated through the tag group and RxC
(Optional) distribution strategies. By default, the interface
writes the No Data state if the value column is null.
/LB Bulk-write events to PI Archive. More efficient than
per-event writing, which is the default, but
(Optional) exception reporting is not performed.

64 PI Interface for Relational Databases (PI RDBMS) User Guide

 Command-line parameters for the PI RDBMS interface

/MaxLog=# Specifies the maximum number of log files. When

the specified number of files has been created, the
(Optional) interface starts overwriting the oldest log files. By
default, there is no limit on the number of log files.
/MaxLogSize=# Maximum size of the log file in MB. When the log
file grows to the specified maximum, a new log file
Default: 20 (Optional) is created.

/No_Input_Error Suppresses writing IO_TIMEOUT and BAD_INPUT

status for input tags when a runtime error occurs
(Optional) or the ODBC connection is lost. By default, the
interface writes I/O Timeout and uses the
current time as the time stamp. Ensures that the
interface can use the last time stamp to recover
data written after the last scan.
/OOO_Option="optionlist" For output tags, specifies what kind of out-of-order
events trigger SQL query execution. Valid options
(Optional) 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.
/Output=UNC_Path Specify the interface log file name, including its full
path. If the path contains spaces, specify the
(Optional) 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.
/Pass_ODBC=password Specify the password for the ODBC connection. If
no password is configured, the user is prompted to
(Optional) 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.
/RBO Read Before Overwrite: Overwrite existing event
with same time stamp only if the new value is
(Optional) different. Tag must have Location5 set to 1,
and /LB must be disabled.

PI Interface for Relational Databases (PI RDBMS) User Guide 65

Command-line parameters for the PI RDBMS interface

/Recovery_Step=# unit To manage workload when performing input

recovery, specifies the length of time for each
Default: 1d (Optional) 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
/Recovery_Time=start-time [,end-time ] For recovery, specifies the oldest (and, optionally,
the most recent) time stamp to be retrieved from
/Recovery_Time=start-tag [, end-tag]
the archive. Specify absolute or relative time in PI
format. Enclose in double quotes if the string
(Optional) 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"

/Recovery=option Specifies how to handle output tags during start-

up, if recovery is enabled. Valid options are as
Default: NO_REC (Optional) 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.

/SQL=Filepath Specifies the location of the SQL statement files. If

there are spaces in the file path, specify it in double
(Optional) quotes. If this parameter is omitted, the interface
requires the query to be specified in the ExDesc
tag attribute.
/SUCC1=# Specifies the beginning of the range in the system
digital state table that contains the "OK value"
Default: 0 (Optional) strings.

66 PI Interface for Relational Databases (PI RDBMS) User Guide

 Command-line parameters for the PI RDBMS interface

/SUCC2=# Specifies the end of the range in the system digital

state table that contains the "OK value" strings.
Default: 0 (Optional)

/User_ODBC=username Specifies the username for the ODBC connection. If

the RDBMS does not require login (for example,
(Optional) Microsoft Access), specify a dummy user name.

/UTC Handle time stamps using UTC (Universal Time

Coordinated) format.
(Optional)

/WD=# If bulk writing (/LB) is enabled, how many

milliseconds, to wait between bulk writes to the PI
Default: 10 (Optional) archive. Used for performance tuning.

/WS=# If bulk writing (/LB) is enabled, the maximum

number of values writing in a single bulk write to
Default: 10240 (Optional) PI archive. Used for performance tuning.

PI Interface for Relational Databases (PI RDBMS) User Guide 67

Command-line parameters for the PI RDBMS interface

68 PI Interface for Relational Databases (PI RDBMS) User Guide

RDBMS-specific considerations
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 Table LIMIT TO 10 ROWS;
SELECT timestamp,value,status FROM Table LIMIT TO 10 ROWS
WHERE timestamp > ? ORDER BY timestamp;
◦ Oracle 8.0 (NT) and above
SELECT timestamp,value,status FROM Table 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:

◦ Creating the package

To define a package, issue the CREATE PACKAGE statement. For example:

PI Interface for Relational Databases (PI RDBMS) User Guide 69

RDBMS-specific considerations

CREATE OR REPLACE PACKAGE myTestPackage IS

TYPE gen_cursor IS REF CURSOR;
END myTestPackage;
◦ Creating 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;
◦ Calling 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 time stamps, 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 time-
related 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 Table;
• 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), -- tag name
@TS datetime -- timestamp)
AS
SET NOCOUNT ON
INSERT Table1 VALUES(@name,@TS)
SELECT Timestamp,Value,0 FROM Table2
WHERE Tagname = @name and Timestamp > @TS

70 PI Interface for Relational Databases (PI RDBMS) User Guide

SQL examples
The examples illustrate various approaches for transferring data between the PI System and an
RDBMS. These examples are illustrative and are not installed as part of the interface. To
implement the examples:

1. Store the SQL queries in a text file directory that is configured for SQL files on the PI ICU
rdbodbc > Startup Parameters tab.
2. Create the PI points, setting example-specific attributes as described in the example.
3. Create the RDBMS table as specified and, if needed, populate the table with sample data.
For all points in these examples, the following settings are standard:
Point attribute Description
Location1 Interface instance ID
Location4 Scan class
InstrumentTag Name of query file
PointSource Matches point source configured for interface
instance

In the examples, note that the name of SQL query files, RDBMS tables and table columns is up
to you. User-defined names are italicized.

Example 1: Update a single tag with single value using key

matching
This query updates a PI point by selecting the first row that contains "Key_1234" in the key
column. To ensure that only the first row of the result set is used, set Location2 to 0.
SELECT your_time AS PI_TIME, your_value AS PI_VALUE, your_status AS PI_STATUS
FROM your_table
WHERE your_key_column = ?;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1="Key_1234"
Location2 First row/all row 0 (Processes only the first row)
Location3 Data distribution strategy 0
Location5 Exception reporting 0 (Exception reporting is enabled)
PointType Data type of PI point Float32

In the RDBMS, create a table formatted as follows.

Result column Column data type
SQL Server data type Microsoft Access data type
PI_TIME Datetime Date/Time
PI_VALUE Real Number-Single Precision

PI Interface for Relational Databases (PI RDBMS) User Guide 71

SQL examples

Result column Column data type

PI_STATUS Smallint Number-Whole Number
your_key_column 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 your_time AS PI_TIME, your_value AS PI_VALUE, 0 as PI_STATUS FROM
your_table
WHERE PI_TIME > ? ORDER BY PI_TIME ASC;

Configure the target PI point with the following settings.

Point Attribute Description Setting
ExDesc Placeholders and options P1=TS
Location2 First row/all row 1 (Processes all rows)
Location3 Data distribution strategy 0
Location5 Exception reporting 0 (Exception reporting is enabled)
PointType Data type of PI point String

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TIME Datetime Date/Time
PI_VALUE Real Number-Single Precision

Example 3: Update three points from a single row

The following example updates three PI points from a single database row that contains three
columns containing difference values. Note that, for each value, the query selects a status value
(0).
SELECT your_time AS PI_TIME,
your_value1 AS PI_VALUE1, 0 AS PI_STATUS1,
your_value1 AS PI_VALUE2, 0 AS PI_STATUS2,
your_value1 AS PI_VALUE3, 0 AS PI_STATUS3,
FROM your_table
WHERE PI_TIME > ? ORDER BY PI_TIME ASC;

Configure the target PI point with the following settings.

Point Attribute Description Setting
ExDesc Placeholders and options P1=TS
Location2 First row/all row 1 (Processes all rows)

72 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

Point Attribute Description Setting

Location3 Data distribution strategy Target_Point1: 2
Target_Point2: 4
Target_Point3: 6

Location5 Exception reporting 0 (Exception reporting is enabled)

PointType Data type of PI point Int32

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TIME Datetime Date/Time
PI_VALUE1 Smallint Number (Whole Number)
PI_VALUE2 Smallint Number (Whole Number)
PI_VALUE3 Smallint Number (Whole Number)

If the query returns two rows containing (10, 20, 30) and (11, 21, 31), the following table
shows how the values are assigned to the target points.
PI_TIMESTAMP PI_VALUE1 to PI_VALUE2 to PI_VALUE3 to
Target_Point1 Target_Point2 Target_Point3
20-Oct-2000 08:10:00 10 20 30
20-Oct-2000 08:20:00 11 21 31

Example 4: Determining target tag from RDBMS

In this example, the database table includes a column specifying the PI tag that is to be updated
with the value.
SELECT your_time AS PI_TIME, your_tagname AS PI_TAG, your_value AS PI_VAL,
your_status AS PI_STATUS
FROM your_table
WHERE PI_TAG LIKE 'Tag%'
ORDER BY PI_TIME, PI_TAG;

Configure the target PI point with the following settings.

Point attribute Description Setting
Location2 First row/all row N/A for distribution
Location3 Data distribution strategy Distributor tag: -1 Target points: 0
Location5 Exception reporting 0 (Exception reporting is enabled)
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
PI_TIME Datetime Date/Time

PI Interface for Relational Databases (PI RDBMS) User Guide 73

SQL examples

Column name Column data type

PI_VALUE Real Number-Single Precision
PI_STATUS Varchar(12) Text(12)
PI_TAG Varchar(80) Text(80)

Example result set:

PI_TIME PI_TAG PI_VALUE PI_STATUS
20-Oct-2000 08:10:00 Target_Point1 10 NULL
20-Oct-2000 08:10:00 Target_Point2 20 NULL
20-Oct-2000 08:10:00 Target_Point3 30 NULL

Given this result set, the interface assigns values to PI points as follows:
Point Value assigned
Target_Point1 10
Target_Point2 20
Target_Point3 30

Example 5: RxC (row by column) distribution

In this approach, each RDBMS row contains data for three different PUI points. For each point,
the row contains a single timestamp followed by three sets of tag name, value, and status
columns, one for each target tag.
A distributor tag executes the query that retrieves the data and updates the target tags. To
indicate that the tag is a distributor tag, set Location3 to -2. The interface writes time stamp,
values and status to the tag specified in the tag name column according to the "PI_" positional
aliases specified in the query.
In the following SQL statement, the reserved word "level" is enclosed in square brackets so it
can be used as a column name when querying Microsoft SQL Server.
SELECT sampletime AS PI_TIMESTAMP1, 'Tag1' AS PI_TAGNAME1, [level] AS PI_VALUE1,
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 your_table
WHERE sampletime > ? AND tank = 'Tank1'

Configure the target PI point with the following settings.

Point Attribute Description Setting
ExDesc Placeholders and options P1=TS
Location2 First row/all row N/A for RxC
Location3 Data distribution strategy RxC Distributor tag: -2 Target points:
0
Location5 Exception reporting 0 (Exception reporting is enabled)
PointType Data type of PI point Float32

74 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
SAMPLETIME Datetime Date/Time
LEVEL Real Number (Single) Prec
TEMPERATURE Real Number (Single) Prec
DENSITY Real Number (Single) Prec
LEVEL_STATUS Varchar(12) Text(12)
TEMPERATURE_STATUS Varchar(12) Text(12)
DENSITY_STATUS Varchar(12) Text(12)
TANK Varchar(80) Text(80)

Example 6: Single input with PI annotations

The following example updates the point with annotations, timestamp and value read from the
RDBMS.
SELECT your_time AS PI_TIMESTAMP, your_value AS PI_VALUE, your_annotation AS
PI_ANNOTATION
FROM your_table WHERE your_time > ? ORDER BY your_time;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1=TS
Location2 First row/all row 1 (All rows are processed)
Location3 Data distribution strategy 0
Location5 Exception reporting 1 (Exception reporting is turned off)
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
your_time Datetime Date/Time
your_value Real Number-Single Precision
your_annotation Varchar(255) Text(50)

Example 7: Event-based writes to RDBMS

This tag writes the value of the SINUSOID tag to the RDBMS when the value changes in the PI
System. Note that the tag has no scan class assigned. Instead, the SourceTag attribute is set to
SINUSOID, the tag that triggers writes to the RDBMS.
INSERT INTO your_table (PI_TIMESTAMP1, PI_VALUE, PI_STATUS) VALUES (?,?,?);

PI Interface for Relational Databases (PI RDBMS) User Guide 75

SQL examples

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
Location3 Data distribution strategy 0
Location5 Out-of-order data handling 0
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 Microsoft Access data type
PI_TIMESTAMP Datetime Date/Time
PI_VALUE Real Number-Single Precision
PI_STATUS Smallint Number-Whole Number

Example 8: Scan-based writes to RDBMS

This example updates the RDBMS when the SINUSOID tag receives a new value (assuming
compression and exception are enabled for the tag). Note that the tag is assigned to scan class1
(Location4) and the placeholders in the ExDesc attribute are configured to write SINUSOID’s
time stamp, value and status.
INSERT INTO your_table (PI_TIMESTAMP1, PI_VALUE, PI_STATUS) VALUES (?,?,?);

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1='SINUSOID'/TS
P2='SINUSOID'/VL
P3='SINUSOID'/SS_I

Location2 First row/all row N/A for outputs

Location3 Data distribution strategy 0
Location5 Out-of-order data handling 0
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
PI_TIMESTAMP Datetime Date/Time
PI_VALUE Real Number-Single Precision
PI_STATUS Smallint Number-Whole Number

76 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

Example 9: Event-based multiple-value write to RDBMS

To write values from different PI points to the same database row in a single query, use the
‘tagname’/VL placeholder. Output to the database is triggered by changes to the SINUSOID tag,
which is configured in the SourceTag point attribute.
When you have a large number of settings such as placeholders, you can define them in a text
file and specify the path and name of the file in the ExDesc attribute using the /EXD flag. The
file named "pi_sin_values_out.plh" contains the following text:
P1=AT.TAG P2=TS P3=VL P4=SS_I P5='SINUSOIDU'/AT.TAG P6='SINUSOIDU'/VL
P7='SINUSOIDU'/SS_I

Use this option when the length of the settings in the ExDesc attribute exceeds 1024
characters.
INSERT INTO your_table (PI_TAGNAME1, PI_TIMESTAMP1, PI_VALUE1, PI_STATUS1,
PI_TAGNAME2, PI_VALUE2, PI_STATUS2) VALUES (?,?,?,?,?,?,?);

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options /EXD=pi_sin_values_out.plh
Location2 First row/all row N/A for outputs
Location3 Data distribution strategy 0
Location5 Out-of-order data handling 0
PointType Data type of PI point Float16
SourceTag Triggering tag SINUSOID

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TIMESTAMP Datetime Date/Time
PI_VALUE Real Number-Single Precision
PI_STATUS Smallint Number-Whole Number
PI_KEY_VALUE Varchar(50) Text(50)

Example 10: Event-based write of annotation data to RDBMS

This example uses the SourceTag attribute to configure a trigger tag and the ANN_C
placeholder to write annotations to the RDBMS.
INSERT INTO your_table (TIME, VALUE, ANNOTATION) VALUES (?,?,?);

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1=TS P2=VL P3=ANN_C
Location2 First row/all row N/A for outputs
Location3 Data distribution strategy 0

PI Interface for Relational Databases (PI RDBMS) User Guide 77

SQL examples

Point attribute Description Setting

Location5 Out-of-order data handling 0
PointType Data type of PI point Float32
SourceTag Trigger tag SINUSOID

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
TIME Datetime Date/Time
VALUE Real Number-Single Precision
ANNOTATION VARCHAR(255) TEXT(50)

Example 11: Field name aliases

This example illustrates use of the "PI_" aliases for position-independence of the result
columns. If you omit aliases and specify only table column names, you must select timestamp,
value and status in precisely that sequence.
SELECT VALIDITY AS PI_STATUS, SCAN_TIME AS PI_TIMESTAMP, VOLUME AS PI_VALUE
FROM your_table
WHERE KEY_VALUE = ?;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1="Key_1234"
Location2 First row/all row 1 (All rows are processed)
Location3 Data distribution strategy 0
Location5 Exception reporting 1 (Exception reporting is turned off)
Point Type Data type of PI point String

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
SCAN_TIME Datetime Date/Time
VOLUME VARCHAR(1000) TEXT(255)
VALIDITY Smallint Whole Number
KEY_VALUE Varchar(50) Text(50)

Example 12: Tag group fixed column positions

This example updates two points from a single result row that contains two values. The points
must specify the same query file in the InstrumentTag attribute. To configure the value to be
written to the target point, set Location3 to the number of the result column. In the following

78 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

example, VALUE1 is column 2 and VALUE2 is column 4. The contents of VALUE1 are written to
Target_Point1 and the contents of VALUE2 are written to Target_Point2.
SELECT your_time AS PI_TIME, your_value1 AS PI_VALUE1, 0 AS PI_STATUS1,
your_value2 AS PI_VALUE2, 0 AS PI_STATUS2
FROM your_table
WHERE PI_TIME > ?;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1=TS (first target point only)
Location2 First row/all row 1 (All rows are processed)
Location3 Data distribution strategy First target point: 2 Second target
point: 4
Location5 Exception reporting 1 (Exception reporting is turned off)
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
PI_TIME Datetime Date/Time
PI_VALUE1 Real Number-Single Precision
PI_VALUE2 Varchar(50) Text(50)

Example 13: Tag group arbitrary column position (aliases)

Like example 11, this example illustrates use of the "PI_" aliases for position-independence of
the result columns. Values in the PI_VALUE1 result column go to Target_Point1, and values in
PI_VALUE2 go to Target_Point2.
SELECT PI_TIMESTAMP, VALUE1 AS PI_VALUE1, VALUE2 AS PI_VALUE2, 0 AS PI_STATUS1,
0 AS PI_STATUS2
FROM your_table
WHERE PI_TIMESTAMP > ?
ORDER BY PI_TIMESTAMP ASC;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1=TS (First target point only only)
Location2 First row/all row 1 (All rows are processed)
Location3 Data distribution strategy First target tag: 1 Second target tag: 2
Location5 Exception reporting 1 (Exception reporting is turned off)
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

PI Interface for Relational Databases (PI RDBMS) User Guide 79

SQL examples

Column name Column data type

PI_TIMESTAMP Datetime Date/Time
PI_VALUE1 Real Number-Single Precision
PI_VALUE2 Real Number-Single Precision

Example 14: Tag distribution retrieving target tag name from

database
This example configures a distributor tag that executes a query that retrieves the names of the
tags to be updated as well as the associated value and timestamp. To configure a distributor
tag, set Location3 to -1.
SELECT PI_TIME, PI_TAGNAME, PI_VALUE, 0 AS PI_STATUS
FROM your_table
WHERE PI_TIME > ?
ORDER BY PI_TIME;

Configure the target PI point with the following settings.

Point Attribute Description Setting
ExDesc Placeholders and options Distributor tag only: P1=LST
Location2 First row/all row N/A for distribution
Location3 Data distribution strategy (distributor -1
tag only)
Location5 Exception reporting 1 (Exception reporting is turned off)
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
PI_TIME Datetime Date/Time
PI_TAGNAME Varchar(50) Text(50)
PI_VALUE Real Number-Single Precision

Example data:
PI_TIME PI_TAGNAME PI_VALUE
20-Oct-2000 08:10:00 Tag1 4.567
20-Oct-2000 08:10:10 Tag2 5.568
20-Oct-2000 08:10:20 Tag3 6.569

Example 15: Tag distribution search according to tag's alias

To map a PI tag to a different name that is used the RDBMS, specify the /ALIAS flag in the tag’s
ExDesc attribute and use the PI_ALIAS placeholder in the query that retrieves data for the

80 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

target tag. In the following example, data for the PI tag named "Tag2" is stored in RDBMS rows
that refer to "Valve1," and so on.
SELECT your_time AS PI_TIME, your_alias AS PI_ALIAS, your_value AS PI_VALUE, 0
AS PI_STATUS
FROM your_table
WHERE PI_TIME > ?;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options Distributor tag only: P1=TS Other
tags: /ALIAS=<tagalias>
Location2 First row/all row N/A for distribution
Location3 Data distribution strategy (distributor -1
tag only)
Location5 Exception reporting 1 (Exception reporting is disabled)
PointType Name of query file (set in distributor
tag only)
SourceTag 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
your_time Datetime Date/Time
your_alias Varchar(50) Text(50)
your_value Real Number-Single Precision

Example data:
Time PI_Alias Value
20-Oct-2000 08:10:00 Valve1 "Open"
20-Oct-2000 08:10:00 Valve2 "Closed"
20-Oct-2000 08:10:00 Valve3 "N/A"

Example 16: Tag distribution marking rows read

This example reads only previously-unread rows from the database. After reading the row, it
sets the table’s rowRead column to 1 to indicate the row has been read.
SELECT your_time AS PI_TIME, your_tag AS PI_TAG, your_value AS PI_VALUE, 0 AS
PI_STATUS
FROM your_table
WHERE rowRead=0;UPDATE your_table SET rowRead=1 WHERE rowRead=0;

Configure the target PI point with the following settings.

Point attribute Description Setting
Location3 Data distribution strategy (distributor -1
tag only)

PI Interface for Relational Databases (PI RDBMS) User Guide 81

SQL examples

Point attribute Description Setting

Location5 Exception reporting 1 (Exception reporting is turned off)
InstrumentTag Name of query file (distributor tag
only)
PointType Data type of PI point Float32

In the RDBMS, create a table formatted as follows.

Column name SQL Server Data Type
PI_TAG Varchar(255)
PI_TIME Datetime
PI_VALUE Real
rowRead Integer

Example 17: Tag distribution storing the latest snapshot

This example maintains a database table that stores the names of target points and their most
recent timestamp, value and status. When a tag contains a time stamp more recent than the
latest one in the table, the table is updated with the newer data. The JOIN clause ensures that
only new entries from the snapshot table are retrieved.
SELECT your_data.time, your_data.tag, your_data.value, 0 AS status
FROM your_data INNER JOIN your_snapshot ON your_data.tag=your_snapshot.tag
WHERE your_data.time > your_snapshot.time;

UPDATE your_snapshot SET time=(SELECT MaxTimeTag.maxTime FROM (SELECT DISTINCT

(SELECT MAX(time)
FROM your_data WHERE tag=TdataTmp.tag) As MaxTime, tag
FROM your_data TdataTmp) MaxTimeTag INNER JOIN your_snapshot TsnapshotTmp ON
MaxTimeTag.tag=TsnapshotTmp.tag
WHERE your_snapshot.tag=MaxTimeTag.tag)

Configure the target PI point with the following settings.

Point attribute Description Setting
Location2 First row/all 0 (Process the first row only)
row
Location3 Data -1
distribution
strategy
(distributor
tag only)
Location5 Exception 1 (Exception reporting is turned
reporting off)
InstrumentTag Name of query
file
(distributor
tag only)
PointType Data type of PI Float32
point

In the RDBMS, create two tables formatted as follows.

82 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

Column name SQL Server data type

tag Varchar(255)
time Datetime
value Real
status Integer

Column name SQL Server data type

tag Varchar(255)
time Datetime

Example 18: Retrieve values for the last hour

This example updates target points with values timestamped within an hour of the current
system time, calculated using the GETDATE() function. To ensure that existing values in the PI
archive are not overwritten, in PI ICU go to the rdbodbc > Optional Parameters tab and enable
the Read Before Overwrite option.
SELECT your_time AS PI_TIME, your_tag AS PI_TAG, your_value AS PI_VALUE, 0 AS
PI_STATUS
FROM your_table
WHERE PI_TIME > GETDATE()-(1./24.);

Configure the target PI point with the following settings.

Point Attribute Description Setting
ExDesc Placeholders and options
Location2 First row/all row N/A for distribution
Location3 Data distribution strategy (distributor -1
tag only)
Location5 Exception reporting 1 (Exception reporting is turned off)
InstrumentTag Name of query file (distributor tag
only)
PointType Data type of PI point Float32

In the RDBMS, create a table formatted as follows.

Column name SQL Server Data Type
PI_TAG Varchar(255)
PI_TIME Datetime
PI_VALUE Real
PI_STATUS Integer

Example 19: Tag distribution with aliases in column names

If the target tag specifies an alias in its ExDesc attribute, this query retrieves rows that contain
a matching entry in the Name column.

PI Interface for Relational Databases (PI RDBMS) User Guide 83

SQL examples

SELECT NAME AS PI_TAGNAME, VALUE AS PI_VALUE, STATUS AS PI_STATUS, DATE_TIME AS

PI_TIMESTAMP
FROM your_table
WHERE NAME LIKE ?;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options Distributor tag: P1="Key_123%"
Target points:- /ALIAS='value in
NAME column'

Location2 First row/all row N/A for distribution

Location3 Data distribution strategy Distributor tag: -1
Location5 Exception reporting 1 (Exception reporting is turned off)
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
DATE_TIME Datetime Date/Time
NAME CHAR(80) TEXT(80)
VALUE Real Number-(Single Precision )
STATUS Real TEXT(12)

Example 20: RxC (row by column) distribution

This example configures a distributor tag that executes a query returning rows that contain the
names of the target tags as well as the associated timestamp, value and status.
SELECT sampletime AS PI_TIMESTAMP1, name1 AS PI_TAGNAME1, value1 AS PI_VALUE1,
sampletime AS PI_TIMESTAMP2, name2 AS PI_TAGNAME2, value2 AS PI_VALUE2, status2
AS PI_STATUS2,
sampletime AS PI_TIMESTAMP3, name3 AS PI_TAGNAME3, value3 AS PI_VALUE3, status3
AS PI_STATUS3
FROM your_table
WHERE sampletime > ?;

Configure the target PI point with the following settings.

Point Attribute Description Setting
ExDesc Placeholders and options Distributor tag: P1=TS
Location2 First row/all row N/A for distribution
Location3 Data distribution strategy Distributor tag: -2
Location5 Exception reporting 1 (Exception reporting is turned off)
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

84 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

Column name Column data type

SAMPLETIME Datetime Date/Time
NAME1, NAME2, NAME3 CHAR(80) TEXT(80)
VALUE1, VALUE2, VALUE3 Real Number
STATUS1, STATUS2, STATUS3 REAL Number

Example 21: RxC (row by column) distribution using a single

time stamp
The following query uses the same RDBMS table as the preceding example. The result rows
contain a single time stamp that is applied to all target tags.
SELECT sampletime AS PI_TIMESTAMP, name1 AS PI_TAGNAME1, value1 AS PI_VALUE1,
name2 AS PI_TAGNAME2, value2 AS PI_VALUE2, status2 AS PI_STATUS2,
name3 AS PI_TAGNAME3, value3 AS PI_VALUE3, status3 AS PI_STATUS3
FROM your_table
WHERE sampletime > ?;

Example 22: Event-based input

The query for this example point is executed when the SINUSOID point is changed. To
configure an event-based tag, specify the /EVENT flag in the ExDesc attribute.
SELECT PI_TIMESTAMP, PI_VALUE, PI_STATUS FROM your_table;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options /EVENT=sinusoid
Location2 First row/all row 0 (Process only the first row)
Location3 Data distribution strategy 0
Location5 Exception reporting 1 (Exception reporting is turned off)
PointType Data type of PI point String

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TIMESTAMP Datetime Date/Time
PI_VALUE VARCHAR(10000) TEXT(255)
PI_STATUS Smallint BYTE

Example 23: Multi-statement query

This query maintains the most recent data in the RDBMS, deleting older entries after writing
the latest one.

PI Interface for Relational Databases (PI RDBMS) User Guide 85

SQL examples

INSERT INTO your_table (PI_TIMESTAMP, PI_VALUE, PI_STATUS) VALUES (?, ?, ?);

DELETE FROM your_table WHERE PI_TIMESTAMP < ?;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1=TS P2=VL P3=SS_I P4=TS
Location2 First row/all row N/A for output
Location3 Data distribution strategy 0
Location5 Out-of-order data handling 0
PointType Data type of PI point Float32
SourceTag Tag from which data is read SINUSOID

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TIMESTAMP Datetime Date/Time
PI_VALUE Smallint Number-Single Precision
PI_STATUS Smallint Number-Whole Number

Example 24: Stored procedure call

The following query calls a stored procedure instead of directly executing a SELECT statement.
Stored procedure:
CREATE PROCEDURE myprocedure @Start_Time DateTime, @End_Time DateTime AS SELECT
PI_TIMESTAMP,PI_VALUE,PI_STATUS
FROM your_table
WHERE PI_TIMESTAMP BETWEEN @Start_Time AND @End_Time

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options /SQL= "{CALL SP3_9(?,?)};" P1=LST
P2=ST
Location2 First row/all row 1
Location3 Data distribution strategy 0
Location5 Exception reporting 1 (Exception reporting is turned off)
PointType Data type of PI point Float16

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TIMESTAMP Datetime Date/Time
PI_VALUE Real Number-Single Precision
PI_STATUS Smallint Number-Whole Number

86 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

Example 25: Event-based output

The following example point writes its data to the RDBMS table when the SINUSOID point
changes.
UPDATE your_table SET PI_TIMESTAMP=?, PI_VALUE=?, PI_STATUS=? WHERE PI_KEY LIKE
'Key123';

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 output
Location3 Data distribution strategy 0
Location5 Out-of-order data handling 0
PointType Data type of PI point Float16
SourceTag Tag that triggers the update SINUSOID

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TIMESTAMP Datetime Date/Time
PI_VALUE Real Number-Single Precision
PI_STATUS Smallint Number-Whole Number

Example 26: Event-based output write another tag’s data

This example writes data from the point named TagDig to the RDBMS when the SINUSOID
point changes.
UPDATE your_table SET PI_TIMESTAMP=?, PI_VALUE=?, PI_STATUS_I=?, PI_STATUS_STR=?;

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1='TagDig'/TS P2='TagDig'/VL
P3='TagDig'/SS_I P4='TagDig'/SS_C
Location2 First row/all row N/A for output
Location3 Data distribution strategy 0
Location5 Out-of-order data handling 0
PointType Data type of PI point Float16
SourceTag Tag that triggers the update SINUSOID

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type

PI Interface for Relational Databases (PI RDBMS) User Guide 87

SQL examples

Column name Column data type

PI_TIMESTAMP Datetime Date/Time
PI_VALUE CHAR(12) TEXT(12)
PI_STATUS_I Smallint Number-Whole Number
PI_STATUS_STR VARCHAR(20) TEXT(12)

Example 27: Using global variables to set placeholders

This example illustrates the use of global variables. This approach provides a level of
indirection, enabling you to change settings without editing individual PI tags. To set
placeholders using global variables:

1. Assign placeholders to global variables in the ExDesc tag attribute.

2. Define the global variables in a text file.
3. Configured the global variables file for the interface instance using PI ICU, on the
rdbodbcStartup Parameters tab.
UPDATE your_table SET PI_TIMESTAMP=?, PI_TAGNAME=?, PI_VALUE=?, PI_STATUS=?;
Content of the global variables file:
G1='sinusoid'/TS G2="any_string1" G3="any_string2" G4='sinusoid'/AT.TAG
G5='sinusoid'/VL G6='sinusoid'/SS_C …

Configure the target PI point with the following settings.

Point attribute Description Setting
ExDesc Placeholders and options P1=G1 P2=G4 P3=G5 P4=G6
Location3 Data distribution strategy 0
Location5 Out-of-order data handling 0
PointType Data type of PI point Int16

In the RDBMS, create a table formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TIMESTAMP Datetime Date/Time
PI_TAGNAME CHAR(50) TEXT(50)
PI_VALUE Real Number-Single Precision
PI_STATUS CHAR(12) TEXT(12)

Example 28: Maintain most recent hour of PI point data

This example ensures that the RDBMS contains the last hour’s worth of data from the
SINUSOID point.
UPDATE PI_INSERT_UPDATE_1ROW SET PI_TSTAMP=?, PI_VALUE=?, PI_STATUS=?;
UPDATE PI_INSERT_UPDATE RIGHT JOIN PI_INSERT_UPDATE_1ROW ON
{Fn MINUTE(PI_INSERT_UPDATE_1ROW.PI_TSTAMP)}={Fn

88 PI Interface for Relational Databases (PI RDBMS) User Guide

 SQL examples

MINUTE(PI_INSERT_UPDATE.PI_TSTAMP)}
SET PI_INSERT_UPDATE.PI_TSTAMP = PI_INSERT_UPDATE_1ROW.PI_TSTAMP,
PI_INSERT_UPDATE.PI_VALUE = PI_INSERT_UPDATE_1ROW.PI_VALUE,
PI_INSERT_UPDATE.PI_STATUS = PI_INSERT_UPDATE_1ROW.PI_STATUS;

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 output
Location3 Data distribution strategy 0
Location5 Out-of-order data handling 0
PointType Data type of PI point Float16
SourceTag Triggering tag SINUSOID

In the RDBMS, create two tables, both formatted as follows.

Column name Column data type
SQL Server data type Microsoft Access data type
PI_TSTAMP Datetime Date/Time
PI_VALUE Real Number-Single Precision
PI_STATUS Smallint Number-Whole Number

PI Interface for Relational Databases (PI RDBMS) User Guide 89

SQL examples

90 PI Interface for Relational Databases (PI RDBMS) User Guide

Recording 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 tag is configured by setting Location4 to
-1 or -2.
Note:
OSIsoft strongly recommends using the PI Server auditing features to audit changes to
points, rather than this interface.

• Short form configuration

When Location4 is set to –1, the interface expects a subset of the AT.* placeholders in the
INSERT query. This statement (INSERT) thus has to be configured and the Managing Tag
always executes it when there is a point attribute change. The following table summarizes
the placeholders supported in the short form:
Example of the RDB table structure for the PI Placeholder
point changes recording
TAG_NAME (SQL_CHAR) AT.TAG
ATTRIBUTE_NAME (SQL_CHAR) AT.ATTRIBUTE
CHANGE_DATETIME (SQL_TIMESTAMP) AT.CHANGEDATE
CHANGER (SQL_CHAR) AT.CHANGER
NEW_VALUE (SQL_CHAR) AT.NEWVALUE
OLD_VALUE (SQL_CHAR) AT.OLDVALUE

The interface stores the number of executed queries into the managing tag. In the short
form, nothing is stored when a point was edited and no real attribute change has been
made.
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 this; the interface misses the first change. Since RDBMSPI 3.11, the two-minute
interval can be changed by specifying the start-up parameter /UPDATEINTERVAL
• 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 the
current PI point attributes state to RDB. The overall principles are the same as with the
short form. That is, any attribute change recognized by the interface is the trigger for the
SQL statement (INSERT) execution. The interface stores the number of executed queries
into the managing tag.

PI Interface for Relational Databases (PI RDBMS) User Guide 91

Recording PI point database changes

92 PI Interface for Relational Databases (PI RDBMS) User Guide

Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or http://
techsupport.osisoft.com. The OSIsoft Technical Support website offers additional contact
options for customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:

• Product name, version, and build numbers

• Details about your computer platform (CPU type, operating system, and version number)
• Time that the difficulty started
• Log files at that time
• Details of any environment changes prior to the start of the issue
• Summary of the issue, including any relevant log files during the time the issue occurred
The OSIsoft Virtual Campus (vCampus) website (http://vcampus.osisoft.com) has
subscription-based resources to help you with the programming and integration of OSIsoft
products.

PI Interface for Relational Databases (PI RDBMS) User Guide 93

Technical support and other resources

94 PI Interface for Relational Databases (PI RDBMS) User Guide