Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new...

218
Progress ® DataDirect ® for JDBC Drivers Reference Release 6.0

Transcript of Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new...

Page 1: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Progress® DataDirect® forJDBC™ DriversReference

Release 6.0

Page 2: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:
Page 3: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Copyright

© 2019 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, Kinvey,NativeScript, OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase,SequeLink, Sitefinity (and Design), Sitefinity, SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (andDesign), Test Studio, and WebSpeed are registered trademarks of Progress Software Corporation or one ofits affiliates or subsidiaries in the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge, DataDirectAutonomous REST Connector, DataDirect Spy, SupportLink, DevCraft, Fiddler, JustAssembly, JustDecompile,JustMock, NativeChat, NativeScript Sidekick, OpenAccess, ProDataSet, Progress Results, Progress Software,ProVision, PSE Pro, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView,SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow,and WebClient are trademarks or service marks of Progress Software Corporation and/or its subsidiaries oraffiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any othermarks contained herein may be trademarks of their respective owners.

Updated: 2019/07/01

3Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 4: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Progress DataDirect for JDBC Drivers: Reference: Version 6.04

Copyright

Page 5: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Table of Contents

Welcome to the Progress DataDirect for JDBC Drivers Reference ..........9

Troubleshooting...........................................................................................11Troubleshooting your application..........................................................................................................11

Turning on and off DataDirect Spy logging................................................................................12DataDirect Spy Log Example.....................................................................................................12

Troubleshooting connection pooling.....................................................................................................14Enabling tracing with the setTracing method.............................................................................14Pool Manager Trace File Example.............................................................................................14

Troubleshooting statement pooling.......................................................................................................18Generating an export file with the exportStatement method......................................................18Statement pool export file example............................................................................................19

Using Java logging................................................................................................................................19Logging components..................................................................................................................20Configuring logging....................................................................................................................22

Contacting Technical Support...............................................................................................................23

Failover..........................................................................................................25Connection failover...............................................................................................................................26Extended connection failover................................................................................................................27Select connection failover.....................................................................................................................28Guidelines for primary and alternate servers........................................................................................29Using client load balancing ..................................................................................................................29Using connection retry..........................................................................................................................30

Client information.........................................................................................31How databases store client information................................................................................................32

Storing client information............................................................................................................32Returning client Information..................................................................................................................36Returning metadata about client information locations.........................................................................37

JDBC support...............................................................................................39Array......................................................................................................................................................40Blob.......................................................................................................................................................41CallableStatement.................................................................................................................................42Clob.......................................................................................................................................................54

5Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Contents

Page 6: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Connection............................................................................................................................................55ConnectionEventListener......................................................................................................................61ConnectionPoolDataSource..................................................................................................................61DatabaseMetaData...............................................................................................................................61DataSource...........................................................................................................................................70Driver.....................................................................................................................................................71ParameterMetaData..............................................................................................................................71PooledConnection.................................................................................................................................72PreparedStatement...............................................................................................................................73Ref.........................................................................................................................................................78ResultSet...............................................................................................................................................78ResultSetMetaData...............................................................................................................................89RowSet..................................................................................................................................................90SavePoint..............................................................................................................................................90Statement..............................................................................................................................................90StatementEventListener........................................................................................................................95Struct.....................................................................................................................................................95XAConnection.......................................................................................................................................95XADataSource......................................................................................................................................95XAResource..........................................................................................................................................96

JDBC extensions..........................................................................................97Using JDBC wrapper methods to access JDBC extensions.................................................................98DatabaseMetaData interface................................................................................................................99DDBulkLoad interface.........................................................................................................................100ExtConnection interface......................................................................................................................107ExtDatabaseMetaData interface.........................................................................................................112ExtLogControl class............................................................................................................................112

SQL escape sequences for JDBC............................................................113Date, time, and timestamp escape sequences...................................................................................114Scalar functions..................................................................................................................................114

String functions........................................................................................................................124Numeric functions....................................................................................................................126Date and time Functions..........................................................................................................127System functions......................................................................................................................129

Outer join escape sequences.............................................................................................................130LIKE escape character sequence for wildcards..................................................................................132Native and refresh escape sequences................................................................................................132

Designing JDBC applications for performance optimization................135Using database metadata methods....................................................................................................136

Minimizing the use of database metadata methods.................................................................136

Progress DataDirect for JDBC Drivers: Reference: Version 6.06

Contents

Page 7: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Avoiding search patterns..........................................................................................................137Using a dummy query to determine table characteristics........................................................137

Returning data....................................................................................................................................138Returning long data..................................................................................................................138Reducing the size of returned data..........................................................................................139Choosing the right data type....................................................................................................139Retrieving result sets................................................................................................................139

Selecting JDBC objects and methods ................................................................................................140Using parameter markers as arguments to stored procedures................................................140Using the statement object instead of the PreparedStatement object.....................................140Using batches instead of prepared statements........................................................................141Choosing the right cursor.........................................................................................................142Using get methods effectively..................................................................................................142Retrieving auto-generated keys...............................................................................................143

Managing connections and updates...................................................................................................143Managing connections.............................................................................................................144Managing commits in transactions...........................................................................................144Choosing the right transaction model.......................................................................................145Using updateXXX methods......................................................................................................145Using getBestRowIdentifier......................................................................................................145

DataDirect tools..........................................................................................147DataDirect Test...................................................................................................................................147

DataDirect Test tutorial.............................................................................................................148Connection Pool Manager..................................................................................................................180

How connection pooling works.................................................................................................180Implementing DataDirect connection pooling...........................................................................183Configuring the connection pool...............................................................................................186Connecting using a connection pool........................................................................................188Closing the connection pool.....................................................................................................190Checking the Pool Manager version........................................................................................190Enabling Pool Manager tracing................................................................................................190Connection Pool Manager interfaces.......................................................................................191

Statement Pool Monitor......................................................................................................................196Using DataDirect-specific methods to access the Statement Pool Monitor.............................196Using JMX to access the Statement Pool Monitor...................................................................198Importing statements into a statement pool.............................................................................200Clearing all statements in a statement pool.............................................................................201Freezing and unfreezing the statement pool............................................................................201Generating a statement pool export file...................................................................................201DataDirect Statement Pool Monitor interfaces and classes.....................................................202

Tracking JDBC calls with DataDirect Spy...........................................................................................204Enabling DataDirect Spy..........................................................................................................204

7Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Contents

Page 8: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Glossary.......................................................................................................209

Index.............................................................................................................213

Progress DataDirect for JDBC Drivers: Reference: Version 6.08

Contents

Page 9: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

1Welcome to the Progress DataDirect forJDBC Drivers Reference

This guide provides general information for the 6.0 version of Progress DataDirect drivers, includingtroubleshooting tips, descriptions of advanced features, and tutorials for DataDirect tools. The content of thisguide applies to all 6.0 versions of the JDBC drivers unless otherwise noted.

The reference acts as a compliment to the driver user's guides, which provide detailed instructions on configuringand using drivers. The full documentation set is available on the DataDirect Connectors Documentation WebPage.

Important: This guide describes features and functionality only for the 6.0 version of the drivers. For otherversions of the drivers, refer to DataDirect Connectors Documentation Web Page.

This guide contains:

• A Troubleshooting on page 11 section that provides information that can help you identify and resolve driverproblems.

• A detailed description of the following advanced features:

• Failover on page 25

• Client information on page 31

9Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 10: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

• The following general reference information:

• JDBC support on page 39 provides information about the JDBC interfaces and methods supported forProgress DataDirect for JDBC drivers.

• JDBC extensions on page 97 describes the JDBC extensions provided by the com.ddtek.jdbc.extensionspackage.

• Designing JDBC applications for performance optimization on page 135 explains how you optimize yourapplication code to improve performance.

• SQL escape sequences for JDBC on page 113 describes the scalar functions supported by the drivers.Your data store may not support all these functions.

• Tutorials for the following DataDirect tools:

• DataDirect Test on page 147 guides through a step-by-step example of how to use DataDirect Test™ forJDBC, a tool that allows you to test and debug your JDBC applications during development.

• Tracking JDBC calls with DataDirect Spy on page 204 describes how to use DataDirect Spy™ for JDBC fortracking JDBC calls in running applications.

• Connection Pool Manager on page 180 describes how to use the DataDirect Connection Pool Managerto create your own connection pooling mechanism.

• Statement Pool Monitor on page 196 describes how to use the DataDirect Statement Pool Monitor toimport statements to and remove statements from the statement pool, as well as generate informationto help you troubleshoot statement pooling performance.

Note: This reference refers the reader to Web pages using URLs for more information about specific topics,including Web URLs not maintained by Progress DataDirect. Because it is the nature of Web content to changefrequently, Progress DataDirect can guarantee only that the URLs in this reference were correct at the time ofpublishing.

Progress DataDirect for JDBC Drivers: Reference: Version 6.010

Chapter 1: Welcome to the Progress DataDirect for JDBC Drivers Reference

Page 11: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

2Troubleshooting

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

For details, see the following topics:

• Troubleshooting your application

• Troubleshooting connection pooling

• Troubleshooting statement pooling

• Using Java logging

• Contacting Technical Support

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

See alsoTracking JDBC calls with DataDirect Spy on page 204

11Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 12: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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 DataDirectSpy logging is enabled, all Connection objects returned to an application provide an implementation of theExtLogControl interface.

For example, the following code turns off logging using setEnableLogging(false):

import com.ddtek.jdbc.extensions.*

// Get Database ConnectionConnection con = DriverManager.getConnection

