Installation and Configuration Guide Simba Technologies Inc.

Transcription

1 Simba ServiceNow ODBC Driver with SQL Connector Installation and Configuration Guide Simba Technologies Inc. Version June 30, 2017

2 Copyright 2017 Simba Technologies Inc. All Rights Reserved. Information in this document is subject to change without notice. Companies, names and data used in examples herein are fictitious unless otherwise noted. No part of this publication, or the software it describes, may be reproduced, transmitted, transcribed, stored in a retrieval system, decompiled, disassembled, reverse-engineered, or translated into any language in any form by any means for any purpose without the express written permission of Simba Technologies Inc. Trademarks Simba, the Simba logo, SimbaEngine, and Simba Technologies are registered trademarks of Simba Technologies Inc. in Canada, United States and/or other countries. All other trademarks and/or servicemarks are the property of their respective owners. Contact Us Simba Technologies Inc. 938 West 8th Avenue Vancouver, BC Canada V5Z 1E5 Tel: +1 (604) Fax: +1 (604)

3 Table of Contents About the Simba ServiceNow ODBC Driver 6 Windows Driver 7 Windows System Requirements 7 Installing the Driver on Windows 7 Creating a Data Source Name on Windows 11 Configuring SSL Verification on Windows 15 Exporting a Data Source Name on Windows 17 Importing a Data Source Name on Windows 17 Configuring Logging Options on Windows 17 Configuring Memory Usage on Windows 21 Encrypting Swap Files on Windows 24 Configuring Event Tracing for Windows 24 macos Driver 28 macos System Requirements 28 Installing the Driver on macos 28 Linux Driver 31 Linux System Requirements 31 Installing the Driver on Linux 31 Configuring the ODBC Driver Manager on Non-Windows Machines 35 Specifying ODBC Driver Managers on Non-Windows Machines 35 Specifying the Locations of the Driver Configuration Files 36 Configuring ODBC Connections on a Non-Windows Machine 37 Creating a Data Source Name on a Non-Windows Machine 37 Configuring a DSN-less Connection on a Non-Windows Machine 41 Configuring SSL Verification on Non-Windows Machines 43 Configuring Logging Options on a Non-Windows Machine 44 Configuring Memory Usage on a Non-Windows Machine 46 Encrypting Swap Files on a Non-Windows Machine 49 Testing the Connection on a Non-Windows Machine 49 Using a Connection String 52 DSN Connection String Example 52 DSN-less Connection String Examples

4 Features 55 Query Folding 55 OAuth 2.0 Authentication 55 Stored Procedures 56 Memory Manager 56 Swap File Encryption 57 Best Practices 58 Configure Double-Buffering 58 Design Queries That Retrieves a Specific Set of columns 58 Use One Session for Multiple Queries 58 Driver Configuration Options 59 Auth_AccessToken 60 Auth_Client_ID 60 Auth_Client_Secret 60 Auth_Expires 61 Auth_RefreshToken 61 Auth_Type 61 Driver 62 Host 62 Enable Double Buffering 62 EncAccessToken 63 EncClientSecret 63 EncodingType 63 Encrypt Swap File 64 LogFileCount 64 LogFileSize 65 LogLevel 65 LogPath 66 Memory Manager Memory Limit 66 Memory Manager Strategy 66 Memory Manager Swap Disk Limit 67 Memory Manager Threshold Percent 68 Proxy Host 68 Proxy Password 68 Proxy Port 69 Proxy Uid 69 Swap File Path

5 TrustCertsPath 70 Use Encrypted Endpoints 70 Use Host Verification 70 Use Peer Verification 71 Use Windows Proxy Settings 71 Third-Party Trademarks 73 Third-Party Licenses

6 About the Simba ServiceNow ODBC Driver About the Simba ServiceNow ODBC Driver The Simba ServiceNow ODBC Driver enables Business Intelligence (BI), analytics, and reporting on data that is stored in ServiceNow. The driver complies with the ODBC 3.80 data standard and adds important functionality such as Unicode, as well as 32- and 64-bit support for high-performance computing environments on all platforms. ODBC is one of the most established and widely supported APIs for connecting to and working with databases. At the heart of the technology is the ODBC driver, which connects an application to the database. For more information about ODBC, see the Data Access Standards Glossary: For complete information about the ODBC specification, see the ODBC API Reference: The Installation and Configuration Guide is suitable for users who are looking to access data residing within ServiceNow from their desktop environment. Application developers may also find the information helpful. Refer to your application for details on connecting via ODBC. For a complete reference guide to the stored procedures available for the driver and database schema tables used by the driver, see the Simba ServiceNow ODBC Driver with SQL Connector Reference Guide. 6

7 Windows Driver Windows Driver Windows System Requirements Install the driver on client machines where the application is installed. Each machine that you install the driver on must meet the following minimum system requirements: One of the following operating systems: o Windows 7 or 10 o Windows Server 2008 or later 35 MB of available disk space Visual C++ Redistributable for Visual Studio 2013 installed (both 32- and 64-bit). You can download the installation packages at To install the driver, you must have Administrator privileges on the machine. In addition, if you are installing multiple drivers and want to minimize the installation footprint, the following libraries must be installed in the Common directory: ICU 53.1 or later OpenSSL or later RDFODBC or later For information about setting up the Common directory, see Installing Shared Dependencies on Windows on page 8. Installing the Driver on Windows The Simba ServiceNow ODBC Driver is delivered in a ZIP archive named SimbaServiceNow_[Version]_Windows.zip, where [Version] is the version number of the driver. In addition to setup files and documentation, this ZIP archive contains a SimbaServiceNow32_[Version].zip archive and a SimbaServiceNow64_[Version].zip archive, each of which contain the files for the 32-bit and 64-bit drivers, respectively. To install the Simba ServiceNow ODBC Driver on Windows, you must do the following: 1. Make sure that the required dependencies are installed on your machine. For more information, see Windows System Requirements on page 7 and Installing Shared Dependencies on Windows on page

