Progress DataDirect for JDBC forOracleEloqua · Releasehighlights Highlightsofthe6.0.0release •...

Progress® DataDirect® forJDBC™ for Oracle Eloqua™

User's Guide

6.0.0 Release

Copyright

© 2018 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, NativeScript,OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase, SequeLink,Sitefinity (and Design), SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test Studio, andWebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiariesin the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge, DataDirect Spy, SupportLink,DevCraft, Fiddler, JustAssembly, JustDecompile, JustMock, 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 aretrademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S.and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks containedherein may be trademarks of their respective owners.

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

Updated: 2018/08/01

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

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

Copyright

Table of Contents

Chapter 1:Welcome to the Progress DataDirect for JDBC for Oracle EloquaDriver.........................................................................................................11

Release highlights.................................................................................................................................12Requirements........................................................................................................................................12Driver and DataSource classes............................................................................................................12Connection URL....................................................................................................................................12Version string information.....................................................................................................................13Connection properties and configuration options..................................................................................13Data Types............................................................................................................................................14

getTypeInfo()..............................................................................................................................14Mapping objects to tables.....................................................................................................................18Contacting Technical Support...............................................................................................................19

Chapter 2: Getting started...........................................................................21Driver and DataSource classes............................................................................................................21Connecting using the DriverManager...................................................................................................22

Setting the class path ................................................................................................................22Passing the connection URL......................................................................................................22Testing the connection...............................................................................................................23

Connecting using data sources.............................................................................................................26How data sources are implemented...........................................................................................27Creating data sources................................................................................................................27Calling a DataSource in an application......................................................................................27

Chapter 3: Using the driver.........................................................................29Connecting from an application............................................................................................................30

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

Using connection properties.................................................................................................................35Required properties....................................................................................................................36Mapping properties....................................................................................................................36Web service properties..............................................................................................................37Bulk load properties...................................................................................................................37Proxy server properties..............................................................................................................38Additional properties..................................................................................................................38

Performance considerations.................................................................................................................38


Contents

Proxy server support.............................................................................................................................39Unicode support....................................................................................................................................39Data encryption.....................................................................................................................................39Bulk operations.....................................................................................................................................40

Efficient queries..........................................................................................................................41Catalog tables.......................................................................................................................................42

SYSTEM_REMOTE_SESSIONS catalog table.........................................................................42SYSTEM_SESSIONS catalog table...........................................................................................43

Identifiers...............................................................................................................................................44Timeouts...............................................................................................................................................45Scrollable cursors.................................................................................................................................45Large object (LOB) support...................................................................................................................46Parameter metadata.............................................................................................................................46

Insert and Update statements....................................................................................................46Select statements.......................................................................................................................46

ResultSet metadata..............................................................................................................................47Rowset support.....................................................................................................................................48Auto-generated keys.............................................................................................................................48Error handling.......................................................................................................................................49DataDirect Test......................................................................................................................................49

DataDirect Test tutorial...............................................................................................................50Tracking JDBC calls with DataDirect Spy.............................................................................................82

Enabling DataDirect Spy............................................................................................................82

Chapter 4: Connection property descriptions...........................................87BulkActivityPageSize............................................................................................................................89BulkPageSize........................................................................................................................................90BulkTimeout..........................................................................................................................................91BulkTopThreshold.................................................................................................................................92Company...............................................................................................................................................93ConfigOptions.......................................................................................................................................93

CheckBoxAsText (configuration option).....................................................................................94KeywordConflictSuffix (configuration option).............................................................................95

CreateMap............................................................................................................................................96FailOnIncompleteData..........................................................................................................................97LogConfigFile........................................................................................................................................97Password..............................................................................................................................................98ProxyHost..............................................................................................................................................99ProxyPassword.....................................................................................................................................99ProxyPort............................................................................................................................................100ProxyUser...........................................................................................................................................101SchemaMap........................................................................................................................................101SpyAttributes.......................................................................................................................................103User.....................................................................................................................................................104


Contents

WSFetchSize......................................................................................................................................104WSRetryCount....................................................................................................................................105WSTimeout.........................................................................................................................................106

Chapter 5: Troubleshooting......................................................................107Troubleshooting your application........................................................................................................107

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

Logging components................................................................................................................108Configuring Logging.................................................................................................................110

Chapter 6: Supported SQL functionality..................................................113Alter Session (EXT)............................................................................................................................113Delete..................................................................................................................................................114Insert...................................................................................................................................................115

Specifying an external ID column.............................................................................................116Refresh Map (EXT).............................................................................................................................117Select..................................................................................................................................................117

Select clause............................................................................................................................118From clause.............................................................................................................................120

Update.................................................................................................................................................128SQL expressions.................................................................................................................................129

Column Names........................................................................................................................129Literals......................................................................................................................................129Operators.................................................................................................................................132Functions..................................................................................................................................135Conditions................................................................................................................................135

Subqueries..........................................................................................................................................136IN predicate..............................................................................................................................137EXISTS predicate.....................................................................................................................137UNIQUE predicate...................................................................................................................137Correlated subqueries..............................................................................................................138

Chapter 7: SQL escape sequences for JDBC..........................................141Date, time, and timestamp escape sequences...................................................................................142Scalar functions..................................................................................................................................142Outer join escape sequences.............................................................................................................144LIKE escape character sequence for wildcards..................................................................................144

Chapter 8: JDBC support..........................................................................145Array....................................................................................................................................................146Blob.....................................................................................................................................................147


Contents

CallableStatement...............................................................................................................................148Clob.....................................................................................................................................................159Connection..........................................................................................................................................160ConnectionEventListener....................................................................................................................165ConnectionPoolDataSource................................................................................................................166DatabaseMetaData.............................................................................................................................166DataSource.........................................................................................................................................174Driver...................................................................................................................................................175ParameterMetaData............................................................................................................................175PooledConnection...............................................................................................................................177PreparedStatement.............................................................................................................................177Ref.......................................................................................................................................................182ResultSet.............................................................................................................................................182ResultSetMetaData.............................................................................................................................193RowSet................................................................................................................................................194SavePoint............................................................................................................................................194Statement............................................................................................................................................194StatementEventListener......................................................................................................................198Struct...................................................................................................................................................198XAConnection.....................................................................................................................................199XADataSource....................................................................................................................................199XAResource........................................................................................................................................199

Chapter 9: JDBC extensions.....................................................................201DatabaseMetaData interface..............................................................................................................201ExtLogControl class............................................................................................................................202

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

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

Returning Data....................................................................................................................................206Returning Long Data................................................................................................................206Reducing the Size of Returned Data........................................................................................207Choosing the Right Data Type.................................................................................................207Retrieving Result Sets..............................................................................................................207

Selecting JDBC Objects and Methods ...............................................................................................208Using Parameter Markers as Arguments to Stored Procedures..............................................208Using the Statement Object Instead of the PreparedStatement Object...................................208Using Batches Instead of Prepared Statements......................................................................209Choosing the Right Cursor.......................................................................................................210


Contents

Using get Methods Effectively..................................................................................................210Retrieving Auto Generated Keys..............................................................................................211

Managing Connections and Updates..................................................................................................211Managing Connections............................................................................................................212Managing Commits in Transactions.........................................................................................212Choosing the Right Transaction Model....................................................................................213Using updateXXX Methods......................................................................................................213Using getBestRowIdentifier......................................................................................................213

Glossary.......................................................................................................215

Index.............................................................................................................219


Contents


Contents

1Welcome to the Progress DataDirect forJDBC for Oracle Eloqua Driver

The Progress® DataDirect® for JDBC™ for Oracle Eloqua™ driver supports SQL read-write access to Oracle Eloqua.To support SQL access to Oracle Eloqua, the driver creates a relational map of the Oracle Eloqua data modeland translates SQL statements provided by the application to Oracle Eloqua queries and web service calls.The driver optimizes performance when executing joins by leveraging data relationships among Oracle Eloquaobjects to minimize the amount of data that needs to be fetched over the network. The driver recognizes therelationships among standard objects and custom objects and can access and update each. Relationshipsamong objects can be reported with the metadata methods getBestRowIdentifier(), getColumns(),getExportedKeys(), getImportedKeys(), getPrimaryKey(), getTables(), and getTypeInfo().

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-write access to Oracle Eloqua. See Supported SQL functionality on page 113 for details.

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

• Supports Oracle Eloqua data types. See Data Types on page 14 and getTypeInfo() on page 14 for details.

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

• Uses a combination of REST and BULK APIs for optimized fetch operations. See Bulk operations on page40 for details.

• Supports retrieving LONGVARCHAR data, using JDBC methods designed for Character Large Object(CLOB) data. See Large object (LOB) support on page 46 for details.

• Supports timeout functionality. See Timeouts on page 45 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.eloqua.EloquaDriver

DataSource classThe DataSource class is:

com.ddtek.jdbcx.eloqua.EloquaDataSource

Connection URLThe connection URL takes the following form:

jdbc:datadirect:eloqua:Company=company_id;User=user_id;Password=password[;property=value[;...]]

where:


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

company_id

specifies the company identifier issued by Oracle Eloqua during the registration process.

