README
     Progress(R) DataDirect(R) 
     Progress(R) DataDirect(R) for JDBC(TM) for Salesforce(TM) Driver
     Release 6.0.0
     March 2019


***********************************************************************
Copyright (C) 1994-2019 Progress Software Corporation and/or its 
subsidiaries or affiliates. All Rights Reserved. 

***********************************************************************


CONTENTS

Requirements
Installation Directory
Progress DataDirect for JDBC for Salesforce Driver
Changes since 6.0.0
Release 6.0.0 Features
Notes, Known Problems, and Restrictions
Documentation
Installed Files


     Requirements

Java SE 7 or higher must be installed and the JVM must be defined on your system
path.


     Installation Directory

The default installation directory for the driver is:

* Windows:
  C:\Program Files\Progress\DataDirect\JDBC_60

* UNIX/Linux:
  /opt/Progress/DataDirect/JDBC_60
  Note: For UNIX/Linux, if you do not have access to "/opt", your user's home
  directory will take the place of this directory.


    Progress DataDirect for JDBC for Salesforce Driver

The driver supports standard SQL query language to select, insert, update, and
delete data from Salesforce.com and other Web service data stores that use the
Salesforce API such as Force.com, Database.com, and Veeva CRM. To support SQL
access to Salesforce, the driver creates a map of the Salesforce data model and
translates SQL statements provided by the application to Salesforce queries
(SOQL) and Web service calls. In addition, the driver supports multiple
simultaneous sessions.

* The driver supports the Salesforce API.

* The driver supports all JDBC Core functions.

* The driver supports the core SQL-92 grammar.

* The driver supports a client-side data cache.

* The driver supports proxy server connectivity.


    Changes since 6.0.0
	
Certifications
--------------
* The driver has been certified with Oracle JDK 11
  Driver version 6.0.0.000140 (C0158.F000174.U000090)

* The driver has been certified with OpenJDK 11.
  Driver version 6.0.0.000140 (C0158.F000174.U000090)

* The driver has been certified with OpenJDK 8 on Windows and Linux.
  Driver version 6.0.0.000140 (C0158.F000174.U000090)	

Enhancement
-----------
The driver has been enhaced 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.
	
	
	Release 6.0.0 Features

Data Source Class
-----------------
The data source class com.ddtek.jdbcx.sforce.SForceDataSource40 has been
deprecated. The data source class com.ddtek.jdbcx.sforce.SForceDataSource
should be used for data source connections. The data source class
com.ddtek.jdbcx.sforce.SForceDataSource now supports all JDBC specifications.

Bulk Fetch
----------
The driver has been enhanced to support the Salesforce Bulk API, including PK
chunking, for bulk fetch operations. This functionality can be enabled and
configured with the EnableBulkFetch, BulkFetchThreshold, EnablePKChunking, and
PKChunkSize connection properties.

Multiple Simultaneous Sessions
------------------------------
The driver has been enhanced to support multiple simultaneous 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 WSPoolSize
connection property.

WSPoolSize Connection Property
------------------------------
The new WSPoolSize connection property allows you to specify the maximum number
of sessions the driver uses. This allows the driver to have multiple Web service
requests active simultaneously when multiple JDBC connections are open, thereby
improving throughput and performance.

DatabaseName and SchemaMap Connection Properties
------------------------------------------------
The DatabaseName property has been deprecated. The SchemaMap property should now
be used to specify the fully qualified path of the configuration file where the
map of the Salesforce data model is written.

CreateDB, RefreshSchema, and CreateMap Connection Properties
------------------------------------------------------------
The CreateDB and RefreshSchema properties have been deprecated. The CreateMap
property should now be used to specify whether the driver creates a new schema
map when establishing the connection.

EnableBulkLoad Connection Property
----------------------------------
The default value of the EnableBulkLoad connection property has been updated to
true. By default, the Salesforce Bulk API can be used for inserts, updates, 
and deletes based on the BulkLoadThreshold property.