("jdbc:datadirect:sqlserver://server1:1433;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 204

DataDirect Spy Log ExampleThis section provides information to help you understand the content of your own DataDirect Spy logs. Forexample, suppose your application executes the following code and performs some operations:

Class.forName("com.ddtek.jdbc.sqlserver.SQLServerDriver");DriverManager.getConnection("jdbc:datadirect:sqlserver:// nc-myserver\\sqlserver2005;useServerSideUpdatableCursors=true;resultsetMetaDataOptions=1;sendStringParametersAsUnicode=true;alwaysReportTriggerResults=false;spyAttributes=(log=(file)c:\\temp\\spy.log)","test04", "test04");

The log file generated by DataDirect Spy would look similar to the following example. Notes provide explanationsfor the referenced text.

spy>> Connection[1].getMetaData()spy>> OK (DatabaseMetaData[1])

spy>> DatabaseMetaData[1].getURL()spy>> OK(jdbc:datadirect:sqlserver://nc-myserver\sqlserver2005:1433;CONNECTIONRETRYCOUNT=5;RECEIVESTRINGPARAMETERTYPE=nvarchar;ALTERNATESERVERS=;DATABASENAME=;PACKETSIZE=16;INITIALIZATIONSTRING=;ENABLECANCELTIMEOUT=false;BATCHPERFORMANCEWORKAROUND=false;AUTHENTICATIONMETHOD=auto;SENDSTRINGPARAMETERSASUNICODE=true;LOGINTIMEOUT=0;WSID=;SPYATTRIBUTES=(log=(file)c:\temp\spy.log);RESULTSETMETADATAOPTIONS=1;ALWAYSREPORTTRIGGERRESULTS=false;TRANSACTIONMODE=implicit;USESERVERSIDEUPDATABLECURSORS=true;SNAPSHOTSERIALIZABLE=false;JAVADOUBLETOSTRING=false;SELECTMETHOD=direct;LOADLIBRARYPATH=;CONNECTIONRETRYDELAY=1;INSENSITIVERESULTSETBUFFERSIZE=2048;MAXPOOLEDSTATEMENTS=0;DESCRIBEPARAMETERS=noDescribe;CODEPAGEOVERRIDE=;NETADDRESS=000000000000;PROGRAMNAME=;LOADBALANCING=false;HOSTPROCESS=0)1

spy>> DatabaseMetaData[1].getDriverName()spy>> OK (SQLServer)

spy>> DatabaseMetaData[1].getDriverVersion()spy>> OK (3.60.0 (000000.000000.000000))

1 The combination of the URL specified by the application and the default values of all connection properties not specified.

Progress DataDirect for JDBC Drivers: Reference: Version 6.012

Chapter 2: Troubleshooting

Page 13: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

spy>> DatabaseMetaData[1].getDatabaseProductName()spy>> OK (Microsoft SQL Server)

spy>> DatabaseMetaData[1].getDatabaseProductVersion()spy>> OK (Microsoft SQL Server Yukon - 9.00.1399)

spy>> Connection Options : 2

spy>> CONNECTIONRETRYCOUNT=5spy>> RECEIVESTRINGPARAMETERTYPE=nvarcharspy>> ALTERNATESERVERS=spy>> DATABASENAME=spy>> PACKETSIZE=16spy>> INITIALIZATIONSTRING=spy>> ENABLECANCELTIMEOUT=falsespy>> BATCHPERFORMANCEWORKAROUND=falsespy>> AUTHENTICATIONMETHOD=autospy>> SENDSTRINGPARAMETERSASUNICODE=truespy>> LOGINTIMEOUT=0spy>> WSID=spy>> SPYATTRIBUTES=(log=(file)c:\temp\spy.log)spy>> RESULTSETMETADATAOPTIONS=1spy>> ALWAYSREPORTTRIGGERRESULTS=falsespy>> TRANSACTIONMODE=implicitspy>> USESERVERSIDEUPDATABLECURSORS=truespy>> SNAPSHOTSERIALIZABLE=falsespy>> JAVADOUBLETOSTRING=falsespy>> SELECTMETHOD=directspy>> LOADLIBRARYPATH=spy>> CONNECTIONRETRYDELAY=1spy>> INSENSITIVERESULTSETBUFFERSIZE=2048spy>> MAXPOOLEDSTATEMENTS=0spy>> DESCRIBEPARAMETERS=noDescribespy>> CODEPAGEOVERRIDE=spy>> NETADDRESS=000000000000spy>> PROGRAMNAME=spy>> LOADBALANCING=falsespy>> HOSTPROCESS=0spy>> Driver Name = SQLServer 3

spy>> Driver Version = 3.60.0 (000000.000000.000000) 4

spy>> Database Name = Microsoft SQL Server 5

spy>> Database Version = Microsoft SQL Server Yukon - 9.00.1399 6

spy>> Connection[1].getWarnings()spy>> OK 7spy>> Connection[1].createStatementspy>> OK (Statement[1])

spy>> Statement[1].executeQuery(String sql)spy>> sql = select empno,ename,job from emp where empno=7369spy>> OK (ResultSet[1]) 8

spy>> ResultSet[1].getMetaData()spy>> OK (ResultSetMetaData[1]) 9

spy>> ResultSetMetaData[1].getColumnCount()spy>> OK (3)10

spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 1spy>> OK (EMPNO)11spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 2spy>> OK (ENAME)12

2 The combination of the connection properties specified by the application and the default values of all connection properties not specified.3 The name of the driver.4 The version of the driver.5 The name of the database server to which the driver connects.6 The version of the database to which the driver connects.7 The application checks to see if there are any warnings. In this example, no warnings are present.8

The statement select empno,ename,job from emp where empno=7369 is created.9 Some metadata is requested.

10 Some metadata is requested.11 Some metadata is requested.12 Some metadata is requested.

13Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Troubleshooting your application

Page 14: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 3spy>> OK (JOB)13spy>> ResultSet[1].next()spy>> OK (true)14

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 1spy>> OK (7369) 15

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 2spy>> OK (SMITH) 16

spy>> ResultSet[1].getString(int columnIndex)spy>> columnIndex = 3spy>> OK (CLERK) 17

spy>> ResultSet[1].next()spy>> OK (false) 18spy>> ResultSet[1].close()spy>> OK 19

spy>> Connection[1].close()spy>> OK 20

Troubleshooting connection poolingConnection pooling allows connections to be reused rather than created each time a connection is requested.If your application is using connection pooling through the DataDirect Connection Pool Manager, you cangenerate a trace file that shows all the actions taken by the Pool Manager. See "Connection Pool Manager"for information about using the Pool Manager.

See alsoConnection Pool Manager on page 180

Enabling tracing with the setTracing methodYou can enable Pool Manager logging by calling setTracing(true) on the PooledConnectionDataSourceconnection. To disable tracing, call setTracing(false) on the connection.

By default, the DataDirect Connection Pool Manager logs its pool activities to the standard output System.out.You can change where the Pool Manager trace information is written by calling the setLogWriter() methodon the PooledConnectionDataSource connection.

Pool Manager Trace File ExampleThe following example shows a DataDirect Connection Pool Manager trace file. Notes provide explanationsfor the referenced text to help you understand the content of your own Pool Manager trace files.

jdbc/SQLServerNCMarkBPool: *** ConnectionPool Created(jdbc/SQLServerNCMarkBPool,

13 Some metadata is requested.14 The first row is retrieved and the application retrieves the result values.15 The first row is retrieved and the application retrieves the result values.16 The first row is retrieved and the application retrieves the result values.17 The first row is retrieved and the application retrieves the result values.18 The application attempts to retrieve the next row, but only one row was returned for this query.19 After the application has completed retrieving result values, the result set is closed.20 The application finishes and disconnects.

Progress DataDirect for JDBC Drivers: Reference: Version 6.014

Chapter 2: Troubleshooting

Page 15: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

com.ddtek.jdbcx.sqlserver.SQLServerDataSource@1835282, 5, 5, 10, scott)21

jdbc/SQLServerNCMarkBPool: Number pooled connections = 0.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Enforced minimum!22

NrFreeConnections was: 0jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 5.

jdbc/SQLServerNCMarkBPool: Reused free connection.23

jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 4.

jdbc/SQLServerNCMarkBPool: Reused free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 3.

jdbc/SQLServerNCMarkBPool: Reused free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 2.

jdbc/SQLServerNCMarkBPool: Reused free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 1.

jdbc/SQLServerNCMarkBPool: Reused free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Created new connection.24

jdbc/SQLServerNCMarkBPool: Number pooled connections = 6.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Created new connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 7.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Created new connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 8.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Created new connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 9.

21 The Pool Manager creates a connection pool. In this example, the characteristics of the connection pool are shown using the following format:

(JNDI_name,DataSource_class,initial_pool_size,min_pool_size,max_pool_size,user)

where:

JNDI_name is the JNDI name used to look up the connection pool (for example, jdbc/SQLServerNCMarkBPool).

DataSource_class is the DataSource class associated with the connection pool (for examplecom.ddtek.jdbcx.sqlserver.SQLServerDataSource).

initial_pool_size is the number of physical connections created when the connection pool is initialized (for example, 5).

min_pool_size is the minimum number of physical connections be kept open in the connection pool (for example, 5).

max_pool_size is the maximum number of physical connections allowed within a single pool at any one time. When thisnumber is reached, additional connections that would normally be placed in a connection pool are closed (for example, 10).

user is the name of the user establishing the connection (for example, scott).22 The Pool Manager checks the pool size. Because the minimum pool size is five connections, the Pool Manager creates new connections to

satisfy the minimum pool size.23 The driver requests a connection from the connection pool. The driver retrieves an available connection.24 The driver requests a connection from the connection pool. Because a connection is unavailable, the Pool Manager creates a new connection

for the request.

15Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Troubleshooting connection pooling

Page 16: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Created new connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Created new connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.25

jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 1.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 2.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 3.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 4.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 5.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 6.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 7.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 8.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 9.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 10.

jdbc/SQLServerNCMarkBPool: Connection was closed and added to the cache.jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 11.

jdbc/SQLServerNCMarkBPool: Enforced minimum!26

NrFreeConnections was: 11jdbc/SQLServerNCMarkBPool: Number pooled connections = 11.jdbc/SQLServerNCMarkBPool: Number free connections = 11.

jdbc/SQLServerNCMarkBPool: Enforced maximum!27

NrFreeConnections was: 11jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 10.

25 A connection is closed by the application and returned to the connection pool.26 The Pool Manager checks the pool size. Because the number of connections in the connection pool is greater than the minimum pool size,

five connections, no action is taken by the Pool Manager.27 The Pool Manager checks the pool size. Because the number of connections in the connection pool is greater than the maximum pool size,

10 connections, a connection is closed and discarded from the pool.

Progress DataDirect for JDBC Drivers: Reference: Version 6.016

Chapter 2: Troubleshooting

Page 17: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

jdbc/SQLServerNCMarkBPool: Enforced minimum!NrFreeConnections was: 10jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 10.

jdbc/SQLServerNCMarkBPool: Enforced maximum!NrFreeConnections was: 10jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 10.

jdbc/SQLServerNCMarkBPool: Enforced minimum!NrFreeConnections was: 10jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 10.

jdbc/SQLServerNCMarkBPool: Enforced maximum!NrFreeConnections was: 10jdbc/SQLServerNCMarkBPool: Number pooled connections = 10.jdbc/SQLServerNCMarkBPool: Number free connections = 10.

jdbc/SQLServerNCMarkBPool: Dumped free connection.28

jdbc/SQLServerNCMarkBPool: Number pooled connections = 9.jdbc/SQLServerNCMarkBPool: Number free connections = 9.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 8.jdbc/SQLServerNCMarkBPool: Number free connections = 8.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 7.jdbc/SQLServerNCMarkBPool: Number free connections = 7.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 6.jdbc/SQLServerNCMarkBPool: Number free connections = 6.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 5.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 4.jdbc/SQLServerNCMarkBPool: Number free connections = 4.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 3.jdbc/SQLServerNCMarkBPool: Number free connections = 3.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 2.jdbc/SQLServerNCMarkBPool: Number free connections = 2.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 1.jdbc/SQLServerNCMarkBPool: Number free connections = 1.

jdbc/SQLServerNCMarkBPool: Dumped free connection.jdbc/SQLServerNCMarkBPool: Number pooled connections = 0.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

jdbc/SQLServerNCMarkBPool: Enforced minimum!29

NrFreeConnections was: 0jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.

28 The Pool Manager detects that a connection was idle in the connection pool longer than the maximum idle timeout. The idle connection isclosed and discarded from the pool.

29 The Pool Manager detects that the number of connections dropped below the limit set by the minimum pool size, five connections. The PoolManager creates new connections to satisfy the minimum pool size.

17Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Troubleshooting connection pooling

Page 18: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

jdbc/SQLServerNCMarkBPool: Number free connections = 5.

jdbc/SQLServerNCMarkBPool: Enforced maximum!NrFreeConnections was: 5jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 5.

jdbc/SQLServerNCMarkBPool: Closing a pool of the groupjdbc/SQLServerNCMarkBPool30

jdbc/SQLServerNCMarkBPool: Number pooled connections = 5.jdbc/SQLServerNCMarkBPool: Number free connections = 5.

jdbc/SQLServerNCMarkBPool: Pool closed31

jdbc/SQLServerNCMarkBPool: Number pooled connections = 0.jdbc/SQLServerNCMarkBPool: Number free connections = 0.

Troubleshooting statement poolingSimilar to connection pooling, statement pooling provides performance gains for applications that execute thesame SQL statements multiple times in the life of the application. The DataDirect Statement Pool Monitorprovides the following functionality to help you troubleshoot problems that may occur with statement pooling:

• You can generate a statement pool export file that shows you all statements in the statement pool. Eachstatement pool entry in the file includes information about statement characteristics such as the SQL textused to generate the statement, statement type, result set type, and result set concurrency type.

• You can use the following methods of the ExtStatementPoolMonitorMBean interface to return usefulinformation to determine if your workload is using the statement pool effectively:

• The getHitCount method returns the hit count for the statement pool. The hit count should be highfor good performance.

• The getMissCount method returns the miss count for the statement pool. The miss count should below for good performance.

See alsoStatement Pool Monitor on page 196

Generating an export file with the exportStatement methodYou can generate an export file by calling the exportStatements method of theExtStatementPoolMonitorMBean interface. For example, the following code exports the contents of thestatement pool associated with the connection to a file named stmt_export.

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor();

exportStatements(stmt_export.txt)

30 The Pool Manager closes one of the connection pools in the pool group. A pool group is a collection of pools created from the samePooledConnectionDataSource call. Different pools are created when different user IDs are used to retrieve connections from the pool. A poolgroup is created for each user ID that requests a connection. In our example, because only one user ID was used, only one pool group isclosed.

31 The Pool Manager closed all the pools in the pool group. The connection pool is closed.

Progress DataDirect for JDBC Drivers: Reference: Version 6.018

Chapter 2: Troubleshooting

Page 19: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Statement pool export file exampleThe following example shows a sample export file. The footnotes provide explanations for the referenced textto help you understand the content of your own statement pool export files.

[DDTEK_STMT_POOL]32

VERSION=133

[STMT_ENTRY]34

SQL_TEXT=[INSERT INTO emp(id, name) VALUES(?,?)]STATEMENT_TYPE=Prepared StatementRESULTSET_TYPE=Forward OnlyRESULTSET_CONCURRENCY=Read OnlyAUTOGENERATEDKEYSREQUESTED=falseREQUESTEDKEYCOLUMNS=

[STMT_ENTRY]35

SQL_TEXT=[INSERT INTO emp(id, name) VALUES(99,?)]STATEMENT_TYPE=Prepared StatementRESULTSET_TYPE=Forward OnlyRESULTSET_CONCURRENCY=Read OnlyAUTOGENERATEDKEYSREQUESTED=falseREQUESTEDKEYCOLUMNS=id,name

Using Java loggingThe following drivers support Java logging:

• Apache Cassandra

• Autonomous REST Connector

• Jira

• MongoDB

• Oracle Eloqua

• Oracle Sales Cloud

• Salesforce

Java logging is a flexible and comprehensive mechanism that allows logging to be incorporated seamlesslywith the logging of your own application or allows logging to be enabled and configured independently fromthe application. The logging mechanism can be instrumental in investigating and diagnosing issues. It alsoprovides valuable insight into the type and number of operations requested by the application from the driverand requested by the driver from the remote data source. This information can help you tune and optimize yourapplication.

32 A string that identifies the file as a statement pool export file.33 The version of the export file.34 The first statement pool entry. Each statement pool entry lists the SQL text, statement type, result set type, result set concurrency type, and

generated keys information.35 The next statement pool entry.

19Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Using Java logging

Page 20: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Logging componentsDrivers that support Java logging use the Java Logging API to configure the loggers (individual loggingcomponents) used by the drivers. 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 driverscan 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 drivers 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

• CONFIG

• FINE

• FINER

• FINEST

Note: Log messages logged by the drivers 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 drivers expose loggers for the following functional areas:

• JDBC API

• SQL Engine

• Web service adapter

JDBC API logger

Namecom.ddtek.jdbc.cloud.level

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.020

Chapter 2: Troubleshooting

Page 21: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

Namecom.ddtek.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 fetching the data, if needed. These are internaloperations that do not necessarily directly correlate with Web service calls made to the remote data source.

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

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

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

Web service adapter logger

Namecom.ddtek.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 Salesforce-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.

21Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Using Java logging

Page 22: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Configuring loggingYou can configure logging using a standard Java properties file in either of the following ways:

• Using the properties file that is shipped with your JVM. See "Using the JVM" for details.

• Using the driver. See "Using the driver" for details.

Using the JVMIf you want to configure logging using the properties file that is shipped with your JVM, use a text editor tomodify the properties file in your JVM. Typically, this file is named logging.properties and is located in theJRE/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 driverIf you want to configure logging using a driver, you can use either of the following approaches:

• Use a single properties file for all connections for a given data source.

• Use a different properties file for each schema map. For example, if you have two maps (such as,C:\data\schemamaps\test1map.config and C:\data\schemamaps\test2map.config), you canload one properties file for the test1map.config schema map and load another properties file for thetest2map.config schema map.

Note: See "SchemaMap" in the user's guide for your driver for information on SchemaMap default values andhow to specify valid values for SchemaMap.

By default, the driver looks for the file named ddlogging.properties in the current working directory toload for all connections for a data source.

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 22, it looks for a properties file nameduser_name.logging.properties in the directory containing the embedded database for the connection,where user_name is your user ID used to connect to the instance.

3. If the driver cannot find the file in Step 2 on page 22, 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 22 , it abandons its attempt to load a properties file.

Progress DataDirect for JDBC Drivers: Reference: Version 6.022

Chapter 2: Troubleshooting

Page 23: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

For details about using the LogConfigFile connection property, refer to "LogConfigFile" topic in the user's guidefor your driver.

A sample properties file is installed in the install_dir/testforjdbc andinstalldir/Examples/driver_nameSamples directories, where:

installdir

is your product installation directory.

The file is named ddlogging.properties.You can copy this file from either location to the current workingdirectory of your application or embedded database directory, and modify it using a text editor for your needs.

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.

23Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Contacting Technical Support

Page 24: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Progress DataDirect for JDBC Drivers: Reference: Version 6.024

Chapter 2: Troubleshooting

Page 25: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

3Failover

The following 6.0 drivers support failover:

• Oracle

• SQL Server

Note: Salesforce does implement failover in the typical way, using an alternate server. Instead, continuousconnection is supported through the ConnectionRetryCount and ConnectionRetryDelay connection properties.

To ensure continuous, uninterrupted access to data, the drivers provide the following levels of failover protection,listed from basic to more comprehensive:

• Connection failover provides failover protection for new connections only. The driver fails over newconnections to an alternate, or backup, database server if the primary database server is unavailable, forexample, because of a hardware failure or traffic overload. If a connection to the database is lost, or dropped,the driver does not fail over the connection. This failover method is the default.

• Extended connection failover provides failover protection for new connections and lost database connections.If a connection to the database is lost, the driver fails over the connection to an alternate server, preservingthe state of the connection at the time it was lost, but not any work in progress.

• Select Connection failover provides failover protection for new connections and lost database connections.In addition, it provides protection for Select statements that have work in progress. If a connection to thedatabase is lost, the driver fails over the connection to an alternate server, preserving the state of theconnection at the time it was lost and preserving the state of any work being performed by Select statements.

The method you choose depends on how failure-tolerant your application is. For example, if a communicationfailure occurs while processing, can your application handle the recovery of transactions and restart them?

25Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 26: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

When using either extended connection failover mode or select connection failover mode, your applicationneeds the ability to recover and restart transactions. The advantage of select mode is that it preserves thestate of any work that was being performed by the Select statement at the time of connection loss. If yourapplication had been iterating through results at the time of the failure, when the connection is reestablished,the driver can reposition on the same row where it stopped so that the application does not have to undo allof its previous result processing. For example, if your application was paging through a list of items on a Webpage when a failover occurred, the next page operation would be seamless instead of starting from the beginning.Performance, however, is a factor in selecting a failover mode. Select mode incurs additional overhead whentracking which rows the application has already processed.

You can specify which failover method you want to use by setting the FailoverMode connection property.Regardless of the failover method you choose, you must configure one or multiple alternate servers using theAlternateServers connection property.

Note: For step-by-step instructions on configuring failover for your database management system, refer tothe "Configuring failover" topic in the user's guide for your driver.

For details, see the following topics:

• Connection failover

• Extended connection failover

• Select connection failover

• Guidelines for primary and alternate servers

• Using client load balancing

• Using connection retry

Connection failoverConnection failover allows an application to connect to an alternate, or backup, database server if the primarydatabase server is unavailable, for example, because of a hardware failure or traffic overload. Connectionfailover provides failover protection for new connections only and does not provide protection for lost connectionsto the database, nor does it preserve states for transactions or queries.

You can customize the drivers for connection failover by configuring a list of alternate database servers thatare tried if the primary server is not accepting connections. Connection attempts continue until a connectionis successfully established or until all the alternate database servers have been tried the specified number oftimes.

For example, suppose you have the environment with multiple database servers as shown in the followingfigure. Database Server A is designated as the primary database server, Database Server B is the first alternateserver, and Database Server C is the second alternate server.

Progress DataDirect for JDBC Drivers: Reference: Version 6.026

Chapter 3: Failover

Page 27: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

First, the application attempts to connect to the primary database server, Database Server A (1). If connectionfailover is enabled and Database Server A fails to accept the connection, the application attempts to connectto Database Server B (2). If that connection attempt also fails, the application attempts to connect to DatabaseServer C (3).

In this scenario, it is probable that at least one connection attempt would succeed, but if no connection attemptsucceeds, the driver can retry each alternate database server (primary and alternate) for a specified numberof attempts. You can specify the number of attempts that are made through the connection retry feature. Youcan also specify the number of seconds of delay, if any, between attempts through the connection delay feature.See "Using connection retry" for more information about connection retry.

A driver fails over to the next alternate database server only if a successful connection cannot be establishedwith the current alternate server. If the driver successfully establishes communication with a database serverand the connection request is rejected by the database server because, for example, the login information isinvalid, then the driver generates an exception.

See alsoUsing connection retry on page 30

Extended connection failoverExtended connection failover provides failover protection for the following types of connections:

• New connections (in the same way as described in "Connection failover")

• Lost connections

When a connection to the database is lost, the driver fails over the connection to an alternate server, restoringthe same state of the connection at the time it was lost. For example, when reestablishing a lost connectionon the alternate database server, the driver performs the following actions:

• Restores the connection using the same connection properties specified by the lost connection

• Reallocates statement handles and attributes

27Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Extended connection failover

Page 28: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

• Logs in the user to the database with the same user credentials

• Restores any prepared statements associated with the connection

• Restores manual commit mode if the connection was in manual commit mode at the time of the failover

The driver does not preserve work in progress. For example, if the database server experienced a hardwarefailure while processing a query, partial rows processed by the database and returned to the client would belost.

You can choose how you want the driver to behave if exceptions occur during failover by setting theFailoverGranularity connection property. If an exception occurs while the driver is reestablishing a lost connection,the driver can react in either of the following ways:

• It can fail the entire failover process. The driver stops trying to connect to an alternative server and returnsan exception indicating that the connection was lost.

• It can proceed with the failover process as far as it is able. For example, suppose an exception occurredwhile reestablishing the connection because the driver was unable to log the user into the database. In thiscase, you may want the driver to notify your application of the exception and proceed with the failoverprocess.

During the failover process, your application may experience a short pause while the driver establishes a newconnection or reestablishes a lost connection on an alternate server. If your application is time-sensitive (areal-time customer order application, for example) and cannot absorb this wait, you can set theFailoverPreconnect property to true. Setting the FailoverPreconnect property to true instructs the driver toestablish connections to the primary server and an alternate server at the same time. Your application usesthe first connection that is successfully established. As a bonus, if this connection to the database is lost at alater time, the driver saves time in reestablishing the connection on the server it fails over to because it canuse the spare connection in its failover process.

See alsoConnection failover on page 26

Select connection failoverSelect connection failover provides failover protection for the following types of connections:

• New connections (in the same way as described in "Connection failover")

• Lost connections (in the same way as described in "Extended connection failover")

In addition, the driver can recover work in progress because it keeps track of the last Select statement theapplication executed on each Statement handle, including how many rows were fetched to the client. Forexample, if the database had only processed 500 of 1,000 rows requested by a Select statement when theconnection was lost, the driver would reestablish the connection to an alternate server, re-execute the Selectstatement, and position the cursor on the next row so that the driver can continue fetching the balance of rowsas if nothing had happened.

Performance, however, is a factor when considering whether to use Select mode. Select mode incurs additionaloverhead when tracking what rows the application has already processed.

Note: The driver only recovers work requested by Select statements. You must explicitly restart the followingtypes of statements after a failover occurs:

Progress DataDirect for JDBC Drivers: Reference: Version 6.028

Chapter 3: Failover

Page 29: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

• Insert, Update, or Delete statements

• Statements that modify the connection state, for example, SET or ALTER SESSION statements

• Objects stored in a temporary tablespace or global temporary table

• Partially executed stored procedures and batch statements

When in manual transaction mode, no statements are rerun if any of the operations in the transaction wereInsert, Update, or Delete. This is true even if the statement in process at the time of failover was a Selectstatement.

By default, the driver verifies that the rows that are restored match the rows that were originally fetched and,if they do not match, generates an exception warning your application that the Select statement must bereissued. By setting the FailoverGranularity connection property, you can configure the driver to fail the entirefailover process if the rows do not match.

See alsoConnection failover on page 26Extended connection failover on page 27

Guidelines for primary and alternate serversMany databases provide advanced database replication technologies such as Oracle Real Application Clusters(RAC) and Microsoft Cluster Server (MSCS). The failover functionality provided by the drivers does not requireany of these technologies, but can work with them to provide comprehensive failover protection. Use thefollowing guidelines for primary and alternate servers to ensure that failover works correctly in your environment:

• Alternate servers should mirror data on the primary server or be part of a configuration where multipledatabase nodes share the same physical data.

• If using failover with an Oracle RAC, the primary server must be a primary node and any alternate servermust be a secondary node.

• If using failover with MSCS, which determines the alternate server for failover instead of the driver, anyalternate server specified must be the same as the primary server. For example:

jdbc:datadirect:sqlserver://server1:1433;DatabaseName=TEST;User=test;Password=secret;AlternateServers=(server1:1433;DatabaseName=TEST)

Using client load balancingClient load balancing helps distribute new connections in your environment so that no one server is overwhelmedwith connection requests. When client load balancing is enabled, the order in which primary and alternatedatabase servers are tried is random. For example, suppose that client load balancing is enabled as shown inthe following figure.

29Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Guidelines for primary and alternate servers

Page 30: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

First, Database Server B is tried (1). Then, Database Server C may be tried (2), followed by a connectionattempt to Database Server A (3). In contrast, if client load balancing were not enabled in this scenario, eachdatabase server would be tried in sequential order, primary server first, then each alternate server based onits entry order in the alternate servers list.

Client load balancing is controlled by the LoadBalancing connection property. For details on configuring clientload balancing, see the individual driver chapter in this book.

Using connection retryConnection retry defines the number of times the driver attempts to connect to the primary server and, ifconfigured, alternate database servers after the initial unsuccessful connection attempt. It can be used withconnection failover, extended connection failover, and select failover. Connection retry can be an importantstrategy for system recovery. For example, suppose you have a power failure in which both the client and theserver fails. When the power is restored and all computers are restarted, the client may be ready to attempt aconnection before the server has completed its startup routines. If connection retry is enabled, the clientapplication can continue to retry the connection until a connection is successfully accepted by the server.

Connection retry can be used in environments that have only one server or can be used as a complementaryfeature with failover in environments with multiple servers.

Using the ConnectionRetryCount and ConnectionRetryDelay properties, you can specify the number of timesthe driver attempts to connect and the time in seconds between connection attempts. For details on configuringconnection retry, see the individual driver chapter in this book.

Progress DataDirect for JDBC Drivers: Reference: Version 6.030

Chapter 3: Failover

Page 31: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

4Client information

The following 6.0 drivers support storing and retrieving client information:

• Apache Hive

• Apache Spark SQL

• Oracle

• SQL Server

Many databases allow applications to store client information associated with a connection. For example, thefollowing types of information can be useful for database administration and monitoring purposes:

• Name of the application currently using the connection.

• User ID for whom the application using the connection is performing work. The user ID may be differentthan the user ID that was used to establish the connection.

• Host name of the client on which the application using the connection is running.

• Product name and version of the driver on the client.

• Additional information that may be used for accounting or troubleshooting purposes, such as an accountingID.

Note: Oracle allows you to store additional client information including the action associated with the currentmodule, identifying information about the client, and the name of the current module.

For details, see the following topics:

• How databases store client information

31Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 32: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

• Returning client Information

• Returning metadata about client information locations

How databases store client informationTypically, databases that support storing client information do so by providing a register, a variable, or a columnin a system table in which the information is stored. If an application attempts to store information and thedatabase does not provide a mechanism for storing that information, the driver caches the information locally.Similarly, if an application returns client information and the database does not provide a mechanism for storingthat information, the driver returns the locally cached value.

For example, let’s assume that the following code returns a pooled connection to an Oracle database and setsa client application name for that connection. In this example, the application sets the application nameSALES157 using the driver property ApplicationName.

// Get Database ConnectionConnection con = DriverManager.getConnection("jdbc:datadirect:oracle://server3:1521;SID=ORCL;ApplicationName=SALES157","TEST","secret");...

The application name SALES157 is stored by the DB2 database in the CURRENT CLIENT_APPLNAMEregister, the location that DB2 reserves for this information. When the connection to the database is closed,the connection is returned to the connection pool as usual and the client information on the connection is resetto an empty string.

The application name SALES157 is stored locally by the database. When the connection to the Oracle databaseis closed, the client information on the connection is reset to an empty string. If we used this same scenarioagainst a MySQL database, which does not support storing client information, the driver would store theapplication name locally.

Storing client informationYour application can store client information associated with a connection using any of the following methods:

• Using the driver connection properties listed in the following table. This table lists the connection propertiesyour application can use to store client information and where that client information is stored for eachdatabase. For information about specifying connection properties using a URL or a JDBC data source, referto the user's guide for your driver

• Using the following JDBC methods:

• Connection.setClientInfo(properties)

• Connection.setClientInfo(property_name, value)

Refer to "JDBC Support" in the for more information about these JDBC methods.

• Using the JDBC extension methods provided in the com.ddtek.jdbc.extensions package. See "JDBCExtensions" for more information about the com.ddtek.jdbc.extensions package.

Progress DataDirect for JDBC Drivers: Reference: Version 6.032

Chapter 4: Client information

Page 33: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Table 1: Database Locations for Storing Client Information

LocationDatabaseDescriptionProperty

Local cacheAmazonRedshift

Additional information thatmay be used for accountingor troubleshootingpurposes, such as anaccounting ID

AccountingInfo

Local cacheApache Hive

Local cacheApache SparkSQL

CLIENT_INFO column in the V$SESSION tableOracle

N/AMicrosoftWindows AzureSQL Database

Local cacheMicrosoftSQL Server

N/AAmazonRedshift

The current action (Select,Insert, Update, or Delete,for example) within thecurrent module

Action

N/AApache Hive

N/AApache SparkSQL

CLIENT_INFO column in the V$SESSION tableOracle

N/AMicrosoftWindows AzureSQL Database

N/AMicrosoftSQL Server

33Progress DataDirect for JDBC Drivers: Reference: Version 6.0

How databases store client information

Page 34: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

LocationDatabaseDescriptionProperty

Local cacheAmazonRedshift

Name of the applicationcurrently using theconnection

ApplicationName

Local cacheApache Hive

Local cacheApache SparkSQL

dbms_session value. In addition, it is also storedin the PROGRAM column in the V$SESSIONtable.

Oracle

N/AMicrosoftWindows AzureSQL Database

For Microsoft SQL Server 2000 and higher,program_name column in the sysprocesses table.For Microsoft SQL Server 7, local cache.

MicrosoftSQL Server

Local CacheAmazonRedshift

Host name of the client onwhich the application usingthe connection is running

ClientHostName

Local cacheApache Hive

Local cacheApache SparkSQL

MACHINE column in the V$SESSION tableOracle

N/AMicrosoftWindows AzureSQL Database

For Microsoft SQL Server 2000 and higher,hostname column in the sysprocesses table. ForMicrosoft SQL Server 7, local cache.

MicrosoftSQL Server

Progress DataDirect for JDBC Drivers: Reference: Version 6.034

Chapter 4: Client information

Page 35: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

LocationDatabaseDescriptionProperty

N/AAmazonRedshift

Additional information aboutthe client to be stored in thedatabase

ClientID

N/AApache Hive

N/AApache SparkSQL

For Oracle9i R1 (9.0.1) and higher, theCLIENT_IDENTIFIER column in the V$SESSIONtable

Oracle

N/AMicrosoftWindows AzureSQL Database

N/AMicrosoftSQL Server

Local cacheAmazonRedshift

User ID for whom theapplication using theconnection is performingwork

ClientUser

Local cacheApache Hive

Local cacheApache SparkSQL

OSUSER column in the V$SESSION tableOracle

N/AMicrosoftWindows AzureSQL Database

Local cacheMicrosoftSQL Server

Local cacheAmazonRedshift

Driver name and version onthe client

ProgramID

Local cacheApache Hive

Local cacheApache SparkSQL

PROCESS column in the V$SESSION tableOracle

N/AMicrosoftWindows AzureSQL Database

For Microsoft SQL Server 2000 and higher, thehostprocess column in the sysprocesses table.

MicrosoftSQL Server

35Progress DataDirect for JDBC Drivers: Reference: Version 6.0

How databases store client information

Page 36: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

LocationDatabaseDescriptionProperty

N/AAmazonRedshift

The module name to bestored in the database

Module

N/AApache Hive

N/AApache SparkSQL

The MODULE column in the V$SESSION tableOracle

N/AMicrosoftWindows AzureSQL Database

N/AMicrosoftSQL Server

See alsoJDBC support on page 39JDBC extensions on page 97

Returning client InformationYour application can return client information in the following ways:

• Using the following JDBC methods:

• Connection.getClientInfo()

• Connection.getClientInfo(property_name)

• DatabaseMetaData.getClientInfoProperties()

See "JDBC support" in the for more information about these JDBC methods.

• Using the JDBC extension methods provided in the com.ddtek.jdbc.extensions package. See "JDBCextensions" for more information about the com.ddtek.jdbc.extensions package.

See alsoJDBC support on page 39JDBC extensions on page 97

Progress DataDirect for JDBC Drivers: Reference: Version 6.036

Chapter 4: Client information

Page 37: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Returningmetadata about client information locationsYou may want to return metadata about the register, variable, or column in which the database stores clientinformation. For example, you may want to determine the maximum length allowed for a client informationvalue before you store that information. If your application attempts to set a client information value that exceedsthe maximum length allowed by the database, that value is truncated and the driver generates a warning.Determining the maximum length of the value beforehand can avoid this situation.

To return metadata about client information, call the DatabaseMetaData.getClientInfoProperties() method:// Get Database ConnectionConnection con = DriverManager.getConnection(

"jdbc:datadirect:oracle://server3:1521;SID=ORCL", "test", "secret");DatabaseMetaData metaData = con.getMetaData();ResultSet rs = metaData.getClientInfoProperties();...

The driver returns a result set that provides the following information for each client information propertysupported by the database:

• Property name

• Maximum length of the property value

• Default property value

• Property description

37Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Returning metadata about client information locations

Page 38: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Progress DataDirect for JDBC Drivers: Reference: Version 6.038

Chapter 4: Client information

Page 39: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

5JDBC 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.

For details, see the following topics:

• Array

• Blob

• CallableStatement

• Clob

• Connection

• ConnectionEventListener

• ConnectionPoolDataSource

• DatabaseMetaData

• DataSource

• Driver

• ParameterMetaData

• PooledConnection

• PreparedStatement

• Ref

39Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 40: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

• 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)

Progress DataDirect for JDBC Drivers: Reference: Version 6.040

Chapter 5: JDBC support

Page 41: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

BlobCommentsSupportedVersion

IntroducedBlob Methods

Yes4.0void free()

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

Yes2.0 CoreInputStream getBinaryStream()

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

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

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

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)

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

