Progress DataDirect for JDBC forOracleSales Cloud · Kinvey,NativeScriptSidekick,OpenAccess,ProDataSet,ProgressResults,ProgressSoftware,ProVision, PSEPro,Sitefinity,SmartBrowser,SmartComponent,SmartDataBrowser,

Progress® DataDirect® forJDBC™ for Oracle SalesCloud™

User's Guide

6.0.0 Release

Copyright

© 2017 Progress Software Corporation and/or its subsidiaries or affiliates. All rightsreserved.These materials and all Progress® software products are copyrighted and all rights are reserved by ProgressSoftware Corporation. The information in these materials is subject to change without notice, and ProgressSoftware Corporation assumes no responsibility for any errors that may appear therein. The references in thesematerials to specific platforms supported are subject to change.

Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirectXML Converters, DataDirect XQuery, DataRPM, Deliver More Than Expected, Icenium, Kendo UI, MakingSoftware Work Together, NativeScript, OpenEdge, Powered by Progress, Progress, Progress SoftwareDevelopers Network, Rollbase, SequeLink, Sitefinity (and Design), SpeedScript, Stylus Studio, TeamPulse,Telerik, Telerik (and Design), Test Studio, and WebSpeed are registered trademarks of Progress SoftwareCorporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. Analytics360, AppServer,BusinessEdge, DataDirect Spy, SupportLink, DevCraft, Fiddler, JustCode, JustDecompile, JustMock, JustTrace,Kinvey, NativeScript Sidekick, OpenAccess, ProDataSet, Progress Results, Progress Software, ProVision,PSE Pro,Sitefinity, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView,SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow,and WebClient are trademarks or service marks of Progress Software Corporation and/or its subsidiaries oraffiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any othermarks contained herein may be trademarks of their respective owners.

Please refer to the Release Notes applicable to the particular Progress product release for any third-partyacknowledgments required to be provided in the documentation associated with the Progress product.

Updated: 2017/11/03

3Progress® DataDirect® for JDBC™ for Oracle Sales Cloud™: User's Guide: Version 6.0.0

Progress® DataDirect® for JDBC™ for Oracle Sales Cloud™: User's Guide: Version 6.0.04

Copyright

Table of Contents

Chapter 1: Welcome to the Progress DataDirect for JDBC for Oracle SalesCloud Driver................................................................................................9

Release highlights.................................................................................................................................10Requirements........................................................................................................................................10Driver and DataSource classes............................................................................................................10Connection URL....................................................................................................................................10Version string information.....................................................................................................................11Connection properties and configuration options..................................................................................12Data types.............................................................................................................................................12

getTypeInfo()..............................................................................................................................12Mapping objects to tables.....................................................................................................................15Contacting Technical Support...............................................................................................................15

Chapter 2: Getting started...........................................................................17Driver and DataSource classes............................................................................................................17Connecting using the DriverManager...................................................................................................18

Setting the class path ................................................................................................................18Passing the connection URL......................................................................................................18Testing the connection...............................................................................................................19

Connecting using data sources.............................................................................................................22How data sources are implemented...........................................................................................23Creating data sources................................................................................................................23Calling a DataSource in an application......................................................................................23

Chapter 3: Using the driver.........................................................................25Connecting from an application............................................................................................................26

Driver and DataSource classes..................................................................................................26Connecting using the DriverManager.........................................................................................26Connecting using data sources..................................................................................................30

Using connection properties.................................................................................................................31Required properties....................................................................................................................32Mapping properties....................................................................................................................32Web service properties..............................................................................................................33Proxy server properties..............................................................................................................33Additional properties..................................................................................................................33

Proxy server support.............................................................................................................................34Unicode.................................................................................................................................................34


Contents

Data encryption.....................................................................................................................................34Catalog Tables......................................................................................................................................34

SYSTEM_REMOTE_SESSIONS catalog table.........................................................................35SYSTEM_SESSIONS catalog table...........................................................................................36

Identifiers...............................................................................................................................................37Timeouts...............................................................................................................................................37Scrollable cursors.................................................................................................................................38Parameter metadata support................................................................................................................38ResultSet metadata support.................................................................................................................39Error handling.......................................................................................................................................39Rowset support.....................................................................................................................................40DataDirect Test......................................................................................................................................40

DataDirect Test Tutorial..............................................................................................................41Tracking JDBC calls with DataDirect Spy.............................................................................................73

Enabling DataDirect Spy............................................................................................................73

Chapter 4: Connection property descriptions...........................................77ConfigOptions.......................................................................................................................................79

APIVersion (configuration option)...............................................................................................80CreateMap............................................................................................................................................80Password..............................................................................................................................................81ProxyHost..............................................................................................................................................82ProxyPassword.....................................................................................................................................83ProxyPort..............................................................................................................................................83ProxyUser.............................................................................................................................................84SchemaMap..........................................................................................................................................85ServerName..........................................................................................................................................86SpyAttributes.........................................................................................................................................87User.......................................................................................................................................................88WSFetchSize........................................................................................................................................88WSRetryCount......................................................................................................................................89WSTimeout...........................................................................................................................................90

Chapter 5: Troubleshooting........................................................................91Troubleshooting your application..........................................................................................................91

Turning on and off DataDirect Spy logging................................................................................92Using Java logging................................................................................................................................92

Logging components..................................................................................................................92Using the JVM for logging..........................................................................................................94

Contacting Technical Support...............................................................................................................95

Chapter 6: Supported SQL functionality....................................................97Alter Session (EXT)..............................................................................................................................97


Contents

Refresh Map (EXT)...............................................................................................................................99Select....................................................................................................................................................99

Select clause............................................................................................................................100SQL expressions.................................................................................................................................110

Column names.........................................................................................................................110Literals......................................................................................................................................110Operators.................................................................................................................................113Functions..................................................................................................................................116Conditions................................................................................................................................116

Subqueries..........................................................................................................................................117IN predicate..............................................................................................................................118EXISTS predicate.....................................................................................................................118UNIQUE predicate...................................................................................................................118Correlated subqueries..............................................................................................................119

Chapter 7: SQL escape sequences for JDBC..........................................121Date, time, and timestamp escape sequences...................................................................................122Scalar functions..................................................................................................................................122Outer join escape sequences.............................................................................................................124LIKE escape character sequence for wildcards..................................................................................124

Chapter 8: JDBC support..........................................................................125Array....................................................................................................................................................126Blob.....................................................................................................................................................127CallableStatement...............................................................................................................................128Clob.....................................................................................................................................................139Connection..........................................................................................................................................140ConnectionEventListener....................................................................................................................145ConnectionPoolDataSource................................................................................................................146DatabaseMetaData.............................................................................................................................146DataSource.........................................................................................................................................154Driver...................................................................................................................................................155ParameterMetaData............................................................................................................................155PooledConnection...............................................................................................................................157PreparedStatement.............................................................................................................................157Ref.......................................................................................................................................................162ResultSet.............................................................................................................................................162ResultSetMetaData.............................................................................................................................173RowSet................................................................................................................................................174SavePoint............................................................................................................................................174Statement............................................................................................................................................174StatementEventListener......................................................................................................................178Struct...................................................................................................................................................179


Contents

XAConnection.....................................................................................................................................179XADataSource....................................................................................................................................179XAResource........................................................................................................................................179

Chapter 9: JDBC extensions.....................................................................181DatabaseMetaData interface..............................................................................................................181ExtLogControl class............................................................................................................................182

Chapter 10: Designing JDBC Applications for PerformanceOptimization............................................................................................183

Using Database Metadata Methods....................................................................................................184Minimizing the Use of Database Metadata Methods................................................................184Avoiding Search Patterns.........................................................................................................185Using a Dummy Query to Determine Table Characteristics.....................................................185

Returning Data....................................................................................................................................186Returning Long Data................................................................................................................186Reducing the Size of Returned Data........................................................................................187Choosing the Right Data Type.................................................................................................187Retrieving Result Sets..............................................................................................................187

Selecting JDBC Objects and Methods ...............................................................................................188Using Parameter Markers as Arguments to Stored Procedures..............................................188Using the Statement Object Instead of the PreparedStatement Object...................................188Using Batches Instead of Prepared Statements......................................................................189Choosing the Right Cursor.......................................................................................................190Using get Methods Effectively..................................................................................................190Retrieving Auto Generated Keys..............................................................................................191

Managing Connections and Updates..................................................................................................191Managing Connections............................................................................................................192Managing Commits in Transactions.........................................................................................192Choosing the Right Transaction Model....................................................................................193Using updateXXX Methods......................................................................................................193Using getBestRowIdentifier......................................................................................................193


Contents

1Welcome to the Progress DataDirect forJDBC for Oracle Sales Cloud Driver

The Progress® DataDirect® for JDBC™ for Oracle Sales Cloud™ driver supports SQL read access to Oracle SalesCloud. To support SQL access to Oracle Sales Cloud, the driver creates a relational map of the Oracle SalesCloud data model and translates SQL statements provided by the application to Oracle Sales Cloud queriesand web service calls.

For details, see the following topics:

• Release highlights

• Requirements

• Driver and DataSource classes

• Connection URL

• Version string information

• Connection properties and configuration options

• Data types

• Mapping objects to tables

• Contacting Technical Support


Release highlightsHighlights of the 6.0.0 Release• Supports SQL read access to the Oracle Sales Cloud. See Supported SQL functionality on page 97 for

details.

• Supports JDBC core functions. See JDBC support on page 125 for details.

• Supports Oracle Sales Cloud data types. See Data types on page 12 and getTypeInfo() on page 12 fordetails.

• Supports HTTP proxy. See Proxy server support on page 34 for details.

• Supports timeout functionality. See Timeouts on page 37 for details.

RequirementsThe driver is compatible with JDBC 2.0, 3.0, 4.0, 4.1, and 4.2. The driver must be run on a Java SE 7 or higherJVM.

Driver and DataSource classesDriver classThe Driver class is:

com.ddtek.jdbc.oraclesalescloud.OracleSalesCloudDriver

DataSource classThe DataSource class is:

com.ddtek.jdbcx.oraclesalescloud.OracleSalesCloudDataSource

Connection URLConnection URLThe connection URL takes the following form:

jdbc:datadirect:oraclesalescloud://base_url;User=user_id;Password=password[;property=value[;...]]

where:


Chapter 1: Welcome to the Progress DataDirect for JDBC for Oracle Sales Cloud Driver

base_url

specifies the base URL of the Oracle Sales Cloud site to which you are connecting, for example,mysite.custhelp.com. This value should not include an internet protocol such as http:// orhttps://.

user_id

specifies the user name that used to connect to the Oracle Sales Cloud instance.

password

specifies the password for the specified User.

property=value

specifies additional connection property settings.

The following is an example of a connection URL to an Oracle Sales Cloud instance.

jdbc:datadirect:oraclesalescloud://mysite.custhelp.com;[email protected];Password=secret

Version string informationThe DatabaseMetaData.getDriverVersion() method returns a Driver Version string in the format:

M.m.s.bbbbbb(CXXXX.FYYYYYY.UZZZZZZ)

where:

M is the major version number.

m is the minor version number.

s is the service pack number.

bbbbbb is the driver build number.

XXXX is the cloud adapter build number.

YYYYYY is the framework build number.

ZZZZZZ is the utl build number.

For example:

6.0.0.000002(C0003.F000001.U000002)|____| |___| |_____| |_____|Driver Cloud Frame Utl


Version string information

Connection properties and configuration optionsThe driver includes over 15 connection properties and configuration options. You can use these properties andoptions to customize the driver for your environment. These properties and options can be used to accomplishdifferent tasks, such as controlling driver functionality and optimizing performance.

See Using connection properties on page 31 and Connection property descriptions on page 77 for moreinformation.

Data typesThe following table lists Oracle Sales Cloud data types supported by the driver and how they are mapped toJDBC data types.

See getTypeInfo() on page 12 for getTypeInfo() results of data types supported by the driver.

Table 1: Oracle Sales Cloud data types

JDBC data typeOracle Sales Cloud data type

BOOLEANBOOLEAN

DECIMALDECIMAL

INTEGER or BIGINT or DECIMALINTEGER1

BIGINTLONG

LONGVARCHARLONGSTRING

VARCHARSTRING2

getTypeInfo()The DatabaseMetaData.getTypeInfo()method returns information about data types. The following tableprovides getTypeInfo() results for supported Oracle Sales Cloud data types.

1 When precision is less than or equal to 9, INTEGER is mapped as INTEGER. When precision is greater than 9, INTEGERis mapped as BIGINT. When no precision is specified, INTEGER is mapped as DECIMAL with a precision of 19 and a scaleof 4.

2 When no precision for STRING fields is offered in the metadata, STRING is mapped as VARCHAR with a length of 4000characters.When precision forSTRING columns is available, the precision is maintained andSTRING is mapped asVARCHAR.



Table 2: getTypeInfo()

MINIMUM_SCALE = NULL

NULLABLE = 1

NUM_PREC_RADIX = NULL

PRECISION = 1

SEARCHABLE = 3

SQL_DATA_TYPE = NULL

SQL_DATETIME_SUB = NULL

UNSIGNED_ATTRIBUTE = NULL

TYPE_NAME = boolean

AUTO_INCREMENT = false

CASE_SENSITIVE = false

CREATE_PARAMS = NULL

DATA_TYPE = 16 (BOOLEAN)

FIXED_PREC_SCALE = false

LITERAL_PREFIX = NULL

LITERAL_SUFFIX = NULL

LOCAL_TYPE_NAME = BOOLEAN

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 19

SEARCHABLE = 3



UNSIGNED_ATTRIBUTE = false

TYPE_NAME = decimal




DATA_TYPE = 3 (DECIMAL)




LOCAL_TYPE_NAME = DECIMAL

MAXIMUM_SCALE = 4

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 10

SEARCHABLE = 3




TYPE_NAME = integer3




DATA_TYPE = 4 (INTEGER)




LOCAL_TYPE_NAME = INTEGER

MAXIMUM_SCALE = 0

3 When precision is less than or equal to 9, INTEGER is mapped as INTEGER. When precision is greater than 9, INTEGERis mapped as BIGINT. When no precision is specified, INTEGER is mapped as DECIMAL with a precision of 19 and a scaleof 4.


Data types

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 19

SEARCHABLE = 3




TYPE_NAME = long




DATA_TYPE = -5 (BIGINT)




LOCAL_TYPE_NAME = LONG

MAXIMUM_SCALE = 0


NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 2147483647

SEARCHABLE = 0




TYPE_NAME = longstring


CASE_SENSITIVE = true


