PI ODBC 2016 R2. Administrator Guide

Transcription

1 PI ODBC 2016 R2 Administrator Guide

2 OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA USA Tel: (01) Fax: (01) Web: PI ODBC 2016 R2 Administrator Guide by OSIsoft, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC. OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services, OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API, PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Coresight, PI Data Archive, PI DataLink, PI DataLink Server, PI Developer s Club, PI Integrator for Business Analytics, PI Interfaces, PI JDBC driver, PI Manual Logger, PI Notifications, PI ODBC, PI OLEDB Enterprise, PI OLEDB Provider, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI Visualization Suite, PI Web API, PI Web Services, and RLINK are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners. U.S. GOVERNMENT RIGHTS Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS , DFARS , FAR , FAR , as applicable. OSIsoft, LLC. Version: 3.2 Published: 26 October 2016

3 Contents Introduction... 1 In this Guide... 1 About PI Developer Technologies...1 Architecture... 2 Deployment Options...2 Information for PI ODBC 1.x users... 2 Installation... 5 System Requirements... 5 Install PI ODBC on Windows... 5 Run the PI ODBC driver setup kit... 5 PI ODBC Windows silent installation... 6 PI ODBC files installed... 7 PI ODBC installation results... 7 Verify the PI ODBC installation... 8 Security... 9 Remove PI ODBC...10 Configure PI ODBC Configure the data source name (DSN) ODBC Connection String Format...14 Trusted connection and double-hop scenario Configure the time zone Configure driver properties...18 Using PI ODBC SQL implementation Advanced ODBC topics Message logging Source code example PI SQL Commander Lite Open PI SQL Commander Lite...23 Connect to PI AF Server...24 Run sample SQL queries PI ODBC Driver Limitations Troubleshooting Run PI SQL DAS Interactively Checklist for Troubleshooting a Trusted Connection in a Double-Hop Scenario Connection Messages and Errors Third Party Libraries gsoap Library Boost Library Tested PI ODBC Scenarios PI ODBC 2016 R2 Administrator Guide iii

4 Contents Technical support and other resources iv PI ODBC 2016 R2 Administrator Guide

5 Introduction PI ODBC Driver is an ODBC 3.8 API-compliant driver that provides robust data access to the PI System through the use of SQL queries. ODBC is a specification for a database application programming interface (API). This API is not dependent on any one database management system (DBMS) or operating system. The ODBC API is based on the Common Language Infrastructure (CLI) specifications from Open Group and ISO/IEC. This version of PI ODBC supports connections and queries for: PI Data Archive PI AF Server PI Views (a feature of certain PI Integrator versions) PI ODBC Driver is a member of the PI Developer Technologies product suite (see About PI Developer Technologies for more information). In this Guide This guide includes procedures to install and configure PI ODBC Driver and PI SQL Data Access Server on Windows operating systems. It also provides information about how to use and troubleshoot PI ODBC Driver. Depending on the data source, users of this guide should be familiar with: ODBC technologies PI OLEDB and PI OLEDB Enterprise Pi Integrator Framework About PI Developer Technologies PI 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. PI 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) Service-oriented architecture (PI Web API) Programmatic access (PI SDK and AF SDK) Licensing for PI Developer Technologies is divided into development and runtime licenses. Developers and integrators obtain development licenses for most PI Developer Technologies products through their individual membership to the PI Developer's Club: PI Developers Club PI ODBC 2016 R2 Administrator Guide 1

