Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce...

34
Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide January 16, 2015 Simba Technologies Inc.

Transcript of Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce...

Page 1: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector

for Salesforce

Installation and Configuration

Guide

January 16, 2015

Simba Technologies Inc.

Page 2: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Copyright © 2012-2015 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, SimbaEngine C/S, SimbaExpress and SimbaLib are registered trademarks of Simba Technologies Inc. All other trademarks and/or servicemarks are the property of their respective owners.

ICU License - ICU 1.8.1 and later

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1995-2010 International Business Machines Corporation and others

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

All trademarks and registered trademarks mentioned herein are the property of their respective owners.

OpenSSL

Copyright (c) 1998-2008 The OpenSSL Project. All rights reserved.

www. s imba .com 2

Page 3: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software must display the following acknowledgment:

"This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)"

4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].

5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project.

6. Redistributions of any form whatsoever must retain the following acknowledgment:

"This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)"

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Expat

Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

www. s imba .com 3

Page 4: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NO INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

rapidjson

Copyright (c) 2011 Milo Yip

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

libcurl

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1996 - 2012, Daniel Stenberg, <[email protected]>.

All rights reserved.

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

www. s imba .com 4

Page 5: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

gSOAP

gSOAP is copyrighted by Robert A. van Engelen, Genivia, Inc.

Copyright (C) 2000-2010 Robert A. van Engelen, Genivia, Inc.

All Rights Reserved.

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.

Contact Us

Simba Technologies Inc. 938 West 8th Avenue Vancouver, BC Canada V5Z 1E5

www.simba.com

Telephone: +1 (604) 633-0008 Information and Product Sales: Extension 2 Technical Support: Extension 3

Fax: +1 (604) 633-0004

Information and Product Sales: [email protected] Technical Support: [email protected] Follow us on Twitter: @SimbaTech

Printed in Canada

www. s imba .com 5

Page 6: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Table of Contents Introduction ........................................................................................................................................................7

Windows Driver ..................................................................................................................................................7 System Requirements ................................................................................................................................7 Installing the Driver ...................................................................................................................................8 Creating a Data Source Name ................................................................................................................8 Configuring Advanced Options ........................................................................................................... 10 Configuring Logging Options .............................................................................................................. 11 Testing the Salesforce Data Source ................................................................................................... 13

Linux Driver ...................................................................................................................................................... 15 System Requirements ............................................................................................................................. 15 Installing the Driver Using the RPM .................................................................................................. 16 Installing the Driver Using the Tarball Package ............................................................................ 17 Setting the LD_LIBRARY_PATH Environment Variable ............................................................... 17

Mac OS X Driver .............................................................................................................................................. 18 System Requirements ............................................................................................................................. 18 Installing the Driver ................................................................................................................................ 18

Configuring ODBC Connections for Linux and Mac OS X ............................................................... 19 Files ............................................................................................................................................................... 19 Sample Files ................................................................................................................................................ 19 Configuring the Environment .............................................................................................................. 20 Configuring the odbc.ini File ............................................................................................................... 20 Configuring the odbcinst.ini File ........................................................................................................ 21 Configuring the simba.salesforceodbc.ini File ............................................................................... 22 Configuring Logging Options .............................................................................................................. 23 Testing the Connection .......................................................................................................................... 24

Features ............................................................................................................................................................. 26 SQL Connector ........................................................................................................................................... 26 Data Types ................................................................................................................................................... 26 Write-Back .................................................................................................................................................. 27

Contact Us ........................................................................................................................................................ 28

Appendix A: Salesforce Object Query Language ................................................................................. 29 Unsupported SOQL Features ................................................................................................................. 29 Known Issues ............................................................................................................................................. 29

Appendix B: Driver Configuration Options ........................................................................................... 30

www. s imba .com 6

Page 7: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Introduction The Simba ODBC Driver with SQL Connector for Salesforce enables Business Intelligence (BI), analytics, and reporting on Salesforce.com data. 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 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 http://www.simba.com/odbc.htm. For complete information on the ODBC 3.80 specification, see the ODBC API Reference at http://msdn.microsoft.com/en-us/library/ms714562(VS.85).aspx

The Simba ODBC Driver with SQL Connector for Salesforce is available for the Microsoft® Windows®, Linux, and Mac OS X operating systems.

Windows Driver

System Requirements The Simba ODBC Driver with SQL Connector for Salesforce requires a Salesforce Enterprise Edition, Unlimited Edition, or Developer Edition account. If you are an existing Salesforce customer and want to upgrade to either Enterprise or Unlimited Edition, please contact your Salesforce account representative.

Note: You will be required to provide login credentials for your Salesforce account when the driver connects to Salesforce.com.

You install the driver on client computers accessing Salesforce.com. Each computer where you install the driver must meet the following minimum system requirements:

• One of the following operating systems (32- and 64-bit editions are supported):

o Windows® XP with SP3

o Windows® Vista

o Windows® 7 Professional

o Windows® Server 2008 R2

• 30 MB of available disk space

The Simba ODBC Driver with SQL Connector for Salesforce is based on Salesforce API version 32.

Important: To install the driver, you need Administrator privileges on the computer.

www. s imba .com 7

Page 8: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Installing the Driver On 64-bit Windows operating systems, you can execute 32- and 64-bit applications transparently. You must use the version of the driver matching the bitness of the client application accessing data on Salesforce.com:

• SimbaSalesforceODBC32.msi for 32-bit applications

• SimbaSalesforceODBC64.msi for 64-bit applications

You can install both versions of the driver on the same computer.

Note: For an explanation of how to use ODBC on 64-bit editions of Windows, see http://www.simba.com/docs/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf

To install Simba ODBC Driver with SQL Connector for Salesforce:

1. Depending on the bitness of your client application, double-click to run SimbaSalesforceODBC32.msi or SimbaSalesforceODBC64.msi

2. Click Next

3. Select the check box to accept the terms of the License Agreement if you agree, and then click Next

4. To change the installation location, click Change, then browse to the desired folder, and then click OK. To accept the installation location, click Next

5. Click Install

6. When the installation completes, click Finish

7. If you received a license file via e-mail, then copy the license file into the \lib subfolder in the installation folder that you selected in step 4.