8 Windows Driver 2. Create the installation directory by extracting the driver files from the ZIP archives and copying them to the appropriate location, and then linking the driver to the required dependencies. For more information, see Installing the Driver Files on Windows on page Configure the Windows Registry to recognize the driver and point to the necessary driver files. For more information, see Configuring the Windows Registry on page 11. Installing Shared Dependencies on Windows Some Simba drivers, including the Simba ServiceNow ODBC Driver, depend on a common set of libraries. This provides an opportunity to minimize the installation footprint for each of these drivers. To minimize the installation footprint, before installing the driver, make sure that the required libraries are installed in the Common directory, which is located parallel to the driver installation directory. For example, if your driver is installed in C:\Program Files\Simba\Simba ServiceNow ODBC Driver\, the Common directory must be located at C:\Program Files\Simba\Common. Alternatively, if footprint reduction is not required, you can install the libraries in the same location and at the same time as the driver. The libraries are provided with the driver in ZIP archives. The following table lists the libraries that the Simba ServiceNow ODBC Driver requires and the file name of the ZIP archive that contains the library: Required Library ICU 53.1 or later OpenSSL or later RDFODBC or later Archive Name Simba_ICU_[Version]_ vs2013.zip Simba_OpenSSL_[Version]_ vs2013.zip RDFODBC_[Version]_Windows_ vs2013.zip If you are installing these libraries in a shared Common directory, then depending on the bitness of the driver and your machine the full path to this directory must be one of the following: If you are installing the 32-bit driver on a 64-bit machine, then the shared dependencies must be installed in C:\Program Files (x86)\simba\common. 8

9 Windows Driver Otherwise, the shared dependencies must be installed in C:\Program Files\Simba\Common. Alternatively, if you are installing these libraries in the same location as the driver, then they must be installed in the \lib folder of the driver installation folder. To install shared dependencies and minimize the driver footprint on Windows: 1. If the Common directory does not already exist, then create it by doing one of the following: If you are installing the 32-bit driver on a 64-bit machine, create the directory C:\Program Files (x86)\simba\common. Otherwise, create the directory C:\Program Files\Simba\Common. 2. For each library that is not already installed, extract the ZIP archive and then copy the contents from the Common subfolder into the directory from the previous step. To install the shared dependencies in the same location as the driver on Windows: 1. Create the driver s installation directory by doing one of the following: If you are installing the 32-bit driver on a 64-bit machine, create the directory C:\Program Files (x86)\simba\simba ServiceNow ODBC Driver\lib. Otherwise, create the directory C:\Program Files\Simba\Simba ServiceNow ODBC Driver\lib. 2. For each library listed in the table above, extract the ZIP archive and then copy the contents from the Common subfolder into the directory from the previous step. You can now install the Simba ServiceNow ODBC Driver. Installing the Driver Files on Windows To install the driver, create the installation directory for the Simba ServiceNow ODBC Driver by extracting the driver files from the ZIP archive and copying them to the appropriate location. Then, if you are using shared dependencies to minimize the driver footprint, link the driver to the required dependencies. On 64-bit Windows operating systems, you can execute 32- and 64-bit applications transparently. However, 64-bit applications must use 64-bit drivers, and 32-bit applications must use 32-bit drivers. Make sure that you install the version of the driver that matches the bitness of the client application. You can install both versions of the driver on the same machine. 9

10 Windows Driver Important: If you are using shared dependencies to minimize the driver footprint, then before installing the driver, make sure that all the dependencies are installed on your machine. For more information, see Windows System Requirements on page 7 and Installing Shared Dependencies on Windows on page 8. To install the driver files on Windows: 1. If you have not already created the driver s installation directory, then do one of the following: If you are installing the 32-bit driver on a 64-bit machine, create the directory C:\Program Files (x86)\simba\simba ServiceNow ODBC Driver. Otherwise, create the directory C:\Program Files\Simba\Simba ServiceNow ODBC Driver. 2. Extract the SimbaServiceNow_[Version]_Windows.zip archive into a convenient temporary location. 3. Depending on whether you are installing the 32-bit or 64-bit driver, do one of the following: To install the 32-bit driver, extract the SimbaServiceNow32_ [Version].zip archive into a convenient temporary location. To install the 64-bit driver, extract the SimbaServiceNow64_ [Version].zip archive into a convenient temporary location. 4. Copy the extracted files from the SimbaServiceNow[Bitness]_[Version] subfolder to the installation directory that you created in step Copy the ServiceNowODBC.did file from the temporary location in step 2 to the \lib subfolder in the installation directory. 6. If you are using shared dependencies to minimize the driver footprint, then in the installation directory, double-click the ImportDependencies.bat file to run it. The batch file creates the necessary symbolic links between the driver and the dependencies in the Common directory, completing the setup of the driver files. To confirm that the links have been created successfully, navigate to the \lib subfolder in the installation directory and check if it contains additional folders or.dll files with names that correspond to the libraries listed in Installing Shared Dependencies on Windows on page 8. For a complete list of the linked dependency files, in the installation directory, see the file dependencies.xml. You can now finish installing the driver by configuring the Windows Registry. 10

