Oracle Service Cloud JDBC 5.1.4

     README
     Progress(R) DataDirect(R) 
     Progress(R) DataDirect(R) for JDBC(TM) for Oracle Service Cloud(TM) Driver
     Release 5.1.4
     February 2026


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

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


CONTENTS

Post-GA Product Announcements
Requirements
Installation Directory
Data Source and Platform Support 
Changes since Service Pack 4
Changes for Service Pack 4
Features
Notes, Known Problems, and Restrictions
Documentation
Installed Files


     Post-GA Product Announcements
The readme files will no longer be updated with product announcements and new 
features after the General Availability (GA) of the product. For the latest 
updates and enhancements, please refer to the release notes 
(https://www.progress.com/datadirect-connectors/whats-new).


     Requirements

* A supported Java Virtual Machine (JVM) must be defined on your system path.

* The installer program requires a JVM that is Java SE 11 or higher, including
  Oracle JDK, OpenJDK, and IBM SDK (Java) distributions.
  
* The driver requires a 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 driver is:

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

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


    Data Source and Platform Support

For the latest data source and platform support information, refer to the 
Product Compatibility Guide: 
https://docs.progress.com/bundle/datadirect-product-compatibility/resource/
datadirect-product-compatibility.pdf  


    Changes since Service Pack 4

SpyAttributes connection property update
----------------------------------------
The connection property SpyAttributes has been updated to exclude the attribute 
load=classname, which was previously used to load the driver specified by the 
given class name. If a log file name does not include the .log extension, the 
driver automatically appends it.

Changes to getURL() Behavior 
----------------------------
The driver has been updated to remove all sensitive values from the string
returned by calling getURL(). You might be impacted if your applications or
tests expect these values when calling the function.

Installer JRE Requirement
-------------------------
The installer program now requires you to install a JRE that is Java SE 11 or
higher before running the installer. In earlier versions, the JRE used by the
installer program was included in the product. However, to avoid potential
security vulnerabilities, the installer program no longer includes a JRE.
Instead, the installer program uses the JRE in your environment to allow for
the most secure version of a JRE to be used.
 
Note: This change does not affect the JVM requirements for the driver. For the latest 
driver requirements, refer to the Product Compatibility Guide:
https://docs.progress.com/bundle/datadirect-product-compatibility/resource/
datadirect-product-compatibility.pdf

Installer Upgrade
-----------------
The installer program has been enhanced to use a more modern and
secure technology. As a result of this enhancement: 

* The default installation location has been changed to:

  - For Windows:
    C:\Program Files\Progress\DataDirect\JDBC

  - For UNIX/Linux:
    /opt/Progress/DataDirect/JDBC

* The new installer program does not support upgrading installations 
  made with earlier versions of the installer. You will need to 
  uninstall the existing installation and reinstall with the new 
  installer to resume upgrades in the same directory. 

* The references to the old installation location will not be
  changed to the new installation location automatically. To 
  learn how to update them, refer to the best practices article 
  at https://community.progress.com/s/.

* License keys you have used for the retired 5.1 installer cannot 
  be used with the new installer. Request new keys by either 
  contacting the Progress DataDirect Technical Support team or visiting
  https://www.progress.com/datadirect-connectors/request-upgrade.

CVE-2022-41853 - Use of Externally-Controlled Input to Select Classes or Code
('Unsafe Reflection')
-----------------------------------------------------------------------------
Several Progress DataDirect JDBC drivers  utilized a version of HyperSQL
Database that was vulnerable to remote code execution described in
CVE-2022-41853. All impacted drivers have been patched to fix this
vulnerability. For details on impacted drivers and fixed versions, refer to
the following KB article:
https://community.progress.com/s/article/DataDirect-JDBC-Critical-Security-
Bulletin-November-2022-CVE-2022-41853

Signed Installer Packages
-------------------------
Starting June 20, 2022, installer packages signed with a digital signature 
will be available for download from OEM FTP. For instructions on verifying 
installer package signatures, refer to 
https://community.progress.com/s/article/Signed-packages-for-DataDirect-OEMs.

Documentation
-------------
Any product package made available after August 7, 2020 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-oracle-service-cloud

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 JDBC documentation has been migrated to
the Progress Information Hub:
https://docs.progress.com/

Timestamp Logging in Spy and JDBC Packet Logs
---------------------------------------------
The driver has been enhanced to include timestamp in the Spy and JDBC packet
logs by default. If required, you can disable the timestamp logging by 
specifying the following at connection: For Spy logs, set 
spyAttributes=(log=(file)Spy.log;timestamp=no) and for JDBC packet logs,
set ddtdbg.ProtocolTraceShowTime=false.

Interactive SQL for JDBC
------------------------
Interactive SQL for JDBC (JDBCISQL) is now installed with the product. 
JDBCISQL is a command-line interface that supports connecting your driver
to a data source, executing SQL statements and retrieving results in a 
terminal. This tool provides a method to quickly test your drivers in an 
environment that does not support GUIs. 

Java SE 7 Support
-----------------
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). 