Note: To avoid security issues, you may need to save the license file on your local computer prior to copying the file into the folder.

Creating a Data Source Name After installing Simba ODBC Driver with SQL Connector for Salesforce, you need to create a Data Source Name (DSN).

To create a Data Source Name (DSN):

1. Click the Start button , then click All Programs, then click the Simba Salesforce ODBC Driver 1.1 program group corresponding to the bitness of the client application accessing data on Salesforce.com, and then click ODBC Administrator

2. In the ODBC Data Source Administrator, click the Drivers tab and verify that the Simba Salesforce ODBC Driver appears in the list of ODBC drivers that are installed on your system.

www. s imba .com 8

Page 9: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

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

4. Click Add

5. In the Create New Data Source dialog box, select Simba Salesforce ODBC Driver, and then click Finish

6. Use the options in the Simba Salesforce Configuration dialog box to configure your DSN:

a. In the Data source name field, type a name for your DSN.

b. Optionally, in the Description field, type relevant details about the DSN.

c. In the Username field, type the user name for your Salesforce account.

Note: When you connect to your data, you will be prompted to provide your Salesforce account credentials. If your user name is saved in the DSN, then you will not need to type it again.

d. In the Password field, type the password corresponding to the user name you typed in step c.

Note: For security reasons, passwords are not saved in the DSN; when you connect to your data, you will be prompted to type your password again. Providing your password in the DSN allows you to test your connection as described in step 7.

e. If you are using a proxy server, then select the Use proxy server check box and then do the following:

i. In the Proxy host field, type the host name or IP address of the proxy server.

ii. In the Proxy port field, type the port number that the proxy server uses for client connections.

iii. In the Proxy username field, type your user name for accessing the proxy server.

iv. In the Proxy password field, type the password corresponding to the user name you typed in step iii.

f. To configure advanced driver options, click Advanced Options. For more information, see “Configuring Advanced Options” on page 10.

g. To configure logging behavior for the driver, click Logging Options. For more information, see “Configuring Logging” on page 11.

7. To test the connection, click Test. Review the results as needed, and then click OK

Note: If the connection fails, then you may need to provide a security token. To obtain a security token, follow the instructions in the Salesforce documentation located at https://help.salesforce.com/apex/HTViewHelpDoc?id=user_security_token.htm. Append the

www. s imba .com 9

Page 10: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

security token (with no spaces) to the end of your password in the Password field, and then test the connection again.

8. To save your settings and close the Simba Salesforce Configuration dialog box, click OK

9. To close the ODBC Data Source Administrator, click OK

Configuring Advanced Options You can configure advanced options to modify the behavior of the driver by using the following:

• Advanced Options dialog box

• Database connection string

Using the Advanced Options dialog box

The Advanced Options dialog box is available from the ODBC Data Source Administrator and the Salesforce Connection dialog box. The Salesforce Connection dialog box appears when you connect to Salesforce.com from a client application using the DSN.

To configure advanced options using the Advanced Options dialog box:

1. To access advanced options, open the ODBC Data Source Administrator where you created the DSN, then select the DSN, then click Configure, and then click Advanced Options

OR

Open the client application that you want to use to connect to Salesforce.com data, and then connect to Salesforce.com using the DSN.

2. To connect to a Salesforce sandbox, select the Enable connection to sandbox URL check box and then type the URL of the sandbox in the Sandbox URL field.

3. To specify the query language that the driver uses to parse queries, select one of the Parse method settings.

4. To configure the driver to infer metadata based on a small sampling of the data rather than all of the data, select the Enable report metadata optimization check box.

Important: Enabling this option allows the driver to run faster, but the metadata may be less accurate.

5. To use the field labels from Salesforce as the labels in the returned data, select the Use Salesforce labels for columns check box.

Note: If this check box is cleared, then the driver uses the field names from Salesforce as the labels in the returned data. Some client applications require the names and labels in the returned data to match.

6. To return data as SQL_WVARCHAR data instead of SQL_VARCHAR data, select the Use SQL_WVARCHAR instead of SQL_VARCHAR check box.

7. To return result set columns as SQL_NUMERIC columns instead of SQL_DOUBLE columns, select the Use SQL_NUMERIC for result set columns of type SQL_DOUBLE check box.

www. s imba .com 10

Page 11: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Note: This option only applies to result set columns that the driver would normally return as SQL_DOUBLE columns. It does not convert all columns into SQL_NUMERIC.

8. To execute reports using the Analytics API instead of using URL, select the Use Analytic API for executing reports.

9. To configure the driver to modify catalog names by removing all invalid SQL-92 identifier characters and replacing all spaces with underscores, select the Sanitize catalog names check box.

10. To configure the driver to remove catalog names from the results of a SQLTables function call, select the Strip catalog name check box.

11. To save your settings and close the Advanced Options dialog box, click OK

Using a Database Connection String

The following is an example of a connection string that sets advanced options: DSN=Sample Simba Salesforce DSN;[email protected];PWD=Password; MetadataLevel=0;ParseMethod=1;UseLabel=1;SanitizeCatalogName=1; StripCatalogName=1;EnableTransactions=1

For more information about the configuration options available in Simba ODBC Driver with SQL Connector for Salesforce, see “Appendix B: Driver Configuration Options” on page 30.

Configuring Logging Options To help troubleshoot issues, you can enable logging. In addition to functionality provided in the Simba ODBC Driver with SQL Connector for Salesforce, the ODBC Data Source Administrator provides tracing functionality.

Important: Only enable logging long enough to capture an issue. Logging decreases performance and can consume a large quantity of disk space.

The driver allows you to set the amount of detail included in log files. Table 1 lists the logging levels provided by the Simba ODBC Driver with SQL Connector for Salesforce, in order from least verbose to most verbose.

Logging Level Description

OFF Disables all logging.

FATAL Logs very severe error events that will lead the driver to abort.

ERROR Logs error events that might still allow the driver to continue running.

WARNING Logs potentially harmful situations.

www. s imba .com 11

Page 12: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Logging Level Description

INFO Logs general information that describes the progress of the driver.

DEBUG Logs detailed information that is useful for debugging the driver.

TRACE Logs more detailed information than the DEBUG level.

Table 1 Simba ODBC Driver with SQL Connector for Salesforce Logging Levels