StmtCallLimit Connection Property
---------------------------------
The default value for the StmtCallLimit connection property 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.

RefreshDirtyCache Connection Property
-------------------------------------
The RefreshDirtyCache property has been deprecated. Now, for every fetch
operation, the driver refreshes the cached object to pick up changes made to
tables and rows.

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. 

AuditColumns Configuration Option
---------------------------------
The default value for the AuditColumns configuration option has been updated to
all (AuditColumns=all). By default, the driver includes all of the audit columns
and the master record id column in its table definitions.

CustomSuffix Configuration Option
---------------------------------
The default value for the CustomSuffix configuration option has been updated to
include (CustomSuffix=include). By default, the driver includes the "__c" suffix
table and column names when mapping the Salesforce data model.

MapSystemColumnName Configuration Option
----------------------------------------
The default value for the MapSystemColumnName configuration option has been
updated to 0 (MapSystemColumnNames=0). By default, the driver does not change
the names of the Salesforce system columns when mapping the Salesforce data
model.

Refresh Map SQL Extension
-------------------------
The REFRESH MAP command has been added to the driver. 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 map and associated files. REFRESH MAP
is an expensive query since it involves the discovery of native data.

Bulk Load Licensing
-------------------
Bulk load operations are no longer restricted to 10,000 rows for evaluation
installations of the driver.


	Notes, Known Problems, and Restrictions

The following are notes, known problems, and restrictions with Release 6.0.0 of
the driver.

API Consumption with Correlated Subqueries
------------------------------------------
For executing correlated subqueries, the current version of the driver requires 
more API calls than those that were required by the previous version.

If the total number of API calls required to complete the execution of a 
correlated subquery is more than the StmtCallLimit set for the connection, 
the driver returns the following error:

"Query Aborted! This query involves correlated subquery. Its execution might
take more than  API calls, which is higher than stmtcalllimit for this 
connection. Please set the stmtcallLimit to more than  to execute this
query."

This will prevent you from exhausting the Salesforce daily API call limit. 
If you are comfortable with the query taking large number of API calls and want
the execution of the correlated subquery to complete, you can increase the 
StmtCallLimit value and retry.

Compatibility Guidance
----------------------
In addition to the information in this readme, refer to the following
compatibility FAQ for guidance on upgrading from the Progress DataDirect for
JDBC for Salesforce 5.1 driver to 6.0 driver:
https://documentation.progress.com/output/DataDirect/collateral/
jdbc_salesforce_faq.pdf

SQL Engine Upgrade
------------------
The driver's SQL engine has been upgraded. Consequently, there are some
differences in how the 6.0 driver handles SQL queries compared to previous
versions of the driver. For details, see the following resources:

* "Supported SQL Statements and Extensions" in the user's guide

* https://documentation.progress.com/output/DataDirect/collateral/
  jdbc_sqlengine_salesforce.pdf

Executing SQL Queries
---------------------
The 6.0 driver pushes SQL queries to Salesforce whenever possible. Queries
that cannot be pushed down may be slower than comparable queries made with
previous versions of the driver because data may be paged to disk while
completing an operation. If you experience slow performance, please contact
Technical Support: https://www.progress.com/support-and-services. Our team will
quickly address any performance issues you encounter.

Foreign key columns
-------------------
In the 6.0 version of the driver, foreign key columns are not shown as indexes.
However, in previous versions of the driver, foreign key columns are shown as
non-unique indexes.

Using the 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.

Stored Procedures Not Supported for Database.com
------------------------------------------------
The driver incorrectly reports that it supports stored procedures for
Database.com (for example, using DatabaseMetadata.supportsStoredProcedures()).
Stored procedures for Database.com are not supported.

JTA Support
-----------
JDBC distributed transactions through JTA are not supported.

System.exit() method and Process Termination
--------------------------------------------
The System.exit() method ensures that all registered shutdown hooks are run.
Applications terminate faster when System.exit(0) is used. When applications
omit the System.exit() call, the termination process may linger for about 10
seconds before exiting.