Yes3.0OutputStream setBinaryStream(long)

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

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

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

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

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

Yes3.0void truncate(long)

41Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Blob

Page 42: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CallableStatementCommentsSupportedVersion

IntroducedCallableStatement Methods

The Autonomous REST Connector and thedrivers for Jira, 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)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes4.0Reader getCharacterStream(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0Reader getCharacterStream(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes2.0 CoreBigDecimal getBigDecimal(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0BigDecimal getBigDecimal(int, int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0BigDecimal getBigDecimal(String)

Progress DataDirect for JDBC Drivers: Reference: Version 6.042

Chapter 5: JDBC support

Page 43: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

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

Yes2.0 CoreBlob getBlob(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0Blob getBlob(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0boolean getBoolean(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0boolean getBoolean(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0byte getByte(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0byte getByte(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0byte [] getBytes(int)

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

Yes3.0byte [] getBytes(String)

43Progress DataDirect for JDBC Drivers: Reference: Version 6.0

CallableStatement

Page 44: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

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

Yes2.0 CoreClob getClob(int)

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

All other drivers throw "unsupportedmethod" exception.

Yes3.0Clob getClob(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0Date getDate(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes2.0 CoreDate getDate(int, Calendar)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0Date getDate(String)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0Date getDate(String, Calendar)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0double getDouble(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0double getDouble(String)

Progress DataDirect for JDBC Drivers: Reference: Version 6.044

Chapter 5: JDBC support

Page 45: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0float getFloat(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0float getFloat(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0int getInt(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0int getInt(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0long getLong(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0long getLong(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0Reader getNCharacterStream(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0Reader getNCharacterStream(String)

45Progress DataDirect for JDBC Drivers: Reference: Version 6.0

CallableStatement

Page 46: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0NClob getNClob(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0NClob getNClob(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw "unsupported method"exception.

Yes4.0String getNString(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0String getNString(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0Object getObject(int)

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0Object getObject(String)

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

All other drivers throw "unsupportedmethod" exception.

Yes3.0Object getObject(String, Map)

Progress DataDirect for JDBC Drivers: Reference: Version 6.046

Chapter 5: JDBC support

Page 47: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

All other drivers throw "unsupportedmethod" exception.

No2.0 CoreRef getRef(int)

The drivers throw "unsupported method"exception.

No3.0Ref getRef(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0short getShort(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0short getShort(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0SQLXML getSQLXML(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0SQLXML getSQLXML(String)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0String getString(int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0String getString(String)

47Progress DataDirect for JDBC Drivers: Reference: Version 6.0

CallableStatement

Page 48: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0Time getTime(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes2.0 CoreTime getTime(int, Calendar)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0Time getTime(String)

Supported for SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0Time getTime(String, Calendar)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0Timestamp getTimestamp(int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes2.0 CoreTimestamp getTimestamp(int, Calendar)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0Timestamp getTimestamp(String)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0Timestamp getTimestamp(String, Calendar)

The drivers throw "unsupported method"exception.

No3.0URL getURL(int)

Progress DataDirect for JDBC Drivers: Reference: Version 6.048

Chapter 5: JDBC support

Page 49: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

The drivers throw "unsupported method"exception.

No3.0URL getURL(String)

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

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

Yes1.0void registerOutParameter(int, int)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

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

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

The Oracle driver supports the Stringargument.

For all other drivers, the String argument isignored.

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

Supported for the SQL Server driver only.

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void registerOutParameter(String, int)

49Progress DataDirect for JDBC Drivers: Reference: Version 6.0

CallableStatement

Page 50: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

Supported for the SQL Server driver only.

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "invalid parameterbindings" exception when your applicationcalls output parameters.

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

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

Supported for the Oracle driver only.

All other drivers throw "unsupportedmethod" exception.

Yes2.0 Corevoid setArray(int, Array)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes4.0void setAsciiStream(String, InputStream)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setBigDecimal(String, BigDecimal)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes4.0void setBinaryStream(String, InputStream)

Progress DataDirect for JDBC Drivers: Reference: Version 6.050

Chapter 5: JDBC support

Page 51: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes4.0void setBlob(String, Blob)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes4.0void setBlob(String, InputStream)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setBoolean(String, boolean)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setByte(String, byte)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes4.0void setClob(String, Clob)

51Progress DataDirect for JDBC Drivers: Reference: Version 6.0

CallableStatement

Page 52: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes4.0void setClob(String, Reader)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setDate(String, Date)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setDouble(String, double)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setFloat(String, float)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setInt(String, int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setLong(String, long)

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

Yes4.0void setNClob(String, NClob)

Yes4.0void setNClob(String, Reader)

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

Yes4.0void setNString(String, String)

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.052

Chapter 5: JDBC support

Page 53: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setNull(String, int)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setObject(String, Object)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setShort(String, short)

The Autonomous REST Connector and thedrivers for Jira, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce throw an "unsupported method"exception.

Yes4.0void setSQLXML(String, SQLXML)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setString(String, String)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setTime(String, Time)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

53Progress DataDirect for JDBC Drivers: Reference: Version 6.0

CallableStatement

Page 54: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

CallableStatement Methods

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

Yes3.0void setTimestamp(String, Timestamp)

Supported for the SQL Server driver only.

All other drivers throw "unsupportedmethod" exception.

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

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

The drivers throw "unsupported method"exception.

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()

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

Yes2.0 CoreReader getCharacterStream()

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

Yes4.0Reader getCharacterStream(long, long)

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

Yes2.0 CoreString getSubString(long, int)

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

Yes2.0 Corelong length()

Progress DataDirect for JDBC Drivers: Reference: Version 6.054

Chapter 5: JDBC support

Page 55: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Clob Methods

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

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

Yes2.0 Corelong position(Clob, long)

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

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

Yes2.0 Corelong position(String, long)

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

Yes3.0 CoreOutputStream setAsciiStream(long)

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

Yes3.0 CoreWriter setCharacterStream(long)

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

Yes3.0 Coreint setString(long, String)

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

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

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

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()

55Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection

Page 56: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Connection Methods

Yes4.0Blob createBlob()

Yes4.0Clob createClob()

Yes4.0NClob createNClob()

Yes4.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 Autonomous REST Connector andthe drivers for Jira, 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)

Supported for the Oracle driver only.

All other drivers throw "unsupported method"exception.

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

Yes1.0boolean getAutoCommit()

Progress DataDirect for JDBC Drivers: Reference: Version 6.056

Chapter 5: JDBC support

Page 57: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Connection Methods

The Autonomous REST Connector and thedrivers 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, Jira,Impala, MongoDB, Oracle, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,PostgreSQL, and Salesforce.

Yes1.0String getCatalog()

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcedo not support storing or retrieving clientinformation.

Yes4.0String getClientInfo()

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcedo not support storing or retrieving clientinformation.

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()

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

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

Yes1.0String nativeSQL(String)

Yes1.0CallableStatement prepareCall(String)

57Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection

Page 58: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Connection Methods

For the Autonomous REST Connector andthe drivers for Apache Cassandra, DB2, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and SalesforceResultSet.TYPE_SCROLL_ SENSITIVE isdowngraded toTYPE_SCROLL_INSENSITIVE.

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

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 Autonomous REST Connector andthe drivers for Apache Cassandra, Jira,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.

All other drivers throw "unsupported method"exception.

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

Supported for the SQL Server driver only.

All other drivers throw "unsupported method"exception.

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.058

Chapter 5: JDBC support

Page 59: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

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.

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcethrow an "unsupported method" exception.

Yes3.0void releaseSavepoint(Savepoint)

Yes1.0void rollback()

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

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcethrow an "unsupported method" exception.

Yes3.0void rollback(Savepoint)

The Autonomous REST Connector and thedrivers for Apache Cassandra, Apache Hive,Apache Spark SQL, Impala, Jira, MongoDB,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, and Salesforce throw"transactions not supported" exception if setto false.

Yes1.0void setAutoCommit(boolean)

The Autonomous REST Connector and thedrivers 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, Jira,MongoDB, Oracle, Oracle Eloqua, OracleSales Cloud, Oracle Service Cloud,PostgreSQL, and Salesforce.

Yes1.0void setCatalog(String)

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcedo not support storing or retrieving clientinformation.

Yes4.0String setClientInfo(Properties)

59Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection

Page 60: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Connection Methods

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcedo not support storing or retrieving clientinformation.

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)

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.

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcethrow an "unsupported method" exception.

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.

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcethrow an "unsupported method" exception.

Yes3.0Savepoint setSavepoint(String)

The Autonomous REST Connector and thedrivers for Apache Cassandra, Apache Hive,Apache Spark SQL, Impala, Jira, MongoDB,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, and Salesforce ignore anyspecified transaction isolation level.

Yes1.0void setTransactionIsolation(int)

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

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.060

Chapter 5: JDBC support

Page 61: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

ConnectionEventListenerCommentsSupportedVersion

IntroducedConnectionEventListener Methods

Yes3.0void connectionClosed(event)

Yes3.0void connectionErrorOccurred(event)

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()

61Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ConnectionEventListener

Page 62: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

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)

Yes1.0ResultSet getCatalogs()

Yes1.0String getCatalogSeparator()

Yes1.0String getCatalogTerm()

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforcedo not support storing or retrieving clientinformation.

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 Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,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()

Progress DataDirect for JDBC Drivers: Reference: Version 6.062

Chapter 5: JDBC support

Page 63: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

The Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,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()

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()

63Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DatabaseMetaData

Page 64: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

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 Autonomous REST Connector andthe drivers for Jira, 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)

Progress DataDirect for JDBC Drivers: Reference: Version 6.064

Chapter 5: JDBC support

Page 65: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

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()

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()

65Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DatabaseMetaData

Page 66: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

Yes1.0String getUserName()

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

Yes2.0 Coreboolean insertsAreDetected(int)

Yes1.0boolean isCatalogAtStart()

Yes1.0boolean isReadOnly()

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

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()

Progress DataDirect for JDBC Drivers: Reference: Version 6.066

Chapter 5: JDBC support

Page 67: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

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()

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()

67Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DatabaseMetaData

Page 68: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

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()

Progress DataDirect for JDBC Drivers: Reference: Version 6.068

Chapter 5: JDBC support

Page 69: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

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()

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()

69Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DatabaseMetaData

Page 70: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

DatabaseMetaData Methods

Yes1.0booleansupportsTransactionIsolationLevel(int)

Yes1.0boolean supportsTransactions()

Yes1.0boolean supportsUnion()

Yes1.0boolean supportsUnionAll()

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

Yes2.0 Coreboolean updatesAreDetected(int)

Yes1.0boolean usesLocalFilePerTable()

Yes1.0boolean usesLocalFiles()

DataSourceThe DataSource interface implements the javax.naming.Referenceable and java.io.Serializable interfaces.

CommentsSupportedVersionIntroduced

DataSource Methods

Yes2.0 OptionalConnection getConnection()

Yes2.0 OptionalConnection getConnection(String, String)

Yes2.0 Optionalint getLoginTimeout()

Yes2.0 OptionalPrintWriter getLogWriter()

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

Yes2.0 Optionalvoid setLoginTimeout(int)

Enables DataDirect Spy, which traces JDBCinformation into the specified PrintWriter.

Yes2.0 Optionalvoid setLogWriter(PrintWriter)

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.070

Chapter 5: JDBC support

Page 71: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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)

Yes3.0int getParameterCount()

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.0int getParameterMode(int)

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.0int getParameterType(int)

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 getParameterTypeName(int)

71Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Driver

Page 72: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ParameterMetaData 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.0int getPrecision(int)

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.0int getScale(int)

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.0int isNullable(int)

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.0boolean isSigned(int)

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

Yes1.0boolean jdbcCompliant()

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

PooledConnectionCommentsSupportedVersion

IntroducedPooledConnection Methods

Yes2.0 Optionalvoid addConnectionEventListener(listener)

Yes4.0void addStatementEventListener(listener)

Yes2.0 Optionalvoid close()

Progress DataDirect for JDBC Drivers: Reference: Version 6.072

Chapter 5: JDBC support

Page 73: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

PooledConnection Methods

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()

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

Supported for the Oracle driver only.

All other drivers throw an "unsupportedmethod" exception.

Yes2.0 Corevoid setArray(int, Array)

Yes4.0void setAsciiStream(int, InputStream)

Yes1.0void setAsciiStream(int, InputStream, int)

73Progress DataDirect for JDBC Drivers: Reference: Version 6.0

PreparedStatement

Page 74: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

PreparedStatement Methods

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)

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.

Yes1.0void setBinaryStream(int, InputStream, int)

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, long)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes2.0 Corevoid setBlob(int, Blob)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes4.0void setBlob(int, InputStream)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

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

Yes1.0void setBoolean(int, boolean)

Yes1.0void setByte(int, byte)

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.

Yes1.0void setBytes(int, byte [])

Progress DataDirect for JDBC Drivers: Reference: Version 6.074

Chapter 5: JDBC support

Page 75: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

PreparedStatement Methods

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)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes4.0void setClob(int, Reader)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

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)

For the Autonomous REST Connector andthe drivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, N methods are identical to theirnon-N counterparts.

Yes4.0void setNCharacterStream(int, Reader)

For the Autonomous REST Connector andthe drivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, N methods are identical to theirnon-N counterparts.

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

For the Autonomous REST Connector andthe drivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, N methods are identical to theirnon-N counterparts.

Yes4.0void setNClob(int, NClob)

75Progress DataDirect for JDBC Drivers: Reference: Version 6.0

PreparedStatement

Page 76: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

PreparedStatement Methods

For the Autonomous REST Connector andthe drivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, N methods are identical to theirnon-N counterparts.

Yes4.0void setNClob(int, Reader)

For the Autonomous REST Connector andthe drivers for Apache Cassandra, Jira,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, N methods are identical to theirnon-N counterparts.

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)

Progress DataDirect for JDBC Drivers: Reference: Version 6.076

Chapter 5: JDBC support

Page 77: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

PreparedStatement Methods

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 Autonomous REST Connector and thedrivers for Jira, 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)

All drivers throw "unsupported method"exception.

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)

77Progress DataDirect for JDBC Drivers: Reference: Version 6.0

PreparedStatement

Page 78: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

PreparedStatement Methods

This method was deprecated in JDBC 2.0.All drivers throw "unsupported method"exception.

No1.0void setUnicodeStream(int, InputStream,int)

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

All drivers throw "unsupported method"exception.

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 clearWarnings()

Yes1.0void close()

Yes2.0 Corevoid deleteRow()

Yes1.0int findColumn(String)

Yes2.0 Coreboolean first()

Yes2.0 CoreArray getArray(int)

Yes2.0 CoreArray getArray(String)

Progress DataDirect for JDBC Drivers: Reference: Version 6.078

Chapter 5: JDBC support

Page 79: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

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)

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(String)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes2.0 CoreBlob getBlob(int)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes2.0 CoreBlob getBlob(String)

Yes1.0boolean getBoolean(int)

Yes1.0boolean getBoolean(String)

Yes1.0byte getByte(int)

Yes1.0byte getByte(String)

79Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ResultSet

Page 80: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ResultSet Methods

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.0byte [] getBytes(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.0byte [] getBytes(String)

Yes2.0 CoreReader getCharacterStream(int)

Yes2.0 CoreReader getCharacterStream(String)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes2.0 CoreClob getClob(int)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes2.0 CoreClob getClob(String)

Yes2.0 Coreint getConcurrency()

All drivers throw "unsupported method"exception.

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)

Progress DataDirect for JDBC Drivers: Reference: Version 6.080

Chapter 5: JDBC support

Page 81: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

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)

All drivers throw "unsupported method"exception.

No2.0 CoreRef getRef(int)

All drivers throw "unsupported method"exception.

No2.0 CoreRef getRef(String)

Yes2.0 Coreint getRow()

Yes1.0short getShort(int)

Yes1.0short getShort(String)

81Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ResultSet

Page 82: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

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()

This method was deprecated in JDBC 2.0.All drivers throw "unsupported method"exception.

No1.0InputStream getUnicodeStream(int)

This method was deprecated in JDBC 2.0.All drivers throw "unsupported method"exception.

No1.0InputStream getUnicodeStream(String)

All drivers throw "unsupported method"exception.

No3.0URL getURL(int)

All drivers throw "unsupported method"exception.

No3.0URL getURL(String)

Yes1.0SQLWarning getWarnings()

Yes2.0 Corevoid insertRow()

Yes2.0 Coreboolean isAfterLast()

Yes2.0 Coreboolean isBeforeFirst()

Progress DataDirect for JDBC Drivers: Reference: Version 6.082

Chapter 5: JDBC support

Page 83: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ResultSet Methods

Yes4.0boolean isClosed()

Yes2.0 Coreboolean isFirst()

Yes2.0 Coreboolean isLast()

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

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)

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

All drivers throw "unsupported method"exception.

No3.0void updateArray(int, Array)

All drivers throw "unsupported method"exception.

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)

83Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ResultSet

Page 84: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

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)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes3.0void updateBlob(int, Blob)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes4.0void updateBlob(int, InputStream)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes4.0void updateBlob(int, InputStream, long)

Progress DataDirect for JDBC Drivers: Reference: Version 6.084

Chapter 5: JDBC support

Page 85: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ResultSet Methods

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes3.0void updateBlob(String, Blob)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

Yes4.0void updateBlob(String, InputStream)

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

All other drivers support using with datatypes that map to the JDBCLONGVARBINARY data type.

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)

85Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ResultSet

Page 86: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ResultSet Methods

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes3.0void updateClob(int, Clob)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes4.0void updateClob(int, Reader)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes4.0void updateClob(int, Reader, long)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes3.0void updateClob(String, Clob)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

Yes4.0void updateClob(String, Reader)

Drivers support using with data types thatmap to the JDBC LONGVARBINARY datatype.

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 Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNCharacterStream(int, Reader)

Progress DataDirect for JDBC Drivers: Reference: Version 6.086

Chapter 5: JDBC support

Page 87: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ResultSet Methods

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNCharacterStream(int, Reader,long)

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNCharacterStream(String,Reader)

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

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

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNClob(int, NClob)

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNClob(int, Reader)

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNClob(int, Reader, long)

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNClob(String, NClob)

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNClob(String, Reader)

87Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ResultSet

Page 88: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ResultSet Methods

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

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

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

Yes4.0void updateNString(int, String)

For the Autonomous REST Connector andthe drivers for Jira, MongoDB, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce, N methods areidentical to their non-N counterparts.

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)

All drivers throw "unsupported method"exception.

No3.0void updateRef(int, Ref)

All drivers throw "unsupported method"exception.

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)

Progress DataDirect for JDBC Drivers: Reference: Version 6.088

Chapter 5: JDBC support

Page 89: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ResultSet Methods

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)

89Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ResultSetMetaData

Page 90: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

ResultSetMetaData Methods

Yes1.0boolean isReadOnly(int)

Yes1.0boolean isSearchable(int)

Yes1.0boolean isSigned(int)

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

Yes1.0boolean isWritable(int)

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

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 and

Progress DataDirect for JDBC Drivers: Reference: Version 6.090

Chapter 5: JDBC support

Page 91: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Statement Methods

higher 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 Autonomous REST Connector and thedrivers for Apache Cassandra, Impala,Informix, Jira, MongoDB, ProgessOpenEdge, Oracle Service Cloud, OracleEloqua, Oracle Sales Cloud, and Salesforcethrow an "unsupported method" exception.

The Apache Hive, Apache Spark SQL36,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 clearWarnings()

Yes1.0void close()

All drivers throw "invalid method call"exception for PreparedStatement andCallableStatement.

Yes1.0boolean execute(String)

Yes3.0boolean execute(String, int)

Supported for the Oracle and SQL Serverdrivers.

All other drivers throw "unsupported method"exception.

Yes3.0boolean execute(String, int [])

Supported for the Oracle and SQL Serverdrivers.

All other drivers throw "unsupported method"exception.

Yes3.0boolean execute(String, String [])

Yes2.0 Coreint [] executeBatch()

All drivers throw "invalid method call"exception for PreparedStatement andCallableStatement.

Yes1.0ResultSet executeQuery(String)

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

91Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Statement

Page 92: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Statement Methods

All drivers throw "invalid method call"exception for PreparedStatement andCallableStatement.

Yes1.0int executeUpdate(String)

Yes3.0int executeUpdate(String, int)

Supported for the Oracle and SQL Serverdrivers.

All other drivers throw "unsupported method"exception.

Yes3.0int executeUpdate(String, int [])

Supported for the Oracle and SQL Serverdrivers.

All other drivers throw "unsupported method"exception.

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 Autonomous REST Connector and thedrivers for Apache Cassandra, Jira,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()

Progress DataDirect for JDBC Drivers: Reference: Version 6.092

Chapter 5: JDBC support

Page 93: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Statement Methods

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.

The drivers for Apache Cassandra,Greenplum, Oracle, PostgreSQL,SQL Server, Sybase, and Amazon Redshiftreturn the timeout value, in seconds, set forthe statement.

The Autonomous REST Connector and thedrivers for Jira, 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()

Yes1.0SQLWarning getWarnings()

Yes4.0boolean isClosed()

Yes4.0boolean isPoolable()

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

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)

93Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Statement

Page 94: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

CommentsSupportedVersionIntroduced

Statement Methods

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.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 Autonomous REST Connector and thedrivers for Jira, 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.

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.094

Chapter 5: JDBC support

Page 95: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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,Autonomous REST Connector, DB2 V8.1for z/OS, Greenplum, Impala, Jira, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, PostgreSQL, and Salesforce.

Yes2.0 Optional(all)

XADataSourceCommentsSupportedVersion

IntroducedXADataSource Methods

Supported for all drivers except AmazonRedshift, Apache Hive, Apache Spark SQL,Autonomous REST Connecter, DB2 V8.1for z/OS, Greenplum, Impala, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, PostgreSQL, and Salesforce.

Yes2.0 Optional(all)

95Progress DataDirect for JDBC Drivers: Reference: Version 6.0

StatementEventListener

Page 96: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

XAResourceCommentsSupportedVersion

IntroducedXAResource 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)

Progress DataDirect for JDBC Drivers: Reference: Version 6.096

Chapter 5: JDBC support

Page 97: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

6JDBC extensions

This section describes the JDBC extensions provided by the com.ddtek.jdbc.extensions package. Someextensions apply to select drivers. In some cases, the functionality described may not apply to the driver ordata store you are using. The interfaces in the com.ddtek.jdbc.extensions are:

DescriptionInterface/Class

The methods in this interface are used with certain DataDirect drivers toextend the standard JDBC metadata results returned by theDatabaseMetaData.getColumns() method to include an additional column.See "DatabaseMetadata interface" for a list of drivers that support thesemethods.

DatabaseMetadata

Methods that allow your application to perform bulk load operations. Thesemethods are supported only by drivers that support DataDirect Bulk Load.See "DDBulkLoad interface" for a list of drivers that support these methods.

DDBulkLoad

Methods that allow you to perform the following actions:

• Store and return client information.

• Switch the user associated with a connection to another user to minimizethe number of connections that are required in a connection pool.

• Access the DataDirect Statement Pool Monitor from a connection.

ExtConnection

97Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 98: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionInterface/Class

Methods that allow your application to return client information parameters.ExtDatabaseMetaData

Methods that allow you to determine if DataDirect Spy logging is enabledand turning on and off DataDirect Spy logging if enabled.

ExtLogControl

For details, see the following topics:

• Using JDBC wrapper methods to access JDBC extensions

• DatabaseMetaData interface

• DDBulkLoad interface

• ExtConnection interface

• ExtDatabaseMetaData interface

• ExtLogControl class

Using JDBC wrapper methods to access JDBCextensions

The wrapper methods allow an application to access vendor-specific classes. The following example showshow to access the DataDirect-specific ExtConnection class using the wrapper methods:

ExtStatementPoolMonitor monitor = null;Class<ExtConnection> cls = ExtConnection.class;if (con.isWrapperFor(cls)) {

ExtConnection extCon = con.unwrap(cls);extCon.setClientUser("Joe Smith");monitor = extCon.getStatementPoolMonitor();

}...if(monitor != null) {

long hits = monitor.getHitCount();long misses = monitor.getMissCount();

}...

Progress DataDirect for JDBC Drivers: Reference: Version 6.098

Chapter 6: JDBC extensions

Page 99: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DatabaseMetaData interfaceThe following drivers support the DatabaseMetaData.getColumns() method:

• Autonomous REST Connector

• Jira

• Oracle Eloqua

• Oracle Sales Cloud

• Oracle Service Cloud

• Salesforce

The DatabaseMetaData.getColumns() method extends the standard JDBC metadata results returned toinclude the additional columns described in the following tables.

Table 2: DatabaseMetaData.getColumns() method

DescriptionData TypeColumn

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 Autonomous REST Connector and the drivers for Jira, Oracle Eloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce extend the standard JDBC metadata results returned by theDatabaseMetaData.getTables() method to include the following additional column.

Table 3: DatabaseMetaData.getTables() Method

DescriptionData TypeColumn

The text label for this table. If not present, this field is null.VARCHAR (128)LABEL

99Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DatabaseMetaData interface

Page 100: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DDBulkLoad interfaceThe DDBulkLoad interface allows your application to perform bulk load operations using DataDirect Bulk Load.The following 6.0 drivers support DataDirect Bulk Load:

• Oracle

• Salesforce

• SQL Server

DescriptionDDBulkLoad Methods

Clears all warnings that were generated by this DDBulkLoad object.void clearWarnings()

Releases a DDBulkLoad object’s resources immediately instead ofwaiting for the connection to close.

void close()

Exports all rows from the table into the specified CSV file specified bya file reference. The table is specified using the setTableName()method. If the CSV file does not already exist, the driver creates it whenthe export() method is executed. In addition, the driver creates a bulkload configuration file matching the CSV file. For more information,refer to "Exporting Data to a CSV File" in the user’s guide for yourdriver.

This method also returns the number of rows that were successfullyexported from the table.

long export(File)

Exports all rows from the specified ResultSet into the CSV file specifiedby a file reference. If the CSV file does not already exist, the drivercreates it when the export() method is executed. In addition, the drivercreates a bulk load configuration file matching the CSV file. For moreinformation, refer to "Exporting Data to a CSV File" in the user’s guidefor your driver.

This method also returns the number of rows that were successfullyexported from the ResultSet object.

long export(ResultSet, File)

Exports all rows from the table into the CSV file specified by name.The table is specified using the setTableName() method. If the CSVfile does not already exist, the driver creates it when the export() methodis executed. In addition, the driver creates a bulk load configuration filematching the CSV file. For more information, refer to "Exporting Datato a CSV File" in the user’s guide for your driver.

This method also returns the number of rows that were successfullyexported from the table.

long export(String)

Returns the number of rows that the driver sends at a time when bulkloading data.

long getBatchSize()

Progress DataDirect for JDBC Drivers: Reference: Version 6.0100

Chapter 6: JDBC extensions

Page 101: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionDDBulkLoad Methods

Returns the maximum size (in bytes) of binary data that can be exportedto the CSV file. Once this size is reached, binary data is written to oneor multiple external overflow files. For more information, refer to"External Overflow Files" in the user’s guide .

long getBinaryThreshold()

Returns the maximum size (in bytes) of character data that can beexported to the CSV file. Once this size is reached, character data iswritten to one or multiple external overflow files. for more information,refer to "External Overflow Files" in the user’s guide for your driver.

long getCharacterThreshold()

Returns the code page that the driver uses for the CSV file. For moreinformation, refer to "Character Set Conversions" in the user’s guidefor your driver.

String getCodePage()

Returns the name of the bulk load configuration file. For moreinformation, refer to "Bulk Load Configuration File" in the User’s Guidefor your driver.

String getConfigFile()

Returns the name of the discard file. The discard file contains rows thatwere unable to be loaded as the result of a bulk load operation. Formore information, refer to "Discard File" in the user’s guide for yourdriver.

String getDiscardFile()

Returns the number of errors that can occur before this DDBulkLoadobject ends the bulk load operation.

long getErrorTolerance()

Returns the name of the log file. The log file records information abouteach bulk load operation. For more information, refer to "Logging" inthe user’s guide for your driver.

String getLogFile()

Returns the maximum number of rows from the CSV file or ResultSetobject the driver will load when the load() method is executed.

long getNumRows()

Returns the properties specified for a DDBulkLoad object. Propertiesare specified using the setProperties() method.

Properties getProperties()

Returns the size (in KB) of the buffer that is used to read the CSV file.long getReadBufferSize()

Returns the position (number of the row) in a CSV file or ResultSetobject from which the driver starts loading. The position is specifiedusing the setStartPosition() method.

long getStartPosition()

Returns the name of the table to which the data is loaded into orexported from. For more information.Refer to "Loading Data From aResultSet Object," "Loading Data From a CSV File," and "ExportingData to a CSV File" in the user's guide for your driver.

void getTableName()

Returns the number of seconds the bulk load operation requires tocomplete before it times out. The timeout is specified using thesetTimeout() method.

long getTimeout()

Returns any warnings generated by this DDBulkLoad object.SQLWarning getWarnings()

101Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DDBulkLoad interface

Page 102: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionDDBulkLoad Methods

Returns the maximum number of warnings that can occur. Once themaximum number is reached, the bulk load operation ends.

long getWarningTolerance()

Loads data from the CSV file specified by a file reference into a table.The table is specified using the setTableName() method. This methodalso returns the number of rows that have been successfully loaded.

If logging is enabled using the setLogFile() method, information aboutthe bulk load operation is recorded in the log file. If a discard file iscreated using the setDiscardFile() method, rows that were unable tobe loaded are recorded in the discard file. For more information, referto "Logging" and "Discard File" in the User’s Guide for your driver.

Before the bulk load operation is performed, your application can verifythat the data in the CSV file is compatible with the structure of the targettable using the validateTableFromFile() method.

long load(File)

Loads data from the CSV file specified by file name into a table. Thetable is specified using the setTableName() method. This method alsoreturns the number of rows that have been successfully loaded.

If logging is enabled using the setLogFile() method, information aboutthe bulk load operation is recorded in the log file. If a discard file iscreated using the setDiscardFile() method, rows that were unable tobe loaded are recorded in the discard file. For more information, referto "Logging" and "Discard File" in the user’s guide for your driver.

Before the bulk load operation is performed, your application can verifythat the data in the CSV file is compatible with the structure of the targettable using the validateTableFromFile() method.

long load(String)

Loads data from a ResultSet object into the table specified using thesetTableName() method. This method also returns the number of rowsthat have been successfully loaded.

If logging is enabled using the setLogFile() method, information aboutthe bulk load operation is recorded in the log file. For more information,refer to "Logging" in the user’s guide for your driver.

The structure of the table that produced the ResultSet object mustmatch the structure of the target table. If not, the driver throws anexception.

long load(ResultSet)

Specifies the number of rows that the driver sends at a time when bulkloading data. Performance can be improved by increasing the numberof rows the driver loads at a time because fewer network round tripsare required. Be aware that increasing the number of rows that areloaded also causes the driver to consume more memory on the client.

If unspecified, the driver uses a value of 2048.

void setBatchSize(long)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0102

Chapter 6: JDBC extensions

Page 103: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionDDBulkLoad Methods

Specifies the maximum size (in bytes) of binary data to be exported tothe CSV file. Any column with data over this threshold is exported intoindividual external overflow files and a marker of the format{DD LOBFILE "filename"} is placed in the CSV file to signify thatthe data for this column is located in an external file. The format foroverflow file names is:

csv_filename_xxxxxx.lob

where:

csv_filename

is the name of the CSV file.

xxxxxx

is a 6-digit number that increments the overflow file.

For example, if multiple overflow files are created for a CSV file namedCSV1, the file names would look like this:

CSV1.000001.lobCSV1.000002.lobCSV1.000003.lob...

If set to -1, the driver does not overflow binary data to external files.If unspecified, the driver uses a value of 4096.

For more information, refer to "External Overflow Files" in the user’sguide for your driver.

void setBinaryThreshold(long)

103Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DDBulkLoad interface

Page 104: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionDDBulkLoad Methods

Specifies the maximum size (in bytes) of character data to be exportedto the CSV file. Any column with data over this threshold is exportedinto individual external overflow files and a marker of the format{DD LOBFILE "filename"} is placed in the CSV file to signify thatthe data for this column is located in an external file. The format foroverflow file names is:

csv_filename_xxxxxx.lob

where:

csv_filename

is the name of the CSV file.

xxxxxx

is a 6-digit number that increments the overflow file.

For example, if multiple overflow files are created for a CSV file namedCSV1, the file names would look like this:

CSV1.000001.lobCSV1.000002.lobCSV1.000003.lob...

If set to -1, the driver does not overflow character data to externalfiles.If unspecified, the driver uses a value of 4096.

For more information, refer to "External Overflow Files" in the user’sguide for your driver.

void setCharacterThreshold(long)

Specifies the code page the driver uses for the CSV file. For moreinformation, refer to "Character Set Conversions" in the user’s guidefor your driver.

void setCodePage(String)

Specifies the fully qualified directory and file name of the bulk loadconfiguration file. If the Column Info section in the bulk loadconfiguration file is specified, the driver uses it to map the columns inthe CSV file to the columns in the target table when performing a bulkload operation.

If unspecified, the name of the bulk load configuration file is assumedto be csv_filename.xml, where csv_filename is the file name ofthe CSV file.

If set to an empty string, the driver does not try to use the bulk loadconfiguration file and reads all data from the CSV file as character data.

For more information, refer to "Bulk Load Configuration File" the user’sguide for your driver.

void setConfigFile(String)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0104

Chapter 6: JDBC extensions

Page 105: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionDDBulkLoad Methods

Specifies the fully qualified directory and file name of the discard file.The discard file contains rows that were unable to be loaded from aCSV file as the result of a bulk load operation. After fixing the reportedissues in the discard file, the bulk load can be reissued, using thediscard file as the CSV file. If unspecified, a discard file is not created.For more information, refer to "Discard File" in the user’s guide for yourdriver.

void setDiscardFile(String)

Specifies the maximum number of errors that can occur. Once themaximum number is reached, the bulk load operation ends. Errors arewritten to the log file. If set to 0, no errors are tolerated; the bulk loadoperation fails if any error is encountered. Any rows that were processedbefore the error occurred are loaded. If unspecified or set to -1, aninfinite number of errors are tolerated.

void setErrorTolerance(long)

Specifies the fully qualified directory and file name of the log file. Thelog file records information about each bulk load operation.If unspecified,a log file is not created. For more information, refer to "Logging" in theuser’s guide for your driver.

void setLogFile(String)

Specifies the maximum number of rows from the CSV file or ResultSetobject the driver will load.

void setNumRows()

Specifies one or more of the following properties for a DDBulkLoadobject:

tableName numRowscodePage binaryThresholdtimeout characterThresholdlogFile errorTolerancediscardFile warningToleranceconfigFile readBufferSizestartPosition batchSizeoperation

Except for the operation property, these properties also can be setusing the corresponding setxxx() methods, which provide a descriptionof the values that can be set.

The operation property defines which type of bulk operation will beperformed when a load method is called. The operation property acceptsthe following values: insert, update, delete, or upsert. The defaultvalue is insert. For more information, refer to "Specifying the BulkLoad Operation" in the user’s guide for your driver.

void setProperties(Properties)

Specifies the size (in KB) of the buffer that is used to read the CSV file.If unspecified, the driver uses a value of 2048.

void setReadBufferSize(long)

Specifies the position (number of the row) in a CSV file or ResultSetobject from which the bulk load operation starts. For example, if a valueof 10 is specified, the first 9 rows of the CSV file are skipped and thefirst row loaded is row 10.

void setStartPosition()

105Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DDBulkLoad interface

Page 106: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionDDBulkLoad Methods

When loading data into a table, specifies the name of the table intowhich the data is loaded (tablename).

Optionally, for the Salesforce driver, you can specify the column namesthat identify which columns to update in the table(destinationColumnList). Specifying column names is usefulwhen loading data from a CSV file into a table. The column namesused in the column list must be the names reported by the driver forthe columns in the table. For example, if you are loading data into theSalesforce system column NAME, the column list must identify thecolumn as SYS_NAME.

If destinationColumnList is not specified, a one-to-one mappingis performed between the columns in the CSV file and the columns inthe table.

destinationColumnList has the following format:

(destColumnName [,destColumnName]...)

where:

destColumnName

is the name of the column in the table to be updated.

The number of specified columns must match the number of columnsin the CSV file. For example, the following call tells the driver to updatethe Name, Address, City, State, PostalCode, Phone, and Websitecolumns:

bulkload.setTableName("account(Name, Address,City,State, PostalCode, Phone, Website)")

When exporting data from a table, specifies the name of the table fromwhich the data is exported. If the specified table does not exist, thedriver throws an exception. For more information, refer to "LoadingData From a ResultSet Object," "Loading Data From a CSV File," and"Exporting Data to a CSV File" in the user’s guide for your driver.

void setTableName(tablename([destinationColumnList]))

Sets the maximum number of seconds that can elapse for this bulkload operation to complete. Once this number is reached, the bulk loadoperation times out.

void setTimeout(long)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0106

Chapter 6: JDBC extensions

Page 107: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionDDBulkLoad Methods

Specifies the maximum number of warnings that can occur. Once themaximum is reached, the bulk load operation ends. Warnings are writtento the log file.

If set to 0, no warnings are tolerated; the bulk load operation fails if anywarning is encountered.

If unspecified or set to -1, an infinite number of warnings are tolerated.

void setWarningTolerance(long)

Verifies the metadata in the bulk load configuration file against thestructure of the table to which the data is loaded. This method is usedto ensure that the data in a CSV file is compatible with the structure ofthe target table before the actual bulk load operation is performed. Thedriver performs checks to detect mismatches of the following types:

Data types

Column sizes

Code pages

Column info

This method returns a Properties object with an entry for each of thesechecks:

• If no mismatches are found, the Properties object does not containany messages.

• If minor mismatches are found, the Properties object lists theproblems.

• If problems are detected that would prevent a successful bulk loadoperation, for example, if the target table does not exist, the driverthrows an exception.

For more information, refer to "Verifying the Bulk Load ConfigurationFile for Database Connections" in the user’s guide for your driver.

Properties validateTableFromFile()

ExtConnection interfaceThe methods of this interface are supported for all drivers.

DescriptionExtConnection Methods

Closes the current connection and marks the connection as closed.This method does not attempt to obtain any locks when closing theconnection. If subsequent operations are performed on the connection,the driver throws an exception.

void abortConnection()

Supported by the Oracle driver only for use with Oracle VARRAY andTABLE data types. Creates an array object.

Connection createArray(String, Object[])

107Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ExtConnection interface

Page 108: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionExtConnection Methods

Returns the accounting client information on the connection or an emptystring if the accounting client information value or the connection hasnot been set.

If getting accounting client information is supported by the databaseand this operation fails, the driver throws an exception.

String getClientAccountingInfo()

Returns the name of the client application on the connection or anempty string if the client name value for the connection has not beenset.

If getting client name information is supported by the database and thisoperation fails, the driver throws an exception.

String getClientApplicationName()

Returns the name of the host used by the client application on theconnection or an empty string if the client hostname value in thedatabase has not been set.

If getting host name information is supported by the database and thisoperation fails, the driver throws an exception.

String getClientHostname()

Returns the user ID of the client on the connection or an empty stringif the client user ID value for the connection has not been set. Theuser ID may be different from the user ID establishing the connection.

If getting user ID application information is supported by the databaseand this operation fails, the driver throws an exception.

String getClientUser()

Returns the current user of the connection. If reauthentication wasperformed on the connection, the current user may be different thanthe user that created the connection. For the DB2 and Oracle drivers,the current user is the same as the user reported byDatabaseMetaData.getUserName(). For the SQL Server driver, thecurrent user is the login user name. DatabaseMetaData.getUserName()reports the user name the login user name is mapped to in thedatabase.

See "Using Reauthentication" for more information.

String getCurrentUser()

Supported by the SQL Server driver to return the network timeout. Thenetwork timeout is the maximum time (in milliseconds) that a connection,or objects created by a connection, will wait for the database to replyto an application request. A value of 0 means that no network timeoutexists.

See void setNetworkTimeout(int) for details about setting a networktimeout.

int getNetworkTimeout()

Returns an ExtStatementPoolMonitor object for the statement poolassociated with the connection. If the connection does not have astatement pool, this method returns null. See "Using DataDirect-specificmethods to access the Statement Pool Monitor" for more information.

ExtStatementPoolMonitorgetStatementPoolMonitor()

Progress DataDirect for JDBC Drivers: Reference: Version 6.0108

Chapter 6: JDBC extensions

Page 109: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionExtConnection Methods

Specifies a non-null string that resets the current user on the connectionto the user that created the connection. It also restores the currentschema, current path, or current database to the original value usedwhen the connection was created. If reauthentication was performedon the connection, this method is useful to reset the connection to theoriginal user.

For the SQL Server driver, the current user is the login user name.Thedriver throws an exception in the following circumstances:

• The driver cannot change the current user to the initial user.

• A transaction is active on the connection.

void resetUser(String)

Specifies a non-null string that sets the accounting client informationon the connection. Some databases include this information in theirusage reports. The maximum length allowed for accounting informationfor a particular database can be determined by calling theExtDatabaseMetaData.getClientAccountingInfoLength() method. If thelength of the information specified is longer than the maximum lengthallowed, the information is truncated to the maximum length, and thedriver generates a warning.

If setting accounting client information is supported by the databaseand this operation fails, the driver throws an exception.

void setClientAccountingInfo(String)

Specifies a non-null string that sets the name of the client applicationon the connection. The maximum client name length allowed for aparticular database can be determined by calling theExtDatabaseMetaData.getClientApplicationNameLength() method. Ifthe length of the client application name specified is longer than themaximum name length allowed, the name is truncated to the maximumlength allowed, and the driver generates a warning.

If setting client name information is supported by the database and thisoperation fails, the driver throws an exception.

void setClientApplicationName(String)

Specifies a non-null string that sets the name of the host used by theclient application on the connection. The maximum hostname lengthallowed for a particular database can be determined by calling theExtDatabaseMetaData.getClientHostnameLength() method. If the lengthof the hostname specified is longer than the maximum hostname lengthallowed, the hostname is truncated to the maximum hostname length,and the driver generates a warning.

If setting hostname information is supported by the database and thisoperation fails, the driver throws an exception.

void setClientHostname(String)

109Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ExtConnection interface

Page 110: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionExtConnection Methods

Specifies a non-null string that sets the user ID of the client on theconnection. This user ID may be different from the user ID establishingthe connection. The maximum user ID length allowed for a particulardatabase can be determined by calling theExtDatabaseMetaData.getClientUserLength() method. If the length ofthe user ID specified is longer than the maximum length allowed, theuser ID is truncated to the maximum user ID length, and the drivergenerates a warning.

If setting user ID information is supported by the database and thisoperation fails, the driver throws an exception.

void setClientUser(String)

Specifies a non-null string that sets the current user on the connection.This method is used to perform reauthentication on a connection. Forthe SQL Server driver, the current user is the login user name. Thedriver throws an exception in the following circumstances:

• The driver is connected to a database server that does not supportreauthentication.

• The database server rejects the request to change the user on theconnection.

• A transaction is active on the connection.

void setCurrentUser(String)

Specifies a non-null string that sets the current user on the connection.This method is used to perform reauthentication on a connection. Inaddition, this method sets options that control how the driver handlesreauthentication. The options that are supported depend on the driver.See the DB2 driver, Oracle driver, and SQL Server driver chapters forinformation on which options are supported by each driver. For theSQL Server driver, the current user is the login user name. The driverthrows an exception in the following circumstances:

• The driver is connected to a database server that does not supportreauthentication.

• The database server rejects the request to change the user on theconnection.

• A transaction is active on the connection.

void setCurrentUser(String, Properties)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0110

Chapter 6: JDBC extensions

Page 111: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionExtConnection Methods

Specifies a non-null string that sets the current user on the connectionto the user specified by the javax.security.auth.Subject object. Thismethod is used to perform reauthentication on a connection. For theSQL Server driver, the current user is the login user name. The driverthrows an exception in the following circumstances:

• The driver does not support reauthentication.

• The driver is connected to a database server that does not supportreauthentication.

• The database server rejects the request to change the user on theconnection.

• A transaction is active on the connection.

voidsetCurrentUser(javax.security.auth.Subject)

Specifies a non-null string that sets the current user on the connectionto the user specified by the javax.security.auth.Subject object. Thismethod is used to perform reauthentication on a connection. In addition,this method sets options that control how the driver handlesreauthentication. The options that are supported depend on the driver.See your user's guide for information on which options are supportedby each driver.

For the SQL Server driver, the current user is the login user name.

The driver throws an exception in the following circumstances:

• The driver does not support reauthentication.

• The driver is connected to a database server that does not supportreauthentication.

• The database server rejects the request to change the user on theconnection.

• A transaction is active on the connection.

voidsetCurrentUser(javax.security.auth.Subject,Properties)

Supported by the SQL Server driver to set the network timeout. Thenetwork timeout is the maximum time (in milliseconds) that a connection,or objects created by a connection, will wait for the database to replyto an application request. If this limit is exceeded, the connection orobjects are closed and the driver returns an exception indicating thata timeout occurred. A value of 0 means that no network timeout exists.

Note that if a query timeout occurs before a network timeout, theexecution of the statement is cancelled. Both the connection and thestatement can be used. If a network timeout occurs before a querytimeout or if the query timeout fails because of network problems, theconnection is closed and neither the connection or the statement canbe used.

void setNetworkTimeout(int)

Indicates whether the connection supports reauthentication. If true isreturned, you can perform reauthentication on the connection. If falseis returned, any attempt to perform reauthentication on the connectionthrows an exception.

boolean supportsReauthentication()

111Progress DataDirect for JDBC Drivers: Reference: Version 6.0

ExtConnection interface

Page 112: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

See alsoUsing Reauthentication on page 182Using DataDirect-specific methods to access the Statement Pool Monitor on page 196

ExtDatabaseMetaData interfaceDescriptionExtDatabaseMetaData Methods

Returns the maximum length of the client application name. A value of0 indicates that the client application name is stored locally in the driver,not in the database. There is no maximum length if the applicationname is stored locally.

int getClientApplicationNameLength()

Returns the maximum length of the client user ID. A value of 0 indicatesthat the client user ID is stored locally in the driver, not in the database.There is no maximum length if the client user ID is stored locally.

int getClientUserLength()

Returns the maximum length of the hostname. A value of 0 indicatesthat the hostname is stored locally in the driver, not in the database.There is no maximum length if the hostname is stored locally.

int getClientHostnameLength()

Returns the maximum length of the accounting information. A value of0 indicates that the accounting information is stored locally in the driver,not in the database. There is no maximum length if the hostname isstored locally.

int getClientAccountingInfoLength()

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()

Progress DataDirect for JDBC Drivers: Reference: Version 6.0112

Chapter 6: JDBC extensions

Page 113: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

• Procedure calls

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.

For details, see the following topics:

• Date, time, and timestamp escape sequences

• Scalar functions

• Outer join escape sequences

• LIKE escape character sequence for wildcards

• Native and refresh escape sequences

113Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 114: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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 functionsThis section describes the scalar functions that are supported by the JDBC drivers. Note that your databasesystem may not support all these functions. The following table documents the functions supported by individualdrivers. Refer to the documentation for your database system to find out which functions are supported by yourdatabase.

In addition, you can also determine the supported scalar functions by using DatabaseMetaData methods.

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

{fn scalar-function}

where:

scalar-function

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

Example:

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.0114

Chapter 7: SQL escape sequences for JDBC

Page 115: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Table 4: Supported Scalar Functions

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

CURSESSIONID

DATABASE

IDENTITY

USER

CURDATE

CURTIME

DATEDIFF

DAY

DAYNAME

DAYOFMONTH

DAYOFWEEK

DAYOFYEAR

EXTRACT

HOUR

MINUTE

MONTH

MONTHNAME

NOW

QUARTER

SECOND

SECONDS_SINCE_MIDNIGHT

TIMESTAMPADD

TIMESTAMPDIFF

TO_CHAR

WEEK

YEAR

ABS

ACOS

ASIN

ATAN

ATAN2

BITAND

BITOR

BITXOR

CEILING

COS

COT

DEGREES

EXP

FLOOR

LOG

LOG10

MOD

PI

POWER

RADIANS

RAND

ROUND

ROUNDMAGIC

SIGN

SIN

SQRT

TAN

TRUNCATE

ASCII

BIT_LENGTH

CHAR

CHAR_LENGTH

CHARACTER_LENGTH

CONCAT

DIFFERENCE

HEXTORAW

INSERT

LCASE

LEFT

LENGTH

LOCATE

LOCATE_2

LOWER

LTRIM

OCTET_LENGTH

RAWTOHEX

REPEAT

REPLACE

RIGHT

RTRIM

SOUNDEX

SPACE

SUBSTR

SUBSTRING

UCASE

UPPER

ApacheCassandra

ApacheHive DBNAMECURDATEABSASCII

IFNULLCURRENT_DATEACOSCONCAT

CURRENT_TIMEASININSERT

CURRENT_TIMESTAMPATANLCASE

115Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Scalar functions

Page 116: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

CURTIMECEILINGLEFT

DAYOFMONTHCOSLENGTH

EXTRACTCOTLOCATE

HOURDEGREESLOCATE2

MINUTEEXPLTRIM

MONTHFLOORREPEAT

NOWLOGREPLACE

QUARTERLOG10RIGHT

SECONDMODPRTRIM

TIMESTAMPADD 37PISPACE

TIMESTAMPDIFFPOWERSUBSTRING

WEEKRADIANSUCASE

YEARRAND

ROUND

SIGN

SIN

SQRT

TAN

37 Apache Hive is limited to adding only days to a timestamp.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0116

Chapter 7: SQL escape sequences for JDBC

Page 117: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

DBNAME

IFNULL

CURDATE

CURRENT_DATE

CURRENT_TIME

CURRENT_TIMESTAMP

CURTIME

DAYOFMONTH

EXTRACT

HOUR

MINUTE

MONTH

NOW

QUARTER

SECOND

TIMESTAMPADD 38

TIMESTAMPDIFF

WEEK

YEAR

ABS

ACOS

ASIN

ATAN

CEILING

COS

COT

DEGREES

EXP

FLOOR

LOG

LOG10

MODP

PI

POWER

RADIANS

RAND

ROUND

SIGN

SIN

SQRT

TAN

ASCII

CONCAT

INSERT

LCASE

LEFT

LENGTH

LOCATE

LOCATE2

LTRIM

REPEAT

REPLACE

RIGHT

RTRIM

SPACE

SUBSTRING

UCASE

ApacheSpark SQL

38 Apache Spark SQL is limited to adding only days to a timestamp.

117Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Scalar functions

Page 118: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

CURSESSIONID

DATABASE

IDENTITY

USER

CURDATE

CURRENT_DATE

CURRENT_TIME

CURRENT_TIMESTAMP

CURTIME

DATEDIFF

DATE_ADD

DATE_SUB

DAY

DAYNAME

DAYOFMONTH

DAYOFWEEK

DAYOFYEAR

EXTRACT

HOUR

MINUTE

MONTH

MONTHNAME

NOW

QUARTER

SECOND

SECONDS_SINCE_MIDNIGHT

TIMESTAMPADD

TIMESTAMPDIFF

TO_CHAR

WEEK

YEAR

ABS

ACOS

ASIN

ATAN

ATAN2

BITAND

BITOR

BITXOR

CEILING

COS

COT

DEGREES

EXP

FLOOR

LOG

LOG10

MOD

PI

POWER

RADIANS

RAND

ROUND

ROUNDMAGIC

SIGN

SIN

SQRT

TAN

TRUNCATE

ASCII

BIT_LENGTH

CHAR

CHAR_LENGTH

CHARACTER_LENGTH

CONCAT

DIFFERENCE

HEXTORAW

INSERT

LCASE

LEFT

LENGTH

LOCATE

LOCATE_2

LOWER

LTRIM

OCTET_LENGTH

RAWTOHEX

REPEAT

REPLACE

RIGHT

RTRIM

SOUNDEX

SPACE

SUBSTR

SUBSTRING

UCASE

UPPER

AutonomousRESTConnector

Progress DataDirect for JDBC Drivers: Reference: Version 6.0118

Chapter 7: SQL escape sequences for JDBC

Page 119: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

CURSESSIONID

DATABASE

IDENTITY

USER

CURDATE

CURRENT_DATE

CURRENT_TIME

CURRENT_TIMESTAMP

CURTIME

DATEDIFF

DATE_ADD

DATE_SUB

DAY

DAYNAME

DAYOFMONTH

DAYOFWEEK

DAYOFYEAR

EXTRACT

HOUR

MINUTE

MONTH

MONTHNAME

NOW

QUARTER

SECOND

SECONDS_SINCE_MIDNIGHT

TIMESTAMPADD

TIMESTAMPDIFF

TO_CHAR

WEEK

YEAR

ABS

ACOS

ASIN

ATAN

ATAN2

BITAND

BITOR

BITXOR

CEILING

COS

COT

DEGREES

EXP

FLOOR

LOG

LOG10

MOD

PI

POWER

RADIANS

RAND

ROUND

ROUNDMAGIC

SIGN

SIN

SQRT

TAN

TRUNCATE

ASCII

BIT_LENGTH

CHAR

CHAR_LENGTH

CHARACTER_LENGTH

CONCAT

DIFFERENCE

HEXTORAW

INSERT

LCASE

LEFT

LENGTH

LOCATE

LOCATE_2

LOWER

LTRIM

OCTET_LENGTH

RAWTOHEX

REPEAT

REPLACE

RIGHT

RTRIM

SOUNDEX

SPACE

SUBSTR

SUBSTRING

UCASE

UPPER

Jira

MongoDBCURSESSIONIDCURDATEABSASCII

DATABASECURTIMEACOSBIT_LENGTH

IDENTITYDATEDIFFASINCHAR

DAYATANCHAR_LENGTH USER

DAYNAMEATAN2CHARACTER_LENGTH

119Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Scalar functions

Page 120: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

DAYOFMONTHBITANDCONCAT

DAYOFWEEKBITORDIFFERENCE

DAYOFYEARBITXORHEXTORAW

EXTRACTCEILINGINSERT

HOURCOSLCASE

MINUTECOTLEFT

MONTHDEGREESLENGTH

MONTHNAMEEXPLOCATE

NOWFLOORLOCATE_2

QUARTERLOGLOWER

SECONDLOG10LTRIM

SECONDS_SINCE_MIDNIGHTMODOCTET_LENGTH

TIMESTAMPADDPIRAWTOHEX

TIMESTAMPDIFFPOWERREPEAT

TO_CHARRADIANSREPLACE

WEEKRANDRIGHT

ROUNDRTRIM YEAR

ROUNDMAGICSOUNDEX

SIGNSPACE

SINSUBSTR

SQRTSUBSTRING

TANUCASE

TRUNCATEUPPER

OracleIFNULLCURDATEABSASCII

DAYNAMEACOSBIT_LENGTH USER

DAYOFMONTHASINCHAR

DAYOFWEEKATANCONCAT

DAYOFYEARATAN2INSERT

HOURCEILINGLCASE

MINUTECOSLEFT

MONTHCOTLENGTH

MONTHNAMEEXPLOCATE

NOWFLOORLOCATE2

QUARTERLOGLTRIM

Progress DataDirect for JDBC Drivers: Reference: Version 6.0120

Chapter 7: SQL escape sequences for JDBC

Page 121: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

SECONDLOG10OCTET_LENGTH

WEEKMODREPEAT

PIREPLACE YEAR

POWERRIGHT

ROUNDRTRIM

SIGNSOUNDEX

SINSPACE

SQRTSUBSTRING

TANUCASE

TRUNCATE

OracleEloqua CURSESSIONIDCURDATEABSASCII

DATABASECURTIMEACOSBIT_LENGTH

IDENTITYDATEDIFFASINCHAR

USERDAYATANCHAR_LENGTH

DAYNAMEATAN2CHARACTER_LENGTH IFNULL

DAYOFMONTHBITANDCONCAT

DAYOFWEEKBITORDIFFERENCE

DAYOFYEARBITXORHEXTORAW

EXTRACTCOSINSERT

HOURCOTLCASE

MINUTEDEGREESLEFT

MONTHEXPLENGTH

MONTHNAMEFLOORLOCATE

NOWLOGLOCATE_2

SECONDLOG10LOWER

TO_CHARMODLTRIM

WEEKPIOCTET_LENGTH

POWERRAWTOHEX YEAR

RADIANSREPEAT

RANDREPLACE

ROUNDRIGHT

SIGNRTRIM

SINSOUNDEX

SQRTSPACE

121Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Scalar functions

Page 122: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

TANSUBSTR

SUBSTRING TRUNCATE

UCASE

UPPER

OracleSalesCloud

CURSESSIONIDCURDATEABSASCII

DATABASECURTIMEACOSBIT_LENGTH

IDENTITYDATEDIFFASINCHAR

USERDAYATANCHAR_LENGTH

DAYNAMEATAN2CHARACTER_LENGTH IFNULL

DAYOFMONTHBITANDCONCAT

DAYOFWEEKBITORDIFFERENCE

DAYOFYEARBITXORHEXTORAW

EXTRACTCEILINGINSERT

HOURCOSLCASE

MINUTECOTLEFT

MONTHDEGREESLENGTH

MONTHNAMEEXPLOCATE

NOWFLOORLOCATE_2

SECONDLOGLOWER

TO_CHARLOG10LTRIM

WEEKMODOCTET_LENGTH

PIRAWTOHEX YEAR

POWERREPEAT

RADIANSREPLACE

RANDRIGHT

ROUNDRTRIM

ROUNDMAGICSOUNDEX

SIGNSPACE

SINSUBSTR

SQRTSUBSTRING

TANUCASE

TRUNCATEUPPER

Progress DataDirect for JDBC Drivers: Reference: Version 6.0122

Chapter 7: SQL escape sequences for JDBC

Page 123: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

CURSESSIONID

DATABASE

IDENTITY

USER

CURDATE

CURRENT_DATE

CURRENT_TIME

CURRENT_TIMESTAMP

CURTIME

DATEDIFF

DATE_ADD

DATE_SUB

DAY

DAYNAME

DAYOFMONTH

DAYOFWEEK

DAYOFYEAR

EXTRACT

HOUR

MINUTE

MONTH

MONTHNAME

NOW

QUARTER

SECOND

SECONDS_SINCE_MIDNIGHT

TIMESTAMPADD

TIMESTAMPDIFF

TO_CHAR

WEEK

YEAR

ABS

ACOS

ASIN

ATAN

ATAN2

BITAND

BITOR

BITXOR

CEILING

COS

COT

DEGREES

EXP

FLOOR

LOG

LOG10

MOD

PI

POWER

RADIANS

RAND

ROUND

ROUNDMAGIC

SIGN

SIN

SQRT

TAN

TRUNCATE

ASCII

BIT_LENGTH

CHAR

CHAR_LENGTH

CHARACTER_LENGTH

CONCAT

DIFFERENCE

HEXTORAW

INSERT

LCASE

LEFT

LENGTH

LOCATE

LOCATE_2

LOWER

LTRIM

OCTET_LENGTH

RAWTOHEX

REPEAT

REPLACE

RIGHT

RTRIM

SOUNDEX

SPACE

SUBSTR

SUBSTRING

UCASE

UPPER

Salesforce

SQLServer DATABASEDAYNAMEABSASCII

IFNULLDAYOFMONTHACOSCHAR

DAYOFWEEKASINCONCAT USER

DAYOFYEARATANDIFFERENCE

EXTRACTATAN2INSERT

123Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Scalar functions

Page 124: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System FunctionsTimedate FunctionsNumericFunctions

String FunctionsDataStore

HOURCEILINGLCASE

MINUTECOSLEFT

MONTHCOTLENGTH

MONTHNAMEDEGREESLOCATE

NOWEXPLTRIM

QUARTERFLOORREPEAT

SECONDLOGREPLACE

TIMESTAMPADDLOG10RIGHT

TIMESTAMPDIFFMODRTRIM

WEEKPISOUNDEX

POWERSPACE YEAR

RADIANSSUBSTRING

RANDUCASE

ROUND

SIGN

SIN

SQRT

TAN

TRUNCATE

String functionsThe following table lists the string functions that JDBC supports.

The string functions listed accept the following arguments:

• string_exp can be the name of a column, a string literal, or the result of another scalar function, wherethe underlying data type is CHAR, VARCHAR, or LONGVARCHAR.

• start, length, and count can be the result of another scalar function or a literal numeric value, wherethe underlying data type is TINYINT, SMALLINT, or INTEGER.

The string functions are one-based; that is, the first character in the string is character 1.

Character string literals must be surrounded in single quotation marks.

Table 5: Scalar String Functions

ReturnsFunction

ASCII code value of the leftmost character of string_exp as an integer.ASCII(string_exp)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0124

Chapter 7: SQL escape sequences for JDBC

Page 125: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

ReturnsFunction

The length in bits of the string expression.BIT_LENGTH(string_exp)

The character with the ASCII code value specified by code. code should bebetween 0 and 255; otherwise, the return value is data-source dependent.

CHAR(code)

The length in characters of the string expression, if the string expression is of acharacter data type; otherwise, the length in bytes of the string expression (thesmallest integer not less than the number of bits divided by 8). (This function isthe same as the CHARACTER_LENGTH function.)

CHAR_LENGTH(string_exp)

The length in characters of the string expression, if the string expression is of acharacter data type; otherwise, the length in bytes of the string expression (thesmallest integer not less than the number of bits divided by 8). (This function isthe same as the CHAR_LENGTH function.)

CHARACTER_LENGTH(string_exp)

The string resulting from concatenating string_exp2 and string_exp1. Thestring is system dependent.

CONCAT(string_exp1, string_exp2)

An integer value that indicates the difference between the values returned bythe SOUNDEX function for string_exp1 and string_exp2.

DIFFERENCE(string_exp1,string_exp2)

A string where length characters have been deleted from string_exp1beginning at start and where string_exp2 has been inserted intostring_exp beginning at start.

INSERT(string_exp1, start, length,string_exp2)

Uppercase characters in string_exp converted to lowercase.LCASE(string_exp)

The count of characters of string_exp.LEFT(string_exp,count)

The number of characters in string_exp, excluding trailing blanks and thestring termination character.

LENGTH(string_exp)

The starting position of the first occurrence of string_exp1 withinstring_exp2. If start is not specified, the search begins with the first characterposition in string_exp2. If start is specified, the search begins with thecharacter position indicated by the value of start. The first character positionin string_exp2 is indicated by the value 1. If string_exp1 is not found, 0 isreturned.

LOCATE(string_exp1,string_exp2[,start])

The characters of string_exp with leading blanks removed.LTRIM(string_exp)

The length in bytes of the string expression. The result is the smallest integernot less than the number of bits divided by 8.

OCTET_LENGTH(string_exp)

The position of the first character expression in the second character expression.The result is an exact numeric with an implementation-defined precision and ascale of 0.

POSITION(character_exp INcharacter_exp)

A string composed of string_exp repeated count times.REPEAT(string_exp, count)

125Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Scalar functions

Page 126: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

ReturnsFunction

Replaces all occurrences of string_exp2 in string_exp1with string_exp3.REPLACE(string_exp1, string_exp2,string_exp3)

The rightmost count of characters in string_exp.RIGHT(string_exp, count)

The characters of string_exp with trailing blanks removed.RTRIM(string_exp)

A data source dependent string representing the sound of the words instring_exp.

SOUNDEX(string_exp)

A string consisting of count spaces.SPACE(count)

A string derived from string_exp beginning at the character position startfor length characters.

SUBSTR(string_exp, start, length)

A string derived from string_exp beginning at the character position startfor length characters.

SUBSTRING(string_exp, start,length)

Lowercase characters in string_exp converted to uppercase.UCASE(string_exp)

Numeric functionsThe following table lists the numeric functions that JDBC supports.

The numeric functions listed accept the following arguments:

• numeric_exp can be a column name, a numeric literal, or the result of another scalar function, where theunderlying data type is NUMERIC, DECIMAL,TINYINT, SMALLINT, INTEGER, BIGINT, FLOAT, SQL_REAL,or DOUBLE.

• float_exp can be a column name, a numeric literal, or the result of another scalar function, where theunderlying data type is FLOAT.

• integer_exp can be a column name, a numeric literal, or the result of another scalar function, where theunderlying data type is TINYINT, SMALLINT, INTEGER, or BIGINT.

Table 6: Scalar Numeric Functions

ReturnsFunction

Absolute value of numeric_exp.ABS(numeric_exp)

Arccosine of float_exp as an angle in radians.ACOS(float_exp)

Arcsine of float_exp as an angle in radians.ASIN(float_exp)

Arctangent of float_exp as an angle in radians.ATAN(float_exp)

Arctangent of the x and y coordinates, specified by float_exp1 andfloat_exp2 as an angle in radians.

ATAN2(float_exp1, float_exp2)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0126

Chapter 7: SQL escape sequences for JDBC

Page 127: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

ReturnsFunction

Smallest integer greater than or equal to numeric_exp.CEILING(numeric_exp)

Cosine of float_exp as an angle in radians.COS(float_exp)

Cotangent of float_exp as an angle in radians.COT(float_exp)

Number if degrees converted from numeric_exp radians.DEGREES(numeric_exp)

Exponential value of float_exp.EXP(float_exp)

Largest integer less than or equal to numeric_exp.FLOOR(numeric_exp)

Natural log of float_exp.LOG(float_exp)

Base 10 log of float_exp.LOG10(float_exp)

Remainder of integer_exp1 divided by integer_exp2.MOD(integer_exp1, integer_exp2)

Constant value of pi as a floating-point number.PI()

Value of numeric_exp to the power of integer_exp.POWER(numeric_exp, integer_exp)

Number of radians converted from numeric_exp degrees.RADIANS(numeric_exp)

Random floating-point value using integer_exp as the optional seedvalue.

RAND([integer_exp])

numeric_exp rounded to integer_exp places right of the decimal (leftof the decimal if integer_exp is negative).

ROUND(numeric_exp, integer_exp)

Indicator of the sign of numeric_exp. If numeric_exp < 0, -1 is returned.If numeric_exp = 0, 0 is returned. If numeric_exp > 0, 1 is returned.

SIGN(numeric_exp)

Sine of float_exp, where float_exp is an angle in radians.SIN(float_exp)

Square root of float_exp.SQRT(float_exp)

Tangent of float_exp, where float_exp is an angle in radians.TAN(float_exp)

numeric_exp truncated to integer_exp places right of the decimal. (Ifinteger_exp is negative, truncation is to the left of the decimal.)

TRUNCATE(numeric_exp, integer_exp)

Date and time FunctionsThe following table lists the date and time functions that JDBC supports.

The date and time functions listed accept the following arguments:

• date_exp can be a column name, a date or timestamp literal, or the result of another scalar function, wherethe underlying data type can be represented as CHAR, VARCHAR, DATE, or TIMESTAMP.

127Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Scalar functions

Page 128: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

• time_exp can be a column name, a timestamp or timestamp literal, or the result of another scalar function,where the underlying data type can be represented as CHAR, VARCHAR, TIME, or TIMESTAMP.

• timestamp_exp can be a column name; a time, date, or timestamp literal; or the result of another scalarfunction, where the underlying data type can be represented as CHAR, VARCHAR, TIME, DATE, orTIMESTAMP.

Table 7: Scalar Time and Date Functions

ReturnsFunction

Current date.CURRENT_DATE()

Current local time. The time-precision argumentdetermines the seconds precision of the returned value.

CURRENT_TIME[(time-precision)]

Current local date and local time as a timestamp value.The timestamp-precision argument determines theseconds precision of the returned timestamp.

CURRENT_TIMESTAMP([timestamp-precision])

Current date as a date value.CURDATE()

Current local time as a time value.CURTIME()

Character string containing a data-source-specific nameof the day for the day portion of date_exp.

DAYNAME(date_exp)

Day of the month in date_exp as an integer value (1–31).DAYOFMONTH(date_exp)

Day of the week in date_exp as an integer value (1–7).DAYOFWEEK(date_exp)

Day of the year in date_exp as an integer value (1–366).DAYOFYEAR(date_exp)

Any of the date and time terms can be extracted fromdatetime_value.

EXTRACT({YEAR | MONTH | DAY | HOUR | MINUTE |SECOND} FROM datetime_value)

Hour in time_exp as an integer value (0–23).HOUR(time_exp)

Minute in time_exp as an integer value (0–59).MINUTE(time_exp)

Month in date_exp as an integer value (1–12).MONTH(date_exp)

Character string containing the data source-specific nameof the month.

MONTHNAME(date_exp)

Current date and time as a timestamp value.NOW()

Quarter in date_exp as an integer value (1–4).QUARTER(date_exp)

Second in date_exp as an integer value (0–59).SECOND(time_exp)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0128

Chapter 7: SQL escape sequences for JDBC

Page 129: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

ReturnsFunction

Timestamp calculated by adding integer_exp intervals oftype interval to time_exp. interval can be one of thefollowing values:

SQL_TSI_FRAC_SECOND

SQL_TSI_SECOND

SQL_TSI_MINUTE

SQL_TSI_HOUR

SQL_TSI_DAY

SQL_TSI_WEEK

SQL_TSI_MONTH

SQL_TSI_QUARTER

SQL_TSI_YEAR

Fractional seconds are expressed in billionths of asecond.

TIMESTAMPADD(interval, integer_exp, time_exp)

Integer number of intervals of type interval by whichtime_exp2 is greater than time_exp1. interval has thesame values as TIMESTAMPADD. Fractional secondsare expressed in billionths of a second.

TIMESTAMPDIFF(interval, time_exp1, time_exp2)

Week of the year in date_exp as an integer value (1–53).WEEK(date_exp)

Year in date_exp. The range is data-source dependent.YEAR(date_exp)

System functionsThe following table lists the system functions that JDBC supports.

Table 8: Scalar System Functions

ReturnsFunction

Name of the database, corresponding to the connection handle (hdbc).DATABASE()

value, if exp is null.IFNULL(exp,value)

Authorization name of the user.USER()

129Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Scalar functions

Page 130: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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'

Note: The ON clause in a join expression must evaluate to a true or false value.

Table 9: Outer Join Escape Sequences Supported

Outer Join Escape SequencesDriver

Left outer joins

Right outer joins

Full outer joins

Nested outer joins

Apache Cassandra

Left outer joins

Right outer joins

Full outer joins

Apache Hive

Left outer joins

Right outer joins

Full outer joins

Apache Spark SQL

Progress DataDirect for JDBC Drivers: Reference: Version 6.0130

Chapter 7: SQL escape sequences for JDBC

Page 131: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Outer Join Escape SequencesDriver

Left outer joins

Right outer joins

Full outer joins

Nested outer joins

Autonomous REST Connector

Left outer joins

Right outer joins

Full outer joins

Nested outer joins

Jira

Left outer joins

Right outer joins

Full outer joins

Nested outer joins

MongoDB

Left outer joins

Right outer joins

Full outer joins

Nested outer joins

Oracle

Left outer joins

Right outer joins

Full outer joins

Nested outer joins

Oracle Eloqua

Left outer joins

Right outer joins

Full outer joins

Nested outer joins

Oracle Sales Cloud

131Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Outer join escape sequences

Page 132: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Outer Join Escape SequencesDriver

Left outer joins

Right outer joins

Nested outer joins

Salesforce

Left outer joins

Right outer joins

Full outer joins

Nested outer joins

SQL Server

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 '*'}

Note: The right-hand side of a LIKE expression must evaluate to a string or binary.

Native and refresh escape sequencesThe following drivers support Native and Refresh Escape Sequences:

• Apache Cassandra

• Salesforce

Native and Refresh escape sequences provide a method to embed data store-specific commands in SQL-92statements. The Native escape sequence allows you to execute native commands directly through the clientapplication, while the Refresh escape sequence is used to incorporate any changes introduced by the Nativeescape into the driver's relational map of the data.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0132

Chapter 7: SQL escape sequences for JDBC

Page 133: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Note: The Native and Refresh escape sequences are mainly intended for the execution of DDL commands,such as ALTER, CREATE, and DROP. A returning clause for the Native escape is not currently supported bythe driver. Therefore, results cannot be retrieved using the Native escape sequence.

The Native escape sequences can be used with the following syntax:

{native(command_text)}

where:

command_text

is a data store-specific command.

The Refresh escape sequence has no additional argument and takes the form:

{refresh}

The following example shows the execution of two data store-specific commands with a refresh of the driver'srelational map of the data. Note that each Native escape sequence must have its own execute method. TheRefresh escape, however, can be used in the same execute statement as the Native escape.

stmt.executeUpdate ("{native (CREATE TABLE emp (empid int, title varchar))}");stmt.executeUpdate ("{native (CREATE TABLE dept (deptid int, city varchar))}{refresh}");

133Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Native and refresh escape sequences

Page 134: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Progress DataDirect for JDBC Drivers: Reference: Version 6.0134

Chapter 7: SQL escape sequences for JDBC

Page 135: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

8Designing 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 136

Reduce network traffic.Network communication is slow.

Using database metadata methods onpage 136

Selecting JDBC objects and methodson page 140

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

135Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 136: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

See guidelines in…SolutionProblem

Returning data on page 138

Selecting JDBC objects and methodson page 140

Optimize application-to-driverinteraction.

Excessive calls from the application tothe driver slow performance.

Managing connections and updates onpage 143

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.

For details, see the following topics:

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.0136

Chapter 8: Designing JDBC applications for performance optimization

Page 137: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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();...

137Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Using database metadata methods

Page 138: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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);

Progress DataDirect for JDBC Drivers: Reference: Version 6.0138

Chapter 8: Designing JDBC applications for performance optimization

Page 139: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

139Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Returning data

Page 140: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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 statement object instead of the PreparedStatement objectJDBC 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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0140

Chapter 8: Designing JDBC applications for performance optimization

Page 141: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

141Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Selecting JDBC objects and methods

Page 142: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0142

Chapter 8: Designing JDBC applications for performance optimization

Page 143: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

143Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Managing connections and updates

Page 144: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.0144

Chapter 8: Designing JDBC applications for performance optimization

Page 145: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

145Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Managing connections and updates

Page 146: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0146

Chapter 8: Designing JDBC applications for performance optimization

Page 147: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

9DataDirect tools

This section provides detailed tutorials for the DataDirect tools that are installed with each JDBC driver.

For details, see the following topics:

• DataDirect Test

• Connection Pool Manager

• Statement Pool Monitor

• Tracking JDBC calls with DataDirect Spy

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.

147Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 148: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0148

Chapter 9: DataDirect tools

Page 149: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

149Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 150: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Important: For the Autonomous REST Connector: REST API data sources do not connect in the samemanner as database servers; therefore; the Connection Established notification does not guaranteethat the driver is properly configured. To confirm that the driver is correctly configured, you will need toretrieve data from an endpoint using the methods described in "Executing a simple database selection."

See alsoExecuting a simple Select statement on page 152

Progress DataDirect for JDBC Drivers: Reference: Version 6.0150

Chapter 9: DataDirect tools

Page 151: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

151Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 152: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Important: For the Autonomous REST Connector: REST API data sources do not connect in the samemanner as database servers; therefore; the Connection Established notification does not guaranteethat the driver is properly configured. To confirm that the driver is correctly configured, you will need toretrieve data from an endpoint using the methods described in "Executing a simple database selection."

See alsoExecuting a simple Select statement on page 152

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0152

Chapter 9: DataDirect tools

Page 153: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

153Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 154: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

a) Type the parameter number.

b) Select the parameter type.

c) Type the parameter value.

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

4. When you are finished, click Close.

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.0154

Chapter 9: DataDirect tools

Page 155: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

6. If you want to insert multiple records, repeat Step 3 on page 154 and Step 5 on page 154 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.

155Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 156: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

See alsoExecuting a simple Select statement on page 152

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0156

Chapter 9: DataDirect tools

Page 157: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

157Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 158: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0158

Chapter 9: DataDirect tools

Page 159: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

159Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 160: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0160

Chapter 9: DataDirect tools

Page 161: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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 160 through Step 4 on page 161 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 the previouslyinserted records are returned.

161Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 162: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

See alsoExecuting a simple Select statement on page 152

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0162

Chapter 9: DataDirect tools

Page 163: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

163Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 164: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0164

Chapter 9: DataDirect tools

Page 165: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

165Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 166: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

2. Complete the following fields:

a) In the resultSetType field, select TYPE_SCROLL_SENSITIVE.

b) In the resultSetConcurrency field, select CONCUR_UPDATABLE.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0166

Chapter 9: DataDirect tools

Page 167: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

3. Click Submit; then, click Close.

4. Select Statement / Execute Stmt Query.

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

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

167Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 168: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0168

Chapter 9: DataDirect tools

Page 169: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

Inserting a row

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

2. Complete the following fields:

a) In the resultSetType field, select TYPE_SCROLL_SENSITIVE.

b) In the resultSetConcurrency field, select CONCUR_UPDATABLE.

169Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 170: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

3. Click Submit; then, click Close.

4. Select Statement / Execute Stmt Query.

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

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.0170

Chapter 9: DataDirect tools

Page 171: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

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

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

171Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 172: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

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

2. Complete the following fields:

a) In the resultSetType field, select TYPE_SCROLL_SENSITIVE.

b) In the resultSetConcurrency field, select CONCUR_UPDATABLE.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0172

Chapter 9: DataDirect tools

Page 173: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

3. Click Submit; then, click Close.

4. Select Statement / Execute Stmt Query.

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

6. Click Submit; then, click Close.

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

173Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 174: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

8. Click Next. Current Row changes to 1.

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

10. Click Update Row.

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

12. Specify the statement that you want to execute.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0174

Chapter 9: DataDirect tools

Page 175: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

13. Click Submit; then, click Close.

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.

2. Select Statement / Execute Stmt Query.

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

175Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 176: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

4. Click Submit; then, click Close.

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

6. Click Next. Current Row changes to 1.

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.0176

Chapter 9: DataDirect tools

Page 177: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

9. Change the data type to Clob.

177Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 178: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.0178

Chapter 9: DataDirect tools

Page 179: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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

179Progress DataDirect for JDBC Drivers: Reference: Version 6.0

DataDirect Test

Page 180: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Connection Pool ManagerThe DataDirect Connection Pool Manager allows you to pool connections when accessing databases. Whenyour applications use connection pooling, connections are reused rather than created each time a connectionis requested. Because establishing a connection is among the most costly operations an application mayperform, using Connection Pool Manager to implement connection pooling can significantly improve performance.