To enable logging using the Simba ODBC Driver with SQL Connector for Salesforce:

1. In the Simba Salesforce Configuration dialog box, click Logging Options

2. In the Log level list, select the desired level of information to include in log files.

3. In the Log path field, type the full path to the folder where you want to save log files.

OR

Click Browse and select 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).

Note: When the maximum file size is reached, the driver creates a new file and continues logging.

6. Click OK

The Simba ODBC Driver with SQL Connector for Salesforce produces a log file named SalesforceODBC_driver.log at the location you specify using the Log path field.

To disable Simba ODBC Driver with SQL Connector for Salesforce logging:

1. In the Simba Salesforce Configuration dialog box, click Logging Options

2. In the Log level list, select LOG_OFF

3. Click OK

To start tracing using the ODBC Data Source Administrator:

1. In the ODBC Data Source Administrator, click the Tracing tab.

2. In the Log File Path area, click Browse. In the Select ODBC Log File dialog box, browse to the location where you want to save the log file, then type a descriptive file name in the File name field, and then click Save

3. On the Tracing tab, click Start Tracing Now

www. s imba .com 12

Page 13: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

To stop ODBC Data Source Administrator tracing:

On the Tracing tab in the ODBC Data Source Administrator, click Stop Tracing Now

For more information about tracing using the ODBC Data Source Administrator, see the article How to Generate an ODBC Trace with ODBC Data Source Administrator at http://support.microsoft.com/kb/274551

Testing the Salesforce Data Source To test your connection to the Salesforce data source, you can use a client application like Excel or Crystal Reports. You can also use the ODBCTest tool, which is available in the Microsoft Data Access (MDAC) 2.8 Software Development Kit (SDK). You can download the SDK from http://www.microsoft.com/downloads/details.aspx?FamilyID=5067faf8-0db4-429a-b502-de4329c8c850&displaylang=en

To test your Salesforce data source using ODBCTest:

1. Click the Start button , then click Microsoft Data Access SDK 2.8, and then click the Unicode ODBCTest tool corresponding to the bitness of the DSN you want to test.

2. In ODBCTest, click the Conn menu, and then click Full Connect

3. In the Full Connect dialog box, select the DSN that you want to test, then configure the ODBC Behavior and Cursor Library options as needed, and then click OK

4. In the Username field, type the user name for your Salesforce account.

5. In the Password field, type the password corresponding to the user name you typed in step 4.

6. If you are using a proxy server, then select the Use proxy server check box and then do the following:

a. In the Proxy host field, type the host name or IP address of the proxy server.

b. In the Proxy port field, type the port number that the proxy server uses for client connections.

c. In the Proxy username field, type your user name for accessing the proxy server.

d. In the Proxy password field, type the password corresponding to the user name you typed in step c.

7. To configure advanced driver options, click Advanced Options. For more information, see “Configuring Advanced Options” on page 10.

8. In the Salesforce Connection dialog box, click OK

If the connection is successful, then ODBC Test displays a message informing you that you successfully connected to the DSN. For example: Full Connect(Default) Env. Attr. SQL_ATTR_ODBC_VERSION set to SQL_OV_ODBC3 Successfully connected to DSN 'MySalesforceDSN'.

www. s imba .com 13

Page 14: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

If the connection fails, then you may need to provide a security token. To obtain a security token, follow the instructions in the Salesforce documentation located at https://help.salesforce.com/apex/HTViewHelpDoc?id=user_security_token.htm. Append the security token (with no spaces) to the end of your password in the Password field, and then test the connection again.

Displaying a List of Salesforce Reports

Important: Reports are implemented as stored procedures. Therefore, reports are only supported when queries are being parsed as SQL; the Parse Method cannot be set to SOQL_ONLY. For more information, see the description of “Parse Method” in “Appendix B: Driver Configuration Options” on page 30.

To display a list of Salesforce reports using ODBCTest:

1. Follow the procedure in “Testing the Salesforce Data Source” on page 11 to connect to your Salesforce.com data.

2. In ODBC Test, click the Catalog menu, and then click SQLProcedures

3. In the SQLProcedures dialog box, click OK. A message similar to the following appears in the Output window: SQLProcedures: In: StatementHandle = 0x005B32D0, CatalogName =

SQL_NULL_HANDLE, NameLength1 = 0, SchemaName = SQL_NULL_HANDLE, NameLength2 = 0, ProcName = SQL_NULL_HANDLE, NameLength3 = 0

Return: SQL_SUCCESS=0

4. Click the Results menu, and then click Get Data All. The Output window displays a list of all stored procedures, which correspond to Salesforce reports. The list includes standard Salesforce reports as well as custom reports you create. For example: Get Data All: "PROCEDURE_CAT", "PROCEDURE_SCHEM", "PROCEDURE_NAME", "NUM_INPUT_PARAMS", "NUM_OUTPUT_PARAMS", "NUM_RESULT_SETS", "REMARKS", "PROCEDURE_TYPE" "Simba Technologies", "Simba Technologies", "API Usage Last 7 Days", -1, -1, -1, <Null>, 1 "Simba Technologies", "Simba Technologies", "Account History Report", -1, -1, -1, <Null>, 1 ... "Simba Technologies", "Simba Technologies", "Web Lead Source", -1, -1, -1, <Null>, 1 "Simba Technologies", "Simba Technologies", "Web Lead Source by Date", -1, -1, -1, <Null>, 1 105 rows fetched from 8 columns.

Displaying the Results of a Salesforce Report

You run a report the same way you run a stored procedure.

www. s imba .com 14

Page 15: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

For example, to run a report named “API Usage Last 7 Days” using ODBC Test, you would do the following:

1. Follow the procedure in “Testing the Salesforce Data Source” on page 11 to connect to your Salesforce.com data.

2. In the ODBC Test Input window, type the following command:

{call "API Usage Last 7 Days"}

3. Click the SQLExecDirect button ( ) in the toolbar. Results similar to the following appear in the Output window:

SQLExecDirect: In: hstmt = 0x005B32D0, szSqlStr = "", cbSqlStr = -3 Return: SQL_SUCCESS=0

4. Click the Results menu, and then click Get Data All. The Output window displays the report results:

Get Data All: "Name", "Client Id", "Day Of Week", "Call Count", "Username", "E-mail" "Simba Test", "", "Friday", 15, "[email protected]", "[email protected]" "Simba Test", "", "Wednesday", 2, "[email protected]", "[email protected]" "Simba Test", "", "Thursday", 644, "[email protected]", "[email protected]" 3 rows fetched from 6 columns.

Linux Driver

System Requirements The Simba ODBC Driver with SQL Connector for Salesforce requires a Salesforce Enterprise Edition, Unlimited Edition, or Developer Edition account. If you are an existing Salesforce customer and want to upgrade to either Enterprise or Unlimited Edition, please contact your Salesforce account representative.

Note: You will be required to provide login credentials for your Salesforce account when the driver connects to Salesforce.com.

You install the driver on client computers accessing Salesforce.com. Each computer where you install the driver must meet the following minimum system requirements:

• One of the following distributions (32- and 64-bit editions are supported):

o Red Hat® Enterprise Linux® (RHEL) 5.0 or 6.0

o CentOS 5.0 or 6.0

o SUSE Linux Enterprise Server (SLES) 11

• 55 MB of available disk space.

www. s imba .com 15

Page 16: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

• One of the following ODBC driver managers installed:

o iODBC 3.52.7 or above

o unixODBC 2.2.12 or above

The Simba ODBC Driver with SQL Connector for Salesforce is based on Salesforce API version 32.

Installing the Driver Using the RPM You can install the driver using RPMs. There are two versions of the driver for Linux:

• SimbaSalesforceODBC-32bit-Version-Release.rpm for 32-bit

• SimbaSalesforceODBC-Version-Release.rpm for 64-bit

Version is the version number of the driver, and Release is the release number for this version of the driver.

The bitness of the driver that you select should match the bitness of the client application accessing your Salesforce data. For example, if the client application is 64-bit, then you should install the 64-bit driver. Note that 64-bit editions of Linux support both 32- and 64-bit applications. Verify the bitness of your intended application and install the appropriate version of the driver.

Important: Ensure that you install the driver using the RPM corresponding to your Linux distribution.

The Simba ODBC Driver with SQL Connector for Salesforce driver files are installed in the following directories:

• /opt/simba/salesforceodbc/ contains release notes, the Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide in PDF format, and a Readme.txt file that provides plain text installation and configuration instructions.

• /opt/simba/salesforceodbc/ErrorMessages contains error messages required by the driver.

• /opt/simba/salesforceodbc/Setup contains configuration files named odbc.ini, odbcinst.ini, and simba.salesforceodbc.ini

• /opt/simba/salesforceodbc/lib/32 contains the 32-bit Simba ODBC Driver with SQL Connector for Salesforce for Linux.

• /opt/simba/salesforceodbc/lib/64 contains the 64-bit Simba ODBC Driver with SQL Connector for Salesforce for Linux.

www. s imba .com 16

Page 17: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

To install Simba ODBC Driver with SQL Connector for Salesforce:

1. In Red Hat Enterprise Linux 5.0 or CentOS 5.0, log in as the root user, then navigate to the folder containing the driver RPM packages to install, and then type the following at the command line, where RPMFileName is the file name of the RPM package containing the version of the driver that you want to install: yum --nogpgcheck localinstall RPMFileName

OR

In SUSE Linux Enterprise Server 11, log in as the root user, then navigate to the folder containing the driver RPM packages to install, and then type the following at the command line, where RPMFileName is the file name of the RPM package containing the version of the driver that you want to install: zypper install RPMFileName

2. If you received a license file via e-mail, then copy the license file into the /opt/simba/salesforceodbc/lib/32 or /opt/simba/salesforceodbc/lib/64 folder, depending on the version of the driver that you installed.

Note: To avoid security issues, you may need to save the license file on your local computer prior to copying the file into the folder.

Installing the Driver Using the Tarball Package Alternatively, the Simba ODBC Driver with SQL Connector for Salesforce is available for installation using a TAR.GZ tarball package. The tarball package includes the following, where INSTALL_DIR is your chosen installation directory:

• [INSTALL_DIR]/simba/salesforceodbc/ contains release notes, the Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide in PDF format, and a Readme.txt file that provides plain text installation and configuration instructions.

• [INSTALL_DIR]/simba/salesforceodbc/lib/32 contains the 32-bit Simba ODBC Driver with SQL Connector for Salesforce for Linux.

• [INSTALL_DIR]/simba/salesforceodbc/lib/64 contains the 64-bit Simba ODBC Driver with SQL Connector for Salesforce for Linux.

• [INSTALL_DIR]/simba/salesforceodbc/ErrorMessages contains error message files required by the driver.

• [INSTALL_DIR]/simba/salesforceodbc/Setup contains configuration files named odbc.ini, odbcinst.ini, and simba.salesforceodbc.ini

Setting the LD_LIBRARY_PATH Environment Variable The LD_LIBRARY_PATH environment variable must include the paths to the installed ODBC driver manager libraries.

www. s imba .com 17

Page 18: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

For example, if ODBC driver manager libraries are installed in /usr/local/lib, then set LD_LIBRARY_PATH as follows: export LD_LIBRARY_PATH=/usr/local/lib

For information on how to set environment variables permanently, refer to your Linux shell documentation.

For information about creating ODBC connections using the Simba ODBC Driver with SQL Connector for Salesforce, see “Configuring ODBC Connections for Linux and Mac OS X” on page 19.

Mac OS X Driver

System Requirements The Simba ODBC Driver with SQL Connector for Salesforce requires a Salesforce Enterprise Edition, Unlimited Edition, or Developer Edition account. If you are an existing Salesforce customer and want to upgrade to either Enterprise or Unlimited Edition, please contact your Salesforce account representative.

Note: You will be required to provide login credentials for your Salesforce account when the driver connects to Salesforce.com.

You install the driver on client computers accessing Salesforce.com. Each computer where you install the driver must meet the following minimum system requirements:

• Mac OS X version 10.6.8 or later

• 100 MB of available disk space

• iODBC 3.52.7 or above

The Simba ODBC Driver with SQL Connector for Salesforce is based on Salesforce API version 32.