DATA_TYPE = -1 (LONGVARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = LONGVARCHAR

MAXIMUM_SCALE = 0


NULLABLE = 1

NUM_PREC_RADIX = NULL

PRECISION = 4000

SEARCHABLE = 3




TYPE_NAME =string4


CASE_SENSITIVE = true


DATA_TYPE = 12 (VARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = STRING

MAXIMUM_SCALE = 0

4 When no precision for STRING fields is offered in the metadata, STRING is mapped as VARCHAR with a length of 4000characters.When precision forSTRING columns is available, the precision is maintained andSTRING is mapped asVARCHAR.



Mapping objects to tablesThe driver automatically maps Oracle Sales Cloud objects and fields to tables and columns when it first connectsto an Oracle Sales Cloud instance. The driver maps standard as well as custom objects. The driver uses alocal schema map to instantiate the mapping of the remote data source objects to tables and the metadataassociated with those tables. The driver creates a schema map for each user. By default, the schema map iscreated in the directory from which the application is run. The CreateMap connection property allows you toupdate or re-create the schema map. The schema map uses the user ID specified for the connection as thename of the schema map configuration file. If the user ID contains punctuation or other non-alphanumericcharacters, the driver strips those characters from the user ID to form the name of the schemamap configurationfile. You can set the SchemaMap connection property to override the default setting for the name and locationof the database.

Note that the Refresh Map SQL extension can also be used to update the relational map of your data.

See alsoCreateMap on page 80SchemaMap on page 85Refresh Map (EXT) on page 99

Contacting Technical SupportProgress DataDirect offers a variety of options to meet your support needs. Please visit our Web site for moredetails and for contact information:

https://www.progress.com/support

The Progress DataDirect Web site provides the latest support information through our global service network.The SupportLink program provides access to support contact details, tools, patches, and valuable information,including a list of FAQs for each product. In addition, you can search our Knowledgebase for technical bulletinsand other information.

When you contact us for assistance, please provide the following information:

• Your number or the serial number that corresponds to the product for which you are seeking support, or acase number if you have been provided one for your issue. If you do not have a SupportLink contract, theSupportLink representative assisting you will connect you with our Sales team.

• Your name, phone number, email address, and organization. For a first-time call, you may be asked for fullinformation, including location.

• The Progress DataDirect product and the version that you are using.

• The type and version of the operating system where you have installed your product.

• Any database, database version, third-party software, or other environment information required to understandthe problem.

• A brief description of the problem, including, but not limited to, any error messages you have received, whatsteps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and soon. Depending on the complexity of the problem, you may be asked to submit an example or reproducibleapplication so that the issue can be re-created.


Mapping objects to tables


• A description of what you have attempted to resolve the issue. If you have researched your issue on Websearch engines, our Knowledgebase, or have tested additional configurations, applications, or other vendorproducts, you will want to carefully note everything you have already attempted.

• A simple assessment of how the severity of the issue is impacting your organization.



2Getting started

After the driver has been installed and defined on your class path, you can connect from your application toyour database in either of the following ways.

• Using the JDBC DriverManager, by specifying the connection URL in theDriverManager.getConnection() method.

• Creating a JDBC DataSource that can be accessed through the Java Naming Directory Interface (JNDI).


• Driver and DataSource classes

• Connecting using the DriverManager

• Connecting using data sources

Driver and DataSource classesDriver classThe Driver class is:





Connecting using the DriverManagerYou can connect to an Oracle Sales Cloud instance using the JDBC DriverManager with theDriverManager.getConnection()method. As the following example shows, this method specifies a stringcontaining a connection URL.

Connection conn = DriverManager.getConnection

("jdbc:datadirect:oraclesalescloud://mysite.custhelp.com;[email protected];Password=secret");

Setting the class pathThe driver must be defined on your class path before you can connect. The class path is the search string yourJava Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not defined on yourclass path, you will receive a class not found exception when trying to load the driver. Set your systemclass path to include the oraclesalescloud.jar file as shown, where install_dir is the path to yourproduct installation directory.

install_dir/lib/oraclesalescloud.jar

Windows ExampleCLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\oraclesalescloud.jar

UNIX ExampleCLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/oraclesalescloud.jar

Passing the connection URLAfter setting the class path, the required connection information needs to be passed in the form of a connectionURL. The connection URL takes the form:


where:

base_url


user_id



Chapter 2: Getting started

password


property=value




Testing the connectionYou can also use DataDirect Test™ to establish and test a DriverManager connection. The screen shots inthis section were taken on a Windows system.

Take the following steps to establish a connection.

1. Navigate to the installation directory. The default location is:

• Windows systems: Program Files\Progress\DataDirect\JDBC_60\testforjdbc

• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_60/testforjdbc

Note: For UNIX/Linux, if you do not have access to /opt, your home directory will be used in its place.

2. From the testforjdbc folder, run the platform-specific tool:

• testforjdbc.bat (on Windows systems)• testforjdbc.sh (on UNIX and Linux systems)

The Test for JDBC Tool window appears:


Connecting using the DriverManager

3. Click Press Here to Continue.

The main dialog appears:



4. From the menu bar, select Connection > Connect to DB.

The Select A Database dialog appears:

5. Select the appropriate database template from the Defined Databases field.

6. In the Database field, specify the base URL of the Oracle Sales Cloud site to which you are connecting.

The base URL replaces servername in the sample string. For example:

jdbc:datadirect:oraclesalescloud://mysite.custhelp.com


Connecting using the DriverManager

7. If you are using user ID/password authentication, enter your user ID and password in the correspondingfields.

8. Click Connect.

If the connection information is entered correctly, the JDBC/Database Outputwindow reports that a connectionhas been established. (If a connection is not established, the window reports an error.)

For more information about using DataDirect Test, see DataDirect Test on page 40.

Connecting using data sourcesA JDBC DataSource is a Java object that defines connection information required for a JDBC driver to connectto the database. Each JDBC driver vendor provides their own data source implementation for this purpose. AProgress DataDirect data source is Progress DataDirect’s implementation of a DataSource object that providesthe connection information needed for the driver to connect to a database.

Because data sources work with the Java Naming Directory Interface (JNDI) naming service, data sourcescan be created andmanaged separately from the applications that use them. Because the connection informationis defined outside of the application, the effort to reconfigure your infrastructure when a change is made isminimized. For example, if the database is moved to another database server, the administrator need onlychange the relevant properties of the DataSource object. The applications using the database do not needto change because they only refer to the name of the data source.



How data sources are implementedData sources are implemented through a DataSource class. A DataSource class implements thejavax.sql.DataSource interface.

See alsoDriver and DataSource classes on page 10

Creating data sourcesThe following example files provide details on creating and using Progress DataDirect data sources with theJava Naming Directory Interface (JNDI), where install_dir is the product installation directory.

• install_dir/Examples/JNDI/JNDI_LDAP_Example.java can be used to create a JDBCDataSourceand save it in your LDAP directory using the JNDI Provider for LDAP.

• install_dir/Examples/JNDI/JNDI_FILESYSTEM_Example.java can be used to create a JDBCDataSource and save it in your local file system using the File System JNDI Provider.

To connect using a JNDI DataSource, the driver needs to access a JNDI data store to persist the data sourceinformation. For a JNDI file system implementation, you must download the File System Service Provider fromthe Oracle Technology Network Java SE Support downloads page, unzip the files to an appropriate location,and add the fscontext.jar and providerutil.jar files to your class path. These steps are not requiredfor LDAP implementations because the LDAP Service Provider has been included with Java SE since Java 2SDK, v1.3.

Calling a DataSource in an applicationApplications can call a Progress DataDirect DataSource using a logical name to retrieve thejavax.sql.DataSource object. This object loads the specified driver and can be used to establish aconnection to the database.

Once the DataSource has been registered with JNDI, it can be used by your JDBC application as shown inthe following code example.

Context ctx = new InitialContext();DataSource ds = (DataSource)ctx.lookup("EmployeeDB");Connection con = ds.getConnection("domino", "spark");

In this example, the JNDI environment is first initialized. Next, the initial naming context is used to find thelogical name of the data source (EmployeeDB). The Context.lookup() method returns a reference to aJava object, which is narrowed to a javax.sql.DataSource object. Then, theDataSource.getConnection() method is called to establish a connection.


Connecting using data sources

http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR



3Using the driver

This section provides information on how to connect to your data store using either the JDBC DriverManageror DataDirect JDBC data sources, as well as information on how to implement and use functionality supportedby the driver.


• Connecting from an application

• Using connection properties

• Proxy server support

• Unicode

• Data encryption

• Catalog Tables

• Identifiers

• Timeouts

• Scrollable cursors

• Parameter metadata support

• ResultSet metadata support

• Error handling

• Rowset support

• DataDirect Test


• Tracking JDBC calls with DataDirect Spy

Connecting from an applicationOnce the driver is installed and configured, you can connect from your application to your database in eitherof the following ways:

• Using the JDBC DriverManager, by specifying the connection URL in theDriverManager.getConnection() method.

• Creating a JDBC data source that can be accessed through the Java Naming Directory Interface (JNDI).

Driver and DataSource classes

Driver classThe Driver class is:




Connecting using the DriverManagerYou can connect to an Oracle Sales Cloud instance using the JDBC DriverManager with theDriverManager.getConnection()method. As the following example shows, this method specifies a stringcontaining a connection URL.

Connection conn = DriverManager.getConnection

("jdbc:datadirect:oraclesalescloud://mysite.custhelp.com;[email protected];Password=secret");

Setting the class pathThe driver must be defined on your class path before you can connect. The class path is the search string yourJava Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not defined on yourclass path, you will receive a class not found exception when trying to load the driver. Set your systemclass path to include the oraclesalescloud.jar file as shown, where install_dir is the path to yourproduct installation directory.

install_dir/lib/oraclesalescloud.jar

Windows ExampleCLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\oraclesalescloud.jar


Chapter 3: Using the driver

UNIX ExampleCLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/oraclesalescloud.jar

Passing the connection URLAfter setting the class path, the required connection information needs to be passed in the form of a connectionURL. The connection URL takes the form:


where:

base_url


user_id


password


property=value




Testing the connectionYou can also use DataDirect Test™ to establish and test a DriverManager connection. The screen shots inthis section were taken on a Windows system.

Take the following steps to establish a connection.

1. Navigate to the installation directory. The default location is:

• Windows systems: Program Files\Progress\DataDirect\JDBC_60\testforjdbc

• UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_60/testforjdbc

Note: For UNIX/Linux, if you do not have access to /opt, your home directory will be used in its place.

2. From the testforjdbc folder, run the platform-specific tool:

• testforjdbc.bat (on Windows systems)• testforjdbc.sh (on UNIX and Linux systems)


Connecting from an application

The Test for JDBC Tool window appears:

3. Click Press Here to Continue.

The main dialog appears:



4. From the menu bar, select Connection > Connect to DB.

The Select A Database dialog appears:

5. Select the appropriate database template from the Defined Databases field.

6. In the Database field, specify the base URL of the Oracle Sales Cloud site to which you are connecting.

The base URL replaces servername in the sample string. For example:

jdbc:datadirect:oraclesalescloud://mysite.custhelp.com


Connecting from an application

7. If you are using user ID/password authentication, enter your user ID and password in the correspondingfields.

8. Click Connect.

If the connection information is entered correctly, the JDBC/Database Outputwindow reports that a connectionhas been established. (If a connection is not established, the window reports an error.)

For more information about using DataDirect Test, see DataDirect Test on page 40.

Connecting using data sourcesA JDBC DataSource is a Java object that defines connection information required for a JDBC driver to connectto the database. Each JDBC driver vendor provides their own data source implementation for this purpose. AProgress DataDirect data source is Progress DataDirect’s implementation of a DataSource object that providesthe connection information needed for the driver to connect to a database.

Because data sources work with the Java Naming Directory Interface (JNDI) naming service, data sourcescan be created andmanaged separately from the applications that use them. Because the connection informationis defined outside of the application, the effort to reconfigure your infrastructure when a change is made isminimized. For example, if the database is moved to another database server, the administrator need onlychange the relevant properties of the DataSource object. The applications using the database do not needto change because they only refer to the name of the data source.



How data sources are implementedData sources are implemented through a DataSource class. A DataSource class implements thejavax.sql.DataSource interface.

See alsoDriver and DataSource classes on page 10

Creating data sourcesThe following example files provide details on creating and using Progress DataDirect data sources with theJava Naming Directory Interface (JNDI), where install_dir is the product installation directory.

• install_dir/Examples/JNDI/JNDI_LDAP_Example.java can be used to create a JDBCDataSourceand save it in your LDAP directory using the JNDI Provider for LDAP.

• install_dir/Examples/JNDI/JNDI_FILESYSTEM_Example.java can be used to create a JDBCDataSource and save it in your local file system using the File System JNDI Provider.

To connect using a JNDI DataSource, the driver needs to access a JNDI data store to persist the data sourceinformation. For a JNDI file system implementation, you must download the File System Service Provider fromthe Oracle Technology Network Java SE Support downloads page, unzip the files to an appropriate location,and add the fscontext.jar and providerutil.jar files to your class path. These steps are not requiredfor LDAP implementations because the LDAP Service Provider has been included with Java SE since Java 2SDK, v1.3.

Calling a DataSource in an applicationApplications can call a Progress DataDirect DataSource using a logical name to retrieve thejavax.sql.DataSource object. This object loads the specified driver and can be used to establish aconnection to the database.

Once the DataSource has been registered with JNDI, it can be used by your JDBC application as shown inthe following code example.

Context ctx = new InitialContext();DataSource ds = (DataSource)ctx.lookup("EmployeeDB");Connection con = ds.getConnection("domino", "spark");

In this example, the JNDI environment is first initialized. Next, the initial naming context is used to find thelogical name of the data source (EmployeeDB). The Context.lookup() method returns a reference to aJava object, which is narrowed to a javax.sql.DataSource object. Then, theDataSource.getConnection() method is called to establish a connection.

Using connection propertiesYou can use connection properties to customize the driver for your environment. This section organizesconnection properties according to functionality. You can use connection properties with either the JDBCDriverManager or a JDBC DataSource. For a DriverManager connection, a property is expressed as akey value pair and takes the form property=value. For a DataSource connection, a property is expressedas a JDBCmethod and takes the form setproperty(value). Connection property names are case-insensitive.For example, Password is the same as password.


Using connection properties


Note: In a JDBC DataSource, string values must be enclosed in double quotation marks, for example,setUser("[email protected]").

See Connection property descriptions on page 77 for an alphabetical list of connection properties and theirdescriptions.

Required propertiesThe following table summarizes connection properties which are required to connect to an Oracle Sales Cloudinstance.

Table 3: Required properties

CharacteristicProperty

Specifies the password used to connect to your Oracle Sales Cloud instance foruser ID/password authentication.

Password on page 81

Specifies the base URL of the Oracle Sales Cloud instance to which the driver isconnecting.

ServerName on page 86

Specifies the user ID used to connect to your Oracle Sales Cloud instance for userID/password authentication.

User on page 88

See alsoConnection property descriptions on page 77

Mapping propertiesThe following table summarizes connection properties which are used for the relational mapping of OracleSales Cloud data.

Table 4: Required properties


Allows you to specify which version of the Oracle Sales Cloud API is being usedin your environment with the APIVersion configuration option.

ConfigOptions on page79

Determines whether the driver creates the internal files required for a relationalmap of the native data when establishing a connection.

CreateMap on page 80

Specifies the name and location of the configuration file used to create the relationalmap of native data. The driver looks for this file when connecting to an OracleSales Cloud instance. By default, if the file does not exist, the driver creates one.

SchemaMap on page 85

See alsoMapping objects to tables on page 15



Connection property descriptions on page 77

Web service propertiesThe following table summarizes web service properties.

Table 5: Web service properties


Specifies the maximum number of rows of data the driver can attempt tofetch for each call. The default is 100 (rows).

WSFetchSize on page 88

Specifies the number of times the driver retries a timed-out Select request.Insert, Update, and Delete requests are never retried. The timeout periodis specified by the WSTimeout connection property. The default is 0.

WSRetryCount on page 89

Specifies the time, in seconds, that the driver waits for a response to aweb service request. The default is 120 seconds.

WSTimeout on page 90


Proxy server propertiesThe following table summarizes connection properties used in the implementation of a proxy server.

Table 6: Proxy server properties


Specifies a proxy server.ProxyHost on page 82

Specifies the password needed to connect to a proxy server.ProxyPassword on page 83

Specifies the port number where the proxy server is listening for HTTP orHTTPS requests.

ProxyPort on page 83

Specifies the user name needed to connect to a proxy server.ProxyUser on page 84


Additional propertiesThe following table summarizes an additional connection property.


Using connection properties

Table 7: Additional property


Enables DataDirect Spy to log detailed information about callsthat are issued by the driver on behalf of the application.DataDirect Spy is not enabled by default.

SpyAttributes on page 87


Proxy server supportThe driver supports proxy server connections with the ProxyHost, ProxyPort, ProxyUser, and ProxyPasswordconnection properties. See Using connection properties on page 31 and Proxy server properties on page 33for details.

UnicodeMultilingual JDBC applications can be developed on any operating system using the driver to access bothUnicode and non-Unicode enabled databases. Internally, Java applications use UTF-16 Unicode encoding forstring data. When fetching data, the driver automatically performs the conversion from the character encodingused by the database to UTF-16. Similarly, when inserting or updating data in the database, the driverautomatically converts UTF-16 encoding to the character encoding used by the database.

The JDBC API provides mechanisms for retrieving and storing character data encoded as Unicode (UTF-16)or ASCII. Additionally, the Java String object contains methods for converting UTF-16 encoding of string datato or from many popular character encodings.

Data encryptionAll communication between the driver and Oracle Sales Cloud, including user ID/password authentication, isencrypted using Secure Sockets Layer (SSL).

See Using connection properties on page 31 for information on specifying a user ID and password.

Catalog TablesThe driver provides a standard set of catalog tables that maintain the information returned by the methods ofthe JDBC DatabaseMetaData, ParameterMetaData, and ResultSetMetaData interfaces. If possible,use JDBC metadata methods to obtain this information instead of querying the catalog tables directly.



The driver also provides additional catalog tables that maintain metadata specific to the driver. This sectiondefines the catalog tables that provide driver-specific information. The catalog tables are defined in theINFORMATION_SCHEMA schema.

SYSTEM_REMOTE_SESSIONS catalog tableThe system table named SYSTEM_REMOTE_SESSIONS stores information about the each of the remote sessionsthat are active for a given database. The values in the SYSTEM_REMOTE_SESSION table are read-only.

The following table defines the columns of the SYSTEM_REMOTE_SESSIONS table, which is sorted on thefollowing columns: SESSION_ID and SCHEMA.

Table 8: SYSTEM_REMOTE_SESSIONS catalog table

DescriptionData TypeColumn Name

The connection (session) id with which theremote session is associated.

INTEGER,NOT NULL

SESSION_ID

The schema name that is mapped to theremote session.

VARCHAR(128),NOT NULL

SCHEMA

The remote session type. The current validtype is OracleSalesCloud .


TYPE

The value for INSTANCE is null.VARCHAR(128)INSTANCE

The version of the remote data source to whichthe session is connected. This is the versionof the web service API the driver is using toconnect to Oracle Sales Cloud.


VERSION

The configuration options used to define theremote data model to relational data modelmapping.

LONGVARCHAR,NOT NULL

CONFIG_OPTIONS

The options used to establish the remoteconnection. This typically is information neededto log into the remote data source. Thepassword value is not displayed.

LONGVARCHAR,NOT NULL

SESSION_OPTIONS

The number ofWeb service calls made throughthis remote session. The value of theWS_CALL_COUNT column can be reset usingthe ALTER SESSION statement.

INTEGER,NOT NULL

WS_CALL_COUNT


Catalog Tables

DescriptionData TypeColumn Name

The total of all of the web service calls madeto the same remote data source by all activeconnections using the same server name anduser ID.

INTEGER,NOT NULL

WS_AGGREGATE_CALL_COUNT

The number of REST calls made by thisconnection. REST calls are used for bulkoperations, invoking reports, and describingreport parameters.

INTEGER,NOT NULL

REST_AGGREGATE_CALL_COUNT

SYSTEM_SESSIONS catalog tableThe system table named SYSTEM_SESSIONS stores information about current system sessions. The valuesin the SYSTEM_SESSIONS table are read-only.

The following table defines the columns of the SYSTEM_SESSIONS table.

Table 9: SYSTEM_SESSIONS catalog table

DescriptionData TypeColumn

A unique ID that identifies this session. The system functionCURSESSIONID( ) returns the session ID associated withthe connection. See Scalar functions on page 122 for moreinformation about the CURSESSIONID() system function.

INTEGER,NOT NULL

SESSION_ID

The date and time the session was established.DATETIME,NOT NULL

CONNECTED

The name of the schema map that the session is using.VARCHAR (128),NOT NULL

USERNAME

For internal use only.BOOLEANIS_ADMIN

For future use.BOOLEAN,NOT NULL

AUTOCOMMIT

The value for READONLY is True.BOOLEAN,NOT NULL

READONLY

For future use.INTEGER,NOT NULL

MAX_ROWS

For future use.BIGINT,NULLABLE

LAST_IDENTITY

For future use.INTEGER,NOT NULL

TRANSACTION_SIZE




The current schema for the session. The current schema maybe changed using the ALTER SESSION SETCURRENT_SCHEMA statement.

VARCHAR (128),NOT NULL

CURRENT_SCHEMA

The maximum number of Web service calls that the driveruses in attempting to execute a query to a remote data source.The statement call limit for the session may be changed viathe ALTER SESSION SET STMT_CALL_LIMIT statement.

INTEGER,NOT NULL

STMT_CALL_LIMIT

IdentifiersIdentifiers are used to refer to objects exposed by the driver, such as tables, columns, or caches. The driversupports both unquoted and quoted identifiers for naming objects. An unquoted identifier must start with anASCII alpha character and can be followed by zero or more ASCII alpha or numeric characters. Unquotedidentifiers are converted to uppercase before being used.

Quoted identifiers must be enclosed in double quotation marks (""). A quoted identifier can contain any Unicodecharacter, including the space character, and is case-sensitive. The Oracle Sales Cloud driver recognizes theUnicode escape sequence \uxxxx as a Unicode character. You can specify a double quotation mark in a quotedidentifier by escaping it with a double quotation mark.

The maximum length of both quoted and unquoted identifiers is 128 characters.

Note: When object names are passed as arguments to catalog functions, the case of the value must matchthe case of the name in the database. If an unquoted identifier name was used when the object was created,the value passed to the catalog function must be uppercase because unquoted identifiers are converted touppercase before being used. If a quoted identifier name was used when the object was created, the valuepassed to the catalog function must match the case of the name as it was defined. Object names in resultsreturned from catalog functions are returned in the case that they are stored in the database.

TimeoutsMost remote data sources impose a limit on the duration of active sessions, meaning a session can fail with asession timeout error if the session extends past the limit. The following scenarios show how the driver handlestimeouts.

Session timeoutsIf the driver receives a session timeout error from a data source, the driver automatically attempts to re-establisha new session. The driver uses the initial server name, port (if appropriate), remote user ID, and remotepassword (encrypted) to re-establish the session. If the attempt fails, the driver returns an error indicating thatthe session timed out and the attempt to re-establish the session failed.


Identifiers

Web service request timeoutsYou can configure the driver to never time out while waiting for a response to a Web service request or to waitfor a specified interval before timing out by setting the WSTimeout connection property for fetch requests.Additionally, in a case where requests might fail, you can configure the driver to retry the request a specifiednumber of times by setting theWSRetryCount connection property. If all subsequent attempts to retry a requestfail, the driver will return an error indicating that the service request timed out and that the subsequent requestsfailed.

See Using connection properties on page 31 and Web service properties on page 33 for details.

Scrollable cursorsThe driver supports scroll-insensitive result sets.

Note: When the driver cannot support the requested result set type or concurrency, it automatically downgradesthe cursor and generates one or more SQLWarnings with detailed information.

Parameter metadata supportThe driver supports returning parameter metadata for Select statements that contain parameters in ANSISQL-92 entry-level predicates, for example, such as COMPARISON, BETWEEN, IN, LIKE, and EXISTSpredicate constructs. Refer to the ANSI SQL reference for detailed syntax.

Parameter metadata can be returned for a Select statement if one of the following conditions is true:

• The statement contains a predicate value expression that can be targeted against the source tables in theassociated FROM clause. For example:

SELECT * FROM foo WHERE bar > ?

In this case, the value expression "bar" can be targeted against the table "foo" to determine the appropriatemetadata for the parameter.

• The statement contains a predicate value expression part that is a nested query. The nested query's metadatamust describe a single column. For example:

SELECT * FROM foo WHERE (SELECT x FROM y WHERE z = 1) < ?

The following Select statements show further examples for which parameter metadata can be returned:

SELECT col1, col2 FROM foo WHERE col1 = ? AND col2 > ?SELECT ... WHERE colname = (SELECT col2 FROM t2 WHERE col3 = ?)SELECT ... WHERE colname LIKE ?SELECT ... WHERE colname BETWEEN ? and ?SELECT ... WHERE colname IN (?, ?, ?)SELECT ... WHERE EXISTS(SELECT ... FROM T2 WHERE col1 < ?)

ANSI SQL-92 entry-level predicates in a WHERE clause containing GROUP BY, HAVING, or ORDER BYstatements are supported. For example:

SELECT * FROM t1 WHERE col = ? ORDER BY 1



Joins are supported. For example:

SELECT * FROM t1,t2 WHERE t1.col1 = ?

Fully qualified names and aliases are supported. For example:

SELECT a, b, c, d FROM T1 AS A, T2 AS B WHERE A.a = ? AND B.b = ?

ResultSet metadata supportIf your application requires table name information, the driver can return table name information in ResultSetmetadata for Select statements. The Select statements for which ResultSet metadata is returned may containaliases, joins, and fully qualified names. The following queries are examples of Select statements for whichthe ResultSetMetaData.getTableName() method returns the correct table name for columns in the Select list:

SELECT id, name FROM EmployeeSELECT E.id, E.name FROM Employee ESELECT E.id, E.name AS EmployeeName FROM Employee ESELECT E.id, E.name, I.location, I.phone FROM Employee E, EmployeeInfo I

WHERE E.id = I.idSELECT id, name, location, phone FROM Employee, EmployeeInfo WHERE id = empIdSELECT Employee.id, Employee.name, EmployeeInfo.location, EmployeeInfo.phone

FROM Employee, EmployeeInfo WHERE Employee.id = EmployeeInfo.id

The table name returned by the driver for generated columns is an empty string. The following query is anexample of a Select statement that returns a result set that contains a generated column (the column named"upper").

SELECT E.id, E.name as EmployeeName, {fn UCASE(E.name)} AS upper FROM Employee E

The driver also can return catalog name information when the ResultSetMetaData.getCatalogName() methodis called if the driver can determine that information. For example, for the following statement, the driver returns"test" for the catalog name and "foo" for the table name:

SELECT * FROM test.foo

The additional processing required to return table name and catalog name information is only performed if theResultSetMetaData.getTableName() or ResultSetMetaData.getCatalogName() methods are called.

Error handlingSQLExceptionsThe driver reports errors to the application by throwing SQLExceptions. Each SQLException contains thefollowing information:

• Description of the probable cause of the error, prefixed by the component that generated the error

• Native error code (if applicable)

• String containing the XOPEN SQLstate


ResultSet metadata support

Driver ErrorsAn error generated by the driver has the format shown in the following example:

[DataDirect][OracleSalesCloud JDBC Driver]Timeout expired.

You may need to check the last JDBC call your application made and refer to the JDBC specification for therecommended action.

Database ErrorsAn error generated by the database has the format shown in the following example:

[DataDirect][OracleSalesCloud JDBC Driver][OracleSalesCloud]Invalid Object Name.

If you need additional information, use the native error code to look up details in your database documentation.

Rowset supportThe driver supports any JSR 114 implementation of the RowSet interface, including:

• CachedRowSets

• FilteredRowSets

• WebRowSets

• JoinRowSets

• JDBCRowSets

Visit http://www.jcp.org/en/jsr/detail?id=114 for more information about JSR 114.

DataDirect TestUse DataDirect Test to test your JDBC applications and learn the JDBC API. DataDirect Test contains menuselections that correspond to specific JDBC functions, for example, connecting to a database or passing a SQLstatement. DataDirect Test allows you to perform the following tasks:

• Execute a single JDBC method or execute multiple JDBC methods simultaneously, so that you can easilyperform some common tasks, such as returning result sets

• Display the results of all JDBC function calls in one window, while displaying fully commented, JDBC codein an alternate window

DataDirect Test works only with JDBC drivers from Progress DataDirect.



http://www.jcp.org/en/jsr/detail?id=114

DataDirect Test TutorialThis DataDirect Test tutorial explains how to use the most important features of DataDirect Test (and the JDBCAPI) and assumes that you can connect to a database with the standard available demo table or fine-tune thesample SQL statements shown in this example as appropriate for your environment.

Note: The tutorial describes functionality across a spectrum of data stores. In some cases, the functionalitydescribed may not apply to the driver or data store you are using. Additionally, examples are drawn from avariety of drivers and data stores.

Note: The step-by-step examples used in this tutorial do not show typical clean-up routines (for example,closing result sets and connections). These steps have been omitted to simplify the examples. Do not forgetto add these steps when you use equivalent code in your applications.

Configuring DataDirect TestThe default DataDirect Test configuration file is:

install_dir/testforjdbc/Config.txt

where:

install_dir

is your product installation directory.

The DataDirect Test configuration file can be edited as appropriate for your environment using any text editor.All parameters are configurable, but the most commonly configured parameters are:

A list of colon-separated JDBC driver classes.Drivers

The default JDBC driver that appears in the Get Driver URL window.DefaultDriver

A list of comma-separated JDBC URLs. The first item in the list appears asthe default in theDatabase Selectionwindow. You can use one of these URLsas a template when you make a JDBC connection. The default Config.txt filecontains example URLs for most databases.

Databases

Set to com.sun.jndi.fscontext.RefFSContextFactory if you are usingfile system data sources, or com.sun.jndi.ldap.LdapCtxFactory if youare using LDAP.

InitialContextFactory

The location of the .bindings file if you are using file system data sources, oryour LDAP Provider URL if you are using LDAP.

ContextProviderURL

A list of comma-separated JDBC data sources. The first item in the list appearsas the default in the Data Source Selection window.

Datasources

To connect using a data source, DataDirect Test needs to access a JNDI data store to persist the data sourceinformation. By default, DataDirect Test is configured to use the JNDI File System Service Provider to persistthe data source. You can download the JNDI File System Service Provider from the Oracle Java PlatformTechnology Downloads page.

Make sure that the fscontext.jar and providerutil.jar files from the download are on your classpath.


DataDirect Test



Starting DataDirect TestHow you start DataDirect Test depends on your platform:

• As a Java application on Windows. Run the testforjdbc.bat file located in the testforjdbcsubdirectory of your product installation directory.

• As a Java application on Linux/UNIX. Run the testforjdbc.sh shell script located in the testforjdbcsubdirectory in the installation directory.

After you start DataDirect Test, the Test for JDBC Tool window appears.

The main Test for JDBC Tool window shows the following information:

• In the Connection List box, a list of available connections.

• In the JDBC/Database Output scroll box, a report indicating whether the last action succeeded or failed.

• In the Java Code scroll box, the actual Java code used to implement the last action.

Tip: DataDirect Test windows contain two Concatenate check boxes. Select a Concatenate check box tosee a cumulative record of previous actions; otherwise, only the last action is shown. Selecting Concatenatecan degrade performance, particularly when displaying large result sets.

Connecting Using DataDirect TestYou can use either of the following methods to connect using DataDirect Test:

• Using a data source

• Using a driver/database selection



Connecting Using a Data SourceTo connect using a data source, DataDirect Test needs to access a JNDI data store to persist the data sourceinformation. By default, DataDirect Test is configured to use the JNDI File System Service Provider to persistthe data source. You can download the JNDI File System Service Provider from the Oracle Java PlatformTechnology Downloads page.

Make sure that the fscontext.jar and providerutil.jar files from the download are on your classpath.

To connect using a data source:

1. From the main Test for JDBC Tool window menu, select Connection / Connect to DB via Data Source.The Select A Datasource window appears.

2. Select a data source from the Defined Datasources pane. In the User Name and Password fields, typevalues for the User and Password connection properties; then, click Connect. For information about JDBCconnection properties, refer to your driver's connection property descriptions.

3. If the connection was successful, the Connection window appears and shows the ConnectionEstablished message in the JDBC/Database Output scroll box.

Connecting Using Database SelectionTo connect using database selection:


DataDirect Test



1. From the Test for JDBC Tool window menu, select Driver / Register Driver. DataDirect Test prompts fora JDBC driver name.

2. In the Please Supply a Driver URL field, specify a driver (for examplecom.ddtek.jdbc.sqlserver.SQLServerDriver); then, click OK.

If the driver was registered successfully, the Test for JDBC Tool window appears with a confirmation inthe JDBC/Database Output scroll box.

3. From the Test for JDBC Tool window, select Connection / Connect to DB. The Select A Databasewindow appears with a list of default connection URLs.

4. Select one of the default driver connection URLs. In the Database field, modify the default values of theconnection URL appropriately for your environment.

Note: There are two entries for DB2: one with locationName and another with databaseName. If you areconnecting to DB2 for Linux/UNIX/Windows, select the entry containing databaseName. If you are connectingto DB2 for z/OS or DB2 for i, select the entry containing locationName.

5. In the User Name and Password fields, type the values for the User and Password connection properties;then, click Connect. For information about JDBC connection properties, refer to your driver's connectionproperty descriptions.

6. If the connection was successful, the Connection window appears and shows the ConnectionEstablished message in the JDBC/Database Output scroll box.



Executing a Simple Select StatementThis example explains how to execute a simple Select statement and return the results.

To Execute a Simple Select Statement:

1. From the Connection window menu, select Connection / Create Statement. The Connection windowindicates that the creation of the statement was successful.

2. Select Statement / Execute Stmt Query. DataDirect Test displays a dialog box that prompts for a SQLstatement.

3. Type a Select statement and click Submit. Then, click Close.

4. Select Results / Show All Results. The data from your result set displays in the JDBC/Database Outputscroll box.


DataDirect Test

5. Scroll through the code in the Java Code scroll box to see which JDBC calls have been implemented byDataDirect Test.

Executing a Prepared StatementThis example explains how to execute a parameterized statement multiple times.

To Execute a Prepared Statement:

1. From the Connection window menu, select Connection / Create Prepared Statement. DataDirect Testprompts you for a SQL statement.

2. Type an Insert statement and click Submit. Then, click Close.

3. Select Statement / Set Prepared Parameters. To set the value and type for each parameter:



a) Type the parameter number.

b) Select the parameter type.