oplog.rs system table
---------------------
The driver hides the oplog.rs system table.

Executing DataDirect Shell Script
---------------------------------
For UNIX/Linux users: If you receive an error message when executing any
DataDirect for JDBC shell script, make sure that the file has EXECUTE
permission. To do this, use the chmod command. For example, to grant EXECUTE
permission to the testforjdbc.sh file, change to the directory containing
testforjdbc.sh and enter: chmod +x testforjdbc.sh

JDBC Methods
------------
The following notes on JDBC methods apply generally to Progress DataDirect for
JDBC drivers. Additional information on driver support for the JDBC API can be
found in the "JDBC Support" section of the product user's guide.

* When attempting to create an updatable, scroll-sensitive result set for a
  query that contains an expression as one of the columns, the driver cannot
  satisfy the scroll-sensitive request. The driver downgrades the type of the
  result returned to scroll-insensitive.

* The ResultSet methods getTimestamp(), getDate(), and getTime() return
  references to mutable objects. If the object reference returned from any of
  these methods is modified, re-fetching the column using the same method
  returns the modified value. The value is only modified in memory; the
  database value is not modified.

Uninstalling on Windows
-----------------------
When you connect with the Salesforce driver, the driver creates multiple local
Salesforce files in the \testforjdbc subdirectory, where
 is your product installation directory. If you connect using the
default Salesforce driver URL jdbc:datadirect:sforce://login.salesforce.com,
the names of these files are associated with your user name. For example, if
your user name is test01@xyz.com, the local Salesforce files that are created 
would be:

\testforjdbc\ddsforce.log
\testforjdbc\test01.app.log
\testforjdbc\test01.config
\testforjdbc\test01.log
\testforjdbc\test01.properties
\testforjdbc\test01.SFORCE.map
\testforjdbc\test01.SFORCE.native
  
When you run the Windows uninstaller, these files are not removed. You can
explicitly delete them.

  
     Documentation	 	 

PROGRESS DATADIRECT FOR JDBC FOR SALESFORCE DRIVER USER'S GUIDE
---------------------------------------------------------------
The user's guide is available as an HTML help system and as a PDF.

* The HTML help system and PDF are installed in the SalesforceHelp subdirectory
  of your product installation directory.

* The HTML help system and the PDF are also available on this Progress
  DataDirect documentation web page:
  https://www.progress.com/documentation/datadirect-connectors


     Installed Files

When you extract the contents of the installation download package to your
installer directory, you will notice the following files that are required to
install the driver:

*  Windows:
   - PROGRESS_DATADIRECT_JDBC_INSTALL.exe
   - PROGRESS_DATADIRECT_JDBC_SALESFORCE_6.0.0_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_COMMON_6.0.0_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_DOCUMENTATION_6.0.0_INSTALL.iam.zip

*  Non-Windows:
   - PROGRESS_DATADIRECT_JDBC_INSTALL.jar
   - PROGRESS_DATADIRECT_JDBC_SALESFORCE_6.0.0_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_COMMON_6.0.0_INSTALL.iam.zip
   - PROGRESS_DATADIRECT_JDBC_DOCUMENTATION_6.0.0_INSTALL.iam.zip

When you install the driver, the installer creates the following directories and
files in the product installation directory in the default installation
directory or in an installation directory you specify, represented by
INSTALL_DIR.


INSTALL_DIR/:
-------------
LicenseTool.jar            Product license file manager

ddprocinfo.exe             Windows executable to start the Processor Information
                           Utility

ddprocinfo                 UNIX/Linux script to start the Processor Information
                           Utility


INSTALL_DIR/Examples/Bulk/:
---------------------------
Load From File/bulkLoadFileDemo.java
                           Java source example for bulk loading from a CSV file

Load From File/load.txt    Sample data for the example