user_id

specifies the user name that used to connect to the Oracle Eloqua 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 Eloqua instance.

jdbc:datadirect:eloqua:Company=ABCcorp;[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

Connection properties and configuration optionsThe driver includes over 20 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.


Version string information

See Using connection properties on page 35 and Connection property descriptions on page 87 for moreinformation.

Data TypesThe following table lists Oracle Eloqua data types supported by the driver and how they are mapped to JDBCdata types.

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

Table 1: Oracle Eloqua data types

JDBC data typeOracle Eloqua data type

VARCHARARRAY

BOOLEANBOOLEAN

TIMESTAMPDATETIME

DECIMALDECIMAL

VARCHARDURATION

INTEGERINTEGER

LONGVARCHARLARGETEXT

BIGINTLONG

VARCHARTEXT

VARCHARURL

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



Table 2: getTypeInfo()

MINIMUM_SCALE = NULL

NULLABLE = 1

NUM_PREC_RADIX = NULL

PRECISION = 4000

SEARCHABLE = 3

SQL_DATA_TYPE = NULL

SQL_DATETIME_SUB = NULL

UNSIGNED_ATTRIBUTE = NULL

TYPE_NAME = array

AUTO_INCREMENT = false

CASE_SENSITIVE = false

CREATE_PARAMS = NULL

DATA_TYPE = 12 (VARCHAR)

FIXED_PREC_SCALE = false

LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = ARRAY

MAXIMUM_SCALE = 0


NULLABLE = 1


PRECISION = 1

SEARCHABLE = 3




TYPE_NAME = boolean




DATA_TYPE = 16 (BOOLEAN)


LITERAL_PREFIX = NULL

LITERAL_SUFFIX = NULL

LOCAL_TYPE_NAME = BOOLEAN

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 23

SEARCHABLE = 3




TYPE_NAME = datetime




DATA_TYPE = 93 (TIMESTAMP)


LITERAL_PREFIX = TIMESTAMP '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = DATETIME

MAXIMUM_SCALE = 3


Data Types

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


NULLABLE = 1


PRECISION = 50

SEARCHABLE = 3




TYPE_NAME = duration






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = DURATION

MAXIMUM_SCALE = 0

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 10

SEARCHABLE = 3




TYPE_NAME = integer




DATA_TYPE = 4 (INTEGER)




LOCAL_TYPE_NAME = INTEGER

MAXIMUM_SCALE = 0




NULLABLE = 1


PRECISION = 32000

SEARCHABLE = 0




TYPE_NAME = largetext




DATA_TYPE = -1 (LONGVARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = LARGETEXT

MAXIMUM_SCALE = 0

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


Data Types


NULLABLE = 1


PRECISION = 4000

SEARCHABLE = 3




TYPE_NAME = text






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = TEXT

MAXIMUM_SCALE = 0


NULLABLE = 1


PRECISION = 4000

SEARCHABLE = 3




TYPE_NAME = url






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = URL

MAXIMUM_SCALE = 0

Mapping objects to tablesThe driver automatically maps Oracle Eloqua objects and fields to tables and columns when it first connectsto an Oracle Eloqua instance. The driver maps standard as well as custom objects, including relationshipsdefined among objects. Relationships among objects can be reported with the metadata methodsgetBestRowIdentifier(), getColumns(), getExportedKeys(), getImportedKeys(),getPrimaryKey(), getTables(), and getTypeInfo().

The driver uses a local schema map to instantiate the mapping of the remote data source objects to tables andthe metadata associated with those tables. The driver creates a schema map for each user. By default, theschema map is created in the directory from which the application is run. The CreateMap connection propertyallows you to update or re-create the schema map. The schema map uses the user ID specified for theconnection as the name of the schema map configuration file. If the user ID contains punctuation or othernon-alphanumeric characters, the driver strips those characters from the user ID to form the name of theschema map configuration file. You can set the SchemaMap connection property to override the default settingfor the name and location of 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 96SchemaMap on page 101Refresh Map (EXT) on page 117Mapping properties on page 36

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.

• 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

https://www.progress.com/support

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 Eloqua 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:eloqua:Company=ABCcorp;[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 eloqua.jar file as shown, where install_dir is the path to your product installationdirectory.

install_dir/lib/eloqua.jar

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

UNIX ExampleCLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/eloqua.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:

company_id


user_id


password



Chapter 2: Getting started

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 theDatabase field, specify the company identifier issued by Oracle Eloqua during the registration process.

For example:

jdbc:datadirect:eloqua:Company=ABCcorp


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

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 and managed 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 12

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

• Performance considerations

• Proxy server support

• Unicode support

• Data encryption

• Bulk operations

• Catalog tables

• Identifiers

• Timeouts

• Scrollable cursors

• Large object (LOB) support

• Parameter metadata

• ResultSet metadata


• Rowset support

• Auto-generated keys

• Error handling

• DataDirect Test

• Tracking JDBC calls with DataDirect Spy

Connecting from an applicationAfter 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

Driver classThe Driver class is:




Connecting using the DriverManagerYou can connect to an Oracle Eloqua 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:eloqua:Company=ABCcorp;[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 eloqua.jar file as shown, where install_dir is the path to your product installationdirectory.

install_dir/lib/eloqua.jar


Chapter 3: Using the driver

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

UNIX ExampleCLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/eloqua.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:

company_id


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:


Connecting from an application

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

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 theDatabase field, specify the company identifier issued by Oracle Eloqua during the registration process.

For example:

jdbc:datadirect:eloqua:Company=ABCcorp


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

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 and managed 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 12

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 JDBC method 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 data source, string values must be enclosed in double quotation marks, for example,setCompany("ABCCorp").

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

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

Table 3: Required properties

CharacteristicProperty

Specifies the company identifier issued by Oracle Eloqua during the registrationprocess.

Company on page 93

Specifies the password used to connect to your Oracle Eloqua instance for userID/password authentication.

Password on page 98

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

User on page 104

See alsoConnection property descriptions on page 87

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

Table 4: Mapping properties


Determines how the mapping of the remote data model to the relational data modelis configured, customized, and updated.

ConfigOptions on page93

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

CreateMap on page 96

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 OracleEloqua instance. By default, if the file does not exist, the driver creates one.

SchemaMap on page 101




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 1000 (rows).

WSFetchSize on page 104

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 105

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

WSTimeout on page 106

See alsoConnection property descriptions on page 87Performance considerations on page 38

Bulk load propertiesThe following table summarizes connection properties related to bulk load operations.

Table 6: Bulk load properties


Specifies the maximum number of rows to be fetched from Activity_XXX tablesin a single request. The default is 50000.

BulkActivityPageSize onpage 89

Specifies the maximum number of rows to be fetched from Oracle Eloqua in asingle request. The default is 5000.

BulkPageSize on page 90

Specifies the timeout duration for a bulk call in seconds. The default is 1800.BulkTimeout on page 91

Specifies a threshold for determining whether bulk operations are used to processqualifying Select queries that include a Top n clause. The default is 1000. (SeeBulk operations on page 40 for more information on qualifying Select queries.)

BulkTopThreshold onpage 92

See alsoBulk operations on page 40Connection property descriptions on page 87Performance considerations on page 38


Using connection properties

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

Table 7: Proxy server properties


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

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

ProxyPort on page 100

Specifies a proxy server.ProxyHost on page 99

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


Additional propertiesThe following table summarizes additional connection properties.

Table 8: Additional properties


Determines how the driver processes a query when no data isreturned for some columns. For these columns, which togetherform incomplete data, the driver can either return NULL valuesor throw an exception. The default is 0 (disabled).

FailOnIncompleteData on page 97

Specifies the filename of the configuration file used to initializedriver logging. The default filename is ddlogging.properties.

LogConfigFile on page 97

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 103


Performance considerationsThe connection properties described in this topic have direct impact on driver performance.



BulkActivityPageSize on page 89. The BulkActivityPageSize connection property specifies the maximumnumber of rows to be fetched from Activity_XXX tables in a single request. Generally, higher page sizesreturn results more quickly. However, Oracle Eloqua imposes a 32 MB limit on response package size. Ifqueries return large records, too many records within a single page will exceed that limit, causing the query tofail. In addition, all of the objects returned within a page must be materialized as the page is retrieved, sosufficient Java heap space is necessary with large page sizes containing many small columns.

BulkPageSize on page 90. The BulkPageSize connection property specifies the maximum number of recordsto be fetched in a single request. Generally, higher page sizes return results more quickly. However, OracleEloqua imposes a 32 MB limit on response package size. If queries return large records, too many recordswithin a single page will exceed that limit, causing the query to fail. In addition, all of the objects returned withina page must be materialized as the page is retrieved, so sufficient Java heap space is necessary with largepage sizes containing many small columns.

BulkTopThreshold on page 92. The BulkTopThreshold connection property can be used to determine the pointat which bulk operations can be used to execute qualifying Select queries. See Bulk operations on page 40for more information on qualifying Select queries.

WSFetchSize on page 104. The WSFetchSize connection property allows you to specify the maximum numberof rows allowed for a fetch on each call to the web service. The default value of 1000 rows typically providesthe maximum throughput. However, for interactive applications, you can reduce response time by settingWSFetchSize at a lower value.

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

Unicode supportMultilingual 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 Eloqua, including user ID/password authentication, is encryptedusing Secure Sockets Layer (SSL).

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


Proxy server support

Bulk operationsThe driver supports Oracle Eloqua bulk operations with some limitations.

Note: Bulk operations are most efficient for queries that return large amounts of data for a relatively small setof columns. For example, SELECT folderid,name,country,c_website FROM Account WHEREcountry='Switzerland' has only four columns but many rows.

Bulk operations for some Select queries with a Top n clause are not supported because it is usually faster touse a standard query to fetch more columns for a few rows than to use a bulk operation. Nevertheless, youcan use the BulkTopThreshold connection property to control, in part, how the driver handles queries with aTop n clause. The default value of BulkTopThreshold is 1000.

Queries on Account and Contact tables have additional limitations. The following criteria must be met for querieson Account and Contact tables.

• The result must have multiple rows.

• The result cannot have more than 250 columns.

• The result must include at least one user-defined column.

• The query must either have no Top n clause, or the value of n in the Top n clause must be greater than thevalue specified in the BulkTopThreshold custom property.

• The query can only include columns that the bulk interface supports. For more information, see the tablebelow.

Table 9: Columns that cannot be retrieved using bulk operations

Contact tableAccount table

accessedAtaccessedAt

bouncebackDatecreatedBy

currentStatuscurrentStatus

createdByDescription

DescriptionfolderId

folderIdPermissions

PermissionsscheduledFor

scheduledForsourceTemplateId

sourceTemplateIdupdatedBy

subscriptionDate



Contact tableAccount table

updatedBy

unsubscriptionDate

The following table provides some query examples and describes why they would not take advantage of bulkoperations and offers suggestions for modifying them. However, there will obviously be use cases where anapplication will use queries that cannot be returned using bulk operations.

DescriptionQuery

There are more than 250 columns in the Contact table.To take advantage of bulk operations, constrain theSELECT statement to a set of less than 250 columns.

SELECT * FROM Contact WHERECountry='Switzerland'

The ContactList table is not supported for bulkoperations.

SELECT * FROM ContactList WHERE Region='East'

This returns one row.SELECT Id, C_Website FROM Account WHERE Id=17

More than one criterion or comparison operator is usedin the WHERE clause.

Tips:

• If a query has zero or one comparison operators(meaning one of =, <=, <, >, >=, <>) in the WHEREclause, the query will usually be processed usingthe bulk operations.

• If a query contains the LIKE operator in the WHEREclause, the query is not processed using the bulkoperations.

SELECT Id, C_Website FROM Contact WHERECountry='Switzerland' AND Region='EAST'

See alsoBulk load properties on page 37Performance considerations on page 38BulkActivityPageSize on page 89BulkPageSize on page 90BulkTimeout on page 91BulkTopThreshold on page 92

Efficient queriesThe driver supports queries based on the definition of Oracle Eloqua minimal, partial, and complete columnsets. If you know which type of column you are querying, you can optimize queries by following these guidelines.

Note: Refer to your Oracle Eloqua documentation for details on minimal, partial, and complete column sets.


Bulk operations

• A minimal column set provides the best performance. For example: SELECTname,description,createdBy FROM Account WHERE scheduledFor='May'

• A partial column set provides the next best performance. For example: SELECT name, description,createdBy, country FROM Account WHERE scheduledFor='May' is processed faster than:SELECT name, description, createdBy, country, c_website FROM Account WHEREscheduledFor='May', which contains columns from Complete Column Set.

• A complete column set is processed faster than a query that uses the bulk interface only when the requirednumber of records is less than the actual number of records that the bulk query would return. For example,the following query would return all rows: SELECT name, country, c_website FROM AccountWHERE scheduledFor='May'. However, if you wanted to return the first 500 of 10,000 records, the querySELECT TOP 500 name, country, c_website FROM Account WHERE scheduledFor='May'would probably be faster, even though it would not be fetched in a bulk operation.

See alsoBulk load properties on page 37Performance considerations on page 38BulkActivityPageSize on page 89BulkPageSize on page 90BulkTimeout on page 91BulkTopThreshold on page 92

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 10: 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



DescriptionData TypeColumn Name

The remote session type. The current validtype is Eloqua.


TYPE

The value for INSTANCE is null.NULLINSTANCE

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


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 of Web 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

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 11: 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 142 for moreinformation about the CURSESSIONID() system function.

INTEGER,NOT NULL

SESSION_ID


Catalog tables


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 False.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 Eloqua 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.

KeywordConflictSuffix

The driver also includes the KeywordConflictSuffix configuration option. KeywordConflictSuffix allows you toavoid naming conflicts when the name of an object corresponds to the name of a SQL engine keyword.KeywordConflictSuffix specifies a string of up to five alphanumeric characters that the driver appends to anyobject or field name that conflicts with a SQL engine keyword. For example, if you specifyKeywordConflictSuffix=tab, the driver maps the case object to the casetab column.

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.

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

Bulk operation timeoutsThe BulkTimeout connection property can be used to specify the duration allowed for bulk calls. If the querytakes longer than the specified duration, the query could be aborted. The default value is 18000 seconds.

See Using connection properties on page 35 and Web service properties on page 37 for details.

Scrollable cursorsThe driver supports scroll-insensitive result sets and updatable 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.


Timeouts

Large object (LOB) supportThe driver allows you to retrieve LONGVARCHAR data, using JDBC methods designed for Character LargeObject (CLOB) data. When using these methods to update long data as CLOBs data, the updates are madeto the local copy of the data contained in the CLOB object.

Retrieving and updating long data using JDBC methods designed for CLOB data provides some of the samebenefits as retrieving and updating CLOB data, such as:

• Provides random access to data

• Allows searching for patterns in the data

To provide the benefits normally associated with CLOB data, data must be cached. Because data is cached,your application will incur a performance penalty, particularly if data is read once sequentially. This performancepenalty can be severe if the size of the long data is larger than available memory.

Parameter metadataThe driver supports returning parameter metadata as described in the following topics.

Insert and Update statementsThe driver supports returning parameter metadata for the following forms of Insert and Update statements:

• INSERT INTO employee VALUES(?, ?, ?)

• INSERT INTO department (col1, col2, col3) VALUES(?, ?, ?)

• UPDATE employee SET col1=?, col2=?, col3=? WHERE col1 operator ? [{AND | OR}col2 operator ?]

where:

operator

is any of the following SQL operators:

=, <, >, <=, >=, and <>.

Select statementsThe 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 metadataIf 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 Selectlist:

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()method is called if the driver can determine that information. For example, for the following statement, the driverreturns "test" for the catalog name and "foo" for the table name:

SELECT * FROM test.foo


ResultSet metadata

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

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.

Auto-generated keysThe driver supports retrieving the values of auto-generated keys. An auto-generated key returned by the driveris the value of an auto-increment column.

An application can return values of auto-generated keys when it executes an Insert statement. How you returnthese values depends on whether you are using an Insert statement with a Statement object or with aPreparedStatement object, as outlined in the following scenarios:

• When using an Insert statement with a Statement object, the driver supports the following form of theStatement.execute and Statement.executeUpdate methods to instruct the driver to return valuesof auto-generated keys:

• Statement.execute(String sql, int autoGeneratedKeys)

• Statement.execute(String sql, int[] columnIndexes)

• Statement.execute(String sql, String[] columnNames)

• Statement.executeUpdate(String sql, int autoGeneratedKeys)

• Statement.executeUpdate(String sql, int[] columnIndexes)

• Statement.executeUpdate(String sql, String[] columnNames)

• When using an Insert statement with a PreparedStatement object, the driver supports the following formof the Connection.prepareStatement method to instruct the driver to return values of auto-generatedkeys:

• Connection.prepareStatement(String sql, int autoGeneratedKeys)

• Connection.prepareStatement(String sql, int[] columnIndexes)

• Connection.prepareStatement(String sql, String[] columnNames)



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

An application can retrieve values of auto-generated keys using the Statement.getGeneratedKeys()method. This method returns a ResultSet object with a column for each auto-generated key.

See Designing JDBC Applications for Performance Optimization on page 203 for more information.

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

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

[DataDirect][Eloqua 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][Eloqua JDBC Driver][Eloqua]Invalid Object Name.

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

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.


Error handling

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.





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


DataDirect Test

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:





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.


DataDirect Test

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.



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:


DataDirect Test

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.



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

7. If you repeat the steps described in "Executing a simple Select statement," you will see that the previouslyinserted records are also returned.


DataDirect Test

See alsoExecuting a simple Select statement on page 54

Retrieving database metadata1. From the Connection window menu, select Connection / Get DB Meta Data.

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



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.


DataDirect Test

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.



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.


DataDirect Test

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.



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 62 through Step 4 on page 63 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," you see that thepreviously inserted records are returned.


DataDirect Test

See alsoExecuting a simple Select statement on page 54

Returning parameter metadata1. 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 parameter metadata.



Establishing savepoints1. 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.


DataDirect Test

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.



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.


DataDirect Test

Click Submit; 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.



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.


DataDirect Test

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.



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

Inserting a row






DataDirect Test



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




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.


DataDirect Test

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









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




DataDirect Test


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

10. Click Update Row.


12. Specify the statement that you want to execute.




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

Retrieving large object (LOB) dataThe 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.


DataDirect Test




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



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

9. Change the data type to Clob.


DataDirect Test

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



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


DataDirect Test

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 setEnableLoggingmethod in the com.ddtek.jdbc.extensions.ExtLogControl interface. See "Troubleshooting yourapplication" for information about using a DataDirect Spy log for troubleshooting.

See alsoTroubleshooting your application on page 107

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 data source.

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.eloqua.EloquaDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:eloqua:Company=ABCcorp;[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_.



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.eloqua.EloquaDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:eloqua:Company=ABCcorp;[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 84SpyAttributes on page 103

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

The com.ddtek.jdbcx.eloqua.EloquaDataSource class supports setting a semi-colon-separated listof DataDirect Spy attributes.

Windows exampleEloquaDataSource sds=new EloquaDataSource():sds.setCompany("ABCCorp");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.

DataDirect Spy loads the driver and logs all JDBC activity to the spy.log file located in the C:\temp directory(log=(file)C:\\temp\\spy.log). In addition to regular JDBC activity, the spy.log file also logs activityon InputStream and Reader objects (logIS=yes). It also includes the name of the current thread(logTName=yes).

UNIX exampleEloquaDataSource mds = new EloquaDataSource();mds.setCompany("ABCCorp");mds.setSpyAttributes("log=(file)/tmp/spy.log;logTName=yes");Connection conn=mds.getConnection("TEST","secret");...


Tracking JDBC calls with DataDirect Spy

DataDirect Spy loads the driver and logs all JDBC activity to the spy.log file located in 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 84SpyAttributes on page 103

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

Table 12: 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.

For Windows, 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: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 namedfile_prefixX.log

where:

X

is an integer that increments by 1 for each connection on which the prefixis specified.

For example, if the attribute log=(filePrefix) C:\\temp\\spy_ is specified on multipleconnections, 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



DescriptionAttribute

Specifies whether DataDirect Spy logs activity on InputStream and Reader objects.

When logIS=nosingleread, logging on InputStream and Reader objects is active;however, logging of the single-byte read InputStream.read or single-characterReader.read is suppressed to prevent generating large log files that containsingle-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}


Tracking JDBC calls with DataDirect Spy

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 DriverManager or a JDBC DataSource. For a DriverManager 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,setCompany("ABCCorp").

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 13: Driver properties

Default ValueData Source MethodConnection String Property

50000 (rows)setBulkActivityPageSizeBulkActivityPageSize on page 89

5000 (rows)setBulkPageSizeBulkPageSize on page 90

1800 (seconds)setBulkTimeoutBulkTimeout on page 91

1000 (rows)setBulkTopThresholdBulkTopThreshold on page 92


Default ValueData Source MethodConnection String Property

No default valuesetCompanyCompany on page 93

CheckBoxAsText=0;KeywordConflictSuffix=

setConfigOptionsConfigOptions on page 93

notExistsetCreateMapCreateMap on page 96

0setFailOnIncompleteDataFailOnIncompleteData on page 97

ddlogging.propertiessetLogConfigFileLogConfigFile on page 97

No default valuesetPasswordPassword on page 98

No default valuesetProxyHostProxyHost on page 99

No default valuesetProxyPasswordProxyPassword on page 99

No default valuesetProxyPortProxyPort on page 100

No default valuesetProxyUserProxyUser on page 101

For Windows:

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

For UNIX/Linux:

˜/progress/datadirect/eloqua_schema/user_name.config

setSchemaMapSchemaMap on page 101

No default valuesetSpyAttributesSpyAttributes on page 103

No default valuesetUserUser on page 104

1000 (rows)setWSFetchSizeWSFetchSize on page 104

0setWSRetryCountWSRetryCount on page 105

120 (seconds)setWSTimeoutWSTimeout on page 106


• BulkActivityPageSize

• BulkPageSize

• BulkTimeout


Chapter 4: Connection property descriptions

• BulkTopThreshold

• Company

• ConfigOptions

• CreateMap

• FailOnIncompleteData

• LogConfigFile

• Password

• ProxyHost

• ProxyPassword

• ProxyPort

• ProxyUser

• SchemaMap

• SpyAttributes

• User

• WSFetchSize

• WSRetryCount

• WSTimeout

BulkActivityPageSizePurposeSpecifies the maximum number of rows to be fetched from Activity_XXX tables in a single request.

Valid Valuesx

where

x

is a positive integer between 2 and 50000.

Notes• Generally, higher page sizes return results more quickly. However, Oracle Eloqua imposes a 32 MB limit

on response package size. If queries return large records, too many records within a single page will exceedthat limit, causing the query to fail.

• All of the objects returned within a page must be materialized as the page is retrieved, so sufficient Javaheap space is necessary with large page sizes containing many small columns.


BulkActivityPageSize

Data Source MethodsetBulkActivityPageSize

Default50000

Data TypeInt

See alsoBulk operations on page 40Bulk load properties on page 37BulkPageSize on page 90BulkTimeout on page 91BulkTopThreshold on page 92Performance considerations on page 38

BulkPageSizePurposeSpecifies the maximum number of records to be fetched from Oracle Eloqua in a single request.

Valid Valuesx

where

x


Notes• Generally, higher page sizes return results more quickly. However, Oracle Eloqua imposes a 32 MB limit

on response package size. If queries return large records, too many records within a single page will exceedthat limit, causing the query to fail.

• All of the objects returned within a page must be materialized as the page is retrieved, so sufficient Javaheap space is necessary with large page sizes containing many small columns.

Data Source MethodsetBulkPageSize

Default5000



Data TypeInt

See alsoBulk operations on page 40Bulk load properties on page 37BulkActivityPageSize on page 89BulkTimeout on page 91BulkTopThreshold on page 92Performance considerations on page 38

BulkTimeoutPurposeSpecifies the timeout duration for a bulk call in seconds.

Valid Valuesx

where

x


NotesOracle Eloqua automatically clears out the bulk staging area after this timeout. If the query is large and thedata takes more than this time to run, the driver may throw a timeout error and abort the query midstream.

Data Source MethodsetBulkTimeout

Default1800

Data TypeInt

See alsoBulk operations on page 40Bulk load properties on page 37BulkActivityPageSize on page 89BulkPageSize on page 90BulkTopThreshold on page 92


BulkTimeout

BulkTopThresholdPurposeSpecifies a threshold for determining whether bulk operations are used to process qualifying Select queriesthat include a Top n clause. (See Bulk operations on page 40 for more information on qualifying Select queries.)

Valid Valuesx

where

x

is a positive integer greater than 0.

BehaviorIf x is less than or equal n (the number of rows specified in the Top n clause), the standard mechanism is usedto process the query.

If x is greater than n (the number of rows specified in the Top n clause), bulk load is used to process thequalifying queries.

NotesOracle Eloqua automatically clears out the bulk staging area after this timeout, so if the query is large and thedata takes more than this time to run, the query could be aborted midstream.

Data Source MethodsetBulkTopThreshold

Default1000

Data TypeInt

See alsoBulk operations on page 40Bulk load properties on page 37BulkActivityPageSize on page 89BulkPageSize on page 90BulkTimeout on page 91Performance considerations on page 38



CompanyPurposeSpecifies the company identifier issued by Oracle Eloqua during the registration process.

Valid Valuescompany_id

where:

company_id

is the company identifier issued by Oracle Eloqua during the registration process. For example, ifyour company name is ABC Corporation, Oracle Eloqua might issue the company identifier asABCCorp.

Data Source MethodsetCompany

DefaultNo default value

Data TypeString

See alsoRequired properties on page 36Password on page 98User on page 104

ConfigOptionsPurposeDetermines how the mapping of the remote data model to the relational data model is configured, customized,and updated. (See also CreateMap on page 96.

NotesThis property is primarily used for initial configuration of the driver for a particular user. It is not intended foruse with every connection. By default, the driver configures itself and this option is normally not needed. IfConfigOptions is specified on a connection after the initial configuration, the values specified for ConfigOptionsmust match the values specified for the initial configuration.


Company

Valid Values(" key = value [; key = value ]")

where:

key

is one of the following configuration options:

• CheckBoxAsText

• KeywordConflictSuffix

value

specifies a setting for the configuration option.

When specifying configuration options in a connection string, key value pairs must be separated by a semicolonand enclosed in quotation marks and then in parentheses. For example:

ConfigOptions=("CheckBoxAsText=1;KeywordConflictSuffix=TAB")

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

setConfigOptions("CheckBoxAsText=1;KeywordConflictSuffix=TAB;RefreshMap=true")

Data Source MethodsetConfigOptions

DefaultCheckBoxAsText=0;KeywordConflictSuffix=

Data TypeString

See alsoMapping objects to tables on page 18Mapping properties on page 36CreateMap on page 96SchemaMap on page 101

CheckBoxAsText (configuration option)

PurposeSpecifies whether the check box values of user-defined columns should be returned as string or Boolean.

Valid Values0 | 1



BehaviorIf set to 0, the check box value is returned as a Boolean. The Boolean is described as a Bit in the relationalmap, either checkedValue or uncheckedValue. When neither of these values is present, the check boxvalue is returned as NULL.

If set to 1, the stored literal value of the check box is returned as a string. The string is described as a Varcharin the relational map.

Default0

Data TypeString

KeywordConflictSuffix (configuration option)

PurposeSpecifies a string of up to five alphanumeric characters that the driver appends to any object or field name thatconflicts with a SQL engine keyword.

Valid Valuesstring

where:

string

is a string of up to five alphanumeric characters.

ExampleA field called CASE exists in the native Oracle Eloqua data. To avoid a naming conflict with the SQL enginekeyword CASE, you could set KeywordConflictSuffix=TAB. In this scenario, the driver maps the Caseobject to the CASETAB column.

NotesDo not use a string that matches the suffix of a custom table, for example, CASEOFICE. If you specifyKeywordConflictSuffix=OFICE, a name collision occurs with the Standard object CASE and the customtable CASEOFICE, or a table with a column called CASEOFICE. In this situation, the standard object CASE isreturned. The custom object is ignored.


Data TypeString


ConfigOptions

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 schema map'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 18Mapping properties on page 36ConfigOptions on page 93SchemaMap on page 101



FailOnIncompleteDataPurposeDetermines how the driver processes a query when no data is returned for some columns. For these columns,which together form incomplete data, the driver can either return NULL values or throw an exception.

Valid Valuesfalse | true

BehaviorIf set to false, the driver returns NULL values for columns that return no data.

If set to true, the driver attempts to retrieve the complete data. The driver throws an exception if the datacannot be retrieved.

Data Source MethodsetFailOnIncompleteData

Defaultfalse

Data TypeBoolean

LogConfigFilePurposeSpecifies the filename of the configuration file used to initialize driver logging. If the driver cannot locate thespecified file when establishing the connection, the connection fails and the driver returns an error.

Valid Valuesstring

where:

string

is the relative or fully qualified path of the configuration file used to initialize driver logging. If thespecified file does not exist, the driver continues searching for an appropriate configuration file asdescribed in "Using the Driver for Logging".

Data Source MethodsetLogConfigFile


FailOnIncompleteData

Defaultddlogging.properties

Data TypeString

See also• Additional properties on page 38

• Using the Driver for Logging on page 111

PasswordDescriptionSpecifies the password used to connect to your Oracle Eloqua 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


Data TypeString

See alsoRequired properties on page 36Company on page 93User on page 104



ProxyHostDescriptionSpecifies 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 38ProxyPassword on page 99ProxyPort on page 100ProxyUser on page 101

ProxyPasswordPurposeSpecifies the password needed to connect to a proxy server.

Valid Valuespassword

where:


ProxyHost

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 38ProxyHost on page 99ProxyPort on page 100ProxyUser on page 101

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.

Data Source MethodsetProxyPort

Default0

Data TypeInt

See alsoProxy server properties on page 38



ProxyHost on page 99ProxyPassword on page 99ProxyUser on page 101

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 38ProxyHost on page 99ProxyPassword on page 99ProxyPort on page 100

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 Eloqua instance. By default, if the file does not exist, thedriver creates one.

Valid Valuesstring

where:


ProxyUser

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\\Eloqua_Schema\\testuser.config,the driver either creates or looks for the configuration file testuser.config in the directoryC:\Users\Default\AppData\Local\Progress\DataDirect\Eloqua_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:eloqua:Company=ABCcorp;[email protected];Password=secret;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect

\Eloqua_Schema\MyConnect.config

DataSource example

EloquaDataSource mds = new EloquaDataSource();mds.setDescription("My EloquaDataSource");mds.setCompany("ABCCorp")mds.setUser("[email protected]")mds.setPassword("secret")mds.setSchemaMap("C:\\Users\\Default\\AppData\\Local\\Progress

\\DataDirect\\Eloqua_Schema\\MyConnect.config")

Data Source MethodsetSchemaMap

Default• For Windows XP and Windows Server 2003

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

• For other Windows platforms

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

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



• For UNIX/Linux

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

Data TypeString

See alsoMapping objects to tables on page 18Mapping properties on page 36ConfigOptions on page 93CreateMap on page 96

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 84 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



SpyAttributes

Data TypeString

See alsoTracking JDBC calls with DataDirect Spy on page 82DataDirect Spy attributes on page 84

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

Valid Valuesuserid

where:

userid

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

Data Source MethodsetUser


Data TypeString

See alsoRequired properties on page 36Company on page 93Password on page 98

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 1000 that defines the maximum number of rows the driver can attemptto fetch for each call.

Data Source MethodsetWSFetchSize

Default1000 (rows)

Data TypeInt

See alsoWeb service properties on page 37Performance considerations on page 38WSRetryCount on page 105WSTimeout on page 106

WSRetryCountDescriptionSpecifies the number of times the driver retries a timed-out Select request. Insert, Update, and Delete requestsare never retried. The timeout period is specified by the 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


WSRetryCount

Data TypeInt

See alsoWeb service properties on page 37WSFetchSize on page 104WSTimeout on page 106

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 37WSFetchSize on page 104WSRetryCount on page 105



5Troubleshooting

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


• Troubleshooting your application

• Using Java logging

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 82


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:eloqua:Company=ABCCorp;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 82

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

• INFO


Chapter 5: Troubleshooting

• 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

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.


Using Java logging

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 Eloqua-specific query being executed. Theactual 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.

Configuring LoggingYou can configure logging by using the properties file that was shipped with your JVM or by using the driver.

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.



Using the Driver for LoggingIf you want to configure logging using the driver, you can use either of the following approaches:

• Use a single properties file for all Oracle Eloqua connections.

• Use a different properties file for each relational map of your native Oracle Eloqua data. For example, if youhave two configuration files, such as C:\data\db\mydb1.config and C:\data\db\mydb2.config,you can load one properties file for the mydb1.config schema map and load another properties file forthe mydb2.config schema map.

Note: You must specify the name and path of the relational map using the SchemaMap property.

If a properties file is specified for the LogConfigFile connection property, the driver uses the following processto determine which file to load:

1. The driver looks for the file specified by the LogConfigFile property.

2. If the driver cannot find the file in Step 1 on page 111, it looks for a properties file namedschema_name.logging.properties in the directory containing the schema map configuration file,where schema_name is the name of the schema map configuration file.

3. If the driver cannot find the file in Step 2 on page 111, it looks for a properties file namedddlogging.properties in the current working directory.

4. If the driver cannot find the file in Step 3 on page 111 , it abandons its attempt to load a properties file.

If any of these files exist, but the logging initialization fails for some reason while using that file, the driver writesa warning to the standard output (System.out), specifying the name of the properties file being used.

A sample properties file is installed in the install_dir/testforjdbc.

See alsoSchemaMap on page 101LogConfigFile on page 97


Using Java logging

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)

• Delete

• Insert

• Refresh Map (EXT)

• Select

• Update

• 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 14: 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=eloqua

DatabaseCurrent_Schema

Resets the Web 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 eloqua.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

DeletePurposeThe Delete statement is used to delete rows from a table.

SyntaxDELETE FROM table_name [WHERE search_condition]

where:

table_name specifies the name of the table from which you want to delete rows.


Chapter 6: Supported SQL functionality

search_condition is an expression that identifies which rows to delete from the table.

The Where clause determines which rows are to be deleted. Without a Where clause, all rows of the table aredeleted, but the table is left intact. See Where clause on page 122 for information about the syntax of Whereclauses. Where clauses can contain subqueries.

Example AThis example shows a Delete statement on the emp table.

DELETE FROM emp WHERE emp_id = 'E10001'

Each Delete statement removes every record that meets the conditions in the Where clause. In this case,every record having the employee ID E10001 is deleted. Because employee IDs are unique in the employeetable, at most, one record is deleted.

Example BThis example shows using a subquery in a Delete clause.

DELETE FROM emp WHERE dept_id = (SELECT dept_id FROM dept WHERE dept_name = 'Marketing')

The records of all employees who belong to the department named Marketing are deleted.

InsertPurposeThe Insert statement is used to add new rows to a table. You can specify either of the following options:

• List of values to be inserted as a new row

• Select statement that copies data from another table to be inserted as a set of new rows

SyntaxINSERT INTO table_name [(column_name[,column_name]...)]{VALUES (expression [,expression]...) | select_statement}

table_name is the name of the table in which you want to insert rows.

column_name is optional and specifies an existing column. Multiple column names (a column list) must beseparated by commas. A column list provides the name and order of the columns, the values of which arespecified in the Values clause. If you omit a column_name or a column list, the value expressions mustprovide values for all columns defined in the table and must be in the same order that the columns are definedfor the table. Table columns that do not appear in the column list are populated with the default value, or withNULL if no default value is specified. See Specifying an external ID column on page 116 for more information.

expression is the list of expressions that provides the values for the columns of the new record. Typically,the expressions are constant values for the columns. Character string values must be enclosed in singlequotation marks (’). See Literals on page 129 for more information.

select_statement is a query that returns values for each column_name value specified in the column list.Using a Select statement instead of a list of value expressions lets you select a set of rows from one tableand insert it into another table using a single Insert statement. The Select statement is evaluated beforeany values are inserted. This query cannot be made on the table into which values are inserted. See Selecton page 117 for information about Select statements.


Insert

Specifying an external ID columnUse the following syntax to specify an external ID column to look up the value of a foreign key column.

Syntaxcolumn_name EXT_ID [schema_name.[table_name.] ]ext_id_column

where:

EXT_ID

is used to specify that the column specified by ext_id_column is used to look up the rowid to beinserted into the column specified by column_name.

schema_name

is the name of the schema of the table that contains the foreign key column being specified as theexternal ID column.

table_name

is the name of the table that contains the foreign key column being specified as the external IDcolumn.

ext_id_column

is the external ID column.

Example AThis example uses a list of expressions to insert records. Each Insert statement adds one record to thedatabase table. In this case, one record is added to the table emp. Values are specified for five columns. Theremaining columns in the table are assigned the default value or NULL if no default value is specified.

INSERT INTO emp (last_name,first_name,emp_id,salary,hire_date)

VALUES ('Smith', 'John', 'E22345', 27500, {1999-04-06})

Example BThis example uses a Select statement to insert records. The number of columns in the result of the Selectstatement must match exactly the number of columns in the table if no column list is specified, or it must matchthe number of column names specified in the column list. A new entry is created in the table for every row ofthe Select result.

INSERT INTO emp1 (first_name,last_name,emp_id,dept,salary)

SELECT first_name, last_name, emp_id, dept, salary FROM empWHERE dept = 'D050'



Example CThis example uses a list of expressions to insert records and specifies an external ID column (a foreign keycolumn) named accountId that references a table that has an external ID column named AccountNum.

INSERT INTO emp (last_name,first_name,emp_id,salary,hire_date,accountId EXT_ID AccountNum)

VALUES ('Smith', 'John', 'E22345', 27500, {1999-04-06}, 0001)

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 schema map configurationfile.

SyntaxREFRESH MAP

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

SelectPurposeThe Select statement can be used 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][orderby_clause][limit_clause]

where:

select_clause

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


Refresh Map (EXT)

from_clause

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

where_clause

is optional and restricts the results that are returned by the query. See Where clause on page 122 fora complete explanation.

groupby_clause

is optional and allows query results to be aggregated in terms of groups. See Group By clause onpage 123 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 123 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 124 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 125 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 126 for a complete explanation.

orderby_clause

is optional and sorts the results that are returned by the query. See Order By clause on page 126 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 127 for a complete explanation.

Select clauseThe Select clause can be used to specify column expressions that identify columns of values that you wantto retrieve or an asterisk (*) to retrieve the value of all columns.



SyntaxSELECT [{LIMIT offsetnumber | TOP number}] [ALL | DISTINCT] {* | column_expression[[AS] column_alias] [,column_expression [[AS] column_alias], ...]}[INTO [DISK | TEMP] new_table]SELECT [{LIMIT offsetlimit | TOP limit}][ALL | DISTINCT]{select_expression | table.* | *} [, ...][INTO [DISK | TEMP] new_table]

where:

LIMIT offset number creates the result set for the Select statement first and then discards the firstnumber of rows specified by offset and returns the number of remaining rows specified by number. To notdiscard any of the rows, specify 0 for offset, for example, LIMIT 0 number. To discard the first offsetnumber of 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 expressionsmay include mathematical operations or string manipulation (for example, salary * 1.05). See SQLexpressions on page 129 for details. column_expression can also include aggregate functions. See Aggregatefunctions on page 120 for details.

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

SELECT dep AS department FROM emp

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.

The DISTINCT operator can precede the first column expression. This operator eliminates duplicate rows fromthe result of a query. For example:

SELECT DISTINCT dep FROM emp

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

The INTO clause copies the result set into new_table. INTO DISK creates the new table in cached memory.INTO TEMP creates a temporary table.

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.


Select

Aggregate functionsAggregate functions can also be a part of a Select clause. Aggregate functions return a single value from aset of rows. An aggregate can be used with a field 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. For example:

COUNT (DISTINCT last_name)

In this example, only distinct last name values are counted.

The following table lists valid aggregate functions.

Table 15: Aggregate Functions

ReturnsAggregate

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

SUM

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

AVG

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

COUNT

The maximum value in any field expression. For example, MAX(SALARY) returns themaximum salary field value.

MAX

The minimum value in any field expression. For example, MIN(SALARY) returns theminimum salary field value.

MIN

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 122 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 aliasfor a 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 analias for 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 statementjoins a 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 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} 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 clauseYou can use a Join as a way to associate multiple tables within a Select statement. Joins may be eitherexplicit or implicit. For example, the following is the example from the previous section restated as an explicitinner join:

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

SyntaxFROM table_name {RIGHT OUTER | INNER | LEFT OUTER | CROSS} JOIN table.key ONsearch-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). For example:

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

Where clause

PurposeSpecifies the conditions that rows must meet to be retrieved.

SyntaxWHERE expr1 rel_operator expr2

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.

ExampleThis 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 alsoSubqueries on page 136

SQL expressions on page 129

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 theSelect clause. Also, the Group By clause must include all non-aggregate columns specified inthe Select list.

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.



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.


Select

SyntaxHAVING expr1 rel_operator expr2

where:

expr1

is a column name, a constant value, or an expression. An expression does not have to match acolumn expression in the Select clause.

expr2

is a column name, a constant value, or an expression. An expression does not have to match acolumn expression in the Select clause.

rel_operator

is the relational operator that links the two expressions.

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

SELECT dept_id, sum(salary) FROM empGROUP 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 theAll keyword (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 bydata type.

SELECT last_name, salary FROM empUNIONSELECT salary, last_name FROM raises

Intersect operator

PurposeReturns a single result set. The result set contains rows that are returned by both Select statements. Duplicatesare returned unless the DISTINCT operator is added.

Syntaxselect_statementINTERSECT [DISTINCT]select_statement

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 empUNIONSELECT salary, last_name FROM raises

Except and Minus operators

PurposeReturns the rows from the left Select statement that are not included in the result of the right Select statement.These operators are synonymous.

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

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

PurposeSpecifies 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 empORDER BY last_name, first_name

or

SELECT emp_id, last_name, first_name FROM empORDER BY 2,3

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



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 number ofrows to skip.

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.


Select

ExampleThe following example returns a maximum of 20 rows.

SELECT last_name, first_name FROM emp WHERE salary > 20000 ORDER BY dept_idLIMIT 20

UpdatePurposeAn Update statement changes the value of columns in selected rows of a table.

SyntaxUPDATE table_name SET column_name = expression[, column_name = expression] [WHERE conditions]

table_name

Is the name of the table for which you want to update values.

column_name

Is the name of a column, the value of which is to be changed. Multiple column values can be changedin a single statement.

expression

Is the new value for the column. The expression can be a constant value or a subquery that returnsa single value. Subqueries must be enclosed in parentheses.

Notes• A Where clause can be used to restrict which rows are updated.


Where clause on page 122

Example AThe following example changes every record that meets the conditions in the Where clause. In this case, thesalary and exempt status are changed for all employees having the employee ID E10001. Because employeeIDs are unique in the emp table, only one record is updated.

UPDATE emp SET salary=32000, exempt=1 WHERE emp_id = 'E10001'

Example BThe following example uses a subquery. In this example, the salary is changed to the average salary in thecompany for the employee having employee ID E10001.

UPDATE emp SET salary = (SELECT avg(salary) FROM emp) WHERE emp_id = 'E10001'



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 NamesThe most 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.


SQL expressions

Table 16: 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

'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


SQL expressions

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 17: 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.

Table 18: 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 19: 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


SQL expressions


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 20: 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 the Where 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.



Table 21: 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 142.

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.


SQL expressions

Table 22: 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)



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)


Subqueries

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)



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)


