README Progress(R) DataDirect(R) Progress DataDirect for ODBC for Salesforce Driver Windows Platforms (32 and 64-bit) 8.0.0 Release February 2022 *********************************************************************** Copyright (c) 2022 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved. *********************************************************************** This file contains instructions for installing the driver on Windows. This README file contains information for Progress(R) DataDirect Connect(R) Series for ODBC Salesforce Driver. CONTENTS Driver Requirements Installation Directory Changes Since 8.0.0 Release 8.0.0 Features Driver WorkAround Options Notes, Known Problems, and Restrictions Documentation Installed Files for 32-bit Drivers Installed Files for 64-bit Drivers Documentation Third-Party Acknowledgements Driver Requirements The driver requires a Java Virtual Machine (JVM) that is Java SE 8 or higher, including Oracle JDK, OpenJDK, and IBM SDK (Java) distributions. Installation Directory * The default installation directory for the 32-bit driver on a 64-bit system is: C:\Program Files (86)\Progress\DataDirect\ODBC * The default installation directory for all other installations is: C:\Program Files\Progress\DataDirect\ODBC Changes Since 8.0.0 Certifications -------------- * The driver has been certified with Salesforce API 51 Driver version 08.00.0186 (B0830, U0606, J001413) * The driver has been certified with Salesforce Service Cloud Driver version 08.00.0162 (B0766, U0531, J001251) * The driver has been certified with Salesforce API 49 Driver version 08.00.0142 (B0691, U0495) * Certified with Windows Server 2019 Driver version 08.00.0025 (B0406, U0277) Documentation ------------- Any product package made available after February 9, 2021 will not include the HTML help system or user's guide PDF. The full documentation set, including these items, is available from the Progress Information Hub: https://docs.progress.com/category/datadirect-salesforce While the product packages will not include these documentation items, the installation Help directory will provide an HTML redirect for direct access to the HTML help. Note that all Progress DataDirect for ODBC documentation has been migrated to the Progress Information Hub: https://docs.progress.com/ Enhancements ------------ * The curl library files that are installed with the product have been upgraded to version 7.80.0, which fixes a number of potential security vulnerabilities. For more information on the vulnerabilities resolved by this enhancement, refer to: https://curl.haxx.se/docs/vulnerabilities.html. This upgrade is available starting in build 08.02.0278 of the curl library files. * The default version of the OpenSSL library has been upgraded to version 1.1.1l, which fixes the following security vulnerabilities: - SM2 Decryption Buffer Overflow (CVE-2021-3711) - Read buffer overruns processing ASN.1 strings (CVE-2021-3712) This upgrade is available in build 08.02.0181 of the following OpenSSL library files: ivtls28.dll (32-bit) and ddtls28.dll (64-bit). Version 1.1.1l also addresses vulnerabilities resolved by earlier versions of the library. For more information on OpenSSL vulnerabilities resolved by this upgrade, refer to the corresponding OpenSSL announcements at: https://www.openssl.org/news/vulnerabilities-1.1.1.html * The curl library files that are installed with the product have been upgraded to version 7.75.0, which fixes a number of potential security vulnerabilities. For more information on the vulnerabilities resolved by this enhancement, refer to: https://curl.haxx.se/docs/vulnerabilities.html. This upgrade is available starting in build 08.02.0239 of the curl library files. * Note: OpenSSL library 1.1.1k has been replaced with version 1.1.1l. In addition to fixing multiple new vulnerabilities, version 1.1.1l also addresses the vulnerabilities resolved by version 1.1.1k. The default version of the OpenSSL library has been upgraded to version 1.1.1k, which fixes the following security vulnerabilities: - CA certificate check bypass with X509_V_FLAG_X509_STRICT (CVE-2021-3450) - NULL pointer deref in signature_algorithms processing (CVE-2021-3449) - Null pointer deref in X509_issuer_and_serial_hash() (CVE-2021-23841) - Integer overflow in CipherUpdate (CVE-2021-23840) This upgrade is available in build 08.02.0162 of the following OpenSSL library files: ivtls28.dll (32-bit) and ddtls28.dll (64-bit). * The driver has been enhanced to support the Salesforce Bulk API V2 for bulk load operations. This functionality can be enabled and configured using the new Bulk Load Version and Bulk Load Job Size connection options. * The driver has been enhanced to support the Apply ToLabel connection option. This option determines whether the driver applies the toLabel() function to the picklist fields when executing queries. * The drivers using base version B0649 and later have been enhanced to include timestamp in the internal packet logs by default. If you want to disable the timestamp logging in packet logs, set PacketLoggingOptions=1. The internal packet logging is not enabled by default. To enable it, set EnablePacketLogging=1. * The driver has been enhanced to support Apache CXF 3.3.4. * yes, no, on and off have been added as valid values for the connection options that accept boolean values. * The driver has been enhanced to support OAuth 2.0, which is an open protocol for token-based authentication. OAuth 2.0 allows you to authenticate without specifying a user ID or password, eliminating the risk of exposing them to unauthorized access. When you attempt to connect with the enhanced driver for the first time, either delete the existing native files or set the Create Map connection option to ForceNew. Changed Behavior ---------------- * The driver has been updated to require a Java Virtual Machine (JVM) that is Java SE 8 or higher, including Oracle JDK, OpenJDK, and IBM SDK (Java) distributions. Java SE 7 has reached the end of its product life cycle and will no longer receive generally available security updates. As a result, the drivers will no longer support JVMs that are version Java SE 7 or earlier. Support for distributed versions of Java SE 7 and earlier will also end, including IBM SDK (Java Edition). * The configuration options have been deprecated. However, the driver will continue to support them until the next major release of the driver when they will be added back as connection options. * The precision for the Integer data type has been changed from 10 to 9. * The NUM_PREC_RADIX value for the Double data type has been changed from 10 to 2. * The following Windows platforms have reached the end of their product lifecycle and are no longer supported by the driver: - Windows 8.0 (versions 8.1 and higher are still supported) - Windows Vista (all versions) - Windows XP (all versions) - Windows Server 2003 (all versions) Release 8.0.0 Features Platform Deprecation -------------------- The driver is not supported on Windows XP and Windows Server 2003 anymore. Bulk Fetch Support ------------------ The driver has been enhanced to support the Salesforce Bulk API, including primary key chunking, for bulk fetch operations. This functionality can be enabled and configured with the Bulk Fetch Threshold, Enable Bulk Fetch, Enable Primary Key Chunking, and Primary Key Chunk Size connection options. Support for Multiple Simultaneous Sessions ------------------------------------------ The driver has been enhanced to support multiple simultaneous sessions. This allows the driver to scale performance by distributing the workload across multiple sessions. The number of active sessions should not exceed the number permitted by your Salesforce account and can be limited by the setting of the new WSPoolSize connection option. New Refresh Map SQL Extension ----------------------------- REFRESH MAP discovers native objects that have been added to the native data store since connection or since the last refresh and maps the objects into your relational view of native data. It also incorporates any configuration changes made to your relational view by reloading the schema definition and associated files. SQL Engine Mode Auto Setting ---------------------------- The SQL Engine Mode connection option now supports Auto mode. When this setting is enabled, the driver automatically determines whether the SQL engine runs in server or direct mode based on availability. In addition, the default value for the SQL Engine Mode connection option on Windows has been updated to 0 (Auto). By default, the SQL engine attempts to run in server mode first; however, if server mode is unavailable, it runs in direct mode. Visual Studio Upgrade --------------------- The driver is now compiled using Visual Studio 2015 for improved security. JVM Version Requirements ------------------------ The Salesforce driver has been updated to require a JVM that is Java SE 7 or higher. This change has been implemented to remain compliant with Salesforce security standards. See "Driver Requirements" for more details on JVM. SQL Engine Upgrade ------------------ The driver's SQL engine has been upgraded. Consequently, there are some differences in how the 8.0 driver handles SQL queries compared to previous versions of the driver. For details, see the following resources: * https://documentation.progress.com/output/DataDirect/collateral/ odbc_salesforce_faq.pdf * https://documentation.progress.com/output/DataDirect/collateral/ odbc_salesforce_sqlengine.pdf Performance Issues When Executing Queries ----------------------------------------- The 8.0 driver pushes queries to Salesforce whenever possible. Queries that cannot be pushed to Salesforce with the 8.0 driver may be slower than comparable queries made with earlier versions of the driver because data may be paged to disk while completing an operation. If you experience slow performance, please contact Technical Support. Our team will quickly address any performance issues you encounter. Evaluation Bulk Load Support ---------------------------- Bulk load operations are no longer restricted to 10,000 rows for evaluation installations of the driver. Mapping of the Currency and Percentage Data Types ------------------------------------------------- The native CURRENCY and PERCENTAGE data types now map to the DECIMAL JDBC data type. In earlier releases, these data types mapped to the DOUBLE data type. The Database Connection Option Replaced by Schema Map ----------------------------------------------------- The Database connection option has been replaced by the new Schema Map option. Similar to Database, Schema Map is used to specify the name and location of the configuration file where the relational map of native data is written; however, the value specified must now be an absolute path. In addition to this change, the default behavior differs between these options. The Database attribute will continue to be supported for this release, but it will be deprecated in subsequent versions of the product. Create Database Connection Option Replaced by Create Map -------------------------------------------------------- The Create Database connection option has been replaced by the new Create Map option. The CreateDB attribute will continue to be supported for this release, but it will be deprecated in subsequent versions of the product. Logon Domain Connection Option Deprecated ----------------------------------------- The Logon Domain connection option has been deprecated. As a result, the User Name option has been updated to accept the user name and domain. Refresh Dirty Cache Connection Option Deprecated ------------------------------------------------ The Refresh Dirty Cache option has been deprecated. Now, for every fetch operation, the driver refreshes the cached object to pick up changes made to tables and rows. Server DB Directory Connection Option Deprecated ------------------------------------------------ The Server DB Directory connection option has been deprecated. To specify the location of database files, use the Schema Map connection option. Default for the Server Port Number Connection Option ---------------------------------------------------- The default value for the Server Port Number connection option has been updated: * For the 32-bit driver, the default is 19938. * For the 64-bit driver, the default is 19937. Default for the JVM Arguments Connection Option ----------------------------------------------- The default value for the JVM Arguments connection option has been updated: * For the 32-bit driver when the SQL Engine Mode connection option is set to 2 (Direct): -Xmx256m * For all other configurations: -Xmx1024m Default Value for the Enable Bulk Load Connection Option -------------------------------------------------------- The default value of the Enable Bulk Load connection option has been updated to true (enabled). By default, the bulk load protocol can be used for inserts, updates, and deletes based on the Bulk Load Threshold options. Default Value for the Statement Call Limit Connection Option ------------------------------------------------------------ The default value for the Statement Call Limit connection option has been updated to 100. By default, the driver can make a maximum of 100 Web service calls when executing any single SQL statement or metadata query. Default Vaule for the AuditColumns Config Option ------------------------------------------------ The default value for the AuditColumns config option has been updated to All (AuditColumns=All). By default, the driver includes the all of the audit columns and the master record id column in its table definitions. Default Relational Mapping of Custom Objects -------------------------------------------- The default value for the CustomSuffix config option has been updated to Include (CustomSuffix=Include). By default, the driver includes the "__c" suffix table and column names when mapping the remote data model to the relational data model. Default Value for the MapSystemColumnNames ------------------------------------------ The default value for the MapSystemColumnNames config option has been updated to 0 (MapSystemColumnNames=0). By default, the driver does not change the names of the Salesforce system columns when mapping them to the relational model. Short Attribute for the Config Options Connection Option -------------------------------------------------------- The short attribute name for the Config Options connection option has changed from CO to CFGO. Deprecated Support for the Security Tab --------------------------------------- The Security tab has been removed from the setup dialog. As a result: * The Logon Domain connection option has been deprecated. * The Security Token connection option has been moved to the General tab. * The User Name connection option has been moved to the General tab. For more information about these features, refer to THE PROGRESS DATADIRECT FOR ODBC FOR SALESFORCE DRIVER USER'S GUIDE AND REFERENCE. Driver WorkAround Options Progress DataDirect has included non-standard connection options (workarounds) for the driver that enable you to take full advantage of packaged ODBC-enabled applications requiring non-standard or extended behavior. Refer to the chapter "WorkAround options" in THE PROGRESS DATADIRECT FOR ODBC DRIVERS REFERENCE for a description of these options. Notes, Known Problems, and Restrictions The following are notes, known problems, or restrictions with Release 8.0.0 of the Progress DataDirect for ODBC for Salesforce driver. Specifying values for the same connection option multiple times --------------------------------------------------------------- The driver does not support specifying values for the same connection option multiple times in a connection string or DSN. If a value is specified using the same attribute multiple times or using both long and short attributes, the connection may fail or the driver may not behave as intended. Using the INSERT INTO SELECT Statement with Bulk API V2 ------------------------------------------------------- When Salesforce Bulk API version is set to V2, the driver does not support INSERT INTO SELECT statements and an exception is thrown. For example: Insert into TestTable(COL_1,COL_2,COL_3) select COL_1,COL_2,COL_3 from TempTable Installer Behavior Changes -------------------------- * The installer now installs the following JDKs on the respective platforms: * Windows (x32 and x64): OpenJDK 11 * Linux (x64): OpenJDK 11 * Linux (x32): Oracle JDK 8 Note: For all the platforms, except those mentioned in the above list, the installer will not install any JDK. The client machine is required to have Oracle JDK 8 or higher to run the installer. * The new version of the installer installs OpenJDK 11 or Oracle JDK 8, and the old version of the installer installs Oracle JDK 7. As there is a difference between the JDK versions installed by the new and the old installers, they are not allowed/supported to overwrite or augment installations done by each other. * Installing different versions of the driver in the same directory is not supported. Important Java Requirement Changes for Salesforce Security Updates ------------------------------------------------------------------ The Salesforce driver has been updated to require a JVM that is Java SE 7 or higher. This change is being implemented to comply with recent revisions to Salesforce security standards. See "Driver Requirements" for more details on JVM. In keeping with best security practices, Salesforce will begin deprecating support for the TLS 1.0 encryption protocol within inbound and outbound connections beginning June 25th, 2016. TLS 1.0 will initially be disabled in Sandbox instances, before being retired for all services in early 2017. To maintain compatibility with services after TLS 1.0 is disabled, the driver must employ a JVM that allows TLS 1.0 to be disabled independently from other encryption protocols--functionality that was first introduced in Java SE 7. By default, the driver uses the Java SE 7 version of the JVM that is installed with the driver. If you designate a JVM that is Java SE 6 or earlier, the driver will return an error when attempting to establish a connection. To correct this issue, set the library path environment variable to the location of a supported JVM. For more information on changes to the Salesforce security policy, refer to https://help.salesforce.com/apex/HTViewSolution?id=000221207#Whatischange. Stored Procedures with Database.com ------------------------------------ Stored procedures are not supported when connected to database.com using the Salesforce driver. However, the Salesforce driver incorrectly returns a response to SQLGetInfo(..., SQL_PROCEDURES, ...) to indicate that stored procedures are supported when connected to database.com. SELECT...INTO Statement ----------------------- The SELECT...INTO statement is supported for local tables only. The source and destination tables must both be local tables. Creating remote tables in Salesforce or loading from remote Salesforce tables using SELECT...INTO is not supported. Additionally, the option to create the destination table as a temporary table does not currently work. 126 Error When Modifying Data Sources on Windows 10 --------------------------------------------------- You may receive a 126 error when adding or configuring a data source stored on a network location. This is caused by the settings of the User Account Control (UAC) security feature on Windows 10. To work around this issue: Important: Implementing this fix disables security safeguards that are designed to protect your machine. Before starting, refer to the following Microsoft documentation for potential risks associated with disabling the UAC feature: http://windows.microsoft.com/en-us/ windows/what-are-user-account-control-settings 1. From the Start menu, type regedit in the search field; then, select regedit from the results list. The Registry Editor window opens. 2. Navigate to the following registry subkey: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System 3. Right click on the subkey; then, select New > DWORD Value. 4. Rename the new value EnableLinkedConnections. 5. Right-click EnableLinkedConnections, and then click Modify. The Edit DWORD Value window opens. 6. In the Value data field, type 1. Click OK. 7. Close the Registry Editor; then, restart your computer. For SSL Users ------------- When trying to connect to a database using SSL encryption, you may receive an error message similar to: "PRNG not seeded". This is because certain versions of some operating systems do not generate truly random numbers necessary for encryption. For more information about this error and available patches, please refer to the Web site: http://www.openssl.org/support/faq.html#USER1 SQLColAttribute(s) ------------------ The column attributes 1001 and 1002, which were assigned as DataDirect- specific attributes, were inadvertently used as system attributes by the Microsoft 3.0 ODBC implementation. Applications using those attributes must now use 1901 and 1902, respectively. SQL_C_NUMERIC ------------- Because of inconsistencies in the ODBC specification, users attempting to use SQL_C_NUMERIC parameters must set the precision and scale values of the corresponding structure and the descriptor fields in the Application Parameter Descriptor. For Developers Using IIS ------------------------ One of the most common connectivity issues encountered while using IIS (Microsoft's Internet Information Server) concerns the use and settings of the account permissions. If you encounter problems using DataDirect drivers with an IIS server, refer to KnowledgeBase document number 4274 on the Progress DataDirect web site: http://knowledgebase.datadirect.com. Documentation PROGRESS DATADIRECT FOR ODBC FOR SALESFORCE DOCUMENTATION SET ------------------------------------------------------------- The driver documentation set is available from the Progress Information Hub: https://docs.progress.com/category/datadirect-salesforce You can access the online help system directly via the HTML redirect in the installation Help directory. Installed Files the 32-bit Driver This file list assumes a full installation of the driver and documentation. The installer copies the following file to the Windows system directory: ivtrc28.dll DataDirect trace library The installer copies the following files and subdirectories to the product installation directory, by default: For 32-bit drivers on 64-bit machines: C:\Program Files (x86)\Progress\DataDirect\ODBC\: For all other installations: C:\Program Files\Progress\DataDirect\ODBC\: fixes.txt List of fixes since last release license.txt Progress DataDirect license agreement \drivers: ivicu28.dll Unicode conversion tables ivsfrc28.dll Salesforce driver ivsfrc28r.dll resource file ivsfrc28s.dll DataDirect Salesforce driver setup library IVODBC.LIC DataDirect License File ivssl28.dll TLS/SSL support file (OpenSSL library version 1.0.2u) ivtls28.dll TLS/SSL support file (OpenSSL library version 1.1.1l) ivtrc28.dll DataDirect trace library qesqlext.h Header file for DataDirect-specific ODBC Definitions \OpenSSL\1.0.2d: ivssl28 SSL support file (OpenSSL library file, version 1.0.2d) \OpenSSL\Latest: ivssl28 SSL support file (OpenSSL library file, version 1.0.2u) \help: *.html HTML redirects to online connector help systems and documentation resources \java\lib: *.* Files associated with the Salesforce driver sforce.jar Java components for the Salesforce driver \JRE: *.* Files associated with the Salesforce driver \NOTICES: ODBC for Salesforce v8.0 notices.txt Third-party vendor license agreements \READMES: ODBC for Salesforce v8.0 readme.txt This file \samples: \bulk\bulk.c Bulk example source \bulk\bulk.exe Bulk application \bulk\bulk.mak Bulk example make file \bulk\bulk.sln Bulk example solution file \bulk\bulk.vcproj Bulk example project file \bulk\ddlogging.properties Log configuration file for the Salesforce WP driver \bulkstrm\bulk.cpp Bulk streaming example source \bulkstrm\bulk.hpp Bulk streaming example header \bulkstrm\bulk.rc Bulk streaming example resource file \bulkstrm\bulkstreaming.sln Bulk streaming example solution file \bulkstrm\bulkstreaming.vcproj Bulk streaming example project file \bulkstrm\bulkstrm.exe Bulk streaming example application \bulkstrm\bulkstrm.txt Bulk streaming description \bulkstrm\ddlogging.properties Log configuration file for the Salesforce driver \bulkstrm\msgprintf.hpp Bulk streaming example header file \bulkstrm\ProgressDataDirect.bmp \bulkstrm\ProgressDataDirect.ico \bulkstrm\winmain.cpp Bulk streaming example source file \example\ddlogging.properties Log configuration file for the Salesforce driver \example\example.c Example source \example\Example.exe Example application \example\example.h Example header \example\Example.mak Example make file \example\Example.sln Example solution file \example\Example.vcproj Example project file \example\example.txt Example description \tools: ddextwin.exe License Extender utility ddprocinfo.exe Processor Information utility DSNConverterSIL.exe Data Source Converter utility salesforceserver32.exe The Salesforce SQL Server Engine XMLP.exe A GUI demo tool that persists a result set to an XML data file \tools\Tableau: DataDirect Salesforce.tdc Tableau data source file \uninstall\*.* Files used to uninstall the product Installed Files for the 64-bit Driver This file list assumes a full installation of the driver and documentation. The installer copies the following file to the Windows system directory: ddtrc28.dll DataDirect trace library The installer copies the following files and subdirectories to the product installation directory, by default: C:\Program Files\Progress\DataDirect\ODBC\: fixes.txt List of fixes since last release license.txt Progress DataDirect license agreement \drivers: ddicu28.dll Unicode conversion tables ddsfrc28.dll Salesforce driver ddsfrc28r.dll resource file ddsfrc28s.dll DDODBC.LIC DataDirect License File ddssl28.dll TLS/SSL support file (OpenSSL library version 1.0.2u) ddtls28.dll TLS/SSL support file (OpenSSL library version 1.1.1l) ddtrc28.dll DataDirect trace library qesqlext.h Header file for DataDirect-specific ODBC Definitions \OpenSSL\1.0.2d: ddssl28.dll SSL support file (OpenSSL library file, version 1.0.2d) \OpenSSL\Latest: ddssl28.dll SSL support file (OpenSSL library file, version 1.0.2u) \help: *.html HTML redirects to online connector help systems and documentation resources \java\lib: *.* Files associated with the Salesforce driver sforce.jar Java components for the Salesforce driver \JRE: *.* Files associated with the Salesforce driver \NOTICES: ODBC for Salesforce v8.0 notices.txt Third-party vendor license agreements \READMES: ODBC for Salesforce v8.0 readme.txt This file \samples: \bulk\bulk.c Bulk example source \bulk\bulk.exe Bulk application \bulk\bulk.mak Bulk example make file \bulk\bulk.sln Bulk example solution file \bulk\bulk.vcproj Bulk example project file \bulk\ddlogging.properties Log configuration file for the Salesforce WP driver \bulkstrm\bulk.cpp Bulk streaming example source \bulkstrm\bulk.hpp Bulk streaming example header \bulkstrm\bulk.rc Bulk streaming example resource file \bulkstrm\bulkstreaming.sln Bulk streaming example solution file \bulkstrm\bulkstreaming.vcproj Bulk streaming example project file \bulkstrm\bulkstrm.exe Bulk streaming example application \bulkstrm\bulkstrm.txt Bulk streaming description \bulkstrm\ddlogging.properties Log configuration file for the Salesforce driver \bulkstrm\msgprintf.hpp Bulk streaming example header file \bulkstrm\ProgressDataDirect.bmp \bulkstrm\ProgressDataDirect.ico \bulkstrm\winmain.cpp Bulk streaming example source file \example\ddlogging.properties Log configuration file for the Salesforce driver \example\example.c Example source \example\Example.exe Example application \example\example.h Example header \example\Example.mak Example make file \example\Example.sln Example solution file \example\Example.vcproj Example project file \example\example.txt Example description \tools: ddextwin.exe License Extender utility ddprocinfo.exe Processor Information utility DSNConverterSIL.exe Data Source Converter utility salesforceserver64.exe The Salesforce SQL Server Engine XMLP.exe A GUI demo tool that persists a result set to an XML data file \tools\Tableau: DataDirect Salesforce.tdc Tableau data source file \uninstall\*.* Files used to uninstall the product ~~~~~~~~~~~~~~~~~~ February 2022 End of README