Installing the Driver The Simba ODBC Driver with SQL Connector for Salesforce driver files are installed in the following directories:

• /opt/simba/salesforceodbc/ contains release notes, the Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide in PDF format, and a Readme.txt file that provides plain text installation and configuration instructions.

• /opt/simba/salesforceodbc/ErrorMessages contains error message files required by the driver.

• /opt/simba/salesforceodbc/Setup contains configuration files named odbc.ini, odbcinst.ini, and simba.salesforceodbc.ini

www. s imba .com 18

Page 19: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

• /opt/simba/salesforceodbc/lib/universal contains the Simba ODBC Driver with SQL Connector for Salesforce for Mac OS X.

To install the Simba ODBC Driver with SQL Connector for Salesforce:

1. Double-click SimbaSalesforceODBC.dmg to mount the disk image.

2. Double-click SimbaSalesforceODBC.pkg to run the installer.

3. In the installer, click Continue

4. On the Software License Agreement screen, click Continue, and when the prompt appears, click Agree if you agree to the terms of the License Agreement.

5. To change the installation location, click Change Installation Location, select the desired location, and then click Continue. To accept the installation location and begin the installation, click Install

6. When the installation completes, click Close

7. If you received a license file via e-mail, then copy the license file into the /opt/simba/salesforceodbc/lib/universal folder.

Note: To avoid security issues, you may need to save the license file on your local computer prior to copying the file into the folder.

Configuring ODBC Connections for Linux and Mac OS X

Files ODBC driver managers use configuration files to define and configure ODBC data sources and drivers. By default, the following configuration files residing in the user’s home directory are used:

• .odbc.ini is used to define ODBC data sources, and it is required.

• .odbcinst.ini is used to define ODBC drivers, and it is optional.

• .simba.salesforceodbc.ini is used to configure the Simba ODBC Driver with SQL Connector for Salesforce, and it is required.

Sample Files The driver installation contains the following sample configuration files in the Setup directory:

• odbc.ini

• odbcinst.ini

• simba.salesforceodbc.ini

The names of the sample configuration files do not begin with a period (.) so that they will appear in directory listings by default. A filename beginning with a period (.) is hidden. For odbc.ini and odbcinst.ini, if the default location is used, then the filenames must begin with a

www. s imba .com 19

Page 20: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

period (.). For simba.salesforceodbc.ini, the filename must begin with a period (.) and the file must reside in the user’s home directory.

If the configuration files do not already exist in the user’s home directory, then the sample configuration files can be copied to that directory and renamed. If the configuration files already exist in the user’s home directory, then the sample configuration files should be used as a guide for modifying the existing configuration files.

Configuring the Environment By default, the configuration files reside in the user’s home directory. However, you can use three environment variables—ODBCINI, ODBCSYSINI, and SIMBAINI—to specify different locations for the odbc.ini, odbcinst.ini, and simba.salesforceodbc.ini configuration files by doing the following:

• Set ODBCINI to point to your odbc.ini file.

• Set ODBCSYSINI to point to the directory containing the odbcinst.ini file.

• Set SIMBAINI to point to your simba.salesforceodbc.ini file.

For example, if your odbc.ini and simbasalesforceodbc.ini files are located in /etc and your odbcinst.ini file is located in /usr/local/odbc, then set the environment variables as follows: export ODBCINI=/etc/odbc.ini export ODBCSYSINI=/usr/local/odbc export SIMBAINI=/etc/simba.salesforceodbc.ini

The following search order is used to locate the simba.salesforceodbc.ini file:

1. If the SIMBAINI environment variable is defined, then the driver searches for the file specified by the environment variable.

Important: SIMBAINI must contain the full path, including the filename.

2. The current working directory of the application is searched for a file named simba.salesforceodbc.ini not beginning with a period.

3. The directory ~/ (that is, $HOME) is searched for a hidden file named .simba.salesforceodbc.ini

4. The directory /etc is searched for a file named simba.salesforceodbc.ini not beginning with a period.

Configuring the odbc.ini File ODBC Data Source Names (DSNs) are defined in the odbc.ini configuration file. The file is divided into several sections:

• [ODBC] is optional and used to control global ODBC configuration, such as ODBC tracing.

• [ODBC Data Sources] is required, listing DSNs and associating DSNs with a driver.

• A section having the same name as the data source specified in the [ODBC Data Sources] section is required to configure the data source.

www. s imba .com 20

Page 21: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

The following is an example of an odbc.ini configuration file in Linux: [ODBC Data Sources] Sample Simba Salesforce DSN 32=Simba Salesforce ODBC Driver 32-bit [Sample Simba Salesforce DSN 32] Driver=/opt/simba/salesforceodbc/lib/32/libsimbasfodbc32.so

The following is an example of an odbc.ini configuration file in Mac OS X: [ODBC Data Sources] Sample Simba Salesforce DSN=Simba Salesforce ODBC Driver [Sample Simba Salesforce DSN] Driver=/opt/simba/salesforceodbc/lib/universal/libsimbasfodbc.dylib

To create a data source:

1. Open the .odbc.ini configuration file in a text editor.

2. In the [ODBC Data Sources] section, add a new entry by typing the Data Source Name (DSN), then an equal sign (=), and then the driver name.

3. In the .odbc.ini file, add a new section with a name that matches the DSN you specified in step 2, and then add configuration options to the section. Specify configuration options as key-value pairs.

4. Save the .odbc.ini configuration file.

For information about the configuration options available in the Simba ODBC Driver with SQL Connector for Salesforce, see “Appendix B: Driver Configuration Options” on page 30.

Configuring the odbcinst.ini File ODBC drivers are defined in the odbcinst.ini configuration file. The configuration file is optional because drivers can be specified directly in the odbc.ini configuration file, as described in “Configuring the odbc.ini File” on page 20.

The odbcinst.ini file is divided into the following sections:

• [ODBC Drivers] lists the names of all the installed ODBC drivers.

• A section having the same name as the driver name specified in the [ODBC Drivers] section lists driver attributes and values.