Streaming/bulkLoadStreamingDemo.java
                           Java source example for bulk loading from a result
                           set

Threaded Streaming/bulkLoadThreadedStreamingDemo.java
                           Java source example for multi-threaded bulk loading
                           from a result set

Threaded Streaming/README.txt
                           Instructions on how to use the thread.properties file

Threaded Streaming/thread.properties
                           Properties file for the example


INSTALL_DIR/Examples/Connector/:
--------------------------------
ConnectorSample.ear        J2EE Application Enterprise Archive file containing
                           the ConnectorSample application 

connectorsample.htm        USING DATADIRECT CONNECT FOR JDBC RESOURCE ADAPTERS
                           document

graphics/*.*               Images referenced by the USING DATADIRECT CONNECT FOR
                           JDBC RESOURCE ADAPTERS document

src/ConnectorSample.jsp    Source for the JavaServer Page used to access the
                           ConnectorSample application

src/connectorsample/ConnectorSample.java     
                           Java source file defining the remote interface for
                           the ConnectorSample EJB

src/connectorsample/ConnectorSampleBean.java  
                           Java source file defining the home interface for the
                           ConnectorSample EJB

src/connectorsample/ConnectorSampleHome.java  
                           Java source file containing the implementation for
                           the ConnectorSample EJB


INSTALL_DIR/Examples/JNDI/:
---------------------------
JNDI_FILESYSTEM_Example.java
                           Example Java(TM) source file

JNDI_LDAP_Example.java     Example Java source file


INSTALL_DIR/Examples/SforceSamples/:
------------------------------------
buildsamples.bat           Batch file to build the Salesforce example

buildsamples.sh            Shell script to build the Salesforce example
 
ddlogging.properties       Logging properties file

runsalesforceconnectsample.bat
                           Batch file to run the Salesforce example

runsalesforceconnectsample.sh
                           Shell script to run the Salesforce example

bin/com/ddtek/jdbc/samples/SalesforceConnectSample.class
                           Java example class

bin/com/ddtek/jdbc/samples/SampleException.class
                           Java example class

src/com/ddtek/jdbc/samples/SalesforceConnectSample.java
                           Java source example


INSTALL_DIR/Help/: 
------------------
SalesforceHelp/index.html  Driver HTML help system entry file

SalesforceHelp/*           Support files and folders for the driver help system


INSTALL_DIR/install/: 
---------------------
.psc_dd_inst_reg.xml       Support file for the installation logs

logs/*.*                   Log file generated upon installation


INSTALL_DIR/jre/:
-----------------
*.*                        Files associated with the Salesforce driver


INSTALL_DIR/lib/:
-----------------
sforce.jar                 Salesforce Driver and DataSource classes


INSTALL_DIR/NOTICES/:
---------------------
JDBC for Salesforce v6.0 notices.txt
                           Third party agreement information


INSTALL_DIR/pool manager/:
--------------------------
pool.jar                   All DataDirect Connection Pool Manager classes


INSTALL_DIR/READMES/:
---------------------
JDBC for Salesforce v6.0 readme.txt
                           This file


INSTALL_DIR/testforjdbc/:
-------------------------
Config.txt                 Configuration file for DataDirect Test

ddlogging.properties       Logging properties file

testforjdbc.bat            Batch file to start DataDirect Test

testforjdbc.sh             Shell script to start DataDirect Test

lib/testforjdbc.jar        DataDirect Test classes


INSTALL_DIR/uninstall/:
-----------------------
.com.zerog.registry.xml    Support file for the uninstaller

.psc_dd_uninst_reg.xml     Support file for the uninstaller

InstallScript.iap_xml      Support file for the uninstaller

installvariables.properties
                           Support file for the Windows uninstaller

Uninstall_JDBC_60.exe      Windows uninstaller

Uninstall_JDBC_60.lax      Support file for the Windows uninstaller

uninstaller.jar            Java uninstaller

resource/*.*               Resource files for the Windows uninstaller


March 2019
============
End of README