Installation and Configuration Guide Simba Technologies Inc.

Transcription

1 Simba QuickBooks 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 About This Guide Purpose The Simba QuickBooks ODBC Driver with SQL Connector Installation and Configuration Guide explains how to install and configure the Simba QuickBooks ODBC Driver with SQL Connector. The guide also provides details related to features of the driver. Audience The guide is intended for end users of the Simba QuickBooks ODBC Driver, as well as administrators and developers integrating the driver. Knowledge Prerequisites To use the Simba QuickBooks ODBC Driver, the following knowledge is helpful: Familiarity with the platform on which you are using the Simba QuickBooks ODBC Driver Ability to use the data source to which the Simba QuickBooks ODBC Driver is connecting An understanding of the role of ODBC technologies and driver managers in connecting to a data source Experience creating and configuring ODBC connections Exposure to SQL Document Conventions Italics are used when referring to book and document titles. Bold is used in procedures for graphical user interface elements that a user clicks and text that a user types. Monospace font indicates commands, source code, or contents of text files. Note: A text box with a pencil icon indicates a short note appended to a paragraph. 3

4 Important: A text box with an exclamation mark indicates an important comment related to the preceding paragraph. 4

5 Table of Contents About the Simba QuickBooks ODBC Driver 8 Windows Driver 9 Windows System Requirements 9 Installing the Driver on Windows 9 Creating a Data Source Name 13 Configuring SSL Verification on Windows 19 Exporting a Data Source Name on Windows 20 Importing a Data Source Name on Windows 20 Configuring Logging Options on Windows 21 Configuring Memory Usage on Windows 25 Encrypting Swap Files on Windows 27 Configuring Event Tracing for Windows 27 macos Driver 31 macos System Requirements 31 Installing the Driver on macos 31 Linux Driver 34 Linux System Requirements 34 Installing the Driver on Linux 34 Configuring the ODBC Driver Manager on Non-Windows Machines 38 Specifying ODBC Driver Managers on Non-Windows Machines 38 Specifying the Locations of the Driver Configuration Files 39 Configuring ODBC Connections on a Non-Windows Machine 40 Creating a Data Source Name on a Non-Windows Machine 40 Configuring a DSN-less Connection on a Non-Windows Machine 45 Configuring SSL Verification on Non-Windows Machines 47 Configuring Logging Options on a Non-Windows Machine 48 Configuring Memory Usage on a Non-Windows Machine 50 Encrypting Swap Files on a Non-Windows Machine 53 Testing the Connection on a Non-Windows Machine 53 Using a Connection String 56 DSN Connection String Example 56 DSN-less Connection String Example

6 Features 59 Query Folding 59 OAuth 1.0 Authentication 59 Stored Procedures 60 Memory Manager 60 Swap File Encryption 61 Best Practices 62 Configure Double-Buffering 62 Enable Server-side Data Compression 62 Design Queries that Use Query Folding 62 Design Queries that Use the Top N Command 63 Driver Configuration Options 64 Auth_AccessToken 65 Auth_AccessTokenSecret 65 Auth_BaseRedirectUri 66 Auth_Client_ID 66 Auth_Client_Secret 66 Auth_Expires 67 Auth_Realm 67 Auth_WindowHeight 67 Auth_WindowWidth 68 Driver 68 Enable Double Buffering 69 EncAccessToken 69 EncAccessTokenSecret 70 EncClientSecret 70 EncodingType 70 Encrypt Swap File 71 Host 71 LogFileCount 72 LogFileSize 72 LogLevel 72 LogPath 73 Memory Manager Memory Limit 73 Memory Manager Strategy 74 Memory Manager Swap Disk Limit 75 Memory Manager Threshold Percent

7 Proxy Host 75 Proxy Password 76 Proxy Port 76 Proxy Uid 76 Swap File Path 77 TrustCertsPath 77 Use Encrypted Endpoints 77 Use Host Verification 78 Use Peer Verification 78 Use Windows Proxy Settings 79 Third-Party Trademarks 80 Third-Party Licenses

8 About the Simba QuickBooks ODBC Driver About the Simba QuickBooks ODBC Driver The Simba QuickBooks ODBC Driver enables Business Intelligence (BI), analytics, and reporting on data that is stored in QuickBooks Online. 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 QuickBooks 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 QuickBooks ODBC Driver with SQL Connector Reference Guide. 8