11 Windows Driver Configuring the Windows Registry To complete the installation process, run the appropriate.reg file from the driver package. This creates registry keys that do the following: Define the driver, specifying its location and indicating that it is installed. Specify driver-wide configuration settings (settings that apply to all connections that use the Simba ServiceNow ODBC Driver). To configure the Windows Registry: 1. In the directory where you extracted the driver package, browse to the setup folder. 2. Double-click the.reg file that matches the bitness of the driver and your machine. For example, if you are installing the 32-bit driver on a 64-bit machine, double-click the Setup-32bitDriverOn64Windows.reg file to run it. The system returns a message indicating whether the registry keys were created successfully. If the keys were created successfully, then the driver installation is complete and you can now configure a connection to access your ServiceNow data. Creating a Data Source Name on Windows Typically, after installing the Simba ServiceNow ODBC Driver, you need to create a Data Source Name (DSN). You can create a DSN by specifying settings in the ODBC Data Source Administrator, or by creating specific subkeys in the Windows Registry. For detailed instructions, see Creating a DSN Using the ODBC Data Source Administrator on page 12 or Creating a DSN Using the Windows Registry on page 13. Note: The DSN settings that are available through the ODBC Data Source Administrator support access token authentication. To retrieve the access token through an OAuth 2.0 authentication flow or to authenticate your connection using your ServiceNow user name and password, create your DSN using the Windows Registry instead of the ODBC Data Source Administrator. Alternatively, for information about DSN-less connections, see Using a Connection String on page

12 Windows Driver Creating a DSN Using the ODBC Data Source Administrator To create a DSN using the ODBC Data Source Administrator: 1. Open the ODBC Administrator: If you are using Windows 7 or earlier, click Start > All Programs > Simba ServiceNow ODBC Driver 1.1 > ODBC Administrator. Or, if you are using Windows 8 or later, on the Start screen, type ODBC administrator, and then click the ODBC Administrator search result. Note: Make sure to select the ODBC Data Source Administrator that has the same bitness as the client application that you are using to connect to ServiceNow. 2. In the ODBC Data Source Administrator, click the Drivers tab, and then scroll down as needed to confirm that the Simba ServiceNow ODBC Driver appears in the alphabetical list of ODBC drivers that are installed on your system. 3. Choose one: To create a DSN that only the user currently logged into Windows can use, click the User DSN tab. Or, to create a DSN that all users who log into Windows can use, click the System DSN tab. Note: It is recommended that you create a System DSN instead of a User DSN. Some applications load the data using a different user account, and might not be able to detect User DSNs that are created under another user account. 4. Click Add. 5. In the Create New Data Source dialog box, select Simba ServiceNow ODBC Driver and then click Finish. The Simba ServiceNow ODBC Driver DSN Setup dialog box opens. 6. In the Data Source Name field, type a name for your DSN. 7. Optionally, in the Description field, type relevant details about the DSN. 8. In the Host field, type the URL of the ServiceNow instance that you are connecting to. 9. From the Method drop-down list, select Access Token. 10. In the Access Token field, type your access token. 12

13 Windows Driver 11. To retrieve data using double-buffering, select the Enable Double Buffering check box. 12. To encrypt the data source endpoints using HTTPS, select the Use HTTPS check box. 13. To configure logging behavior for the driver, click Logging Options. For more information, see Configuring Logging Options on Windows on page To test the connection, click Test. Review the results as needed, and then click OK. Note: If the connection fails, then confirm that the settings in the Simba ServiceNow ODBC Driver DSN Setup dialog box are correct. Contact your ServiceNow server administrator as needed. 15. To save your settings and close the Simba ServiceNow ODBC Driver DSN Setup dialog box, click OK. 16. To close the ODBC Data Source Administrator, click OK. You can now use the DSN in an application to connect to the data store. Creating a DSN Using the Windows Registry To create a DSN using the Windows Registry: 1. Choose one: If you are using Windows 7 or earlier, click Start, then type regedit in the Search field, and then click regedit.exe in the search results. Or, if you are using Windows 8 or later, on the Start screen, type regedit, and then click the regedit search result. 2. Navigate to the appropriate registry key for the bitness of your driver and your machine: If you are using the 32-bit driver on a 64-bit machine, then browse to the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI Otherwise, browse to the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI 3. Create a subkey for your DSN by doing the following: a. Right-click the ODBC.INI key and then select New > Key. b. Type a name for your DSN and then press Enter. 13

14 Windows Driver 4. Create the Driver value by doing the following: a. Right-click the DSN subkey and then select New > String Value. b. Type Driver, and then press Enter. c. Right-click the Driver value and then click Modify. d. In the Edit String dialog box, type Simba ServiceNow ODBC Driver in the Value Data field, and then click OK. 5. Repeat the process described in the previous step to create the following string values in the DSN subkey: Value Name Host Description Value Data The URL of the ServiceNow instance that you are connecting to. (Optional) Information about the DSN. 6. Configure authentication by doing one of the following: To authenticate using your ServiceNow user name and password, create the following string values in the DSN subkey: Property Value Auth_Type Basic Authentication UID PWD The user name that you use to access ServiceNow. The password corresponding to your user name. Or, if you have a valid OAuth 2.0 access token, create the following string values in the DSN subkey: Property Value Auth_Type Access Token Auth_AccessToken Your access token. Or, to provide information about your ServiceNow app so that the driver obtains and uses an OAuth 2.0 access token, create the following string values in the DSN subkey: 14