The following is an example of an odbcinst.ini file in Linux: [ODBC Drivers] Simba Salesforce ODBC Driver 32-bit=Installed Simba Salesforce ODBC Driver 64-bit=Installed [Simba Salesforce ODBC Driver 32-bit] Description=Simba Salesforce ODBC Driver (32-bit) Driver=/opt/simba/salesforceodbc/lib/32/libsimbasfodbc32.so [Simba Salesforce ODBC Driver 64-bit] Description=Simba Salesforce ODBC Driver (64-bit) Driver=/opt/simba/salesforceodbc/lib/64/libsimbasfodbc64.so

www. s imba .com 21

Page 22: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

The following is an example of an odbcinst.ini file in Mac OS X: [ODBC Drivers] Simba Salesforce ODBC Driver=Installed [Simba Salesforce ODBC Driver] Description=Simba Salesforce ODBC Driver Driver=/opt/simba/salesforceodbc/lib/universal/libsimbasfodbc.dylib

To define a driver:

1. Open the .odbcinst.ini configuration file in a text editor.

2. In the [ODBC Drivers] section, add a new entry by typing the driver name and then typing =Installed

Note: Type a symbolic name that you want to use to refer to the driver in connection strings or DSNs.

3. In the .odbcinst.ini file, add a new section with a name that matches the driver name you typed in step 2, and then add configuration options to the section based on the sample odbcinst.ini file provided in the Setup directory. Specify configuration options as key-value pairs.

4. Save the .odbcinst.ini configuration file.

Configuring the simba.salesforceodbc.ini File The simba.salesforceodbc.ini file contains configuration settings for the Simba ODBC Driver with SQL Connector for Salesforce. Settings that you define in the simba.salesforceodbc.ini file apply to all connections that use the driver.

To configure the Simba ODBC Driver with SQL Connector for Salesforce to work with your ODBC driver manager:

1. Open the .simba.salesforceodbc.ini configuration file in a text editor.

2. Edit the DriverManagerEncoding setting. The value is usually UTF-16 or UTF-32, depending on the ODBC driver manager you use. iODBC uses UTF-32, and unixODBC uses UTF-16. To determine the correct setting to use, consult your ODBC Driver Manager documentation.

3. Edit the ODBCInstLib setting. The value is the name of the ODBCInst shared library for the ODBC driver manager you use. To determine the correct library to specify, refer to your ODBC driver manager documentation.

The configuration file defaults to the shared library for iODBC. In Linux, the shared library name for iODBC is libiodbcinst.so. In Mac OS X, the shared library name for iODBC is libiodbcinst.dylib

Note: You can specify an absolute or relative filename for the library. For Linux, if you intend to use the relative filename, then the path to the library must be included in the LD_LIBRARY_PATH environment variable.

4. Optionally, configure logging by editing the LogLevel and LogPath settings. For more information, see “Configuring Logging Options” on page 23.

www. s imba .com 22

Page 23: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

5. Save the .simba.salesforceodbc.ini configuration file.

Configuring Logging Options To help troubleshoot issues, you can enable logging in the driver.

Important: Only enable logging long enough to capture an issue. Logging decreases performance and can consume a large quantity of disk space.

Use the LogLevel key to set the amount of detail included in log files. Table 2 lists the logging levels provided by the Simba ODBC Driver with SQL Connector for Salesforce, in order from least verbose to most verbose.

LogLevel value Description

0 Disables all logging.

1 Logs very severe error events that will lead the driver to abort.

2 Logs error events that might still allow the driver to continue running.

3 Logs potentially harmful situations.

4 Logs general information that describes the progress of the driver.

5 Logs detailed information that is useful for debugging the driver.

6 Logs more detailed information than LogLevel=5

Table 2 Simba ODBC Driver with SQL Connector for Salesforce Logging Levels

To enable logging:

1. Open the simba.salesforceodbc.ini configuration file in a text editor.

2. Set the LogLevel key to the desired level of information to include in log files. For example: LogLevel=2

3. Set the LogPath key to the full path to the folder where you want to save log files. For example: LogPath=/localhome/employee/Documents

4. Save the simba.salesforceodbc.ini configuration file.

The Simba ODBC Driver with SQL Connector for Salesforce produces a log file named SalesforceODBC_driver.log at the location you specify using the LogPath key.

www. s imba .com 23

Page 24: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

To disable logging:

1. Open the simba.salesforceodbc.ini configuration file in a text editor.

2. Set the LogLevel key to 0

3. Save the simba.salesforceodbc.ini configuration file.

Testing the Connection To test your connection to the Salesforce data source, you can use an ODBC-enabled client application. For a basic connection test, you can also use the test utilities that are packaged with your driver manager installation.

For example, the iODBC driver manager includes simple utilities called iodbctest and iodbctestw. Similarly, the unixODBC driver manager includes simple utilities called isql and iusql.

Using the iODBC Driver Manager

You can use the iodbctest and iodbctestw utilities to establish a test connection with your driver. Use iodbctest to test how your driver works with an ANSI application, or use iodbctestw to test how your driver works with a Unicode application.

Note: There are 32-bit and 64-bit installations of the iODBC driver manager available. If you have only one or the other installed, then the appropriate version of iodbctest (or iodbctestw) is available. However, if you have both 32- and 64-bit versions installed, then you need to ensure that you are running the version from the correct installation directory.

For more information about using the iODBC driver manager, see http://www.iodbc.org

To test your connection using the iODBC driver manager:

1. Run iodbctest or iodbctestw. The program prompts you for an ODBC connection string.

2. Optionally, if you do not remember the DSN, then type a question mark (?) to see a list of DSNs.

3. Type an ODBC connection string using the following format: DSN=DataSourceName;UID=UserID;PWD=Password

DataSourceName is the DSN that you are using for the connection, and UserID and Password are your credentials for accessing the Salesforce data source.

If the connection is successful, then the SQL> prompt appears.

If the connection fails, then you may need to provide a security token. To obtain a security token, follow the instructions in the Salesforce documentation located at https://help.salesforce.com/apex/HTViewHelpDoc?id=user_security_token.htm. Append the security token (with no spaces) to the end of your password and test the connection again.

www. s imba .com 24

Page 25: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Using the unixODBC Driver Manager

You can use the isql and iusql utilities to establish a test connection with your driver and your DSN. Use isql to test how your driver works with an ANSI application, or use iusql to test how your driver works with a Unicode application.

Important: isql and iusql can only be used to test connections that use a DSN.