Subqueries

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 driver, as listed in the following table.

Example:

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

Table 23: 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 "unsupported method"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 "unsupported method"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 the WSTimeout 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, the Mapargument is ignored.

Yes2.0 CoreObject getObject(int, Map)

Yes1.0Object getObject(String)

The Oracle and Sybase drivers support theMap argument. For all other drivers, the Mapargument 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, Impala,Informix, MongoDB, Progess OpenEdge,Oracle Service Cloud, Oracle Eloqua, OracleSales Cloud, and Salesforce throw an"unsupported method" exception.




Statement Methods

The Apache Hive, Apache Spark SQL1,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 [])

1 Supported only for Apache Spark SQL 2.0 and higher. For earlier versions of Apache Spark SQL, the driver throws an "unsupportedmethod" exception.


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 Apache Hive, Apache Spark SQL,Impala, Informix and Progress OpenEdgedrivers return 0.




Statement Methods

The drivers for Apache Cassandra,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 exceptionindicating that the statement was timed out.


Statement


Statement Methods

The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The drivers for Apache Hive, Apache SparkSQL, Impala, and Informix throw an"unsupported method" exception.

The drivers for Greenplum, 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




XAConnection

9JDBC extensions

This section describes the JDBC extensions in the com.ddtek.jdbc.extensions package that can beused with the Oracle Eloqua 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 standardJDBC metadata results returned by the DatabaseMetaData.getColumns()method to include the followingadditional columns.