15 Windows Driver Property Value Auth_Type OAuth 2.0 Auth_Client_ID Auth_Client_Secret Auth_Refresh_Token The API key associated with your ServiceNow app. The credential set associated with your ServiceNow app. (Optional) A refresh token. The driver uses these settings to authenticate your connection to ServiceNow through an OAuth 2.0 authentication flow. For more information, see OAuth 2.0 Authentication on page Create key values to configure SSL as needed. For more information see Configuring SSL Verification on Windows on page Optionally, create additional key values as needed to specify other optional connection settings. For detailed information about all the configuration options supported by the Simba ServiceNow ODBC Driver, see Driver Configuration Options on page 59. You can now use the DSN in an application to connect to the data store. Configuring SSL Verification on Windows Note: In this documentation, "SSL" refers to both TLS (Transport Layer Security) and SSL (Secure Sockets Layer). The driver supports up to TLS 1.2. The SSL version used for the connection is the highest version that is supported by both the driver and the server. When connecting to data stores, by default the Windows version of the Simba ServiceNow ODBC Driver uses one-way SSL authentication with peer and host verification. The driver verifies the identity of the server, and the host name specified in the server certificate must match the host name of the server that you are connecting to. To successfully connect to the server, you must either provide the appropriate trusted server certificate or disable peer verification. 15

16 Windows Driver Specifying a Server Certificate The Windows version of the driver enables peer verification by default. The driver uses the certificates in the Windows trust store to verify the server. To add a certificate to the trust store, use the Microsoft Management Console (MMC). For more information, see "Manage Trusted Root Certificates" on Microsoft TechNet: Disabling SSL Verification If peer verification is not required for your connection, disable peer verification so that the driver can connect to the data store. You can also disable host verification and SSL encryption, if necessary. Note: It is recommended that you keep SSL enabled if possible. SSL encryption protects data and credentials when they are transferred over the network, and provides stronger security than authentication alone. To disable SSL verification on Windows: 1. Choose one: If you are using Windows 7 or earlier, click Start, then type regedit in the Search field, and then click regedit.exe in the search results. Or, if you are using Windows 8 or later, on the Start screen, type regedit, and then click the regedit search result. 2. Navigate to the subkey for your DSN: If you are using the 32-bit driver on a 64-bit machine, then browse to the following registry key, where [DSN_Name] is the name of your DSN: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ODBC\ODBC.INI\[DSN_Name] Otherwise, browse to the following registry key, where [DSN_Name] is the name of your DSN: HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\[DSN_Name] 3. To disable peer verification so that the driver does not verify the identity of the server, set the UsePeerVerification value to To disable host verification so that the driver does not require the host name in the server's certificate to match the host name of the server, set the UseHostVerification value to To disable SSL encryption so that the driver does not connect to the server over SSL, set the UseEncryptedEndpoints value to

17 Windows Driver Exporting a Data Source Name on Windows After you configure a DSN, you can export it to be used on other machines. When you export a DSN, all of its configuration settings are saved in a.sdc file. You can then distribute the.sdc file to other users so that they can import your DSN configuration and use it on their machines. To export a Data Source Name on Windows: 1. Open the ODBC Data Source Administrator corresponding to the bitness of the driver, select the DSN, click Configure, and then click Logging Options. 2. Click Export Configuration, specify a name and location for the exported DSN, and then click Save. Your DSN is saved as a.sdc file in the location that you specified. Importing a Data Source Name on Windows You can import a DSN configuration from a.sdc file and then use those settings to connect to your data source. To import a Data Source Name on Windows: 1. Open the ODBC Data Source Administrator corresponding to the bitness of the driver, select the DSN, click Configure, and then click Logging Options. 2. Click Import Configuration, browse to select the.sdc file that you want to import the DSN configuration from, and then click Open. 3. Click OK to close the Logging Options dialog box. The Simba RestSQL ODBC Driver DSN Setup dialog box loads the configuration settings from the selected.sdc file. You can now save this DSN and use it to connect to your data source. Configuring Logging Options on Windows To help troubleshoot issues, you can enable logging. Important: Only enable logging or tracing long enough to capture an issue. Logging decreases performance and can consume a large quantity of disk space. Driver-wide configuration settings, such as logging, are applied to all drivers that use the RDFODBC dependency. 17