Note: There are 32-bit and 64-bit installations of the unixODBC driver manager available. If you have only one or the other installed, then the appropriate version of isql (or iusql) is available. However, if you have both 32- and 64-bit versions installed, then you need to ensure that you are running the version from the correct installation directory.

For more information about using the unixODBC driver manager, see http://www.unixodbc.org

To test your connection using the unixODBC driver manager:

Run isql using the following syntax: isql DataSourceName UserID Password

DataSourceName is the DSN that you are using for the connection, and UserID and Password are your credentials for accessing the Salesforce data source.

OR

Run iusql using the following syntax: iusql DataSourceName UserID Password

DataSourceName is the DSN that you are using for the connection, and UserID and Password are your credentials for accessing the Salesforce data source.

If the connection is successful, then the SQL> prompt appears.

If the connection fails, then you may need to provide a security token. To obtain a security token, follow the instructions in the Salesforce documentation located at https://help.salesforce.com/apex/HTViewHelpDoc?id=user_security_token.htm. Append the security token (with no spaces) to the end of your password and test the connection again.

Displaying Results of a Salesforce Report

You run a report the same way you run a stored procedure.

For example, to run a report named “API Usage Last 7 Days” using iODBCTest or iSQL, you would do the following:

1. Follow the procedure in “Using the iODBC Driver Manager” on page 24 to connect to your Salesforce.com data.

OR

Follow the procedure in “Using the unixODBC Driver Manager” on page 25 to connect to your Salesforce.com data.

www. s imba .com 25

Page 26: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

2. At the utility command line, type the following, and then press ENTER: {call "API Usage Last 7 Days"}

The report results are displayed. For example: Name | Client Id |Day Of Week | Call Count | Username | E-mail Simba | | Tuesday | 6 | [email protected] | [email protected] Simba | | Wednesday | 21 | [email protected] | [email protected] result set 1 returned 2 rows.

Features

SQL Connector The SQL Connector feature of the driver allows applications to use normal SQL queries against Salesforce.com, translating standard SQL-92 queries into equivalent Salesforce API calls. This allows standard queries that BI tools execute to run against your Salesforce data source.

Data Types The Simba ODBC Driver with SQL Connector for Salesforce supports many common data formats, converting them between Salesforce data types and SQL data types.

Table 3 lists the supported data type mappings.

Salesforce Type SQL Type

Address SQL_VARCHAR or SQL_WVARCHAR

AnyType SQL_VARCHAR or SQL_WVARCHAR

Auto Number SQL_VARCHAR or SQL_WVARCHAR

Checkbox SQL_BIT

Combobox SQL_VARCHAR or SQL_WVARCHAR

Currency SQL_NUMERIC

Date SQL_TYPE_DATE

DateCategoryGroupReference SQL_VARCHAR or SQL_WVARCHAR

Date/Time SQL_TYPE_TIMESTAMP

Email SQL_VARCHAR or SQL_WVARCHAR

Id SQL_VARCHAR

Lookup Relationship SQL_VARCHAR or SQL_WVARCHAR

Multi-Select Picklist SQL_VARCHAR or SQL_WVARCHAR

Percent SQL_NUMERIC

www. s imba .com 26

Page 27: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Salesforce Type SQL Type

Phone SQL_VARCHAR or SQL_WVARCHAR

Picklist SQL_VARCHAR or SQL_WVARCHAR

Reference SQL_VARCHAR or SQL_WVARCHAR

Text SQL_VARCHAR or SQL_WVARCHAR

Text Area SQL_VARCHAR or SQL_WVARCHAR

Text Area (Long) SQL_VARCHAR or SQL_WVARCHAR

Text Area (Rich) SQL_VARCHAR or SQL_WVARCHAR

Text (Encrypted) SQL_VARCHAR or SQL_WVARCHAR

Time SQL_TYPE_TIME

URL SQL_VARCHAR or SQL_WVARCHAR

Table 3 Supported Data Types

Note: For information about how the driver returns data as SQL_VARCHAR or SQL_WVARCHAR, see the description of the “Use SQL_WVARCHAR instead of SQL_VARCHAR” option in “Appendix B: Driver Configuration Options” on page 30.

Write-Back The write-enabled version of the Simba ODBC Driver with SQL Connector for Salesforce supports Data Manipulation Language (DML) statements such as INSERT, UPDATE, and DELETE. Write-back operations use the Salesforce Bulk API for loading and deleting data.

Binary data types are not supported for INSERT, UPDATE, and DELETE statements because the Salesforce Bulk API currently does not support binary data types.

Important: The read-only version of the driver does not support the use of DML statements. For information about obtaining a write-enabled version of the driver, please contact Simba Technologies Inc. through one of the options listed at http://www.simba.com/contact-us

www. s imba .com 27

Page 28: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Contact Us If you have difficulty using the driver, please contact our Technical Support staff. We welcome your questions, comments, and feature requests.

Technical Support is available Monday to Friday from 8 a.m. to 5 p.m. Pacific Time.

Important: To help us assist you, prior to contacting Technical Support please prepare a detailed summary of the client and server environment including operating system version, patch level, and configuration.

You can contact Technical Support via:

• E-mail: [email protected]

• Web site: www.simba.com

• Telephone: (604) 633-0008 Extension 3

• Fax: (604) 633-0004

You can also follow us on Twitter @SimbaTech

www. s imba .com 28

Page 29: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Appendix A: Salesforce Object Query Language For more information about the Salesforce Object Query Language (SOQL), refer to the SOQL Reference at: http://www.salesforce.com/us/developer/docs/soql_sosl/index.htm

Unsupported SOQL Features The following SOQL features are not supported by the driver:

• Typeof

• Offset

• With

• Aliases

Known Issues

Restrictions in queries may not be enforced during the prepare stage

A query may succeed during the prepare stage even if it violates one of the following:

• Restrictions on using ToLabel() in the filter clause.

• Restrictions on using fields in the HAVING clause.

• Restrictions on the operations that can be performed for specific data types. For example, ORDER BY is not supported for the following data types:

o Multi-select picklist

o Rich text area

o Long text area

o Encrypted

The query will fail when it is executed.

Query processing is not optimal when GROUP BY returns large result sets