Table 24: 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 25: 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 Database Metadata Methods onpage 204

Reduce network traffic.Network communication is slow.

Using Database Metadata Methods onpage 204

Selecting JDBC Objects and Methodson page 208

Simplify queries.Evaluation of complex SQL queries onthe database server is slow and canreduce concurrency.


See guidelines in…SolutionProblem

Returning Data on page 206

Selecting JDBC Objects and Methodson page 208

Optimize application-to-driverinteraction.

Excessive calls from the application tothe driver slow performance.

Managing Connections and Updateson page 211

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 JDBC methods, 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 two major 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 and maximum 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 updateXXX methods 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.



Glossary

authenticationThe process of identifying a user, typically based on a user ID and password. Authentication ensures that theuser is who they claim to be. See also client authentication, NTLM authentication, OS authentication, and userID/password authentication.

bulk loadThe process of sending large numbers of rows of data to the database in a continuous stream instead of innumerous smaller database protocol packets. This process also is referred to as bulk copy.

client authenticationClient authentication uses the user ID and password of the user logged onto the system on which the driver isrunning to authenticate the user to the database. The database server depends on the client to authenticatethe user and does not provide additional authentication. See also authentication.

client load balancingClient load balancing distributes new connections in a computing environment so that no one server isoverwhelmed with connection requests.