18 Windows Driver You can configure logging by setting properties in the rdf.rdfodbc.ini file, or by setting the logging options in the ODBC Data Source Administrator. For detailed instructions, see Configuring Logging Using the rdf.rdfodbc.ini File on page 18 or Configuring Logging Using the ODBC Data Source Administrator on page 20. Configuring Logging Using the rdf.rdfodbc.ini File To enable driver logging using the rdf.rdfodbc.ini file: 1. Navigate to the directory that contains the rdf.rdfodbc.ini file: If you installed the shared dependencies separately to minimize the driver footprint, then navigate to one of the following directories: o If you are using a 32-bit driver on a 64-bit machine, then go to the C:\Program Files (x86)\simba\common\rdfodbc\ [LibVersion]\vs[CompilerVersion]\setup directory. o Otherwise, go to the C:\Program Files\Simba\Common\RDFODBC\[LibVersion]\vs [CompilerVersion]\setup directory. Where [LibVersion] is the RDFODBC version number and [CompilerVersion] is the Visual Studio version number. Otherwise, if you installed the shared dependencies in the same location as the driver, then navigate to one of the following directories: o If you are using the 32-bit driver on a 64-bit machine, then go to the C:\Program Files (x86)\simba\simbaservicenow ODBC Driver\lib\RDFODBC\[LibVersion]\vs [CompilerVersion]\setup directory. o Otherwise, go to the C:\Program Files\Simba\SimbaServiceNow ODBC Driver\lib\RDFODBC\[LibVersion]\vs [CompilerVersion]\setup directory. Where [LibVersion] is the RDFODBC version number and [CompilerVersion] is the Visual Studio version number. 2. Open the rdf.rdfodbc.ini file in a text editor. 3. To specify the level of information to include in the log files, set the LogLevel property to one of the following numbers: Logging Level Description 0 Disables all logging. 18

19 Windows Driver Logging Level Description 1 Logs severe error events that lead the driver to abort. 2 Logs error events that might allow the driver to continue running. 3 Logs events that might result in an error if action is not taken. 4 Logs general information that describes the progress of the driver. 5 Logs detailed information that is useful for debugging the driver. 6 Logs all driver activity. 4. Set the LogPath property to the full path to the folder where you want to save log files. 5. Optionally, set the LogFileSize key to the maximum size of each log file in megabytes (MB). Note: After the maximum file size is reached, the driver creates a new file and continues logging. 6. Optionally, set the LogFileCount key to the maximum number of log files to keep. Note: After the maximum number of log files is reached, each time an additional file is created, the driver deletes the oldest log file. 7. Save the rdf.rdfodbc.ini file. 8. Restart your ODBC application to make sure that the new settings take effect. The Simba ServiceNow ODBC Driver produces a log file named SimbaServiceNowODBCDriver.log at the location you specify using the LogPath setting. 19

20 Windows Driver To disable driver logging using the rdf.rdfodbc.ini file: 1. Navigate to one of the following directories: If you are using a 32-bit driver on a 64-bit machine, then go to the C:\Program Files (x86)\simba\common\rdfodbc\ [LibVersion]\vs[CompilerVersion]\setup directory. Otherwise, go to the C:\Program Files\Simba\Common\RDFODBC\ [LibVersion]\vs[CompilerVersion]\setup directory. Where [LibVersion] is the RDFODBC version number and [CompilerVersion] is the Visual Studio version number. 2. Open the rdf.rdfodbc.ini file in a text editor. 3. Set the LogLevel property to Save the rdf.rdfodbc.ini file. 5. Restart your ODBC application to make sure that the new settings take effect. Configuring Logging Using the ODBC Data Source Administrator To enable driver logging using the ODBC Data Source Administrator: 1. To access logging options, open the ODBC Data Source Administrator where you created the DSN, then select the DSN, then click Configure, and then click Logging Options. 2. From the Log Level drop-down list, select the logging level corresponding to the amount of information that you want to include in log files: Logging Level Description OFF FATAL ERROR WARNING INFO Disables all logging. Logs severe error events that lead the driver to abort. Logs error events that might allow the driver to continue running. Logs events that might result in an error if action is not taken. Logs general information that describes the progress of the driver. 20

21 Windows Driver Logging Level DEBUG TRACE Description Logs detailed information that is useful for debugging the driver. Logs all driver activity. 3. In the Log Path field, specify the full path to the folder where you want to save log files. 4. In the Max Number Files field, type the maximum number of log files to keep. Note: After the maximum number of log files is reached, each time an additional file is created, the driver deletes the oldest log file. 5. In the Max File Size field, type the maximum size of each log file in megabytes (MB). 6. Click OK. 7. Restart your ODBC application to make sure that the new settings take effect. The Simba ServiceNow ODBC Driver produces a log file named SimbaServiceNowODBCDriver.log at the location you specify using the LogPath setting. To disable driver logging using the ODBC Data Source Administrator: 1. Open the ODBC Data Source Administrator where you created the DSN, then select the DSN, then click Configure, and then click Logging Options. 2. From the Log Level drop-down list, select LOG_OFF. 3. Click OK. 4. Restart your ODBC application to make sure that the new settings take effect. Configuring Memory Usage on Windows Some SQL operations, when applied to non-sql data, require data to be cached temporarily before they can be completed. You can configure the Memory Manager feature in the driver to restrict the amount of RAM or disk space that the driver can use to cache data. For more information, see Memory Manager on page

22 Windows Driver Important: By default, when data is cached as a file on disk, it is stored as unencrypted data. For information about encrypting this data to prevent security risks, see Encrypt Swap File on page 64. Driver-wide configuration settings, such as the settings for the Memory Manager, are applied to all drivers that use the RDFODBC dependency. To configure memory usage on Windows: 1. Navigate to one of the following directories: If you are using a 32-bit driver on a 64-bit machine, then go to the C:\Program Files (x86)\simba\common\rdfodbc\ [LibVersion]\vs[CompilerVersion]\setup directory. Otherwise, go to the C:\Program Files\Simba\Common\RDFODBC\ [LibVersion]\vs[CompilerVersion]\setup directory. Where [LibVersion] is the RDFODBC version number and [CompilerVersion] is the Visual Studio version number. 2. Open the rdf.rdfodbc.ini file in a text editor. 3. Set the properties as follows: Property MemoryManagerMemoryLimit MemoryManagerThresholdPercent Value The maximum amount of RAM in megabytes (MB) that the driver can use to cache data for SQL operations. The maximum percentage of the memory limit that can be used by an existing operation. The remaining memory limit is reserved for new operations. 22