c) Type the parameter value.

d) Click Set to pass this information to the JDBC driver.

4. When you are finished, click Close.

5. Select Statement / Execute Stmt Update. The JDBC/Database Output scroll box indicates that one rowhas been inserted.


DataDirect Test

6. If you want to insert multiple records, repeat Step 3 on page 46 and Step 5 on page 47 for each record.

7. If you repeat the steps described in Executing a Simple Select Statement on page 45, you will see that thepreviously inserted records are also returned.



Retrieving Database Metadata1. From the Connection window menu, select Connection / Get DB Meta Data.

2. SelectMetaData / Show Meta Data. Information about the JDBC driver and the database to which you areconnected is returned.


DataDirect Test

3. Scroll through the Java code in the Java Code scroll box to find out which JDBC calls have been implementedby DataDirect Test.

Metadata also allows you to query the database catalog (enumerate the tables in the database, for example).In this example, we will query all tables with the schema pattern test01.

4. Select MetaData / Tables.

5. In the Schema Pattern field, type test01.

6. Click Ok. The Connection window indicates that getTables() succeeded.

7. Select Results / Show All Results. All tables with a test01 schema pattern are returned.



Scrolling Through a Result Set1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement. DataDirect Test

prompts for a result set type and concurrency.

2. Complete the following fields:

a) In the resultSetType field, select TYPE_SCROLL_SENSITIVE.

b) In the resultSetConcurrency field, select CONCUR_READ_ONLY.

c) Click Submit; then, click Close.

3. Select Statement / Execute Stmt Query.

4. Type a Select statement and click Submit. Then, click Close.


DataDirect Test

5. Select Results / Scroll Results. The Scroll Result Set window indicates that the cursor is positionedbefore the first row.

6. Click the Absolute, Relative, Before, First, Prev, Next, Last, and After buttons as appropriate to navigatethrough the result set. After each action, the Scroll Result Set window displays the data at the currentposition of the cursor.



7. Click Close.

Batch Execution on a Prepared StatementBatch execution on a prepared statement allows you to update or insert multiple records simultaneously. Insome cases, this can significantly improve system performance because fewer round trips to the database arerequired.

To Execute a Batch on a Prepared Statement:

1. From the Connection window menu, select Connection / Create Prepared Statement.

Type an Insert statement and click Submit. Then, click Close.

2. Select Statement / Add Stmt Batch.

3. For each parameter:

a) Type the parameter number.

b) Select the parameter type.

c) Type the parameter value.

d) Click Set.


DataDirect Test

4. Click Add to add the specified set of parameters to the batch. To add multiple parameter sets to the batch,repeat Step 2 on page 53 through Step 4 on page 54 as many times as necessary. When you are finishedadding parameter sets to the batch, click Close.

5. Select Statement / Execute Stmt Batch. DataDirect Test displays the rowcount for each of the elementsin the batch.

6. If you re-execute the Select statement from Executing a Simple Select Statement on page 45, you see thatthe previously inserted records are returned.



Returning ParameterMetaData

Note: Returning ParameterMetaData requires a Java SE 5 or higher JVM.

1. From the Connection window menu, select Connection / Create Prepared Statement.

Type the prepared statement and click Submit. Then, click Close.

2. Select Statement / Get ParameterMetaData. The Connection window displays ParameterMetaData.


DataDirect Test

Establishing Savepoints

Note: Savepoints require a Java SE 5 or higher JVM.

1. From the Connection window menu, select Connection / Connection Properties.

2. Select TRANSACTION_COMMITTED from the Transaction Isolation drop-down list. Do not select the AutoCommit check box.

3. Click Set; then, click Close.

4. From the Connection window menu, select Connection / Load and Go. The Get Load And Go SQLwindow appears.

5. Type a statement and click Submit.



6. Select Connection / Set Savepoint.

7. In the Set Savepoints window, type a savepoint name.

8. Click Apply; then, click Close. The Connection window indicates whether or not the savepoint succeeded.

9. Return to the Get Load And Go SQL window and specify another statement. Click Submit.


DataDirect Test

10. Select Connection / Rollback Savepoint. In the Rollback Savepoints window, specify the savepointname.

11. Click Apply; then, click Close. The Connection window indicates whether or not the savepoint rollbacksucceeded.

12. Return to the Get Load And Go SQL window and specify another statement.



ClickSubmit; then, clickClose. TheConnectionwindow displays the data inserted before the first Savepoint.The second insert was rolled back.

Updatable Result SetsThe following examples explain the concept of updatable result sets by deleting, inserting, and updating a row.

Deleting a Row

1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement.



b) In the resultSetConcurrency field, select CONCUR_UPDATABLE.


DataDirect Test

3. Click Submit; then, click Close.


5. Specify the Select statement and click Submit. Then, click Close.

6. Select Results / Inspect Results. The Inspect Result Set window appears.



7. Click Next. Current Row changes to 1.

8. Click Delete Row.

9. To verify the result, return to the Connection menu and select Connection / Load and Go. The Get LoadAnd Go SQL window appears.

10. Specify the statement that you want to execute and click Submit. Then, click Close.


DataDirect Test

11. The Connection window shows that the row has been deleted.

Inserting a Row









5. Specify the Select statement that you want to execute and click Submit. Then, click Close.



DataDirect Test

7. Click Move to insert row; Current Row is now Insert row.

8. Change Data Type to int. In Set Cell Value, enter 20. Click Set Cell.

9. Select the second row in the top pane. Change the Data Type to String. In Set Cell Value, enter RESEARCH.Click Set Cell.

10. Select the third row in the top pane. In Set Cell Value, enter DALLAS. Click Set Cell.

11. Click Insert Row.


13. Specify the statement that you want to execute and click Submit. Then, click Close.



14. The Connection window shows the newly inserted row.

Caution: The ID will be 3 for the row you just inserted because it is an auto increment column.

Updating a Row






DataDirect Test



5. Specify the Select statement that you want to execute.






9. In Set Cell Value, type RALEIGH. Then, click Set Cell.

10. Click Update Row.


12. Specify the statement that you want to execute.


DataDirect Test


14. The Connection window shows LOC for accounting changed from NEW YORK to RALEIGH.

Retrieving Large Object Data

Note: LOB support (Blobs and Clobs) requires a Java SE 5 or higher JVM.

The following example uses Clob data; however, this procedure also applies to Blob data. This exampleillustrates only one of multiple ways in which LOB data can be processed.

1. From the Connection window menu, select Connection / Create Statement.


3. Specify the Select statement that you want to execute.






7. Deselect Auto Traverse. This disables automatic traversal to the next row.


DataDirect Test

8. Click Get Cell. Values are returned in the Get Cell Value field.

9. Change the data type to Clob.



10. Click Get Cell. The Clob data window appears.


DataDirect Test

11. Click Get Cell. Values are returned in the Cell Value field.



Tracking JDBC calls with DataDirect SpyDataDirect Spy is functionality that is built into the drivers. It is used to log detailed information about calls yourdriver makes and provide information you can use for troubleshooting. DataDirect Spy provides the followingadvantages:

• Logging is JDBC 4.0-compliant.

• All parameters and function results for JDBC calls can be logged.

• Logging can be enabled without changing the application.

When you enable DataDirect Spy for a connection, you can customize logging by setting one or multiple optionsfor DataDirect Spy. For example, you may want to direct logging to a local file on your machine.

Once logging is enabled for a connection, you can turn it on and off at runtime using the setEnableLogging()method in the com.ddtek.jdbc.extensions.ExtLogControl interface. See "Troubleshooting Your Application" forinformation about using a DataDirect Spy log for troubleshooting.

See alsoTroubleshooting your application on page 91

Enabling DataDirect SpyYou can enable and customize DataDirect Spy logging in either of the following ways.

• Specifying the SpyAttributes connection property for connections using the JDBC DriverManager.

• Specifying DataDirect Spy attributes using a JDBC DataSource.

Using the DriverManagerThe SpyAttributes connection property allows you to specify a semi-colon separated list of DataDirect Spyattributes. The format for the value of the SpyAttributes property is:

(spy_attribute[;spy_attribute]...)

where spy_attribute is any valid DataDirect Spy attribute.

Windows exampleClass.forName("com.ddtek.jdbc.oraclesalescloud.OracleSalesCloudDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:oraclesalescloud://mysite.custhelp.com;[email protected];Password=secret;SpyAttributes=(log=(filePrefix)C:\\temp\\spy_;linelimit=80;logTName=yes;timestamp=yes)");

Note: If coding a path on Windows to the log file in a Java string, the backslash character (\) must be precededby the Java escape character, a backslash. For example: log=(filePrefix)C:\\temp\\spy_.


Tracking JDBC calls with DataDirect Spy

Using this example, DataDirect Spy loads the driver and logs all JDBC activity to the spy_x.log file locatedin the C:\temp directory (log=(filePrefix)C:\\temp\\spy_), where x is an integer that increments by1 for each connection on which the prefix is specified. The spy_x.log file logs a maximum of 80 characterson each line (linelimit=80) and includes the name of the current thread (logTName=yes) and a timestampon each line in the log (timestamp=yes).

UNIX exampleClass.forName("com.ddtek.jdbc.oraclesalescloud.OracleSalesCloudDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:oraclesalescloud://mysite.custhelp.com;[email protected];Password=secret;SpyAttributes=(log=(filePrefix)/tmp/spy_;logTName=yes;timestamp=yes)");

Using this example, DataDirect Spy loads the driver and logs all JDBC activity to the spy_x.log file locatedin the /tmp directory (log=(filePrefix)/tmp/spy_), where x is an integer that increments by 1 foreach connection on which the prefix is specified. The spy_x.log file includes the name of the current thread(logTName=yes) and a timestamp on each line in the log (timestamp=yes).

See alsoDataDirect Spy attributes on page 75SpyAttributes on page 87

Using data sourcesYou can use DataDirect Spy to track JDBC calls made by running an application with JNDI for NamingDatabases.

The com.ddtek.jdbcx.oraclesalescloud.OracleSalesCloudDataSource class supports setting asemi-colon-separated list of DataDirect Spy attributes.

Windows exampleOracleSalesCloudDataSource sds=new OracleSalesCloudDataSource():sds.setServerName("mysite.custhelp.com");sds.setSpyAttributes("log=(file)C:\\temp\\spy.log;logIS=yes;logTName=yes");Connection conn=sds.getConnection("TEST","secret");...

Note: If coding a path on Windows to the log file in a Java string, the backslash character (\) must be precededby the Java escape character, a backslash. For example:log=(file)C:\\temp\\spy.log;logIS=yes;logTName=yes.

Using this example, DataDirect Spy would load the driver and log all JDBC activity to the spy.log file locatedin the C:\temp directory (log=(file)C:\\temp\\spy.log). In addition to regular JDBC activity, thespy.log file also logs activity on InputStream and Reader objects (logIS=yes). It also includes the name ofthe current thread (logTName=yes).

UNIX exampleOracleSalesCloudDataSource mds = new OracleSalesCloudDataSource();mds.setServerName("mysite.custhelp.com");mds.setSpyAttributes("log=(file)/tmp/spy.log;logTName=yes");Connection conn=mds.getConnection("TEST","secret");...



Using this example, DataDirect Spy would load the driver and log all JDBC activity to the spy.log file locatedin the /tmp directory (log=(file)/tmp/spy.log). The spy.log file includes the name of the current thread(logTName=yes).

See alsoDataDirect Spy attributes on page 75SpyAttributes on page 87

DataDirect Spy attributesDataDirect Spy supports the attributes described in the following table.

Table 10: DataDirect Spy attributes

DescriptionAttribute

Sets the maximum number of characters that DataDirect Spy logs on a single line.

The default is 0 (no maximum limit).

linelimit=numberofchars

Loads the driver specified by classname.load=classname

Directs logging to the file specified by filename.

log=(file)C:\\temp\\spy.log;logIS=yes;logTName=yes.

log=(file)filename

Directs logging to a file prefixed by file_prefix. The log file is named ForWindows, if coding a path to the log file in a Java string, the backslash character(\) must be preceded by the Java escape character, a backslash. For example:file_prefixX.log

where:

X

For Windows, if coding a path to the log file inis an integer that incrementsby 1 for each connection on which the prefix is specified.

For example, if the attribute log=(filePrefix) C:\\temp\\spy_ is specifiedon multiple connections, the following logs are created:

C:\temp\spy_1.logC:\temp\spy_2.logC:\temp\spy_3.log...

If coding a path to the log file in a Java string, the backslash character (\) must bepreceded by the Java escape character, a backslash. For example:log=(filePrefix)C:\\temp\\spy_;logIS=yes;logTName=yes.

log=(filePrefix)file_prefix

Directs logging to the Java output standard, System.out.log=System.out


Tracking JDBC calls with DataDirect Spy

DescriptionAttribute

Specifies whether DataDirect Spy logs activity on InputStream and Readerobjects.

When logIS=nosingleread, logging on InputStream and Reader objects isactive; however, logging of the single-byte read InputStream.read orsingle-character Reader.read is suppressed to prevent generating large log filesthat contain single-byte or single character read messages.

The default is no.

logIS={yes | no |nosingleread}

Specifies whether DataDirect Spy logs activity on BLOB and CLOB objects.logLobs={yes | no}

Specifies whether DataDirect Spy logs the name of the current thread.

The default is no.

logTName={yes | no}

Specifies whether a timestamp is included on each line of the DataDirect Spy log.The default is no.

timestamp={yes | no}

See alsoSpyAttributes on page 87



4Connection property descriptions

You can use connection properties to customize the driver for your environment. This section lists the connectionproperties supported by the driver and describes each property. You can use these connection properties witheither the JDBC Driver Manager or a JDBC data source. For a Driver Manager connection, a property isexpressed as a key value pair and takes the form property=value. For a data source connection, a propertyis expressed as a JDBC method and takes the form setproperty(value). Connection property names arecase-insensitive. For example, Password is the same as password.

Note: In a JDBC DataSource, string values must be enclosed in double quotation marks, for example,setUser("[email protected]").

Note: The data type listed in each of the connection property descriptions is the Java data type used for theproperty value in a JDBC data source.

The following table provides a summary of the connection properties supported by the driver, their correspondingdata source methods, and their default values.

Table 11: Driver Properties

Default ValueData Source MethodConnection String Property

APIVersion=latestsetConfigOptionsConfigOptions on page 79

notExistsetCreateMapCreateMap on page 80

No default valuesetPasswordPassword on page 81

No default valuesetProxyHostProxyHost on page 82


Default ValueData Source MethodConnection String Property

No default valuesetProxyPasswordProxyPassword on page 83

No default valuesetProxyPortProxyPort on page 83

No default valuesetProxyUserProxyUser on page 84

For Windows:

application_data_folder\Local\Progress\DataDirect\Oracle_Sales_Cloud_Schema\user_name.config

For UNIX/Linux:

˜/progress/datadirect/oracle_sales_cloud_schema/user_name.config

setSchemaMapSchemaMap on page 85

No default valuesetServerNameServerName on page 86

No default valuesetSpyAttributesSpyAttributes on page 87

No default valuesetUserUser on page 88

100 (rows)setWSFetchSizeWSFetchSize on page 88

0setWSRetryCountWSRetryCount on page 89

120 (seconds)setWSTimeoutWSTimeout on page 90


• ConfigOptions

• CreateMap

• Password

• ProxyHost

• ProxyPassword

• ProxyPort

• ProxyUser

• SchemaMap

• ServerName

• SpyAttributes

• User

• WSFetchSize


Chapter 4: Connection property descriptions

• WSRetryCount

• WSTimeout

ConfigOptionsPurposeAllows you to specify which version of the Oracle Sales Cloud API is being used in your environment with theAPIVersion configuration option.

Valid Values("key=value")

where

key

is the APIVersion configuration option.

value

specifies a setting for the APIVersion configuration option.

The key value pair must be enclosed in quotation marks and then in parentheses. For example:

ConfigOptions=("APIVersion=11.1.11")

Similarly, when specifying configuration options using a DataSourcemethod, key value pairs must be enclosedin quotation marks. For example:

setConfigOptions("APIVersion=11.1.11")

Data Source MethodsetConfigOptions

DefaultAPIVersion=latest

Data TypeString

See alsoMapping objects to tables on page 15Mapping properties on page 32CreateMap on page 80SchemaMap on page 85


ConfigOptions

APIVersion (configuration option)

PurposeIdentifies the version of Oracle Sales Cloud used in your environment.

Valid Valueslatest | MM.mm.ss

where

latest

is the latest version of Oracle Sales Cloud supported by the driver. When set to latest, the driverassumes the latest version of Oracle Sales Cloud is being used. This is the default setting.

MM.mm.ss

is the version of Oracle Sales Cloud used in your environment where MM is the major version number,mm is the minor version number, and ss is the service pack number. For example, 11.1.11.

Defaultlatest

Data TypeString

CreateMapPurposeDetermines whether the driver creates the internal files required for a relational map of the native data whenestablishing a connection.

Valid ValuesforceNew | no | notExist

BehaviorIf set to forceNew, the driver deletes the group of internal files specified by SchemaMap and creates a newgroup of these files at the same location.

If set to no, the driver uses the current group of internal files specified by SchemaMap. If the files do not exist,the connection fails.

If set to notExist, the driver uses the current group of internal files specified by SchemaMap. If the files donot exist, the driver creates them.



Notes• The internal files share the same directory as the schemamap's configuration file. This directory is specified

with the SchemaMap connection property.

• You can refresh the internal files related to an existing relational view of your data with the SQL extensionRefresh Map. Refresh Map runs a discovery against your native data and updates your internal filesaccordingly.

Data Source MethodsetCreateMap

DefaultnotExist

Data TypeString

See alsoMapping objects to tables on page 15Mapping properties on page 32ConfigOptions on page 79SchemaMap on page 85

PasswordDescriptionSpecifies the password used to connect to your Oracle Sales Cloud instance for user ID/password authentication.

Important: Setting the password using a data source is not recommended. The data source persists allproperties, including Password, in clear text.

Valid Valuespassword

where:

password

is a valid password. The password is case-sensitive.

Data Source MethodsetPassword

DefaultNo default value


Password

Data TypeString

See alsoRequired properties on page 32ServerName on page 86User on page 88

ProxyHostDescriptionIdentifies a proxy server.

Valid Valuesserver_name | IP_address

where:

server_name

is the name of the proxy server, which may be qualified with the domain name.

IP_address

is an IP address, specified in either IPv4 or IPv6 format, or a combination of the two.

Data Source MethodsetProxyHost


Data TypeString

See alsoProxy server properties on page 33ProxyPassword on page 83ProxyPort on page 83ProxyUser on page 84



ProxyPasswordPurposeSpecifies the password needed to connect to a proxy server.

Valid Valuespassword

where:

password

is a valid password for that server. Contact your system administrator to obtain a valid password.

Data Source MethodsetProxyPassword


Data TypeString

See alsoProxy server properties on page 33ProxyHost on page 82ProxyPort on page 83ProxyUser on page 84

ProxyPortPurposeSpecifies the port number where the proxy server is listening for HTTP or HTTPS requests.

Valid Valuesport

where:

port

is the port number on which the proxy server is listening. Contact your system administrator to obtainthe correct port.


ProxyPassword

Data Source MethodsetProxyPort

Default0

Data TypeInt

See alsoProxy server properties on page 33ProxyHost on page 82ProxyPassword on page 83ProxyUser on page 84

ProxyUserPurposeSpecifies the user name needed to connect to a proxy server.

Valid Valuesuser_name

where:

user_name

is a valid user ID for the proxy server.

Data Source MethodsetProxyUser


Data TypeString

See alsoProxy server properties on page 33ProxyHost on page 82ProxyPassword on page 83ProxyPort on page 83



SchemaMapPurposeSpecifies the name and location of the configuration file used to create the relational map of native data. Thedriver looks for this file when connecting to an Oracle Sales Cloud instance. By default, if the file does not exist,the driver creates one.

Valid Valuesstring

where:

string

is the absolute path and filename of the configuration file, including the .config extension. Forexample, if SchemaMap is set to a value ofC:\\Users\\Default\\AppData\\Local\\Progress\\DataDirect\\Oracle_Sales_Cloud_Schema\\testuser.config,the driver either creates or looks for the configuration file testuser.config in the directoryC:\Users\Default\AppData\Local\Progress\DataDirect\Oracle_Sales_Cloud_Schema\.

Notes• When connecting to a server, the driver looks for the SchemaMap configuration file. If the configuration file

does not exist, the driver creates a SchemaMap configuration file using the name and location you haveprovided. If you do not provide a name and location for a SchemaMap configuration file, the driver createsit using default values.

• The driver uses the path specified in this connection property to store additional internal files.

• You can refresh the internal files related to an existing relational view of your data by using the SQL extensionRefresh Map. Refresh Map runs a discovery against your native data and updates your internal filesaccordingly.

ExampleAs the following examples show, escapes are needed when specifying SchemaMap for a DataSource butare not used when specifying SchemaMap in a DriverManager connection URL.

DriverManager example

jdbc:datadirect:oraclesalescloud://mysite.custhelp.com;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect

\Oracle_Sales_Cloud_Schema\testuser.config

DataSource example