connection poolingConnection pooling allows you to reuse connections rather than create a new one every time a driver needsto establish a connection to the database. Connection pooling manages connection sharing across differentuser requests to maintain performance and reduce the number of new connections that must be created. Seealso DataDirect Connection Pool Manager.

connection retryConnection retry defines the number of times the driver attempts to connect to the primary and, if configured,alternate database servers after an initial unsuccessful connection attempt. Connection retry can be an importantstrategy for system recovery.

connection URLA connection URL is a string passed by an application to the Driver Manager that contains information requiredto establish a connection. See also Driver Manager.

DataDirect Connection Pool ManagerThe DataDirect Connection Pool Manager is a component shipped with Progress DataDirect drivers that allowsapplications to use connection pooling.


DataDirect DB2 Package ManagerA Java graphical tool shipped with DataDirect Connect Series for JDBC for creating, dropping, and replacingDB2 packages for DB2.

DataDirect SpyDataDirect Spy allows you to track and log detailed information about JDBC calls made by the drivers at runtime.This functionality is built into the drivers.

DataDirect TestDataDirect Test is a menu-driven component shipped with Progress DataDirect drivers that helps you debugyour applications and learn how to use the drivers. DataDirect Test displays the results of all JDBC functioncalls in one window, while displaying fully commented, Java JDBC code in an alternate window.