23 Windows Driver Property MemoryManagerStrategy SwapFilePath MemoryManagerSwapDiskLimit Value One of the following numbers specifying how the driver restricts RAM usage and manages operations when more RAM is required: 1: The driver does not use any disk space to support SQL operations. 2: The driver restricts the amount of RAM that each operation can use, and uses swap files to support operations if more memory is required. 3: The driver allows the first SQL operation to consume as much RAM as necessary from the amounts specified by the memory limit and threshold, while subsequent operations use the remaining amount. The full path to the directory where the driver creates swap files to temporarily cache data on disk. The maximum total size of all the swap files, in megabytes (MB). When this option is set to 0, there is no limit to the size of the swap files. For more information about each of these settings, including recommendations for setting the MemoryManagerStrategy property, see Driver Configuration Options on page Save the rdf.rdfodbc.ini file. 23

24 Windows Driver Encrypting Swap Files on Windows To keep all data as secure as possible, the Simba ServiceNow ODBC Driver allows you to encrypt the swap file content. Important: Enabling swap file encryption can significantly decrease performance. Only enable swap file encryption in situations where it is required. Driver-wide configuration settings, such as swap file encryption, are applied to all drivers that use the RDFODBC dependency. To enable swap file encryption on Windows: 1. Navigate to one of the following directories: If you are using a 32-bit driver on a 64-bit machine, then go to the C:\Program Files (x86)\simba\common\rdfodbc\ [LibVersion]\vs[CompilerVersion]\setup directory. Otherwise, go to the C:\Program Files\Simba\Common\RDFODBC\ [LibVersion]\vs[CompilerVersion]\setup directory. Where [LibVersion] is the RDFODBC version number and [CompilerVersion] is the Visual Studio version number. 2. Open the rdf.rdfodbc.ini file in a text editor. 3. Set the EncryptSwapFile property to Save the rdf.rdfodbc.ini file. Configuring Event Tracing for Windows Event Tracing for Windows (ETW) is a kernel-level tracing facility that lets developers log kernel or application-defined events to a log file. They can consume the events in real time or from a log file, and use them to debug an application or to determine where performance issues are occurring in the application. This section describes how to configure Simba ODBC drivers to enable ETW. This involves three steps: Registering Drivers as ETW Providers on page 25 Activating ETW Tracing on page 26 Enable Logging on page

25 Windows Driver Registering Drivers as ETW Providers First, register the driver as an ETW provider so that the system knows to look for events from this driver. You must register the driver library file as well as a common library file. Depending on the bitness of the driver and your machine, the commands for registering the driver require different file names and paths. To register the 32-bit driver on a 64-bit machine: 1. From a command line in your development environment, run the following command to register the driver library file: Where: wevtutil im [Database]ODBC32.man /resourcefilepath:"c:\program Files (x86)\ [DriverDir]\lib\[DriverDLL]" /messagefilepath:"c:\program Files (x86)\ [DriverDir]\lib\[DriverDLL]" [Database] is the database type corresponding to the driver. [DriverDir] is the installation directory of the driver. [DriverDLL] is the DLL corresponding to the driver: [Database]ODBCPlugin_sb[Bitness].dll. 2. Run the following command to register the common library file: wevtutil im RDFODBC32.man /resourcefilepath:"c:\program Files (x86)\simba\common\rdfodbc\ [Version]\vs2013\release32mt\lib\RDFODBC_sb32.dll" /messagefilepath:"c:\program Files (x86)\simba\common\rdfodbc\ [Version]\vs2013\release32mt\lib\RDFODBC_sb32.dll" Where [Version] is the version number of the shared library. Important: You must specify absolute paths for both resourcefilepath and messagefilepath. To register a driver that has the same bitness as the machine: 1. From a command line in your development environment, run the following command to register the driver library file: 25

26 Windows Driver Where: wevtutil im [Database]ODBC[Bitness].man /resourcefilepath:"c:\program Files\[DriverDir]\lib\ [DriverDLL]" /messagefilepath:"c:\program Files\ [DriverDir]\lib\[DriverDLL]" [Database] is the database type corresponding to the driver. [DriverDir] is the installation directory of the driver. [Bitness] is the bitness of the driver. [DriverDLL] is the DLL corresponding to the driver: [Database]ODBCPlugin_sb[Bitness].dll. 2. Run the following command to register the common library file: wevtutil im RFODBC[Bitness].man /resourcefilepath:"c:\program Files (x86)\simba\common\rdfodbc\[version]\vs2013\release [Bitness]mt\lib\RDFODBC_sb[Bitness].dll" /messagefilepath:"c:\program Files (x86)\simba\common\rdfodbc\[version]\vs2013\release [Bitness]mt\lib\RDFODBC_sb[Bitness].dll" Where [Version] is the version number of the shared library, and [Bitness] is the bitness of the driver and the shared library. Important: You must specify absolute paths for both resourcefilepath and messagefilepath. Activating ETW Tracing After registering the driver as an ETW provider, modify the driver-wide configuration settings to activate ETW tracing. These settings are specified in a registry key or in the rdf.rdfodbc.ini file, depending on whether the driver is set up to use that file. Important: Settings that you define in the rdf.rdfodbc.ini file apply to all drivers that use that file. 26