OracleSalesCloudDataSource mds = new OracleSalesCloudDataSource();mds.setDescription("My OracleSalesCloudDataSource");mds.setServerName("mysite.custhelp.com");mds.setSchemaMap("C:\\Users\\Default\\AppData\\Local\\Progress

\\DataDirect\\Oracle_Sales_Cloud_Schema\\testuser.config")

Data Source MethodsetSchemaMap


SchemaMap

Default• For Windows XP and Windows Server 2003

• userprofile\ApplicationData\Local\Progress\DataDirect\Oracle_Sales_Cloud_Schema\user_name.config

• For other Windows platforms

• User data source:userprofile\AppData\Local\Progress\DataDirect\Oracle_Sales_Cloud_Schema\user_name.config

• System data source:C:\Users\Default\AppData\Local\Progress\DataDirect\Oracle_Sales_Cloud_Schema\user_name.config

• For UNIX/Linux

• ˜/progress/datadirect/Oracle_Sales_Cloud_Schema/user_name.config

Data TypeString

See alsoMapping objects to tables on page 15Mapping properties on page 32ConfigOptions on page 79CreateMap on page 80

ServerNamePurposeSpecifies the base URL of the Oracle Sales Cloud instance to which the driver is connecting.

Valid Valuesbase_url

where:

base_url

is the base URL of the Oracle Sales Cloud instance to which you are connecting, for example,mysite.custhelp.com. This value should not include an internet protocol such as http:// orhttps://.

Data Source MethodsetServerName




Data TypeString

See alsoRequired properties on page 32Password on page 81User on page 88

SpyAttributesPurposeEnables DataDirect Spy to log detailed information about calls that are issued by the driver on behalf of theapplication. DataDirect Spy is not enabled by default.

Valid Values( spy_attribute [; spy_attribute ]...)

where:

spy_attribute

is any valid DataDirect Spy attribute. See DataDirect Spy attributes on page 75 for a list of supportedattributes.

NotesIf coding a path on Windows to the log file in a Java string, the backslash character (\) must be preceded bythe Java escape character, a backslash. For example: log=(file)C:\\temp\\spy.log.

ExampleThe following value instructs the driver to log all JDBC activity to a file using a maximum of 80 characters foreach line.

(log=(file)/tmp/spy.log;linelimit=80)

Data Source MethodsetSpyAttributes


Data TypeString

See alsoTracking JDBC calls with DataDirect Spy on page 73DataDirect Spy attributes on page 75


SpyAttributes

UserPurposeSpecifies the user ID used to connect to your Oracle Sales Cloud instance for user ID/password authentication.

Valid Valuesuserid

where:

userid

is a valid user ID used to connect to your Oracle Sales Cloud instance.

Data Source MethodsetUser


Data TypeString

See alsoRequired properties on page 32Password on page 81ServerName on page 86

WSFetchSizePurposeSpecifies the maximum number of rows of data the driver can attempt to fetch for each call.

Valid Valuesx

where

x

is a positive integer from 1 to 100 that defines the maximum number of rows the driver can attemptto fetch for each call.



Data Source MethodsetWSFetchSize

Default100 (rows)

Data TypeInt

See alsoWeb service properties on page 33WSRetryCount on page 89WSTimeout on page 90

WSRetryCountDescriptionSpecifies the number of times the driver retries a timed-out Select request. The timeout period is specified bythe WSTimeout connection property.

Valid Values0 | x

where:

x

is a positive integer.

BehaviorIf set to 0, the driver does not retry timed-out requests after the initial unsuccessful attempt.

If set to x, the driver retries the timed-out request the specified number of times.

Data Source MethodsetWSRetryCount

Default0

Data TypeInt

See alsoWeb service properties on page 33


WSRetryCount

WSFetchSize on page 88WSTimeout on page 90

WSTimeoutPurposeSpecifies the time, in seconds, that the driver waits for a response to a web service request.

Valid Values0 | x

where:

x

is a positive integer that defines the number of seconds the driver waits for a response to a webservice request.

BehaviorIf set to 0, the driver waits indefinitely for a response; there is no timeout.

If set to x, the driver uses the value as the default timeout for any statement created by the connection. If aSelect request times out and WSRetryCount is set to retry timed-out requests, the driver retries the requestthe specified number of times.

Data Source MethodsetWSTimeout

Default120 (seconds)

Data TypeInt

See alsoWeb service properties on page 33WSFetchSize on page 88WSRetryCount on page 89



5Troubleshooting

This section provides information that can help you troubleshoot problems when they occur.


• Troubleshooting your application

• Using Java logging

• Contacting Technical Support

Troubleshooting your applicationTo help you troubleshoot any problems that occur with your application, you can use DataDirect Spy to logdetailed information about calls issued by the drivers on behalf of your application. When you enable DataDirectSpy for a connection, you can customize DataDirect Spy logging by setting one or multiple options. See "TrackingJDBC Calls with DataDirect Spy" for information about using DataDirect Spy and instructions on enabling andcustomizing logging.

See alsoTracking JDBC calls with DataDirect Spy on page 73


Turning on and off DataDirect Spy loggingOnce DataDirect Spy logging is enabled for a connection, you can turn on and off the logging at runtime usingthe setEnableLogging() method in the com.ddtek.jdbc.extensions.ExtLogControl interface.When DataDirect Spy logging is enabled, all Connection objects returned to an application provide animplementation of the ExtLogControl interface.

The code shows how to turn off logging using setEnableLogging(false).

import com.ddtek.jdbc.extensions.*

// Get Database ConnectionConnection con = DriverManager.getConnection

("jdbc:datadirect:oraclesalescloud://mysite.custhelp.com;User=TEST;Password=secret;SpyAttributes=(log=(file)/tmp/spy.log");

((ExtLogControl) con).setEnableLogging(false);...

The setEnableLogging()method only turns on and off logging if DataDirect Spy logging has already beenenabled for a connection; it does not set or change DataDirect Spy attributes. See "Enabling DataDirect Spy"for information about enabling and customizing DataDirect Spy logging.

See alsoEnabling DataDirect Spy on page 73

Using Java loggingThe driver provides a flexible and comprehensive logging mechanism that allows logging to be incorporatedseamlessly with the logging of your own application or allows logging to be enabled and configured independentlyfrom the application. The logging mechanism can be instrumental in investigating and diagnosing issues. Italso provides valuable insight into the type and number of operations requested by the application from thedriver and requested by the driver from the remote data source. This information can help you tune and optimizeyour application.

Logging componentsThe driver uses the Java Logging API to configure the loggers (individual logging components) used by thedriver. The Java Logging API is built into the JVM.

The Java Logging API allows applications or components to define one or more named loggers. Messageswritten to the loggers can be given different levels of importance. For example, errors that occur in the drivercan be written to a logger at the CONFIG level, while progress or flow information may be written to a loggerat the FINE or FINER level. Each logger used by the driver can be configured independently. The configurationfor a logger includes what level of log messages are written, the location to which they are written, and theformat of the log message.

The Java Logging API defines the following levels:

• SEVERE

• WARNING


Chapter 5: Troubleshooting

• INFO

• CONFIG

• FINE

• FINER

• FINEST

Note: Log messages logged by the driver only use the CONFIG, FINE, FINER, and FINEST logging levels.

Setting the log threshold of a logger to a particular level causes the logger to write log messages of that leveland higher to the log. For example, if the threshold is set to FINE, the logger writes messages of levels FINE,CONFIG, INFO, WARNING, and SEVERE to its log. Messages of level FINER or FINEST are not written tothe log.

The driver exposes loggers for the following functional areas:

• JDBC API

• SQL engine

• Web service

JDBC API logger

Namedatadirect.jdbc.cloud.level

PurposeLogs the JDBC calls made by the application to the driver and the responses from the driver back to theapplication. DataDirect Spy is used to log the JDBC calls.

Message LevelsFINER - Calls to the JDBC methods are logged at the FINER level. The value of all input parameters passedto these methods and the return values passed from them are also logged, except that input parameter orresult data contained in InputStream, Reader, Blob, or Clob objects are not written at this level.

FINEST - In addition to the same information logged by the FINER level, input parameter values and returnvalues contained in InputStream, Reader, Blob and Clob objects are written at this level.

OFF - Calls to the JDBC methods are not logged.

SQL Engine logger

Namedatadirect.cloud.sql.level


Using Java logging

PurposeLogs the operations that the SQL engine performs while executing a query. Operations include preparing astatement to be executed, executing the statement, and (if needed) fetching the data. These are internaloperations that do not necessarily directly correlate calls made to the data source.

Message LevelsCONFIG - Any errors or warnings detected by the SQL engine are written at this level.

FINE - In addition to the same information logged by the CONFIG level, SQL engine operations are logged atthis level. In particular, the SQL statement that is being executed is written at this level.

FINER - In addition to the same information logged by the CONFIG and FINE levels, data sent or received inthe process of performing an operation is written at this level.

Web service adapter logger

Namedatadirect.cloud.adapter.level

PurposeLogs the web service calls the driver makes to the remote data source and the responses it receives from theremote data source.

Message LevelsCONFIG - Any errors or warnings detected by the web service adapter are written at this level.

FINE - In addition to the same information logged by the CONFIG level, information about web service callsmade by the web service adapter and responses received by the web service adapter are written at this level.In particular, the web service calls made to execute the query and the calls to fetch or send the data are logged.The log entries for the calls to execute the query include the Oracle Sales Cloud-specific query being executed.The actual data sent or fetched is not written at this level.

FINER - In addition to the same information logged by the CONFIG and FINE levels, this level provides additionalinformation.

FINEST - In addition to the same information logged by the CONFIG, FINE, and FINER levels, data associatedwith the web service calls made by the web service adapter is written.

Using the JVM for loggingYou can configure logging using the properties file that is shipped with your JVM. To configure JVM logging,use a text editor to modify the properties file in your JVM. Typically, this file is named logging.properties andis located in the JRE/lib subdirectory of your JVM. The JRE looks for this file when it is loading.

You can also specify which properties file to use by setting the java.util.logging.config.file systemproperty. At a command prompt, enter:

java -Djava.util.logging.config.file=properties_file

where:

properties_file

is the name of the properties file you want to load.



Contacting Technical SupportProgress DataDirect offers a variety of options to meet your support needs. Please visit our Web site for moredetails and for contact information:


The Progress DataDirect Web site provides the latest support information through our global service network.The SupportLink program provides access to support contact details, tools, patches, and valuable information,including a list of FAQs for each product. In addition, you can search our Knowledgebase for technical bulletinsand other information.

When you contact us for assistance, please provide the following information:

• Your number or the serial number that corresponds to the product for which you are seeking support, or acase number if you have been provided one for your issue. If you do not have a SupportLink contract, theSupportLink representative assisting you will connect you with our Sales team.

• Your name, phone number, email address, and organization. For a first-time call, you may be asked for fullinformation, including location.

• The Progress DataDirect product and the version that you are using.

• The type and version of the operating system where you have installed your product.

• Any database, database version, third-party software, or other environment information required to understandthe problem.

• A brief description of the problem, including, but not limited to, any error messages you have received, whatsteps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and soon. Depending on the complexity of the problem, you may be asked to submit an example or reproducibleapplication so that the issue can be re-created.

• A description of what you have attempted to resolve the issue. If you have researched your issue on Websearch engines, our Knowledgebase, or have tested additional configurations, applications, or other vendorproducts, you will want to carefully note everything you have already attempted.

• A simple assessment of how the severity of the issue is impacting your organization.


Contacting Technical Support




6Supported SQL functionality

The driver provides support for SQL statements and extensions described in this section. SQL extensions aredenoted by an (EXT) in the topic title.


• Alter Session (EXT)

• Refresh Map (EXT)

• Select

• SQL expressions

• Subqueries

Alter Session (EXT)PurposeThe Alter Session statement allows you to change various attributes of a connection session.

SyntaxALTER SESSION SET attribute_name=value

where:


attribute_name

Specifies the name of the attribute to be changed.

value

Refers to the specific value setting for that attribute.

The following table lists session attributes and describes them.

Table 12: Alter Session Attributes

DescriptionSession TypeAttribute Name

Sets the current schema for the database session. The currentschema is the schema used when an identifier in a SQL statementis unqualified. The string value must be the name of a schema visiblein the session. For example:

ALTER SESSION SET CURRENT_SCHEMA=oraclesalescloud

DatabaseCurrent_Schema

Sets the maximum number of Web service calls the driver can makein executing a statement. Setting the Stmt_Call_Limit attributehas the same effect as setting the StmtCallLimit connectionoption. It sets the default Web service call limit used by any statementon the connection. Executing this command on a statement overridesthe previously set StmtCallLimit for the connection. The valuespecified must be a positive integer or 0. The value 0 means that nocall limit exists. For example:

ALTER SESSION SET STMT_CALL_LIMIT=10

DatabaseStmt_Call_Limit

Resets theWeb service call count of a session to the value specified.The value must be zero or a positive integer. Ws_Call_Countrepresents the total number of Web service calls made to the datastore instance for the current session. For example:

ALTER SESSION SET sforce.WS_CALL_COUNT=0

The current value of Ws_Call_Count can be obtained by referringto the System_Remote_Sessions system table. For example:

SELECT * FROM information_schema.system_remote_sessions

WHERE session_id = cursessionid()

RemoteWs_Call_Count


Chapter 6: Supported SQL functionality

Refresh Map (EXT)PurposeThe REFRESH MAP statement adds newly discovered objects to your relational view of native data. It alsoincorporates any configuration changes made to your relational view by reloading the schemamap configurationfile.

SyntaxREFRESH MAP

NotesREFRESH MAP is an expensive query since it involves the discovery of native data.

SelectPurposeUse the Select statement to fetch results from one or more tables.

SyntaxSELECT select_clausefrom_clause[where_clause][groupby_clause][having_clause][{UNION [ALL | DISTINCT] |{MINUS [DISTINCT] | EXCEPT [DISTINCT]} |INTERSECT [DISTINCT]} select_statement][limit_clause]

where:

select_clause

specifies the columns from which results are to be returned by the query. See Select clause on page100 for a complete explanation.

from_clause

specifies one or more tables on which the other clauses in the query operate. See From clause onpage 102 for a complete explanation.

where_clause

is optional and restricts the results that are returned by the query. SeeWhere clause on page 104 fora complete explanation.


Refresh Map (EXT)

groupby_clause

is optional and allows query results to be aggregated in terms of groups. See Group By clause onpage 105 for a complete explanation.

having_clause

is optional and specifies conditions for groups of rows (for example, display only the departmentsthat have salaries totaling more than $200,000). See Having clause on page 106 for a completeexplanation.

UNION

is an optional operator that combines the results of the left and right Select statements into a singleresult. See Union operator on page 106 for a complete explanation.

INTERSECT

is an optional operator that returns a single result by keeping any distinct values from the results ofthe left and right Select statements. See Intersect operator on page 107 for a complete explanation.

EXCEPT | MINUS

are synonymous optional operators that returns a single result by taking the results of the left Selectstatement and removing the results of the right Select statement. See Except and Minus operatorson page 108 for a complete explanation.

orderby_clause

is optional and sorts the results that are returned by the query. See Order By clause on page 109 fora complete explanation.

limit_clause

is optional and places an upper bound on the number of rows returned in the result. See Limit clauseon page 109 for a complete explanation.

Select clause

PurposeUse the Select clause to specify with a list of column expressions that identify columns of values that you wantto retrieve or an asterisk (*) to retrieve the value of all columns.

SyntaxSELECT [{LIMIT offset number | TOP number}] [ALL | DISTINCT] {* | column_expression[[AS] column_alias] [,column_expression [[AS] column_alias], ...]}

where:

LIMIT offset number

creates the result set for the Select statement first and then discards the first number of rows specifiedby offset and returns the number of remaining rows specified by number. To not discard any of



the rows, specify 0 for offset, for example, LIMIT 0 number. To discard the first offset numberof rows and return all the remaining rows, specify 0 for number, for example, LIMIT offset0.

TOP number

is equivalent to LIMIT 0number.

column_expression

can be simply a column name (for example, last_name). More complex expressions may includemathematical operations or stringmanipulation (for example, salary * 1.05). See SQL expressionson page 110 for details. column_expression can also include aggregate functions. See Aggregatefunctions on page 101 for details.

column_alias

can be used to give the column a descriptive name. For example, to assign the alias department tothe column dep:

SELECT dep AS department FROM emp

DISTINCT

eliminates duplicate rows from the result of a query. This operator can precede the first columnexpression. For example:

SELECT DISTINCT dep FROM emp

Notes• Separate multiple column expressions with commas (for example, SELECT last_name, first_name,

hire_date).

• Column names can be prefixed with the table name or table alias. For example, SELECT emp.last_nameor e.last_name, where e is the alias for the table emp.

• NULL values are not treated as distinct from each other. The default behavior is that all result rows bereturned, which can be made explicit with the keyword ALL.

Aggregate functionsAggregate functions can also be a part of a Select clause. Aggregate functions return a single value from a setof rows. An aggregate can be used with a column name (for example, AVG(salary)) or in combination witha more complex column expression (for example, AVG(salary * 1.07)). The column expression can bepreceded by the DISTINCT operator. The DISTINCT operator eliminates duplicate values from an aggregateexpression.

The following table lists supported aggregate functions.

Table 13: Aggregate Functions

ReturnsAggregate

The average of the values in a numeric column expression. For example, AVG(salary)returns the average of all salary column values.

AVG


Select

The number of values in any field expression. For example, COUNT(name) returns thenumber of name values. When using COUNT with a field name, COUNT returns thenumber of non-NULL column values. A special example is COUNT(*), which returnsthe number of rows in the set, including rows with NULL values.

COUNT

The maximum value in any column expression. For example, MAX(salary) returnsthe maximum salary column value.

MAX

The minimum value in any column expression. For example, MIN(salary) returnsthe minimum salary column value.

MIN

The total of the values in a numeric column expression. For example, SUM(salary)returns the sum of all salary column values.

SUM

Example AIn the following example, only distinct last name values are counted. The default behavior is that all duplicatevalues be returned, which can be made explicit with ALL.

COUNT (DISTINCT last_name)

Example BThe following example uses the COUNT, MAX, and AVG aggregate functions:

SELECTCOUNT(amount) AS numOpportunities,MAX(amount) AS maxAmount,AVG(amount) AS avgAmount

FROM opportunity o INNER JOIN user uON o.ownerId = u.id

WHERE o.isClosed = 'false' ANDu.name = 'MyName'

From clause

PurposeThe From clause indicates the tables to be used in the Select statement.

SyntaxFROM table_name [table_alias] [,...]

where:

table_name

is the name of a table or a subquery. Multiple tables define an implicit inner join among those tables.Multiple table names must be separated by a comma. For example:

SELECT * FROM emp, dep

Subqueries can be used instead of table names. Subqueries must be enclosed in parentheses. SeeSubquery in a From clause on page 104 for an example.



table_alias

is a name used to refer to a table in the rest of the Select statement. When you specify an alias fora table, you can prefix all column names of that table with the table alias.

ExampleThe following example specifies two table aliases, e for emp and d for dep:

SELECT e.name, d.deptNameFROM emp e, dep dWHERE e.deptId = d.id

table_alias is a name used to refer to a table in the rest of the Select statement. When you specify an aliasfor a table, you can prefix all column names of that table with the table alias. For example, given the tablespecification:

FROM emp E

you may refer to the last_name field as E.last_name. Table aliases must be used if the Select statement joinsa table to itself. For example:

SELECT * FROM emp E, emp F WHERE E.mgr_id = F.emp_id

The equal sign (=) includes only matching rows in the results.

Outer join escape sequences

PurposeThe SQL-92 left, right, and full outer join syntax is supported.

Syntax{oj outer-join}

where outer-join is

table-reference {LEFT | RIGHT | FULL} OUTER JOIN {table-reference | outer-join} ONsearch-condition

where table-reference is a database table name, and search-condition is the join condition you wantto use for the tables.

Example: SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.Status FROM {ojCustomers LEFT OUTER JOIN Orders ON Customers.CustID=Orders.CustID} WHEREOrders.Status='OPEN'

The following outer join escape sequences are supported:

• Left outer joins

• Right outer joins

• Full outer joins

• Nested outer joins


Select

Join in a From clause

PurposeYou can use a Join as a way to associate multiple tables within a Select statement. Joins may be either explicitor implicit. For example, the following is the example from the previous section restated as an explicit innerjoin:

SELECT * FROM emp INNER JOIN dep ON id=empIdSELECT e.name, d.deptNameFROM emp e INNER JOIN dep d ON e.deptId = d.id;

whereas the following is the same statement as an implicit inner join:

SELECT * FROM emp, dep WHERE emp.deptID=dep.id

Syntax

FROM table_name {RIGHT OUTER | INNER | LEFT OUTER | CROSS | FULL OUTER} JOIN table.keyON search-condition

ExampleIn this example, two tables are joined using LEFT OUTER JOIN. T1, the first table named includes nonmatchingrows.

SELECT * FROM T1 LEFT OUTER JOIN T2 ON T1.key = T2.key

If you use a CROSS JOIN, no ON expression is allowed for the join.

Subquery in a From clauseSubqueries can be used in the From clause in place of table references (table_name).

ExampleSELECT * FROM (SELECT * FROM emp WHERE sal > 10000) new_emp, dept WHEREnew_emp.deptno = dept.deptno

See alsoFor more information about subqueries, see Subqueries on page 117.

Where clause

PurposeSpecifies the conditions that rows must meet to be retrieved.

SyntaxWHERE expr1rel_operatorexpr2

where:



expr1

is either a column name, literal, or expression.

expr2

is either a column name, literal, expression, or subquery. Subqueries must be enclosed in parentheses.

rel_operator

is the relational operator that links the two expressions.

ExampleThe following Select statement retrieves the first and last names of employees that make at least $20,000.

SELECT last_name, first_name FROM emp WHERE salary >= 20000

See also• SQL expressions on page 110

• Subqueries on page 117

Group By clause

PurposeSpecifies the names of one or more columns by which the returned values are grouped. This clause is usedto return a set of aggregate values.

SyntaxGROUP BY column_expression [,...]

where:

column_expression

is either a column name or a SQL expression. Multiple values must be separated by a comma. Ifcolumn_expression is a column name, it must match one of the column names specified in the Selectclause. Also, the Group By clause must include all non-aggregate columns specified in the Selectlist.

ExampleThe following example totals the salaries in each department:

SELECT dept_id, sum(salary) FROM emp GROUP BY dept_id

This statement returns one row for each distinct department ID. Each row contains the department ID and thesum of the salaries of the employees in the department.




Select

Having clause

PurposeSpecifies conditions for groups of rows (for example, display only the departments that have salaries totalingmore than $200,000). This clause is valid only if you have already defined a Group By clause.

SyntaxHAVING expr1rel_operatorexpr2

where:

expr1 | expr2

can be column names, constant values, or expressions. These expressions do not have to match acolumn expression in the Select clause. See SQL expressions on page 110 for details regarding SQLexpressions.

rel_operator

is the relational operator that links the two expressions.

ExampleThe following example returns only the departments that have salaries totaling more than $200,000:

SELECT dept_id, sum(salary) FROM emp GROUP BY dept_id HAVING sum(salary) > 200000



Union operator

PurposeCombines the results of two Select statements into a single result. The single result is all the returned rowsfrom both Select statements. By default, duplicate rows are not returned. To return duplicate rows, use the Allkeyword (UNION ALL).

Syntaxselect_statementUNION [ALL | DISTINCT] | {MINUS [DISTINCT] | EXCEPT [DISTINCT]} | INTERSECT[DISTINCT]select_statement

Notes• When using the Union operator, the Select lists for each Select statement must have the same number of

column expressions with the same data types and must be specified in the same order.



Example AThe following example has the same number of column expressions, and each column expression, in order,has the same data type.

SELECT last_name, salary, hire_date FROM empUNIONSELECT name, pay, birth_date FROM person

Example BThe following example is not valid because the data types of the column expressions are different (salaryFROM emp has a different data type than last_name FROM raises). This example does have the samenumber of column expressions in each Select statement but the expressions are not in the same order by datatype.

SELECT last_name, salary FROM empUNIONSELECT salary, last_name FROM raises

Intersect operator

PurposeIntersect operator returns a single result set. The result set contains rows that are returned by both Selectstatements. Duplicates are returned unless the Distinct operator is added.

Syntaxselect_statementINTERSECT [DISTINCT]select_statement

where:

DISTINCT

eliminates duplicate rows from the results.

Notes• When using the Intersect operator, the Select lists for each Select statement must have the same number

of column expressions with the same data types and must be specified in the same order.


SELECT last_name, salary, hire_date FROM empINTERSECT [DISTINCT]SELECT name, pay, birth_date FROM person


Select


SELECT last_name, salary FROM empINTERSECTSELECT salary, last_name FROM raises

Except and Minus operators

PurposeReturn the rows from the left Select statement that are not included in the result of the right Select statement.

Syntaxselect_statement{EXCEPT [DISTINCT] | MINUS [DISTINCT]}select_statement

where:

DISTINCT

eliminates duplicate rows from the results.

Notes• When using one of these operators, the Select lists for each Select statement must have the same number

of column expressions with the same data types and must be specified in the same order.


SELECT last_name, salary, hire_date FROM empEXCEPTSELECT name, pay, birth_date FROM person


SELECT last_name, salary FROM empEXCEPTSELECT salary, last_name FROM raises



Order By clause

PurposeThe Order By clause specifies how the rows are to be sorted.

SyntaxORDER BY sort_expression [DESC | ASC] [,...]

where:

sort_expression

is either the name of a column, a column alias, a SQL expression, or the positioned number of thecolumn or expression in the select list to use.

The default is to perform an ascending (ASC) sort.

ExampleTo sort by last_name and then by first_name, you could use either of the following Select statements:

SELECT emp_id, last_name, first_name FROM emp

ORDER BY last_name, first_name

or

SELECT emp_id, last_name, first_name FROM emp

ORDER BY 2,3

In the second example, last_name is the second item in the Select list, so ORDER BY 2,3 sorts by last_nameand then by first_name.

See alsoSQL expressions on page 110

Limit clause

PurposePlaces an upper bound on the number of rows returned in the result.

SyntaxLIMIT number_of_rows [OFFSET offset_number]

where:

number_of_rows

specifies a maximum number of rows in the result. A negative number indicates no upper bound.

OFFSET

specifies how many rows to skip at the beginning of the result set. offset_number is the numberof rows to skip.


Select

Notes• In a compound query, the Limit clause can appear only on the final Select statement. The limit is applied

to the entire query, not to the individual Select statement to which it is attached.

ExampleThe following example returns a maximum of 20 rows.

SELECT last_name, first_name FROM emp WHERE salary > 20000 ORDER BY dept_idc LIMIT20

SQL expressionsAn expression is a combination of one or more values, operators, and SQL functions that evaluate to a value.You can use expressions in the Where, and Having of Select statements; and in the Set clauses of Updatestatements.

Expressions enable you to use mathematical operations as well as character string manipulation operators toform complex queries.

The driver supports both unquoted and quoted identifiers. An unquoted identifier must start with an ASCII alphacharacter and can be followed by zero or more ASCII alphanumeric characters. Unquoted identifiers areconverted to uppercase before being used.

Quoted identifiers must be enclosed in double quotation marks (""). A quoted identifier can contain any Unicodecharacter including the space character. The driver recognizes the Unicode escape sequence \uxxxx as aUnicode character. You can specify a double quotation mark in a quoted identifier by escaping it with a doublequotation mark.

The maximum length of both quoted and unquoted identifiers is 128 characters.

Valid expression elements are:

• Column names

• Literals

• Operators

• Functions

Column namesThemost common expression is a simple column name. You can combine a column name with other expressionelements.

LiteralsLiterals are fixed data values. For example, in the expression PRICE * 1.05, the value 1.05 is a constant.Literals are classified into types, including the following:

• Binary

• Character string

• Date



• Floating point

• Integer

• Numeric

• Time

• Timestamp

The following table describes the literal format for supported SQL data types.

Table 14: Literal syntax examples

ExampleLiteral SyntaxSQL Type

12 or -34 or 0n

wheren is any valid integer value in the range of theINTEGER data type

BIGINT

0

1

Min Value: 0

Max Value: 1

BOOLEAN

'2010-05-21'DATE'date'DATE

'2010-05-2118:33:05.025'

TIMESTAMP'ts'DATETIME

0.25

3.1415

-7.48

n.f

where:

n

is the integral part

f

is the fractional part

DECIMAL

1.2E0 or 2.5E40 or -3.45E2or 5.67E-4

n.fEx

where:

n is the integral part

f is the fractional part

x is the exponent

DOUBLE

12 or -34 or 0n

where n is a valid integer value in the rangeof the INTEGER data type

INTEGER

'000482ff'X'hex_value'LONGVARBINARY

'This is a stringliteral'

'value'LONGVARCHAR


SQL expressions

ExampleLiteral SyntaxSQL Type

'2010-05-2118:33:05.025'

TIME'time'TIME

'This is a stringliteral'

'value'VARCHAR

Character string literalsText specifies a character string literal. A character string literal must be enclosed in single quotation marks.To represent one single quotation mark within a literal, you must enter two single quotation marks. When thedata in the fields is returned to the client, trailing blanks are stripped.

A character string literal can have a maximum length of 32 KB, that is, (32*1024) bytes.

Example

'Hello''Jim''s friend is Joe'

Numeric literalsUnquoted numeric values are treated as numeric literals. If the unquoted numeric value contains a decimalpoint or exponent, it is treated as a real literal; otherwise, it is treated as an integer literal.

Example+1894.1204

Binary literalsBinary literals are represented with single quotation marks. The valid characters in a binary literal are 0-9, a-f,and A-F.

Example'00af123d'

Date and time literalsDate and time literal values are enclosed in single quotion marks ('value').

• The format for a Date literal is DATE'date'.

• The format for a Time literal is TIME'time'.

• The format for a Timestamp literal is TIMESTAMP'ts'.

Integer literalsInteger literals are represented by a string of numbers that are not enclosed in quotation marks and do notcontain decimal points.



Notes• Integer constants must be whole numbers; they cannot contain decimals.

• Integer literals can start with sign characters (+/-).

Example1994 or -2

OperatorsThis section describes the operators that can be used in SQL expressions.

Unary operatorA unary operator operates on only one operand.operator operand

Binary operatorA binary operator operates on two operands.operand1 operator operand2

If an operator is given a null operand, the result is always null. The only operator that does not follow this ruleis concatenation (||).

Arithmetic operatorsYou can use an arithmetic operator in an expression to negate, add, subtract, multiply, and divide numericvalues. The result of this operation is also a numeric value. The + and - operators are also supported in date/timefields to allow date arithmetic. The following table lists the supported arithmetic operators.

Table 15: Arithmetic operators

ExamplePurposeOperator

SELECT * FROM emp WHERE comm = -1Denotes a positive or negative expression. Theseare unary operators.

+ -

UPDATE emp SET sal = sal + sal *0.10

Multiplies, divides. These are binary operators.* /

SELECT sal + comm FROM emp WHEREempno > 100

Adds, subtracts. These are binary operators.+ -

Concatenation operatorThe concatenation operator manipulates character strings. The following table lists the only supportedconcatenation operator.


SQL expressions

Table 16: Concatenation operator


SELECT 'Name is' || ename FROM empConcatenates character strings.||

The result of concatenating two character strings is the data type VARCHAR.

Comparison operatorsComparison operators compare one expression to another. The result of such a comparison can be TRUE,FALSE, or UNKNOWN (if one of the operands is NULL). The driver considers the UNKNOWN result as FALSE.

The following table lists the supported comparison operators.

Table 17: Comparison operators


SELECT * FROM emp WHERE sal =1500

Equality test.=

SELECT * FROM emp WHERE sal !=1500

Inequality test.!=<>

SELECT * FROM emp WHERE sal >1500 SELECT * FROM emp WHEREsal < 1500

“Greater than" and "less than"tests.

><

SELECT * FROM emp WHERE sal >=1500 SELECT * FROM emp WHEREsal <= 1500

“Greater than or equal to" and "lessthan or equal to" tests.

>=<=

SELECT * FROM emp WHERE ENAMELIKE 'J%\_%' ESCAPE '\'

This matches all records with names thatstart with letter 'J' and have the '_'character in them.

The Escape clause is supported inthe LIKE predicate to indicate theescape character. Escapecharacters are used in the patternstring to indicate that any wildcardcharacter that is after the escape

ESCAPE clause in LIKEoperator

LIKE ’pattern string’ ESCAPE’c’

SELECT * FROM emp WHERE ENAMELIKE 'JOE\_JOHN' ESCAPE '\'

character in the pattern stringshould be treated as a regularcharacter.

The default escape character isbackslash (\).

This matches only records with name’JOE_JOHN’.

SELECT * FROM emp WHERE job IN('CLERK','ANALYST') SELECT *FROM emp WHERE sal IN (SELECTsal FROM emp WHERE deptno =30)

“Equal to any member of" test.[NOT] IN

SELECT * FROM emp WHERE salBETWEEN 2000 AND 3000

"Greater than or equal to x" and"less than or equal to y."

[NOT] BETWEEN x AND y




SELECT empno, ename, deptnoFROM emp e WHERE EXISTS(SELECT deptno FROM dept WHEREe.deptno = dept.deptno)

Tests for existence of rows in asubquery.

EXISTS

SELECT * FROM emp WHERE enameIS NOT NULL SELECT * FROM empWHERE ename IS NULL

Tests whether the value of thecolumn or expression is NULL.

IS [NOT] NULL

Logical operatorsA logical operator combines the results of two component conditions to produce a single result or to invert theresult of a single condition. The following table lists the supported logical operators.

Table 18: Logical operators


SELECT * FROM emp WHERE NOT (jobIS NULL)SELECT * FROM emp WHERE NOT (salBETWEEN 1000 AND 2000)

Returns TRUE if the following condition isFALSE. Returns FALSE if it is TRUE. If it isUNKNOWN, it remains UNKNOWN.

NOT

SELECT * FROM emp WHERE job ='CLERK' AND deptno = 10

Returns TRUE if both component conditions areTRUE. Returns FALSE if either is FALSE;otherwise, returns UNKNOWN.

AND

SELECT * FROM emp WHERE job ='CLERK' OR deptno = 10

Returns TRUE if either component condition isTRUE. Returns FALSE if both are FALSE;otherwise, returns UNKNOWN.

OR

ExampleIn theWhere clause of the following Select statement, the AND logical operator is used to ensure that managersearning more than $1000 a month are returned in the result:

SELECT * FROM emp WHERE jobtitle = manager AND sal > 1000

Operator precedenceAs expressions become more complex, the order in which the expressions are evaluated becomes important.The following table shows the order in which the operators are evaluated. The operators in the first line areevaluated first, then those in the second line, and so on. Operators in the same line are evaluated left to rightin the expression.You can change the order of precedence by using parentheses. Enclosing expressions inparentheses forces them to be evaluated together.


SQL expressions

Table 19: Operator precedence

OperatorPrecedence

+ (Positive), - (Negative)1

*(Multiply), / (Division)2

+ (Add), - (Subtract)3

|| (Concatenate)4

=, >, <, >=, <=, <>, != (Comparison operators)5

NOT, IN, LIKE6

AND7

OR8

Example AThe query in the following example returns employee records for which the department number is 1 or 2 andthe salary is greater than $1000:

SELECT * FROM emp WHERE (deptno = 1 OR deptno = 2) AND sal > 1000

Because parenthetical expressions are forced to be evaluated first, the OR operation takes precedence overAND.

Example BIn the following example, the query returns records for all the employees in department 1, but only employeeswhose salary is greater than $1000 in department 2.

SELECT * FROM emp WHERE deptno = 1 OR deptno = 2 AND sal > 1000

The AND operator takes precedence over OR, so that the search condition in the example is equivalent to theexpression deptno = 1 OR (deptno = 2 AND sal > 1000).

FunctionsThe driver supports a number of functions that you can use in expressions, as listed and described in Scalarfunctions on page 122.

ConditionsA condition specifies a combination of one or more expressions and logical operators that evaluates to eitherTRUE, FALSE, or UNKNOWN. You can use a condition in the Where clause of the Delete, Select, and Updatestatements; and in the Having clauses of Select statements. The following describes supported conditions.



Table 20: Conditions

DescriptionCondition

Specifies a comparison with expressions or subquery results.

= , !=, <>, < , >, <=, <=

Simple comparison

Specifies a comparison with any or all members in a list orsubquery.

[= , !=, <>, < , >, <=, <=] [ANY, ALL, SOME]

Group comparison

Tests for membership in a list or subquery.

[NOT] IN

Membership

Tests for inclusion in a range.

[NOT] BETWEEN

Range

Tests for nulls.

IS NULL, IS NOT NULL

NULL

Tests for existence of rows in a subquery.

[NOT] EXISTS

EXISTS

Specifies a test involving pattern matching.

[NOT] LIKE

LIKE

Specifies a combination of other conditions.

CONDITION [AND/OR] CONDITION

Compound

SubqueriesA query is an operation that retrieves data from one or more tables or views. In this reference, a top-level queryis called a Select statement, and a query nested within a Select statement is called a subquery.

A subquery is a query expression that appears in the body of another expression such as a Select, an Update,or a Delete statement. In the following example, the second Select statement is a subquery:

SELECT * FROM emp WHERE deptno IN (SELECT deptno FROM dept)


Subqueries

IN predicate

PurposeThe In predicate specifies a set of values against which to compare a result set. If the values are being comparedagainst a subquery, only a single column result set is returned.

Syntaxvalue [NOT] IN (value1, value2,...)

OR

value [NOT] IN (subquery)

ExampleSELECT * FROM emp WHERE deptno IN

(SELECT deptno FROM dept WHERE dname <> 'Sales')

EXISTS predicate

PurposeThe Exists predicate is true only if the cardinality of the subquery is greater than 0; otherwise, it is false.

SyntaxEXISTS (subquery)

Example

SELECT empno, ename, deptno FROM emp e WHERE EXISTS(SELECT deptno FROM dept WHERE e.deptno = dept.deptno)

UNIQUE predicate

PurposeThe Unique predicate is used to determine whether duplicate rows exist in a virtual table (one returned from asubquery).

SyntaxUNIQUE (subquery)

Example

SELECT * FROM dept d WHERE UNIQUE(SELECT deptno FROM emp e WHERE e.deptno = d.deptno)



Correlated subqueries

PurposeA correlated subquery is a subquery that references a column from a table referred to in the parent statement.A correlated subquery is evaluated once for each row processed by the parent statement. The parent statementcan be a Select, Update, or Delete statement.

A correlated subquery answers a multiple-part question in which the answer depends on the value in each rowprocessed by the parent statement. For example, you can use a correlated subquery to determine whichemployees earn more than the average salaries for their departments. In this case, the correlated subqueryspecifically computes the average salary for each department.

SyntaxSELECT select_list

FROM table1 t_alias1WHERE expr rel_operator(SELECT column_list

FROM table2 t_alias2WHERE t_alias1.columnrel_operatort_alias2.column)

UPDATE table1 t_alias1SET column =(SELECT expr

FROM table2 t_alias2WHERE t_alias1.column = t_alias2.column)

DELETE FROM table1 t_alias1WHERE column rel_operator(SELECT expr

FROM table2 t_alias2WHERE t_alias1.column = t_alias2.column)

Notes• Correlated column names in correlated subqueries must be explicitly qualified with the table name of the

parent.

Example AThe following statement returns data about employees whose salaries exceed their department average. Thisstatement assigns an alias to emp, the table containing the salary information, and then uses the alias in acorrelated subquery:

SELECT deptno, ename, sal FROM emp x WHERE sal >(SELECT AVG(sal) FROM emp WHERE x.deptno = deptno)ORDER BY deptno

Example BThis is an example of a correlated subquery that returns row values:

SELECT * FROM dept "outer" WHERE 'manager' IN(SELECT managername FROM empWHERE "outer".deptno = emp.deptno)


Subqueries

Example CThis is an example of finding the department number (deptno) with multiple employees:

SELECT * FROM dept main WHERE 1 <(SELECT COUNT(*) FROM emp WHERE deptno = main.deptno)

Example DThis is an example of correlating a table with itself:

SELECT deptno, ename, sal FROM emp x WHERE sal >(SELECT AVG(sal) FROM emp WHERE x.deptno = deptno)



7SQL escape sequences for JDBC

Language features, such as outer joins and scalar function calls, are commonly implemented by databasesystems. The syntax for these features is often database-specific, even when a standard syntax has beendefined. JDBC defines escape sequences that contain the standard syntax for the following language features:

• Date, time, and timestamp literals

• Scalar functions such as numeric, string, and data type conversion functions

• Outer joins

• Escape characters for wildcards used in LIKE clauses

The escape sequence used by JDBC is:

{extension}

The escape sequence is recognized and parsed by the drivers, which replaces the escape sequences withdata store-specific grammar.


• Date, time, and timestamp escape sequences

• Scalar functions

• Outer join escape sequences

• LIKE escape character sequence for wildcards


Date, time, and timestamp escape sequencesThe escape sequence for date, time, and timestamp literals is:

{literal-type 'value'}

where:

literal-type

is one of the following:

Value FormatDescriptionliteral-type

yyyy-mm-ddDated

hh:mm:ss []Timet

yyyy-mm-dd hh:mm:ss[.f...]Timestampts

Example:

UPDATE Orders SET OpenDate={d '1995-01-15'} WHERE OrderID=1023

Scalar functionsYou can use scalar functions in SQL statements with the following syntax:

{fn scalar-function}

where:

scalar-function

is a scalar function supported by the drivers, as listed in the following table.

Example:

SELECT id, name FROM emp WHERE name LIKE {fn UCASE('Smith')}

Table 21: Scalar functions

System FunctionsTimedate FunctionsNumeric FunctionsString Functions

CURSESSIONIDCURDATEABSASCII

DATABASECURTIMEACOSBIT_LENGTH

IDENTITYDATEDIFFASINCHAR

USERDAYATANCHAR_LENGTH


Chapter 7: SQL escape sequences for JDBC

System FunctionsTimedate FunctionsNumeric FunctionsString Functions

IFNULLDAYNAMEATAN2CHARACTER_LENGTH

DAYOFMONTHCEILINGCONCAT

DAYOFWEEKBITANDDIFFERENCE

DAYOFYEARBITORHEXTORAW

EXTRACTBITXORINSERT

HOURCOSLCASE

MINUTECOTLEFT

MONTHDEGREESLENGTH

MONTHNAMEEXPLOCATE

NOWFLOORLOCATE_2

SECONDLOGLOWER

TO_CHARLOG10LTRIM

WEEKMODOCTET_LENGTH

YEARPIRAWTOHEX

POWERREPEAT

RADIANSREPLACE

RANDRIGHT

ROUNDRTRIM

SIGNSOUNDEX

SINSPACE

SQRTSUBSTR

TANSUBSTRING

TRUNCATEUCASE

ROUNDMAGICUPPER


Scalar functions

Outer join escape sequencesJDBC supports the SQL-92 left, right, and full outer join syntax. The escape sequence for outer joins is:

{oj outer-join}

where:

outer-join

is table-reference {LEFT | RIGHT | FULL} OUTER JOIN {table-reference |outer-join} ON search-condition

table-reference

is a database table name.

search-condition

is the join condition you want to use for the tables.

Example:

SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.StatusFROM {oj Customers LEFT OUTER JOIN

Orders ON Customers.CustID=Orders.CustID}WHERE Orders.Status='OPEN'

The driver supports the following outer join escape sequences:

• Left outer joins

• Right outer joins

• Full outer joins

• Nested outer join

LIKE escape character sequence for wildcardsYou can specify the character to be used to escape wildcard characters (% and _, for example) in LIKE clauses.The escape sequence for escape characters is:

{escape 'escape-character'}

where:

escape-character

is the character used to escape the wildcard character.

For example, the following SQL statement specifies that an asterisk (*) be used as the escape character in theLIKE clause for the wildcard character %:

SELECT col1 FROM table1 WHERE col1 LIKE '*%%' {escape '*'}


Chapter 7: SQL escape sequences for JDBC

8JDBC support

Progress DataDirect for JDBC drivers are compatible with JDBC 2.0, 3.0, 4.0, 4.1, and 4.2. The following topicsdescribe support for JDBC interfaces and methods across the JDBC driver product line. Support for JDBCinterfaces and methods depends, in part, on which driver you are using.


• Array

• Blob

• CallableStatement

• Clob

• Connection

• ConnectionEventListener

• ConnectionPoolDataSource

• DatabaseMetaData

• DataSource

• Driver

• ParameterMetaData

• PooledConnection

• PreparedStatement

• Ref


• ResultSet

• ResultSetMetaData

• RowSet

• SavePoint

• Statement

• StatementEventListener

• Struct

• XAConnection

• XADataSource

• XAResource

ArrayCommentsSupportedVersion

IntroducedArray Methods

Yes4.0void free()

Yes2.0 CoreObject getArray()

The drivers ignore the map argument.Yes2.0 CoreObject getArray(map)

Yes2.0 CoreObject getArray(long, int)

The drivers ignore the map argument.Yes2.0 CoreObject getArray(long, int, map)

Yes2.0 Coreint getBaseType()

Yes2.0 CoreString getBaseTypeName()

Yes2.0 CoreResultSet getResultSet()

The drivers ignore the map argument.Yes2.0 CoreResultSet getResultSet(map)

Yes2.0 CoreResultSet getResultSet(long, int)

The drivers ignore the map argument.Yes2.0 CoreResultSet getResultSet(long, int, map)


Chapter 8: JDBC support

BlobCommentsSupportedVersion

IntroducedBlob Methods

Yes4.0void free()

The drivers support using data types thatmap to the JDBC LONGVARBINARY datatype.

Yes2.0 CoreInputStream getBinaryStream()


Yes2.0 Corebyte[] getBytes(long, int)


Yes2.0 Corelong length()

The Informix driver requires that the patternparameter (which specifies the Blob objectdesignating the BLOB value for which tosearch) be less than or equal to a maximumvalue of 4096 bytes.

All other drivers support using data typesthat map to the JDBC LONGVARBINARYdata type.

Yes2.0 Corelong position(Blob, long)

The Informix driver requires that the patternparameter (which specifies the byte arrayfor which to search) be less than or equalto a maximum value of 4096 bytes. All otherdrivers support using data types that mapto the JDBC LONGVARBINARY data type.

Yes2.0 Corelong position(byte[], long)


Yes3.0OutputStream setBinaryStream(long)


Yes3.0int setBytes(long, byte[])


Yes3.0int setBytes(long, byte[], int, int)


Yes3.0void truncate(long)


Blob

CallableStatementCommentsSupportedVersion

IntroducedCallableStatement Methods

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

The Progress OpenEdge driver throws an"unsupported method" exception.

Yes2.0 CoreArray getArray(int)

Supported for the SQL Server driver only.

All other drivers throw an "unsupportedmethod" exception.

Yes3.0Array getArray(String)


Yes4.0Reader getCharacterStream(int)

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupportedmethod"exception.

Yes4.0Reader getCharacterStream(String)


Yes2.0 CoreBigDecimal getBigDecimal(int)


Yes1.0BigDecimal getBigDecimal(int, int)


All other drivers throw "unsupportedmethod" exception.

Yes3.0BigDecimal getBigDecimal(String)



CommentsSupportedVersionIntroduced

CallableStatement Methods



Yes2.0 CoreBlob getBlob(int)



Yes3.0Blob getBlob(String)


Yes1.0boolean getBoolean(int)



Yes3.0boolean getBoolean(String)


Yes1.0byte getByte(int)



Yes3.0byte getByte(String)


Yes1.0byte [] getBytes(int)

Supported for the SQL Server driver only.All other drivers throw "unsupportedmethod" exception.

Yes3.0byte [] getBytes(String)


CallableStatement





Yes2.0 CoreClob getClob(int)

Supported for the SQL Server driver onlyusing with data types that map to the JDBCLONGVARCHAR data type.


Yes3.0Clob getClob(String)


Yes1.0Date getDate(int)


Yes2.0 CoreDate getDate(int, Calendar)



Yes3.0Date getDate(String)



Yes3.0Date getDate(String, Calendar)


Yes1.0double getDouble(int)



Yes3.0double getDouble(String)






Yes1.0float getFloat(int)



Yes3.0float getFloat(String)


Yes1.0int getInt(int)



Yes3.0int getInt(String)


Yes1.0long getLong(int)



Yes3.0long getLong(String)


Yes4.0Reader getNCharacterStream(int)


Yes4.0Reader getNCharacterStream(String)


Yes4.0NClob getNClob(int)


Yes4.0NClob getNClob(String)


CallableStatement



The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw "unsupported method"exception.

Yes4.0String getNString(int)


Yes4.0String getNString(String)


Yes1.0Object getObject(int)

The drivers ignore the Map argument.Yes2.0 CoreObject getObject(int, Map)



Yes3.0Object getObject(String)

Supported for the SQL Server driver only.The SQL Server driver ignores the Mapargument.


Yes3.0Object getObject(String, Map)



No2.0 CoreRef getRef(int)

The drivers throw "unsupported method"exception.

No3.0Ref getRef(String)


Yes1.0short getShort(int)



Yes3.0short getShort(String)






Yes4.0SQLXML getSQLXML(int)


Yes4.0SQLXML getSQLXML(String)


Yes1.0String getString(int)



Yes3.0String getString(String)


Yes1.0Time getTime(int)


Yes2.0 CoreTime getTime(int, Calendar)



Yes3.0Time getTime(String)

Supported for SQL Server driver only.


Yes3.0Time getTime(String, Calendar)


Yes1.0Timestamp getTimestamp(int)


CallableStatement




Yes2.0 CoreTimestamp getTimestamp(int, Calendar)



Yes3.0Timestamp getTimestamp(String)



Yes3.0Timestamp getTimestamp(String, Calendar)


No3.0URL getURL(int)


No3.0URL getURL(String)

Yes4.0boolean isWrapperFor(Class<?> iface)


Yes1.0void registerOutParameter(int, int)


Yes1.0void registerOutParameter(int, int, int)


The Oracle driver supports the Stringargument.

For all other drivers, the String argument isignored.

Yes2.0 Corevoid registerOutParameter(int, int, String)








Yes3.0void registerOutParameter(String, int)




Yes3.0void registerOutParameter(String, int, int)



All other drivers throw "unsupportedmethod" exception. String/typenameignored.

Yes3.0void registerOutParameter(String, int, String)

Supported for the Oracle driver only.


Yes2.0 Corevoid setArray(int, Array)



Yes4.0void setAsciiStream(String, InputStream)



Yes3.0void setAsciiStream(String, InputStream,int)



Yes4.0void setAsciiStream(String, InputStream,long)


CallableStatement





Yes3.0void setBigDecimal(String, BigDecimal)



Yes4.0void setBinaryStream(String, InputStream)



Yes3.0void setBinaryStream(String, InputStream,int)



Yes4.0void setBinaryStream(String, InputStream,long)



Yes4.0void setBlob(String, Blob)



Yes4.0void setBlob(String, InputStream)



Yes4.0void setBlob(String, InputStream, long)



Yes3.0void setBoolean(String, boolean)



Yes3.0void setByte(String, byte)



Yes3.0void setBytes(String, byte [])



Yes3.0void setCharacterStream(String, Reader,int)







Yes4.0void setCharacterStream(String,InputStream, long)



Yes4.0void setClob(String, Clob)



Yes4.0void setClob(String, Reader)



Yes4.0void setClob(String, Reader, long)



Yes3.0void setDate(String, Date)



Yes3.0void setDate(String, Date, Calendar)



Yes3.0void setDouble(String, double)



Yes3.0void setFloat(String, float)



Yes3.0void setInt(String, int)



Yes3.0void setLong(String, long)

Yes4.0void setNCharacterStream(String, Reader,long)

Yes4.0void setNClob(String, NClob)


CallableStatement



Yes4.0void setNClob(String, Reader)

Yes4.0void setNClob(String, Reader, long)

Yes4.0void setNString(String, String)

Yes2.0 Corevoid setNull(int, int, String)



Yes3.0void setNull(String, int)



Yes3.0void setNull(String, int, String)



Yes3.0void setObject(String, Object)



Yes3.0void setObject(String, Object, int)



Yes3.0void setObject(String, Object, int, int)



Yes3.0void setShort(String, short)


Yes4.0void setSQLXML(String, SQLXML)



Yes3.0void setString(String, String)



Yes3.0void setTime(String, Time)







Yes3.0void setTime(String, Time, Calendar)



Yes3.0void setTimestamp(String, Timestamp)



Yes3.0void setTimestamp(String, Timestamp,Calendar)

Yes4.0<T> T unwrap(Class<T> iface)


No3.0void setURL(String, URL)

Yes1.0boolean wasNull()

ClobCommentsSupportedVersion

IntroducedClob Methods

Yes4.0void free()

All drivers support using with data types thatmap to the JDBC LONGVARCHAR datatype.

Yes2.0 CoreInputStream getAsciiStream()


Yes2.0 CoreReader getCharacterStream()


Yes4.0Reader getCharacterStream(long, long)


Yes2.0 CoreString getSubString(long, int)


Yes2.0 Corelong length()


Clob


Clob Methods


The Informix driver requires that thesearchStr parameter be less than or equalto a maximum value of 4096 bytes.

Yes2.0 Corelong position(Clob, long)


The Informix driver requires that thesearchStr parameter be less than or equalto a maximum value of 4096 bytes.

Yes2.0 Corelong position(String, long)


Yes3.0 CoreOutputStream setAsciiStream(long)


Yes3.0 CoreWriter setCharacterStream(long)


Yes3.0 Coreint setString(long, String)


Yes3.0 Coreint setString(long, String, int, int)


Yes3.0 Corevoid truncate(long)

ConnectionCommentsSupportedVersion

IntroducedConnection Methods

Yes1.0void clearWarnings()

When a connection is closed while atransaction is still active, that transaction isrolled back.

Yes1.0void close()

Yes1.0void commit()




Connection Methods

Yes4.0Blob createBlob()

Yes4.0Clob createClob()

Yes4.0NClob createNClob()

The drivers throw an unsupported methodexception.

No4.0createArrayOf(String, Object[])

Only the Oracle driver supports this method.Yes4.0createStruct(String, Object[])

Yes4.0SQLXML createSQLXML()

Yes1.0Statement createStatement()

For the DB2 driver,ResultSet.TYPE_SCROLL_SENSITIVE isdowngraded toTYPE_SCROLL_INSENSITIVE.

For the drivers for Oracle Eloqua, OracleSales Cloud, Oracle Service Cloud, andSalesforce, be aware that scroll-sensitiveresult sets are expensive from both a Webservice call and a performance perspective.The drivers expend a network round trip foreach row that is fetched.

Yes2.0 CoreStatement createStatement(int, int)

With the exception of the DB2 driver, thespecified holdability must match thedatabase default holdability. Otherwise, an"unsupported method" exception is thrown.

For the DB2 driver, the method can becalled regardless of whether the specifiedholdability matches the database defaultholdability.

No3.0Statement createStatement(int, int, int)


All other drivers throw "unsupportedmethod"exception.

Yes1.0Struct createStruct(String, Object[])

Yes1.0boolean getAutoCommit()


Connection


Connection Methods

The drivers for the listed database systemsreturn an empty string because they do nothave the concept of a catalog: AmazonRedshift, Apache Cassandra, Apache Hive,Apache Spark SQL, Greenplum, Impala,MongoDB, Oracle, Oracle Eloqua, OracleSales Cloud, Oracle Service Cloud,PostgreSQL, and Salesforce.

Yes1.0String getCatalog()

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcedo not support storing or retrieving clientinformation.

Yes4.0String getClientInfo()


Yes4.0String getClientInfo(String)

Yes3.0int getHoldability()

Yes1.0DatabaseMetaData getMetaData()

Yes1.0int getTransactionIsolation()

Always returns empty java.util.HashMap.Yes2.0 CoreMap getTypeMap()

Yes1.0SQLWarning getWarnings()

Yes1.0boolean isClosed()

Yes1.0boolean isReadOnly()

Yes4.0boolean isValid()


Always returns the same String that waspassed in from the application.

Yes1.0String nativeSQL(String)

Yes1.0CallableStatement prepareCall(String)

For the drivers for Apache Cassandra, DB2,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, ResultSet.TYPE_SCROLL_SENSITIVE is downgraded toTYPE_SCROLL_INSENSITIVE.

Yes2.0 CoreCallableStatement prepareCall(String, int,int)




Connection Methods

The DB2 driver allows this method whetheror not the specified holdability is the sameas the default holdability.

The other drivers throw the exception"Changing the default holdability is notsupported" when the specified holdabilitydoes not match the default holdability.

Yes3.0CallableStatement prepareCall(String, int,int, int)

Yes1.0PreparedStatement prepareStatement(String)

Yes3.0PreparedStatement prepareStatement(String, int)

For the DB2 driver,ResultSet.TYPE_SCROLL_ SENSITIVE isdowngraded toTYPE_SCROLL_INSENSITIVE.

For the drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, be aware that scroll-sensitiveresult sets are expensive from both a Webservice call and a performance perspective.The drivers expend a network round trip foreach row that is fetched.

Yes2.0 CorePreparedStatement prepareStatement(String, int, int)

All drivers throw "unsupported method"exception.

No3.0PreparedStatement prepareStatement(String, int, int, int)

Supported for the Oracle and SQL Serverdrivers.


Yes3.0PreparedStatement prepareStatement(String, int[])



Yes3.0PreparedStatement prepareStatement(String, String [])

The DB2 driver only supports with DB2 V8.xand higher for Linux/UNIX/Windows, DB2for z/OS (all versions), and DB2 for i.

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcethrow an "unsupported method" exception.

Yes3.0void releaseSavepoint(Savepoint)


Connection


Connection Methods

Yes1.0void rollback()

The DB2 driver only supports with DB2 V8.xfor i.


Yes3.0void rollback(Savepoint)

The drivers for Apache Cassandra, ApacheHive, Apache Spark SQL, Impala,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcethrow "transactions not supported" exceptionif set to false.

Yes1.0void setAutoCommit(boolean)

The driver for the listed database systemsignore any value set by the Stringargument.The corresponding drivers returnan empty string because they do not havethe concept of a catalog: Amazon Redshift,Apache Cassandra, Apache Hive, ApacheSpark SQL, Greenplum, Impala, MongoDB,Oracle, Oracle Eloqua, Oracle Sales Cloud,Oracle Service Cloud, PostgreSQL, andSalesforce.

Yes1.0void setCatalog(String)


Yes4.0String setClientInfo(Properties)


Yes4.0String setClientInfo(String, String)

The DB2 driver supports the Holdabilityparameter value.

For other drivers, the Holdability parametervalue is ignored.

Yes3.0void setHoldability(int)

Yes1.0void setReadOnly(boolean)




Connection Methods

The DB2 driver only supports with DB2 V8.xand higher for Linux/UNIX/Windows, DB2for z/OS (all versions), and DB2 for i. Inaddition, the DB2 driver only supportsmultiple nested savepoints for DB2 V8.2 andhigher for Linux/UNIX/Windows.


Yes3.0Savepoint setSavepoint()

The DB2 driver only supports with DB2 V8.xand higher for Linux/UNIX/Windows, DB2for z/OS (all versions), and DB2 for i. Inaddition, the DB2 driver only supportsmultiple nested savepoints for DB2 V8.2 andhigher for Linux/UNIX/Windows.


Yes3.0Savepoint setSavepoint(String)

The drivers for Apache Cassandra, ApacheHive, Apache Spark SQL, Impala,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforceignore any specified transaction isolationlevel.

Yes1.0void setTransactionIsolation(int)

The drivers ignore this connection method.Yes2.0 Corevoid setTypeMap(Map)


ConnectionEventListenerCommentsSupportedVersion

IntroducedConnectionEventListener Methods

Yes3.0void connectionClosed(event)

Yes3.0void connectionErrorOccurred(event)


ConnectionEventListener

ConnectionPoolDataSourceCommentsSupportedVersion

IntroducedConnectionPoolDataSource Methods

Yes2.0 Optionalint getLoginTimeout()

Yes2.0 OptionalPrintWriter getLogWriter()

Yes2.0 OptionalPooledConnection getPooledConnection()

Yes2.0 OptionalPooledConnection getPooledConnection(String, String)

Yes2.0 Optionalvoid setLoginTimeout(int)

Yes2.0 Optionalvoid setLogWriter(PrintWriter)

DatabaseMetaDataCommentsSupportedVersion

IntroducedDatabaseMetaData Methods

Yes4.0booleanautoCommitFailureClosesAllResultSets()

Yes1.0boolean allProceduresAreCallable()

Yes1.0boolean allTablesAreSelectable()

Yes1.0booleandataDefinitionCausesTransactionCommit()

Yes1.0booleandataDefinitionIgnoredInTransactions()

Yes2.0 Coreboolean deletesAreDetected(int)

Not supported by the SQL Server andSybase drivers.

Yes1.0boolean doesMaxRowSizeIncludeBlobs()

The Oracle driver may return results.

All other drivers return an empty result set.

Yes3.0getAttributes(String, String, String, String)

Yes1.0ResultSet getBestRowIdentifier(String,String, String, int, boolean)




DatabaseMetaData Methods

Yes1.0ResultSet getCatalogs()

Yes1.0String getCatalogSeparator()

Yes1.0String getCatalogTerm()


Yes4.0String getClientInfoProperties()

Not supported by the drivers for ApacheHive, Apache Spark SQL, Impala, OracleEloqua, and Oracle Sales Cloud.

Yes1.0ResultSet getColumnPrivileges(String,String, String, String)

Yes1.0ResultSet getColumns(String, String, String,String)

Yes2.0 CoreConnection getConnection()

Yes1.0ResultSet getCrossReference(String, String,String, String, String, String)

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcereturn an empty result set.

Not supported by the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes4.0ResultSet getFunctions()

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcereturn an empty result set.

Not supported by the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes4.0ResultSet getFunctionColumns()

Yes3.0int getDatabaseMajorVersion()

Yes3.0int getDatabaseMinorVersion()

Yes1.0String getDatabaseProductName()

Yes1.0String getDatabaseProductVersion()

Yes1.0int getDefaultTransactionIsolation()

Yes1.0int getDriverMajorVersion()


DatabaseMetaData



Yes1.0int getDriverMinorVersion()

Yes1.0String getDriverName()

Yes1.0String getDriverVersion()

Yes1.0ResultSet getExportedKeys(String, String,String)

Yes1.0String getExtraNameCharacters()

Yes1.0String getIdentifierQuoteString()

Yes1.0ResultSet getImportedKeys(String, String,String)

Yes1.0ResultSet getIndexInfo(String, String, String,boolean, boolean)

Yes3.0int getJDBCMajorVersion()

Yes3.0int getJDBCMinorVersion()

Yes1.0int getMaxBinaryLiteralLength()

Yes1.0int getMaxCatalogNameLength()

Yes1.0int getMaxCharLiteralLength()

Yes1.0int getMaxColumnNameLength()

Yes1.0int getMaxColumnsInGroupBy()

Yes1.0int getMaxColumnsInIndex()

Yes1.0int getMaxColumnsInOrderBy()

Yes1.0int getMaxColumnsInSelect()

Yes1.0int getMaxColumnsInTable()

Yes1.0int getMaxConnections()

Yes1.0int getMaxCursorNameLength()

Yes1.0int getMaxIndexLength()

Yes1.0int getMaxProcedureNameLength()

Yes1.0int getMaxRowSize()





Yes1.0int getMaxSchemaNameLength()

Yes1.0int getMaxStatementLength()

Yes1.0int getMaxStatements()

Yes1.0int getMaxTableNameLength()

Yes1.0int getMaxTablesInSelect()

Yes1.0int getMaxUserNameLength()

Yes1.0String getNumericFunctions()

Yes1.0ResultSet getPrimaryKeys(String, String,String)

For the drivers for Oracle Service Cloud,and Salesforce, SchemaName andProcedureName must be explicit values;they cannot be patterns.

The drivers for Apache Cassandra andMongoDB return an empty result set.

Not supported for the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes1.0ResultSet getProcedureColumns(String,String, String, String)

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, and Oracle SalesCloud return an empty result set.

Not supported for the drivers for ApacheHive, Apache Spark SQL, or Impala.

Yes1.0ResultSet getProcedures(String, String,String)

Yes1.0String getProcedureTerm()

Yes3.0int getResultSetHoldability()

Yes1.0ResultSet getSchemas()

Yes4.0ResultSet getSchemas(catalog, pattern)

Yes1.0String getSchemaTerm()

Yes1.0String getSearchStringEscape()

Yes1.0String getSQLKeywords()

Yes3.0int getSQLStateType()

Yes1.0String getStringFunctions()


DatabaseMetaData



Returns an empty result set.Yes3.0ResultSet getSuperTables(String, String,String)

Returns an empty result set.Yes3.0ResultSet getSuperTypes(String, String,String)

Yes1.0String getSystemFunctions()

Not supported for the drivers for ApacheHive, Apache Spark SQL, Impala, OracleEloqua, and Oracle Sales Cloud.

Yes1.0ResultSet getTablePrivileges(String, String,String)

Yes1.0ResultSet getTables(String, String, String,String [])

Yes1.0ResultSet getTableTypes()

Yes1.0String getTimeDateFunctions()

Yes1.0ResultSet getTypeInfo()

Supported for Oracle only.Yes2.0 CoreResultSet getUDTs(String, String, String,int [])

Yes1.0String getURL()

Yes1.0String getUserName()

Yes1.0ResultSet getVersionColumns(String, String,String)

Yes2.0 Coreboolean insertsAreDetected(int)

Yes1.0boolean isCatalogAtStart()

Yes1.0boolean isReadOnly()


Yes3.0boolean locatorsUpdateCopy()

Yes1.0boolean nullPlusNonNullIsNull()

Yes1.0boolean nullsAreSortedAtEnd()

Yes1.0boolean nullsAreSortedAtStart()

Yes1.0boolean nullsAreSortedHigh()

Yes1.0boolean nullsAreSortedLow()





Yes2.0 Coreboolean othersDeletesAreVisible(int)

Yes2.0 Coreboolean othersInsertsAreVisible(int)

Yes2.0 Coreboolean othersUpdatesAreVisible(int)

Yes2.0 Coreboolean ownDeletesAreVisible(int)

Yes2.0 Coreboolean ownInsertsAreVisible(int)

Yes2.0 Coreboolean ownUpdatesAreVisible(int)

Yes1.0boolean storesLowerCaseIdentifiers()

Yes1.0booleanstoresLowerCaseQuotedIdentifiers()

Yes1.0boolean storesMixedCaseIdentifiers()

Yes1.0booleanstoresMixedCaseQuotedIdentifiers()

Yes1.0boolean storesUpperCaseIdentifiers()

Yes1.0booleanstoresUpperCaseQuotedIdentifiers()

Yes1.0booleansupportsAlterTableWithAddColumn()

Yes1.0booleansupportsAlterTableWithDropColumn()

Yes1.0boolean supportsANSI92EntryLevelSQL()

Yes1.0boolean supportsANSI92FullSQL()

Yes1.0boolean supportsANSI92IntermediateSQL()

Yes2.0 Coreboolean supportsBatchUpdates()

Yes1.0booleansupportsCatalogsInDataManipulation()

Yes1.0booleansupportsCatalogsInIndexDefinitions()

Yes1.0booleansupportsCatalogsInPrivilegeDefinitions()


DatabaseMetaData



Yes1.0booleansupportsCatalogsInProcedureCalls()

Yes1.0booleansupportsCatalogsInTableDefinitions()

Yes1.0boolean supportsColumnAliasing()

Yes1.0boolean supportsConvert()

Yes1.0boolean supportsConvert(int, int)

Yes1.0boolean supportsCoreSQLGrammar()

Yes1.0boolean supportsCorrelatedSubqueries()

Yes1.0boolean supportsDataDefinitionAndDataManipulationTransactions()

Yes1.0booleansupportsDataManipulationTransactionsOnly()

Yes1.0booleansupportsDifferentTableCorrelationNames()

Yes1.0boolean supportsExpressionsInOrderBy()

Yes1.0boolean supportsExtendedSQLGrammar()

Yes1.0boolean supportsFullOuterJoins()

Yes3.0boolean supportsGetGeneratedKeys()

Yes1.0boolean supportsGroupBy()

Yes1.0boolean supportsGroupByBeyondSelect()

Yes1.0boolean supportsGroupByUnrelated()

Yes1.0booleansupportsIntegrityEnhancementFacility()

Yes1.0boolean supportsLikeEscapeClause()

Yes1.0boolean supportsLimitedOuterJoins()

Yes1.0boolean supportsMinimumSQLGrammar()

Yes1.0boolean supportsMixedCaseIdentifiers()





Yes1.0booleansupportsMixedCaseQuotedIdentifiers()

Yes3.0boolean supportsMultipleOpenResults()

Yes1.0boolean supportsMultipleResultSets()

Yes1.0boolean supportsMultipleTransactions()

Yes3.0boolean supportsNamedParameters()

Yes1.0boolean supportsNonNullableColumns()

Yes1.0booleansupportsOpenCursorsAcrossCommit()

Yes1.0booleansupportsOpenCursorsAcrossRollback()

Yes1.0booleansupportsOpenStatementsAcrossCommit()

Yes1.0booleansupportsOpenStatementsAcrossRollback()

Yes1.0boolean supportsOrderByUnrelated()

Yes1.0boolean supportsOuterJoins()

Yes1.0boolean supportsPositionedDelete()

Yes1.0boolean supportsPositionedUpdate()

Yes2.0 Coreboolean supportsResultSetConcurrency(int,int)

Yes3.0boolean supportsResultSetHoldability(int)

Yes2.0 Coreboolean supportsResultSetType(int)

Yes3.0boolean supportsSavePoints()

Yes1.0booleansupportsSchemasInDataManipulation()

Yes1.0booleansupportsSchemasInIndexDefinitions()

Yes1.0booleansupportsSchemasInPrivilegeDefinitions()


DatabaseMetaData



Yes1.0booleansupportsSchemasInProcedureCalls()

Yes1.0booleansupportsSchemasInTableDefinitions()

Yes1.0boolean supportsSelectForUpdate()

Yes4.0booleansupportsStoredFunctionsUsingCallSyntax()

Yes1.0boolean supportsStoredProcedures()

Yes1.0booleansupportsSubqueriesInComparisons()

Yes1.0boolean supportsSubqueriesInExists()

Yes1.0boolean supportsSubqueriesInIns()

Yes1.0boolean supportsSubqueriesInQuantifieds()

Yes1.0boolean supportsTableCorrelationNames()

Yes1.0booleansupportsTransactionIsolationLevel(int)

Yes1.0boolean supportsTransactions()

Yes1.0boolean supportsUnion()

Yes1.0boolean supportsUnionAll()


Yes2.0 Coreboolean updatesAreDetected(int)

Yes1.0boolean usesLocalFilePerTable()

Yes1.0boolean usesLocalFiles()

DataSourceThe DataSource interface implements the javax.naming.Referenceable and java.io.Serializable interfaces.




DataSource Methods

Yes2.0 OptionalConnection getConnection()

Yes2.0 OptionalConnection getConnection(String, String)

Yes2.0 Optionalint getLoginTimeout()

Yes2.0 OptionalPrintWriter getLogWriter()


Yes2.0 Optionalvoid setLoginTimeout(int)

Enables DataDirect Spy, which traces JDBCinformation into the specified PrintWriter.

Yes2.0 Optionalvoid setLogWriter(PrintWriter)


DriverCommentsSupportedVersion

IntroducedDriver Methods

Yes1.0boolean acceptsURL(String)

Yes1.0Connection connect(String, Properties)

Yes1.0int getMajorVersion()

Yes1.0int getMinorVersion()

Yes1.0DriverPropertyInfo [] getPropertyInfo(String,Properties)

ParameterMetaDataCommentsSupportedVersion

IntroducedParameterMetaData Methods

The DB2 driver supports parametermetadata for stored procedures forDB2 V8.x and higher forLinux/UNIX/Windows, DB2 for z/OS (allversions), and DB2 for i.

Yes3.0String getParameterClassName(int)


Driver


ParameterMetaData Methods

Yes3.0int getParameterCount()


Yes3.0int getParameterMode(int)


Yes3.0int getParameterType(int)


Yes3.0String getParameterTypeName(int)


Yes3.0int getPrecision(int)


Yes3.0int getScale(int)


Yes3.0int isNullable(int)


Yes3.0boolean isSigned(int)


Yes1.0boolean jdbcCompliant()




PooledConnectionCommentsSupportedVersion

IntroducedPooledConnection Methods

Yes2.0 Optionalvoid addConnectionEventListener(listener)

Yes4.0void addStatementEventListener(listener)

Yes2.0 Optionalvoid close()

A pooled connection object can have onlyone Connection object open (the one mostrecently created). The purpose of allowingthe server (PoolManager implementation)to invoke this a second time is to give anapplication server a way to take aconnection away from an application andgive it to another user (a rare occurrence).The drivers do not support the "reclaiming"of connections and will throw an exception.

Yes2.0 OptionalConnection getConnection()

Yes2.0 OptionalvoidremoveConnectionEventListener(listener)

Yes4.0voidremoveStatementEventListener(listener)

PreparedStatementCommentsSupportedVersion

IntroducedPreparedStatement Methods

Yes2.0 Corevoid addBatch()

Yes1.0void clearParameters()

Yes1.0boolean execute()

Yes1.0ResultSet executeQuery()

Yes1.0int executeUpdate()

Yes2.0 CoreResultSetMetaData getMetaData()

Yes3.0ParameterMetaDatagetParameterMetaData()


PooledConnection


PreparedStatement Methods



All other drivers throw an "unsupportedmethod" exception.

Yes2.0 Corevoid setArray(int, Array)

Yes4.0void setAsciiStream(int, InputStream)

Yes1.0void setAsciiStream(int, InputStream, int)

Yes4.0void setAsciiStream(int, InputStream, long)

Yes1.0void setBigDecimal(int, BigDecimal)

When used with Blobs, the DB2 driver onlysupports with DB2 V8.x and higher forLinux/UNIX/Windows, DB2 for z/OS (allversions), and DB2 for i.

Yes4.0void setBinaryStream(int, InputStream)


Yes1.0void setBinaryStream(int, InputStream, int)


Yes4.0void setBinaryStream(int, InputStream, long)


All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes2.0 Corevoid setBlob(int, Blob)



Yes4.0void setBlob(int, InputStream)







Yes4.0void setBlob(int, InputStream, long)

Yes1.0void setBoolean(int, boolean)

Yes1.0void setByte(int, byte)


Yes1.0void setBytes(int, byte [])

Yes4.0void setCharacterStream(int, Reader)

Yes2.0 Corevoid setCharacterStream(int, Reader, int)

Yes4.0void setCharacterStream(int, Reader, long)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes2.0 Corevoid setClob(int, Clob)


Yes4.0void setClob(int, Reader)


Yes4.0void setClob(int, Reader, long)

Yes1.0void setDate(int, Date)

Yes2.0 Corevoid setDate(int, Date, Calendar)

Yes1.0void setDouble(int, double)

Yes1.0void setFloat(int, float)

Yes1.0void setInt(int, int)

Yes1.0void setLong(int, long)


PreparedStatement



For the drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, N methods are identical to theirnon-N counterparts.

Yes4.0void setNCharacterStream(int, Reader)

For the drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce,N methods are identical to theirnon-N counterparts.

Yes4.0void setNCharacterStream(int, Reader, long)


Yes4.0void setNClob(int, NClob)


Yes4.0void setNClob(int, Reader)


Yes4.0void setNClob(int, Reader, long)

Yes1.0void setNull(int, int)

Yes2.0 Corevoid setNull(int, int, String)

Yes4.0void setNString(int, String)

Yes1.0void setObject(int, Object)

Yes1.0void setObject(int, Object, int)

Yes1.0void setObject(int, Object, int, int)





The DB2 driver supports setting a timeoutvalue, in seconds, for a statement withDB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the execution of thestatement exceeds the timeout value, thestatement is timed out by the databaseserver, and the driver throws an exceptionindicating that the statement was timed out.The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The Informix driver throws an "unsupportedmethod" exception.

The drivers for MongoDB, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,and Salesforce ignore any value set usingthis method. Use theWSTimeout connectionproperty to set a timeout value.

The drivers for Apache Cassandra andMongoDB ignore any value set using thismethod.

All other drivers support setting a timeoutvalue, in seconds, for a statement. If theexecution of the statement exceeds thetimeout value, the statement is timed out bythe database server, and the driver throwsan exception indicating that the statementwas timed out.

Yes1.0void setQueryTimeout(int)


No2.0 Corevoid setRef(int, Ref)

Yes1.0void setShort(int, short)

Yes4.0void setSQLXML(int, SQLXML)

Yes1.0void setString(int, String)

Yes1.0void setTime(int, Time)

Yes2.0 Corevoid setTime(int, Time, Calendar)

Yes1.0void setTimestamp(int, Timestamp)

Yes2.0 Corevoid setTimestamp(int, Timestamp,Calendar)


PreparedStatement



This method was deprecated in JDBC 2.0.All drivers throw "unsupported method"exception.

No1.0void setUnicodeStream(int, InputStream,int)



No3.0void setURL(int, URL)

RefCommentsSupportedVersion

IntroducedRef MethodsRef interface

No2.0 Core(all)

ResultSetCommentsSupportedVersion

IntroducedResultSet Methods

Yes2.0 Coreboolean absolute(int)

Yes2.0 Corevoid afterLast()

Yes2.0 Corevoid beforeFirst()

Yes2.0 Corevoid cancelRowUpdates()


Yes1.0void close()

Yes2.0 Corevoid deleteRow()

Yes1.0int findColumn(String)

Yes2.0 Coreboolean first()

Yes2.0 CoreArray getArray(int)


No2.0 CoreArray getArray(String)




ResultSet Methods

Yes1.0InputStream getAsciiStream(int)

Yes1.0InputStream getAsciiStream(String)

Yes2.0 CoreBigDecimal getBigDecimal(int)

Yes1.0BigDecimal getBigDecimal(int, int)

Yes2.0 CoreBigDecimal getBigDecimal(String)

Yes1.0BigDecimal getBigDecimal(String, int)

The DB2 driver supports for all DB2 versionswhen retrieving BINARY, VARBINARY, andLONGVARBINARY data. The DB2 driveronly supports with DB2 V8.x and higher forLinux/UNIX/Windows, DB2 for z/OS (allversions), and DB2 for i when retrieving Blobdata.

Yes1.0InputStream getBinaryStream(int)


Yes1.0InputStream getBinaryStream(String)



Yes2.0 CoreBlob getBlob(int)



Yes2.0 CoreBlob getBlob(String)

Yes1.0boolean getBoolean(int)

Yes1.0boolean getBoolean(String)

Yes1.0byte getByte(int)

Yes1.0byte getByte(String)


ResultSet


ResultSet Methods


Yes1.0byte [] getBytes(int)


Yes1.0byte [] getBytes(String)

Yes2.0 CoreReader getCharacterStream(int)

Yes2.0 CoreReader getCharacterStream(String)


Yes2.0 CoreClob getClob(int)


Yes2.0 CoreClob getClob(String)

Yes2.0 Coreint getConcurrency()


No1.0String getCursorName()

Yes1.0Date getDate(int)

Yes2.0 CoreDate getDate(int, Calendar)

Yes1.0Date getDate(String)

Yes2.0 CoreDate getDate(String, Calendar)

Yes1.0double getDouble(int)

Yes1.0double getDouble(String)

Yes2.0 Coreint getFetchDirection()

Yes2.0 Coreint getFetchSize()

Yes1.0float getFloat(int)




ResultSet Methods

Yes1.0float getFloat(String)

Yes4.0int getHoldability()

Yes1.0int getInt(int)

Yes1.0int getInt(String)

Yes1.0long getLong(int)

Yes1.0long getLong(String)

Yes1.0ResultSetMetaData getMetaData()

Yes4.0Reader getNCharacterStream(int)

Yes4.0Reader getNCharacterStream(String)

Yes4.0NClob getNClob(int)

Yes4.0NClob getNClob(String)

Yes4.0String getNString(int)

Yes4.0String getNString(String)

The DB2 driver returns a Long object whencalled on Bigint columns.

Yes1.0Object getObject(int)

The Oracle and Sybase drivers support theMap argument. For all other drivers, theMapargument is ignored.

Yes2.0 CoreObject getObject(int, Map)

Yes1.0Object getObject(String)

The Oracle and Sybase drivers support theMap argument. For all other drivers, theMapargument is ignored.

Yes2.0 CoreObject getObject(String, Map)


No2.0 CoreRef getRef(int)


No2.0 CoreRef getRef(String)

Yes2.0 Coreint getRow()

Yes1.0short getShort(int)

Yes1.0short getShort(String)


ResultSet


ResultSet Methods

Yes4.0SQLXML getSQLXML(int)

Yes4.0SQLXML getSQLXML(String)

Yes2.0 CoreStatement getStatement()

Yes1.0String getString(int)

Yes1.0String getString(String)

Yes1.0Time getTime(int)

Yes2.0 CoreTime getTime(int, Calendar)

Yes1.0Time getTime(String)

Yes2.0 CoreTime getTime(String, Calendar)

Yes1.0Timestamp getTimestamp(int)

Yes2.0 CoreTimestamp getTimestamp(int, Calendar)

Yes1.0Timestamp getTimestamp(String)

Yes2.0 CoreTimestamp getTimestamp(String, Calendar)

Yes2.0 Coreint getType()


No1.0InputStream getUnicodeStream(int)


No1.0InputStream getUnicodeStream(String)


No3.0URL getURL(int)


No3.0URL getURL(String)


Yes2.0 Corevoid insertRow()

Yes2.0 Coreboolean isAfterLast()

Yes2.0 Coreboolean isBeforeFirst()




ResultSet Methods


Yes2.0 Coreboolean isFirst()

Yes2.0 Coreboolean isLast()


Yes2.0 Coreboolean last()

Yes2.0 Corevoid moveToCurrentRow()

Yes2.0 Corevoid moveToInsertRow()

Yes1.0boolean next()

Yes2.0 Coreboolean previous()

Yes2.0 Corevoid refreshRow()

Yes2.0 Coreboolean relative(int)

Yes2.0 Coreboolean rowDeleted()

Yes2.0 Coreboolean rowInserted()

Yes2.0 Coreboolean rowUpdated()

Yes2.0 Corevoid setFetchDirection(int)

Yes2.0 Corevoid setFetchSize(int)



No3.0void updateArray(int, Array)


No3.0void updateArray(String, Array)

Yes2.0 Corevoid updateAsciiStream(int, InputStream,int)

Yes4.0void updateAsciiStream(int, InputStream,long)

Yes4.0void updateAsciiStream(String, InputStream)

Yes2.0 Corevoid updateAsciiStream(String, InputStream,int)


ResultSet


ResultSet Methods

Yes4.0void updateAsciiStream(String, InputStream,long)

Yes2.0 Corevoid updateBigDecimal(int, BigDecimal)

Yes2.0 Corevoid updateBigDecimal(String, BigDecimal)

Yes4.0void updateBinaryStream(int, InputStream)

Yes2.0 Corevoid updateBinaryStream(int, InputStream,int)

Yes4.0void updateBinaryStream(int, InputStream,long)

Yes4.0void updateBinaryStream(String,InputStream)

Yes2.0 Corevoid updateBinaryStream(String,InputStream, int)

Yes4.0void updateBinaryStream(String,InputStream, long)



Yes3.0void updateBlob(int, Blob)



Yes4.0void updateBlob(int, InputStream)



Yes4.0void updateBlob(int, InputStream, long)




ResultSet Methods



Yes3.0void updateBlob(String, Blob)



Yes4.0void updateBlob(String, InputStream)



Yes4.0void updateBlob(String, InputStream, long)

Yes2.0 Corevoid updateBoolean(int, boolean)

Yes2.0 Corevoid updateBoolean(String, boolean)

Yes2.0 Corevoid updateByte(int, byte)

Yes2.0 Corevoid updateByte(String, byte)

Yes2.0 Corevoid updateBytes(int, byte [])

Yes2.0 Corevoid updateBytes(String, byte [])

Yes4.0void updateCharacterStream(int, Reader)

Yes2.0 Corevoid updateCharacterStream(int, Reader,int)

Yes4.0void updateCharacterStream(int, Reader,long)

Yes4.0void updateCharacterStream(String,Reader)

Yes2.0 Corevoid updateCharacterStream(String,Reader, int)

Yes4.0void updateCharacterStream(String,Reader, long)


ResultSet


ResultSet Methods


Yes3.0void updateClob(int, Clob)


Yes4.0void updateClob(int, Reader)


Yes4.0void updateClob(int, Reader, long)


Yes3.0void updateClob(String, Clob)


Yes4.0void updateClob(String, Reader)


Yes4.0void updateClob(String, Reader, long)

Yes2.0 Corevoid updateDate(int, Date)

Yes2.0 Corevoid updateDate(String, Date)

Yes2.0 Corevoid updateDouble(int, double)

Yes2.0 Corevoid updateDouble(String, double)

Yes2.0 Corevoid updateFloat(int, float)

Yes2.0 Corevoid updateFloat(String, float)

Yes2.0 Corevoid updateInt(int, int)

Yes2.0 Corevoid updateInt(String, int)

Yes2.0 Corevoid updateLong(int, long)

Yes2.0 Corevoid updateLong(String, long)

For the drivers for MongoDB, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,and Salesforce, N methods are identical totheir non-N counterparts.

Yes4.0void updateNCharacterStream(int, Reader)




ResultSet Methods


Yes4.0void updateNCharacterStream(int, Reader,long)


Yes4.0void updateNCharacterStream(String,Reader)


Yes4.0void updateNCharacterStream(String,Reader, long)


Yes4.0void updateNClob(int, NClob)


Yes4.0void updateNClob(int, Reader)


Yes4.0void updateNClob(int, Reader, long)


Yes4.0void updateNClob(String, NClob)


Yes4.0void updateNClob(String, Reader)


Yes4.0void updateNClob(String, Reader, long)


Yes4.0void updateNString(int, String)


ResultSet


ResultSet Methods


Yes4.0void updateNString(String, String)

Yes2.0 Corevoid updateNull(int)

Yes2.0 Corevoid updateNull(String)

Yes2.0 Corevoid updateObject(int, Object)

Yes2.0 Corevoid updateObject(int, Object, int)

Yes2.0 Corevoid updateObject(String, Object)

Yes2.0 Corevoid updateObject(String, Object, int)


No3.0void updateRef(int, Ref)


No3.0void updateRef(String, Ref)

Yes2.0 Corevoid updateRow()

Yes2.0 Corevoid updateShort(int, short)

Yes2.0 Corevoid updateShort(String, short)

Yes4.0void updateSQLXML(int, SQLXML)

Yes4.0void updateSQLXML(String, SQLXML)

Yes2.0 Corevoid updateString(int, String)

Yes2.0 Corevoid updateString(String, String)

Yes2.0 Corevoid updateTime(int, Time)

Yes2.0 Corevoid updateTime(String, Time)

Yes2.0 Corevoid updateTimestamp(int, Timestamp)

Yes2.0 Corevoid updateTimestamp(String, Timestamp)

Yes1.0boolean wasNull()



ResultSetMetaDataCommentsSupportedVersion

IntroducedResultSetMetaData Methods

Yes1.0String getCatalogName(int)

Yes2.0 CoreString getColumnClassName(int)

Yes1.0int getColumnCount()

Yes1.0int getColumnDisplaySize(int)

Yes1.0String getColumnLabel(int)

Yes1.0String getColumnName(int)

Yes1.0int getColumnType(int)

Yes1.0String getColumnTypeName(int)

Yes1.0int getPrecision(int)

Yes1.0int getScale(int)

Yes1.0String getSchemaName(int)

Yes1.0String getTableName(int)

Yes1.0boolean isAutoIncrement(int)

Yes1.0boolean isCaseSensitive(int)

Yes1.0boolean isCurrency(int)

Yes1.0boolean isDefinitelyWritable(int)

Yes1.0int isNullable(int)

Yes1.0boolean isReadOnly(int)

Yes1.0boolean isSearchable(int)

Yes1.0boolean isSigned(int)


Yes1.0boolean isWritable(int)



ResultSetMetaData

RowSetCommentsSupportedVersion

IntroducedRowSet Methods

No2.0 Optional(all)

SavePointCommentsSupportedVersion

IntroducedSavePoint Methods

The DB2 driver only supports with DB2 V8.xand higher for Linux/UNIX/Windows, DB2for z/OS ((all versions), and DB2 for i.

Yes3.0(all)

StatementCommentsSupportedVersion

IntroducedStatement Methods

All drivers throw "invalid method call"exception for PreparedStatement andCallableStatement.

Yes2.0 Corevoid addBatch(String)

The DB2 driver cancels the execution of thestatement with DB2 V8.x and higher for

Yes1.0void cancel()

Linux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the statement is canceledby the database server, the driver throwsan exception indicating that it was canceled.The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The drivers for Apache Cassandra, ApacheHive, Apache Spark SQL, Impala, Informix,MongoDB, Progess OpenEdge, OracleService Cloud, Oracle Eloqua, Oracle SalesCloud, and Salesforce throw an"unsupported method" exception.




Statement Methods

The Greenplum, Oracle, PostgreSQL, SQLServer, Sybase, and Amazon Redshiftdrivers cancel the execution of thestatement. If the statement is canceled bythe database server, the driver throws anexception indicating that it was canceled.

Yes2.0 Corevoid clearBatch()


Yes1.0void close()


Yes1.0boolean execute(String)

Yes3.0boolean execute(String, int)



Yes3.0boolean execute(String, int [])



Yes3.0boolean execute(String, String [])

Yes2.0 Coreint [] executeBatch()


Yes1.0ResultSet executeQuery(String)


Yes1.0int executeUpdate(String)

Yes3.0int executeUpdate(String, int)



Yes3.0int executeUpdate(String, int [])


Statement


Statement Methods



Yes3.0int executeUpdate(String, String [])

Yes2.0 CoreConnection getConnection()

Yes2.0 Coreint getFetchDirection()

Yes2.0 Coreint getFetchSize()

The DB2, SQL Server, and Sybase driversreturn the last value inserted into an identity

Yes3.0ResultSet getGeneratedKeys()

column. If an identity column does not existin the table, the drivers return an emptyresult set.

The Informix driver returns the last valueinserted into a Serial or Serial8 column. If aSerial or Serial8 column does not exist inthe table, the driver returns an empty resultset.

The Oracle driver returns the ROWID of thelast row that was inserted.

The drivers for Apache Cassandra,MongoDB, Oracle Eloqua, Oracle ServiceCloud, and Salesforce return the ID of thelast row that was inserted.

Auto-generated keys are not supported inany of the other drivers.

Yes1.0int getMaxFieldSize()

Yes1.0int getMaxRows()

Yes1.0boolean getMoreResults()

Yes3.0boolean getMoreResults(int)

The DB2 driver returns the timeout value,in seconds, set for the statement with

Yes1.0int getQueryTimeout()

DB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. The DB2 driver returns 0with other DB2 versions.

The Informix and Progress OpenEdgedrivers return 0.




Statement Methods

The drivers for Apache Cassandra, ApacheHive, Apache Spark SQL, Impala,Greenplum, Oracle, PostgreSQL,SQL Server, Sybase, and Amazon Redshiftreturn the timeout value, in seconds, set forthe statement.

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcereturn an "unsupported method" exception.

Yes1.0ResultSet getResultSet()

Yes2.0 Coreint getResultSetConcurrency()

Yes3.0int getResultSetHoldability()

Yes2.0 Coreint getResultSetType()

Yes1.0int getUpdateCount()



Yes4.0boolean isPoolable()


Throws "unsupported method" exception.No1.0void setCursorName(String)

Ignored.Yes1.0void setEscapeProcessing(boolean)

Yes2.0 Corevoid setFetchDirection(int)

Yes2.0 Corevoid setFetchSize(int)

Yes1.0void setMaxFieldSize(int)

Yes1.0void setMaxRows(int)

Yes4.0void setPoolable(boolean)

The DB2 driver supports setting a timeoutvalue, in seconds, for a statement with

Yes1.0void setQueryTimeout(int)

DB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the execution of thestatement exceeds the timeout value, thestatement is timed out by the databaseserver, and the driver throws an exception


Statement


Statement Methods

indicating that the statement was timed out.The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The Informix driver throws an "unsupportedmethod" exception.

The drivers for Greenplum, Apache Hive,Apache Spark SQL, Impala, Oracle,PostgreSQL, Progress OpenEdge,SQL Server, Sybase, and Amazon Redshiftsupport setting a timeout value, in seconds,for a statement. If the execution of thestatement exceeds the timeout value, thestatement is timed out by the databaseserver, and the driver throws an exceptionindicating that the statement was timed out.

The drivers for Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforceignore any value set using this method. Usethe WSTimeout connection property to seta timeout.

The drivers for Apache Cassandra andMongoDB driver ignore any value set usingthis method.


StatementEventListenerCommentsSupportedVersion

IntroducedStatementEventListener Methods

Yes4.0void statementClosed(event)

Yes4.0void statementErrorOccurred(event)



StructCommentsSupportedVersion

IntroducedStruct Methods

Supported for the Oracle driver only. Allother drivers throw "unsupported method"exception.

Yes2.0(all)

XAConnectionCommentsSupportedVersion

IntroducedXAConnection Methods

Supported for all drivers except AmazonRedshift, Apache Hive, Apache Spark SQL,DB2 V8.1 for z/OS, Greenplum, Impala,Oracle Eloqua, Oracle Sales Cloud, andPostgreSQL.

Yes2.0 Optional(all)

XADataSourceCommentsSupportedVersion

IntroducedXADataSource Methods



XAResourceCommentsSupportedVersion

IntroducedXAResource Methods




Struct



9JDBC extensions

This section describes the JDBC extensions in the com.ddtek.jdbc.extensions package that can beused with the Oracle Sales Cloud driver.

DescriptionInterface/Class

The methods in this interface are used to extend the standard JDBCmetadata results returned by the DatabaseMetaData.getColumns()method to include an additional column.

DatabaseMetadata

Methods that allow you to determine if DataDirect Spy logging is enabledand turning on and off DataDirect Spy logging if enabled.

ExtLogControl


• DatabaseMetaData interface

• ExtLogControl class

DatabaseMetaData interfaceThe drivers for Oracle Eloqua, Oracle Sales Cloud, Oracle Service Cloud, and Salesforce extend the standardJDBCmetadata results returned by the DatabaseMetaData.getColumns()method to include the followingadditional columns.


Table 22: DatabaseMetaData.getColumns() method


Provides an indication of whether the column can be used as anExternal ID. External ID columns can be used as the lookup columnfor insert and upsert operations and foreign-key relationship values.Valid values are:

• YES: The column can be used as an external ID.

• NO: The column cannot be used as an external ID.

The standard catalog table SYSTEM_COLUMNS is also extended toinclude the IS_EXTERNAL_ID column.

VARCHAR (3), NOTNULL

IS_EXTERNAL_ID

The text label for this column. If not present, this field is null.VARCHAR (128)LABEL

The drivers for Oracle Eloqua, Oracle Sales Cloud, Oracle Service Cloud, and Salesforce extend the standardJDBC metadata results returned by the DatabaseMetaData.getTables()method to include the followingadditional column.

Table 23: DatabaseMetaData.getTables() Method


The text label for this table. If not present, this field is null.VARCHAR (128)LABEL

ExtLogControl classDescriptionExtLogControl Methods

If DataDirect Spy was enabled when the connection was created, youcan turn on or off DataDirect Spy logging at runtime using this method.If true, logging is turned on. If false, logging is turned off. If DataDirectSpy logging was not enabled when the connection was created, callingthis method has no effect.

void setEnableLogging(boolean enable|disable)

Indicates whether DataDirect Spy logging was enabled when theconnection was created and whether logging is turned on. If the returnedvalue is true, logging is turned on. If the returned value is false, loggingis turned off.

boolean getEnableLogging()


Chapter 9: JDBC extensions

10Designing JDBC Applications forPerformance Optimization

Developing performance-oriented JDBC applications is not easy. JDBC drivers do not throw exceptions to tellyou when your code is running too slow. This chapter presents some general guidelines for improving JDBCapplication performance that have been compiled by examining the JDBC implementations of numerousshipping JDBC applications. These guidelines include:

• Use DatabaseMetaData methods appropriately

• Return only required data

• Select functions that optimize performance

• Manage connections and updates

Following these general guidelines can help you solve some common JDBC system performance problems,such as those listed in the following table.

See guidelines in…SolutionProblem

Using DatabaseMetadataMethods onpage 184

Reduce network traffic.Network communication is slow.

Using DatabaseMetadataMethods onpage 184

Selecting JDBC Objects and Methodson page 188

Simplify queries.Evaluation of complex SQL queries onthe database server is slow and canreduce concurrency.


See guidelines in…SolutionProblem

Returning Data on page 186

Selecting JDBC Objects and Methodson page 188

Optimize application-to-driverinteraction.

Excessive calls from the application tothe driver slow performance.

Managing Connections and Updateson page 191

Limit disk I/O.Disk I/O is slow.

In addition, most JDBC drivers provide options that improve performance, often with a trade-off in functionality.If your application is not affected by functionality that is modified by setting a particular option, significantperformance improvements can be realized.

Note: The section describes functionality across a spectrum of data stores. In some cases, the functionalitydescribed may not apply to the driver or data store you are using. In addition, examples are drawn from avariety of drivers and data stores.


• Using Database Metadata Methods

• Returning Data

• Selecting JDBC Objects and Methods

• Managing Connections and Updates

Using Database Metadata MethodsBecause database metadata methods that generate ResultSet objects are slow compared to other JDBCmethods, their frequent use can impair system performance. The guidelines in this section will help you optimizesystem performance when selecting and using database metadata.

Minimizing the Use of Database Metadata MethodsCompared to other JDBCmethods, database metadata methods that generate ResultSet objects are relativelyslow. Applications should cache information returned from result sets that generate database metadata methodsso that multiple executions are not needed.

Although almost no JDBC application can be written without database metadata methods, you can improvesystem performance by minimizing their use. To return all result column information mandated by the JDBCspecification, a JDBC driver may have to perform complex queries or multiple queries to return the necessaryresult set for a single call to a database metadata method. These particular elements of the SQL language areperformance-expensive.

Applications should cache information from database metadata methods. For example, call getTypeInfo() oncein the application and cache the elements of the result set that your application depends on. It is unlikely thatany application uses all elements of the result set generated by a database metadata method, so the cacheof information should not be difficult to maintain.


Chapter 10: Designing JDBC Applications for Performance Optimization

Avoiding Search PatternsUsing null arguments or search patterns in database metadata methods results in generating time-consumingqueries. In addition, network traffic potentially increases due to unwanted results. Always supply as manynon-null arguments as possible to result sets that generate database metadata methods.

Because database metadata methods are slow, invoke them in your applications as efficiently as possible.Many applications pass the fewest non-null arguments necessary for the function to return success. For example:

ResultSet WSrs = WSdbmd.getTables(null, null, "WSTable", null);

In this example, an application uses the getTables() method to determine if the WSTable table exists. A JDBCdriver interprets the request as: return all tables, views, system tables, synonyms, temporary tables, and aliasesnamed "WSTable" that exist in any database schema inside the database catalog.

In contrast, the following request provides non-null arguments as shown:

String[] tableTypes = {"TABLE"};WSdbmd.getTables("cat1", "johng", "WSTable", "tableTypes");

Clearly, a JDBC driver can process the second request more efficiently than it can process the first request.

Sometimes, little information is known about the object for which you are requesting information. Any informationthat the application can send the driver when calling database metadata methods can result in improvedperformance and reliability.

Using a Dummy Query to Determine Table CharacteristicsAvoid using the getColumns() method to determine characteristics about a database table. Instead, use adummy query with getMetadata().

Consider an application that allows the user to choose the columns to be selected. Should the application usegetColumns() to return information about the columns to the user or instead prepare a dummy query and callgetMetadata()?

Case 1: GetColumns() MethodResultSet WSrc = WSc.getColumns(... "UnknownTable" ...);// This call to getColumns will generate a query to// the system catalogs... possibly a join// which must be prepared, executed, and produce// a result set. . .WSrc.next();string Cname = getString(4);. . .// user must return N rows from the server// N = # result columns of UnknownTable// result column information has now been obtained

Case 2: GetMetadata() Method// prepare dummy queryPreparedStatement WSps = WSc.prepareStatement

("SELECT * FROM UnknownTable WHERE 1 = 0");// query is never executed on the server - only preparedResultSetMetaData WSsmd=WSps.getMetaData();int numcols = WSrsmd.getColumnCount();...


Using Database Metadata Methods

int ctype = WSrsmd.getColumnType(n)...// result column information has now been obtained// Note we also know the column ordering within the// table! This information cannot be// assumed from the getColumns example.

In both cases, a query is sent to the server. However, in Case 1, the potentially complex query must be preparedand executed, result description information must be formulated, and a result set of rows must be sent to theclient. In Case 2, we prepare a simple query where we only return result set information. Clearly, Case 2 is thebetter performing model.

To somewhat complicate this discussion, let us consider a DBMS server that does not natively support preparinga SQL statement. The performance of Case 1 does not change but the performance of Case 2 improves slightlybecause the dummy query must be evaluated in addition to being prepared. Because the Where clause of thequery always evaluates to FALSE, the query generates no result rows and should execute without accessingtable data. For this situation, Case 2 still outperforms Case 1.

In summary, always use result set metadata to return table column information, such as column names, columndata types, and column precision and scale. Only use the getColumns() method when the requested informationcannot be obtained from result set metadata (for example, using the table column default values).

Returning DataTo return data efficiently, return only the data that you need and choose the most efficient method of doing so.The guidelines in this section will help you optimize system performance when retrieving data with JDBCapplications.

Returning Long DataBecause retrieving long data across a network is slow and resource intensive, applications should not requestlong data unless it is necessary.

Most users do not want to see long data. If the user does want to see these result items, then the applicationcan query the database again, specifying only the long columns in the Select list. This method allows theaverage user to return the result set without having to pay a high performance penalty for network traffic.

Although the best method is to exclude long data from the Select list, some applications do not formulate theSelect list before sending the query to the JDBC driver (that is, some applications SELECT * FROMtable_name ...). If the Select list contains long data, most drivers are forced to return that long data at fetchtime, even if the application does not ask for the long data in the result set. When possible, the designer shouldattempt to implement a method that does not return all columns of the table.

For example, consider the following code:

ResultSet rs = stmt.executeQuery("SELECT * FROM Employees WHERE SSID = '999-99-2222'");

rs.next();string name = rs.getString(1);



Remember that a JDBC driver cannot interpret an application's final intention. When a query is executed, thedriver has no way to know which result columns an application will use. A driver anticipates that an applicationcan request any of the result columns that are returned. When the JDBC driver processes the rs.next request,it will probably return at least one, if not more, result rows from the database server across the network. In thiscase, a result row contains all the column values for each row, including an employee photograph if theEmployees table contains such a column. If you limit the Select list to contain only the employee name column,it results in decreased network traffic and a faster performing query at runtime. For example:

ResultSet rs = stmt.executeQuery("SELECT name FROM Employees WHERE SSID = '999-99-2222'");

rs.next();string name = rs.getString(1);

Additionally, although the getClob() and getBlob() methods allow the application to control how long data isreturned in the application, the designer must realize that in many cases, the JDBC driver emulates thesemethods due to the lack of true Large Object (LOB) locator support in the DBMS. In such cases, the drivermust return all the long data across the network before exposing the getClob() and getBlob() methods.

Reducing the Size of Returned DataSometimes long data must be returned. When this is the case, remember that most users do not want to see100 KB, or more, of text on the screen.

To reduce network traffic and improve performance, you can reduce the size of any data being returned tosome manageable limit by calling setMaxRows(), setMaxFieldSize(), and the driver-specific setFetchSize().Another method of reducing the size of the data being returned is to decrease the column size.

In addition, be careful to return only the rows you need. If you return five columns when you only need twocolumns, performance is decreased, especially if the unnecessary rows include long data.

Choosing the Right Data TypeRetrieving and sending certain data types can be expensive. When you design a schema, select the data typethat can be processed most efficiently. For example, integer data is processed faster than floating-point data.Floating-point data is defined according to internal database-specific formats, usually in a compressed format.The data must be decompressed and converted into a different format so that it can be processed by thedatabase wire protocol.

Retrieving Result SetsMost JDBC drivers cannot implement scrollable cursors because of limited support for scrollable cursors in thedatabase system. Unless you are certain that the database supports using a scrollable result set, rs, for example,do not call rs.last and rs.getRow() methods to find out how many rows the result set contains. For JDBC driversthat emulate scrollable cursors, calling rs.last results in the driver retrieving all results across the network toreach the last row. Instead, you can either count the rows by iterating through the result set or get the numberof rows by submitting a query with a Count column in the Select clause.

In general, do not write code that relies on the number of result rows from a query because drivers must fetchall rows in a result set to know how many rows the query will return.


Returning Data

Selecting JDBC Objects and MethodsThe guidelines in this section will help you to select which JDBC objects and methods will give you the bestperformance.

Using Parameter Markers as Arguments to Stored ProceduresWhen calling stored procedures, always use parameter markers for argument markers instead of using literalarguments. JDBC drivers can call stored procedures on the database server either by executing the procedureas a SQL query or by optimizing the execution by invoking a Remote Procedure Call (RPC) directly on thedatabase server. When you execute a stored procedure as a SQL query, the database server parses thestatement, validates the argument types, and converts the arguments into the correct data types.

Remember that SQL is always sent to the database server as a character string, for example, {callgetCustName(12345)}. In this case, even though the application programmer may have assumed that theonly argument to getCustName() was an integer, the argument is actually passed inside a character string tothe server. The database server parses the SQL query, isolates the single argument value 12345, and convertsthe string 12345 into an integer value before executing the procedure as a SQL language event.

By invoking a RPC on the database server, the overhead of using a SQL character string is avoided. Instead,the JDBC driver constructs a network packet that contains the parameters in their native data type formats andexecutes the procedure remotely.

Case 1: Not Using a Server-Side RPCIn this example, the stored procedure getCustName() cannot be optimized to use a server-side RPC. Thedatabase server must treat the SQL request as a normal language event, which includes parsing the statement,validating the argument types, and converting the arguments into the correct data types before executing theprocedure.

CallableStatement cstmt = conn.prepareCall("call getCustName(12345)");ResultSet rs = cstmt.executeQuery();

Case 2: Using a Server-Side RPCIn this example, the stored procedure getCustName() can be optimized to use a server-side RPC. Becausethe application avoids literal arguments and calls the procedure by specifying all arguments as parameters,the JDBC driver can optimize the execution by invoking the stored procedure directly on the database as anRPC. The SQL language processing on the database server is avoided and execution time is greatly improved.

CallableStatement cstmt = conn.prepareCall("call getCustName(?)}");cstmt.setLong(1,12345);ResultSet rs = cstmt.executeQuery();

Using the StatementObject Instead of the PreparedStatementObjectJDBC drivers are optimized based on the perceived use of the functions that are being executed. Choosebetween the PreparedStatement object and the Statement object depending on how you plan to use the object.The Statement object is optimized for a single execution of a SQL statement. In contrast, the PreparedStatementobject is optimized for SQL statements to be executed two or more times.



The overhead for the initial execution of a PreparedStatement object is high. The advantage comes withsubsequent executions of the SQL statement. For example, suppose we are preparing and executing a querythat returns employee information based on an ID. Using a PreparedStatement object, a JDBC driver wouldprocess the prepare request by making a network request to the database server to parse and optimize thequery. The execute results in another network request. If the application will only make this request once duringits life span, using a Statement object instead of a PreparedStatement object results in only a single networkroundtrip to the database server. Reducing network communication typically provides the most performancegains.

This guideline is complicated by the use of prepared statement pooling because the scope of execution islonger. When using prepared statement pooling, if a query will only be executed once, use the Statementobject. If a query will be executed infrequently, but may be executed again during the life of a statement poolinside a connection pool, use a PreparedStatement object. Under similar circumstances without statementpooling, use the Statement object.

Using Batches Instead of Prepared StatementsUpdating large amounts of data typically is done by preparing an Insert statement and executing that statementmultiple times, resulting in numerous network roundtrips. To reduce the number of JDBC calls and improveperformance, you can send multiple queries to the database at a time using the addBatch method of thePreparedStatement object. For example, let us compare the following examples, Case 1 and Case 2.

Case 1: Executing Prepared Statement Multiple TimesPreparedStatement ps = conn.prepareStatement(

"INSERT INTO employees VALUES (?, ?, ?)");for (n = 0; n < 100; n++) {

ps.setString(name[n]);ps.setLong(id[n]);ps.setInt(salary[n]);ps.executeUpdate();

}

Case 2: Using a BatchPreparedStatement ps = conn.prepareStatement(

"INSERT INTO employees VALUES (?, ?, ?)");for (n = 0; n < 100; n++) {

ps.setString(name[n]);ps.setLong(id[n]);ps.setInt(salary[n]);ps.addBatch();

}ps.executeBatch();

In Case 1, a prepared statement is used to execute an Insert statement multiple times. In this case, 101 networkroundtrips are required to perform 100 Insert operations: one roundtrip to prepare the statement and 100additional roundtrips to execute its iterations. When the addBatch method is used to consolidate 100 Insertoperations, as demonstrated in Case 2, only two network roundtrips are required—one to prepare the statementand another to execute the batch. Although more database CPU cycles are involved by using batches,performance is gained through the reduction of network roundtrips. Remember that the biggest gain inperformance is realized by reducing network communication between the JDBC driver and the database server.


Selecting JDBC Objects and Methods

Choosing the Right CursorChoosing the appropriate type of cursor allows maximum application flexibility. This section summarizes theperformance issues of three types of cursors: forward-only, insensitive, and sensitive.

A forward-only cursor provides excellent performance for sequential reads of all rows in a table. For retrievingtable data, there is no faster way to return result rows than using a forward-only cursor; however, forward-onlycursors cannot be used when the rows to be returned are not sequential.

Insensitive cursors are ideal for applications that require high levels of concurrency on the database serverand require the ability to scroll forwards and backwards through result sets. The first request to an insensitivecursor fetches all the rows and stores them on the client. In most cases, the first request to an insensitive cursorfetches all the rows and stores them on the client. If a driver uses "lazy" fetching (fetch-on-demand), the firstrequest may include many rows, if not all rows.The initial request is slow, especially when long data is returned.Subsequent requests do not require any network traffic (or, when a driver uses "lazy" fetching, requires limitednetwork traffic) and are processed quickly.

Because the first request is processed slowly, insensitive cursors should not be used for a single request ofone row. Developers should also avoid using insensitive cursors when long data or large result sets are returnedbecause memory can be exhausted. Some insensitive cursor implementations cache the data in a temporarytable on the database server and avoid the performance issue, but most cache the information local to theapplication.

Sensitive cursors, or keyset-driven cursors, use identifiers such as a ROWID that already exist in the database.When you scroll through the result set, the data for these identifiers is returned. Because each request generatesnetwork traffic, performance can be very slow. However, returning non-sequential rows does not further affectperformance.

To illustrate this point further, consider an application that normally returns 1000 rows to an application. Atexecute time, or when the first row is requested, a JDBC driver does not execute the Select statement thatwas provided by the application. Instead, the JDBC driver replaces the Select list of the query with a keyidentifier, for example, ROWID. This modified query is then executed by the driver and all 1000 key values arereturned by the database server and cached for use by the driver. Each request from the application for a resultrow directs the JDBC driver to look up the key value for the appropriate row in its local cache, construct anoptimized query that contains a Where clause similar to WHERE ROWID=?, execute the modified query, andreturn the single result row from the server.

Sensitive cursors are the preferred scrollable cursor model for dynamic situations when the application cannotafford to buffer the data associated with an insensitive cursor.

Using get Methods EffectivelyJDBC provides a variety of methods to return data from a result set (for example, getInt(), getString(), andgetObject()). The getObject() method is the most generic and provides the worst performance when thenon-default mappings are specified because the JDBC driver must perform extra processing to determine thetype of the value being returned and generate the appropriate mapping. Always use the specific method forthe data type.

To further improve performance, provide the column number of the column being returned, for example,getString(1), getLong(2), and getInt(3), instead of the column name. If the column names are notspecified, network traffic is unaffected, but costly conversions and lookups increase. For example, supposeyou use:

getString("foo")...

The JDBC driver may need to convert foo to uppercase and then compare foo with all columns in the columnlist, which is costly. If the driver is able to go directly to result column 23, a large amount of processing is saved.



For example, suppose you have a result set that has 15 columns and 100 rows, and the column names arenot included in the result set. You are interested in only three columns: EMPLOYEENAME (string),EMPLOYEENUMBER (long integer), and SALARY (integer). If you specify getString("EmployeeName"),getLong("EmployeeNumber"), and getInt("Salary"), each column name must be converted to theappropriate case of the columns in the database metadata and lookups would increase considerably.Performance improves significantly if you specify getString(1), getLong(2), and getInt(15).

Retrieving Auto Generated KeysMany databases have hidden columns (pseudo-columns) that represent a unique key for each row in a table.Typically, using these types of columns in a query is the fastest way to access a row because thepseudo-columns usually represent the physical disk address of the data. Prior to JDBC 3.0, an applicationcould only return the value of the pseudo-columns by executing a Select statement immediately after insertingthe data. For example:

//insert rowint rowcount = stmt.executeUpdate (

"INSERT INTO LocalGeniusList (name)VALUES ('Karen')");

// now get the disk address – rowid -// for the newly inserted rowResultSet rs = stmt.executeQuery (

"SELECT rowid FROM LocalGeniusListWHERE name = 'Karen'");