data sourceA data source is a DataSource object that provides the connection information needed to connect to a database.The main advantage of using a data source is that it works with the Java Naming Directory Interface (JNDI)naming service, and it is created and managed apart from the applications that use it.

Driver ManagerThe main purpose of the Driver Manager is to load drivers for the application. The Driver Manager also processesJDBC initialization calls and maps data sources to a specific driver.

failoverFailover allows an application to connect to an alternate, or backup, database server. Progress DataDirectdrivers provide different levels of failover: connection failover, extended connection failover, and select failover.

indexA database structure used to improve the performance of database activity. A database table can have one ormore indexes associated with it.

isolation levelAn isolation level represents a particular locking strategy employed in the database system to improve dataconsistency. The higher the isolation level number, the more complex the locking strategy behind it. The isolationlevel provided by the database determines how a transaction handles data consistency.

The American National Standards Institute (ANSI) defines four isolation levels:

• Read uncommitted (0)

• Read committed (1)

• Repeatable read (2)

• Serializable (3)

J2EEJ2EE (Java 2 Platform, Enterprise Edition) technology and its component-based model simplify enterprisedevelopment and deployment. The J2EE platform manages the infrastructure and supports the Web servicesto enable development of secure, robust and interoperable business applications. Also known as Java EE(Java Platform, Enterprise Edition).

