PI SQL Data Access Server (OLE DB) 2018

Administrator Guide
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

© 2010-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, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services,
OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API,
PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive,
PI DataLink, PI DataLink Server, PI Developer’s Club, PI Integrator for Business Analytics, PI Interfaces,
PI JDBC driver, PI Manual Logger, PI Notifications, PI ODBC, PI OLEDB Enterprise, PI OLEDB Provider,
PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI Vision,
PI Visualization Suite, PI Web API, PI WebParts, PI Web Services, RLINK, and RtReports 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: 1.6
Published: 6 September 2018
Contents

Introduction.............................................................................................................. 1
In this guide..................................................................................................................................................... 1
About Developer Technologies........................................................................................................................1
Architecture.................................................................................................................................................... 2
Deployment options........................................................................................................................................2

PI SQL DAS (OLE DB) installation................................................................................5

System requirements...................................................................................................................................... 5
Install PI SQL DAS (OLE DB) ........................................................................................................................... 6
Run the PI SQL DAS (OLE DB) setup kit....................................................................................................... 6
PI SQL DAS silent installation...................................................................................................................... 8
PI SQL DAS (OLE DB) installation results.....................................................................................................9
PI SQL DAS in a double-hop scenario............................................................................................................ 10
Trusted connection and double-hop scenario.............................................................................................12
Resource Based Constrained Delegation for PI SQL DAS............................................................................... 13
Introduction to Resource Based Constrained Delegation........................................................................... 14
Configuration of Resource Based Constrained Delegation......................................................................... 14
Certificate for HTTPS communication........................................................................................................... 16
About PI SQL DAS configuration................................................................................................................... 17
Configure PI SQL DAS................................................................................................................................17
SSL port configuration...............................................................................................................................18
PI Server login through PI SQL DAS...............................................................................................................19
Upgrade scenarios......................................................................................................................................... 21
Uninstall PI SQL DAS (OLE DB)......................................................................................................................23

Using PI SQL DAS (OLE DB)...................................................................................... 25

SQL implementation..................................................................................................................................... 25
Log message................................................................................................................................................. 25
Messaging features................................................................................................................................... 26

Troubleshooting...................................................................................................... 29
Run PI SQL DAS (OLE DB) interactively.........................................................................................................29
Checklist for troubleshooting a trusted connection in a double-hop scenario................................................ 29
Connection messages and errors................................................................................................................... 30

Third-party libraries..................................................................................................33

Technical support and other resources....................................................................... 35

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide iii
Contents

iv PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

Introduction
PI SQL Data Access Server (PI SQL DAS) is a middleware component that supports the PI SQL
family of drivers such as PI ODBC Driver and PI JDBC Driver. While these drivers implement a
certain industry standard or API and build the interface to third-party clients or applications PI
SQL DAS is responsible for executing the queries.
This version of PI SQL DAS (OLE DB) supports connections and queries for:
• PI Data Archive
• PI AF Server
Connections are made by client software that make use of PI SQL Family drivers such as PI
JDBC Driver and PI ODBC Driver.
PI ODBC Driver and PI JDBC Driver are members of the Developer Technologies product suite.
For more information, see About Developer Technologies.

In this guide
This guide provides procedures for the installation and configuration of PI SQL DAS (OLE DB)
on Windows operating systems.
Users of this guide should be familiar with PI OLEDB Provider and PI OLEDB Enterprise.

About Developer Technologies

Developer Technologies are designed to support implementation of custom applications on top
of the PI System, as well as integration of PI System data with other applications and business
systems such as Microsoft Office or SQL Server, Enterprise Resource Planning systems (ERPs),
Web portals, and maintenance systems, to name just a few.
Developer Technologies cover a wide range of use cases in various environments,
programming languages, operating systems and infrastructures. Products include:

• SQL-based data access (PI OLEDB Provider, PI OLEDB Enterprise, PI JDBC Driver, PI ODBC
Driver, and PI SQL Client OLE DB)
• Service-oriented architecture (PI Web API)
• Programmatic access (AF SDK)
Developer Technologies products are available for download from the OSIsoft Tech Support
Downloads page (https://techsupport.osisoft.com/Downloads/All-Downloads/) at no charge.
You can develop applications using the Developer Technologies tools and your PI Server. If you
do not have access to a PI Server, you can obtain development licenses for the PI Server
through membership in the PI Developers Club (https://pisquare.osisoft.com/community/
developers-club). For details, see PI Developers Club FAQ (https://pisquare.osisoft.com/docs/
DOC-1101).
Deployment of an application into production requires a PI System Access (PSA) license. This is
a runtime license that enables end users to access PI System data, including time series data in

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 1

Introduction

PI Data Archive and asset metadata in PI AF Server, using any of the Developer Technologies.
For more information or questions, contact your Account Manager. In case of technical issues
with the PSA license, contact OSIsoft Technical Support (https://techsupport.osisoft.com).

Architecture
The family of SQL based drivers has been re-architected to leverage PI SQL DAS for query
execution. This allows reducing the software being installed on the client to a thin driver that
has no local dependency on bigger components such as a query engine and PI SDK or AF SDK.
Currently this architecture applies to PI ODBC Driver and PI JDBC Driver. The driver
architecture provides two query engine options such as the PI OLEDB Enterprise and PI OLEDB
Provider query engines.
PI SQL DAS provides secure network communication through Net.Tcp or HTTPS to the driver
on the client side.

Deployment options
PI drivers can be deployed in various combinations. The driver and PI SQL DAS can run on
different architectures (32-bit or 64-bit). However, PI SQL DAS (OLE DB) is constructed as a 64-
bit version.
The resulting combinations can be categorized as standalone and middleware scenarios.
Note:
OSIsoft recommends using 64-bit operating systems whenever possible. Performance
will be better on a 64-bit operating system than on a 32-bit operating system.
Multiple standalone and middleware configurations can be used as needed. This is useful if the
performance of one application should not be influenced by queries of another one.

2 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 Introduction

Standalone deployment

Note:
When using the standalone deployment, the following points have to be taken into
account:
• All products are installed on the server.
• Only Windows is supported for this configuration.
• Standalone applications are supported.
Use the standalone deployment if a single application must be supported with maximum
performance.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 3

Introduction

Middleware deployment

Note:
When using this deployment, consider the following:
• PI SQL standard drivers are installed on the clients, other products are installed on the
server.
• This option is also suitable for WAN, which is recommended when the expected
number of resulting rows is rather low.
• A thin driver, which is resource inexpensive, is part of this configuration.
• Queries are executed in middleware.
Middleware deployment takes advantage of cross-architecture support; for example, when
using 64-bit query execution (in PI SQL DAS) from a 32-bit ODBC application.

4 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

PI SQL DAS (OLE DB) installation
This section covers the installation of PI SQL DAS (OLE DB). The setup kit is distributed as a
self-extracting executable file.

Topics in this section

• System requirements
• Install PI SQL DAS (OLE DB)
• PI SQL DAS in a double-hop scenario
• Resource Based Constrained Delegation for PI SQL DAS
• Certificate for HTTPS communication
• About PI SQL DAS configuration
• PI Server login through PI SQL DAS
• Upgrade scenarios
• Uninstall PI SQL DAS (OLE DB)

System requirements
Operating systems
PI SQL DAS (OLE DB) is supported on the following servers:

• Windows 7 SP1
• Windows 8 and 8.1
• Windows 10
• Windows Server 2008 R2
• Windows Server 2012 and 2012 R2
• Windows Server 2016

Server platforms
Supported server platforms (PI Data Archive, PI AF Server) are defined by the underlying OLE
DB providers used. For more information, see the PI OLEDB Enterprise and PI OLEDB Provider
Release Notes available at the OSIsoft Tech Support Downloads page (https://
techsupport.osisoft.com/Downloads/All-Downloads/)

Further requirements
PI SQL DAS (OLE DB) requires
• Microsoft .NET Framework 4.6.2
• PI OLEDB Provider 2016 or later
• PI OLEDB Enterprise 2016 or later

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 5

PI SQL DAS (OLE DB) installation

The required products have additional dependencies (for example, AF SDK) that are
documented in the related product documentation.
For additional information about the specific PI software release you are using, see the Release
notes of the specific product available at the OSIsoft Tech Support Downloads page (https://
techsupport.osisoft.com/Downloads/All-Downloads/). The release notes also describe the
minimum version requirements when sharing PI SQL DAS (OLE DB) across clients.

Install PI SQL DAS (OLE DB)

Procedure
1. Verify whether the computer you use meets the minimum System requirements.
2. Run the PI SQL DAS setup kit.

Run the PI SQL DAS (OLE DB) setup kit

Before you start
The installation must be run from an account that has administrative privileges.

Procedure
1. Double-click the PISQLDAS_version_.exe file. The self-extracting executable window
opens.
2. Review the extraction path for the installation files and click OK.
3. Review the installation files and click OK.

4. If you select Advanced Options, you might do one of the following:

6 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

◦ Specify a different account for the PI SQL DAS service, for example a Managed Service
Account.
◦ Choose the ports that the service will use.
◦ Select an SSL certificate for encrypting the communication.
◦ Choose whether to create Windows Firewall Exceptions.
If you click the Install button, the following settings are applied by default:
◦ The service runs using a virtual service account
◦ HTTPS port defaults to 5461, Net.Tcp to 5462.
◦ Self-signed certificate
◦ Firewall exceptions for ports 5461 and 5462 are created.
Note:
Consider the following points:
◦ If you decide to use Managed Service Account instead of the virtual service account,
make sure it was installed on the computer. For more information, see the Add-
ADComputerServiceAccount and Install-ADServiceAccount Active
Directory cmdlets or Installing a Managed Service Account (https://
technet.microsoft.com/en-us/library/dd378855(v=ws.10).aspx).
◦ If you upgrade from an older version, advanced options are not accessible. PI SQL
DAS (OLE DB) gets installed using the default settings. You need to uninstall the
older version manually prior installing the new one if you want to use the custom
settings.
◦ If your scenario requires the usage of the domain account, OSIsoft strongly
recommends you use a Managed Service Account. If you need to use a standard
domain user account, run the installation with the argument USE_MSA=0.
msiexec.exe /i PI_SQL_Data_Access_Server_for_OLE_DB_x64.msi
USE_MSA=0

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 7

PI SQL DAS (OLE DB) installation

5. Verify that the PI SQL Data Access Server (OLE DB) Service is running.

PI SQL DAS silent installation

The PI SQL DAS setup kit extracts several installation modules. The components of the
installation process, their order, and the arguments used to launch the components, are
provided in a configuration file named setup.ini.
You can modify setup.ini to provide different command-line arguments for different stages
of the setup. This might be useful within a well-controlled environment with options that are
known in advance, such as when performing an embedded installation.
The setup kit also contains a file named silent.ini, which contains modifications to
setup.ini that are typically needed to run a silent installation. You can augment these
arguments by adding any of the options described in the following table.
Individual arguments must not contain spaces unless they are surrounded by quotes.
Argument Description
/i Specifies an installation.
/qn Specifies "quiet mode" and suppresses dialog boxes and
prompts. No UI is displayed.

8 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

Argument Description
SERVICE_ACCOUNT_TYPE "Default" corresponds to a virtual service account.
Specify "Custom" to use a custom service account. Use the
SERVICE_ACCOUNT_USERNAME parameter to specify the
account.

SERVICE_ACCOUNT_USERNAME Custom service account user name.

It is recommended that you use Managed Service Accounts.
Specify the USE_MSA=0 argument to use a standard user
account. Make sure to specify the user's password using
SERVICE_ACCOUNT_PASSWORD parameter.

SERVICE_ACCOUNT_PASSWORD Custom service account user's password.

USE_MSA Specifies whether managed service accounts or standard user
accounts are used.
1 means to use Managed Service Accounts. (recommended)
(default = 1).
0 means standard user accounts.

HTTPS_PORT Port used for HTTPS communication (default = 5461).

TCP_PORT Port used for Net.Tcp communication (default = 5462).
SSL_CERT_THUMBPRINT Thumbprint of the certificate used for encrypting the
communication. (Default = <empty> means self-signed
certificate gets generated).
FIREWALL_EXCEPTION 1 means to create the firewall exception (default = 1).
0 means do not create the firewall exception.

Use the following syntax for a silent installation of a single component:

msiexec.exe /i PI_SQL_Data_Access_Server_for_OLE_DB_x64.msi HTTPS_PORT=443 /qn

Note:
To run the complete package in silent mode, replace the setup.ini file with
silent.ini and run Setup.exe, or run Setup -f silent.ini from a command
prompt.

PI SQL DAS (OLE DB) installation results

Files are installed in the PIHOME\SQLDAS directory. The PI SQL Data Access Server (OLE DB)
Windows service is registered with the startup type Automatic, and then it is started. By
default, the service is configured to run as the built-in virtual service account (NT SERVICE
\PISqlDas).
OSIsoft recommends that network administrators not change the service account unless this is
required by company-specific network policies.
Note:
It is possible to use a domain account instead of the service account; however, Kerberos
delegation must be configured accordingly.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 9

PI SQL DAS (OLE DB) installation

By default, PI SQL DAS (OLE DB) uses the following ports for the communication with the
specific driver:
Port Description
5461 The https endpoint is used for secure
communication with trusted connection or explicit
login.
5462 The net.tcp endpoint is used for communication
with trusted connection or explicit login.

You might have third-party firewall or virus scanner tools that restrict communication through
those ports. Make sure those ports are accessible.

PI SQL DAS in a double-hop scenario

A double-hop scenario is a scenario in which a client application is on one computer, the
middleware (PI SQL DAS) is on a second computer, and the resource that requires
impersonated credentials (such as PI Server or PI AF Server) is stored on a third computer.
PI SQL Family clients use the Kerberos protocol for authentication to make this scenario work,
but delegation of end-user credentials must be enabled. For older PI ODBC and PI JDBC

10 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

versions, Kerberos delegation has to be enabled for either the middleware component (PI SQL
DAS machine or PI SQL DAS service account) or the resource (Resource Based Constrained
Delegation). Details for this configuration are described in the following section.
For newer product versions, this additional configuration may not be required because the
client requests delegation if allowed by the Kerberos realm policy. Refer to the corresponding
client administration guide to determine if RFC 5896 is supported.

Kerberos Delegation for PI SQL DAS

Because PI SQL DAS uses the virtual service account, you must enable delegation for the
machine itself. The setting is done on the domain controller by a domain administrator. You can
choose between delegation to any service and delegation to specified services only, which is
more secure.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 11

PI SQL DAS (OLE DB) installation

Note:
A double-hop can only occur if Trusted Connection (TRUSTED CONNECTION=YES) is
specified for the client connection or a domain user account is provided. This is because
the original authentication occurs on the client.
If the driver is provided with a local user name and password, the information is sent to
PI SQL DAS and authentication occurs there, which is one fewer hop.

If you use a managed service account or a standard domain user account to run PI SQL DAS,
you need to enable the delegation for this particular account. Additionally you need to
associate the following service principal names (SPN) with the account:
• HTTP/computer name:port
• HTTP/computer fully qualified domain name:port
The association may be accomplished by using setspn command.
setspn -S HTTP/myserver:port mydomain\myserviceaccount$
setspn -S HTTP/myserver.mydomain.com:port mydomain\myserviceaccount$
If a domain account is used to run PI SQL DAS (OLE DB), Kerberos authentication is currently
supported for HTTPS trusted connection channel only. Net.Tcp connections will not work.

Trusted connection and double-hop scenario

A trusted connection causes that user authentication is done on the client, but data needs to be
accessed on remote resources. It is important that the user account is not restricted regarding
delegation. If you are not sure, consult with your system administrator. The setting is
configured in the domain controller as shown below (option flag must be unchecked).

12 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

See also main section PI SQL DAS in a double-hop scenario.

In the following situations Kerberos delegation might not be required:
• PI SQL DAS is on the same computer as the PI SQL Client.
• PI SQL DAS is on the same computer as the data source (PI Data Archive and PI AF Server).
• PI Trust is configured for PI SQL DAS where all users are mapped to the same credentials -
Provider Type=PIOLEDB only.

Resource Based Constrained Delegation for PI SQL DAS

For basic information about Resource Based Constrained Delegation, see the Microsoft TechNet
article Kerberos Constrained Delegation Overview (https://technet.microsoft.com/en-us/
library/jj553400(v=ws.11).aspx)
Note:
Resource Based Constrained Delegation applies to double-hop scenarios.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 13

PI SQL DAS (OLE DB) installation

Introduction to Resource Based Constrained Delegation

Windows Server 2012 introduced Resource Based Constrained Delegation which removes the
need for Domain Admin rights and also works across domain boundaries or forest boundaries.
Note:
Resource Based Constrained Delegation can only be configured on a domain controller
running Windows Server 2012 and later, but can be applied within a mixed-mode forest.
PI SQL DAS can be deployed on a separate machine which means that a connection using a PI
SQL Client, such as PI ODBC Driver or PI JDBC Driver, spans at least three machines. In such a
scenario most logon options require Kerberos authentication because a double hop is involved.

Authentication - Middleware deployment and double-hop requires Kerberos authentication

Configuration of Resource Based Constrained Delegation

Resource Based Constrained Delegation is configured by using PowerShell. When Resource
Based Constrained Delegation is configured, an attribute is set on the identity of the back-end
service which specifies which front-end service identities are allowed to send delegated
credentials to it.
Note:
The PowerShell module is executed on the back-end machine, in our case that is the PI AF
Server.

Install the Active Directory PowerShell module

Before you start
The Active Directory PowerShell module is required.

14 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

Procedure
1. In the Windows search, type Windows PowerShell and click to start the command-line.
2. Enter the following commands:
# For non-servers this requires installation of
# Remote Server Administration Tools for Windows
Import-Module ServerManager
# This is only for Windows server versions
Add-WindowsFeature RSAT-AD-PowerShell
Import-Module activedirectory

Set PrincipalsAllowedToDelegateToAccount property

Procedure
1. Get the identities of the PI AF Server machine and PI SQL DAS machine into variables:
$afid = Get-ADComputer -Identity MYAFSERVERNAME
$pisqldasid = Get-ADComputer -Identity MYPISQLDASNAME

Note:
If the PI SQL DAS service runs under a domain account, use the Get-ADUser and Set-
ADUser instead.
2. Assign the front-end identity to the PrincipalsAllowedToDelegateToAccount property of the
back-end identity.
Set-ADComputer $afid -PrincipalsAllowedToDelegateToAccount $pisqldasid

Run command as System

Normal user accounts, even when in the local administrators group, may get an error returned
by the Set-ADComputer command. In this case you may use a Windows Systinternals tool to
elevate the system privileges.

Procedure
1. Download PsTools Suite.
Note:
The Windows Sysinternals website contains an introduction to PsTools and the
download of the PsTools Suite (https://technet.microsoft.com/en-us/sysinternals/
bb896649).
2. Run psexec -sid cmd.exe as administrator.
3. In the command window run PowerShell.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 15

PI SQL DAS (OLE DB) installation

4. Verify your identity.

5. When you are System, run the PowerShell command Set-ADComputer as explained in Set
PrincipalsAllowedToDelegateToAccount property.

Settings verification
OSIsoft recommends checking the settings that were made with the following command:
Get-ADComputer $afid -Properties PrincipalsAllowedToDelegateToAccount

Example of verified settings

Certificate for HTTPS communication

PI SQL DAS is automatically configured to use a self-signed certificate, bound to port 5461.

16 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

PI SQL DAS requires an SSL certificate to encrypt traffic between the server and clients. You can
select an SSL certificate using the advanced options during the installation. If another
certificate is already assigned to port 5461 and you select a different certificate, the original
assignment will be overwritten. OSIsoft recommends that you do not use self-signed
certificates.

About PI SQL DAS configuration

PI SQL DAS is a self-hosted Windows Communication Foundation (WCF) service that uses
HTTP transport and SSL/TLS security. As a result, a port is bound with an X.509 certificate.
Secure Sockets Layer (SSL) uses certificates on the client and server to store encryption keys.
The server provides its SSL certificate when a connection is made so that the client can verify
the identity of the server. The server can also request a certificate from the client to provide
mutual authentication of both sides of the connection.
Certificates are stored centralized, according to the IP address and port number of the
connection. The special IP address 0.0.0.0 matches any IP address for the local machine. You
must have administrative privileges to modify the certificates stored on the computer.
If you are required to use enterprise-type security certificates and have not selected it during
the advanced installation, use the following information to configure an enterprise certificate
for PI SQL DAS and bind it to the port used by PI SQL DAS.

Configure PI SQL DAS

Note:
The configuration of PI SQL DAS is optional.
Use the PiSqlDasAutoConfig.exe configuration tool for all basic configurations of PI SQL
DAS. The tool is located in the PIHOME\SQLDAS\Tools directory, where PIHOME is your PIPC
installation directory.
If your IT policies require that you use enterprise-type certificates, you can use the tool to
configure an enterprise certificate for PI SQL DAS and bind it to the port used by PI SQL DAS.

Procedure
1. In a command prompt, run the tool with parameter -e. For example: From the C:\Program
Files\PIPC\SQLDAS\Tools directory, type PiSqlDasAutoConfig.exe -e.
2. Optional: Select a certificate from the Certificates dialog. The certificate must be intended at
least for Client Authentication and Server Authentication.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 17

PI SQL DAS (OLE DB) installation

Note:
Enterprise certificates are typically already installed on your computer if it is part of a
domain. You should see your organization's name in the Issued by row. The certificate
named PISQLDAS is the self-signed certificate used by default.
3. Click OK.
4. This output indicates that the selected certificate has been bound to the SSL port:
C:\Program Files\PIPC\SQLDAS\Tools>PiSqlDasAutoConfig.exe –e
Found existing binding ....deleted
Create new SSL binding ....OK
Updating config file.......OK

In this example, the tool has configured the selected certificate to be used by PI SQL DAS and
bound this certificate to IP address/port 0.0.0.0:5461.
5. Restart the PI SQL DAS service to use the new configuration.

SSL port configuration

Port 5461 is used for PI SQL DAS HTTPS communication.
The configuration tool allows communication from any IP address. For more information, see
Configure PI SQL DAS.
You can use existing operating system tools to further restrict the port if desired. For details,
see the Microsoft Windows documentation about Netsh.exe (http://msdn.microsoft.com/en-
us/library/bb736546), or Windows integrated firewall.
You may also have third-party firewall or virus scanner tools that can restrict communication
through port 5461.

18 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

PI Server login through PI SQL DAS

For the PI Server login, OSIsoft recommends that you use Integrated Security (SSPI)
configuration. PI SQL DAS will log into PI Server with the user credentials of its client, that is,
the PI SQL Client connection.
The Windows user of the PI SQL DAS login must have a trust configured on PI Server, or have a
PI Server identity mapping on PI Server (available in PI Server 3.4.380 or later). For details
about how to configure trusts, see the PI Server topics "Create a trust" in Live Library (https://
livelibrary.osisoft.com) and "Edit a PI trust" in Live Library (https://livelibrary.osisoft.com).
For example, use the following properties to configure a trust for Windows user MyDomain
\User1:
• Trust name: PISQLDAS
• Network Path: PiSqlDas
Note:
The network path must indicate the machine name or fully qualified domain name like
shown in the example above.
• Domain: MyDomain
• Account: User1

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 19

PI SQL DAS (OLE DB) installation

Use the following properties to map a PI Server identity for Windows user MyDomain\User1:
• Name: User1Map
• Windows Account: MyDomain\User1
• Identity: piadmin

20 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

In the PI SQL Client, the authentication information is usually configured in the connection
string. For details, see the related product documentation.

Upgrade scenarios
This section describes the installation behavior when a previous version of PI SQL DAS is
already installed. The following scenarios are possible:

PI SQL Data Access Server 1.3.3.0259 or earlier installed

PI SQL Data Access Server is upgraded.

PI SQL Data Access Server 1.4.1 installed

This version of the PI SQL Data Access Server supports PI Integrator and OLE DB queries as
features, it depends which feature is enabled.
• If the OLE DB feature is not enabled, the new version of PI SQL Data Access Server (OLE DB)
gets installed in parallel. Port sharing gets enabled automatically.
• If the OLE DB feature is enabled and the PI Integrator feature is not; then the new version of
PI SQL Data Access Server (OLE DB) replaces the previous installation.
• If both features PI Integrator and OLE DB are enabled, the OLE DB feature gets disabled and
the new version of PI SQL Data Access Server (OLE DB) gets installed in parallel.

PI SQL Data Access Server (OLE DB) 1.5 installed

PI SQL Data Access Server (OLE DB) gets installed in parallel. Port sharing gets enabled
automatically.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 21

PI SQL DAS (OLE DB) installation

Note:
This is a special situation. PI SQL Data Access Server (Integrator) is installed and a
previous version of PI SQL DAS is installed to support OLE DB queries.

Add an older version of PI SQL Data Access Server

The older version of PI SQL Data Access Server (1.4.1 or earlier) is installed in parallel but does
not detect that port sharing is required. The PI SQL Data Access Server windows service does
not start.
The situation can be fixed in one of the following ways:
• Reinstall PI SQL Data Access Server (OLE DB)
• Repair PI SQL Data Access Server (OLE DB)
Note:
The repair function is only available in the context menu of the .msi file, but not
through the Windows Control Panel.

Repair function for PI SQL DAS (OLE DB)

22 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 PI SQL DAS (OLE DB) installation

Uninstall PI SQL DAS (OLE DB)

Procedure
• In the Windows start menu, click Control Panel > Programs and Features and right-click PI
SQL DAS (OLE DB) > Uninstall.
The Uninstall option automatically stops and deletes the PI SQL DAS (OLE DB) service, and
uninstalls all files.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 23

PI SQL DAS (OLE DB) installation

24 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

Using PI SQL DAS (OLE DB)
The use of PI SQL DAS (OLE DB), including SQL implementation, message logging, and
messaging features, is described in the topics in this section.

SQL implementation
A PI driver delegates all SQL commands via PI SQL DAS (OLE DB) to the underlying query
engine.
• Provider Type=PIOLEDBENT
When connected to PI AF Server, the built-in query engine of PI OLEDB Enterprise is used.
For supported SQL syntax, see the PI OLEDB Enterprise topic "SQL statements" in Live
Library (https://livelibrary.osisoft.com) .
• Provider Type=PIOLEDB
When connected to a PI Server, the built-in query engine of PI OLEDB Provider is used. For
supported SQL syntax, see the PI OLEDB Provider topic "Statements" in Live Library
(https://livelibrary.osisoft.com).
PI OLEDB documentation is available at the OSIsoft Tech Support Downloads page (https://
techsupport.osisoft.com/Downloads/All-Downloads/).

Log message
Procedure
1. Start Event Viewer.
2. Click View > Show Analytic and Debug Logs.
3. Expand to Applications and Services Logs > OSIsoft > SQL > DataAccessServer-OLEDB >
Debug, right-click and click Enable Log.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 25

Using PI SQL DAS (OLE DB)

Now all PI SQL DAS activity gets logged. Use any Event Tracing for Windows (ETW) tool for
analyzing the trace events.
See also Messaging features on how to receive further logging information.

Messaging features
PI SQL Data Access Server Trace
PI SQL DAS (OLE DB) optionally allows to generate logging information. To enable this feature
add the following or similar section to the PiSqlDas.exe.config file:
<system.diagnostics>
<trace autoflush="true">
<listeners>
<clear/>
<!-- Debug output -->
<add name="Default"
type="System.Diagnostics.DefaultTraceListener"/>
<!-- Event log (logs only errors) -->
<add name="EventLog"
type="System.Diagnostics.EventLogTraceListener"
initializeData="PI SQL DAS OLE DB">
<filter type="System.Diagnostics.EventTypeFilter"
initializeData="Error" />
</add>
<!-- Text file-->
<add name="TextFile"
type="System.Diagnostics.TextWriterTraceListener"

26 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 Using PI SQL DAS (OLE DB)

traceOutputOptions="DateTime" initializeData="C:\Temp\PI_SQL_DAS_OLE_DB.log"/>
</listeners>
</trace>
</system.diagnostics>

Note:
You can also direct output to other locations such as Windows Event Log or Console. For
configuration details see How to: Create and Initialize Trace Listeners (https://
msdn.microsoft.com/en-us/library/sk36c28t).

OLE DB Provider Logging

For connections of the type PIOLEDB and PIOLEDBENT, log mechanisms of the corresponding
providers can be used. For more information see the "PI OLEDB Provider User Guide" in Live
Library (https://livelibrary.osisoft.com) or the "PI OLEDB Enterprise User Guide" in Live
Library (https://livelibrary.osisoft.com).

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 27

Using PI SQL DAS (OLE DB)

28 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

Troubleshooting
To identify solutions when a PI driver does not connect or does not receive data, OSIsoft
recommends that you troubleshoot from the ground up, and test components in the order they
are used:

• PI SDK
Check the connectivity using About PI-SDK

• PI OLEDB Enterprise
Verify the functionality using PI SQL Commander

• PI OLEDB Provider
Verify the functionality using PI OLEDB Tester

• PI SQL DAS
Run PI SQL DAS interactively to verify the functionality, or use a PI OLEDB Provider query in
the pilog..pisdklog table to check for PI SQL DAS error messages

• PI driver
Start with the installation on the same computer as PI SQL DAS
Refer to Connection messages and errors for more troubleshooting information.

Run PI SQL DAS (OLE DB) interactively

Procedure
1. To run PI SQL DAS (OLE DB) in interactive mode, start a command prompt.
2. Run the PISqlDas.exe executable file.
Note:
By default, only explicit logins (using PI User authentication) can be used if PI SQL DAS
runs interactively.

Checklist for troubleshooting a trusted connection in a double-

hop scenario
Verify the following points to troubleshoot a trusted connection:
• PI SQL DAS (OLE DB) runs as a service and uses the virtual service account, a managed
service account, or a standard domain user account.
• If you use a virtual service account: The PI SQL DAS machine account that is delegating the
credentials is trusted for delegation. Alternatively, Resource Based Constrained Delegation
is configured on each back-end data source.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 29

Troubleshooting

In case of a managed service or a standard domain user account verify that it is trusted for
the delegation.
• In Active Directory, the Account is sensitive and cannot be delegated check box is cleared
for users who access the application.
• The time stamp on the authenticator does not differ by more than five minutes from the
time stamp of the server.
• TCP/UDP port 88 is not blocked by a firewall or a router. By default, Kerberos
authentication uses TCP/UDP port 88.
• The HOST SPN is registered for the machine account (by default) or HTTP SPN is registered
for the managed service account or standard domain user account (register manually).
You can check the existing set of SPNs for the machine, managed service, or standard
domain user account by running the following command:
Setspn.exe -L <myServer-NetBIOS-name>
Setspn.exe -L <mydomain\myuser>

Connection messages and errors

This topic contains common connection messages, including messages that indicate connection
problems and the corresponding error messages.
These messages are visible as output of the getSnap ODBC sample application.
Other applications might display messages in a message box or log file, depending on how
those applications handle exceptions.

Successful connection
Connected to the PI SQL Data Access Server version 02.09.0000 rev.7979.
Product Version Architecture
------- ------- ------------
PI OLEDB Enterprise 1.4.2.95 64-bit
AF SDK 2.8.5.7759 MSIL
AF Server 2.8.5.7759 MSIL
AF Backend Database 2.9.0.7979
SQL Scripts for PI SQL 3.4.0.0

or
Connected to the PI SQL Data Access Server version 03.04.0405 rev.1198.
Product Version Architecture
------- ------- ------------
PI 3.4.405.1198
PIOLEDB 3.4.1.28 64-bit
PISDK 1.4.6.494 64-bit

Incorrect user name or password for connection to PI SQL DAS

[PI SQL DAS gSOAP Channel] HTTP Error
Details: HTTP/1.1 403 Forbidden

No SSPI configuration or incorrect user name or password

[PISQLDAS] [PIOLEDB][PI SDK] Unable to open a session on a server.
The user name and password may be incorrect. Mypiserver

30 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

 Troubleshooting

Kerberos/Double-hop Issue, no delegation of user credentials

ERROR [08004] [PIODBC] [PIOLEDBENT] [OSIsoft.AFSDK]
Cannot connect to server 'myAFServer'.

Incorrect data source (server) name

[PI SDK] The requested server was not found in the known servers table.
Unable to resolve name to IP address. mypi3

or
PI System 'pisqldas63' is not registered.

Incorrect PI SQL DAS

ERROR [08004] [PIODBC]
System.ServiceModel.EndpointNotFoundException: Could not connect
to net.tcp://myPIServer:5462/DataAccessServer/Query. The
connection attempt lasted for a time span of 00:00:01.0156518. TCP
error code 10061: No connection could be made because the target
machine actively refused it 192.168.0.10:5462.

or
ERROR [08004] [PIODBC] [PI SQL DAS gSOAP Channel] No connection
could be made because the target machine actively refused it.
Details: connect failed in tcp_connect()

Note:
This error message also occurs when the PI SQL DAS port is linked by rules, such as those
implemented by McAfee software (port 5461 or 5462 blocked by access rule).

Firewall does not allow inbound connection on PI SQL DAS side

[PI SQL DAS gSOAP Channel] A connection attempt failed because the
connected party did not properly respond after a period of time,
or established connection failed because connected host has failed
to respond.

SSL not configured (error appears after short timeout)

[PI SQL DAS gSOAP Channel] EOF was observed that violates
the protocol. The client probably provided invalid authentication
information.
Details: SSL connect failed in tcp_connect()

Certificate not suitable error (appears immediately)

[PI SQL DAS gSOAP Channel] EOF was observed that violates the
protocol. The client probably provided invalid authentication
information.
Details: SSL connect failed in tcp_connect()

SSL Certificate binding error (appears immediately)

[PI SQL DAS gSOAP Channel] Error observed by underlying BIO:
Connection reset by peer
Details: SSL connect failed in tcp_connect()

Above error usually corresponds to an error in PiSqlDasAutoConfig.log as shown in the

following screenshot.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 31

Troubleshooting

You might be able to fix the problem by running the configuration tool
PiSqlDasAutoConfig.exe from an administrative account with elevated privileges.

1. Remove the existing configuration by calling PiSqlDasAutoConfig.exe -r

C:\PIPC\SQLDAS\Tools>PiSqlDasAutoConfig.exe -r
SELF-SIGNED certificate : removed
Found existing reservation (5461, OLEDB) : deleted
Found existing reservation (5461, BI) : deleted
2. Generate a new configuration by executing PiSqlDasAutoConfig.exe
C:\Program Files\PIPC\SQLDAS\Tools>PiSqlDasAutoConfig.exe
SELF-SIGNED certificate : created
Create new SSL binding : OK
URL Namespace reservation (5461, OLEDB) : OK
URL Namespace reservation (5461, BI) : OK
Updating config file pisqldas64.exe : OK
Updating config file pisqldas64_bi.exe : OK
See Configure PI SQL DAS if you require the use of enterprise certificates.

32 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

Third-party libraries
Boost library
PI SQL DAS includes the Boost libraries (http://www.boost.org/).
Note:
The license and copyright information documents are located in the PIHOME\SQLDAS
\Doc folder, where PIHOME is your PIPC installation directory.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 33

Third-party libraries

34 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide

Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Tech Support Contact Us page (https://techsupport.osisoft.com/Contact-Us/). The
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
To ask questions of others who use OSIsoft software, join the OSIsoft user community,
PI Square (https://pisquare.osisoft.com). Members of the community can request advice and
share ideas about the PI System. The PI Developers Club space within PI Square offers
resources to help you with the programming and integration of OSIsoft products.

PI SQL Data Access Server (OLE DB) 2018 Administrator Guide 35

Technical support and other resources

36 PI SQL Data Access Server (OLE DB) 2018 Administrator Guide