How connection pooling worksTypically, creating a connection is the most expensive operation an application performs. Connection poolingallows you to reuse connections rather than create a new one every time an application needs to connect tothe database. Connection pooling manages connection sharing across different user requests to maintainperformance and reduce the number of new connections that must be created. For example, compare thefollowing transaction sequences.

Example A: Without connection pooling1. The application creates a connection.

2. The application sends a query to the database.

3. The application obtains the result set of the query.

4. The application displays the result to the end user.

5. The application ends the connection.

Example B: With connection pooling1. The application requests a connection from the connection pool.

2. If an unused connection exists, it is returned by the pool; otherwise, the pool creates a new connection.

3. The application sends a query to the database.

4. The application obtains the result set of the query.

5. The application displays the result to the end user.

6. The application closes the connection, which returns the connection to the pool.

Note: The application calls the close() method, but the connection remains open and the pool is notified ofthe close request.

The connection pool environmentThere is a one-to-one relationship between a JDBC connection pool and a data source, so the number ofconnection pools used by an application depends on the number of data sources configured to use connectionpooling. If multiple applications are configured to use the same data source, those applications share the sameconnection pool as shown in the following figure.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0180

Chapter 9: DataDirect tools

Page 181: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

An application may use only one data source, but allow multiple users, each with their own set of login credentials.The connection pool contains connections for all unique users using the same data source as shown in thefollowing figure.