JDBC data sourceSee data source.

JNDIThe Java Naming and Directory Interface (JNDI) is a standard extension to the Java platform, providing Javatechnology-enabled applications with a unified interface to multiple naming and directory services in theenterprise. As part of the Java Enterprise API set, JNDI enables seamless connectivity to heterogeneousenterprise naming and directory services. Developers can now build powerful and portable directory-enabledapplications using this industry standard.


Glossary

JTAJTA (Java Transaction API) specifies standard Java interfaces between a transaction manager and the partiesinvolved in a distributed transaction system: the resource manager, the application server, and the transactionalapplications.

KerberosKerberos is an OS authentication protocol that provides authentication using secret key cryptography. Seealso authentication and OS authentication.

load balancingSee client load balancing.

locking levelLocking is a database operation that restricts a user from accessing a table or record. Locking is used insituations where more than one user might try to use the same table at the same time. By locking the table orrecord, the system ensures that only one user at a time can affect the data.

NTLM authenticationNTLM (NT LAN Manager) is an authentication protocol that provides security for connections between Windowsclients and servers. See also authentication and OS authentication.

OS authenticationOS authentication can take advantage of the user name and password maintained by the operating system toauthenticate users to the database or use another set of user credentials specified by the application. Byallowing the database to share the user name and password used for the operating system, users with a validoperating system account can log into the database without supplying a user name and password. See alsoauthentication, Kerberos authentication, and NTLM authentication.

reauthenticationThe process of switching the user associated with a connection to another user to help minimize the numberof connections required in a connection pool.

resource adapterA resource adapter is a system-level software driver used by an application server to connect to an EnterpriseInformation Service (EIS). The resource adapter communicates with the server to provide the underlyingtransaction, security, and connection pooling mechanisms.

Secure Socket LayerSecure Socket Layer (SSL) is an industry-standard protocol for sending encrypted data over databaseconnections. SSL secures the integrity of your data by encrypting information and providing SSL client/SSLserver authentication. See also SSL client/server authentication.

SSL client and server authenticationSSL (Secure Socket Layer) works by allowing the client and server to send each other encrypted data thatonly they can decrypt. SSL negotiates the terms of the encryption in a sequence of events known as the SSLhandshake. The handshake involves the following types of authentication:

• SSL server authentication requires the server to authenticate itself to the client.

• SSL client authentication is optional and requires the client to authenticate itself to the server after the serverhas authenticated itself to the client.

See also Secure Socket Layer.

UnicodeA standard for representing characters as integers. Unlike ASCII, which uses 7 bits for each character, Unicodeuses 16 bits, which means that it can represent more than 65,000 unique characters. This is necessary formany languages, such as Greek, Chinese, and Japanese.

user ID and password authenticationUser ID and password authentication authenticates the user to the database using a database user name andpassword. See also authentication.


Glossary

Index

Aaggregate functions 120Alter Session (EXT) 113application

troubleshooting 107arithmetic operators 132Array interface, methods 146ASCII

encoding 39auto generated keys

example, retrieving 211performance optimization 211

auto-generated keys 48auto-increment column 48Autocommit mode 212

Bbatch inserts and updates

batch execution on a prepared statement withDataDirect Test 62using instead of prepared statements 209

binaryliterals 131operators 132

Blob interface, methods 147Blobs

retrieving with DataDirect Test 77bulk load

BulkActivityPageSize 89BulkPageSize 90BulkTimeout 91BulkTopThreshold 92connection properties 37

Bulk operation timeouts 45bulk operations

efficient queries 41BulkActivityPageSize 89BulkPageSize 90BulkTimeout 91BulkTopThreshold 92