6 Introduction ( For details, see PI Developers Club FAQ ( The PI System Access (PSA) runtime license enables end users to access PI System data, including time series data in PI Data Archives and asset metadata in AF Servers, using any of the PI ODBC 2015 Developer Technologies. For more information, see OSIsoft website ( or contact OSIsoft Technical Support ( Architecture The PI ODBC driver is an implementation of the ODBC standard based on the ODBC 3.8 API. PI ODBC employs the PI OLEDB Enterprise and PI OLEDB Provider query engines to connect to the PI System and execute queries. Communication from PI ODBC to the PI System requires using the PI SQL Data Access Server (PI SQL DAS). PI SQL DAS serves as a gateway between PI ODBC and the query engine that executes the queries. It provides secure network communication through net.tcp or HTTPS to PI ODBC. Note: For HTTPS connections, PI ODBC supports Transport Layer Security (TLS), version 1.0, 1.1 and 1.2. The TLS version used is negotiated with the PI SQL Data Access Server and depends on its version and the operating systems being involved. PI SQL DAS is also used for PI JDBC connections. PI ODBC and PI JDBC can connect to the same PI SQL DAS at the same time. Deployment Options PI ODBC can be deployed in various combinations. PI ODBC and PI SQL DAS can run on different architectures (32-bit or 64-bit). For details, see the PI SQL Data Access Server Guide. Information for PI ODBC 1.x users PI ODBC 1.x and PI ODBC 2016 are not compatible and upgrading one does not upgrade the other; however, a migration of PI ODBC 1.x applications in many cases is straightforward 2 PI ODBC 2016 R2 Administrator Guide

7 Introduction because many tables in PI ODBC 1.x are also available in the new version (using Data Source Type=PIOLEDB) and many queries therefore look the same. Both PI ODBC versions can coexist and a side-by-side installation is possible. PI ODBC 2016 R2 Administrator Guide 3

8 Introduction 4 PI ODBC 2016 R2 Administrator Guide

9 Installation The PI ODBC setup kits are distributed as self-extracting executable files. Note: The setup kits for each of these components include both 32- and 64-bit versions. Topics in this section System Requirements Install PI ODBC on Windows System Requirements PI ODBC on Windows requires: Microsoft.NET Framework 4.6 For additional information about the PI ODBC release you are using, see PI ODBC Release Notes. Install PI ODBC on Windows You install PI ODBC Driver by performing the following steps. Procedure 1. Run the PI ODBC driver setup kit (see Run the PI ODBC driver setup kit). 2. To validate the installation results, review the files installed (see Files installed). 3. Verify the installation (see Verify the PI ODBC installation) using PI SQL Commander Lite or the ipisql tool. Run the PI ODBC driver setup kit To start the PI ODBC Installation Wizard, run the following program: PI ODBC_2016 R2_.exe PI ODBC 2016 R2 Administrator Guide 5

10 Installation PI ODBC Windows silent installation The PI ODBC 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. If you modify this file, you can provide different command line arguments for different stages of the setup. This may be useful within a well-controlled environment with options that are known in advance, such as in the case of an embedded installation. The setup kit also contains a file named silent.ini that 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 below. Individual arguments must contain no spaces unless they are surrounded by quotes. Argument Description /i Specifies an installation. /qn /qb REBOOT Specifies the "quiet mode" and suppresses dialog boxes and prompts. Specifies the "quiet mode" and suppresses dialog boxes and prompts, only a progress bar dialog is displayed. Specifies the PIHOME folder. If PIHOME (HKEY_LOCAL_MACHINE\SOFTWARE\PISystem) already exists, setting this argument does not have any effect. 6 PI ODBC 2016 R2 Administrator Guide

11 Installation Use this syntax for a silent installation of a single component: msiexec.exe /i PI_ODBC_x86.msi PIPCFOLDER=c:\MYPI /qn msiexec.exe /i PI_ODBC_x64.msi PIPCFOLDER=c:\MIPI64 /qb 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 ODBC files installed After you run the PI ODBC Driver setup kit (see Run the PI ODBC driver setup kit ), you can view a list of files that were installed in the [PIHOME]\ODBC3 directory. Refer to the PI ODBC Release Notes for a complete list of files. PI ODBC installation results Files are installed into the [PIHOME]\ODBC3 directory. The PI ODBC has been registered to Windows and is visible in the ODBC Data Source Administrator as PI ODBC Driver and PI Views. Note: On a 64-bit Windows, a 32-bit version of the PI ODBC driver as well as a 64-bit version are installed. For each architecture there is a separate ODBC Data Source Administrator to be checked. PI ODBC 2016 R2 Administrator Guide 7

12 Installation Verify the PI ODBC installation PI ODBC ships with PI SQL Commander Lite and ipisql command-line tool. You can use them to validate successful installation. PI SQL Commander Lite requires DSNs to be created first (see Configure the data source name (DSN)) while ipisql works with raw connection strings (see ODBC Connection String Format). ipisql The ipisql command-line tool is located in the Tools directory of the PI ODBC installation. To open it, use a Windows PowerShell command window. Procedure 1. Change to the following directory: <PIHOME>\PIPC\ODBC3\Tools 2. Enter the following three parameters: connectionstring query (optional, ipisql has a default query for every datasource) Example connecting to AF Server: PS <PIHOME>\ODBC3\Tools>.\iPiSql.ps1 -connectionstring "Driver=PI ODBC Driver; Server=DAS1; Provider Type=PIOLEDBENT; Provider String={Data Source=AF275; Integrated Security=SSPI}" You should see results such as: Example connecting to PI Data Archive: PS <PIHOME>\ODBC3\Tools>.\iPiSql.ps1 -connectionstring "Driver=PI ODBC Driver; Server=DAS1; Provider Type=PIOLEDB; Provider String={Data Source=PISERVER1; Integrated Security=SSPI}" You should see results such as: Example connecting to PI Views using PI Integrator Framework: PS <PIHOME>\ODBC3\Tools>.\iPiSql.ps1 -connectionstring "Driver=PI Views; Server=PIINTEGRATOR1; Trusted Connection=yes" You should see results such as: 8 PI ODBC 2016 R2 Administrator Guide

13 Installation Security Two logins are required to connect to the PI Server through PI SQL DAS: A login to the PI SQL Data Access Server (see Log on to PI SQL Data Access Server). A login to the backend (PI Data Archive, PI AF Server or PI Integrator Framework Server) (see Log on to Backend.). Log on to PI SQL Data Access Server The ODBC login mechanism is used to connect with the PI SQL Data Access Server. After you install PI ODBC and attempt the first connection with PI SQL Data Access Server, use the login dialog: PI ODBC 2016 R2 Administrator Guide 9

14 Installation Procedure 1. Provide valid Windows user login information for the machine that runs PI SQL DAS: 2. Click Connect. Note: Login credentials are not required when using Trusted connection. Log on to Backend For the PI Data Archive login, OSIsoft recommends that you use Integrated Security (SSPI) configuration. For complete details, see Configuring PI Server Security, available at OSIsoft Technical Support website ( For PI Integrator Framework, delegated authentication is used, which means no extra configuration information is required on the client. In PI ODBC, the authentication information is configured in the ODBC connection string. For details, see Using PI ODBC. Remove PI ODBC To remove PI ODBC on Windows, use Windows Control Panel. 10 PI ODBC 2016 R2 Administrator Guide

15 Configure PI ODBC The following topics describe how to configure PI ODBC. Topics in this section Configure the data source name (DSN) ODBC Connection String Format Trusted connection and double-hop scenario Configure the time zone Configure driver properties Configure the data source name (DSN) A DSN (Data Source Name) is a data structure that contains the information about a specific database that an ODBC driver needs in order to connect to it. Included in the DSN is information such as the name, directory and driver of the database, and, depending on the type of DSN, the ID and password of the user. The ODBC client then just references the preconfigured DSN. In contrast, DSN-less connections require that all the necessary information be specified within the ODBC client. DSNs can be configured using the ODBC Data Source Administrator. On a 64-bit Windows there is a 32-bit and a 64-bit ODBC Data Source Administrator so that DSNs for 32-bit connections and 64-bit connections can be configured separately. When adding a DSN for PI ODBC, first choose PI ODBC Driver or PI Views. Depending on the selection one of the following configuration dialogs display: PI ODBC 2016 R2 Administrator Guide 11

16 Configure PI ODBC The following tables provide details about the different fields in the main window and the fields in each of the tabs. Option DSN Name DSN Description PI SQL Data Access Server Description unique name identifying the DSN description machine name of PI SQL DAS 12 PI ODBC 2016 R2 Administrator Guide

17 Configure PI ODBC Option Trusted Connection User Description Check this box to specify that the driver will request a secure (or trusted) connection to a PI SQL DAS instance. When selected, PI ODBC uses integrated login security to establish connections using this data source. Any login ID or password supplied is ignored. The User ID to use for authentication when you log on to the data source. Data Source tab Option Type AF Server/PI Data Archive Initial catalog Options Description Select PI OLEDB Provider for using the PI OLEDB Provider query engine. Select PI OLEDB Enterprise for using the PI OLEDB Enterprise query engine. AF Server name or PI Data Archive name. default catalog name PI OLEDB Connection String for connection with PI Data Archive, PI OLEDB Enterprise Connection String for connection with PI AF Server. Please refer to the PIOLEDB Enterprise User Guide and PIOLEDB Provider User Manual for supported Connection String syntax. PI OLEDB documentation is available at the OSIsoft Technical Support website ( techsupport.osisoft.com). Note: For security reasons the Log File keyword is disabled. Protocols tab Option Order Protocol Port Description The protocol with the lower order number is tried first. The protocol being used. IP port being used. Workarounds tab Option Command Timeout Maximum string Description Enforces the command timeout for all commands, even if ODBC statement query timeout was specified. Specifies the maximum string size to be returned, as some clients may not handle long string correctly. Use 0 for unlimited size. PI ODBC 2016 R2 Administrator Guide 13

18 Configure PI ODBC Option Variant as String GUID as string No Error on Rollback Stateless connection (not available for PI Views) Description Checking this box will expose original Variant columns as String columns. Checking this box will expose original GUID columns as String columns. Checking this option will suppress errors when rolling back a transaction. Check this box if the connection shall be stateless. Stateless connections will allow the client to remain connected across PI SQL Data Access Server restarts. Note: Stateful commands such as "USE catalog" cannot be used with this option. ODBC Connection String Format To connect to a database without using a DSN, ODBC uses a connection string. The connection string for PI ODBC needs to provide the name of the PI SQL DAS machine and the PI OLEDB Enterprise /PI OLEDB Provider connection string. To use the PI OLEDB Enterprise table set and connect to the PI Asset Framework: Driver={PI ODBC Driver}; Server=<DataAccessServer>; Provider Type=PIOLEDBENT; Provider String ={<pioledbent_connectionstring>}; For example: Driver={PI ODBC Driver}; Server=myDataAccessServer; Provider Type=PIOLEDBENT; Initial Catalog=NuGreen; Provider String ={Data Source=myAFServer; Integrated Security=SSPI;}; To use PI OLEDB Provider tables and connect to the PI Data Archive: Driver={PI ODBC Driver}; Server=<DataAccessServer>; Provider Type=PIOLEDB; Provider String={<pioledb_connectionstring>}; For example: Driver={PI ODBC Driver}; Server=myDataAccessServer; Trusted_Connection=No; UID=User1; PWD=password1; Provider Type=PIOLEDB; Provider String={Data Source=myPIServer; Integrated Security=SSPI;}; To Use PI Views tables: Driver={PI Views};Server=<IntegratorFrameworkServer>; Trusted Connection=True; For example: Driver={PI Views};Server=myIntegratorFrameworkServer; Trusted Connection = True; The following table lists available keywords for the PI ODBC connection string. For Provider String keywords see the PI OLEDB and PI OLEDB Enterprise User Guides. 14 PI ODBC 2016 R2 Administrator Guide

19 Configure PI ODBC Option Trusted_Connection UID or User ID PWD or Password Provider Type Description Yes or True specifies that the driver will request a secure (or trusted) connection to a PI SQL DAS instance. When selected, PI ODBC uses integrated login security to establish connections using this data source. Any login ID or password supplied is ignored. Example: Trusted_Connection=Yes; User ID to use for authentication when you log on to the PI SQL Data Access Server. Password for the PI SQL Data Access Server. PIOLEDB for using the PI OLEDB Provider query engine. PIOLEDBENT for using the PI OLEDB Enterprise query engine Example: Provider Type=PIOLEDBENT; Provider Type is not used for the PI Views driver. Initial Catalog Command Timeout Provider String Variant as String default catalog name Enforces the command timeout for all commands, even if ODBC statement query timeout was specified. PI OLEDB Connection String for Data Source Type=PIOLEDB, PI OLEDB Enterprise Connection String for Data Source Type=PIOLEDBENT. Please refer to the PI OLEDB Enterprise User Guide and PI OLEDB Provider User Manual for supported Connection String syntax. PI OLEDB documentation is available at the OSIsoft Technical Support website OSIsoft Technical Support ( For security reasons the Log File keyword is disabled. Initial Catalog and Command Timeout keywords need to be specified outside the Provider String. Example: Provider String= {Data Source=afserver1; {Integrated Security=SSPI;}; True or False (default) original Variant columns will be exposed as String columns. Example: Variant as String=True; PI ODBC 2016 R2 Administrator Guide 15

20 Configure PI ODBC Option GUID as String No Error on Rollback Stateless Connection (not available for PI Views) Description True or False (default) original GUID columns will be exposed as String columns Example: GUID as String=True; True or False (default) by default, the ODBC driver returns an error if a client operates on manual transactions and tries to rollback a statement. This error can be suppressed. Example: No Error on Rollback=True; True or False (default). Stateless connections will allow the client to remain connected across PI SQL Data Access Server restarts. Note: Stateful commands such as "USE catalog" cannot be used with this option. Trusted connection and double-hop scenario Because for a trusted connection, 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 not sure, consult with your system administrator. The setting is configured in the domain controller as shown below (option flag must be unchecked). 16 PI ODBC 2016 R2 Administrator Guide

21 Configure PI ODBC See also Trusted connection and double-hop scenario. In the following situations Kerberos delegation may not be required: PI SQL Data Access Server is on same computer as the PI ODBC driver PI SQL Data Access Server is on same computer as the Data Source (PI Data Archive or PI AF Server) PI Trust is configured for PI SQL Data Access Server (all users are mapped to the same credentials) Provider Type=PIOLEDB only. Https protocol is used Configure the time zone In this version of the software, Time Zone and DST (daylight savings time) settings for the PI SQL DAS computer and the PI ODBC client computer must be the same. PI ODBC 2016 R2 Administrator Guide 17

22 Configure PI ODBC PI ODBC by default uses "Time Zone=Local;". When connecting to PI SQL Data Access Server (OLE DB), "Time Zone=UTC;" can be used to specify that all timestamps within the SQL statement as well as returned data is in UTC. Connections using Provider Type=PIOLEDB also support "Time Zone=Server;" in which case all timestamps within the SQL statement as well as returned data is in the time of the PI Data Archive server. Configure driver properties The ODBC standard defines several functions that provide information about the driver capabilities. Important parameters for PI ODBC can be retrieved using the following ODBC functions: SQLGetEnvAttr() SQLGetConnectAttr() SQLGetInfo() Output from a sample application is shown below. Consult the ODBC standard documentation provided by Microsoft for additional details. 18 PI ODBC 2016 R2 Administrator Guide

23 Using PI ODBC The topics in this section describe how to use PI ODBC, which includes: information about SQL, Advanced ODBC topics, message logging, and a source code example. A description of PI SQL Commander Lite is also provided. Topics in this section SQL implementation Advanced ODBC topics Message logging Source code example PI SQL Commander Lite PI ODBC Driver Limitations SQL implementation PI ODBC delegates all SQL commands via PI SQL DAS to the underlying query engine. Driver={PI ODBC Driver}; Provider Type=PIOLEDBENT When connected to the PI Asset Framework (AF) Server, the built-in query engine of PIOLEDB Enterprise is used. Please refer to the PI OLEDB Enterprise User Guide for supported SQL syntax. Driver={PI ODBC Driver}; Provider Type=PIOLEDB When connected to a PI Server, the built-in query engine of PIOLEDB is used. Refer to the PI OLEDB Provider User Manual for supported SQL syntax. Driver={PI Views} When connected to a PI Integrator database, the built-in PI Integrator Query Engine is used. Refer to the PI Integrator for Business Analytics documentation for supported SQL syntax. Documentation is available at the OSIsoft Technical Support Website ( techsupport.osisoft.com). Advanced ODBC topics Multithreading PI ODBC supports query execution from multiple threads. We recommend reusing connection objects as much as possible because connection open and close operations are expensive. For example, connection objects can be passed as parameter to a new thread and when that thread is finished, it gives that connection to a connection pool. PI ODBC 2016 R2 Administrator Guide 19

24 Using PI ODBC Multiple Connections Multiple connections from one PI ODBC application to different PI SQL DAS (installed on multiple nodes) are supported. Batch processing To be implemented. ODBC driver and variant data types PI ODBC supports columns that have DBTYPE_VARIANT as the underlying OLE DB data type. PI ODBC uses the same approach as is used for Microsoft ODBC drivers and the underlying SQL Server data type sql_variant. Applications developed in.net, using namespace System.Data.ODBC automatically recognize such a column as Object. To recognize the contained subtype you can use the GetType method ( For native code applications details can be found in this technet article ( technet.microsoft.com/en-us/library/ms aspx). Applications that use binding usually bind the column to a string data type. Message logging PI SQL DAS PI SQL DAS optionally allows to generate logging information. To enable this feature add the following or similar section to the pisqldas64.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"> <filter type="system.diagnostics.eventtypefilter" initializedata="error" /> </add> <!-- Text file--> <add name="textfile" type="system.diagnostics.textwritertracelistener" traceoutputoptions="datetime" initializedata="c:\temp\pi_sql_das.log"/> </listeners> </trace> </system.diagnostics> PI ODBC Note: You can also direct output to other locations such as the Windows Event Log or the Console. For configuration details see How to: Create and Initialize Trace Listeners ( The PI ODBC driver offers several logging mechanisms: a. Remote configuration of PI OLEDB or PIOLEDB Enterprise logging to obtain details about query execution. PI OLEDB logging is configurable by using the Provider String portion of the Connection String. 20 PI ODBC 2016 R2 Administrator Guide

25 Note: For security reasons the Log File keyword is disabled for remote use. Use the ServerLog keyword instead. Note: This mechanism is only available for Driver={PI ODBC Driver}; Provider Type=PIOLEDB or PIOLEDBENT. For Driver={PI Views} the PI SQL DAS logging mechanism is used. b. Tracing via ODBC Manager. Using PI ODBC c. Function Tracing via Event Tracing for Windows (ETW). To use the mechanism, launch Windows Event Viewer and enable Show Analytic and Debug Logs. PI ODBC 2016 R2 Administrator Guide 21

26 Using PI ODBC Then Expand to the OSIsoft-SQL-PIODBC Debug channel and Enable Log. Now all PI ODBC activity will be logged. Use any ETW tool for analyzing the trace events. Source code example The source code for the ipisql.ps1 test application is located in the Tools directory. 22 PI ODBC 2016 R2 Administrator Guide

27 Using PI ODBC For example, you can execute ipisql in the Windows PowerShell ISE to step through the code as shown below. PI SQL Commander Lite PI ODBC includes PI SQL Commander Lite, an application you can use to validate your installation, learn the product, and develop and test queries. For more information, see PI SQL Commander Lite Help, available at the Menu. Open PI SQL Commander Lite Procedure 1. Click Start > All Programs > PI System > PI SQL Commander Lite 2. Connect to a data source that previously has been configured via the ODBC Data Source Administrator. PI ODBC 2016 R2 Administrator Guide 23

28 Using PI ODBC Connect to PI AF Server Procedure 1. Right-click a data source icon in PI SQL Object Explorer and select Connect: 2. Provide credentials for a Windows user account, or select Trusted Connection to use your Windows credentials to connect to the PI SQL Data Access Server: 24 PI ODBC 2016 R2 Administrator Guide

29 Using PI ODBC Note: To access the various PI AF data sources, PI data references, and so on, you must enter login information for an account with valid permissions for the machine that runs the PI AF server. For details, see the topic AF Security through a Firewall in the PI AF Installation and Maintenance User Guide, available at Tech Support ( techsupport.osisoft.com/). A green arrow next to the data source icon indicates that the connection is successful: Run sample SQL queries PI ODBC includes one sample SQL query for each table in the catalogs for PI AF server and PI Data Archive connections. Use these queries to explore PI SQL Commander Lite functionality, or edit and save these queries to use as a custom query. PI ODBC 2016 R2 Administrator Guide 25

30 Using PI ODBC Procedure 1. Connect to a PI AF server and expand the schema under PI AF servers in PI SQL Data Source Object Explorer: 2. Right-click an object in the catalog that represents a table, view or function, and then select Execute Predefined Query: Note: You can edit a sample query and save it as a customized query. Note: For information about two additional collections of sample queries that you can load onto your system using PI SQL Commander Lite, see PI SQL Commander Lite Help. 26 PI ODBC 2016 R2 Administrator Guide

31 Using PI ODBC 3. You can edit a sample query and save it as a customized query. Note: For information about two additional collections of sample queries that you can load onto your system using PI SQL Commander Lite, see PI SQL Commander Lite Help. 4. View the query in the PI SQL Query Editor viewer and its results in the Result pane: PI ODBC 2016 R2 Administrator Guide 27

32 Using PI ODBC Note: For information about two additional collections of sample queries that you can load onto your system using PI SQL Commander Lite, see PI SQL Commander Lite Help. PI ODBC Driver Limitations Time Zone In this version Time Zone/DST settings have to be the same for the PI SQL DAS computer and the PI ODBC client computer. Data Types The following data types are unsupported:.net (AF) Object COM Object, etc. VARIANT containing GUID or VARIANT containing Timestamp Transactions Manual transactions are not supported. Queries should be executed in auto-commit mode. If an application cannot use auto-commit, be aware that queries are executed immediately and commit has no effect. That also means that rollback has no effect. The error after calling rollback can be suppressed by specifying the related workaround in the connection string or DSN. PI Initialization Properties The following Initialization Properties are pre-configured and cannot be changed (their use in the connection string Data Source Options part has no effect): Connection String Keyword Always Return Rowset PI OLEDB Enterprise or PI OLEDB Description If set, all SQL commands return rowsets containing number of rows affected by the execution. Value Log File Full log file path/name. Log File =; The following Initialization Properties have different default values: Always Return Rowset = False; 28 PI ODBC 2016 R2 Administrator Guide

33 Using PI ODBC Connection String Keyword Session ID PI OLEDB Enterprise or PI OLEDB Description Can be a positive integer value or -1. Only applies to consumer processes that work with multiple session objects. Allows for grouping of server connections. All sessions with the same positive Session ID belong to the same group. Server calls within the same group are serialized. Value Session ID = -1; sessions in the same process have own server connections and own cache PI ODBC 2016 R2 Administrator Guide 29

34 Using PI ODBC 30 PI ODBC 2016 R2 Administrator Guide

35 Troubleshooting To identify solutions when PIODBC driver does not connect or does not get data, OSIsoft recommends that you troubleshoot from the ground up, and test components in the order they are used: PI SDK, check connectivity using About PI-SDK PI OLEDB Enterprise, verify functionality using PI SQL Commander PI OLEDB Provider, verify functionality using PI OLEDB Tester PI SQL Data Access Server, run PI SQL DAS interactively to verify functionality or use the PI SQL DAS Event Log to check for PI SQL DAS error messages. PI ODBC, start with installation on same computer as PI SQL DAS Refer to Connection Messages and Errors for more troubleshooting information. Run PI SQL DAS Interactively Procedure 1. To run PI SQL DAS in interactive mode, start a command prompt: Note: By default, only explicit login can be used if PI SQL DAS runs interactively. PI ODBC 2016 R2 Administrator Guide 31

36 Troubleshooting Checklist for Troubleshooting a Trusted Connection in a Double- Hop Scenario Verify that the PI SQL Data Access Server runs as Service and uses the Network Service account. Verify that the PI SQL DAS machine account that is delegating the credentials is trusted for delegation. In Active Directory, verify that the Account is sensitive and cannot be delegated check box is cleared for users who access the application. Verify that the time stamp on the authenticator does not differ by more than five minutes from the time stamp of the server. Verify that TCP/UDP port 88 is not blocked by a firewall or a router. By default, Kerberos authentication uses TCP/UDP port 88. Verify that the HOST SPN is registered for the machine account. This is by default. (You can check the existing set of SPNs for the machine account by running the following command: Setspn.exe -L <myserver-netbios-name> 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 ipisql.ps1 sample application. Other ODBC applications might display messages in a message box or log file, depending on how those applications handle exceptions. Successful Connection (output depends on data source choice) Connected to PI SQL Data Access Server version Product Version Architecture PI PIOLEDB bit PISDK bit Connected to PI SQL Data Access Server version Product Version Architecture PI OLEDB Enterprise bit AF SDK MSIL AF Server MSIL AF Backend Database SQL Scripts for PI SQL Connected to PI SQL Data Access Server version Product Status PI Integrator Framework Ready Incorrect Username or password for connection to PI SQL DAS [PI SQL DAS gsoap Channel] HTTP Error Details: HTTP/ Forbidden 32 PI ODBC 2016 R2 Administrator Guide

37 Troubleshooting No SSPI configuration or incorrect username or password [PISQLDAS] [PIOLEDB][PI SDK] Unable to open a session on a server. The user name and password may be incorrect. Mypiserver 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 [PISQLDAS] [PIOLEDB][PI SDK] The requested server was not found in the known servers table. Unable to resolve name to IP address. mypi3 or: [PI SQL DAS] [PIOLEDBENT] 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: TCP error code 10061: No connection could be made because the target machine actively refused it :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 show in the following screen shot. PI ODBC 2016 R2 Administrator Guide 33

38 Troubleshooting You may be able to fix the problem by running the configuration tool pisqldasautoconfig.exe from an administrative account with elevated privileges on the PI SQL Data Access Server. 1. First remove the existing configuration by calling pisqldasautoconfig.exe C:\PIPC\SQLDAS>pisqldasAutoConfig.exe -r SELF-SIGNED certificate :removed Found existing reservation (5461, OLEDB) :deleted Found existing reservation (5461, BI) :deleted 2. Generate new configuration by executing pisqldasautoconfig.exe C:\Program Files\PIPC\SQLDAS>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 See also the Configure PI SQL Data Access Server (optional) topic in the PI SQL Data Access Server Administrator Guide if you require using enterprise certificates. 34 PI ODBC 2016 R2 Administrator Guide

39 Third Party Libraries The list below provides information about third party libraries that PI ODBC includes. gsoap Library PI ODBC includes the gsoap Library. ( Boost Library PI ODBC includes the Boost Libraries ( Please see the PI ODBC Release Notes for the location of the license and the copyright information documents. PI ODBC 2016 R2 Administrator Guide 35

40 Third Party Libraries 36 PI ODBC 2016 R2 Administrator Guide

41 Tested PI ODBC Scenarios PI ODBC (x86) and Microsoft Access (x86) PI ODBC (x64) and Microsoft Access (x64) PI ODBC (x86) and Microsoft Query 32-bit (MSO ) PI ODBC (x86) and Microsoft Excel 2013 (x86) PI ODBC (x64) and Microsoft Excel 2013 (x64) PI ODBC (x64) and Oracle Database Gateway for ODBC (Oracle 12c) PI ODBC (x86) and Microsoft Power Shell PI ODBC (x64) and Microsoft Power Shell PI ODBC (x64) and TIBCO Spotfire PI ODBC (x64) and Tableau Desktop PI ODBC (x64) and Microsoft Excel 2013 PI ODBC (x64) and Microsoft Power Query for Excel PI ODBC 2016 R2 Administrator Guide 37

42 Tested PI ODBC Scenarios 38 PI ODBC 2016 R2 Administrator Guide

43 Technical support and other resources For technical assistance, contact OSIsoft Technical Support at or through the OSIsoft Tech Support Contact Us page ( 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 ( 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 ODBC 2016 R2 Administrator Guide 39

44 Technical support and other resources 40 PI ODBC 2016 R2 Administrator Guide