27 Windows Driver To activate ETW tracing in the registry key: 1. Choose one: If you are using Windows 7 or earlier, click Start, then type regedit in the Search field, and then click regedit.exe in the search results. Or, if you are using Windows 8 or later, on the Start screen, type regedit, and then click the regedit search result. 2. Navigate to the appropriate registry key for the bitness of your driver: If you are using the 32-bit driver on a 64-bit machine, then browse to the following registry key, where [DriverName] is the driver for which you want to configure tracing: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Simba\ [DriverName]\Driver Otherwise, browse to the following registry key, where [DriverName] is the driver for which you want to configure tracing: HKEY_LOCAL_MACHINE\SOFTWARE\Simba\ [DriverName]\Driver 3. Right-click the Driver key and select New > String Value. 4. Type LogType and press Enter. 5. Right-click the LogType string and select Modify. 6. Type ETW in the Value Data string, and click OK. 7. Close the Registry Editor. To activate ETW tracing in the INI file: 1. In a text editor, open the rdf.rdfodbc.ini file. For a 32-bit driver installed on a 64-bit machine, the rdf.rdfodbc.ini file is located in the C:\Program Files (x86)\simba\common\rdfodbc\ [Version]\vs2013\setup directory. For other installations, the file is located in the C:\Program Files\Simba\Common\RDFODBC\ [Version]\vs2013\setup directory. 2. Set the LogType property to ETW. 3. Save the rdf.rdfodbc.ini file. Enable Logging Finally, to enable ETW logging, you must enable driver logging at level 6 (TRACE). For instructions, see Configuring Logging Options on Windows on page

28 macos Driver macos Driver macos System Requirements Install the driver on client machines where the application is installed. Each machine that you install the driver on must meet the following minimum system requirements: macos version 10.9, 10.10, or MB of available disk space iodbc or later To install the driver, you must have root access on the machine. In addition, if you are installing multiple drivers and want to minimize the installation footprint, the following libraries must be installed in the Common directory: ICU 53.1 or later OpenSSL or later RDFODBC or later For information about setting up the Common directory, see Installing Shared Dependencies on macos on page 28. Installing the Driver on macos The Simba ServiceNow ODBC Driver is delivered in a TAR archive named SimbaServiceNowODBC_[Version]-OSX.tar.gz, where [Version] is the version number of the driver. To install the Simba ServiceNow ODBC Driver, you must do the following: 1. Make sure that the required dependencies are installed on your machine. For more information, see macos System Requirements on page 28 and Installing Shared Dependencies on macos on page Create the installation directory by extracting the driver files from the TAR archives and copying them to the appropriate location, and then linking the driver to the required dependencies. For more information, see Installing the Driver Files on macos on page 29. Installing Shared Dependencies on macos Some Simba drivers, including the Simba ServiceNow ODBC Driver, depend on a common set of libraries. This provides an opportunity to minimize the installation footprint for each of these drivers. 28

29 macos Driver To minimize the installation footprint, before installing the driver, make sure that the required libraries are installed in the Common directory, which is located parallel to the driver installation directory. For example, if your driver is installed in /Library/simba/servicenowodbc, the Common directory must be located at /Library/simba/Common. Alternatively, if footprint reduction is not required, you can install the libraries in the same location and at the same time as the driver. The libraries are provided with the driver in TAR archives. The following table lists the libraries that the Simba ServiceNow ODBC Driver requires and the file name of the TAR archive that contains the library: Required Library ICU 53.1 or later OpenSSL or later RDFODBC or later Archive Name Simba_ICU_[Version]_xcode5_ 1.tar.gz Simba_OpenSSL_[Version]_ xcode5_1.tar.gz RDFODBC_[Version]_OSX_ xcode5_1.tar.gz To install shared dependencies and minimize the driver footprint on macos: 1. If the Common directory does not already exist in the directory where you want to install the driver, then create it. 2. For each dependency that is not already installed, extract the TAR archive and then copy the contents from the Common subfolder into the directory from the previous step. To install the shared libraries in the same location as the driver on macos: 1. Create the driver s installation directory. The recommended location is /Library/simba/servicenowodbc/lib. 2. For each dependency that is not already installed, extract the TAR archive and then copy the contents from the Common subfolder into the directory from the previous step. You can now install and use the Simba ServiceNow ODBC Driver. Installing the Driver Files on macos To install the driver, create the installation directory for the Simba ServiceNow ODBC Driver by extracting the driver files from the TAR archive and copying them to the 29

30 macos Driver appropriate location. Then, if you are using shared dependencies to minimize the driver footprint, link the driver to the required dependencies. Important: If you are using shared dependencies to minimize the driver footprint, then before installing the driver, make sure that all the dependencies are installed on your machine. For more information, see macos System Requirements on page 28 and Installing Shared Dependencies on macos on page 28. To install the driver files on macos: 1. If you have not already done so, create the driver s installation directory. The recommended location is /Library/simba/servicenowodbc. 2. Extract the SimbaServiceNowODBC_[Version]-OSX.tar.gz archive into a convenient temporary location. 3. Extract the SimbaServiceNowODBC_[Version].tar.gz archive into a convenient temporary location. 4. Copy the extracted files from the SimbaServiceNowODBC_[Version] subfolder to the installation directory that you created in step Copy the ServiceNowODBC.did file from the temporary location in step 2 to the /lib subfolder in the installation directory. 6. If you are using shared dependencies to minimize the driver footprint, then in the installation directory, double-click the ImportDependencies.sh file to run it. The batch file creates the necessary symbolic links between the driver and the dependencies in the Common directory, completing the setup of the driver files. To confirm that the links have been created successfully, navigate to the /lib subfolder in the installation directory and check if it contains additional folders or.dylib files with names that correspond to the libraries listed in Installing Shared Dependencies on macos on page 28. For a complete list of the linked dependency files, in the installation directory, see the file Dependencies.ini. Next, configure the environment variables on your machine to make sure that the ODBC driver manager can work with the driver. For more information, see Configuring the ODBC Driver Manager on Non-Windows Machines on page