Support for API 1.4
------------------- 
The driver has been enhanced to support Oracle RightNow CX API version 1.4.

When attempting to connect with the enhanced driver for the first
time, either delete the existing native files manually or set the CreateMap
connection property to ForceNew.

ManagedObjects connection property
----------------------------------
The driver may not fetch metadata for the newly added managed objects by 
default. You can specify them using the ManagedObjects connection property
to fetch metadata for them.

EnableAccessRequestHeader connection property
---------------------------------------------
The new EnableAccessRequestHeader connection property allows you to enable
the access request header for a connection to improve its performance and
quality of service.

Deprecation of InterfaceName connection property
------------------------------------------------
The InterfaceName connection property has been deprecated. The driver will
continue to provide backward copatibility for it, but will not use it for
connections in the current and new versions.

NamedIDBehavior Configuration Option
------------------------------------
The new NamedIDBehavior configuration option allows you to determine whether the
Name attribute of NamedID fields is exposed in the relational map. This  option
can be used to avoid "Poor performing query" errors by reducing the size of
result sets. For details, see "'Poor performing query' Error  Message" and
"NamedIDBehavior Configuration Option" in "Notes, Known Problems, and
Restictions."

Statement Pooling
-----------------
The driver no longer registers the Statement Pool Monitor as a JMX MBean by
default. To register the Statement Pool Monitor and manage statement pooling with
standard JMX API calls, the new RegisterStatementPoolMonitorMBean connection
property must be set to true. See "Notes, Known Problems, and Restrictions" for
details.


     Changes for Service Pack 4

Result Set Holdability
----------------------
Support for result set holdability has been added to the driver.


     Features

The driver supports standard SQL query language to provide read-only access to
data managed by Oracle Service Cloud. The driver maps the Oracle Service
Cloud data model to a set of relational tables and uses a client-side data cache
for improved performance.

* The driver supports the Oracle RightNow CX API version 1.2 against sites
  using Oracle Service Cloud February 2014 or later.

* The driver supports all JDBC Core functions.

* The driver supports the core SQL-92 grammar.

* The driver supports SSL encryption and User ID/Password authentication.

* The driver supports statement pooling.

* The driver supports connecting through a proxy server.

* The driver supports the following data types:
  - BASE_64_BINARY    maps to LONGVARBINARY
  - BOOLEAN           maps to BOOLEAN
  - DATE              maps to DATE
  - DATETIME          maps to TIMESTAMP
  - DECIMAL           maps to DOUBLE
  - ID                maps to BIGINT
  - INTEGER           maps to INTEGER
  - LONG              maps to BIGINT
  - LONGTEXT          maps to LONGVARCHAR
  - STRING            maps to VARCHAR

* The driver package includes the following components:
  - DataDirect Test for JDBC
  - DataDirect Spy for JDBC
  - DataDirect Statement Pool Monitor


     Notes, Known Problems, and Restrictions

The following are notes, known problems, and restrictions with the Oracle
Service Cloud driver.

"Poor performing query" Error Message
-------------------------------------
Oracle Service Cloud returns a "Poor performing query" error when executing 
certain queries with the driver. This typically occurs when executing a query 
that requires the Oracle Service Cloud service to perform join operations on 
tables containing a large number of rows. We are currently working on a 
permanent solution to this problem; however, in the interim, you can work 
around this issue by doing the following:

1. Configure the following connection properties to the values provided:

   ConfigOptions
   -------------   
   Value: (NamedIDBehavior=2)
   Note: In addition to specifying the recommended value, include any other
   key value pairs that you currently specify for ConfigOptions. These key value
   pairs should be specified in parentheses in a comma-separated list. For
   details, see "ConfigOptions" in the User's Guide.
   
   CreateDB
   --------
   Value: forceNew
   Note: Set CreateDB to forceNew for your initial connection. With this setting
   for the initial connection, NamedIDBehavior=2 takes effect and local map files
   are rebuilt to avoid "Poor performing query" errors. After the local map files
   have been rebuilt, CreateDB should be set to your preferred setting. We
   recommend setting CreateDB to notExist.
   
   EnablePagingWithOrderByID
   -------------------------
   Value: true
   Note: This default value allows the driver to inject the Order By clause in
   the Select query.
   
2. Connect to your Oracle Service Cloud instance. At connection, the driver
   deletes the current local map files and creates new files using the updated
   configuration option settings.
   
3. Change the value of CreateDB to your preferred setting before your next 
   connection. We recommend specifying a value of notExist.

4. Test your settings by executing a query that previously returned the error.
   Based on the results, choose one of the following:
   - If you receive the "Poor performing query" error, proceed to the 
     next step.
   - If your query is successfully returned, skip to the "Results" section.  
   
5. Tune the driver's fetching behavior. Using the WSFetchSize property, decrease
   the number of rows the driver attempts to fetch until the "Poor performing
   query" error is no longer returned. For optimal performance, configure
   WSFetchSize so that the driver returns the maximum number of rows possible
   without returning the error. For example, if you receive the error fetching
   500 rows, but not 499 rows, set WSFetchSize=499 for maximum throughput. Be
   aware that decreasing the fetch size can increase the number of web service
   calls the driver makes to the Oracle Service Cloud service. If your query
   exceeds the statement call limit, increase the number of rows fetched using
   WSFetchSize or increase the statement call limit using the StatementCallLimit
   property to work around this issue.
   
   Notes: 
   * You must disconnect and reconnect for changes to connection property values
     to take effect.
   * In the default setting, WSFetchSize=0, the driver uses the maximum page 
     size allowed by the database to determine the number of rows it attempts 
     to fetch for Oracle Service Cloud versions August 2014 or later. For 
     versions earlier than August 2014, the driver attempts to fetch a maximum
     of 10,000 rows.
	 
Results: 
This configuration allows you to avoid the "Poor performing query" error in
subsequent connections. If you begin receiving the error again, tune the 
WSFetchSize connection property according to the guidelines provided in step 4.

NamedIDBehavior Configuration Option 
------------------------------------
Determines whether the Name attribute of NamedID fields is exposed in the
relational map. 

Valid Values:
1 | 2 

The value for this option is specified as a key value pair via the ConfigOptions
property. For details, see "ConfigOptions" in the User's Guide.

Behavior:
If set to 1, the driver exposes the Name attribute of the NamedID fields in 
the relational model. Specify this setting if your application needs to 
access the Name strings associated with NamedID columns.

If set to 2, the driver does not expose the Name attribute of the NamedID 
fields in the relational model. This setting can be used to avoid "Poor 
performing query" errors received when executing SELECT * queries against
tables containing a large number of rows.

Default:
1

Notes:
If you are receiving "Poor performing query" errors, you can work around this
issue by setting NamedIDBehavior=2. This reduces the size of the result set,
allowing the Oracle Service Cloud service to successfully return the query. For
this change to have effect, you will need recreate the local mapping files by
setting CreateDB=forceNew; then, connecting to your Oracle Service Cloud
instance. After creating your new local mapping files, you should reconfigure
CreateDB to your preferred setting. We recommend a setting of CreateDB=notExist.

RegisterStatementPoolMonitorMBean Connection Property
-----------------------------------------------------
The RegisterStatementPoolMonitorMBean connection property registers the
Statement Pool Monitor as a JMX MBean when statement pooling has been enabled
with MaxPooledStatements. This allows you to manage statement pooling with
standard JMX API calls and to use JMX-compliant tools, such as JConsole.
- Valid values are true | false
- If set to true, the driver registers an MBean for the statement pool monitor
  for each statement pool. This gives applications access to the Statement
  Pool Monitor through JMX when statement pooling is enabled.