Retrieving pseudo-columns this way has twomajor flaws. First, retrieving the pseudo-column requires a separatequery to be sent over the network and executed on the server. Second, because there may not be a primarykey over the table, the search condition of the query may be unable to uniquely identify the row. In the lattercase, multiple pseudo-column values can be returned, and the application may not be able to determine whichvalue is actually the value for the most recently inserted row.

An optional feature of the JDBC 3.0 specification is the ability to return auto-generated key information for arow when the row is inserted into a table. For example:

int rowcount = stmt.executeUpdate("INSERT INTO LocalGeniusList(name) VALUES('Karen')",

// insert row AND return keyStatement.RETURN_GENERATED_KEYS);ResultSet rs = stmt.getGeneratedKeys();// key is automatically available

Now, the application contains a value that can be used in a search condition to provide the fastest access tothe row and a value that uniquely identifies the row, even when a primary key doesn't exist on the table.

The ability to return keys provides flexibility to the JDBC developer and creates performance boosts whenaccessing data.

Managing Connections and UpdatesThe guidelines in this section will help you to manage connections and updates to improve system performancefor your JDBC applications.


Managing Connections and Updates

Managing ConnectionsConnection management is important to application performance. Optimize your application by connectingonce and using multiple Statement objects, instead of performing multiple connections. Avoid connecting to adata source after establishing an initial connection.

Although gathering driver information at connect time is a good practice, it is often more efficient to gather it inone step rather than two steps. For example, some applications establish a connection and then call a methodin a separate component that reattaches and gathers information about the driver. Applications that are designedas separate entities should pass the established connection object to the data collection routine instead ofestablishing a second connection.

Another bad practice is to connect and disconnect several times throughout your application to perform SQLstatements. Connection objects can have multiple Statement objects associated with them. Statement objects,which are defined to be memory storage for information about SQL statements, can manage multiple SQLstatements.

You can improve performance significantly with connection pooling, especially for applications that connectover a network or through the World Wide Web. Connection pooling lets you reuse connections. Closingconnections does not close the physical connection to the database.When an application requests a connection,an active connection is reused, thus avoiding the network round trips needed to create a new connection.

Typically, you can configure a connection pool to provide scalability for connections. The goal is to maintain areasonable connection pool size while ensuring that each user who needs a connection has one availablewithin an acceptable response time. To achieve this goal, you can configure the minimum andmaximum numberof connections that are in the pool at any given time, and how long idle connections stay in the pool. In addition,to help minimize the number of connections required in a connection pool, you can switch the user associatedwith a connection to another user, a process known as reauthentication. Not all databases supportreauthentication.

In addition to connection pooling tuning options, JDBC also specifies semantics for providing a preparedstatement pool. Similar to connection pooling, a prepared statement pool caches PreparedStatement objectsso that they can be re-used from a cache without application intervention. For example, an application maycreate a PreparedStatement object similar to the following SQL statement:

SELECT name, address, dept, salary FROM personnelWHERE empid = ? or name = ? or address = ?

When the PreparedStatement object is created, the SQL query is parsed for semantic validation and a queryoptimization plan is produced. The process of creating a prepared statement can be extremely expensive interms of performance with some database systems. Once the prepared statement is closed, a JDBC3.0-compliant driver places the prepared statement into a local cache instead of discarding it. If the applicationlater attempts to create a prepared statement with the same SQL query, a common occurrence in manyapplications, the driver can simply retrieve the associated statement from the local cache instead of performinga network roundtrip to the server and an expensive database validation.

Connection and statement handling should be addressed before implementation. Thoughtfully handlingconnections and statements improves application performance and maintainability.

Managing Commits in TransactionsCommitting transactions is slow because of the amount of disk I/O and potentially network round trips that arerequired. Always turn off Autocommit by using Connection.setAutoCommit(false).



What does a commit actually involve? The database server must flush back to disk every data page thatcontains updated or new data. This is usually a sequential write to a journal file, but nevertheless, it involvesdisk I/O. By default, Autocommit is on when connecting to a data source, and Autocommit mode usually impairsperformance because of the significant amount of disk I/O needed to commit every operation.

Furthermore, most database servers do not provide a native Autocommit mode. For this type of server, theJDBC driver must explicitly issue a COMMIT statement and a BEGIN TRANSACTION for every operation sentto the server. In addition to the large amount of disk I/O required to support Autocommit mode, a performancepenalty is paid for up to three network requests for every statement issued by an application.

Although using transactions can help application performance, do not take this tip too far. Leaving transactionsactive can reduce throughput by holding locks on rows for longer than necessary, preventing other users fromaccessing the rows. Commit transactions in intervals that allow maximum concurrency.

Choosing the Right Transaction ModelMany systems support distributed transactions; that is, transactions that span multiple connections. Distributedtransactions are at least four times slower than normal transactions due to the logging and network round tripsnecessary to communicate between all the components involved in the distributed transaction (the JDBC driver,transaction monitor, and DBMS). Unless distributed transactions are required, avoid using them. Instead, uselocal transactions when possible. Many Java application servers provide a default transaction behavior thatuses distributed transactions.

For the best system performance, design the application to run using a single Connection object.

Using updateXXX MethodsAlthough programmatic updates do not apply to all types of applications, developers should attempt to useprogrammatic updates and deletes. Using the updateXXXmethods of the ResultSet object allows the developerto update data without building a complex SQL statement. Instead, the developer simply supplies the columnin the result set that is to be updated and the data that is to be changed. Then, before moving the cursor fromthe row in the result set, the updateRow() method must be called to update the database as well.

In the following code fragment, the value of the Age column of the ResultSet object rs is returned using thegetInt() method, and the updateInt() method is used to update the column with an int value of 25. TheupdateRow() method is called to update the row in the database with the modified value.

int n = rs.getInt("Age");// n contains value of Age column in the resultset rs...rs.updateInt("Age", 25);rs.updateRow();

In addition to making the application more easily maintainable, programmatic updates usually result in improvedperformance. Because the database server is already positioned on the row for the Select statement in process,performance-expensive operations to locate the row that needs to be changed are unnecessary. If the rowmust be located, the server usually has an internal pointer to the row available (for example, ROWID).

Using getBestRowIdentifierUse getBestRowIdentifier() to determine the optimal set of columns to use in the Where clause for updatingdata. Pseudo-columns often provide the fastest access to the data, and these columns can only be determinedby using getBestRowIdentifier().


Managing Connections and Updates

Some applications cannot be designed to take advantage of positioned updates and deletes. Some applicationsformulate the Where clause by calling getPrimaryKeys() to use all searchable result columns or by callinggetIndexInfo() to find columns that may be part of a unique index. These methods usually work, but can resultin fairly complex queries.

Consider the following example:

ResultSet WSrs = WSs.executeQuery("SELECT first_name, last_name, ssn, address, city, state, zip FROM emp");

// fetchdata...WSs.executeQuery (

"UPDATE emp SET address = ?WHERE first_name = ? AND last_name = ? AND ssn = ?AND address = ? AND city = ? AND state = ? AND zip = ?");