Connections are one of the following types:

• Active connection is a connection that is in use by the application.

• Idle connection is a connection in the connection pool that is available for use.

The DataDirect Connection Pool ManagerConnection pooling is performed in the background and does not affect how an application is coded. To useconnection pooling, an application must use a DataSource object (an object implementing the DataSourceinterface) to obtain a connection instead of using the DriverManager class. A DataSource object registerswith a JNDI naming service. Once a DataSource object is registered, the application retrieves it from the JNDInaming service in the standard way.

Connection pool implementations, such as the DataDirect Connection Pool Manager, use objects that implementthe javax.sql.ConnectionPoolDataSource interface to create the connections managed in a connectionpool. All Progress DataDirect data source objects implement the ConnectionPoolDataSource interface.

The DataDirect Connection Pool Manager creates database connections, referred to as PooledConnections,by using the getPooledConnection() method of the ConnectionPoolDataSource interface. Then, thePool Manager registers itself as a listener to the PooledConnection. When a client application requests aconnection, the Pool Manager assigns an available connection. If a connection is unavailable, the Pool Managerestablishes a new connection and assigns it to that application.

181Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection Pool Manager

Page 182: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

When the application closes the connection, the driver uses the ConnectionEventListener interface tonotify the Pool Manager that the connection is free and available for reuse. The driver also uses theConnectionEventListener interface to notify the Pool Manager when a connection is corrupted so thatthe Pool Manager can remove that connection from the pool.

Using a connection pool DataSource objectOnce a PooledConnectionDataSource object has been created and registered with JNDI, it can be usedby your JDBC application as shown in the following example:

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

The example begins with the intialization of the JNDI environment. Then, the initial naming context is used tofind the logical name of the JDBC DataSource (EmployeeDB). The Context.lookup method returns areference to a Java object, which is narrowed to a javax.sql.ConnectionPoolDataSource object. Next,the ConnectionPoolDataSource.getPooledConnection() method is called to establish a connectionwith the underlying database. Then, the application obtains a connection from theConnectionPoolDataSource.

Using ReauthenticationTypically, you can configure a connection pool to provide scalability for connections. In addition, to help minimizethe number of connections required in a connection pool, you can switch the user associated with a connectionto another user, a process known as reauthentication.

For example, suppose you are using Kerberos authentication to authenticate users using their operating systemuser name and password. To reduce the number of connections that must be created and managed, you canuse reauthentication to switch the user associated with a connection to multiple users. For example, supposeyour connection pool contains a connection, Conn, which was established by the user ALLUSERS. Thatconnection can service multiple users (User A, B, and C) by switching the user associated with the connectionConn to User A, B, and C.

Not all databases support reauthentication. For databases that do, the user performing the switch must havebeen granted specific database permissions.

The following table shows the support for reauthentication and lists the required database permissions. Referto your database documentation for information about granting permissions.

Table 10: Support for Reauthentication

Database PermissionsDatabaseDriver

CONNECT THROUGHOracle8i R2 and higher 39Oracle

IMPERSONATEMicrosoft SQL Server 2005 and higher 40, 41SQL Server

Note: Before performing reauthentication, applications must ensure that any statements or result sets createdas one user are closed before switching the connection to another user.

39 Oracle refers to reauthentication as proxy authentication.40 Microsoft SQL Server refers to reauthentication as impersonation.41 Reauthentication is not supported for SQL Server Azure, Analytics Data Warehouse, or Analytics Platform System (Parallel

Data Warehouse).

Progress DataDirect for JDBC Drivers: Reference: Version 6.0182

Chapter 9: DataDirect tools

Page 183: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

To perform reauthentication on a connection explicitly, call the setCurrentUser() method in the ExtConnectioninterface located in the com.ddtek.jdbc.extensions package. For example, the following code switches the useron the connection from the user that created the connection (TEST) to a new user (SMITH). In addition, it setsoptions that switch the current schema and current database path to the schema and database path of thenew user.

import com.ddtek.jdbc.extensions.*// Get Database ConnectionConnection con = DriverManager.getConnection(

"jdbc:datadirect:sqlserver://server1:1433;DatabaseName=jdbc", "TEST", "secret");ExtConnection extCon = (ExtConnection)conProperties props = new Properties();

props.put("CURRENT_SCHEMA", "SCHEMA");props.put("CURRENT_PATH", "PATH");ExtCon.setCurrentUser("SMITH", props);...

See the appropriate driver chapters for information on supported options for each driver.

If you are using the DataDirect Connection Pool Manager for connection pooling, you can enable reauthenticationin the Pool Manager. See "Using Reauthentication with the Pool Manager" for details.

See alsoUsing Reauthentication with the Pool Manager on page 187

Implementing DataDirect connection poolingTo use connection pooling, an application must use a DataSource object (an object implementing theDataSource interface) to obtain a connection instead of using the DriverManager class. A DataSourceobject registers with a JNDI naming service. Once a DataSource object is registered, the application retrievesit from the JNDI naming service in the standard way.

To implement DataDirect connection pooling, perform the following steps.

1. Create and register with JNDI a Progress DataDirect data source object. Once created, the DataSourceobject can be used by a connection pool (PooledConnectionDataSource object created in "Creating adriver DataSource object") to create connections for one or multiple connection pools.

2. To create a connection pool, you must create and register with JNDI a PooledConnectionDataSourceobject. A PooledConnectionDataSource creates and manages one or multiple connection pools. ThePooledConnectionDataSource uses the driver DataSource object created in "Creating the connectionpool" to create the connections for the connection pool.

Creating a driver DataSource objectThe following Java code example creates a Progress DataDirect DataSource object and registers it with aJNDI naming service.

The DataSource class is database-dependent. In this example we use Oracle, so the DataSource class isOracleDataSource. Refer to your the user’s guide for your driver for the name of your driver's DataSourceclass.

Note: The DataSource class implements the ConnectionPoolDataSource interface for pooling in additionto the DataSource interface for non-pooling.

183Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection Pool Manager

Page 184: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

//************************************************************************// This code creates a Progress DataDirect for JDBC data source and// registers it to a JNDI naming service. This JDBC data source uses the// DataSource implementation provided by DataDirect Connect Series// for JDBC Drivers.//// This data source registers its name as <jdbc/ConnectOracle>.//// NOTE: To connect using a data source, the driver needs to access a JNDI data// store to persist the data source information. To download the JNDI File// System Service Provider, go to://// http://www.oracle.com/technetwork/java/javasebusiness/downloads/// java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR////// Make sure that the fscontext.jar and providerutil.jar files from the// download are on your classpath.//************************************************************************// From DataDirect Connect Series for JDBC:import java.util.Hashtable;

import javax.naming.Context;import javax.naming.InitialContext;

import com.ddtek.jdbcx.oracle.OracleDataSource;public class OracleDataSourceRegisterJNDI {public static void main(String argv[]) {try {

// Set up data source reference data for naming context:// ----------------------------------------------------// Create a class instance that implements the interface// ConnectionPoolDataSourceOracleDataSource ds = new OracleDataSource();

ds.setDescription("Oracle DataSource");ds.setServerName("Server3");ds.setPortNumber(1521);ds.setUser("User123");ds.setPassword("secret");ds.setSID("ORCL");

// Set up environment for creating initial contextHashtable env = new Hashtable();env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.fscontext.RefFSContextFactory");env.put(Context.PROVIDER_URL, "file:C:\\JNDI_Test_Dir");Context ctx = new InitialContext(env);

// Register the data source to JNDI naming servicectx.bind("jdbc/ConnectOracle", ds);

} catch (Exception e) {System.out.println(e.getStackTrace());e.printStackTrace();return;}}// Main}// class OracleDataSourceRegisterJNDI

Creating the connection poolTo create a connection pool, you must create and register with JNDI a PooledConnectionDataSourceobject. The following Java code creates a PooledConnectionDataSource object and registers it with aJNDI naming service.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0184

Chapter 9: DataDirect tools

Page 185: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

To specify the driver DataSource object to be used by the connection pool to create pooled connections, setthe parameter of the DataSourceName method to the JNDI name of a registered driver DataSource object.For example, the following code sets the parameter of the DataSourceName method to the JNDI name of thedriver DataSource object created in "Creating a driver DataSource object."

The PooledConnectionDataSource class is provided by the DataDirect com.ddtek.pool package.See "PooledConnectionDataSource" for a description of the methods supported by thePooledConnectionDataSource class.

//************************************************************************// This code creates a data source and registers it to a JNDI naming service.// This data source uses the PooledConnectionDataSource// implementation provided by the DataDirect com.ddtek.pool package.//// This data source refers to a registered// DataDirect Connect Series for JDBC driver DataSource object.//// This data source registers its name as <jdbc/ConnectOracle>.//// NOTE: To connect using a data source, the driver needs to access a JNDI data// store to persist the data source information. To download the JNDI File// System Service Provider, go to://// http://www.oracle.com/technetwork/java/javasebusiness/downloads/// java-archive-downloads-java-plat-419418.html#7110-jndi-1.2.1-oth-JPR//// Make sure that the fscontext.jar and providerutil.jar files from the// download are on your classpath.//************************************************************************// From the DataDirect connection pooling package:import com.ddtek.pool.PooledConnectionDataSource;

import javax.sql.*;import java.sql.*;import javax.naming.*;import javax.naming.directory.*;import java.util.Hashtable;

public class PoolMgrDataSourceRegisterJNDI{

public static void main(String argv[]){

try {// Set up data source reference data for naming context:// ----------------------------------------------------// Create a pooling manager's class instance that implements// the interface DataSourcePooledConnectionDataSource ds = new PooledConnectionDataSource();

ds.setDescription("Oracle DataSource");

// Specify a registered driver DataSource object to be used// by this data source to create pooled connectionsds.setDataSourceName("jdbc/ConnectOracle");

// The pool manager will be initiated with 5 physical connectionsds.setInitialPoolSize(5);

// The pool maintenance thread will make sure that there are 5// physical connections availableds.setMinPoolSize(5);

// The pool maintenance thread will check that there are no more// than 10 physical connections availableds.setMaxPoolSize(10);

// The pool maintenance thread will wake up and check the pool// every 20 secondsds.setPropertyCycle(20);

185Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection Pool Manager

Page 186: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

// The pool maintenance thread will remove physical connections// that are inactive for more than 300 secondsds.setMaxIdleTime(300);

// Set tracing off because we choose not to see an output listing// of activities on a connectionds.setTracing(false);

// Set up environment for creating initial contextHashtable env = new Hashtable();env.put(Context.INITIAL_CONTEXT_FACTORY,

"com.sun.jndi.fscontext.RefFSContextFactory");env.put(Context.PROVIDER_URL, "file:c:\\JDBCDataSource");Context ctx = new InitialContext(env);

// Register this data source to the JNDI naming servicectx.bind("jdbc/SparkyOracle", ds);

catch (Exception e) {System.out.println(e);return;

}}

}

See alsoCreating a driver DataSource object on page 183PooledConnectionDataSource on page 191

Configuring the connection poolYou can configure attributes of a connection pool for optimal performance and scalability using the methodsprovided by the DataDirect Connection Pool Manager classes.

Some commonly set connection pool attributes include:

• Minimum pool size, which is the minimum number of connections that will be kept in the pool for each user

• Maximum pool size, which is the maximum number of connections in the pool for each user

• Initial pool size, which is the number of connections created for each user when the connection pool isinitialized

• Maximum idle time, which is the amount of time a pooled connection remains idle before it is removed fromthe connection pool

See alsoConnection Pool Manager interfaces on page 191

Configuring the maximum pool sizeYou set the maximum pool size using the PooledConnectionDataSource.setMaxPoolSize() method.For example, the following code sets the maximum pool size to 10:

ds.setMaxPoolSize(10);

You can control how the Pool Manager implements the maximum pool size by setting thePooledConnectionDataSource.setMaxPoolSizeBehavior() method:

Progress DataDirect for JDBC Drivers: Reference: Version 6.0186

Chapter 9: DataDirect tools

Page 187: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

• If setMaxPoolSizeBehavior(softCap), the number of active connections can exceed the maximumpool size, but the number of idle connections for each user in the pool cannot exceed this limit. If a userrequests a connection and an idle connection is unavailable, the Pool Manager creates a new connectionfor that user. When the connection is no longer needed, it is returned to the pool. If the number of idleconnections exceeds the maximum pool size, the Pool Manager closes idle connections to enforce the poolsize limit. This is the default behavior.

• If setMaxPoolSizeBehavior(hardCap), the total number of active and idle connections cannot exceedthe maximum pool size. Instead of creating a new connection for a connection request if an idle connectionis unavailable, the Pool Manager queues the connection request until a connection is available or the requesttimes out. This behavior is useful if your client or application server has memory limitations or if your databaseserver is licensed for only a certain number of connections.

See alsoPooledConnectionDataSource on page 191

Using Reauthentication with the Pool ManagerReauthentication, or the ability to switch a user on a connection, is a useful strategy for minimizing the numberof connections that are required in a connection pool. See "Using reauthentication" for an introduction toreauthentication.

If you are using the DataDirect Connection Pool Manager for connection pooling, you can enable reauthenticationin the Pool Manager. By default, reauthentication is disabled. To enable reauthentication, callsetReauthentication(enable) on the PooledConnectionDataSource. To disable reauthentication, callsetReauthentication(disable).

The Pool Manager implements the maximum pool size, minimum pool size, and initial pool size attributesdifferently depending on whether reauthentication is enabled. For example, in both of the following figures, themaximum pool size is set to a value of 10, the minimum pool size is set to 5, and the initial pool size is set to 5.

The following figure shows a connection pool that is configured to work without reauthentication while usingthe default behavior for maximum pool size. When User A requests a connection, the Pool Manager assignsan available connection associated with User A. Similarly, if User B requests a connection, the Pool Managerassigns an available connection associated with User B. If a connection is unavailable for a particular user,the Pool Manager creates a new connection for that user. Because the maximum pool size is set to 10, amaximum of 10 idle connections can exist for each user. In this case, the total number of idle connections is 20,or 10 idle connections for each user.

The Pool Manager implements the minimum pool size and initial pool size in a similar way. The Pool Managerinitially populates five connections for User A and five connections for User B, and ensures that, at a minimum,five idle connections are maintained in the pool for each user.

187Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection Pool Manager

Page 188: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

In contrast, the following figure shows a connection pool that is configured to work with reauthentication whileusing the default behavior for maximum pool size. The Pool Manager treats all connections as one group ofconnections. When User A requests a connection, the Pool Manager assigns an available connection associatedwith User A. Similarly, when User B requests a connection, the Pool Manager assigns an available connectionassociated with User B. If a connection is unavailable for a particular user, the Pool Manager assigns anyavailable connection to that user, switching the user associated with the connection to the new user. In thiscase, the maximum number of idle connections in the pool is 10, regardless of how many users are using theconnection pool.

The Pool Manager initially populates the pool with five connections and ensures that, at a minimum, five idleconnections are maintained in the pool for all users.

See alsoUsing Reauthentication on page 182

Connecting using a connection poolBecause an application uses connection pooling by referencing the JNDI name of a registeredPooledConnectionDataSource object, code changes are not required for an application to use connectionpooling.

The following example for the Oracle driver shows Java code that looks up and uses the JNDI-registeredPooledConnectionDataSource object created in "Creating the connection pool."

//********************************************************************// Test program to look up and use a JNDI-registered data source.//// To run the program, specify the JNDI lookup name for the// command-line argument, for example://// java TestDataSourceApp <jdbc/ConnectOracle>//********************************************************************import javax.sql.*;import java.sql.*;import javax.naming.*;import java.util.Hashtable;public class TestDataSourceApp{ public static void main(String argv[])

{String strJNDILookupName = "";// Get the JNDI lookup name for a data sourceint nArgv = argv.length;if (nArgv != 1) {

// User does not specify a JNDI lookup name for a data source,System.out.println(

"Please specify a JNDI name for your data source");

Progress DataDirect for JDBC Drivers: Reference: Version 6.0188

Chapter 9: DataDirect tools

Page 189: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System.exit(0);else {strJNDILookupName = argv[0];

}DataSource ds = null;Connection con = null;Context ctx = null;Hashtable env = null;long nStartTime, nStopTime, nElapsedTime;// Set up environment for creating InitialContext objectenv = new Hashtable();env.put(Context.INITIAL_CONTEXT_FACTORY,

"com.sun.jndi.fscontext.RefFSContextFactory");env.put(Context.PROVIDER_URL, "file:c:\\JDBCDataSource");try {

// Retrieve the DataSource object that is bound to the logical// lookup JNDI namectx = new InitialContext(env);ds = (DataSource) ctx.lookup(strJNDILookupName);catch (NamingException eName) {System.out.println("Error looking up " +

strJNDILookupName + ": " +eName);System.exit(0);

}int numOfTest = 4;int [] nCount = {100, 100, 1000, 3000};for (int i = 0; i < numOfTest; i ++) {

// Log the start timenStartTime = System.currentTimeMillis();for (int j = 1; j <= nCount[i]; j++) {

// Get Database Connectiontry {

con = ds.getConnection("scott", "tiger");// Do something with the connection// ...// Close Database Connectionif (con != null) con.close();} catch (SQLException eCon) {System.out.println("Error getting a connection: " + eCon);System.exit(0);} // try getConnection

} // for j loop// Log the end timenStopTime = System.currentTimeMillis();// Compute elapsed timenElapsedTime = nStopTime - nStartTime;System.out.println("Test number " + i + ": looping " +