Normally, when a result set exceeds 2000 rows, the driver will use the queryMore() call and a server-side cursor to retrieve additional rows in 200-row chunks. Doing so allows the query to be processed efficiently.

However, if the query contains a GROUP BY clause, then queryMore() cannot be used. In this case, you must change the filtering conditions to query data in smaller chunks.

www. s imba .com 29

Page 30: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Appendix B: Driver Configuration Options Table 4 lists the configuration options available in the Simba ODBC Driver with SQL Connector for Salesforce alphabetically by field or button label.

When configuring a connection from a Windows machine, the fields and buttons described in Table 4 are available in the Simba Salesforce Configuration dialog box and the Advanced Options dialog box.

When configuring a connection from a Linux or Mac OS X machine, use the key names provided in Table 4. All keys except for the EnableTransactions key are set in the odbc.ini file because they apply to specific DSNs. The EnableTransactions key is set in the .simba.salesforceodbc.ini file because it applies to the driver itself and affects all connections that use the driver.

Field or Button Label (Key Name)

Default Value Description

Enable report metadata optimization (MetadataLevel)

0 or FULL When this option is enabled (the key is set to 1 or LIGHT), the driver infers metadata based on a small sampling of data rather than all of the data. Important: Enabling this option allows the driver to run faster, but the metadata may be less accurate. When this option is disabled (the key is set to 0 or FULL), the driver infers metadata based on all of the data. (Optional)

Parse method (ParseMethod)

2 The query language that the driver uses to parse queries. Select one of the following settings, or set the key to one of the values in the parentheses:

• Attempt to parse queries as SOQL only (0 or SOQL_ONLY)

• Attempt to parse queries as SQL only (1 or SQL_ONLY)

• Attempt to parse queries as SOQL first, then SQL (2 or SOQL_FIRST)

• Attempt to parse queries in SQL first, then SOQL (3 or SQL_FIRST)

(Optional)

www. s imba .com 30

Page 31: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Field or Button Label (Key Name)

Default Value Description

Password (PWD)

None The password corresponding to the user name that you provided in the Username field (the UID key). In some cases, you may also be required to append a Salesforce security token to the end of your password. Note: For security reasons, passwords are not saved in the DSN. When you connect to your data, you will be prompted to type your password again. Providing your password in the DSN allows you to test your connection using the Test button in the Salesforce Configuration dialog box. (Optional)

Proxy host (ProxyHost)

None The host name or IP address of a proxy server that you want to connect to. (Optional)

Proxy password (ProxyPassword)

None The password corresponding to the user name that you provided in the Proxy username field (the ProxyUsername key). (Required if connecting to a proxy server)

Proxy port (ProxyPort)

None The port number that the proxy server uses for client connections. (Required if connecting to a proxy server)

Proxy username (ProxyUsername)

None The user name that you use to access the proxy server. (Required if connecting to a proxy server)

Sandbox URL (URL)

None The URL for connecting to a Salesforce sandbox. (Optional)

www. s imba .com 31

Page 32: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Field or Button Label (Key Name)

Default Value Description

Sanitize catalog names (SanitizeCatalogName)

0 When this option is enabled (1), the driver modifies catalog names by removing all invalid SQL-92 identifier characters and replacing all spaces with underscores. When this option is disabled (0), the driver does not modify catalog names. (Optional)

Strip catalog name (StripCatalogName)

0 When this option is enabled (1), the driver removes catalog names from the results of a SQLTables ODBC API function call. When this option is disabled (0), the driver does not remove the catalog names. Note: Some applications include catalog names in the TableName parameter, and the catalog names may need to be removed. (Optional)

Use Analytic API for executing reports (UseAnalyticAPI)

1 When this option is enabled (1), the driver executes reports using the Analytics API. When this option is disabled (0), the driver executes reports via URL. (Optional)

Use Salesforce labels for columns (UseLabel)

0 When this option is enabled (1), the driver uses the field names and labels from Salesforce as the names and labels in the returned data, respectively. When this option is disabled (0), the driver uses the field names from Salesforce as both the names and the labels in the returned data. Note: Some client applications require the name and label in the returned data to match. (Optional)

www. s imba .com 32

Page 33: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Field or Button Label (Key Name)

Default Value Description

Use SQL_NUMERIC for result set columns of type SQL_DOUBLE (UseWVarChar)

0 When this option is enabled (1), the driver returns result set columns as SQL_NUMERIC columns instead of SQL_DOUBLE columns. When this option is disabled (0), the driver returns result set columns as SQL_DOUBLE. Note: This option applies only to result set columns that the driver would normally return as SQL_DOUBLE columns. It does not convert all columns. (Optional)

Use SQL_WVARCHAR instead of SQL_VARCHAR (UseNumeric)

0 When this option is enabled (1), the driver returns data as SQL_WVARCHAR data instead of SQL_VARCHAR data. When this option is disabled (0), the driver returns data as SQL_VARCHAR data. (Optional)

Username (UID)

None The user name for your Salesforce account. Note: When you connect to your data, you will be prompted to provide your Salesforce account credentials. You are not required to save your user name in the DSN. (Optional)

N/A (Driver)

The default value varies depending on the version of the driver that is installed. For example, the value for the Windows driver is different from the value for the Mac OS X driver.

The absolute path of the Simba ODBC Driver with SQL Connector for Salesforce shared object file. (Required)

www. s imba .com 33

Page 34: Simba ODBC Driver with SQL Connector for …...Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide Redistribution and use in source and binary

Simba ODBC Driver with SQL Connector for Salesforce Installation and Configuration Guide

Field or Button Label (Key Name)

Default Value Description

N/A (EnableTransactions)

0 When this option is enabled (1), the driver simulates transactions for applications that require transaction support. The transactions will not be executed. Note: This key is set in the .simba.salesforceodbc.ini file instead of the odbc.ini file because the configuration option applies to the driver itself and affects all connections that use the driver. (Optional)

N/A (UIDDomain)

None The domain in your Salesforce user name. For example, if your Salesforce user name is [email protected], then you would set the UID key to myuser and set the UIDDomain key to myorganization.com Use this configuration option if your ODBC application does not allow the at sign (@) to be part of the user name. (Optional)

Table 4 Driver Configuration Options

www. s imba .com 34