// fairly complex query

Applications should call getBestRowIdentifier() to return the optimal set of columns (possibly a pseudo-column)that identifies a specific record. Many databases support special columns that are not explicitly defined by theuser in the table definition, but are "hidden" columns of every table (for example, ROWID and TID). Thesepseudo-columns generally provide the fastest access to the data because they typically are pointers to theexact location of the record. Because pseudo-columns are not part of the explicit table definition, they are notreturned from getColumns(). To determine if pseudo-columns exist, call getBestRowIdentifier().

Consider the previous example again:

...ResultSet WSrowid = getBestRowIdentifier()

(... "emp", ...);...WSs.executeUpdate("UPDATE EMP SET ADDRESS = ? WHERE ROWID = ?");// fastest access to the data!

If your data source does not contain special pseudo-columns, the result set of getBestRowIdentifier() consistsof the columns of the most optimal unique index on the specified table (if a unique index exists). Therefore,your application does not need to call getIndexInfo() to find the smallest unique index.



Documents

Progress DataDirect for JDBC forOracleSales Cloud · Kinvey,NativeScriptSidekick,OpenAccess,ProDataSet,ProgressResults,ProgressSoftware,ProVision, PSEPro,Sitefinity,SmartBrowser,SmartComponent,SmartDataBrowser,