nCount[i] + " times");System.out.println("Elapsed Time: " + nElapsedTime + "\n");

} // for i loop// All doneSystem.exit(0);// Main

} // TestDataSourceApp

Note: To use non-pooled connections, specify the JNDI name of a registered driver DataSource object as thecommand-line argument when you run the preceding application. For example, the following command specifiesthe driver DataSource object created in "Creating a driver DataSource object": java TestDataSourceAppjdbc/ConnectOracle.

See alsoCreating a driver DataSource object on page 183Creating the connection pool on page 184

189Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection Pool Manager

Page 190: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Closing the connection poolThe PooledConnectionDataSource.close() method can be used to explicitly close the connection poolwhile the application is running. For example, if changes are made to the pool configuration using a poolmanagement tool, the PooledConnectionDataSource.close()method can be used to force the connectionpool to close and re-create the pool using the new configuration values.

Checking the Pool Manager versionTo check the version of your DataDirect Connection Pool Manager, navigate to the directory containing theDataDirect Connection Pool Manager (install_dir/pool manager where install_dir is your productinstallation directory). At a command prompt, enter the command:

On Windows:java -classpath poolmgr_dir\pool.jar com.ddtek.pool.PoolManagerInfo

On UNIX:java -classpath poolmgr_dir/pool.jar com.ddtek.pool.PoolManagerInfo

where:

poolmgr_dir

is the directory containing the DataDirect Connection Pool Manager.

Alternatively, you can obtain the name and version of the DataDirect Connection Pool Manager programmaticallyby invoking the following static methods:

• com.ddtek.pool.PoolManagerInfo.getPoolManagerName()

• com.ddtek.pool.PoolManagerInfo.getPoolManagerVersion()

Enabling Pool Manager tracingYou can enable Pool Manager tracing by calling setTracing(true) on the PooledConnectionDataSourceconnection. To disable logging, call setTracing(false).

By default, the DataDirect Connection Pool Manager logs its pool activities to the standard output System.out.You can change where the Pool Manager trace information is written by calling the setLogWriter() methodon the PooledConnectionDataSource connection.

See "Troubleshooting connection pooling" for information about using a Pool Manager trace file fortroubleshooting.

See alsoTroubleshooting connection pooling on page 14

Progress DataDirect for JDBC Drivers: Reference: Version 6.0190

Chapter 9: DataDirect tools

Page 191: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Connection Pool Manager interfacesThis section describes the methods used by the DataDirect Connection Pool Manager interfaces:PooledConnectionDataSourceFactory, PooledConnectionDataSource, andConnectionPoolMonitor.

PooledConnectionDataSourceFactoryThePooledConnectionDataSourceFactory interface is used to create aPooledConnectionDataSourceobject from a Reference object that is stored in a naming or directory service. These methods are typicallyinvoked by a JNDI service provider; they are not usually invoked by a user application.

DescriptionPooledConnectionDataSourceFactory Methods

Creates a PooledConnectionDataSource object froma Reference object that is stored in a naming or directoryservice. This is an implementation of the method of thesame name defined in thejavax.naming.spi.ObjectFactory interface. Referto the Javadoc for this interface for a description.

static Object getObjectInstance(ObjectrefObj, Name name, Context nameCtx,Hashtable env)

PooledConnectionDataSourceThe PooledConnectionDataSource interface is used to create a PooledConnectionDataSource objectfor use with the DataDirect Connection Pool Manager.

DescriptionPooledConnectionDataSource Methods

Closes the connection pool. All physical connections in the pool areclosed. Any subsequent connection request re-initializes the connectionpool.

void close()

Obtains a physical connection from the connection pool.Connection getConnection()

Obtains a physical connection from the connection pool, where useris the user requesting the connection and password is the passwordfor the connection.

Connection getConnection(Stringuser, String password)

Returns the JNDI name that is used to look up the DataSource objectreferenced by this PooledConnectionDataSource.

String getDataSourceName()

Returns the description of this PooledConnectionDataSource.String getDescription()

Returns whether the Pool Manager is enabled for reauthentication. See"Using Reauthentication with the Pool Manager" for more information.

String getReauthentication()

Returns the value of the initial pool size, which is the number of physicalconnections created when the connection pool is initialized.

int getInitialPoolSize()

Returns the value of the login timeout, which is the time allowed for thedatabase login to be validated.

int getLoginTimeout()

191Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection Pool Manager

Page 192: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionPooledConnectionDataSource Methods

Returns the writer to which the Pool Manager sends trace informationabout its activities.

PrintWriter getLogWriter()

Returns the value of the maximum idle time, which is the time a physicalconnection can remain idle in the connection pool before it is removedfrom the connection pool.

int getMaxIdleTime()

Returns the value of the maximum pool size. See "Configuring themaximum pool size" for more information about how the Pool Managerimplements the maximum pool size. In addition, see "UsingReauthentication with the Pool Manager"

int getMaxPoolSize()

Returns the value of the maximum pool size behavior. See "Configuringthe maximum pool size" for more information about how the PoolManager implements the maximum pool size.

int getMaxPoolSizeBehavior()

Returns the value of the minimum pool size, which is the minimumnumber of idle connections to be kept in the pool.

int getMinPoolSize()

Returns the value of the property cycle, which specifies how often thepool maintenance thread wakes up and checks the connection pool.

int getPropertyCycle()

Obtains a javax.naming. Reference object for thisPooledConnectionDataSource. The Reference object contains allthe state information needed to recreate an instance of this data sourceusing the PooledConnectionDataSourceFactory object. Thismethod is typically called by a JNDI service provider when thisPooledConnectionDataSource is bound to a JNDI naming service.

Reference getReference()

Returns an array of Connection Pool Monitors, one for each connectionpool managed by the Pool Manager.

public staticConnectionPoolMonitor[ ]getMonitor()

Returns the name of the Connection Pool Monitor for the connectionpool specified by name. If a pool with the specified name cannot befound, this method returns null. The connection pool name has theform:

jndi_name-user_id

where:

jndi_name

is the name used for the JNDI lookup of the driverDataSource object from which the pooled connection wasobtained and

user_id

is the user ID used to establish the connections contained inthe pool.

public static ConnectionPoolMonitorgetMonitor(String name)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0192

Chapter 9: DataDirect tools

Page 193: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionPooledConnectionDataSource Methods

Determines whether tracing is enabled. If enabled, tracing informationis sent to the PrintWriter that is passed to the setLogWriter()method or the standard output System.out if the setLogWriter()method is not called.

boolean isTracing()

Sets the JNDI name, which is used to look up the driver DataSourceobject referenced by this PooledConnectionDataSource. The driverDataSource object bound to this PooledConnectionDataSource,specified by dataSourceName, is not persisted. Any changes madeto the PooledConnectionDataSource bound to the specified driverDataSource object affect this PooledConnectionDataSource.

void setDataSourceName(StringdataSourceName)

Sets the JNDI name associated with thisPooledConnectionDataSource, specified by dataSourceName,and the driver DataSource object, specified by dataSource,referenced by this PooledConnectionDataSource.

The driver DataSource object, specified by dataSource, is persistedwith this PooledConnectionDataSource. Changes made to thespecified driver DataSource object after thisPooledConnectionDataSource is persisted do not affect thisPooledConnectionDataSource.

void setDataSourceName(StringdataSourceName,ConnectionPoolDataSourcedataSource)

Sets the JNDI name, specified by dataSourceName, and context,specified by ctx, to be used to look up the driver DataSourcereferenced by this PooledConnectionDataSource.

The JNDI name, specified by dataSourceName, and context, specifiedby ctx, are used to look up a driver DataSource object. The driverDataSource object is persisted with thisPooledConnectionDataSource. Changes made to the driverDataSource after this PooledConnectionDataSource is persisteddo not affect this PooledConnectionDataSource.

void setDataSourceName(StringdataSourceName, Context ctx)

Sets the description of the PooledConnectionDataSource, wheredescription is the description.

void setDescription(Stringdescription)

Sets the value of the initial pool size, which is the number of connectionscreated when the connection pool is initialized.

void setInitialPoolSize(intinitialPoolSize)

Sets the value of the login timeout, where i is the login timeout, whichis the time allowed for the database login to be validated.

void setLoginTimeout(int i)

If set to true, the timestamp is logged when DataDirect Spy loggingis enabled. If set to false, the timestamp is not logged.

void setLogTimestamp(boolean value)

If set to true, the thread name is logged when DataDirect Spy loggingis enabled. If set to false, the thread name is not logged.

void setLogTname(boolean value)

Sets the writer, where printWriter is the writer to which the streamwill be printed.

void setLogWriter(PrintWriterprintWriter)

193Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection Pool Manager

Page 194: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionPooledConnectionDataSource Methods

Sets the value in seconds of the maximum idle time, which is the timea connection can remain unused in the connection pool before it isclosed and removed from the pool. Zero (0) indicates no limit.

void setMaxIdleTime(intmaxIdleTime)

Sets the value of the maximum pool size, which is the maximum numberof connections for each user allowed in the pool. See "Configuring themaximum pool size" for more information about how the Pool Managerimplements the maximum pool size.

void setMaxPoolSize(intmaxPoolSize)

Sets the value of the maximum pool size behavior, which is eithersoftCap or hardCap.

If setMaxPoolSizeBehavior(softCap), the number of activeconnections may exceed the maximum pool size, but the number ofidle connections in the connection pool for each user cannot exceedthis limit. If a user requests a connection and an idle connection isunavailable, the Pool Manager creates a new connection for that user.When the connection is no longer needed, it is returned to the pool. Ifthe number of idle connections exceeds the maximum pool size, thePool Manager closes idle connections to enforce the maximum poolsize limit. This is the default behavior.

If setMaxPoolSizeBehavior(hardCap), the total number of activeand idle connections cannot exceed the maximum pool size. Insteadof creating a new connection for a connection request if an idleconnection is unavailable, the Pool Manager queues the connectionrequest until a connection is available or the request times out. Thisbehavior is useful if your database server has memory limitations or islicensed for only a specific number of connections.The timeout is setusing the LoginTimeout connection property. If the connection requesttimes out, the driver throws an exception.

See "Configuring the maximum pool size" for more information abouthow the Pool Manager implements the maximum pool size.

void setMaxPoolSizeBehavior(Stringvalue)

Sets the value of the minimum pool size, which is the minimum numberof idle connections to be kept in the connection pool.

void setMinPoolSize(intminPoolSize)

Sets the value in seconds of the property cycle, which specifies howoften the pool maintenance thread wakes up and checks the connectionpool.

void setPropertyCycle(intpropertyCycle)

Enables and disables reauthentication for the Pool Manager. To enablereauthentication, use setReauthentication(enable). To disablereauthentication, use setReauthentication(disable). See "UsingReauthentication with the Pool Manager" for more information.

void setReauthentication(Stringvalue)

Enables or disables tracing. If set to true, tracing is enabled; if false,it is disabled. If enabled, tracing information is sent to the PrintWriterthat is passed to the setLogWriter()method or the standard outputSystem.out if the setLogWriter() method is not called.

void setTracing(boolean value)

Progress DataDirect for JDBC Drivers: Reference: Version 6.0194

Chapter 9: DataDirect tools

Page 195: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

See alsoUsing Reauthentication with the Pool Manager on page 187Configuring the maximum pool size on page 186

ConnectionPoolMonitorThe ConnectionPoolMonitor interface is used to return information that is useful for monitoring the statusof your connection pools.

DescriptionConnectionPoolMonitor Methods

Returns the name of the connection pool associated with the monitor.The connection pool name has the form:

jndi_name-user_id

where:

jndi_name

is the name used for the JNDI lookup of thePooledConnectionDataSource object from which thepooled connection was obtained

user_id

is the user ID used to establish the connections contained inthe pool.

String getName()

Returns the number of connections that have been checked out of thepool and are currently in use.

int getNumActive()

Returns the number of connections that are idle in the pool (availableconnections).

int getNumAvailable()

Returns the initial size of the connection pool (the number of availableconnections in the pool when the pool was first created).

int getInitialPoolSize()

Returns the maximum number of available connection in the connectionpool. If the number of available connections exceeds this value, thePool Manager removes one or multiple available connections from thepool.

int getMaxPoolSize()

Returns the minimum number of available connections in the connectionpool. When the number of available connections is lower than thisvalue, the Pool Manager creates additional connections and makesthem available.

int getMinPoolSize()

Returns the current size of the connection pool, which is the total ofactive connections and available connections.

int getPoolSize()

195Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Connection Pool Manager

Page 196: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Statement Pool MonitorThe driver supports the DataDirect Statement Pool Monitor. You can use the Statement Pool Monitor to loadstatements into and remove statements from the statement pool as well as generate information to help youtroubleshoot statement pooling performance. The Statement Pool Monitor is an integrated component of thedriver, and you can manage statement pooling directly with DataDirect-specific methods. In addition, theStatement Pool Monitor can be enabled as a Java Management Extensions (JMX) MBean. When enabled asa JMX MBean, the Statement Pool Monitor can be used to manage statement pooling with standard JMX APIcalls, and it can easily be used by JMX-compliant tools, such as JConsole.

Using DataDirect-specific methods to access the Statement PoolMonitor

To access the Statement Pool Monitor using DataDirect-specific methods, you should first enable statementpooling. You can enable statement pooling by setting the MaxPooledStatements connection property to a valuegreater than zero (0). For more information, refer to "MaxPooledStatements" in the user's guide for your driver.

The ExtConnection.getStatementPoolMonitor() method returns an ExtStatementPoolMonitor object for thestatement pool associated with the connection. This method is provided by the ExtConnection interface in thecom.ddtek.jdbc.extensions package. If the connection does not have a statement pool, the method returnsnull.

Once you have an ExtStatementPoolMonitor object, you can use the poolEntries() method of theExtStatementPoolMonitorMBean interface implemented by the ExtStatementPoolMonitor to return a list ofstatements in the statement pool as an array.

Using the poolEntries methodUsing the poolEntries()method, your application can return all statements in the pool or filter the list basedon the following criteria:

• Statement type (prepared statement or callable statement)

• Result set type (forward only, scroll insensitive, or scroll sensitive)

• Concurrency type of the result set (read only and updateable)

The following table lists the parameters and the valid values supported by the poolEntries() method.

Table 11: poolEntries() Parameters

DescriptionValueParameter

Returns only prepared statementsExtStatementPoolMonitor.TYPE_PREPARED_STATEMENTstatementType

Returns only callable statementsExtStatementPoolMonitor.TYPE_CALLABLE_STATEMENT

Returns all statements regardlessof statement type

-1

Progress DataDirect for JDBC Drivers: Reference: Version 6.0196

Chapter 9: DataDirect tools

Page 197: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionValueParameter

Returns only statements withforward-only result sets

ResultSet.TYPE_FORWARD_ONLYresultSetType

Returns only statements with scrollinsensitive result sets

ResultSet.TYPE_SCROLL_INSENSITIVE

Returns only statements with scrollsensitive result sets

ResultSet.TYPE_SCROLL_SENSITIVE

Returns statements regardless ofresult set type

-1

Returns only statements with aread-only result set concurrency

ResultSet.CONCUR_READ_ONLYresultSetConcurrency

Returns only statements with anupdateable result set concurrency

ResultSet.CONCUR_UPDATABLE

Returns statements regardless ofresult set concurrency type

-1

The result of the poolEntries() method is an array that contains a String entry for each statement in thestatement pool using the format:

SQL_TEXT=[SQL_text];STATEMENT_TYPE=TYPE_PREPARED_STATEMENT|TYPE_CALLABLE_STATEMENT;RESULTSET_TYPE=TYPE_FORWARD_ONLY|TYPE_SCROLL_INSENSITIVE|TYPE_SCROLL_SENSITIVE;RESULTSET_CONCURRENCY=CONCUR_READ_ONLY|CONCUR_UPDATABLE;AUTOGENERATEDKEYSREQUESTED=true|false;REQUESTEDKEYCOLUMNS=comma-separated_list

where SQL_text is the SQL text of the statement and comma-separated_list is a list of column namesthat will be returned as generated keys.

For example:

SQL_TEXT=[INSERT INTO emp(id, name) VALUES(99, ?)];STATEMENT_TYPE=Prepared Statement;RESULTSET_TYPE=Forward Only;RESULTSET_CONCURRENCY=ReadOnly;AUTOGENERATEDKEYSREQUESTED=false;REQUESTEDKEYCOLUMNS=id,name

Generating a list of statements in the statement poolThe following code shows how to return an ExtStatementPoolMonitor object using a connection and how togenerate a list of statements in the statement pool associated with the connection.

Note: The following example is drawn from a Microsoft SQL Server use case, but applies to most ProgressDataDirect drivers.

private void run(String[] args) {Connection con = null;PreparedStatement prepStmt = null;String sql = null;

197Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Statement Pool Monitor

Page 198: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

try {// Create the connection and enable statement poolingClass.forName("com.ddtek.jdbc.sqlserver.SQLServerDriver");con = DriverManager.getConnection(

"jdbc:datadirect:sqlserver://MyServer:1433;" +"RegisterStatementPoolMonitorMBean=true","maxPooledStatements=10","test", "test");

// Prepare a couple of statementssql = "INSERT INTO employees (id, name) VALUES(?, ?)";prepStmt = con.prepareStatement(sql);prepStmt.close();sql = "SELECT name FROM employees WHERE id = ?";prepStmt = con.prepareStatement(sql);prepStmt.close();ExtStatementPoolMonitor monitor =

((ExtConnection) con).getStatementPoolMonitor();System.out.println("Statement Pool - " + monitor.getName());System.out.println("Max Size: " + monitor.getMaxSize());System.out.println("Current Size: " + monitor.getCurrentSize());System.out.println("Hit Count: " + monitor.getHitCount());System.out.println("Miss Count: " + monitor.getMissCount());System.out.println("Statements:");ArrayList statements = monitor.poolEntries(-1, -1, -1);Iterator itr = statements.iterator();while (itr.hasNext()) {

String entry = (String)itr.next();System.out.println(entry);

}}catch (Throwable except) {

System.out.println("ERROR: " + except);}finally {

if (con != null) {try {

con.close();}catch (SQLException except) {}}

}}

In the previous code example, the PoolEntries() method returns all statements in the statement pool regardlessof statement type, result set cursor type, and concurrency type by specifying the value -1 for each parameteras shown in the following code:

ArrayList statements = monitor.poolEntries(-1, -1, -1);

We could have easily filtered the list of statements to return only prepared statements that have a forward-onlyresult set with a concurrency type of updateable using the following code:

ArrayList statements = monitor.poolEntries(ExtStatementPoolMonitor.TYPE_PREPARED_STATEMENT,ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_UPDATABLE);

Using JMX to access the Statement Pool MonitorYour application cannot access the Statement Pool Monitor using JMX unless the driver registers the StatementPool Monitor as a JMX MBean. To enable the Statement Pool Monitor as an MBean, statement pooling mustbe enabled with the MaxPooledStatements connection property, and the Statement Pool Monitor MBean mustbe registered using the RegisterStatementPoolMonitorMBean connection property.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0198

Chapter 9: DataDirect tools

Page 199: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

When the Statement Pool Monitor is enabled, the driver registers a single MBean for each statement pool. Theregistered MBean name has the following form, where monitor_name is the string returned by theExtStatementPoolMonitor.getName() method:

com.ddtek.jdbc.type=StatementPoolMonitor,name=monitor_name

Note: Registering the MBean exports a reference to the Statement Pool Monitor. The exported reference canprevent garbage collection on connections if the connections are not properly closed. When garbage collectiondoes not take place on these connections, out of memory errors can occur.