31 Linux Driver Linux Driver Linux System Requirements Install the driver on client machines where the application is installed. Each machine that you install the driver on must meet the following minimum system requirements: One of the following distributions: o Red Hat Enterprise Linux (RHEL) 6 or 7 o CentOS 6 or 7 o SUSE Linux Enterprise Server (SLES) 11 or 12 o Debian 7 or 8 o Ubuntu or MB of available disk space One of the following ODBC driver managers installed: o o iodbc or later unixodbc or later To install the driver, you must have root access on the machine. In addition, if you are installing multiple drivers and want to minimize the installation footprint, the following libraries must be installed in the Common directory: ICU 53.1 or later OpenSSL or later RDFODBC or later For information about setting up the Common directory, see Installing Shared Dependencies on Linux on page 32. Installing the Driver on Linux The Simba ServiceNow ODBC Driver is delivered in a TAR archive named SimbaServiceNowODBC_[Version]-Linux.tar.gz, where [Version] is the version number of the driver. To install the Simba ServiceNow ODBC Driver, you must do the following: 1. Make sure that the required dependencies are installed on your machine. For more information, see Linux System Requirements on page 31 and Installing Shared Dependencies on Linux on page

32 Linux Driver 2. Create the installation directory by extracting the driver files from the TAR archives and copying them to the appropriate location. Then link the driver to the required dependencies. For more information, see Installing the Driver Files on Linux on page 33. Installing Shared Dependencies on Linux Some Simba drivers, including the Simba ServiceNow ODBC Driver, depend on a common set of libraries. This provides an opportunity to minimize the installation footprint for each of these drivers. To minimize the installation footprint, before installing the driver, make sure that the required libraries are installed in the Common directory, which is located parallel to the driver installation directory. For example, if your driver is installed in /opt/simba/servicenowodbc, the Common directory must be located at /opt/simba/common. Alternatively, if footprint reduction is not required, you can install the libraries in the same location and at the same time as the driver. The libraries are provided with the driver in TAR archives. The following table lists the libraries that the Simba ServiceNow ODBC Driver requires and the file name of the TAR archive that contains the library: Required Library ICU 53.1 or later OpenSSL or later RDFODBC or later Archive Name Simba_ICU_[Version]_gcc4_ 4.tar.gz Simba_OpenSSL_[Version]_ gcc4_4.tar.gz RDFODBC_[Version]_Linux_ gcc4_4.tar.gz To install shared dependencies and minimize the driver footprint on Linux: 1. If the Common directory does not already exist in the directory where you want to install the driver, then create it. 2. For each dependency that is not already installed, extract the TAR archive and then copy the contents from the Common subfolder into the directory from the previous step. To install the shared libraries in the same location as the driver on Linux: 1. Create an installation directory for the driver. The recommended directory is /opt/simba/servicenowodbc/lib. 32

33 Linux Driver 2. For each dependency that is not already installed, extract the TAR archive and then copy the contents from the Common subfolder into the directory from the previous step. You can now install and use the Simba ServiceNow ODBC Driver. Installing the Driver Files on Linux To install the driver, create the installation directory for the Simba ServiceNow ODBC Driver by extracting the driver files from the TAR archive and copying them to the appropriate location. Then, if you are using shared dependencies to minimize the driver footprint, link the driver to the required dependencies. Important: If you are using shared dependencies to minimize the driver footprint, then before installing the driver, make sure that all the dependencies are installed on your machine. For more information, see Linux System Requirements on page 31 and Installing Shared Dependencies on Linux on page 32. To install the driver files on Linux: 1. If you have not already done so, create an installation directory for the driver. The recommended directory is /opt/simba/servicenowodbc. 2. Extract the SimbaServiceNowODBC_[Version]-Linux.tar.gz archive into a convenient temporary location. 3. Depending on whether you are installing the 32-bit or 64-bit driver, do one of the following: To install the 32-bit driver, extract the SimbaServiceNowODBC32- [Version].tar.gz archive into a convenient temporary location. To install the 64-bit driver, extract the SimbaServiceNowODBC64- [Version].tar.gz archive into a convenient temporary location. 4. Copy the extracted files from the SimbaServiceNowODBC[Bitness]- [Version] subfolder to the installation directory that you created in step Copy the ServiceNowODBC.did file from the temporary location in step 2 to the /lib subfolder in the installation directory. 6. If you are using shared dependencies to minimize the driver footprint, then in the installation directory, double-click the ImportDependencies.sh file to run it. The batch file creates the necessary symbolic links between the driver and the dependencies in the Common directory, completing the setup of the driver files. To confirm that the links have been created successfully, navigate to the /lib subfolder in the installation directory and check if it contains additional folders or.so files with names that correspond to the libraries listed in Installing Shared 33