- If set to false, the driver does not register an MBean for the Statement Pool
  Monitor for any statement pool.
- Registering the MBean exports a reference to the Statement Pool Monitor. The
  exported reference can prevent garbage collection on connections if the
  connections are not properly closed. When garbage collection does not take
  place on these connections, out of memory errors can occur.
- The default is false.
- The data type is boolean.

CreatedTime and UpdatedTime Fields
----------------------------------
Although the CreatedTime and UpdatedTime fields on custom objects map to the
relational view, you cannot query against them unless you enable the fields
within the Object Designer in the Oracle Service Cloud admin tool.

ExtStatementPoolMBean Method
----------------------------
When calling the ExtStatementPoolMonitorMBean.getName() method, the driver
should return a concatenation of the driver's name, the loginHost URL to which
the Statement Pool Monitor is connected, and the MBean ID of the connection. The
driver returns null in place of the loginHost URL.

Invalid Schema Error
--------------------
The driver returns an invalid schema error when creating a view using a two-part
name in the view definition.

DROP CACHE Statement
--------------------
In some situations, executing a DROP CACHE statement will complete successfully
without dropping the cache.

Queries Against File Attachments
--------------------------------
Queries against File attachments for sub-objects fail to retrieve the attachment
data.

Executing DataDirect Shell Script
---------------------------------
For UNIX 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

Performance Tuning Wizard
-------------------------
The Performance Tuning Wizard is not available with the Oracle Service Cloud
driver. For information on tuning the driver for performance, see "Performance
Considerations" in the USER'S GUIDE.

Help System Issue
-----------------
Internet Explorer with the Google Toolbar installed sometimes displays the
following error when the browser is closed: "An error has occurred in the
script on this page." This is a known issue with the Google Toolbar and has
been reported to Google. When closing the driver's help system, this error may
display.


     Documentation	 	 

PROGRESS DATADIRECT FOR JDBC FOR ORACLE SERVICE CLOUD DOCUMENTATION SET
-----------------------------------------------------------------------
The driver documentation set is available from the Progress Information Hub:

https://docs.progress.com/category/datadirect-oracle-service-cloud

You can access the online help system directly via the HTML redirect in the
installation Help directory.


     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
* DriverModules
  - PROGRESS_DATADIRECT_JDBC_OSC_5.1.4_INSTALL.iam.zip
  - PROGRESS_DATADIRECT_JDBC_COMMON_5.1.4_INSTALL.iam.zip

Non-Windows:
------------
* PROGRESS_DATADIRECT_JDBC_INSTALL.jar
* DriverModules
  - PROGRESS_DATADIRECT_JDBC_OSC_5.1.4_INSTALL.iam.zip
  - PROGRESS_DATADIRECT_JDBC_COMMON_5.1.4_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

fixes.txt                  Information on resolved issues for Progress
                           DataDirect for JDBC drivers


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/JNDI/:
---------------------------
JNDI_FILESYSTEM_Example.java
                           Example Java(TM) source file

JNDI_LDAP_Example.java     Example Java source file


INSTALL_DIR/help/: 
------------------
*.html                     HTML redirects to driver help systems


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

logs/*.*                   Log file generated upon installing or uninstalling


INSTALL_DIR/jdbcisql/:
----------------------
jdbcisql.bat               Batch file to start JDBC iSQL

jdbcisql.jar               Java program to start JDBC iSQL

jdbcisql.sh                Shell script to start JDBC iSQL


INSTALL_DIR/lib/51:
-----------------
rightnow.jar               Oracle Service Cloud Driver and DataSource classes


INSTALL_DIR/NOTICES/:
---------------------
JDBC for Oracle Service Cloud v5.1.4 notices.txt
                           Third party agreement information


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


INSTALL_DIR/READMES/:
---------------------
JDBC for Oracle Service Cloud v5.1.4 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.exe         Windows uninstaller

Uninstall_JDBC.lax         Support file for the Windows uninstaller

uninstaller.jar            Java uninstaller

resource/*.*               Resource files for the Windows uninstaller


February 2026
================
End of README