To return information about the statement pool, retrieve the names of all MBeans that are registered with thecom.ddtek.jdbc domain and search through the list for the StatementPoolMonitor type attribute. The followingcode shows how to use the standard JMX API calls to return the state of all active statement pools in the JVM:

private void run(String[] args) {if (args.length < 2) {

System.out.println("Not enough arguments supplied");System.out.println("Usage: " + "ShowStatementPoolInfo hostname port");

}String hostname = args[0];String port = args[1];JMXServiceURL url = null;JMXConnector connector = null;MBeanServerConnection server = null;try {

url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://" +hostname +":" + port + "/jmxrmi");

connector = JMXConnectorFactory.connect(url);server = connector.getMBeanServerConnection();System.out.println("Connected to JMX MBean Server at " +

args[0] + ":" + args[1]);// Get the MBeans that have been registered with the// com.ddtek.jdbc domain.ObjectName ddMBeans = new ObjectName("com.ddtek.jdbc:*");Set<ObjectName> mbeans = server.queryNames(ddMBeans, null);// For each statement pool monitor MBean, display statistics and// contents of the statement pool monitored by that MBeanfor (ObjectName name: mbeans) {

if (name.getDomain().equals("com.ddtek.jdbc") &&name.getKeyProperty("type")

.equals("StatementPoolMonitor")) {System.out.println("Statement Pool - " +

server.getAttribute(name, "Name"));System.out.println("Max Size: " +

server.getAttribute(name, "MaxSize"));System.out.println("Current Size: " +

server.getAttribute(name, "CurrentSize"));System.out.println("Hit Count: " +

server.getAttribute(name, "HitCount"));System.out.println("Miss Count: " +

server.getAttribute(name, "MissCount"));System.out.println("Statements:");Object[] params = new Object[3];params[0] = new Integer(-1);params[1] = new Integer(-1);params[2] = new Integer(-1);String[] types = new String[3];types[0] = "int";types[1] = "int";types[2] = "int";ArrayList<String>statements = (ArrayList<String>)

server.invoke(name,"poolEntries",params,types);

for (String stmt : statements) {int index = stmt.indexOf(";");

199Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Statement Pool Monitor

Page 200: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

System.out.println(" " + stmt.substring(0, index));}

}}

}catch (Throwable except) {

System.out.println("ERROR: " + except);}

}

Importing statements into a statement poolWhen importing statements into a statement pool, for each statement entry in the export file, a statement isadded to the statement pool provided a statement with the same SQL text and statement attributes does notalready exist in the statement pool. Existing statements in the pool that correspond to a statement entry arekept in the pool unless the addition of new statements causes the number of statements to exceed the maximumpool size. In this case, the driver closes and discards some statements until the pool size is shrunk to themaximum pool size.

For example, if the maximum number of statements allowed for a statement pool is 10 and the number ofstatements to be imported is 20, only the last 10 imported statements are placed in the statement pool. Theother statements are created, closed, and discarded. Importing more statements than the maximum numberof statements allowed in the statement pool can negatively affect performance because the driver unnecessarilycreates some statements that are never placed in the pool.

To import statements into a statement pool:

1. Create a statement pool export file. See "Statement pool export file example" for an example of a statementpool export file.

Note: The easiest way to create a statement pool export file is to generate an export file from the statementpool associated with the connection as described in "Generating a statement pool export file."

2. Edit the export file to contain statements to be added to the statement pool.

3. Import the contents of the export file to the statement pool using either of the following methods to specifythe path and file name of the export file:

• Use the ImportStatementPool property. For example:

jdbc:datadirect:sqlserver://MyServer:1433;User=User123;Password=secret;DatabaseName=MyDB;ImportStatementPool=C:\\statement_pooling\\stmt_export.txt

• Use the importStatements() method of the ExtStatementPoolMonitorMBean interface. For example:

ExtStatementPoolMonitor monitor =((ExtConnection)

con).getStatementPoolMonitor().importStatements("C:\\statement_pooling\\stmt_export.txt");

See alsoStatement pool export file example on page 19Generating a statement pool export file on page 201

Progress DataDirect for JDBC Drivers: Reference: Version 6.0200

Chapter 9: DataDirect tools

Page 201: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Clearing all statements in a statement poolTo close and discard all statements in a statement pool, use the emptyPool() method of theExtStatementPoolMonitorMBean interface. For example:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().emptyPool();

Freezing and unfreezing the statement poolFreezing the statement pool restricts the statements in the pool to those that were in the pool at the time thepool was frozen. For example, perhaps you have a core set of statements that you do not want replaced bynew statements when your core statements are closed. You can freeze the pool using the setFrozen()method:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().setFrozen(true);

Similarly, you can use the same method to unfreeze the statement pool:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().setFrozen(false);

When the statement pool is frozen, your application can still clear the pool and import statements into the pool.In addition, you can use the Statement.setPoolable() method to add or remove single statements fromthe pool regardless of the pool’s frozen state, assuming the pool is not full. If the pool is frozen and the numberof statements in the pool is the maximum, no statements can be added to the pool.

To determine if a pool is frozen, use the isFrozen() method.

Generating a statement pool export fileYou may want to generate an export file in the following circumstances:

• To import statements to the statement pool, you can create an export file, edit its contents, and import thefile into the statement pool to import statements to the pool.

• To examine the characteristics of the statements in the statement pool to help you troubleshoot statementpool performance.

To generate a statement pool export file, use the exportStatements() method of theExtStatementPoolMonitorMBean interface. For example, the following code exports the contents of thestatement pool associated with the connection to a file named stmt_export.txt:

ExtStatementPoolMonitor monitor =((ExtConnection) con).getStatementPoolMonitor().exportStatements("stmt_export.txt");

See the "Statement pool export file example" topic for information on interpreting the contents of an export file.

See alsoStatement pool export file example on page 19

201Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Statement Pool Monitor

Page 202: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DataDirect Statement Pool Monitor interfaces and classesThis section describes the methods used by the DataDirect Statement Pool Monitor interfaces and classes.

ExtStatementPoolMonitor classThis class is used to control and monitor a single statement pool. This class implements theExtStatementPoolMonitorMBean interface.

ExtStatementPoolMonitorMBean interface

DescriptionExtStatementPoolMonitorMBean Methods

Returns the name of a Statement Pool Monitor instanceassociated with the connection. The name is comprised ofthe name of the driver that established the connection, andthe name and port of the server to which the StatementPool Monitor is connected, and the MBean ID of theconnection.

String getName()

Returns the total number of statements cached in thestatement pool.

int getCurrentSize()

Returns the hit count for the statement pool. The hit countis the number of times a lookup is performed for a statementthat results in a cache hit. A cache hit occurs when theStatement Pool Monitor successfully finds a statement inthe pool with the same SQL text, statement type, result settype, result set concurrency, and requested generated keyinformation.

This method is useful to determine if your workload is usingthe statement pool effectively. For example, if the hit countis low, the statement pool is probably not being used to itsbest advantage.

long getHitCount()

Returns the miss count for the statement pool. The misscount is the number of times a lookup is performed for astatement that fails to result in a cache hit. A cache hitoccurs when the Statement Pool Monitor successfully findsa statement in the pool with the same SQL text, statementtype, result set type, result set concurrency, and requestedgenerated key information.

This method is useful to determine if your workload is usingthe statement pool effectively. For example, if the misscount is high, the statement pool is probably not being usedto its best advantage.

long getMissCount()

Returns the maximum number of statements that can bestored in the statement pool.

int getMaxSize()

Progress DataDirect for JDBC Drivers: Reference: Version 6.0202

Chapter 9: DataDirect tools

Page 203: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionExtStatementPoolMonitorMBean Methods

Changes the maximum number of statements that can bestored in the statement pool to the specified value.

int setMaxSize(int value)

Closes and discards all the statements in the statementpool.

void emptyPool()

Resets the hit and miss counts to zero (0). See longgetHitCount() and long getMissCount() for moreinformation.

void resetCounts()

Returns a list of statements in the pool. The list is an arraythat contains a String entry for each statement in thestatement pool.

ArrayList poolEntries(int statementType,int resultSetType, int resultSetConcurrency)

Exports statements from the statement pool into thespecified file. The file format contains an entry for eachstatement in the statement pool.

void exportStatements(File file_object)

Exports statements from statement pool into the specifiedfile. The file format contains an entry for each statement inthe statement pool.

void exportStatements(String file_name)

Imports statements from the specified File object into thestatement pool.

void importStatements(File file_object)

Imports statements from the specified file into the statementpool.

void importStatements(String file_name)

Returns whether the state of the statement pool is frozen.When the statement pool is frozen, the statements that canbe stored in the pool are restricted to those that were in thepool at the time the pool was frozen. Freezing a pool isuseful if you have a core set of statements that you do notwant replaced by other statements when the corestatements are closed.

boolean isFrozen()

setFrozen(true) freezes the statement pool.setFrozen(false) unfreezes the statement pool. Whenthe statement pool is frozen, the statements that can bestored in the pool are restricted to those that were in thepool at the time the pool was frozen. Freezing a pool isuseful if you have a core set of statements that you do notwant replaced by other statements when the corestatements are closed.

void setFrozen(boolean)

203Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Statement Pool Monitor

Page 204: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

• Logging is consistent, regardless of which DataDirect for JDBC driver is used.

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

• Logging works with all DataDirect for JDBC drivers.

• 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 11

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 JDBC 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. See "DataDirect Spy attributes" for a list ofsupported attributes.

Windows exampleThe following example uses the JDBC Driver Manager to connect to Oracle while enabling DataDirect Spy:

Class.forName("com.ddtek.jdbc.oracle.OracleDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:oracle://Server3:1521;SID=ORCL;

Progress DataDirect for JDBC Drivers: Reference: Version 6.0204

Chapter 9: DataDirect tools

Page 205: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

User=User123;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 exampleThe following code example uses the JDBC Driver Manager to connect to Oracle while enabling DataDirectSpy:

Class.forName("com.ddtek.jdbc.oracle.OracleDriver");Connection conn = DriverManager.getConnection

("jdbc:datadirect:oracle://server:1521;SID=ORCL;User=User123;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 206

Using JDBC data sourcesYou can use DataDirect Spy to track JDBC calls made by a running application with either of these features:

• JNDI for Naming Databases

• Connection Pooling

• Java Transaction API (JTA)

Note: JTA is currently only supported by the following 6.0 drivers: Oracle and SQL Server drivers.

You can use DataDirect Spy to track JDBC calls made by a running application with any of these features. Thecom.ddtek.jdbcx.Oracle.OracleDataSource class supports setting a semi-colon separated list ofDataDirect Spy attributes. For more information about configuring data sources, refer to the user’s guide foryour driver.

Windows exampleThe following example creates a JDBC data source for the Oracle driver, which enables DataDirect Spy.

OracleDataSource sds = new OracleDataSource();sds.setDescription("My Oracle Datasource");

205Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Tracking JDBC calls with DataDirect Spy

Page 206: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

sds.setServerName("Server3");sds.setPortNumber(1521);sds.setUser("User123");sds.setPassword("secret");sds.setSID("ORCL");sds.setSpyAttributes("log=(file)C:\\temp\\spy.log;logIS=yes;logTName=yes");Connection conn=sds.getConnection;...

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 exampleThe following example creates a JDBC data source for the Oracle driver, which enables DataDirect Spy.

OracleDataSource mds = new OracleDataSource();mds.setDescription("My Oracle Datasource");mds.setServerName("Server3");mds.setPortNumber(1521);mds.setUser("User123");mds.setPassword("secret");mds.setSID("ORCL");mds.setSpyAttributes("log=(file)/tmp/spy.log;logIS=yes;logTName=yes");Connection conn=mds.getConnection;...

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). In addition to regular JDBC activity, the spy.log file also logs activity onInputStream and Reader objects (logIS=yes). It also includes the name of the current thread(logTName=yes).

See alsoDataDirect Spy attributes on page 206

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

Progress DataDirect for JDBC Drivers: Reference: Version 6.0206

Chapter 9: DataDirect tools

Page 207: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DescriptionAttribute

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 specifiedon multiple connections, the following logs are created:

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

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

log=(filePrefix)file_prefix

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

Specifies whether DataDirect Spy logs activity on InputStream and Readerobjects.

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

The default is no.

logIS={yes | no |nosingleread}

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

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

The default is no.

logTName={yes | no}

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

timestamp={yes | no}

207Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Tracking JDBC calls with DataDirect Spy

Page 208: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Progress DataDirect for JDBC Drivers: Reference: Version 6.0208

Chapter 9: DataDirect tools

Page 209: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

209Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Page 210: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

Progress DataDirect for JDBC Drivers: Reference: Version 6.0210

Glossary

Page 211: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

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.

211Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Glossary

Page 212: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:
Page 213: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Index

Aabout

extended connection failover 27select failover 28

accessing the DataDirect Statement Pool Monitor 198alternate database servers

about 26guidelines for 29

applicationDataDirect Spy, using to troubleshoot 11troubleshooting problems 11

Array interface, methods 40auto generated keys

example, retrieving 143performance optimization 143

Autocommit mode 144

Bbatch inserts and updates

batch execution on a prepared statement withDataDirect Test 160using instead of prepared statements 141

Blob interface, methods 41Blobs

retrieving with DataDirect Test 175

CCallableStatement interface, methods 42changing the maximum pool size behavior 186clearing statements in the statement pool 201client information

about 31how databases store 32maximum length of a value, determining 37metadata, returning 37returning 36storing 32

client load balancing, about 29Clob interface, methods 54Clobs

retrieving with DataDirect Test 175closing the connection pool 190committing transactions 144components, Java logging 20connecting

DataDirect Testusing a data source 150using driver/database selection 151

connecting (continued)using connection pool 188using DataDirect Test 149

connection failoverabout 25–26connection retry 26load balancing and 29

Connection interface, methods 55connection management 144Connection object

ExtLogControl interface 12managing connections 144transaction model 145

Connection Pool Managerversion information 190

connection poolingconfiguring 186connection pool

closing 190connecting using 188

DataDirect Connection Pool Manager trace file 14performance optimization 144using 180

connection propertiesSpyAttributes 204, 206

connection retry, about 26ConnectionEventListener interface, methods 61ConnectionPoolDataSource interface, methods 61ConnectionPoolMonitor

interface 195copyrightCounter data type 132cursors

choosing 142

DData Definition Language (DDL) 132data sources

connection pooling 180creating 183–184specifying SpyAttributes 204

data types, choosing for performance 139database

table characteristics, using dummy query todetermine 137

database metadataretrieving with DataDirect Test 156

DatabaseMetaData interface 99DatabaseMetaData interface, methods 61

213Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Index

Page 214: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

DataDirect Connection Pool Managertrace file 14tracing, enabling 14, 190using reauthentication with 187version information 190

DataDirect Spyattributes 206enabling 204logging

generating a log 11log example 12turning on and off 12

overview 204setEnableLogging() method 12

DataDirect Spy, enabling 205DataDirect Statement Pool Monitor

accessingusing the JMX API 198

classes and interfaces 202DataDirect Test

batch execution 160configuring 148connecting with 149database metadata, retrieving 156deleting rows 166executing

Select statement 152executing prepared statement 153inserting rows 166, 169LOB support 175parameter metadata, returning 162result set, scrolling through 158savepoints, establishing 163starting 149tutorial 147–148updatable result sets 166updating rows 166, 172using 147

DataDirect tools 147DataSource

connection pooling 183–184DataSource interface, methods 70date

escape sequence 114date and time functions 127DDBulkLoad interface, methods 100DDL (Data Definition Language) 132deleting rows

with DataDirect Test 166Driver interface, methods 71DriverManager

specifying SpyAttributes 204dummy query, using to determine table characteristics137

Eescape sequences

date, time, and timestamp 114LIKE escape character for wildcards 132native 132outer join 130refresh 132

exampleDataDirect Spy

log 12outer join escape sequence 130reauthentication 182scalar functions 114

export file for statement poolexample 19generating 201

ExtConnection interface, methods 107ExtDatabaseMetaData interface, methods 112extended connection failover 27extensions package

datadirect.jdbc.extensions package 97ExtLogControl class, methods 112ExtStatementPoolMonitor class 202ExtStatementPoolMonitorMBean interface 202

Ffailover

about 25forward-only cursor

performance implications 142freezing the statement pool 201

GgetBestRowIdentifier() method 145getBlob() method 138getClob() method 138getObject() method 142guidelines for primary and alternate servers 29

Hhelp, online 23

Iimporting statements into the statement pool 200initial pool size 186InputStream object, DataDirect Spy 205insensitive cursors

performance implications 142inserting rows

with DataDirect Test 169

Progress DataDirect for JDBC Drivers: Reference: Version 6.0214

Index

Page 215: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Interfaces, JDBC 39

JJava logging

components 20JDBC API logger 20SQL engine logger 21using 19Web service adapter logger 21

Java logging components 20JDBC

interfaces 39JVM compatibility 39SQL escape sequences 113versions supported 39

JDBC API logger 20JDBC data source, specifying SpyAttributes 205JDBC Driver Manager

specifying SpyAttribute 204JDBC extensions

introduction 97wrapper methods to access 98

JTA supporttransaction

model, choosing for performance 145JTA transaction support

managing commits 144JVM

JDBC compatibility 39properties file 22

KKerberos authentication

using with reauthentication 182keyset-driven cursors, performance implications 142

LLIKE escape character for wildcards escape sequence132literals

arguments, using parameter markers 140date 114time 114timestamp 114

load balancingabout 29

LOBs supportexecuting a query with DataDirect Test 175

log for DataDirect Spy, using 11logging

JVM properties file 22with DataDirect Spy 204

logging, Javacomponents 20JDBC API logger 20SQL engine logger 21using 19Web service adapter logger 21

long data, retrieving and performance 138lost connections

extended connection failover 27recovering work in progress 28select failover 28

Mmaximum idle time 186maximum pool size 186maximum pool size behavior 186MBean name, registering 198metadata

JDBC extensions 99metadata about client information 37metadata methods, minimizing use of 136methods

Array interface 40Blob interface 41CallableStatement interface 42Clob interface 54Connection interface 55ConnectionEventListener interface 61ConnectionPoolDataSource interface 61DatabaseMetaData interface 61DataSource interface 70DDBulkLoad interface 100Driver interface 71ExtConnection interface 107ExtDatabaseMetaData interface 112ExtLogControl class 112ParameterMetaData interface 71PooledConnection interface 72PreparedStatement interface 73Ref interface 78ResultSet interface 78ResultSetMetaData interface 89RowSet interface 90SavePoint interface 90Statement interface 90StatementEventListener interface 95Struct interface 95XAConnection interface 95XADataSource interface 95XAResource interface 96

Microsoft Cluster Server (MSCS) 29minimum pool size 186

215Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Index

Page 216: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Nnative escape sequence 132numeric functions 126

Oobject

ConnectionExtLogControl interface 12managing connections 144transaction model 145

Long (DB2) 81PooledConnectionDataSource

connecting with 188PreparedStatement

using Statement object instead of 140ResultSet

database metadata 136generating 136updating data 145

Statementusing instead of PreparedStatement object 140using multiple 144

using addBatch() instead of PreparedStatement 141Oracle

Real Application Clusters (RAC) 29outer join escape sequence, example 130

Pparameter markers, using as arguments to storedprocedures 140parameter metadata

returning with DataDirect Test 162ParameterMetaData interface, methods 71performance optimization

auto generated keys, retrieving 143batches, using instead of prepared statements 141commits, managing 144connection

management 144pooling 144

database metadata methods 136designing JDBC applications 143get methods, using effectively 142getBestRowIdentifier() 145result sets, retrieving 139retrieving long data 138scrollable cursors 139selecting JDBC objects and methods 140transaction model, choosing 145update methods of the ResultSet object 145updating data 145

PooledConnection interface, methods 72

PooledConnectionDataSourceinterface 191

PooledConnectionDataSource objectconnecting with 188creating 183–184, 191

PooledConnectionDataSourceFactoryinterface 191

poolEntries() method 196prepared statement pooling, performance optimization144prepared statement, executing with DataDirect Test 153prepared statements

using batches instead of 141PreparedStatement interface, methods 73PreparedStatement object

performanceimplications of using Statement object instead140of prepared statement pool 144

prepared statement pooling 144using Statement object instead of 140

primary serverguidelines for 29

properties file for Java loggingdriver 22

RReader object, DataDirect Spy 205reauthentication

about 182enabling in DataDirect Connection Pool Manager187example, performing on a connection explicitly 182Kerberos, using with 182performing explicitly 182support 182using 182using with the DataDirect Connection Pool Manager187

Ref interface, methods 78Reference object

creating PooledConnectionDataSource object 191refresh escape sequence 132registering MBean name 198result sets

deleting rows with DataDirect Test 166inserting rows with DataDirect Test 166scrolling through a result set with DataDirect Test158updating rows with DataDirect Test 166

result sets, scrollableperformance optimization 139

ResultSet interface, methods 78ResultSet object

database metadata 136

Progress DataDirect for JDBC Drivers: Reference: Version 6.0216

Index

Page 217: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

ResultSet object (continued)generating 136updating data 145

ResultSetMetaData interface, methods 89returning client information 36RowSet interface, methods 90

SSavePoint interface, methods 90savepoints

establishing with DataDirect Test 163scalar functions 114search patterns, avoiding 137select failover 28Select statement

executing with DataDirect Test 152sensitive cursors

performance implications 142server-side RPCs 140setEnableLogging(), using to turn on and off DataDirectSpy logging 12SpyAttributes 204, 206SQL engine logger 21SQL escape sequences

date, time, and timestamp 114LIKE escape character for wildcards 132native 132outer join 130refresh 132scalar functions 114

SQL ServerMicrosoft Cluster Server (MSCS) 29

SQL statementsUpdate 132

Statement interface, methods 90Statement object

Connection object association 144using instead of PreparedStatement object 140using multiple 144when to use 140

statement poolclearing statements 201export file, generating 201freezing and unfreezing 201importing statements to 200

statement pool export fileexample 19generating 18

Statement Pool Monitoraccessing with DataDirect-specific methods 196classes and interfaces 202poolEntries() method 196

statement poolingstatement pool export file 18

statement pooling (continued)troubleshooting problems 18

StatementEventListener interface, methods 95stored procedures

parameter markers as arguments, using 140storing client information 32string functions 124Struct interface, methods 95support

online help 23technical support 23

system functions 129

TTechnical Support 23time functions 127time literal

escape sequence 114timestamp literal

escape sequence 114tracing, enabling for Pool Manager 190transactions , See JTA supporttroubleshooting

application problems 11connection pooling problems 14statement pooling problems 18

turning on and off DataDirect Spy logging 12

Uunderstanding the maximum pool size 186unfreezing the statement pool 201updatable result sets, DataDirect Test 166Update statement 132updating rows

with DataDirect Test 172using

DataDirect Spy log 11JMX API 198

WWeb service adapter logger 21Workload Manager (WLM)

using client information with 31wrapper methods

to access JDBC Extensions 98

XXAConnection interface, methods 95XADataSource interface, methods 95XAResource interface, methods 96

217Progress DataDirect for JDBC Drivers: Reference: Version 6.0

Index

Page 218: Progress DataDirect for JDBC Drivers Reference€¦ · jdbc/SQLServerNCMarkBPool: Created new connection.24 jdbc/SQLServerNCMarkBPool: Number pooled connections = 6. jdbc/SQLServerNCMarkBPool:

Progress DataDirect for JDBC Drivers: Reference: Version 6.0218

Index