CCallableStatement interface, methods 148catalog tables 42character string literals 131CheckBoxAsText (configuration option 94class path

setting 22, 30

classesDataSource 12, 21, 30Driver 12, 21, 30

CLOBreturning long data 46

Clob interface, methods 159Clobs

retrieving with DataDirect Test 77column

names 129committing transactions 212Company 93comparison operators 133concatenation operator 132conditions 135ConfigOptions 93configuration options

CheckBoxAsText 94KeywordConflictSuffix 95

connectingconnection URL 22, 31DataDirect Test

using a data source 52using driver/database selection 52

using DataDirect Test 51with a proxy server 39with data sources 26, 34

connectiontesting 23, 31

Connection interface, methods 160connection management 212Connection object

managing connections 212transaction model 213

connection poolingperformance optimization 212

connection propertiesadditional 38BulkActivityPageSize 89BulkPageSize 90BulkTimeout 91BulkTopThreshold 92Company 93ConfigOptions 93FailOnIncompleteData 97LogConfigFile 97mapping 36overview 35Password 98ProxyHost 99ProxyPassword 99


Index

connection properties (continued)ProxyPort 100ProxyUser 101required 36SchemaMap 101SpyAttributes 82, 84, 103User 104web service 37WSFetchSize 104WSRetryCount 105WSTimeout 106

connection propertyCreateMap 96

connection property descriptions 87connection URL

overview 22, 31ConnectionEventListener interface, methods 165ConnectionPoolDataSource interface, methods 166copyrightcorrelated subqueries 138CreateMap 96cursors

choosing 210

Ddata encryption 39data source methods 87data sources

connecting with 26, 34creating 27, 35implementing 27, 35specifying SpyAttributes 82

data typesgetTypeInfo() results 14mapping 14

data types, choosing for performance 207database

table characteristics, using dummy query todetermine 205

database metadataretrieving with DataDirect Test 58

DatabaseMetaData interface 201DatabaseMetaData interface, methods 166DataDirect Spy

attributes 84enabling 82logging 107–108overview 82setEnableLogging() method 108SpyAttributes connection property 103troubleshooting 107

DataDirect Spy, enabling 83DataDirect Test

batch execution 62configuring 50

DataDirect Test (continued)connecting with 51database metadata, retrieving 58deleting rows 68executing

Select statement 54executing prepared statement 55inserting rows 68, 71LOB support 77parameter metadata, returning 64result set, scrolling through 60savepoints, establishing 65starting 51testing a connection 23, 31tutorial 49–50updatable result sets 68updating rows 68, 74using 49

DataSourcecalling in an application 27, 35connecting with 21, 30

DataSource class 12, 21, 30DataSource interface, methods 174date

escape sequence 142date/time literals 131Delete 114deleting rows

with DataDirect Test 68Driver class 12, 21, 30Driver interface, methods 175driver overview 11driver version string

format 13DriverManager

connecting with 21–22, 30specifying SpyAttribute 82specifying SpyAttributes 82

dummy query, using to determine table characteristics205

Eefficient queries

bulk operations 41encryption 39error handling

format 49escape sequences

date, time, and timestamp 142LIKE escape character for wildcards 144outer join 144

exampleouter join escape sequence 144

EXISTS predicate 137


Index

extensions packagedatadirect.jdbc.extensions package 201

external ID column, specifying 116ExtLogControl class, methods 202ExtLogControl interface 108

FFailOnIncompleteData 97forward-only cursor

performance implications 210From clause 120functions 135

GgetBestRowIdentifier() method 213getBlob() method 206getClob() method 206getObject() method 210getTypeInfo()

results 14

Hhelp, online 19

Iidentifiers 44IN predicate 137InputStream object, DataDirect Spy 83insensitive cursors

performance implications 210inserting rows

with DataDirect Test 71Inserts

parameter metadata 46integer literals 131Interfaces, JDBC 145

JJava logging

components 108JDBC API logger 109SQL engine logger 109using 108web service adapter logger 110

Java Naming Directory Interface (JNDI)connecting with 21, 30data sources 26, 34initializing environment 27, 35

Java requirements 12

JDBCinterfaces 145JVM compatibility 145SQL escape sequences 141versions supported 145

JDBC API logger 109JDBC data source, specifying SpyAttributes 83JDBC data sources

connecting with 26, 34JDBC data types

mapping 14JDBC DriverManager

connecting with 22, 30JDBC extensions

introduction 201JDBC requirements 12JNDI Provider for LDAP

saving a JDBC DataSource 27, 35join in a From clause 122JSR 114, Rowsets 48JTA support

transactionmodel, choosing for performance 213

JTA transaction supportmanaging commits 212

JVMJDBC compatibility 145

JVM logging 110JVM requirements 12

Kkeyset-driven cursors, performance implications 210KeywordConflictSuffix (configuration option) 95

Llarge object (LOB) support 46LDAP Directory

saving JDBC a DataSource 27, 35LIKE escape character for wildcards escape sequence144literals

about 129arguments, using parameter markers 208binary 131character string 131date 142date/time 131integer 131numeric 131time 142timestamp 142

LOBs supportexecuting a query with DataDirect Test 77

LogConfigFile 97


Index

loggingJVM 110with DataDirect Spy 82

logging, Javacomponents 108JDBC API logger 109SQL engine logger 109using 108web service adapter logger 110

logical operators 134long data

CLOB 46long data, retrieving and performance 206

Mmapping

data types 14objects to tables 18

metadatacatalog tables 42JDBC extensions 201ResultSet metadata 47

metadata methods, minimizing use of 204methods

Array interface 146Blob interface 147CallableStatement interface 148Clob interface 159Connection interface 160ConnectionEventListener interface 165ConnectionPoolDataSource interface 166DatabaseMetaData interface 166DataSource interface 174Driver interface 175ExtLogControl class 202ParameterMetaData interface 175PooledConnection interface 177PreparedStatement interface 177Ref interface 182ResultSet interface 182ResultSetMetaData interface 193RowSet interface 194SavePoint interface 194Statement interface 194StatementEventListener interface 198Struct interface 198XAConnection interface 199XADataSource interface 199XAResource interface 199

multilingual applicationsdevelopment 39

Nnaming conflicts

identifiers 44numeric literals 131

Oobject

Connectionmanaging connections 212transaction model 213

Long (DB2) 185mapping to tables 18PreparedStatement

using Statement object instead of 208ResultSet

database metadata 204generating 204updating data 213

Statementusing instead of PreparedStatement object 208using multiple 212

using addBatch() instead of PreparedStatement 209operators

arithmetic 132comparison 133concatenation 132logical 134precedence 134

outer join escape sequence, example 144outer join escape sequences 121overview

driver 11

Pparameter markers, using as arguments to storedprocedures 208parameter metadata

returning 46returning with DataDirect Test 64

ParameterMetaData interface, methods 175Password 98performance optimization

auto generated keys, retrieving 211batches, using instead of prepared statements 209commits, managing 212connection

management 212pooling 212

database metadata methods 204designing JDBC applications 211get methods, using effectively 210getBestRowIdentifier() 213result sets, retrieving 207


Index

performance optimization (continued)retrieving long data 206scrollable cursors 207selecting JDBC objects and methods 208transaction model, choosing 213update methods of the ResultSet object 213updating data 213

PooledConnection interface, methods 177predicate

EXISTS 137IN 137UNIQUE 137

prepared statement pooling, performance optimization212prepared statement, executing with DataDirect Test 55prepared statements

using batches instead of 209PreparedStatement interface, methods 177PreparedStatement object

performanceimplications of using Statement object instead208of prepared statement pool 212

prepared statement pooling 212using Statement object instead of 208

properties file for Java logging 111proxy server

connecting 39connection properties 38

ProxyHost 99ProxyPassword 99ProxyPort 100ProxyUser 101

RReader object, DataDirect Spy 83Ref interface, methods 182Refresh Map (EXT) 117requirements

Java SE 12JDBC 12JVM 12

result setsdeleting rows with DataDirect Test 68inserting rows with DataDirect Test 68scrolling through a result set with DataDirect Test 60updating rows with DataDirect Test 68

result sets, scrollableperformance optimization 207

ResultSet interface, methods 182ResultSet metadata 47ResultSet object

database metadata 204generating 204updating data 213

ResultSetMetaData interface, methods 193RowSet interface, methods 194Rowsets 48

SSavePoint interface, methods 194savepoints

establishing with DataDirect Test 65scalar functions 142SchemaMap 101scroll-insensitive result sets 45search patterns, avoiding 205security 39Select clause 117Select statement

executing with DataDirect Test 54selecting column expressions 118selects

parameter metadata 46sensitive cursors

performance implications 210server-side RPCs 208Session timeouts 45setEnableLogging() 108SpyAttributes 82, 84, 103SQL

expressions 129SQL engine logger 109SQL escape sequences

date, time, and timestamp 142LIKE escape character for wildcards 144outer join 144scalar functions 142

SQL statement support 113SQL statements

Alter Session 113Delete 114Insert 115

SQLExceptionsreporting 49

Statement interface, methods 194Statement object

Connection object association 212using instead of PreparedStatement object 208using multiple 212when to use 208

StatementEventListener interface, methods 198stored procedures

parameter markers as arguments, using 208Struct interface, methods 198subqueries

correlated 138overview 136

subquery in a From clause 122


Index

supportonline help 19technical support 19

syntaxconnection URL 22, 31

TTechnical Support 19testing a connection

instructions 23, 31time literal

escape sequence 142timeouts 45timestamp literal

escape sequence 142transactions , See JTA supporttroubleshooting

your application 107

Uunary operator 132Unicode support 39Union operator 124UNIQUE predicate 137UNIX class path

setting 22, 30updatable result sets 45updatable result sets, DataDirect Test 68Update statement 128Updates

parameter metadata 46

updating rowswith DataDirect Test 74

URLconnecting with 22, 30driver connection 12

User connection property 104UTF-16

conversion 39encoding 39

Vversion string information

format 13

Wweb service adapter logger 110Web service request timeouts 45Where clause 122–123, 125–127Windows class path

setting 22, 30WSFetchSize 104WSRetryCount 105WSTimeout 106

XXAConnection interface, methods 199XADataSource interface, methods 199XAResource interface, methods 199


Index

Progress DataDirect for JDBC forOracleEloqua · Releasehighlights Highlightsofthe6.0.0release •...

Documents

Transcript of Progress DataDirect for JDBC forOracleEloqua · Releasehighlights Highlightsofthe6.0.0release •...