9 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 10. Installing the Driver on Windows The Simba QuickBooks ODBC Driver is delivered in a ZIP archive named SimbaQuickBooks_[Version]_Windows.zip, where [Version] is the version number of the driver. In addition to setup files and documentation, this ZIP archive contains a SimbaQuickBooks32_[Version].zip archive and a SimbaQuickBooks64_[Version].zip archive, each of which contain the files for the 32-bit and 64-bit drivers, respectively. To install the Simba QuickBooks 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 9 and Installing Shared Dependencies on Windows on page

10 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 13. Installing Shared Dependencies on Windows Some Simba drivers, including the Simba QuickBooks 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 QuickBooks 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 QuickBooks 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. 10

11 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 QuickBooks ODBC Driver\lib. Otherwise, create the directory C:\Program Files\Simba\Simba QuickBooks 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 QuickBooks ODBC Driver. Installing the Driver Files on Windows To install the driver, create the installation directory for the Simba QuickBooks 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. 11

12 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 9 and Installing Shared Dependencies on Windows on page 10. 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 QuickBooks ODBC Driver. Otherwise, create the directory C:\Program Files\Simba\Simba QuickBooks ODBC Driver. 2. Extract the SimbaQuickBooks_[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 SimbaQuickBooks32_ [Version].zip archive into a convenient temporary location. To install the 64-bit driver, extract the SimbaQuickBooks64_ [Version].zip archive into a convenient temporary location. 4. Copy the extracted files from the SimbaQuickBooks[Bitness]_[Version] subfolder to the installation directory that you created in step Copy the QuickBooksODBC.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 10. 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. 12

13 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 QuickBooks 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 QuickBooks data. Creating a Data Source Name Typically, after installing the Simba QuickBooks 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 13 or Creating a DSN Using the Windows Registry on page 15. Alternatively, for information about DSN-less connections, see Using a Connection String on page 56. 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 QuickBooks 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. 13

14 Windows Driver 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 QuickBooks. 2. In the ODBC Data Source Administrator, click the Drivers tab, and then scroll down as needed to confirm that the Simba QuickBooks 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 QuickBooks ODBC Driver and then click Finish. The Simba QuickBooks 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 endpoint of the QuickBooks Online server that you are connecting to. 9. In the Consumer Key field, type the consumer key associated with your QuickBooks app. For information about finding your consumer key, see "Get OAuth Keys" in the QuickBooks Online documentation: essentials/000300_your_first_request/0100_get_auth_tokens. 10. In the Consumer Secret field, type the consumer secret associated with your QuickBooks app. For information about finding your consumer secret, see "Get OAuth Keys" in the QuickBooks Online documentation: essentials/000300_your_first_request/0100_get_auth_tokens. 11. In the Realm field, type the company ID associated with your QuickBooks account. 12. Provide an access token tuple (access token and access token secret) by doing one of the following: 14

15 Windows Driver If you already have a valid access token tuple, then do the following: a. In the Access Token field, type your access token. b. In the Access Token Secret field, type your access token secret. Or, to retrieve an access token tuple based on the specified consumer key, consumer secret, and realm, click Get Access Token. The driver uses these settings to authenticate your connection to QuickBooks through an OAuth 1.0 authentication flow. The driver automatically populates the Access Token and Access Token Secret fields with the retrieved access token tuple. For more information, see OAuth 1.0 Authentication on page To retrieve data using double-buffering, select the Enable Double Buffering check box. 14. To encrypt the data source endpoints using HTTPS, select the Use HTTPS check box. 15. 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 QuickBooks ODBC Driver DSN Setup dialog box are correct. Contact your QuickBooks server administrator as needed. 17. To save your settings and close the Simba QuickBooks ODBC Driver DSN Setup dialog box, click OK. 18. 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: 15

16 Windows Driver 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. 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 QuickBooks 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: Host Value Name Description Value Data The endpoint of the QuickBooks Online server that you are connecting to. (Optional) Information about the DSN. 6. Configure authentication by doing one of the following: If you already have a valid access token tuple (access token and access token secret), create the following string values in the DSN subkey: Value Name Value Data Auth_AccessToken Auth_ AccessTokenSecret Your access token. Your access token secret. 16

17 Windows Driver Value Name Auth_Client_ID Value Data The consumer key associated with your QuickBooks app. For information about finding your consumer key, see "Get OAuth Keys" in the QuickBooks Online documentation: online/0100_essentials/000300_your_first_ request/0100_get_auth_tokens. Auth_Client_Secret The consumer secret associated with your QuickBooks app. For information about finding your consumer secret, see "Get OAuth Keys" in the QuickBooks Online documentation: online/0100_essentials/000300_your_first_ request/0100_get_auth_tokens. Auth_Realm The company ID associated with your QuickBooks account. Or, to provide information about your QuickBooks app so that the driver obtains and uses an access token tuple, create the following string values in the DSN subkey: Value Name Auth_ BaseRedirectUri Value Data The redirect URL associated with your QuickBooks app. 17

18 Windows Driver Value Name Auth_Client_ID Value Data The consumer key associated with your QuickBooks app. For information about finding your consumer key, see "Get OAuth Keys" in the QuickBooks Online documentation: online/0100_essentials/000300_your_first_ request/0100_get_auth_tokens. Auth_Client_ Secret The consumer secret associated with your QuickBooks app. For information about finding your consumer secret, see "Get OAuth Keys" in the QuickBooks Online documentation: online/0100_essentials/000300_your_first_ request/0100_get_auth_tokens. Auth_Realm The company ID associated with your QuickBooks account. The driver uses these settings to authenticate your connection to QuickBooks through an OAuth 1.0 authentication flow. For more information, see OAuth 1.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 QuickBooks ODBC Driver, see Driver Configuration Options on page 64. You can now use the DSN in an application to connect to the data store. 18

19 Windows Driver 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 QuickBooks 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. 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. 19

20 Windows Driver 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 0. 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 20

21 Windows Driver import the DSN configuration from, and then click Open. 3. Click OK to close the Logging Options dialog box. The Simba QuickBooks ODBC DriverSimba 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. 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 21 or Configuring Logging Using the ODBC Data Source Administrator on page 23. 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\simbaquickbooks ODBC Driver\lib\RDFODBC\[LibVersion]\vs 21

22 Windows Driver o [CompilerVersion]\setup directory. Otherwise, go to the C:\Program Files\Simba\SimbaQuickBooks 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. 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. 22

23 Windows Driver 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 QuickBooks ODBC Driver produces a log file named SimbaQuickBooksODBCDriver.log at the location you specify using the LogPath setting. 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 Disables all logging. 23

24 Windows Driver Logging Level FATAL ERROR WARNING INFO DEBUG TRACE Description 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. 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 QuickBooks ODBC Driver produces a log file named SimbaQuickBooksODBCDriver.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. 24

25 Windows Driver 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 60. 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 71. 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. 25

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

27 Windows Driver Encrypting Swap Files on Windows To keep all data as secure as possible, the Simba QuickBooks 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 28 Activating ETW Tracing on page 29 Enable Logging on page

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

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

30 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

31 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 31. Installing the Driver on macos The Simba QuickBooks ODBC Driver is delivered in a TAR archive named SimbaQuickBooksODBC_[Version]-OSX.tar.gz, where [Version] is the version number of the driver. To install the Simba QuickBooks 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 31 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 32. Installing Shared Dependencies on macos Some Simba drivers, including the Simba QuickBooks ODBC Driver, depend on a common set of libraries. This provides an opportunity to minimize the installation footprint for each of these drivers. 31

32 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/quickbooks, 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 QuickBooks 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/quickbooks/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 QuickBooks ODBC Driver. Installing the Driver Files on macos To install the driver, create the installation directory for the Simba QuickBooks ODBC Driver by extracting the driver files from the TAR archive and copying them to the 32

33 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 31 and Installing Shared Dependencies on macos on page 31. 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/quickbooks. 2. Extract the SimbaQuickBooksODBC_[Version]-OSX.tar.gz archive into a convenient temporary location. 3. Extract the SimbaQuickBooksODBC_[Version].tar.gz archive into a convenient temporary location. 4. Copy the extracted files from the SimbaQuickBooksODBC_[Version] subfolder to the installation directory that you created in step Copy the QuickBooksODBC.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 31. 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

34 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 35. Installing the Driver on Linux The Simba QuickBooks ODBC Driver is delivered in a TAR archive named SimbaQuickBooksODBC_[Version]-Linux.tar.gz, where [Version] is the version number of the driver. To install the Simba QuickBooks 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 34 and Installing Shared Dependencies on Linux on page