progress® datadirect® for jdbc™ for …jdbc for salesforce driver the progress® datadirect®...

Progress® DataDirect® forJDBC™ for Salesforce™ DriverUser's Guide

Release 6.0.0

Copyright

© 2020 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 inthese materials to specific platforms supported are subject to change.

Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirectXML Converters, DataDirect XQuery, DataRPM, Defrag This, Deliver More Than Expected, Icenium, Ipswitch,iMacros, Kendo UI, Kinvey, MessageWay, MOVEit, NativeChat, NativeScript, OpenEdge, Powered by Progress,Progress, Progress Software Developers Network, SequeLink, Sitefinity (and Design), Sitefinity, SpeedScript,Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test Studio, WebSpeed, WhatsConfigured,WhatsConnected, WhatsUp, and WS_FTP are registered trademarks of Progress Software Corporation or oneof its affiliates or subsidiaries in the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge,DataDirect Autonomous REST Connector, DataDirect Spy, SupportLink, DevCraft, Fiddler, iMail, JustAssembly,JustDecompile, JustMock, NativeScript Sidekick, OpenAccess, ProDataSet, Progress Results, ProgressSoftware, 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 itssubsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or itsaffiliates. Any other marks contained herein may be trademarks of their respective owners.

Updated: 2020/04/13

3Progress® DataDirect® for JDBC™ for Salesforce™ Driver: User's Guide: Version 6.0.0

Progress® DataDirect® for JDBC™ for Salesforce™ Driver: User's Guide: Version 6.0.04

Copyright

Table of Contents

Welcome to the Progress DataDirect for JDBC for Salesforce Driver....13What's New in this Release?................................................................................................................14

Requirements.......................................................................................................................................16

Version String Information....................................................................................................................16

Data Source and Driver Classes..........................................................................................................17

Connection URL...................................................................................................................................17

Connection Properties..........................................................................................................................18

Mapping Objects to Tables...................................................................................................................18

Data Types............................................................................................................................................19

getTypeInfo()..............................................................................................................................20

Contacting Technical Support...............................................................................................................28

Getting Started.............................................................................................31Setting the Classpath...........................................................................................................................31

Data Source and Driver Classes..........................................................................................................32

Connecting Using the DriverManager..................................................................................................32

Passing the Connection URL.....................................................................................................32

Testing the Connection..............................................................................................................33

Connecting using data sources............................................................................................................36

How Data Sources Are Implemented........................................................................................36

Creating data sources................................................................................................................37

Calling a data source in an application......................................................................................38

Testing a data source connection..............................................................................................38

Using the driver............................................................................................43Required permissions for Java SE with the standard Security Manager enabled................................44

Permissions for establishing connections..................................................................................45

Granting access to Java properties...........................................................................................45

Granting access to temporary files............................................................................................45

Permissions for bulk load from a CSV file..................................................................................46

Connecting from an application............................................................................................................46

Setting the Classpath ................................................................................................................46

Connecting Using the JDBC Driver Manager............................................................................47

Connecting using data sources.................................................................................................51

Using Connection Properties................................................................................................................56

Required Properties...................................................................................................................56

Mapping Properties...................................................................................................................57

Authentication Properties...........................................................................................................58


Contents

Failover Properties.....................................................................................................................60

Proxy Server Properties.............................................................................................................61

Web Service Properties.............................................................................................................61

Bulk API Properties...................................................................................................................63

Timeout Properties....................................................................................................................66

Statement Pooling Properties....................................................................................................67

Additional Properties.................................................................................................................68

Connecting Through a Proxy Server....................................................................................................71

Performance Considerations................................................................................................................72

Client-Side Caches...............................................................................................................................73

Creating a Cache.......................................................................................................................74

Modifying a Cache Definition.....................................................................................................74

Dropping a Cache......................................................................................................................76

Caching MetaData.....................................................................................................................76

Catalog Tables......................................................................................................................................76

SYSTEM_CACHES Catalog Table............................................................................................76

SYSTEM_CACHE_REFERENCES Catalog Table....................................................................78

SYSTEM_REMOTE_SESSIONS Catalog Table........................................................................78

SYSTEM_SESSIONS Catalog Table.........................................................................................79

Reports.................................................................................................................................................81

Authentication.......................................................................................................................................81

Configuring user ID/password authentication............................................................................82

Configuring OAuth 2.0 authentication........................................................................................82

Data Encryption....................................................................................................................................83

Using Identifiers....................................................................................................................................83

Failover Support...................................................................................................................................83

IP Addresses........................................................................................................................................84

Timeouts...............................................................................................................................................85

Views and Remote/Local Tables...........................................................................................................85

SQL escape sequences.......................................................................................................................85

Isolation Levels.....................................................................................................................................86

Scrollable cursors.................................................................................................................................86

Unicode support...................................................................................................................................86

Error Handling......................................................................................................................................87

Large Object (LOB) Support.................................................................................................................87

Parameter Metadata Support...............................................................................................................88

Insert and Update Statements...................................................................................................88

Select Statements......................................................................................................................88

ResultSet MetaData Support................................................................................................................89

Rowset Support....................................................................................................................................89

Auto-Generated Keys Support..............................................................................................................90

Connection Pool Manager....................................................................................................................91

How connection pooling works..................................................................................................91

Implementing DataDirect connection pooling............................................................................93

Configuring the connection pool................................................................................................96


Contents

Connecting Using a Connection Pool........................................................................................97

Closing the connection pool.......................................................................................................98

Checking the Pool Manager version..........................................................................................98

Enabling Pool Manager tracing..................................................................................................99

Connection Pool Manager interfaces.........................................................................................99

Statement Pool Monitor......................................................................................................................104

Using DataDirect-Specific Methods to Access the Statement Pool Monitor............................104

Using JMX to access the Statement Pool Monitor...................................................................107

Importing Statements into a Statement Pool...........................................................................108

Clearing all statements in a statement pool.............................................................................109

Freezing and unfreezing the statement pool............................................................................109

Generating a statement pool export file...................................................................................109

DataDirect Statement Pool Monitor interfaces and classes.....................................................110

DataDirect Bulk Load..........................................................................................................................112

Using a DDBulkLoad Object....................................................................................................112

CSV files.............................................................................................................................................116

Bulk load configuration file.......................................................................................................116

Bulk load configuration file schema.........................................................................................117

Character set conversions.......................................................................................................117

External overflow files..............................................................................................................118

Discard file...............................................................................................................................119

DataDirect Test...................................................................................................................................119

DataDirect Test tutorial.............................................................................................................120

Tracking JDBC calls with DataDirect Spy...........................................................................................153

Enabling DataDirect Spy..........................................................................................................153

Connection Property Descriptions...........................................................159AccessToken.......................................................................................................................................163

AuthenticationMethod.........................................................................................................................164

BulkFetchThreshold............................................................................................................................165

BulkLoadAsync...................................................................................................................................166

BulkLoadBatchSize............................................................................................................................167

BulkLoadConcurrencyMode...............................................................................................................167

BulkLoadPollInterval...........................................................................................................................168

BulkLoadThreshold.............................................................................................................................169

CatalogOptions...................................................................................................................................170

ClientID...............................................................................................................................................170

ClientSecret........................................................................................................................................171

ConfigOptions.....................................................................................................................................172

AuditColumns (Configuration Option)......................................................................................173

CustomSuffix (Configuration Option).......................................................................................174

KeywordConflictSuffix (Configuration Option)..........................................................................174

MapSystemColumnNames (Configuration Option)..................................................................175

NumberFieldMapping (Configuration Option)..........................................................................176


Contents

UppercaseIdentifiers (Configuration Option)...........................................................................176

ConnectionRetryCount.......................................................................................................................177

ConnectionRetryDelay........................................................................................................................178

ConvertNull.........................................................................................................................................178

CreateMap..........................................................................................................................................179

EnableBulkFetch.................................................................................................................................180

EnableBulkLoad.................................................................................................................................181

EnablePKChunking............................................................................................................................181

FetchSize............................................................................................................................................182

ImportStatementPool..........................................................................................................................183

InitializationString...............................................................................................................................184

InsensitiveResultSetBufferSize...........................................................................................................185

JavaDoubleToString............................................................................................................................186

LogConfigFile.....................................................................................................................................186

LoginTimeout......................................................................................................................................187

MaxPooledStatements........................................................................................................................188

Password............................................................................................................................................189

PKChunkSize.....................................................................................................................................189

ProxyHost...........................................................................................................................................190

ProxyPassword...................................................................................................................................191

ProxyPort............................................................................................................................................192

ProxyUser...........................................................................................................................................192

ReadOnly............................................................................................................................................193

RefreshToken......................................................................................................................................194

RegisterStatementPoolMonitorMBean...............................................................................................195

SchemaMap.......................................................................................................................................195

SecurityToken.....................................................................................................................................197

ServerName.......................................................................................................................................198

SpyAttributes......................................................................................................................................199

StmtCallLimit......................................................................................................................................200

StmtCallLimitBehavior........................................................................................................................200

TransactionMode................................................................................................................................201

User....................................................................................................................................................202

WSCompressData..............................................................................................................................202

WSFetchSize......................................................................................................................................203

WSPoolSize........................................................................................................................................204

WSRetryCount...................................................................................................................................204

WSTimeout.........................................................................................................................................205

Troubleshooting.........................................................................................207Troubleshooting your application........................................................................................................207

Turning On and Off DataDirect Spy Logging...........................................................................208

DataDirect Spy Log Example...................................................................................................209

Troubleshooting connection pooling...................................................................................................211


Contents

Enabling tracing with the setTracing method...........................................................................211

Pool Manager Trace File Example...........................................................................................211

Troubleshooting statement pooling.....................................................................................................214

Generating an export file with the exportStatement method....................................................215

Statement pool export file example.........................................................................................215

Using Java Logging............................................................................................................................216

Logging Components...............................................................................................................216

Configuring Logging.................................................................................................................218

Supported SQL Statements and Extensions...........................................221Alter Cache (EXT)..............................................................................................................................222

Relational Caches....................................................................................................................224

Alter Index...........................................................................................................................................224

Alter Sequence...................................................................................................................................224

Alter Session (EXT)............................................................................................................................225

Alter Table...........................................................................................................................................226

Altering a Remote Table...........................................................................................................226

Altering a Local Table...............................................................................................................229

Create Cache (EXT)...........................................................................................................................232

Relational Caches....................................................................................................................233

Referencing Clause.................................................................................................................234

Refresh Interval Clause...........................................................................................................234

Initial Check Clause.................................................................................................................235

Persist Clause..........................................................................................................................235

Enabled Clause.......................................................................................................................236

Call Limit Clause......................................................................................................................237

Filter Clause.............................................................................................................................237

Create Index.......................................................................................................................................238

Create Sequence................................................................................................................................239

Next Value For Clause.............................................................................................................239

Create Table.......................................................................................................................................240

Creating a Remote Table.........................................................................................................240

Creating a Local Table.............................................................................................................244

Create View........................................................................................................................................250

Delete.................................................................................................................................................252

Drop Cache (EXT)..............................................................................................................................253

Drop Index..........................................................................................................................................253

Drop Sequence...................................................................................................................................254

Drop Table..........................................................................................................................................254

Drop View...........................................................................................................................................255

Explain Plan........................................................................................................................................255

Insert..................................................................................................................................................256

Specifying an External ID Column...........................................................................................257

Refresh Cache (EXT).........................................................................................................................258


Contents

Refresh Map (EXT).............................................................................................................................258

Select..................................................................................................................................................259

Select Clause...........................................................................................................................260

Update................................................................................................................................................269

SQL Expressions................................................................................................................................270

Column Names........................................................................................................................270

Literals.....................................................................................................................................271

Operators.................................................................................................................................273

Functions.................................................................................................................................277

Conditions................................................................................................................................277

Subqueries.........................................................................................................................................278

IN Predicate.............................................................................................................................278

EXISTS Predicate....................................................................................................................279

UNIQUE Predicate...................................................................................................................279

Correlated Subqueries.............................................................................................................279

SQL escape sequences for JDBC............................................................281Date, time, and timestamp escape sequences...................................................................................282

Scalar Functions.................................................................................................................................282

Outer Join Escape Sequences...........................................................................................................283

LIKE escape character sequence for wildcards..................................................................................284

Native and Refresh Escape Sequences.............................................................................................284

JDBC support.............................................................................................287JDBC and JVM Compatibility.............................................................................................................287

Supported functionality.......................................................................................................................287

Array........................................................................................................................................288

Blob..........................................................................................................................................288

CallableStatement...................................................................................................................289

Clob.........................................................................................................................................302

Connection...............................................................................................................................304

ConnectionEventListener.........................................................................................................309

ConnectionPoolDataSource.....................................................................................................310

DatabaseMetaData..................................................................................................................310

DataSource..............................................................................................................................319

Driver.......................................................................................................................................319

ParameterMetaData.................................................................................................................320

PooledConnection....................................................................................................................321

PreparedStatement..................................................................................................................321

Ref...........................................................................................................................................326

ResultSet.................................................................................................................................326

ResultSetMetaData..................................................................................................................337

RowSet....................................................................................................................................338


Contents

SavePoint.................................................................................................................................338

Statement................................................................................................................................339

StatementEventListener...........................................................................................................343

Struct.......................................................................................................................................343

XAConnection..........................................................................................................................343

XADataSource.........................................................................................................................344

XAResource.............................................................................................................................344

JDBC extensions.......................................................................................345Using JDBC wrapper methods to access JDBC extensions...............................................................346

DatabaseMetaData interface..............................................................................................................347

DDBulkLoad interface.........................................................................................................................348

ExtConnection interface......................................................................................................................354

ExtDatabaseMetaData interface.........................................................................................................359

ExtLogControl class............................................................................................................................359

Designing JDBC applications for performance optimization................361Using database metadata methods....................................................................................................362

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

Avoiding search patterns.........................................................................................................363

Using a dummy query to determine table characteristics........................................................363

Returning data....................................................................................................................................364

Returning long data.................................................................................................................364

Reducing the size of returned data..........................................................................................365

Choosing the right data type....................................................................................................365

Retrieving result sets...............................................................................................................365

Selecting JDBC objects and methods ...............................................................................................366

Using parameter markers as arguments to stored procedures...............................................366

Using the statement object instead of the PreparedStatement object.....................................366

Using batches instead of prepared statements.......................................................................367

Choosing the right cursor.........................................................................................................368

Using get methods effectively..................................................................................................368

Retrieving auto-generated keys...............................................................................................369

Managing connections and updates...................................................................................................369

Managing connections.............................................................................................................370

Managing commits in transactions..........................................................................................370

Choosing the right transaction model......................................................................................371

Using updateXXX methods......................................................................................................371

Using getBestRowIdentifier.....................................................................................................371


Contents


Contents

1Welcome to the Progress DataDirect forJDBC for Salesforce Driver

The Progress® DataDirect® for JDBC™ for Salesforce™ driver supports standard SQL query language to select,insert, update, and delete data from Salesforce.com and other Web service data stores that use the SalesforceAPI such as Force.com, Database.com, and Veeva CRM. To support SQL access to Salesforce, the drivercreates a map of the Salesforce data model and translates SQL statements provided by the application toSalesforce queries (SOQL) and Web service calls.

The driver optimizes performance when executing joins by leveraging data relationships among Salesforceobjects to minimize the amount of data that needs to be fetched over the network. The Salesforce driverrecognizes the relationships among standard objects and custom objects and can access and update both.Relationships among objects can be reported with the metadata methods getBestRowIdentifier(),getColumns(), getExportedKeys(), getImportedKeys(), getPrimaryKey(), getTables(), andgetTypeInfo().

The driver also provides a client-side data cache.You can improve performance for some queries by definingrules that specify which data to cache on the client as well as when the cached data becomes invalid and needsto be refreshed.

For details, see the following topics:

• What's New in this Release?

• Requirements

• Version String Information

• Data Source and Driver Classes

• Connection URL


• Connection Properties

• Mapping Objects to Tables

• Data Types

• Contacting Technical Support

What's New in this Release?

Support and certificationVisit the following web pages for the latest support and certification information.

• Release Notes

• Supported Configurations

• DataDirect Support Matrices

Changes Since 6.0.0

• Driver Enhancements

• yes, no, on and off have been added as valid values for the connection properties that accept booleanvalues.

• The driver has been enhanced to support OAuth 2.0 authentication. See Configuring OAuth 2.0authentication on page 82 for details.

• Changed Behavior

• The configuration options have been deprecated. However, the driver will continue to support them untilthe next major release of the driver.

• The driver has been updated to require a Java Virtual Machine (JVM) that is Java SE 8 or higher, includingOracle JDK, OpenJDK, and IBM SDK (Java) distributions. See Requirements on page 16 for more detailson JVM.

Java SE 7 has reached the end of its product life cycle and will no longer receive generally availablesecurity updates. As a result, the driver will no longer support JVMs that are version Java SE 7 or earlier.Support for distributed versions of Java SE 7 and earlier will also end.

• The precision for the Integer data type has been changed from 10 to 9.

• The NUM_PREC_RADIX value for the Double data type has been changed from 10 to 2.

Changes for 6.0.0

• Driver Enhancements

• The driver has been enhanced to support the Salesforce Bulk API, including PK chunking, for bulk fetchoperations. This functionality can be enabled and configured with the EnableBulkFetch,BulkFetchThreshold, EnablePKChunking, and PKChunkSize connection properties. See Bulk APIProperties on page 63 for details.


Chapter 1: Welcome to the Progress DataDirect for JDBC for Salesforce Driver

https://www.progress.com/jdbc/release-history/salesforce-jdbc

https://www.progress.com/supported-configurations/datadirect?ds=salesforce

https://www.progress.com/matrices/datadirect

• The driver has been enhanced to support multiple simultaneous sessions.The number of active sessionsshould not exceed the number permitted by your Salesforce account and can be limited by the settingof the WSPoolSize connection property.

• The new WSPoolSize connection property allows you to specify the maximum number of sessions thedriver uses. This allows the driver to have multiple Web service requests active simultaneously whenmultiple JDBC connections are open, thereby improving throughput and performance. See WSPoolSizeon page 204 for details.

• The Refresh Map SQL extension has been added to the driver. REFRESH MAP discovers native objectsthat have been added to the native data store since connection or since the last refresh and maps theobjects into your relational view of native data. It also incorporates any configuration changes made toyour relational view by reloading the schema map and associated files. See Refresh Map (EXT) on page258 for details.

• Changed Behavior

• The data source class com.ddtek.jdbcx.sforce.SForceDataSource40 has been deprecated.The data source class com.ddtek.jdbcx.sforce.SForceDataSource should be used for datasource connections. The data source class com.ddtek.jdbcx.sforce.SForceDataSource nowsupports all JDBC specifications. See also Data Source and Driver Classes on page 17.

• In addition to the information listed here, refer to this compatibility FAQ for guidance on upgrading fromthe Progress DataDirect for JDBC for Salesforce 5.1 driver to the 6.0 driver.

• The driver’s SQL engine was upgraded for this release. Consequently, there are differences in how thedriver handles some SQL queries. Refer to this SQL engine upgrade document for details. See alsoSupported SQL Statements and Extensions on page 221.

• The 6.0 driver pushes queries to Salesforce whenever possible. Queries that cannot be pushed toSalesforce with the 6.0 driver may be slower than comparable queries made with previous versions ofthe driver because data may be paged to disk while completing an operation. If you experience slowperformance, please contact Technical Support. Our team will quickly address any performance issuesyou encounter.

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

• The native CURRENCY and PERCENTAGE data types now map to the DECIMAL JDBC data type. Inearlier releases, these data types mapped to the DOUBLE data type. See Data Types on page 19 details.

• The DatabaseName property has been deprecated. The SchemaMap property should now be used tospecify the fully qualified path of the configuration file where the map of the Salesforce data model iswritten. See SchemaMap on page 195 for details.

• The CreateDB and RefreshSchema properties have been deprecated. The CreateMap property shouldnow be used to specify whether the driver creates a new schema map when establishing the connection.See CreateMap on page 179 for details.

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

• The following connection properties and configuration options now have new default settings.

• The default value of the EnableBulkLoad connection property has been updated to true. By default,the bulk load protocol can be used for inserts, updates, and deletes based on the BulkLoadThresholdproperty. See EnableBulkLoad on page 181 for details.

• The default value for the StmtCallLimit connection property has been updated to 100. By default, thedriver can make a maximum of 100 Web service calls when executing any single SQL statement ormetadata query. See StmtCallLimit on page 200 for details.


What's New in this Release?

https://documentation.progress.com/output/DataDirect/collateral/salesforce_faq.pdf

https://documentation.progress.com/output/DataDirect/collateral/salesforce_sqlengine.pdf

https://www.progress.com/support-and-services

• The default value for the AuditColumns configuration option has been updated to all(AuditColumns=all). By default, the driver includes all audit columns and the master record idcolumn in its table definitions. See ConfigOptions on page 172 for details.

• The default value for the CustomSuffix configuration option has been updated to include(CustomSuffix=include). By default, the driver includes the "__c" suffix table and column nameswhen mapping the Salesforce data model. See ConfigOptions on page 172 for details.

• The default value for the MapSystemColumnName configuration option has been updated to 0(MapSystemColumnNames=0). By default, the driver does not change the names of the Salesforcesystem columns when mapping the Salesforce data model. See ConfigOptions on page 172 for details.

RequirementsThe driver is compatible with JDBC 2.0, 3.0, 4.0, 4.1, and 4.2.

The driver requires a Java Virtual Machine (JVM) that is Java SE 8 or higher, including Oracle JDK, OpenJDK,and IBM SDK (Java) distributions.

Note: To use the driver on a Java Platform with standard Security Manager enabled, certain permissions mustbe set in the security policy file of the Java Platform. See Required permissions for Java SE with the standardSecurity Manager enabled on page 44 for details.

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

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

where:

M is the major version number.

m is the minor version number.

s is the service pack number.

bbbbbb is the driver build number.

XXXX is the cloud adapter build number.

YYYYYY is the framework build number.

ZZZZZZ is the utl build number.

For example:

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



Data Source and Driver ClassesThe Driver class for the driver is:

com.ddtek.jdbc.sforce.SForceDriver

The DataSource class for the driver is:

com.ddtek.jdbcx.sforce.SForceDataSource

Connection URLAfter setting the CLASSPATH, the required connection information needs to be passed in the form of aconnection URL.

jdbc:datadirect:sforce://servername;User=username;Password=password; SecurityToken=value[;property=value[;...]]

where:

servername

specifies the base Salesforce URL to use for logging in. The default is login.salesforce.com.

User

specifies the user name that is used to connect to the Salesforce instance.

Password

specifies the password to use to connect to your Salesforce instance. A security token may beappended to the password. See "Password" for details.

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

SecurityToken

specifies the security token required to make a connection to a Salesforce instance that is configuredfor a security token. If a security token is required and you do not supply one, the driver returns anerror indicating that an invalid user or password was supplied. A security token may be appendedto the password. See "SecurityToken" for details.

Important: If setting the security token using a data source, be aware that the SecurityToken property, likeall data source properties, is persisted in clear text.

The following examples show how to establish a connection to a Salesforce instance.

Connection conn = DriverManager.getConnection ("jdbc:datadirect:sforce://login.salesforce.com;[email protected]; Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS");


Data Source and Driver Classes

See alsoUsing Connection Properties on page 56

Connection PropertiesThe driver includes over 40 connection properties.You can use connection properties to customize the driverfor your environment. Connection properties can be used to accomplish different tasks, such as implementingdriver functionality and optimizing performance.You can specify connection properties in a connection URLor within a JDBC data source object.

See alsoUsing Connection Properties on page 56Connection Property Descriptions on page 159

Mapping Objects to TablesThe driver automatically maps Salesforce objects and fields to tables and columns the first time it connects toa Salesforce instance. The driver maps both standard and custom objects and includes any relationshipsdefined between objects.You can use the getPrimaryKeys, getExportedKeys, and getImportedKeysmethods to report relationships among objects.

Schema MapThe driver uses a local schema map to instantiate the mapping of the remote Salesforce data model as tablesand the metadata associated with those tables. By default, the driver creates a schema map for each user.The schema map is created in each user's application data folder and uses the user ID specified for theconnection as the name of the schema map file. If the user ID contains punctuation or other non-alphanumericcharacters, the driver strips those characters from the user ID to form the name of the schema map file. Thedriver includes a SchemaMap connection property that allows you to override the default setting for the nameand location of the schema map file.

IdentifiersWhen mapping the remote data model, the driver converts unquoted identifiers to uppercase by default.Youcan use the UppercaseIdentifiers configuration option to map identifiers to use the case of the remote object.

Audit ColumnsSalesforce adds audit fields to all the objects defined in a Salesforce instance. By default, the driver includescorresponding audit columns in table definitions when mapping the remote data model. The AuditColumnsconfiguration option can be used to exclude or limit audit columns.

Custom Objects and FieldsSalesforce appends custom objects and fields with a standard "__c" suffix. By default, the driver includes thestandard "__c" suffix when mapping the remote data model.You can use the CustomSuffix configuration optionto strip the "__c" suffix.



System FieldsSalesforce includes system fields in a Salesforce instance. By default, the driver uses the name of the systemfield when mapping the system fields as columns.You can use the MapSystemColumnNames configurationoption to make it evident that the columns in a table correspond to system fields.

See alsoSchemaMap on page 195Using Identifiers on page 83ConfigOptions on page 172UppercaseIdentifiers (Configuration Option) on page 176AuditColumns (Configuration Option) on page 173CustomSuffix (Configuration Option) on page 174MapSystemColumnNames (Configuration Option) on page 175

Data TypesThe following table lists the data types supported by the driver, how the Salesforce data types are exposed inthe Salesforce Web Service API, and how these data types are mapped to JDBC data types.

Table 1: Salesforce Data Types

JDBC Data TypeWeb Service API Data TypeSalesforce Data Type

VARCHARanytypeANYTYPE1

VARCHARstringAUTONUMBER

LONGVARBINARYbinaryBINARY1

BOOLEANbooleanCHECKBOX

VARCHARcomboboxCOMBOBOX1

DECIMALcurrencyCURRENCY Formula (CURRENCY)

VARCHARDataCategoryGroupReferenceDATACATEGORYGROUPREFERENCE

DATEdateDATE Formula (DATE)

DATETIMEdatetimeDATETIME Formula (DATETIME)

VARCHARemailEMAIL

VARCHARencryptedtextENCRYPTEDTEXT

VARCHARhtmlHTML

LONGVARCHARidID

1 You cannot create columns with this data type using the Create Table and AlterTable statements.


Data Types

JDBC Data TypeWeb Service API Data TypeSalesforce Data Type

INTEGER or DOUBLEdoubleINT2

LONGVARCHARlongtextareaLONGTEXTAREA

VARCHARmultipicklistMULTISELECTPICKLIST

INTEGER or DOUBLEdoubleNUMBER3

DECIMALpercentPERCENT Formula (PERCENT)

VARCHARphonePHONE

VARCHARpicklistPICKLIST

VARCHARreferenceREFERENCE

VARCHARstringTEXT Formula (TEXT)

VARCHAR orLONGVARCHAR

textareaTEXTAREA4

TIMEtimeTIME1

VARCHARurlURL

getTypeInfo()

The DatabaseMetaData.getTypeInfo() method returns information about data types.The following table providesgetTypeInfo() results for supported Salesforce data types.

2 If the NumberFieldMapping key of the ConfigOptions property is set to emulateInteger, this data type maps to INTEGER.If set to alwaysDouble, this data type maps to DOUBLE.

3 If scale = 0 and precision <= 9 and the NumberFieldMapping key of the ConfigOptions property is set to emulateInteger,this data type maps to INTEGER. If scale does not = 0, precision > 9, or the NumberFieldMapping key of the ConfigOptionsproperty is set to alwaysDouble, this data type maps to DOUBLE.

4 For searchable columns, this data type maps to VARCHAR. For non-searchable columns, it maps to LONGVARCHAR.



Table 2: getTypeInfo() Results

MINIMUM_SCALE = NULL

NULLABLE = 1

NUM_PREC_RADIX = NULL

PRECISION = 255

SEARCHABLE = 3

SQL_DATA_TYPE = NULL

SQL_DATETIME_SUB = NULL

UNSIGNED_ATTRIBUTE = NULL

TYPE_NAME = AnyType

AUTO_INCREMENT = NULL

CASE_SENSITIVE = false

CREATE_PARAMS = NULL

DATA_TYPE = 12 (VARCHAR)

FIXED_PREC_SCALE = false

LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = ANYTYPE

MAXIMUM_SCALE = NULL


NULLABLE = 0


PRECISION = 30

SEARCHABLE = 3




TYPE_NAME = AutoNumber

AUTO_INCREMENT = true





LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = AUTONUMBER


MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 5242880

SEARCHABLE = 0




TYPE_NAME = Binary




DATA_TYPE = -4 (LONGVARBINARY)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = BINARY

MAXIMUM_SCALE = 0


Data Types


NULLABLE = 0


PRECISION = 1

SEARCHABLE = 3




TYPE_NAME = CheckBox




DATA_TYPE = 16 (BOOLEAN)


LITERAL_PREFIX = NULL

LITERAL_SUFFIX = NULL

LOCAL_TYPE_NAME = CHECKBOX



NULLABLE = 1


PRECISION = 255

SEARCHABLE = 3




TYPE_NAME = ComboBox






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = COMBOBOX


MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 31

SEARCHABLE = 2



UNSIGNED_ATTRIBUTE = false

TYPE_NAME = Currency

AUTO_INCREMENT = false


CREATE_PARAMS = precision, scale

DATA_TYPE = 3 (DECIMAL)




LOCAL_TYPE_NAME = CURRENCY

MAXIMUM_SCALE = 31




NULLABLE = 1


PRECISION = 255

SEARCHABLE = 3




TYPE_NAME = DataCategoryGroupReference






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = DATE



NULLABLE = 1


PRECISION = 10

SEARCHABLE = 3




TYPE_NAME = Date




DATA_TYPE = 91 (DATE)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = DATE


MINIMUM_SCALE = 0

NULLABLE = 1


PRECISION = 19

SEARCHABLE = 3




TYPE_NAME = DateTime




DATA_TYPE = 93 (TIMESTAMP)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = DATETIME

MAXIMUM_SCALE = 0


Data Types


NULLABLE = 1


PRECISION = 80

SEARCHABLE = 3




TYPE_NAME = Email






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = EMAIL



NULLABLE = 1


PRECISION = 32000

SEARCHABLE = 0




TYPE_NAME = HTML



CREATE_PARAMS = length

DATA_TYPE = -1 (LONGVARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = HTML



NULLABLE = 0


PRECISION = 18

SEARCHABLE = 3




TYPE_NAME = ID






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = ID





NULLABLE = 1


PRECISION = 32000

SEARCHABLE = 0




TYPE_NAME = LongTextArea




DATA_TYPE = -1 (LONGVARCHAR)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = LONGTEXTAREA



NULLABLE = 1


PRECISION = 255

SEARCHABLE = 3




TYPE_NAME = MultiSelectPickList






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = MULTISELECTPICKLIST


MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 18

SEARCHABLE = 3




TYPE_NAME = Number




DATA_TYPE = 8 (DOUBLE)




LOCAL_TYPE_NAME = NUMBER

MAXIMUM_SCALE = 18


Data Types

MINIMUM_SCALE = 0

NULLABLE = 1

NUM_PREC_RADIX = 10

PRECISION = 31

SEARCHABLE = 2




TYPE_NAME = Percent




DATA_TYPE = 3 (DECIMAL)




LOCAL_TYPE_NAME = PERCENT

MAXIMUM_SCALE = 31


NULLABLE = 1


PRECISION = 40

SEARCHABLE = 3




TYPE_NAME = Phone






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = PHONE



NULLABLE = 1


PRECISION = 255

SEARCHABLE = 3




TYPE_NAME = PickList






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = PICKLIST





NULLABLE = 1


PRECISION = 18

SEARCHABLE = 3




TYPE_NAME = Reference






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = REFERENCE



NULLABLE = 1


PRECISION = 255

SEARCHABLE = 3




TYPE_NAME = Text






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = TEXT



NULLABLE = 1


PRECISION = 255

SEARCHABLE = 3




TYPE_NAME = TextArea






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = TEXTAREA



Data Types


NULLABLE = 1


PRECISION = 8

SEARCHABLE = 3




TYPE_NAME = Time




DATA_TYPE = 92 (TIME)


LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = TIME



NULLABLE = 1


PRECISION = 255

SEARCHABLE = 3




TYPE_NAME = URL






LITERAL_PREFIX = '

LITERAL_SUFFIX = '

LOCAL_TYPE_NAME = URL


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.



https://www.progress.com/support

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

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

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

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

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

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


Contacting Technical Support

2Getting Started

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

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

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


• Setting the Classpath

• Data Source and Driver Classes

• Connecting Using the DriverManager

• Connecting using data sources

Setting the ClasspathThe driver must be defined on your CLASSPATH before you can connect. The CLASSPATH is the searchstring your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver is not definedon your CLASSPATH, you will receive a class not found exception when trying to load the driver. Set yoursystem CLASSPATH to include the sforce.jar file as shown, where install_dir is the path to yourproduct installation directory.

install_dir/lib/sforce.jar


Windows Example

CLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\sforce.jar

UNIX Example

CLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/sforce.jar

Data Source and Driver ClassesThe Driver class for the driver is:

com.ddtek.jdbc.sforce.SForceDriver

The DataSource class for the driver is:

com.ddtek.jdbcx.sforce.SForceDataSource

Connecting Using the DriverManagerOne way to connect to a Salesforce instance is through the JDBC DriverManager using theDriverManager.getConnection() method. As the following example shows, this method specifies a stringcontaining a connection URL.


Passing the Connection URL

After setting the CLASSPATH, the required connection information needs to be passed in the form of aconnection URL. The connection URL takes the form:

Connection URL Syntax


where:

servername


User



Chapter 2: Getting Started

Password



SecurityToken



Connection URL Example


See alsoPassword on page 189SecurityToken on page 197Using Connection Properties on page 56

Testing the Connection

You can use DataDirect Test™ to verify your connection. The screen shots in this section were taken on aWindows system.

To test the connection from the driver to your data source, follow these steps:

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

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

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

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

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

• testforjdbc.bat (on Windows systems)

• testforjdbc.sh (on UNIX and Linux systems)

The Test for JDBC Tool window appears:


Connecting Using the DriverManager

3. Click Press Here to Continue.

The main dialog appears:



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

The Select A Database dialog appears:

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

6. In the Database field, specify all required connection properties.

For example:

jdbc:datadirect:sforce://login.salesforce.com;[email protected]; Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS

7. If you did not specify your user name and password in the connection URL, enter this information in thecorresponding fields.

8. Click Connect.

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


Connecting Using the DriverManager

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

Connecting using data sourcesA JDBC data source is a Java object, specifically a DataSource object, that defines connection informationrequired for a JDBC driver to connect to the database. Each JDBC driver vendor provides their own data sourceimplementation for this purpose. A Progress DataDirect data source is Progress DataDirect’s implementationof a DataSource object that provides the connection information needed for the driver to connect to a database.

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

How Data Sources Are Implemented

Data sources are implemented through a data source class. A data source class implements the followinginterfaces.

• javax.sql.DataSource

• javax.sql.ConnectionPoolDataSource (allows applications to use connection pooling)



See alsoData Source and Driver Classes on page 17Connection Pool Manager on page 91

Creating data sources

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

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

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

See "Example data source" for an example data source definition for the example files.

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

Example Data SourceTo configure a data source using the example files, you will need to create a data source definition.The contentrequired to create a data source definition is divided into three sections. For example:

import com.ddtek.jdbcx.SForce.SForceDataSource;

Next, you will need to set the values and define the data source. For example, the following definition containsthe minimum properties required to establish connection:

Important: Setting the password and security token using a data source is generally not recommended. Thedata source persists all properties, including the Password and SecurityToken properties, in clear text.

SForceDataSource mds = new SForceDataSource();mds.setDescription("My Salesforce Datasource");mds.setServerName("login.salesforce.com");mds.setUser("[email protected]");mds.setPassword("secret");mds.setSecurityToken("XaBARTsLZReM4Px47qPLOS");

Finally, you will need to configure the example application to print out the data source attributes. Note that thiscode is specific to the driver and should only be used in the example application. For example, you would addthe following section for the minimum properties required to establish a connection:

if (ds instanceof SForceDataSource){SForceDataSource jmds = (SForceDataSource) ds;System.out.println("description=" + jmds.getDescription());System.out.println("serverName=" + jmds.getServerName());System.out.println("user=" + jmds.getUser());System.out.println("password=" + jmds.getPassword());System.out.println("securityToken=" + jmds.getSecurityToken());


Connecting using data sources

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

System.out.println();}

Calling a data source in an application

Applications can call a Progress DataDirect data source using a logical name to retrieve thejavax.sql.DataSource object. This object loads the specified driver and can be used to establish aconnection to the database.

Once the data source has been registered with JNDI, it can be used by your JDBC application as shown in thefollowing code example.

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

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

Testing a data source connection

You can use DataDirect Test™ to establish and test a data source connection. The screen shots in this sectionwere taken on a Windows system.

Take the following steps to establish a connection.













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




5. Select a datasource template from the Defined Datasources field.

6. Provide the following information:

a) In the Initial Context Factory, specify the location of the initial context provider for your application.

b) In the Context Provider URL, specify the location of the context provider for your application.

c) In the Datasource field, specify the name of your datasource.

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

8. Click Connect.

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



3Using the driver

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


• Required permissions for Java SE with the standard Security Manager enabled

• Connecting from an application

• Using Connection Properties

• Connecting Through a Proxy Server

• Performance Considerations

• Client-Side Caches

• Catalog Tables

• Reports

• Authentication

• Data Encryption

• Using Identifiers

• Failover Support

• IP Addresses

• Timeouts


• Views and Remote/Local Tables

• SQL escape sequences

• Isolation Levels

• Scrollable cursors

• Unicode support

• Error Handling

• Large Object (LOB) Support

• Parameter Metadata Support

• ResultSet MetaData Support

• Rowset Support

• Auto-Generated Keys Support

• Connection Pool Manager

• Statement Pool Monitor

• DataDirect Bulk Load

• CSV files

• DataDirect Test

• Tracking JDBC calls with DataDirect Spy

Required permissions for Java SE with the standardSecurity Manager enabled

Using the driver on a Java platform with the standard Security Manager enabled requires certain permissionsto be set in the Java SE security policy file java.policy. The default location of this file isjava_install_dir/jre/lib/security.

Note: Security manager may be enabled by default in certain scenarios, such as running on an applicationserver or in a Web browser applet.

To run an application on a Java platform with the standard Security Manager, use the following command:

"java -Djava.security.manager application_class_name"

where application_class_name is the class name of the application.

Refer to your Java documentation for more information about setting permissions in the security policy file.


Chapter 3: Using the driver

Permissions for establishing connections

To establish a connection to the database server, the driver must be granted the permissions as shown in thefollowing example:

grant codeBase "file:/install_dir/lib/-" { permission java.net.SocketPermission "*", "connect";};

where:

install_dir

is the product installation directory.

Granting access to Java properties

To allow the driver to read the value of various Java properties to perform certain operations, permissions mustbe granted as shown in the following example:

grant codeBase "file:/install_dir/lib/-" { permission java.util.PropertyPermission "*", "read, write";};

where:

install_dir


Granting access to temporary files

Access to the temporary directory specified by the JVM configuration must be granted in the Java SE securitypolicy file to use insensitive scrollable cursors or to perform client-side sorting of DatabaseMetaData resultsets. The following example shows permissions that have been granted for the C:\TEMP directory:

grant codeBase "file:/install_dir/lib/-" {// Permission to create and delete temporary files.// Adjust the temporary directory for your environment. permission java.io.FilePermission "C:\\TEMP\\-", "read,write,delete";};

where:

install_dir



Required permissions for Java SE with the standard Security Manager enabled

Permissions for bulk load from a CSV file

To bulk load data from a comma-separated value (CSV) file with the drivers, the application and driver codebases must be granted security permissions in the security policy file of the Java Platform as shown in thefollowing examples.

grant codeBase "file:/install_dir/lib/-" { permission java.util.PropertyPermission "true", "read"; permission java.util.PropertyPermission "file.encoding", "read"; permission java.util.PropertyPermission "user.dir", "read"; permission java.lang.RuntimePermission "readFileDescriptor";};

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

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

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

Setting the Classpath

Before you can connect, the driver must be defined in your CLASSPATH variable. The CLASSPATH is thesearch string your Java Virtual Machine (JVM) uses to locate JDBC drivers on your computer. If the driver isnot defined on your CLASSPATH, you will receive a class not found exception when trying to load thedriver. Set your system CLASSPATH to include the sforce.jar file as shown, where install_dir is thepath to your product installation directory:

install_dir/lib/sforce.jar

Windows Example

CLASSPATH=.;C:\Program Files\Progress\DataDirect\JDBC_60\lib\sforce.jar

UNIX Example

CLASSPATH=.:/opt/Progress/DataDirect/JDBC_60/lib/sforce.jar



Connecting Using the JDBC Driver Manager

One way to connect to a Salesforce instance is through the JDBC Driver Manager using theDriverManager.getConnection() method. This method specifies a string containing a connection URL.This example shows how to establish a connection to a data source:


Passing the Connection URLAfter setting the CLASSPATH, the required connection information needs to be passed in the form of aconnection URL. The connection URL takes the form:

Connection URL Syntax


where:

servername


User


Password



SecurityToken



Connection URL Example



Connecting from an application

See alsoPassword on page 189SecurityToken on page 197Using Connection Properties on page 56

Testing the ConnectionYou can use DataDirect Test™ to verify your connection. The screen shots in this section were taken on aWindows system.

To test the connection from the driver to your data source, follow these steps:











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


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

6. In the Database field, specify all required connection properties.

For example:


7. If you did not specify your user name and password in the connection URL, enter this information in thecorresponding fields.

8. Click Connect.

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



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


A JDBC data source is a Java object, specifically a DataSource object, that defines connection informationrequired for a JDBC driver to connect to the database. Each JDBC driver vendor provides their own data sourceimplementation for this purpose. A Progress DataDirect data source is Progress DataDirect’s implementationof a DataSource object that provides the connection information needed for the driver to connect to a database.

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

How Data Sources Are ImplementedData sources are implemented through a data source class. A data source class implements the followinginterfaces.

• javax.sql.DataSource

• javax.sql.ConnectionPoolDataSource (allows applications to use connection pooling)



See alsoData Source and Driver Classes on page 17Connection Pool Manager on page 91

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

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

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

See "Example data source" for an example data source definition for the example files.

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

Example Data Source

To configure a data source using the example files, you will need to create a data source definition.The contentrequired to create a data source definition is divided into three sections. For example:

import com.ddtek.jdbcx.SForce.SForceDataSource;

Next, you will need to set the values and define the data source. For example, the following definition containsthe minimum properties required to establish connection:

Important: Setting the password and security token using a data source is generally not recommended. Thedata source persists all properties, including the Password and SecurityToken properties, in clear text.

SForceDataSource mds = new SForceDataSource();mds.setDescription("My Salesforce Datasource");mds.setServerName("login.salesforce.com");mds.setUser("[email protected]");mds.setPassword("secret");mds.setSecurityToken("XaBARTsLZReM4Px47qPLOS");

Finally, you will need to configure the example application to print out the data source attributes. Note that thiscode is specific to the driver and should only be used in the example application. For example, you would addthe following section for the minimum properties required to establish a connection:

if (ds instanceof SForceDataSource){SForceDataSource jmds = (SForceDataSource) ds;System.out.println("description=" + jmds.getDescription());System.out.println("serverName=" + jmds.getServerName());System.out.println("user=" + jmds.getUser());System.out.println("password=" + jmds.getPassword());System.out.println("securityToken=" + jmds.getSecurityToken());System.out.println();}




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

Once the data source has been registered with JNDI, it can be used by your JDBC application as shown in thefollowing code example.

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

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

Testing a data source connectionYou can use DataDirect Test™ to establish and test a data source connection. The screen shots in this sectionwere taken on a Windows system.

Take the following steps to establish a connection.













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




5. Select a datasource template from the Defined Datasources field.

6. Provide the following information:

a) In the Initial Context Factory, specify the location of the initial context provider for your application.

b) In the Context Provider URL, specify the location of the context provider for your application.

c) In the Datasource field, specify the name of your datasource.

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

8. Click Connect.

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



Using Connection PropertiesYou can use connection properties to customize the driver for your environment. This section organizesconnection properties according to functionality.You can use connection properties with either the JDBCDriverManager or a JDBC data source. For a DriverManager connection, a property is expressed as akey value pair and takes the form property=value. For a data source connection, a property is expressedas a JDBC method and takes the form setproperty(value).

Note: Connection property names are case-insensitive. For example, Password is the same as password.

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

See "Connection Property Descriptions" for an alphabetical list of connection properties and their descriptions.

See alsoConnecting Using the JDBC Driver Manager on page 47Connecting using data sources on page 36Connection Property Descriptions on page 159

Required Properties

The following table summarizes connection properties which are required to connect to a Salesforce instance.

Table 3: Required Properties

CharacteristicProperty

Specifies the password to use to connect to your Salesforce instance. A passwordis required. Contact your system administrator to obtain your password.

Important: Setting the password using a data source is not recommended. Thedata source persists all properties, including the Password property, in clear text.

Password on page 189




Specifies the security token required to make a connection to a Salesforce instancethat is configured for a security token.

Note: A security token is not required when Salesforce has been configured forTrusted IP Ranges and the user is logging in from a trusted IP address. Refer to"Set Trusted IP Ranges for Your Organization" in your Salesforce documentationfor details.

Note: If setting the security token using a data source, be aware that theSecurityToken property, like all data source properties, is persisted in clear text.

SecurityToken on page197

Specifies the base Salesforce URL to use for logging in. This value is as follows:

• Production environments: login.salesforce.com

• Sandbox instances: test.salesforce.com

The default is login.salesforce.com.

ServerName on page 198

Specifies the user name that is used to connect to the Salesforce instance.User on page 202

See alsoConnection Property Descriptions on page 159

Mapping Properties

The following table summarizes connection properties involved in mapping the remote Salesforce data modelto a local schema map used to support SQL queries against Salesforce.

Table 4: Mapping Properties


Determines how the mapping of the remote Salesforce data model to a localschema map can be configured, customized, and updated.

The default is:

(AuditColumns=all;CustomSuffix=include;KeywordConflictSuffix=; MapSystemColumnNames=0;NumberFieldMapping=emulateInteger; UppercaseIdentifiers=true)

ConfigOptions on page 172


Using Connection Properties


Specifies whether the driver creates a new map of the Salesforce data modelwhen establishing the connection.

If set to forceNew, the driver deletes the current schema map specified bythe SchemaMap property and creates a new one at the same location.

If set to notExist, the driver uses the current schema map specified by theSchemaMap property. If one does not exist, the driver creates one.

If set to no, the driver uses the current schema map specified by theSchemaMap property. If one does not exist, the connection fails.

The default is notExist.

CreateMap on page 179

Specifies the fully qualified path of the configuration file where the map of theSalesforce data model is written. The driver looks for this file when connectingto a Salesforce instance. If the file does not exist, the driver creates one.

The default varies based on your environment:

For Windows:

application_data_folder\Local\Progress\DataDirect\SForce_Sch

ema\user_name.config

For UNIX/Linux:

~/progress/datadirect/SForce_Schema/user_name.config

SchemaMap on page 195

See alsoMapping Objects to Tables on page 18Connection Property Descriptions on page 159

Authentication Properties

The following table summarizes connection properties which are required for user ID and passwordauthentication.

Table 5: Authentication Properties


Specifies the access token required to authenticate to a Salesforce instance whenOAuth 2.0 is enabled (AuthenticationMethod=oauth2.0).

Note: If a value for the AccessToken property is not specified, the driver uses thevalue of the RefreshToken property to make a connection. If both values are notspecified, the driver cannot make a successful connection. If both are specified,the driver ignores the AccessToken value and uses the RefreshToken value togenerate a new AccessToken value.

AccessToken on page 163




Determines which authentication method the driver uses when establishing aconnection.

If set to userIDPassword, the driver uses user ID/password authentication whenestablishing a connection.

If set to oauth2.0, the driver uses OAuth 2.0 authentication when establishing aconnection.

The default is userIDPassword.

AuthenticationMethod onpage 164

Specifies the consumer key for your application. The driver uses this value toauthenticate to a Salesforce instance when OAuth 2.0 is enabled(AuthenticationMethod=oauth2.0).

ClientID on page 170

Specifies the consumer secret for your application. This value can optionally bespecified when authenticating to a Salesforce instance using OAuth 2.0(AuthenticationMethod=oauth2.0).

ClientSecret on page 171

Specifies the password to use to connect to your Salesforce instance. A passwordis required. Contact your system administrator to obtain your password.

Important: Setting the password using a data source is not recommended. Thedata source persists all properties, including the Password property, in clear text.

Password on page 189

Specifies the refresh token used to either request a new access token or renewan expired access token. When the refresh token is specified, the access tokengenerated at connection is used to authenticate to a Salesforce instance whenOAuth 2.0 is enabled (AuthenticationMethod=oauth2.0).

Note: If a value for the AccessToken property is not specified, the driver uses thevalue of the RefreshToken property to make a connection. If both values are notspecified, the driver cannot make a successful connection. If both are specified,the driver ignores the AccessToken value and uses the RefreshToken value togenerate a new AccessToken value.

RefreshToken on page 194




Specifies the security token required to make a connection to a Salesforce instancethat is configured for a security token.

Note: A security token is not required when Salesforce has been configured forTrusted IP Ranges and the user is logging in from a trusted IP address. Refer to"Set Trusted IP Ranges for Your Organization" in your Salesforce documentationfor details.

Note: If setting the security token using a data source, be aware that theSecurityToken property, like all data source properties, is persisted in clear text.

SecurityToken on page197

Specifies the user name that is used to connect to the Salesforce instance.User on page 202


Failover Properties

The following table summarizes connection properties which can be used to implement failover.

Table 6: Failover Properties


Specifies the number of times the driver retries connection attempts to theprimary database server, and if specified, alternate servers before returninga connection failure.

If set to 0, the driver does not try to reconnect after the initial unsuccessfulattempt.

If set to x, the driver retries connection attempts the specified number oftimes. If a connection is not established during the retry attempts, the driverreturns an exception that is generated by the last database server to whichit tried to connect.

The default is 5.

ConnectionRetryCount on page177

Specifies the number of seconds the driver waits between connection retryattempts when ConnectionRetryCount is set to a positive integer.

If set to 0, the driver does not delay between retries.

If set to x, the driver waits between connection retry attempts the specifiednumber of seconds.

The default is 1.

ConnectionRetryDelay on page178



See also

• Connection Property Descriptions on page 159

Proxy Server Properties

The following table summarizes proxy server connection properties.

Table 7: Proxy Server Properties


Identifies a proxy server to use for the first connection. This can be a namedserver or an IP address.

ProxyHost on page 190

Specifies the password needed to connect to a proxy server for the firstconnection.

ProxyPassword on page 191

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

The default is 0.

ProxyPort on page 192

Specifies the user name needed to connect to a proxy server for the firstconnection.

ProxyUser on page 192

See also


• Connecting Through a Proxy Server on page 71

Web Service Properties

The following table summarizes Web service connection properties, including those related to timeouts.

Table 8: Web Service Properties


The amount of time, in seconds, that the driver waits for a connection tobe established before timing out the connection request.

If set to 0, the driver does not time out a connection request.

If set to x, the driver waits for the specified number of seconds beforereturning control to the application and throwing a timeout exception.

The default is 0 (no timeout).

LoginTimeout on page 187




Specifies the maximum number of Web service calls the driver can makewhen executing any single SQL statement or metadata query.

If set to 0, there is no limit.

If set to x, the driver uses this value to set the maximum number of Webservice calls on a single connection that can be made when executing aSQL statement. This limit can be overridden by changing theSTMT_CALL_LIMIT session attribute using the ALTER SESSION statement.

The default is 100 (Web service calls).

StmtCallLimit on page 200

Specifies the behavior of the driver when the maximum Web service calllimit specified by the StmtCallLimit property is exceeded.

If set to errorAlways, the driver generates an exception if the maximumWeb service call limit is exceed.

If set to returnResults, the driver returns any partial results it receivedprior to the call limit being exceeded. The driver generates a warning thatnot all of the results were fetched.

The default is errorAlways.

StmtCallLimitBehavior on page200

Specifies whether the driver compresses data it sends to or receives fromthe Web server.

If set to none, the driver sends and receives uncompressed data to andfrom the Web server.

If set to compress, the driver sends and receives compressed data to andfrom the Web server.

The default is compress.

WSCompressData on page 202

Specifies the number of rows of data the driver attempts to fetch for eachJDBC call.

If set to 0, the driver attempts to fetch up to a maximum of 2000 rows. Thisvalue typically provides the maximum throughput.

If set to x, the driver attempts to fetch up to a maximum of the specifiednumber of rows. Setting the value lower than 2000 can reduce the responsetime for returning the initial data. Consider using a smaller WSFetch sizefor interactive applications only.

WSFetchSize on page 203

Specifies the maximum number of Salesforce sessions the driver uses.This allows the driver to have multiple web service requests active whenmultiple ODBC connections are open, thereby improving throughput andperformance.

The default is 1.

WSPoolSize on page 204




The number of times the driver retries a timed-out Select request. Insert,Update, and Delete requests are never retried.

If set to 0, the driver does not retry timed-out requests after the initialunsuccessful attempt.

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

The default is 0.

WSRetryCount on page 204

Specifies the time, in seconds, that the driver waits for a response to aWeb service request.

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

If set to x, the driver uses the value as the default timeout for any statementcreated by the connection.

The default is 120.

WSTimeout on page 205

See also


• Performance Considerations on page 72

• Timeouts on page 85

Bulk API Properties

The following table summarizes connection properties that are used to implement the Salesforce Bulk API forselects, inserts, updates, and deletes.

Table 9: Bulk API Properties

DescriptionProperty

Specifies a number of rows that, if exceeded, signals the driver to usethe Salesforce Bulk API for select operations. For this behavior to takeeffect, the EnableBulkFetch property must be set to true.

If set to 0, the driver uses the Salesforce Bulk API for all selectoperations.

If set to x, the driver uses the Salesforce Bulk API for select operationswhen the value of x is exceeded.

The default is 30000 (rows).

BulkFetchThreshold on page 165



DescriptionProperty

Determines whether the driver treats bulk load operations assynchronous or asynchronous.

If set to 0, bulk load operations are synchronous. The driver does notreturn from the method that invoked an operation until the operationhas completed or the operation has timed out. If the operation timesout, the driver throws an exception.

If set to 1, bulk load operations are asynchronous. The driver returnsfrom the method that invoked an operation immediately after theoperation is submitted to the server. The driver does not verify that thebulk load operation was completed.

The default is 0 (synchronous).

BulkLoadAsync on page 166

Provides a suggestion to the driver for the number of rows to load tothe database at a time when bulk loading data.

The default is 10000.

BulkLoadBatchSize on page 167

Determines whether multiple batches associated with a bulk loadoperation are processed by Salesforce in parallel or one at a time.

If set to parallel, multiple batches associated with a bulk loadoperation are processed in parallel.The order in which the batches areprocessed can vary.

If set to serial, multiple batches associated with a bulk load operationare processed one at a time.

The default is parallel.

BulkLoadConcurrencyMode on page167

Specifies the number of seconds the driver waits to request bulkoperation status. This interval is used by the driver the first time itrequests status and for all subsequent status requests.

The default is 10 (seconds).

BulkLoadPollInterval on page 168

Specifies a number of rows that, if exceeded, signals the driver to usethe Salesforce Bulk API for inserts, updates, and deletes. For thisbehavior to take effect, the EnableBulkLoad property must be set totrue.

If set to 0, the driver uses the Salesforce Bulk API for all inserts,updates, and deletes.

If set to x, the driver uses the Salesforce Bulk API to execute the insert,update, or delete operation when the value of x is exceeded.


BulkLoadThreshold on page 169



DescriptionProperty

Specifies whether the driver can use the Salesforce Bulk API for selectsbased on the value of the BulkFetchThreshold connection property. Ifthe number of rows expected in the result set exceeds the value ofBulkFetchThreshold property, the driver uses the Salesforce Bulk APIto execute the select operation. Using the Salesforce Bulk API maysignificantly reduce the number of Web service calls used to executea statement and, therefore, may improve performance.

If set to true, the driver can use the Salesforce Bulk API for selectsbased on the value of the BulkFetchThreshold connection property. Ifthe number of rows expected in the result set exceeds the value ofBulkFetchThreshold property, the driver uses the Salesforce Bulk APIto execute the select operation.

If set to false, the driver does not use the Salesforce Bulk API, andthe BulkFetchThreshold property is ignored.

The default is true.

EnableBulkFetch on page 180

Specifies whether the driver can use the Salesforce Bulk API for inserts,updates, and deletes based on the value of the BulkLoadThresholdconnection property. If the number of affected rows exceeds the valueof BulkLoadThreshold property, the driver uses the Salesforce BulkAPI to execute the insert, update, or delete operation. Using theSalesforce Bulk API may significantly reduce the number of Web servicecalls used to execute a statement and, therefore, may improveperformance.

If set to true, the driver can use the Salesforce Bulk API for inserts,updates, and deletes based on the value of the BulkLoadThresholdconnection property. If the number of affected rows exceeds the valueof BulkLoadThreshold property, the driver uses the Salesforce BulkAPI to execute the insert, update, or delete operation.

If set to false, the driver does not use the Salesforce Bulk API, andthe BulkLoadThreshold property is ignored.


EnableBulkLoad on page 181



DescriptionProperty

Specifies whether the driver uses PK chunking for select operations.PK chunking breaks down bulk fetch operations into smaller, moremanageable batches for improved performance.

If set to true, the driver uses PK chunking for select operations whenthe expected number of rows in the result set is greater than the valuesof the BulkFetchThreshold and PKChunkSize properties. For thisbehavior to take effect, the EnableBulkFetch property must also be setto true.

If set to false, the driver does not use PK chunking when executingselect operations, and the PKChunkSize property is ignored.


EnablePKChunking on page 181

Specifies the size, in rows, of a primary key chunk when PK chunkinghas been enabled via the EnablePKChunking property.The SalesforceBulk API splits the query into chunks of this size.

PKChunkSize may be set to a maximum value of 250000 rows.


PKChunkSize on page 189

See alsoDataDirect Bulk Load on page 112Connection Property Descriptions on page 159

Timeout Properties

The following table summarizes timeout connection properties.

Table 10:Timeout Properties


Specifies the amount of time, in seconds, that the driver waits for a connectionto be established before timing out the connection request.

If set to 0, the driver does not time out a connection request.

If set to x, the driver waits for the specified number of seconds before returningcontrol to the application and throwing a timeout exception.

The default is 0.

LoginTimeout on page 187




The number of times the driver retries a timed-out Select request. Insert,Update, and Delete requests are never retried.

If set to 0, the driver does not retry timed-out requests after the initialunsuccessful attempt.

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

The default is 0.

WSRetryCount on page 204

Specifies the time, in seconds, that the driver waits for a response to a Webservice request.

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

If set to x, the driver uses the value as the default timeout for any statementcreated by the connection.

The default is 120.

WSTimeout on page 205

See also


• Web Service Properties on page 61

Statement Pooling Properties

The following table summarizes statement pooling connection properties.

Table 11: Statement Pooling Properties


Specifies the path and file name of the file to be used to load thecontents of the statement pool. When this property is specified,statements are imported into the statement pool from the specifiedfile.

ImportStatementPool on page 183




Specifies the maximum number of prepared statements to bepooled for each connection and enables the driver’s internalprepared statement pooling when set to an integer greater thanzero (0).The driver’s internal prepared statement pooling providesperformance benefits when the driver is not running from withinan application server or another application that provides its ownstatement pooling.

If set to 0, the driver’s internal prepared statement pooling is notenabled.

If set to x, the driver enables the DataDirect Statement Pool anduses the specified value to cache a certain number of preparedstatements created by an application. If the value set for thisproperty is greater than the number of prepared statements thatare used by the application, all prepared statements that arecreated by the application are cached. Because CallableStatementis a sub-class of PreparedStatement, CallableStatements alsoare cached.

The default is 0.

MaxPooledStatements on page 188

Registers the Statement Pool Monitor as a JMX MBean whenstatement pooling has been enabled with MaxPooledStatements.This allows you to manage statement pooling with standard JMXAPI calls and to use JMX-compliant tools, such as JConsole.

If set to true, the driver registers an MBean for the statementpool monitor for each statement pool. This gives applicationsaccess to the Statement Pool Monitor through JMX whenstatement pooling is enabled.

If set to false, the driver does not register an MBean for theStatement Pool Monitor for any statement pool.

The default is false.

RegisterStatementPoolMonitorMBean onpage 195

See alsoStatement Pool Monitor on page 104Connection Property Descriptions on page 159

Additional Properties

The following table summarizes additional connection properties.



Table 12: Additional Properties


Determines which type of metadata information is included in result setswhen an application calls DatabaseMetaData methods.

If set to 2, result sets do not contain synonyms.

If set to 4, a hint is provided to the driver to emulate getColumns() callsusing the ResultSetMetaData object instead of querying database catalogsfor column information. Result sets contain synonyms. Using emulationcan improve performance because the SQL statement that is formulatedby the emulation is less complex than the SQL statement that isformulated using getColumns(). The argument to getColumns() mustevaluate to a single table. If it does not, because of a wildcard or nullvalue, for example, the driver reverts to the default behavior forgetColumns() calls.

The default is 2.

CatalogOptions on page 170

Controls how data conversions are handled for null values.

If set to 0, the driver does not perform the data type check if the value ofthe column is null. This allows null values to be returned even though aconversion between the requested type and the column type is undefined.

If set to 1, the driver checks the data type being requested against thedata type of the table column that stores the data. If a conversion betweenthe requested type and column type is not defined, the driver generatesan "unsupported data conversion" exception regardless of whether thecolumn value is NULL.

The default is 1.

ConvertNull on page 178

Specifies the maximum number of rows that the driver processes beforereturning data to the application for a single fetch request when executinga Select. This value provides a suggestion to the driver as to the numberof rows that should be returned to the application. The driver may fetchfewer rows to conserve memory when processing exceptionally widerows.

If set to 0, the driver processes all the rows of the result before returningcontrol to the application. When large data sets are being processed,setting FetchSize to 0 can diminish performance and increase thelikelihood of out-of-memory errors.

If set to x, the driver limits the number of rows that may be processed foreach fetch request before returning control to the application.

FetchSize on page 182

Specifies one or multiple SQL commands to be executed by the driverafter it has established the connection to the database and has performedall initialization for the connection. If the execution of a SQL commandfails, the connection attempt also fails and the driver throws an exceptionindicating which SQL command or commands failed.

InitializationString on page 184




Determines the amount of memory used by the driver to cache insensitiveresult set data.

If set to -1, the driver caches insensitive result set data in memory. If thesize of the result set exceeds available memory, anOutOfMemoryException is generated. With no need to write result setdata to disk, the driver processes the data efficiently.

If set to 0, the driver caches insensitive result set data in memory, up toa maximum of 2 MB. If the size of the result set data exceeds availablememory, then the driver pages the result set data to disk, which can havea negative performance effect. Because result set data may be writtento disk, the driver may have to reformat the data to write it correctly todisk.

If set to x, the driver caches insensitive result set data in memory anduses this value to set the size (in KB) of the memory buffer for cachinginsensitive result set data. If the size of the result set data exceedsavailable memory, then the driver pages the result set data to disk, whichcan have a negative performance effect. Because the result set data maybe written to disk, the driver may have to reformat the data to write itcorrectly to disk. Specifying a buffer size that is a power of 2 results inefficient memory use.

The default is 2048.

InsensitiveResultSetBufferSize onpage 185

Determines which algorithm the driver uses when converting a doubleor float value to a string value. By default, the driver uses its own internalconversion algorithm, which improves performance.

If set to true, the driver uses the JVM algorithm when converting adouble or float value to a string value. If your application cannot acceptrounding differences and you are willing to sacrifice performance, set thisvalue to true to use the JVM conversion algorithm.

If set to false, the driver uses its own internal algorithm when convertinga double or float value to a string value.This value improves performance,but slight rounding differences within the allowable error of the doubleand float data types can occur when compared to the same conversionusing the JVM algorithm.


JavaDoubleToString on page 186

Specifies the filename of the configuration file used to initialize driverlogging.

The default is ddlogging.properties.

LogConfigFile on page 186




Specifies whether the connection supports read-only access to the datasource.

If set to true, the connection has read-only access. The followingcommands are the only commands that you can use when a connectionif read-only:

• Call* (if the procedure does not update data)

• Explain Plan

• Select (except Select Into)

• Set Database Collation

• Set IgnoreCase

• Set Maxrows

• Set Schema

The driver generates an exception if any other command is executed.

If set to false, the connection is opened for read/write access, and youcan use all commands supported by the product.


ReadOnly on page 193

Enables DataDirect Spy to log detailed information about calls issued bythe driver on behalf of the application. DataDirect Spy is disabled bydefault.

SpyAttributes on page 199

Specifies how the driver handles manual transactions.

If set to ignore, the data source does not support transactions and thedriver always operates in auto-commit mode.

If set to noTransactions, the data source and the driver do not supporttransactions.

The default is noTransactions.

TransactionMode on page 201


Connecting Through a Proxy ServerIn some environments, your application may need to connect through a proxy server, for example, if yourapplication accesses an external resource such as a Web service. At a minimum, your application needs toprovide the following connection information when you invoke the JVM if the application connects through aproxy server:

• Server name or IP address of the proxy server

• Port number on which the proxy server is listening for HTTP/HTTPS requests


Connecting Through a Proxy Server

In addition, if authentication is required, your application may need to provide a valid user ID and password forthe proxy server. Consult with your system administrator for the required information.

For example, the following command invokes the JVM while specifying a proxy server named pserver, a portof 808, and provides a user ID and password for authentication:

java -Dhttp.proxyHost=pserver -Dhttp.proxyPort=808 -Dhttp.proxyUser=smith -Dhttp.proxyPassword=secret -cp sforce.jar com.acme.myapp.Main

Alternatively, you can use the ProxyHost, ProxyPort, ProxyUser, and ProxyPassword connection properties.See "Connection Property Descriptions" for details about these properties.


Performance ConsiderationsEnableBulkFetch: The EnableBulkfetch property can be used to improve performance by enabling the driverto use the Salesforce Bulk API for selects. Using the Salesforce Bulk API may significantly reduce the numberof Web service calls used to execute a statement and, therefore, may improve performance. WhenEnableBulkFetch has been set to true, the driver uses the Salesforce Bulk API based on the value of theBulkFetchThreshold connection property. If the number of rows expected in the result set exceeds the valueof BulkFetchThreshold property, the driver uses the Salesforce Bulk API to execute the select operation.

EnableBulkLoad: The EnableBulkLoad property can be used to improve performance by enabling the driverto use the Salesforce Bulk API for inserts, updates, and deletes. Using the Salesforce Bulk API may significantlyreduce the number of Web service calls used to execute a statement and, therefore, may improve performance.When EnableBulkLoad has been set to true, the driver uses the Salesforce Bulk API based on the value ofthe BulkLoadThreshold connection property. If the number of affected rows exceeds the value ofBulkLoadThreshold property, the driver uses the Salesforce Bulk API to execute the insert, update, or deleteoperation.

EnablePKChunking: The EnablePKChunking property can be used to improve performance by enabling thedriver to use PK chunking for bulk fetch operations. When EnablePKChunking is set to true, the driver usesPK chunking to execute the operation if the expected number of rows in the result set is greater than the valuesof the BulkFetchThreshold and PKChunkSize properties. For this behavior to take effect, the EnableBulkFetchproperty must also be set to true.

Note: PK chunking is supported for all custom objects and the following standard objects:Account, Campaign,CampaignMember, Case, Contact, Lead, LoginHistory, Opportunity, Task, and User. In addition,PK chunking is supported for sharing objects as long as the parent object is supported.

FetchSize/WSFetchSize: The connection options FetchSize and WSFetchSize can be used to adjust thetrade-off between throughput and response time. In general, setting larger values for WSFetchSize andFetchSize will improve throughput, but can reduce response time.

For example, if an application attempts to fetch 100,000 rows from the remote data source and WSFetchSizeis set to 500, the driver must make 200 Web service calls to get the 100,000 rows. If, however, WSFetchSizeis set to 2000 (the maximum), the driver only needs to make 50 Web service calls to retrieve 100,000 rows.Web service calls are expensive, so generally, minimizing Web service calls increases throughput. In addition,many Cloud data sources impose limits on the number of Web service calls that can be made in a given periodof time. Minimizing the number of Web service calls used to fetch data also can help prevent exceeding thedata source call limits.



For many applications, throughput is the primary performance measure, but for interactive applications, suchas Web applications, response time (how fast the first set of data is returned) is more important than throughput.For example, suppose that you have a Web application that displays data 50 rows to a page and that, onaverage, you view three or four pages. Response time can be improved by setting FetchSize to 50 (the numberof rows displayed on a page) and WSFetchSize to 200. With these settings, the driver fetches all of the rowsfrom the remote data source that you would typically view in a single Web service call and only processes therows needed to display the first page.

InsensitiveResultSetBufferSize: To improve performance when using scroll-insensitive result sets, the drivercan cache the result set data in memory instead of writing it to disk. By default, the driver caches 2 MB ofinsensitive result set data in memory and writes any remaining result set data to disk. Performance can beimproved by increasing the amount of memory used by the driver before writing data to disk or by forcing thedriver to never write insensitive result set data to disk. The maximum cache size setting is 2 GB.

WSPoolSize: WSPoolSize determines the maximum number of sessions the driver uses when there aremultiple active connections to Salesforce. By increasing this number, you increase the number of sessions thedriver uses to distribute calls to Salesforce, thereby improving throughput and performance. For example, ifWSPoolSize is set to 1, and you have two open connections, the session must complete a call from oneconnection before it can begin processing a call from the other connection. However, if WSPoolSize is equalto 2, a second session is opened that allows calls from both connections to be processed simultaneously.

Note: The number specified for WSPoolSize should not exceed the amount of sessions permitted by yourSalesforce account.

Client-Side CachesThe Salesforce driver can implement a client-side data cache for improved performance. Data is cached fromthe remote data source to the local machine on which the driver is located.

The driver caches data on a per-table basis, as opposed to caching the result of a particular query. This allowsthe caches to be queried, filtered, and sorted in other queries. Once a cache is created, its use is transparentto the application. For example, if a cache is created on the Account table, all subsequent queries that referenceAccount access the Account cache. Disabling or dropping the cache allows references to the Account table toaccess the remote data again. Because the use of the cache is transparent, no changes to the application arerequired to take advantage of the cache.

You must create a cache before it can be populated; caches are not created automatically. After you havecreated a cache on a table, the cache is populated as a result of the next operation on the table. For example,after creating a cache on Account, data is returned from the Salesforce data source and stored locally in thecache when you first execute the following statement:

SELECT ROWID, SYS_NAME FROM Account

Any subsequent queries against the Account table return data from the cache, which reduces response time.SQL queries can access both cached data and remote data (data stored in Salesforce that has not beenassigned to a cache) in the same statement.

The caches maintained by the Salesforce driver are write-through caches. This means that, for any operationthat modifies data in a table that is cached, the driver performs the operation on the remote data first and thenupdates the cache.

To create, modify, refresh, or delete client-side data caches, use the following SQL statement extensions:

• Create Cache

• Alter Cache


Client-Side Caches

• Refresh Cache

• Drop Cache

See "Supported SQL Statements and Extensions" for descriptions of the syntax of these extensions.

See alsoSupported SQL Statements and Extensions on page 221

Creating a Cache

You create a cache using the Create Cache statement (see "Create Cache (EXT)"). A cache can be createdon a single table or on a set of related tables. When creating a cache on a single table, you specify the nameof the table to cache and optionally a filter for the table. The filter determines whether the cache holds all thedata in the remote table or a subset of the data that matches the filter.You can also specify attributes for theCreate Cache statement that determine:

• Whether the cache data is held on disk or in memory

• How often the cache data is refreshed

• If the cache is initially enabled

• If the driver checks to see if a refresh is needed at connect time

Creating a cache for a set of related tables is similar to creating a cache on a single table, except that a primarytable and one or more referencing tables are specified. This is useful if you want to cache a subset of data fora table and also cache data related to that subset of data. For example, suppose you have three tables (namedAccount, Contact, and Opportunity), where both a contact and an opportunity belong to a particular account.Using a relational cache, you could specify that accounts that have had activity in the past year be cached, aswell as caching the opportunities and contacts for only those cached accounts.

See alsoCreate Cache (EXT) on page 232

Modifying a Cache Definition

Once a cache has been created, you can modify the definition of the cache or set of related caches with theAlter Cache statement (see Alter Cache (EXT)). Only the attributes of the cache can be modified through theAlter Cache statement; the table or related set of tables cannot be changed and a single table cache cannotbe changed to a relational cache.

warning: Changing the attributes of a cache may cause the current data in the cache to be discarded andrefetched from the remote data source.

See alsoAlter Cache (EXT) on page 222



Disabling and Enabling a CacheWhen a cache is defined on a table, all fetch operations performed on that table access the cache, essentiallyhiding the remote table from the application. At times, you may want an application to query the remote datainstead of the cached data.

Assume that a cache was created on the Account table with a filter set to cache accounts that have had activityin the past year. If you want to run a query to get information about an account that has not been active for twoyears, you can drop the Account cache, run the query, and then recreate the cache on Account, but this canbe problematic. First, you must recreate the cache and make sure it had the same attributes as before. Second,the data in the cache is discarded and needs to be refetched when the cache is recreated. Depending on theamount of cached data, this could take a significant amount of time.

A better alternative is to temporarily disable a cache. When a cache is disabled, its definition and data aremaintained. Any queries that reference a table with a disabled cache access the remote table. When you wantto access cached data again, the cache can be enabled.

Refreshing Cache DataTo prevent the data in a cache from becoming out of date, the driver periodically refreshes the cache data withdata from the remote data source. To minimize the amount of data that needs to be moved when a cache isrefreshed, and the time required to refresh it, the driver checks to see which records in the remote table havebeen added, modified, or deleted since the last time the cache was refreshed. The driver retrieves only datafor added or modified records and removes only deleted records from the cache.Your application can explicitlyrefresh the cache or the driver can refresh the cache automatically.

You can refresh a cache explicitly at any time by using the Refresh Cache statement (see Refresh Cache(EXT)). The Refresh Cache statement can also be used to perform a Clean (complete) refresh in addition tothe standard optimized refresh. A Clean refresh discards all the data from the cache and repopulates it withdata from the remote data source.

The driver also can refresh a cache automatically. When you create a cache, one of the attributes that you setis the refresh interval for the cache. During each cache query, the driver checks to see whether the time elapsedsince the last refresh has exceeded the refresh interval for the cache. If it has, the driver refreshes the cachebefore satisfying the query.

Update operations to a table that is cached can trigger the driver to refresh the cache automatically.The cachesmaintained by the Salesforce driver are write-through caches. For any operation that modifies data in a tablethat is cached, the driver performs the operation on the remote data first and then updates the cache. Thedriver may not be able to update the cache with all modifications because some of the modified data may havebeen generated by the remote data source. For example, if a row is inserted but a value for all columns in therow is not required, any default values generated by the remote data source for columns not specified in theInsert statement would not be set in the cache. Because the driver cannot reflect all the changes made whena cached table is modified, it sets the cache state to dirty. When a cache state is dirty, the next query thatattempts to fetch data from that cache causes the driver to refresh the cache before the fetch operation isperformed. This allows the fetch to access the values populated by the remote data source.

The state of a cache can be viewed by selecting the STATUS column of theINFORMATION_SCHEMA.SYSTEM_CACHES table. See "SYSTEM_CACHES Catalog Table" for moreinformation.

See alsoRefresh Cache (EXT) on page 258SYSTEM_CACHES Catalog Table on page 76


Client-Side Caches

Dropping a Cache

You can drop an existing cache using the Drop Cache statement (see Drop Cache (EXT)). If a cache is arelational cache, the Drop Cache statement drops the cache for the primary table as well as the caches for therelated tables.

Note: When a cache is dropped, all the data in that cache is discarded.

See alsoDrop Cache (EXT) on page 253

Caching MetaData

The Salesforce driver maintains information about the caches that have been created. The driver provides twosystem tables to expose the cache information:

• SYSTEM_CACHES

• SYSTEM_CACHE_REFERENCES

Both system tables are in the INFORMATION_SCHEMA schema. See "Catalog Tables" for a completedescription of the contents of these system tables.

See alsoCatalog Tables on page 76

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

The driver also provides additional catalog tables that maintain metadata specific to the Salesforce driver.Thissection defines the catalog tables that provide Salesforce driver-specific information. The catalog tables aredefined in the INFORMATION_SCHEMA schema.

SYSTEM_CACHES Catalog Table

The SYSTEM_CACHES catalog table stores the definitions of the caches created on remote tables. The datain the SYSTEM_CACHES table provides the name, type (single table or relational), status, and other informationfor each defined cache.The table name returned for a remote relational cache is the name of the primary tableof the relational cache; however, its type is REMOTE RELATIONAL.You can query SYSTEM_CACHES todetermine the caches currently defined by the driver.The values in the SYSTEM_CACHES table are read-only.The referenced tables of a relational cache can be determined by querying theSYSTEM_CACHE_REFERENCES catalog table (see "SYSTEM_CACHE_REFERENCES Catalog Table").

The following table describes the columns of the SYSTEM_CACHES table, which is sorted on the followingcolumns: CACHE_TYPE, TABLE_SCHEMA, and TABLE_NAME.



Table 13: SYSTEM_CACHES Catalog Table

DescriptionData TypeColumn Name

The catalog that contains the remote table on which the cacheis defined. It is NULL for the Salesforce driver.

VARCHAR(128),NULLABLE

TABLE_CAT

The schema that contains the remote table on which thecache is defined.

VARCHAR(128),NULLABLE

TABLE_SCHEM

The name of the remote table on which the cache is defined.VARCHAR(128),NOT NULL

TABLE_NAME

The type cache, which can be either REMOTE TABLE orREMOTE RELATIONAL.

VARCHAR(20),NOT NULL

CACHE_TYPE

The refresh interval (in minutes).INTEGER, NOTNULL

REFRESH_INTERVAL

The value that defines when the initial refresh check isperformed: ONFIRSTCONNECT or FIRSTUSE.


INITIAL_CHECK

The value that defines whether the data in the cache ispersisted past the lifetime of the connection: TEMPORARY,MEMORY, or DISK.


PERSIST

The value that defines whether the cache is enabled for usewith SQL statements: TRUE or FALSE.

BOOLEAN, NOTNULL

ENABLED

The maximum number of Web service calls that can be madewhen refreshing the cache.The value 0 indicates no call limit.

INTEGER, NOTNULL

CALL_LIMIT

For internal use only.INTEGER, NOTNULL

REFRESH_MODE

The Where clause used to filter the rows that are cached.VARCHAR(128),NULLABLE

FILTER

The time, in Coordinated Universal Time (UTC), the cachewas last refreshed.

DATETIME,NULLABLE

LAST_REFRESH

The Cache status.Valid values are:New:The cache has beencreated, but the data has not been populated.Initialized:The cache has been created and the data has beenpopulated.Load aborted: The cache has been created,but the last attempt to populate the data failed. The cache isstill valid. The next access attempts to populate the dataagain.Invalid: The cache is invalid. The second attemptto populate the data failed.Dirty: An insert or updateoperation has been performed on the cache and the cachehas not been refreshed.

VARCHAR(30)STATUS


Catalog Tables

See alsoSYSTEM_CACHE_REFERENCES Catalog Table on page 78

SYSTEM_CACHE_REFERENCES Catalog Table

The referenced tables in a relational cache can be determined by querying the SYSTEM_CACHE_REFERENCESsystem table. This table contains the names of the referenced tables as well as the name of the primary tablewith which they are associated.

The following table defines the columns of the SYSTEM_CACHE_REFERENCES table, which is sorted onthe following columns: TABLE_SCHEMA, TABLE_NAME, and REF_TABLE_NAME.

Table 14: SYSTEM_CACHE_REFERENCES Catalog Table

DescriptionData TypeColumn

The catalog that contains the primary table of therelational cache. It is NULL for the Salesforce driver.

VARCHAR (128),NULLABLE

PRIMARY_TABLE_CAT

The schema that contains the primary table of therelational cache.

VARCHAR (128),NULLABLE

PRIMARY_TABLE_SCHEM

The primary table of the relational cache.VARCHAR (128),NOT NULL

PRIMARY_TABLE_NAME

The name of the referenced table.VARCHAR (128),NOT NULL

REF_TABLE_NAME

The name of the foreign key relationship used to relatethis table to the primary table or one of the other tablesin the relational cache.


RELATIONSHIP_NAME

SYSTEM_REMOTE_SESSIONS Catalog Table

The system table named SYSTEM_REMOTE_SESSIONS stores information about the each of the remotesessions that are active for a given database. The values in the SYSTEM_REMOTE_SESSION table areread-only.

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

Table 15: SYSTEM_REMOTE_SESSIONS Catalog Table


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

INTEGER,NOT NULL

SESSION_ID

The schema name that is mapped to theremote session.


SCHEMA




The remote session type. The current validtype is Salesforce.


TYPE

The remote session instance name or null ifthe remote data source does not have multipleinstances.The Salesforce value for INSTANCEhas the following form:Organization_Name[Sandbox]where Organization_Name is theorganization name of the Salesforce instanceto which the connection is established. If theconnection is established to a sandbox of theorganization, then the word Sandbox is addedto the end of the name.

VARCHAR(128)INSTANCE

The version of the remote data source to whichthe session is connected. For Salesforce, thisis the version of the Web Service API the driveris using to connect to Salesforce.


VERSION

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

LONGVARCHAR,NOT NULL

CONFIG_OPTIONS

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

LONGVARCHAR,NOT NULL

SESSION_OPTIONS

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

INTEGER,NOT NULL

WS_CALL_COUNT

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

INTEGER,NOT NULL

WS_AGGREGATE_CALL_COUNT

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

INTEGER,NOT NULL

REST_AGGREGATE_CALL_COUNT

SYSTEM_SESSIONS Catalog Table

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

The following table defines the columns of the SYSTEM_SESSIONS table.


Catalog Tables

Table 16: SYSTEM_SESSIONS Catalog Table


A unique ID that identifies this session. The system functionCURSESSIONID( ) returns the session ID associated with theconnection. See "Functions" for more information about theCURSESSIONID() system function.

INTEGER,NOT NULL

SESSION_ID

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

CONNECTED

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

USERNAME

For internal use only.BOOLEANIS_ADMIN

For future use.BOOLEAN,NOT NULL

AUTOCOMMIT

True if the connection is in read-only mode. The READONLYstatus is based on whether the connection has been explicitlyset to read-only mode by the ReadOnly connection option orthe Connection.setReadOnly() method.

BOOLEAN,NOT NULL

READONLY

For future use.INTEGER,NOT NULL

MAX_ROWS

For future use.BIGINT,NULLABLE

LAST_IDENTITY

For future use.INTEGER,NOT NULL

TRANSACTION_SIZE

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

VARCHAR (128),NOT NULL

CURRENT_SCHEMA

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

INTEGER,NOT NULL

STMT_CALL_LIMIT

See alsoFunctions on page 277



ReportsThe driver exposes reports defined on a Salesforce instance as stored procedures. An application can obtaina list of the reports defined on a Salesforce instance by calling the DatabaseMetaData.getProcedures method.The names of the reports that can be invoked through the driver are listed in the PROCEDURE_NAME namecolumn of the getProcedures() results.

Salesforce organizes reports into folders. The Salesforce driver incorporates the folder name and report nameinto the procedure name reported by getProcedures(). The driver creates the reported procedure name byprepending the folder name to the report name using an underscore (_) to join them. Additionally, any spacesin the report or folder names are replaced with an underscore character. Like all identifier name metadatareturned by the driver, the procedure name is uppercase. For example, if a report named Opportunity Pipelineis in the folder Opportunity Reports, it would be:

OPPORTUNITY_REPORTS_OPPORTUNITY_PIPELINE

An application invokes a report using the standard Call escape syntax, {call report name}, and JDBCmechanisms for calling a stored procedure that returns a result set. The following example shows one way toinvoke the Opportunity Pipeline report:

String sql = "{call OPPORTUNITY_REPORTS_OPPORTUNITY_PIPELINE()}";CallableStatement callStmt = con.prepareCall(sql);boolean isResultSet = callStmt.execute();if (isResultSet) { resultSet = callStmt.getResultSet(); // process the resultset}

Note: The API used by the driver to obtain the list of reports and execute the reports is not an API that isdocumented by Salesforce. This API may change or may not be supported in the future.

Note: When passing parameters to stored procedures, reports are not supported.

AuthenticationAuthentication ensures that only the authorized users are allowed to connect to a Salesforce instance.

The Salesforce driver supports the following methods of authentication:

• User ID/password authentication authenticates the user to a Salesforce instance using the user ID andpassword specified by the application.

• OAuth 2.0 authentication allows the user to authenticate to a Salesforce instance without having to specifyuser ID and password.

See alsoUsing Connection Properties on page 56Authentication Properties on page 58


Reports

Configuring user ID/password authentication

Take the following steps to configure user ID/password authentication.

1. Set the AuthenticationMethod property to userIDPassword.

2. Set the User property to provide the user ID.

3. Set the Password property to provide the password.

See alsoAuthenticationMethod on page 164

Configuring OAuth 2.0 authentication

The driver supports OAuth 2.0, which is an open protocol for token-based authentication. OAuth 2.0 allowsyou to authenticate without specifying a user ID or password, eliminating the risk of exposing them tounauthorized access. It uses an access token, accompanied by the values discussed below, to authenticateto a Salesforce instance. Refer to the Salesforce documentation to know how to obtain an access token.

To configure the driver to use OAuth 2.0 authentication, set the following connection properties:

• Set the AuthenticationMethod property to oauth2.0.

• Set at least one of the following properties:

• AccessToken: Set this to specify the access token you have obtained from Salesforce.

• RefreshToken: Set this to specify the refresh token you have obtained from Salesforce.

If a value for the AccessToken property is not specified, the driver uses the value of the RefreshTokenproperty to make a connection. If both values are not specified, the driver cannot make a successfulconnection. If both are specified, the driver ignores the AccessToken value and uses the RefreshTokenvalue to generate a new AccessToken value.

• Set the ClientID property to specify the consumer key for your application.

• Set the SchemaMap property to specify either the name or the absolute path and name of the configurationfile where the map of the Salesforce data model is written. Note that a value for the SchemaMap propertymust be specified every time you authenticate to a Salesforce instance using OAuth 2.0.

• Optionally, set the ClientSecret property to specify the consumer secret for your application.

The following example shows how to connect to a Salesforce instance using OAuth 2.0 authentication.

Connection conn = DriverManager.getConnection("jdbc:datadirect:sforce://login.salesforce.com;AuthenticationMethod=oauth2.0;SchemaMap=ABC;clientId=RaARBTsXZTeN4Qx67qPLOS;RefreshToken=YaTARBsRZLeM4Px47qSOLP;AccessToken=ZbTARBsRZLeM4Px56qOLPS;","","");

See alsoAuthenticationMethod on page 164AccessToken on page 163RefreshToken on page 194ClientID on page 170



SchemaMap on page 195ClientSecret on page 171

Data EncryptionAll communication between the driver and Salesforce, including user ID/password authentication, is encryptedusing Secure Sockets Layer (SSL). See "Using Connection Properties" for information on specifying a user IDand Password.

See alsoUsing Connection Properties on page 56

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

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

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

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

Failover SupportThe driver provides connection failover support to ensure continuous, uninterrupted access to data. Connectionfailover provides failover protection for new connections. In more traditional scenarios, the driver fails over newconnections to an alternate, or backup, database server if the primary database server is unavailable. However,Salesforce currently supports only the notion of a single leader node. Therefore, to ensure a continuousconnection, you only need to set the ConnectionRetryCount and ConnectionRetryDelay connection properties.

See alsoFailover Properties on page 60ConnectionRetryCount on page 177ConnectionRetryDelay on page 178


Data Encryption

IP AddressesThe driver supports Internet Protocol (IP) addresses in IPv4 and IPv6 format.

The server name specified in the connection URL, or data source, can resolve to an IPv4 or IPv6 address. Forexample, the following URL can resolve to either type of address:


Note: The server name specifies the base Salesforce URL to use for logging in, for example,login.salesforce.com.

Alternately, you can specify addresses using IPv4 or IPv6 format in the server portion of the connection URL.For example, the following connection URL specifies the server using an IPv4 address:

jdbc:datadirect:sforce://123.456.78.90;[email protected]; Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS

You also can specify addresses in either format using the ServerName data source property. The followingexample shows a data source definition that specifies the server name using IPv6 format:

SalesforceDataSource mds = new SalesforceDataSource(); mds.setDescription("My SalesforceDataSource"); mds.setServerName("[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]"); ...

Note: When specifying IPv6 addresses in a connection URL or data source property, the address must beenclosed by brackets.

In addition to the normal IPv6 format, the drivers support IPv6 alternative formats for compressed and IPv4/IPv6combination addresses. For example, the following connection URL specifies the server using IPv6 format,but uses the compressed syntax for strings of zero bits:

jdbc:datadirect:sforce://[2001:DB8:0:0:8:800:200C:417A];[email protected]; Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS

Similarly, the following connection URL specifies the server using a combination of IPv4 and IPv6:

jdbc:datadirect:sforce://[0000:0000:0000:0000:0000:FFFF:123.456.78.90];[email protected];

Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS

For complete information about IPv6, go to the following URL:

http://tools.ietf.org/html/rfc4291#section-2.2

See alsoServerName on page 198



http://tools.ietf.org/html/rfc4291#section-2.2

TimeoutsThe driver supports the LoginTimeout, WSTimeout, and WSRetryCount connection properties.The LoginTimeoutproperty specifies the amount of time, in seconds, that the driver waits for a connection to be established beforetiming out the connection request. In contrast, the WSTimeout property specifies the time, in seconds, that thedriver waits for a response to a Web service request. The WSTimeout property can be used in conjunctionwith the WSRetryCount property. The WSRetryCount connection property can be used to retry select queriesthat have timed out.

Session TimeoutsMost remote data sources impose a limit on the duration of active sessions, meaning a session can fail with asession timeout error if the session extends past the limit. This is particularly true when connection pooling isused. The driver automatically attempts to re-establish a new session if the driver receives a session timeouterror from a data source. The driver uses the initial server name, remote user ID, and remote password tore-establish the session. If the attempt fails, the driver returns an error indicating that the session timed outand the attempt to re-establish the session failed.

Web Service Request TimeoutsYou can configure the driver to never time out while waiting for a response to a Web service request or to waitfor a specified interval before timing out by setting the WSTimeout connection property. For fetch requests,you can configure the driver to retry the request a specified number of times by setting the WSRetryCountconnection property. If subsequent attempts to retry a request fail, the driver returns an error indicating thatthe service request timed out and the subsequent requests failed.

See alsoTimeout Properties on page 66Connection Pool Manager on page 91

Views and Remote/Local TablesYou can create views with the Create View statement. A view is like a named query. The view can refer to anycombination of remote and local tables as well as other views.

You can create a remote or local table using the Create Table statement. A remote table is a Salesforce objectand is exposed in the SFORCE schema. A local table is maintained by the driver and is local to the machine onwhich the driver is running. A local table is exposed in the PUBLIC schema.

See "Supported SQL Statements and Extensions" for details on the Create View and Create Table statementsand other SQL statements supported by the driver.


SQL escape sequencesThe driver supports the following SQL escape sequences.


Timeouts

• Date, Time, and Timestamp Escape Sequences

• Scalar Functions

• Outer Join Escape Sequences

• LIKE Escape Character Sequence for Wildcards

See "SQL escape sequences for JDBC" for more information.

See alsoSQL escape sequences for JDBC on page 281

Isolation LevelsThe driver supports the TRANSACTION_NONE isolation level because Salesforce does not support transactions.However, manual transactions can be handled to some degree with the TransactionMode connection property.

See alsoTransactionMode on page 201

Scrollable cursorsThe driver supports scroll-insensitive result sets and updatable result sets.

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

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

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



Error Handling

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

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

• Native error code (if applicable)

• String containing the XOPEN SQLstate

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

[DataDirect][Salesforce JDBC Driver]Timeout expired.

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

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

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

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

Large Object (LOB) SupportThe Salesforce driver allows you to retrieve and update long data, specifically LONGVARBINARY andLONGVARCHAR data, using JDBC methods designed for Blobs and Clobs. When using these methods toupdate long data as Blobs or Clobs, the updates are made to the local copy of the data contained in the Blobor Clob object.

Retrieving and updating long data using JDBC methods designed for Blobs and Clobs provides some of thesame benefits as retrieving and updating Blobs and Clobs, such as:

• Provides random access to data

• Allows searching for patterns in the data, such as retrieving long data that begins with a specific characterstring

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


Error Handling

Parameter Metadata SupportThe driver supports returning parameter metadata as described in "Insert and Update Statements" and "SelectStatements."

Insert and Update Statements

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

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

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

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

where:

operator

is any of the following SQL operators:

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

Select Statements

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

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

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

SELECT * FROM foo WHERE bar > ?

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

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

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

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

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



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

SELECT * FROM t1 WHERE col = ? ORDER BY 1

Joins are supported. For example:

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

Fully qualified names and aliases are supported. For example:

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

ResultSet MetaData SupportIf your application requires table name information, the Salesforce driver can return table name information inResultSet metadata for Select statements. The Select statements for which ResultSet metadata is returnedmay contain aliases, joins, and fully qualified names. The following queries are examples of Select statementsfor which the ResultSetMetaData.getTableName() method returns the correct table name for columns in theSelect list:

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

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

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

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

SELECT * FROM test.foo

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

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

• CachedRowSets

• FilteredRowSets


ResultSet MetaData Support

• WebRowSets

• JoinRowSets

• JDBCRowSets

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

Auto-Generated Keys SupportThe Salesforce driver supports retrieving the values of auto-generated keys. An auto-generated key returnedby the Salesforce driver is the value of an auto-increment column.

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

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

• Statement.execute(String sql, int autoGeneratedKeys)

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

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

• Statement.executeUpdate(String sql, int autoGeneratedKeys)

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

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

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

• Connection.prepareStatement(String sql, int autoGeneratedKeys)

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

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

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

See "Designing JDBC Applications for Performance Optimization" in the for more information.

See alsoDesigning JDBC applications for performance optimization on page 361



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

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 works

Typically, 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 pooling

1. 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 pooling

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


Connection Pool Manager

An application may use only one data source, but allow multiple users, each with their own set of logincredentials. The connection pool contains connections for all unique users using the same data source asshown in the following 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 theJNDI naming 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.



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.

Implementing DataDirect connection pooling

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

Note: The DataSource class implements the ConnectionPoolDataSource interface for pooling in additionto the DataSource interface for non-pooling.

//************************************************************************// 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/ConnectSalesforce>.//// 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.sforce.SForceDataSource;public class SalesforceDataSourceRegisterJNDI {public static void main(String argv[]) { try {

// Set up data source reference data for naming context: // ---------------------------------------------------- // Create a class instance that implements the interface // ConnectionPoolDataSource SForceDataSource ds = new SForceDataSource(); ds.setDescription("Salesforce"); ds.setUser("scott"); ds.setPassword("test"); ds.setLoginHost("login.salesforce.com"); ds.setSecurityToken("XaBARTsLZReM4Px47qPLOS");

// Set up environment for creating initial context Hashtable 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 service ctx.bind("jdbc/ConnectSalesforce", ds); } catch (Exception e) { System.out.println(e.getStackTrace()); e.printStackTrace(); return; } }// Main}// class SalesforceDataSourceRegisterJNDI

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.

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/ConnectSalesforce>.//// 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 DataSource PooledConnectionDataSource ds = new PooledConnectionDataSource();

ds.setDescription("Salesforce data source");

// Specify a registered driver DataSource object to be used // by this data source to create pooled connections ds.setDataSourceName("jdbc/ConnectSalesforce");

// The pool manager will be initiated with 5 physical connections ds.setInitialPoolSize(5);

// The pool maintenance thread will make sure that there are 5 // physical connections available ds.setMinPoolSize(5);

// The pool maintenance thread will check that there are no more // than 10 physical connections available ds.setMaxPoolSize(10);

// The pool maintenance thread will wake up and check the pool // every 20 seconds ds.setPropertyCycle(20);

// The pool maintenance thread will remove physical connections // that are inactive for more than 300 seconds ds.setMaxIdleTime(300);

// Set tracing off because we choose not to see an output listing // of activities on a connection ds.setTracing(false);

// Set up environment for creating initial context Hashtable 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 service ctx.bind("jdbc/SparkyOracle", ds);

catch (Exception e) { System.out.println(e); return; } }}

See alsoCreating a Driver DataSource Object on page 93PooledConnectionDataSource on page 99

Configuring the connection pool

You 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 99

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:

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

Connecting Using a Connection Pool

Because 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 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/Salesforce>//********************************************************************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 source int 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"); 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 object env = 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 name ctx = 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 time nStartTime = System.currentTimeMillis(); for (int j = 1; j <= nCount[i]; j++) { // Get Database Connection



try { con = ds.getConnection("scott", "tiger"); // Do something with the connection // ... // Close Database Connection if (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 time nStopTime = System.currentTimeMillis(); // Compute elapsed time nElapsedTime = nStopTime - nStartTime; System.out.println("Test number " + i + ": looping " + nCount[i] + " times"); System.out.println("Elapsed Time: " + nElapsedTime + "\n"); } // for i loop // All done System.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/ConnectSalesforce

See alsoCreating the connection poolCreating a Driver DataSource Object on page 93

Closing the connection pool

The 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 version

To 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 tracing

You 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 211

Connection Pool Manager interfaces

This section describes the methods used by the DataDirect Connection Pool Manager interfaces:PooledConnectionDataSourceFactory, PooledConnectionDataSource, andConnectionPoolMonitor.

PooledConnectionDataSourceFactoryThe PooledConnectionDataSourceFactory interface is used to create a PooledConnectionDataSourceobject 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 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()

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.

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)

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)

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

See alsoConfiguring the maximum pool size on page 96

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



DescriptionConnectionPoolMonitor Methods

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

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 avalue greater than zero (0).

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.

See alsoMaxPooledStatements on page 188

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 17: poolEntries() Parameters

DescriptionValueParameter

Returns only prepared statementsExtStatementPoolMonitor.TYPE_PREPARED_STATEMENTstatementType

Returns only callable statementsExtStatementPoolMonitor.TYPE_CALLABLE_STATEMENT

Returns all statements regardlessof statement type

-1

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


Statement Pool Monitor

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.

private void run(String[] args) { Connection con = null; PreparedStatement prepStmt = null; String sql = null; try { // Create the connection and enable statement pooling Class.forName("com.ddtek.jdbc.sforce.SForceDriver"); con = DriverManager.getConnection( "jdbc:datadirect:sforce://login.salesforce.com;" + "RegisterStatementPoolMonitorMBean=true", "maxPooledStatements=10", "test", "test"); // Prepare a couple of statements sql = "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 Monitor

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

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 MBean for (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(";"); System.out.println(" " + stmt.substring(0, index)); } } } } catch (Throwable except) { System.out.println("ERROR: " + except); }}

See alsoMaxPooledStatements on page 188RegisterStatementPoolMonitorMBean on page 195

Importing Statements into a Statement Pool

When 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:sforce://login.salesforce.com; [email protected];Password=secret; SecurityToken=XaBARTsLZReM4Px47qPLOS; 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 215Generating a statement pool export file on page 109

Clearing all statements in a statement pool

To 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 pool

Freezing 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 file

You 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 215

DataDirect Statement Pool Monitor interfaces and classes

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

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 inthe pool at the time the pool was frozen. Freezing a poolis useful if you have a core set of statements that you donot want 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)

DataDirect Bulk LoadIn addition to supporting bulk operations via the Salesforce Bulk API, the driver supports DataDirect Bulk Load.DataDirect Bulk Load allows you to perform bulk load operations by creating a DDBulkLoad object and usingthe methods provided by the DDBulkLoad interface in the com.ddtek.jdbc.extensions package for bulkload.You may want to use this method if you are developing a new application that needs to perform bulk loadoperations.

Important: Because a bulk load operation may bypass data integrity checks, your application must ensurethat the data it is transferring does not violate integrity constraints in the database. For example, suppose youare bulk loading data into a database table and some of that data duplicates data stored as a primary key,which must be unique. The driver will not throw an exception to alert you to the error; your application mustprovide its own data integrity checks.

See alsoBulk API Properties on page 63

Using a DDBulkLoad Object

The first step in performing a bulk load operation using a DDBulkLoad object is to create a DDBulkLoadobject. A DDBulkLoad must be created with the getInstance method using the DDBulkLoadFactoryclass as shown in the following example.

import com.ddtek.jdbc.extensions.*// Get Salesforce ConnectionConnection con = DriverManager.getConnection( "jdbc:datadirect:sforce://login.salesforce.com;[email protected]; Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS");

// Get a DDBulkLoad objectDDBulkLoad bulkLoad = com.ddtek.jdbc.extensions.DDBulkLoadFactory.getInstance(con);



Once the DDBulkLoad object has been created, DDBulkLoad methods can be used to instruct the driver toobtain data from one location and load it to another location.The driver can obtain data either from a ResultSetobject or from a CSV file.

Migrating Data Using a ResultSet ObjectThe following steps would need to be taken to migrate data from Oracle to Salesforce using a ResultSetobject.

Important: This scenario assumes that you are using the DataDirect Oracle driver to query the Oracle databaseand the DataDirect Salesforce driver to insert data on the Salesforce data store.

1. The application creates a DDBulkLoad object.

2. The application executes a standard query on the Oracle database, and the Oracle driver retrieves theresults as a ResultSet object.

3. The application instructs the Salesforce driver to load the data from the ResultSet object into Salesforce.(See "Loading Data From a ResultSet Object".)

Migrating Data Using a CSV FileThe following steps would need to be taken to migrate data from Oracle to Salesforce using a CSV file.

1. The application creates a DDBulkLoad object.

2. The application instructs the Oracle driver to export the data from the Oracle database into a CSV file. (See"Exporting Data to a CSV File.")

3. The application instructs the Salesforce driver to load data from the CSV file into Salesforce. (See "LoadingData From a CSV File.")

See alsoCSV files on page 116JDBC extensions on page 345Permissions for bulk load from a CSV file on page 46

Exporting data to a CSV fileUsing a BulkLoad object, data can be exported either as a table or ResultSet object.

Exporting Data as a TableTo export data as a table, the application must specify the table name with the setTableName method andthen export the data to a CSV file using the export method. For example, the following code snippet specifiesthe GBMAXTABLE table and exports it to a CSV file called tmp.csv.

bulkLoad.setTableName("GBMAXTABLE");bulkLoad.export("tmp.csv");

Alternatively, you can create a file reference to the CSV file and use the export method to specify the filereference. For example:

File csvFile = new File ("tmp.csv");bulkLoad.export(csvFile);


DataDirect Bulk Load

Exporting Data as a ResultSet objectTo export data as a ResultSet object, the application must first create a file reference to a CSV file, and then,using the export method, specify the ResultSet object and the file reference. For example, the followingcode snippet creates the tmp.csv file reference and then specifies MyResults (the ResultSet object beexported).

File csvFile = new File ("tmp.csv");bulkLoad.export(MyResults, csvFile);

If the CSV file does not already exist, the driver creates it when the export method is executed. The driveralso creates a bulk load configuration file, which describes the structure of the CSV file.

For more information about bulk load methods, refer to JDBC extensions in the Progress DataDirect for JDBCDrivers Reference.

See alsoCSV files on page 116Permissions for bulk load from a CSV file on page 46

Loading Data from a ResultSet ObjectThe setTableName method should be used to specify the table into which you want to load the data. Then,the load method is used to specify the ResultSet object that contains the data you are loading. For example,the following code snippet loads data from a ResultSet object named MyResults into a table namedGBMAXTABLE

bulkLoad.setTableName("GBMAXTABLE");bulkLoad.load(MyResults);

This example loads the first column in the result set to the ColName1 column, the second column in the resultset to the ColName2 column, and so on.

You can use the BulkLoadBatchSize property to specify the number of rows the driver loads at a time whenbulk loading data. Performance can be improved by increasing the number of rows the driver loads at a timebecause fewer network round trips are required. Be aware that increasing the number of rows that are loadedalso causes the driver to consume more memory on the client.

See alsoBulkLoadBatchSize on page 167JDBC extensions on page 345

Loading Data from a CSV FileThe setTableName method should be used to specify the table into which you want to load the data. Then,the load method is used to specify the CSV file that contains the data you are loading. For example:

bulkLoad.setTableName("GBMAXTABLE");bulkLoad.load("tmp.csv");

Alternatively, you can create a file reference to the CSV file, and use the load() method to specify the filereference:

File csvFile = new File("tmp.csv");bulkLoad.load(csvFile);



../../datadirect-jdbc-reference/page/JDBC-extensions.html

For the Salesforce driver, you also can specify the columns to which you want to load the data. This exampleloads the first column in the CSV file to the ColName1 column, the second column in the CSV file to theColName2 column, and the third column in the CSV file to the ColName3 column:

bulkLoad.setTableName("GBMAXTABLE(ColName1, ColName2, ColName3)");bulkLoad.load("tmp.csv");

Use the BulkLoadBatchSize property to specify the number of rows the driver loads at a time when bulk loadingdata. Performance can be improved by increasing the number of rows the driver loads at a time because fewernetwork round trips are required. Be aware that increasing the number of rows that are loaded also causes thedriver to consume more memory on the client. See "JDBC Extensions" for more information about bulk loadmethods.

See alsoCSV files on page 116BulkLoadBatchSize on page 167JDBC extensions on page 345

Specifying the bulk load operationYou can specify which type of bulk load operation will be performed when a load method is called by settingthe operation property using the setProperties method of the DDBulkLoad interface.The operation propertyaccepts the following values: insert, update, delete and upsert. The default value is insert.

The following example changes the type of bulk load operation to update.

DDBulkLoad bulkLoad =com.ddtek.jdbc.extensions.DDBulkLoadFactory.getInstance(connection);Properties props = new Properties();props.put("operation", "update");bulkLoad.setProperties(props);

For more information about bulk load methods, refer to JDBC extensions in the Progress DataDirect for JDBCDrivers Reference.

LoggingIf logging is enabled for bulk load, a log file records information for each bulk load operation. Logging is enabledby specifying a file name and location for the log file using the setLogFile method.

The log file records the following types of information about each bulk load operation.

• Total number of rows that were read

• Total number of rows that successfully loaded

Note: The total number of rows that successfully loaded is not provided for Microsoft Azure SynapseAnalytics or Microsoft Analytics Platform System.

• Total number of rows that failed to load

For example, the following log file shows that the 11 rows read were all successfully loaded.

/*----- Load Started: <Feb 25, 2009 11:20:09 AM EST>---------------------*/Total number of rows read 11Total number of rows successfully loaded 11Total number of rows that failed to load 0


DataDirect Bulk Load

../../datadirect-jdbc-reference/page/JDBC-extensions.html

Enabling Logging on WindowsTo enable logging using a log file named bulk_load.log located in the C:\temp directory, you would specify:

bulkLoad.setLogFile(C:\\temp\\bulk_load.log)

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: C:\\temp\\bulk_load.log.

Enabling Logging on UNIX/LinuxTo enable logging using a log file named bulk_load.log located in the /tmp directory, you would specify:

bulkLoad.setLogFile(/tmp/bulk_load.log)

CSV filesAs described in "Exporting data to a CSV file," the driver can create a CSV file by exporting data from a tableor ResultSet object. For example, suppose you want to export data from a 4-column table named GBMAXTABLEinto a CSV file. The contents of the CSV file, named GBMAXTABLE.csv, might look like the following example:

1,0x6263,"bc","bc"2,0x636465,"cde","cde"3,0x64656667,"defg","defg"4,0x6566676869,"efghi","efghi"5,0x666768696a6b,"fghijk","fghijk"6,0x6768696a6b6c6d,"ghijklm","ghijklm"7,0x68696a6b6c6d6e6f,"hijklmno","hijklmno"8,0x696a6b6c6d6e6f7071,"ijklmnopq","ijklmnopq"9,0x6a6b6c6d6e6f70717273,"jklmnopqrs","jklmnopqrs"10,0x6b,"k","k"

See alsoExporting data to a CSV file on page 113

Bulk load configuration file

Each time data is exported to a CSV file, a bulk load configuration file is created. This file has the same nameas the CSV file, but with an .xml extension (for example, GBMAXTABLE.xml).

In its metadata, the bulk load configuration file defines the names and data types of the columns in the CSVfile based on those in the table or ResultSet object. It also defines other data properties, such as the sourcecode page for character data types, precision and scale for numeric data types, and nullability for all data types.The format of GBMAXTABLE.xml might look like the following example.

Note: If the driver cannot read a bulk load configuration file (for example, because it was inadvertently deleted),the driver reads all data as character data. The character set used by the driver is UTF-8.

<?xml version="1.0" encoding="utf-8"?><table codepage="UTF-8" xsi:noNamespaceSchemaLocation="https://documentation.progress.com/output/DataDirect/collateral/BulkData.xsd"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">



<row> <column datatype="DECIMAL" precision="38" scale="0" nullable="false"> INTEGERCOL</column> <column datatype="VARBINARY" length="10"nullable="true">VARBINCOL</column> <column datatype="VARCHAR" length="10" sourcecodepage="Windows-1252" externalfilecodepage="Windows-1252"nullable="true">VCHARCOL</column> <column datatype="VARCHAR" length="10" sourcecodepage="Windows-1252" externalfilecodepage="Windows-1252"nullable="true">UNIVCHARCOL</column></row></table>

Bulk load configuration file schema

The bulk load configuration file must conform to the bulk load configuration XML schema defined at the followingWeb site.

https://documentation.progress.com/output/DataDirect/collateral/BulkData.xsd

The driver throws an exception if either of the following circumstances occur.

• If the driver performs a data export and the CSV file cannot be created

• If the driver performs a bulk load operation and the driver detects that the CSV file does not comply withthe XML schema described in the bulk load configuration file

Character set conversions

When you export data from a database to a CSV file, the CSV file uses the same code page as the table fromwhich the data was exported. If the CSV file and the target table use different code pages, performance forbulk load operations can suffer because the driver must perform a character set conversion.

To avoid character set conversions, your application can specify which code page to use for the CSV file whenexporting data. For example, if the source database table uses a SHIFT-JIS code page and the target tableuses a EUC-JP code page, specify setCodePage("EUC_JP") to ensure that the CSV file will use the samecode page as the target table.

You can specify any of the following code pages.


CSV files

https://documentation.progress.com/output/DataDirect/collateral/BulkData.xsd

Note: If the code page you need to use is not listed, contact Customer Support to request support for thatcode page.

IBM01140

IBM01141

IBM01142

IBM01143

IBM01144

IBM01145

IBM01146

IBM01147

IBM01148

IBM01149

WINDOWS-1250

WINDOWS-1251

WINDOWS-1252

WINDOWS-1253

WINDOWS-1254

WINDOWS-1255

WINDOWS-1256

WINDOWS-1257

WINDOWS-1258

WINDOWS-854

IBM-939

IBM-943_P14A-2000

IBM-4396

IBM-5026

IBM-5035

UTF-8

UTF-16LE

UTF-16BE

IBM273

IBM277

IBM278

IBM280

IBM284

IBM285

IBM290

IBM297

IBM420

IBM424

IBM500

IBM851

IBM855

IBM857

IBM860

IBM861

IBM863

IBM864

IBM865

IBM869

IBM870

IBM871

IBM1026

KOI8_R

HZ_GB_2312

IBM866

IBM775

IBM00858

US_ASCII

ISO_8859_1

ISO_8859_2

ISO_8859_3

ISO_8859_4

ISO_8859_5

ISO_8859_6

ISO_8859_7

ISO_8859_8

ISO_8859_9

JIS_Encoding

Shift_JIS

EUC_JP

KS_C_5601

ISO_2022_KR

EUC_KR

ISO_2022_JP

GB2312

ISO_8859_13

ISO_8859_15

GBK

IBM850

IBM852

IBM437

IBM862

Big5

MACINTOSH

IBM037

External overflow files

When you export data into a CSV file, you can choose to create one large file or multiple smaller files. Forexample, if you are exporting BLOB data that is a total of several GB, you may want to break the data that intomultiple smaller files of 100 MB each.



If the values set by the setCharacterThreshold or setBinaryThreshold methods are exceeded,separate files are generated to store character or binary data, respectively. Overflow files are located in thesame directory as the CSV file.

The format for overflow file names is:

CSV_file_name.xxxxxx.lob

where:

CSV_file_name is the name of the CSV file.

xxxxxx is a 6-digit number that increments an overflow file.

For example, if multiple overflow files are created for a CSV file named CSV1, the file names would look likethis:

CSV1.000001.lob

CSV1.000002.lob

CSV1.000003.lob

...

If the overflow file contains character data, the code page used by the file is the code page specified in thebulk load configuration file for the CSV file.

Discard file

If the driver was unable to load rows into the database for a bulk load operation from a CSV file, it can recordall the rows that were not loaded in a discard file. The contents of the discard file is in the same format as thatof the CSV file. After fixing reported issues in the discard file, the bulk load can be reissued, using the discardfile as the CSV file.

A discard file is created by specifying a file name and location for the discard file using the setDiscardFilemethod.

Creating a discard file on Windows

To create a discard file named discard.csv located in the C:\temp directory, you would specify:

bulkLoad.setDiscardFile(C:\\temp\\discard.csv)

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: C:\\temp\\discard.csv.

Creating a discard file on UNIX/Linux

To create a discard file named discard.csv located in the /tmp directory, you would specify:

bulkLoad.setDiscardFile(/tmp/discard.csv)

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 aSQL statement. DataDirect Test allows you to perform the following tasks:


DataDirect Test

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

DataDirect Test tutorial

This 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 the Database Selection window.You can use one of these URLsas a template when you make a JDBC connection. The default Config.txt filecontains example URLs for most databases.

Databases

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

InitialContextFactory



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

ContextProviderURL

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

Datasources

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

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

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

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

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

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

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

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

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

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


DataDirect Test



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

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

• Using a data source

• Using a driver/database selection

Connecting using a data source

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.

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 125

Connecting using database selection

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


DataDirect Test

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.

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




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.


DataDirect Test

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

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

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

Executing a prepared statementThis example explains how to execute a parameterized statement multiple times.

To execute a prepared statement:

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

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



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

a) Type the parameter number.

b) Select the parameter type.

c) Type the parameter value.

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

4. When you are finished, click Close.

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


DataDirect Test

6. If you want to insert multiple records, repeat Step 3 on page 127 and Step 5 on page 127 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.




Retrieving database metadata

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


DataDirect Test

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

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

4. Select MetaData / Tables.

5. In the Schema Pattern field, type test01.

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

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



Scrolling through a result set

1. From the Connection window menu, select Connection / Create JDBC 2.0 Statement. DataDirect Testprompts for a result set type and concurrency.

2. Complete the following fields:

a) In the resultSetType field, select TYPE_SCROLL_SENSITIVE.

b) In the resultSetConcurrency field, select CONCUR_READ_ONLY.

c) Click Submit; then, click Close.

3. Select Statement / Execute Stmt Query.

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


DataDirect Test

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

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



7. Click Close.

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

To execute a batch on a prepared statement:

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

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

2. Select Statement / Add Stmt Batch.

3. For each parameter:

a) Type the parameter number.

b) Select the parameter type.

c) Type the parameter value.

d) Click Set.


DataDirect Test

4. Click Add to add the specified set of parameters to the batch. To add multiple parameter sets to the batch,repeat Step 2 on page 133 through Step 4 on page 134 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.




Returning ParameterMetaData

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

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

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


DataDirect Test

Establishing savepoints

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

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

3. Click Set; then, click Close.

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

5. Type a statement and click Submit.



6. Select Connection / Set Savepoint.

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

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

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


DataDirect Test

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

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

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



Click Submit; then, click Close.The Connection window displays the data inserted before the first Savepoint.The second insert was rolled back.

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

Deleting a row

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



b) In the resultSetConcurrency field, select CONCUR_UPDATABLE.


DataDirect Test

3. Click Submit; then, click Close.


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

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



7. Click Next. Current Row changes to 1.

8. Click Delete Row.

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

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


DataDirect Test

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

Inserting a row









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



DataDirect Test

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

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

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

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

11. Click Insert Row.


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



14. The Connection window shows the newly inserted row.

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

Updating a row






DataDirect Test



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






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

10. Click Update Row.


12. Specify the statement that you want to execute.


DataDirect Test


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

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

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


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






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


DataDirect Test

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

9. Change the data type to Clob.



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


DataDirect Test

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



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

• Logging is JDBC 4.0-compliant.

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

• Logging can be enabled without changing the application.

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

Once logging is enabled for a connection, you can turn it on and off at runtime using the setEnableLoggingmethod in the com.ddtek.jdbc.extensions.ExtLogControl interface.

Refer to Troubleshooting your application in the Progress DataDirect for JDBC Drivers Reference for informationabout using a DataDirect Spy log for troubleshooting.

Enabling DataDirect Spy

You 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 Example

Class.forName("com.ddtek.jdbc.sforce.SForceDriver");Connection conn = DriverManager.getConnection ("jdbc:datadirect:sforce://login.salesforce.com;[email protected]; Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS; SpyAttributes=(log=(filePrefix)C:\\temp\\spy_;linelimit=80;logTName=yes; timestamp=yes)");

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


Tracking JDBC calls with DataDirect Spy

https://docs.progress.com/bundle/datadirect-jdbc-reference/page/Troubleshooting-your-application.html

DataDirect Spy loads the Salesforce driver and logs all JDBC activity to the spy_x.log file located in theC:\temp directory (log=(filePrefix)C:\\temp\\spy_), where x is an integer that increments by 1 foreach connection on which the prefix is specified. The spy_x.log file logs a maximum of 80 characters oneach line (linelimit=80) and includes the name of the current thread (logTName=yes) with a timestampon each line in the log (timestamp=yes).

UNIX Example

Class.forName("com.ddtek.jdbc.sforce.SForceDriver");Connection conn = DriverManager.getConnection ("jdbc:datadirect:sforce://login.salesforce.com;[email protected]; Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS; SpyAttributes=(log=(filePrefix)/tmp/spy_;logTName=yes;timestamp=yes)");

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

See alsoDataDirect Spy attributes on page 155

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

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

Windows Example

SForceDataSource sds = new SForceDataSource();sds.setDescription("My Salesforce Datasource");sds.setServerName("login.salesforce.com");sds.setUser("[email protected]");sds.setPassword("secret");sds.setSecurityToken("XaBARTsLZReM4Px47qPLOS");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 Salesforce driver and logs all JDBC activity to the spy.log file located in the C:\tempdirectory (log=(file)C:\\temp\\spy.log). In addition to regular JDBC activity, the spy.log file alsologs activity on InputStream and Reader objects (logIS=yes). It also includes the name of the currentthread (logTName=yes).



UNIX Example

SForceDataSource mds = new SForceDataSource();mds.setDescription("My Salesforce Datasource");mds.setServerName("login.salesforce.com");mds.setUser("[email protected]");mds.setPassword("secret");mds.setSecurityToken("XaBARTsLZReM4Px47qPLOS");mds.setSpyAttributes("log=(file)/tmp/spy.log;logIS=yes;logTName=yes");Connection conn=mds.getConnection;...

DataDirect Spy loads the Salesforce driver and logs all JDBC activity to the spy.log file located in the /tmpdirectory (log=(file)/tmp/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).

See alsoDataDirect Spy attributes on page 155

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



DescriptionAttribute

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

linelimit=numberofchars

The default is 0 (no maximum limit).

Loads the driver specified by classname.load=classname

Directs logging to the file specified by filename.log=(file)filename

For Windows, if coding a path to the log file in a Javastring, the backslash character (\) must be precededby the Java escape character, a backslash. Forexample:log=(file)C:\\temp\\spy.log;logIS=yes;logTName=yes.

Directs logging to a file prefixed by file_prefix.The log file is named file_prefixX.log

log=(filePrefix)file_prefix

where:

X is an integer that increments by 1 for eachconnection on which the prefix is specified.

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

C:\temp\spy_1.log

C:\temp\spy_2.log

C:\temp\spy_3.log

...

If coding a path to the log file in a Java string, thebackslash character (\) must be preceded by the Javaescape character, a backslash.

For example:log=(filePrefix)C:\\temp\\spy_;logIS=yes;logTName=yes.

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

log=System.out



DescriptionAttribute

Specifies whether DataDirect Spy logs activity onInputStream and Reader objects.

When logIS=nosingleread, logging onInputStream and Reader objects is active; however,logging of the single-byte read InputStream.reador single-character Reader.read is suppressed toprevent generating large log files that containsingle-byte or single character read messages.

The default is no.

logIS= { yes | no | nosingleread }

Specifies whether DataDirect Spy logs activity onBLOB and CLOB objects.

logLobs= { yes | no }

Specifies whether DataDirect Spy logs the name ofthe current thread.

The default is no.

logTName= { yes | no }

Specifies whether a timestamp is included on eachline of the DataDirect Spy log.

The default is no.

timestamp= { yes | no }



4Connection Property Descriptions

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

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

Note: The data type listed for each connection property is the Java data type used for the property value in aJDBC data source.

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

Table 18: Salesforce Driver Properties

DefaultData Source MethodProperty

NonesetAccessTokenAccessToken on page 163

userIDPasswordsetAuthenticationMethodAuthenticationMethod on page 164

30000 (rows)setBulkFetchThresholdBulkFetchThreshold on page 165



0 (bulk load operations aresynchronous)

setBulkLoadAsyncBulkLoadAsync on page 166

1000 (rows)setBulkLoadBatchSizeBulkLoadBatchSize on page 167

parallelsetBulkLoadConcurrencyModeBulkLoadConcurrencyMode onpage 167

10 (seconds)setBulkLoadPollIntervalBulkLoadPollInterval on page 168

4000 (rows)setBulkLoadThresholdBulkLoadThreshold on page 169

2setCatalogOptionsCatalogOptions on page 170

NonesetClientIDClientID on page 170

NonesetClientSecretClientSecret on page 171

AuditColumns=all;CustomSuffix=include;KeywordConflictSuffix=;MapSystemColumnNames=0;NumberFieldMapping=emulateInteger;UppercaseIdentifiers=true

setConfigOptionsConfigOptions on page 172

Important: The configurationoptions have been deprecated.However, the driver will continue tosupport them until the next majorrelease of the driver.

5setConnectionRetryCountConnectionRetryCount on page 177

1 (second)setConnectionRetryDelayConnectionRetryDelay on page 178

1 (data type check is performed ifcolumn value is null)

setConvertNullConvertNull on page 178

notExistsetCreateMapCreateMap on page 179

truesetEnableBulkFetchEnableBulkFetch on page 180

truesetEnableBulkLoadEnableBulkLoad on page 181

truesetEnablePKChunkingEnablePKChunking on page 181

100 (rows)setFetchSizeFetchSize on page 182

empty stringsetImportStatementPoolImportStatementPool on page 183

NonesetInitializationStringInitializationString on page 184

2048 (KB of memory)setInsensitiveResultSetBufferSizeInsensitiveResultSetBufferSize onpage 185


Chapter 4: Connection Property Descriptions


falsesetJavaDoubleToStringJavaDoubleToString on page 186

ddlogging.propertiessetLogConfigFileLogConfigFile on page 186

0 (no timeout)setLoginTimeoutLoginTimeout on page 187

0 (driver’s internal preparedstatement pooling is not enabled)

setMaxPooledStatementsMaxPooledStatements on page 188

NonesetPasswordPassword on page 189

100000 (rows)setPKChunkSizePKChunkSize on page 189

empty stringsetProxyHostProxyHost on page 190

empty stringsetProxyPasswordProxyPassword on page 191

0setProxyPortProxyPort on page 192

empty stringsetProxyUserProxyUser on page 192

falsesetReadyOnlyReadOnly on page 193

NonesetRefreshTokenRefreshToken on page 194

falsesetRegisterStatementPoolMonitorMBeanRegisterStatementPoolMonitorMBeanon page 195

For Windows:

<application_data_folder>\Local\Progress\DataDirect\SForce_Schema\<user_name>.config

For UNIX/Linux:

˜/progress/datadirect/SForce_Schema/<user_name>.config

setSchemaMapSchemaMap on page 195

NonesetSecurityTokenSecurityToken on page 197

login.salesforce.comsetServerNameServerName on page 198

NonesetSpyAttributesSpyAttributes on page 199

100 (Web service calls)setStmtCallLimitStmtCallLimit on page 200

errorAlwayssetStmtCallLimitBehaviorStmtCallLimitBehavior on page 200

noTransactionssetTransactionModeTransactionMode on page 201



NonesetUserUser on page 202

compresssetWSCompressDataWSCompressData on page 202

0 (maximum of 2000 rows)setWSFetchSizeWSFetchSize on page 203

1setWSPoolSizeWSPoolSize on page 204

0 (no retries for timed-out requests)setWSRetryCountWSRetryCount on page 204

120 (seconds)setWSTimeoutWSTimeout on page 205


• AccessToken

• AuthenticationMethod

• BulkFetchThreshold

• BulkLoadAsync

• BulkLoadBatchSize

• BulkLoadConcurrencyMode

• BulkLoadPollInterval

• BulkLoadThreshold

• CatalogOptions

• ClientID

• ClientSecret

• ConfigOptions

• ConnectionRetryCount

• ConnectionRetryDelay

• ConvertNull

• CreateMap

• EnableBulkFetch

• EnableBulkLoad

• EnablePKChunking

• FetchSize

• ImportStatementPool

• InitializationString



• InsensitiveResultSetBufferSize

• JavaDoubleToString

• LogConfigFile

• LoginTimeout

• MaxPooledStatements

• Password

• PKChunkSize

• ProxyHost

• ProxyPassword

• ProxyPort

• ProxyUser

• ReadOnly

• RefreshToken

• RegisterStatementPoolMonitorMBean

• SchemaMap

• SecurityToken

• ServerName

• SpyAttributes

• StmtCallLimit

• StmtCallLimitBehavior

• TransactionMode

• User

• WSCompressData

• WSFetchSize

• WSPoolSize

• WSRetryCount

• WSTimeout

AccessToken

PurposeSpecifies the access token required to authenticate to a Salesforce instance when OAuth 2.0 is enabled(AuthenticationMethod=oauth2.0).


AccessToken

The access token acts as a session ID for the connection. Refer to the Salesforce documentation to know howto obtain an access token.

Valid Valuesstring

where:

string

is the access token you have obtained from Salesforce.

Notes

• If a value for the AccessToken property is not specified, the driver uses the value of the RefreshTokenproperty to make a connection.

• If both AccessToken and RefreshToken values are not specified, the driver cannot make a successfulconnection.

• If both AccessToken and RefreshToken values are specified, the driver ignores the AccessToken valueand uses the RefreshToken value to generate a new AccessToken value.

Data Source MethodsetAccessToken

DefaultNone

Data TypeString

See alsoConfiguring OAuth 2.0 authentication on page 82

AuthenticationMethod on page 164

RefreshToken on page 194

AuthenticationMethod

PurposeDetermines which authentication method the driver uses when establishing a connection.

Valid valuesuserIDPassword | oauth2.0

BehaviorIf set to userIDPassword, the driver uses user ID/password authentication when establishing a connection.



If set to oauth2.0, the driver uses OAuth 2.0 authentication when establishing a connection.

Data Source MethodsetAuthenticationMethod

DefaultuserIDPassword

Data TypeString

See AlsoConfiguring user ID/password authentication on page 82

Configuring OAuth 2.0 authentication on page 82

BulkFetchThreshold

PurposeSpecifies a number of rows that, if exceeded, signals the driver to use the Salesforce Bulk API for selectoperations. For this behavior to take effect, the EnableBulkFetch property must be set to true.

Valid Values0 | x

where:

x

is a positive integer that represents a number of rows.

BehaviorIf set to 0, the driver uses the Salesforce Bulk API for all select operations.

If set to x, the driver uses the Salesforce Bulk API for select operations when the value of x is exceeded.

Notes

• If the EnableBulkFetch property is set to false, the BulkFetchThreshold property is ignored.

• The EnablePKChunking connection property can be used to break bulk fetch operations into smaller, moremanageable batches for improved performance.

• Do not set the BulkFetchThreshold property to a value greater than the Web service call limit set by theStmtCallLimit property. If the value set for BulkFetchThreshold is greater than the value of StmtCallLimit,the driver would not use the Salesforce Bulk API for fetch operations because the Web service call limitwould be reached before the driver reached the threshold to use the Salesforce Bulk API.


BulkFetchThreshold

Data Source MethodsetBulkFetchThreshold

Default30000 (rows)

Data Typeint

See also

• EnableBulkFetch on page 180

• EnablePKChunking on page 181

• StmtCallLimit on page 200

BulkLoadAsync

PurposeDetermines whether the driver treats bulk load operations as synchronous or asynchronous..

Valid Values0 | 1

BehaviorIf set to 0, bulk load operations are synchronous. The driver does not return from the method that invoked anoperation until the operation has completed or the operation has timed out. If the operation times out, the driverthrows an exception.

If set to 1, bulk load operations are asynchronous.The driver returns from the method that invoked an operationimmediately after the operation is submitted to the server.The driver does not verify that the bulk load operationwas completed.

Default0

Data Source MethodsetBulkLoadAsync

Data Typeint

See alsoDataDirect Bulk Load on page 112



BulkLoadBatchSize

PurposeProvides a suggestion to the driver for the number of rows to load at a time when bulk loading data. Performancecan be improved by increasing the number of rows the driver loads at a time because fewer network roundtrips are required. Be aware that increasing the number of rows that are loaded also causes the driver toconsume more memory on the client.

Valid Valuesx

where:

x


BehaviorThe driver loads the specified number of rows at a time. If the specified value exceeds the maximum batchsize allowed by the data source, the driver uses the maximum batch size allowed by the data source.

NotesThe batchSize() method of the DDBulkLoad interface can be used to override this value for a particularbulk load operation.

Data Source MethodsetBulkLoadBatchSize

Default1000 (rows)

Data Typelong


BulkLoadConcurrencyMode

PurposeDetermines whether multiple batches associated with a bulk load operation are processed by Salesforce inparallel or one at a time.


BulkLoadBatchSize

Valid Valuesparallel | serial

BehaviorIf set to parallel, multiple batches associated with a bulk load operation are processed in parallel.The orderin which the batches are processed can vary.

If set to serial, multiple batches associated with a bulk load operation are processed one at a time.

Data Source MethodsetBulkLoadConcurrencyMode

Defaultparallel

Data TypeString


BulkLoadPollInterval

PurposeSpecifies the number of seconds the driver waits to request bulk operation status. This interval is used by thedriver the first time it requests status and for all subsequent status requests.

Valid Valuesx

where:

x

is a positive integer that represents a number of seconds the driver waits before requesting bulkoperation status.

Data Source MethodsetBulkLoadPollInterval

Default10 (seconds)

Data Typeint




BulkLoadThreshold

PurposeSpecifies a number of rows that, if exceeded, signals the driver to use the Salesforce Bulk API for inserts,updates, and deletes. For this behavior to take effect, the EnableBulkLoad property must be set to true.

Valid Values0 | x

where:

x


BehaviorIf set to 0, the driver uses the Salesforce Bulk API for all inserts, updates, and deletes.

If set to x, the driver uses the Salesforce Bulk API to execute the insert, update, or delete operation when thevalue of x is exceeded.

Notes

• If the EnableBulkLoad property is set to false, the BulkLoadThreshold property is ignored.

• Do not set the BulkLoadThreshold property to a value greater than the Web service call limit set by theStmtCallLimit property. If the value set for BulkLoadThreshold is greater than the value of StmtCallLimit,the driver would not use the Salesforce Bulk API because the Web service call limit would be reached beforethe driver reached the threshold to use the Salesforce Bulk API.

Data Source MethodsetBulkLoadThreshold

Default4000 (rows)

Data Typeint

See also

• EnableBulkLoad on page 181

• DataDirect Bulk Load on page 112


BulkLoadThreshold

CatalogOptions

PurposeDetermines which type of metadata information is included in result sets when an application callsDatabaseMetaData methods.

Valid Values2 | 4

BehaviorIf set to 2, result sets do not contain synonyms.

If set to 4, a hint is provided to the driver to emulate getColumns() calls using the ResultSetMetaData objectinstead of querying database catalogs for column information. Result sets contain synonyms. Using emulationcan improve performance because the SQL statement that is formulated by the emulation is less complex thanthe SQL statement that is formulated using getColumns(). The argument to getColumns() must evaluate to asingle table. If it does not, because of a wildcard or null value, for example, the driver reverts to the defaultbehavior for getColumns() calls.

Data Source MethodsetCatalogOptions

Default2

Data Typeint

ClientID

PurposeSpecifies the consumer key for your application.The driver uses this value when authenticating to a Salesforceinstance using OAuth 2.0 (AuthenticationMethod=oauth2.0).

Refer to the Salesforce documentation to know how to obtain the consumer key for your application.

Valid Valuesstring

where:

string

is the consumer key for your application.



Data Source MethodsetClientID

DefaultNone

Data TypeString



ClientSecret

PurposeSpecifies the consumer secret for your application. This value can optionally be specified when authenticatingto a Salesforce instance using OAuth 2.0 (AuthenticationMethod=oauth2.0).

Refer to the Salesforce documentation to know how to obtain the consumer secret for your application.

Valid Valuesstring

where:

string

is the consumer secret for your aplication.

Data Source MethodsetClientSecret

DefaultNone

Data TypeString




ClientSecret

ConfigOptions

Important: The configuration options have been deprecated. However, the driver will continue to support themuntil the next major release of the driver.

PurposeDetermines how the mapping of the remote Salesforce data model to a local schema map can be configured,customized, and updated.

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

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

where:

key

is one of the following configuration options:

• AuditColumns

• CustomSuffix

• KeywordConflictSuffix

• MapSystemColumnNames

• NumberFieldMapping

• UppercaseIdentifiers

value

specifies a setting for the configuration option.

When specifying configuration options in a connection string, key value pairs must be enclosed in parenthesesand separated by a semicolon. For example:

ConfigOptions=(AuditColumns=none;CustomSuffix=strip;KeywordConflictSuffix=;MapSystemColumnNames=1;NumberFieldMapping=emulateInteger;UppercaseIdentifiers=true)

Data Source MethodsetConfigOptions



Default

AuditColumns=all;CustomSuffix=include;KeywordConflictSuffix=;MapSystemColumnNames=0;NumberFieldMapping=emulateInteger;UppercaseIdentifiers=true

Data TypeString

AuditColumns (Configuration Option)

PurposeDetermines whether the driver includes audit fields, which Salesforce adds to all objects defined in a Salesforceinstance, as table columns when mapping the Salesforce data model.

The audit columns added by Salesforce are:

• IsDeleted

• CreatedById

• CreatedDate

• LastModifiedById

• LastModifiedDate

• SystemModstamp

Valid Valuesall | auditOnly | masterOnly | none

BehaviorIf set to all, the driver includes the all of the audit columns and the master record id column in its tabledefinitions.

If set to auditOnly, the driver adds only the audit columns in its table definitions.

If set to masterOnly, the driver adds only the MasterRecordId column in its table definitions.

If set to none, the driver does not add the audit columns or the MasterRecordId column in its table definitions.

NotesIn a typical Salesforce instance, not all users are granted access to the Audit or MasterRecordId columns. IfAuditColumns is set to a value other than none and the driver cannot include the columns requested, theconnection fails and the driver generates a SQLException with a SQLState of 08001.

Defaultall

See alsoConfigOptions on page 172


ConfigOptions

CustomSuffix (Configuration Option)

PurposeDetermines whether the driver includes or strips the __c suffix from the table and column names when mappingthe Salesforce data model. Salesforce adds the suffix to all custom objects and fields.

Valid Valuesinclude | strip

BehaviorIf set to include, the driver includes the __c suffix.

If set to strip, the driver strips the __c suffix.

Defaultinclude


KeywordConflictSuffix (Configuration Option)

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

Valid Valuesstring

where:

string

is a string of up to five alphanumeric characters.

ExampleA field called CASE exists in the native Salesforce data.To avoid a naming conflict with the SQL engine keywordCASE, you could set KeywordConflictSuffix=TAB. In this scenario, the driver maps the Case object tothe CASETAB column.

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



DefaultEmpty string


MapSystemColumnNames (Configuration Option)

PurposeDetermines how the driver maps Salesforce system columns.

Valid Values0 | 1

BehaviorIf set to 0, the driver does not change the names of the Salesforce system columns.

If set to 1, the driver changes the names of the Salesforce system columns as described in the following table:

Table 19: Mapped Names for Salesforce Field Names When Using MapSystemColumnNames

Mapped NameField Name

ROWIDId

SYS_NAMEName

SYS_ISDELETEDIsDeleted

SYS_CREATEDDATECreatedDate

SYS_CREATEDBYIDCreatedById

SYS_LASTMODIFIEDDATELastModifiedDate

SYS_LASTMODIFIEDIDLastModifiedId

SYS_SYSTEMMODSTAMPSystemModstamp

SYS_LASTACTIVITYDATELastActivityDate

SYS_OWNERIDOwnerId

Default0



ConfigOptions

NumberFieldMapping (Configuration Option)

PurposeDetermines how the driver maps fields defined as NUMBER in Salesforce. The Salesforce API uses DOUBLEvalues to transfer data to and from NUMBER fields, which can cause problems when the precision of theNUMBER field is greater than the precision of a DOUBLE value. Rounding can occur when converting largevalues to and from DOUBLE. The NumberFieldMapping option allows you to map the NUMBER fields to therequired SQL types based on their precision.

Valid ValuesemulateInteger | alwaysDouble | alwaysDecimal

BehaviorIf set to emulateInteger, the driver maps NUMBER fields with a precision of 9 or less and a scale of 0 tothe INTEGER SQL type and maps all other NUMBER fields to the DOUBLE SQL type.

If set to alwaysDouble, the driver maps all NUMBER fields to the DOUBLE SQL type regardless of theirprecision.

If set to alwaysDecimal, the driver maps all NUMBER fields to the DECIMAL SQL type. It can be used whenthe precision of the NUMBER field is greater than the precision of a DOUBLE value.

DefaultemulateInteger


UppercaseIdentifiers (Configuration Option)

PurposeSpecifies whether the driver maps all identifier names to uppercase.

Valid Valuestrue | false

BehaviorIf set to true, the driver maps identifiers to uppercase.

If set to false , the driver maps identifiers to the mixed case name of the object being mapped. If mixed caseidentifiers are used, SQL statements must enclose those identifiers in double quotes and the case of theidentifier must exactly match the case of the identifier name.

ExampleFor example, if UppercaseIdentifiers=false, to query the Account table you specify:

SELECT "Phone", "Website" FROM "Account"



NotesDo not change the value of UppercaseIdentifiers unless the data source you are connecting to has objectswith names that differ only by case.

Defaulttrue


ConnectionRetryCount

PurposeThe number of times the driver retries connection attempts to the Salesforce instance until a successfulconnection is established.

Valid Values0 | x

where x is a positive integer that represents the number of retries.

BehaviorIf set to 0, the driver does not try to reconnect after the initial unsuccessful attempt.

If set to x, the driver retries connection attempts the specified number of times. If a connection is not establishedduring the retry attempts, the driver returns an exception that is generated by the last database server to whichit tried to connect.

ExampleIf this property is set to 2, the driver retries the server twice after the initial retry attempt.

Notes

• If an application sets a login timeout value (for example, using DataSource.loginTimeout orDriverManager.loginTimeout), and the login timeout expires, the driver ceases connection attempts.

• The ConnectionRetryDelay property specifies the wait interval, in seconds, to occur between retry attempts.

Data Source MethodsetConnectionRetryCount

Default5

Data Typeint


ConnectionRetryCount

ConnectionRetryDelay

PurposeThe number of seconds the driver waits between connection retry attempts when ConnectionRetryCount isset to a positive integer.

Valid Values0 | x

where:

x

is a number of seconds.

BehaviorIf set to 0, the driver does not delay between retries.

If set to x, the driver waits between connection retry attempts the specified number of seconds.

ExampleIf ConnectionRetryCount is set to 2 and this property is set to 3, the driver retries the server twice after theinitial retry attempt. The driver waits 3 seconds between retry attempts.

Data Source MethodConnectionRetryDelay

Default1 (second)

Data Typeint

ConvertNull

PurposeControls how data conversions are handled for null values.

Valid Values0 | 1



BehaviorIf set to 0, the driver does not perform the data type check if the value of the column is null. This allows nullvalues to be returned even though a conversion between the requested type and the column type is undefined.

If set to 1, the driver checks the data type being requested against the data type of the table column that storesthe data. If a conversion between the requested type and column type is not defined, the driver generates an"unsupported data conversion" exception regardless of whether the column value is NULL.

Data Source MethodsetConvertNull

Default1

Data Typeint

CreateMap

PurposeSpecifies whether the driver creates a new map of the Salesforce data model when establishing the connection.

Valid ValuesforceNew | notExist | no

BehaviorIf set to forceNew, the driver deletes the current schema map specified by the SchemaMap property andcreates a new one at the same location.

Warning: This causes all views, data caches, and map customizations defined in the current schema map tobe lost.

If set to notExist, the driver uses the current schema map specified by the SchemaMap property. If one doesnot exist, the driver creates one.

If set to no, the driver uses the current schema map specified by the SchemaMap property. If one does notexist, the connection fails.

NotesAlternatively, you can refresh a schema manually at any time by using the Refresh Map statement. See "RefreshMap (EXT)" for details.

Data Source MethodsetCreateMap


CreateMap

DefaultnotExist

Data TypeString

See Also

• SchemaMap on page 195

• Refresh Map (EXT) on page 258

EnableBulkFetch

PurposeSpecifies whether the driver can use the Salesforce Bulk API for selects based on the value of theBulkFetchThreshold connection property. If the number of rows expected in the result set exceeds the valueof BulkFetchThreshold property, the driver uses the Salesforce Bulk API to execute the select operation. Usingthe Salesforce Bulk API may significantly reduce the number of Web service calls used to execute a statementand, therefore, may improve performance.

Valid Values1 | 0

BehaviorIf set to 1, the driver can use the Salesforce Bulk API for selects based on the value of the BulkFetchThresholdconnection property. If the number of rows expected in the result set exceeds the value of BulkFetchThresholdproperty, the driver uses the Salesforce Bulk API to execute the select operation.

If set to 0, the driver does not use the Salesforce Bulk API, and the BulkFetchThreshold property is ignored.

Data Source MethodsetEnableBulkFetch

Default1

Data Typeboolean

See Also

• BulkFetchThreshold on page 165




EnableBulkLoad

PurposeSpecifies whether the driver can use the Salesforce Bulk API for inserts, updates, and deletes based on thevalue of BulkLoadThreshold connection property. If the number of affected rows exceeds the value ofBulkLoadThreshold property, the driver uses the Salesforce Bulk API to execute the insert, update, or deleteoperation. Using the Salesforce Bulk API may significantly reduce the number of Web service calls used toexecute a statement and, therefore, may improve performance.

Valid Values1 | 0

BehaviorIf set to 1, the driver can use the Salesforce Bulk API for inserts, updates, and deletes based on the value ofBulkLoadThreshold connection property. If the number of affected rows exceeds the value of BulkLoadThresholdproperty, the driver uses the Salesforce Bulk API to execute the insert, update, or delete operation.

If set to 0, the driver does not use the Salesforce Bulk API, and the BulkLoadThreshold property is ignored.

Data Source MethodsetEnableBulkLoad

Default1

Data Typeboolean

See Also

• BulkLoadThreshold on page 169


EnablePKChunking

PurposeSpecifies whether the driver uses PK chunking for select operations. PK chunking breaks down bulk fetchoperations into smaller, more manageable batches for improved performance.

Valid Values1 | 0


EnableBulkLoad

BehaviorIf set to 1, the driver uses PK chunking for select operations when the expected number of rows in the resultset is greater than the values of the BulkFetchThreshold and PKChunkSize properties. For this behavior totake effect, the EnableBulkFetch property must also be set to 1.

If set to 0, the driver does not use PK chunking when executing select operations, and the PKChunkSizeproperty is ignored.

Notes

• PK chunking is supported for all custom objects and the following standard objects: Account, Campaign,CampaignMember, Case, Contact, Lead, LoginHistory, Opportunity, Task, and User. In addition,PK chunking is supported for sharing objects as long as the parent object is supported.

Data Source MethodsetEnablePKChunking

Default1

Data Typeboolean

See Also


• PKChunkSize on page 189

• EnableBulkFetch on page 180

FetchSize

PurposeSpecifies the maximum number of rows that the driver processes before returning data to the application whenexecuting a Select. This value provides a suggestion to the driver as to the number of rows it should internallyprocess before returning control to the application. The driver may fetch fewer rows to conserve memory whenprocessing exceptionally wide rows.

Valid Values0 | x

where:

x

is a positive integer indicating the number of rows that should be processed.



BehaviorIf set to 0, the driver processes all the rows of the result before returning control to the application. When largedata sets are being processed, setting FetchSize to 0 can diminish performance and increase the likelihoodof out-of-memory errors.

If set to x, the driver limits the number of rows that may be processed for each fetch request before returningcontrol to the application.

Notes

• To optimize throughput and conserve memory, the driver uses an internal algorithm to determine how manyrows should be processed based on the width of rows in the result set. Therefore, the driver may processfewer rows than specified by FetchSize when the result set contains exceptionally wide rows. Alternatively,the driver processes the number of rows specified by FetchSize when the result set contains rows ofunexceptional width.

• FetchSize and WSFetchSize can be used to adjust the trade-off between throughput and response time.Smaller fetch sizes can improve the initial response time of the query. Larger fetch sizes can improve overallresponse times at the cost of additional memory.

• You can use FetchSize to reduce demands on memory and decrease the likelihood of out-of-memory errors.Simply, decrease FetchSize to reduce the number of rows the driver is required to process before returningdata to the application.

Data Source MethodsetFetchSize

Default100 (rows)

Data TypeInt

See also

• Additional Properties on page 68


ImportStatementPool

PurposeSpecifies the path and file name of the file to be used to load the contents of the statement pool. When thisproperty is specified, statements are imported into the statement pool from the specified file.

If the driver cannot locate the specified file when establishing the connection, the connection fails and the driverthrows an exception. See "Importing Statements into a Statement Pool" for details about the import file.

Valid Valuesstring

where:


ImportStatementPool

string

is the path and file name of the file to be used to load the contents of the statement pool.

Data Source MethodsetImportStatementPool

Defaultempty string

Data TypeString

See also

• Importing Statements into a Statement Pool on page 108

InitializationString

PurposeSpecifies one or multiple SQL commands to be executed by the driver after it has established the connectionto the database and has performed all initialization for the connection. If the execution of a SQL command fails,the connection attempt also fails and the driver throws an exception indicating which SQL command orcommands failed.

Valid Valuescommand [[; command ]...]

where:

command

is a SQL command.

Notes

• Multiple commands must be separated by semicolons. In addition, if this property is specified in a connectionURL, the entire value must be enclosed in parentheses when multiple commands are specified.



ExampleBecause fetching metadata and generating mapping files can significantly increase the time it takes to connectto Salesforce, the driver caches this information on the client the first time the driver connects on behalf of eachuser. The cached metadata is used in subsequent connections made by the user instead of re-fetching themetadata from Salesforce. To force the driver to re-fetch the metadata information for a connection, use theInitializationString property to pass the REFRESH SCHEMA SFORCE command in the connection URL. Forexample:

jdbc:datadirect:sforce://login.salesforce.com;[email protected];Password=secret;InitializationString=(REFRESH SCHEMA SFORCE)

DefaultNone

Data TypeString

InsensitiveResultSetBufferSize

PurposeDetermines the amount of memory that is used by the driver to cache insensitive result set data.

Valid Values-1 | 0 | x

where:

x

is a positive integer that represents the amount of memory.

BehaviorIf set to -1, the driver caches insensitive result set data in memory. If the size of the result set exceeds availablememory, an OutOfMemoryException is generated. With no need to write result set data to disk, the driverprocesses the data efficiently.

If set to 0, the driver caches insensitive result set data in memory, up to a maximum of 2 MB. If the size of theresult set data exceeds available memory, then the driver pages the result set data to disk, which can have anegative performance effect. Because result set data may be written to disk, the driver may have to reformatthe data to write it correctly to disk.

If set to x, the driver caches insensitive result set data in memory and uses this value to set the size (in KB)of the memory buffer for caching insensitive result set data. If the size of the result set data exceeds availablememory, then the driver pages the result set data to disk, which can have a negative performance effect.Because the result set data may be written to disk, the driver may have to reformat the data to write it correctlyto disk. Specifying a buffer size that is a power of 2 results in efficient memory use.

Data Source MethodsetInsensitiveResultSetBufferSize


InsensitiveResultSetBufferSize

Default2048

Data Typeint

JavaDoubleToString

PurposeDetermines which algorithm the driver uses when converting a double or float value to a string value. By default,the driver uses its own internal conversion algorithm, which improves performance.

Valid Values1 | 0

BehaviorIf set to 1, the driver uses the JVM algorithm when converting a double or float value to a string value. If yourapplication cannot accept rounding differences and you are willing to sacrifice performance, set this value to1 to use the JVM conversion algorithm.

If set to 0, the driver uses its own internal algorithm when converting a double or float value to a string value.This value improves performance, but slight rounding differences within the allowable error of the double andfloat data types can occur when compared to the same conversion using the JVM algorithm.

Data Source MethodsetJavaDoubleToString

Default0

Data Typeboolean

LogConfigFile

PurposeSpecifies the file name, and optionally, the path of the properties file used to initialize driver logging.

Valid Valuesstring

where:



string

is the relative or fully qualified path of the properties file to load to initialize driver logging. If you donot specify a path, the driver looks for this file in the current working directory. If the specified filedoes not exist, the driver continues searching for an appropriate properties file as described in "UsingJava Logging."

Data Source MethodsetLogConfigFile

Defaultddlogging.properties

Data TypeString

See alsoUsing Java Logging on page 216

LoginTimeout

PurposeThe amount of time, in seconds, that the driver waits for a connection to be established before timing out theconnection request.

Valid Values0 | x

where:

x

is a positive integer that represents a number of seconds.

BehaviorIf set to 0, the driver does not time out a connection request.

If set to x, the driver waits for the specified number of seconds before returning control to the application andthrowing a timeout exception.

Data Source MethodsetLoginTimeout

Default0


LoginTimeout

Data Typeint

MaxPooledStatements

PurposeThe maximum number of pooled prepared statements for this connection. Setting MaxStatements to an integergreater than zero (0) enables the driver’s internal prepared statement pooling, which is useful when the driveris not running from within an application server or another application that provides its own prepared statementpooling.

Valid Values0 | x

where

x

is a positive integer that represents a number of pooled prepared statements.

BehaviorIf set to 0, the driver’s internal prepared statement pooling is not enabled.

If set to x, the driver enables the DataDirect Statement Pool and uses the specified value to cache a certainnumber of prepared statements created by an application. If the value set for this property is greater than thenumber of prepared statements that are used by the application, all prepared statements that are created bythe application are cached. Because CallableStatement is a sub-class of PreparedStatement, CallableStatementsalso are cached.

ExampleIf the value of this property is set to 20, the driver caches the last 20 prepared statements that are created bythe application.

Data Source MethodsetMaxPooledStatements

Default0

Data Typeint



Password

DescriptionSpecifies the password to use to connect to your Salesforce instance. A password is required. Contact yoursystem administrator to obtain your password.


Valid Valuespassword | password+securitytoken

where:

password

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

password+securitytoken

is a valid password appended by the security token required to connect to the Salesforce instance,for example, secretXaBARTsLZReM4Px47qPLOS, where secret is the password and the remainderof the value is the security token. Both the password and security token are case-sensitive.

Note: Optionally, you can specify the security token in the SecurityToken property. Do not specify the securitytoken in both properties.

Data Source MethodsetPassword

DefaultNone

Data TypeString

PKChunkSize

PurposeSpecifies the size, in rows, of a primary key chunk when PK chunking has been enabled via theEnablePKChunking property. The Salesforce Bulk API splits the query into chunks of this size.


Password

Valid Valuesx

where:

x

is a positive integer less than or equal to 250,000 rows.

BehaviorThe driver requests, via the Salesforce Bulk API, that Salesforce divide the query into chunks of this size.

Notes

• Fewer rows may be returned if a WHERE clause has been applied to the fetch operation, or if soft-deletedrecords are included within the boundaries of a given chunk.

• Each chunk is processed as a separate batch that counts toward your daily batch limit. Larger chunks willresult in fewer batches, but may reduce performance. PKChunkSize may be set to a maximum value of250,000 rows.

• For PK chunking to be used in select operations, the expected number of rows in the result set must begreater than the values of the BulkFetchThreshold and PKChunkSize properties.

Data Source MethodsetPKChunkSize

Default100000 (rows)

Data Typelong

See also

• EnablePKChunking on page 181


ProxyHost

DescriptionIdentifies a proxy server to use for the first connection.

Valid Valuesserver_name | IP_address

where:



server_name

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

IP_address

is an IP address, specified in either IPv4 or IPv6 format, or a combination of the two. See "Using IPAddresses" for details about using these formats.

Data Source MethodsetProxyHost

Defaultempty string

See also

• IP Addresses on page 84

• Connecting Through a Proxy Server on page 71

ProxyPassword

PurposeSpecifies the password needed to connect to a proxy server for the first connection.

Valid Valuespassword

where:

password

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

Data Source MethodsetProxyPassword

Defaultempty string

See alsoConnecting Through a Proxy Server on page 71


ProxyPassword

ProxyPort

PurposeSpecifies the port number where the proxy server is listening for HTTP or HTTPS requests for the first connection.

Valid Valuesport

where:

port

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

Data Source MethodsetProxyPort

Default0


ProxyUser

PurposeSpecifies the specifies the user name needed to connect to a proxy server for the first connection.

Valid Valuesuser_name

where:

user_name

is a valid user ID for the proxy server.

Data Source MethodsetProxyUser

Defaultempty string




ReadOnly

PurposeSpecifies whether the connection has read-only access to the data source.

Valid Values1 | 0

BehaviorIf set to 1, the connection has read-only access. The following commands are the only commands that youcan use when a connection if read-only:

• Call* (if the procedure does not update data)

• Explain Plan

• Select (except Select Into)

• Set Database Collation

• Set IgnoreCase

• Set Maxrows

• Set Schema

The driver generates an exception if any other command is executed.

If set to 0, the connection is opened for read/write access, and you can use all commands supported by theproduct.

Notes

• You also can use the JDBC connection method setReadOnly to set a read-only state for a connection.

Data Source MethodsetReadOnly

Default0

Data Typeboolean


ReadOnly

RefreshToken

PurposeSpecifies the refresh token used to either request a new access token or renew an expired access token.Whenthe refresh token is specified, the access token generated at connection is used to authenticate to a Salesforceinstance when OAuth 2.0 is enabled (AuthenticationMethod=oauth2.0).

Refer to the Salesforce documentation to know how to obtain a refresh token.

Valid Valuesstring

where:

string

is the refresh token you have obtained from Salesforce.

Notes

• If a value for the AccessToken property is not specified, the driver uses the value of the RefreshTokenproperty to make a connection.

• If both AccessToken and RefreshToken values are not specified, the driver cannot make a successfulconnection.

• If both AccessToken and RefreshToken values are specified, the driver ignores the AccessToken valueand uses the RefreshToken value to generate a new AccessToken value.

Data Source MethodsetRefreshToken

DefaultNone

Data TypeString



AccessToken on page 163



RegisterStatementPoolMonitorMBean

PurposeRegisters the Statement Pool Monitor as a JMX MBean when statement pooling has been enabled withMaxPooledStatements. This allows you to manage statement pooling with standard JMX API calls and to useJMX-compliant tools, such as JConsole.

Valid Valuestrue | false

BehaviorIf set to true, the driver registers an MBean for the statement pool monitor for each statement pool.This givesapplications access to the Statement Pool Monitor through JMX when statement pooling is enabled.

If set to false, the driver does not register an MBean for the Statement Pool Monitor for any statement pool.

Notes

•

• In addition to true and false, the driver accepts 1, 0, on, and off as valid values.1 and On are equivalentto true, and 0 and Off are equivalent to false.

Data Source MethodsetRegisterStatementPoolMonitorMBean

Defaultfalse

Data TypeBoolean

See also

• Statement Pool Monitor on page 104

• Statement Pooling Properties on page 67

• MaxPooledStatements on page 188

SchemaMap

PurposeSpecifies either the name or the absolute path and name of the configuration file where the map of the Salesforcedata model is written. The driver looks for this file when connecting to a Salesforce instance. If the file doesnot exist, the driver creates one.


RegisterStatementPoolMonitorMBean

Valid Valuesstring

where:

string

is either the name or the absolute path and name (including the .config extension) of theconfiguration file. For example, if SchemaMap is set to a value of:

• ABC, the driver either creates or looks for the configuration file ABC in the working directory ofyour application.

• C:\\Users\\Default\\AppData\\Local\\Progress\\DataDirect\\SForce_Schema\\[email protected],the driver either creates or looks for the configuration file [email protected] in thedirectory C:\Users\Default\AppData\Local\Progress\DataDirect\SForce_Schema.

Notes

• If using OAuth 2.0 authentication, a value for the SchemaMap property must be specified for every connection.

• When connecting to a Salesforce instance, the driver looks for the schema map configuration file. If theconfiguration file does not exist, the driver creates the schema map configuration file using the name andlocation you have provided. If you do not provide a name and location for the configuration file, the drivercreates it using default values.

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

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

ExampleAs the following examples show, escapes are needed when specifying SchemaMap for a data source but arenot used when specifying SchemaMap in a DriverManager connection URL.

Driver Manager Example

jdbc:datadirect:sforce://login.salesforce.com;User=abc@defcorp;Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect\SForce_Schema\[email protected]

Data Source Example

SForceDataSource ds = new SForceDataSource();ds.setDescription("My Salesforce DataSource");ds.setServerName("login.salesforce.com");ds.setUser("[email protected]");ds.setPassword("secret");ds.setSecurityToken("XaBARTsLZReM4Px47qPLOS");ds.setSchemaMap("C:\\Users\\Default\\AppData\\Local\\Progress \\DataDirect\\SForce_Schema\\[email protected]")

Data Source MethodsetSchemaMap

Default

• For Windows XP and Windows Server 2003



userprofile\ApplicationData\Local\Progress\DataDirect\SForce_Schema\user_name.config

•

• For other Windows platforms

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

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

• For UNIX/Linux

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

Data TypeString

See alsoRefresh Map (EXT) on page 258

Configuring OAuth 2.0 authentication on page 82

SecurityToken

PurposeSpecifies the security token required to make a connection to a Salesforce instance that is configured for asecurity token. If a security token is required and you do not supply one, the driver returns an error indicatingthat an invalid user or password was supplied. Contact your Salesforce administrator to find out if a securitytoken is required.


Valid Valuesstring

where:

string

is the value of the security token assigned to the user.

Notes

• Optionally, you can specify the security token in the Password property by appending the security token tothe password, for example, secretXaBARTsLZReM4Px47qPLOS, where secret is the password and theremainder of the value is the security token. Do not specify the security token in both properties.


SecurityToken

• A security token is not required when Salesforce has been configured for Trusted IP Ranges and the useris logging in from a trusted IP address. Refer to "Set Trusted IP Ranges for Your Organization" in yourSalesforce documentation for details.

• If setting the security token using a data source, be aware that the SecurityToken property, like all datasource properties, is persisted in clear text.

Data Source MethodsetSecurityToken

DefaultNone

Data TypeString

ServerName

PurposeSpecifies the base Salesforce URL to use for logging in.

Valid Valuesurl

where:

url

is the root of the Salesforce URL to which you want to connect.

ExampleSuppose you have a Salesforce instance that is configured with a production instance and a sandbox instance.You can specify login.salesforce.com as the value for the ServerName property to connect to theproduction instance or test.salesforce.com to connect to the sandbox instance:

URLSalesforce Instance

login.salesforce.comProduction

test.salesforce.comSandbox

Data Source MethodsetServerName



Defaultlogin.salesforce.com

Data TypeString

SpyAttributes

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

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

where:

spy_attribute

is any valid DataDirect Spy attribute. See "DataDirect Spy Attributes" for a list of supported attributes.

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

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

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

Data Source MethodsetSpyAttributes

DefaultEmpty string

Data TypeString

See also

• Tracking JDBC calls with DataDirect Spy on page 153

• DataDirect Spy attributes on page 155


SpyAttributes

StmtCallLimit

PurposeSpecifies the maximum number of Web service calls the driver can make when executing any single SQLstatement or metadata query.

Valid Values0 | x

where:

x

is a positive integer that defines the maximum number of Web service calls the driver can makewhen executing any single SQL statement or metadata query.

BehaviorIf set to 0, there is no limit.

If set to x, the driver uses this value to set the maximum number of Web service calls on a single connectionthat can be made when executing a SQL statement. This limit can be overridden by changing theSTMT_CALL_LIMIT session attribute using the ALTER SESSION statement. For example, the followingstatement sets the statement call limit to 10 Web service calls:

ALTER SESSION SET STMT_CALL_LIMIT=10

If the Web service call limit is exceeded, the behavior of the driver depends on the value specified for theStmtCallLimitBehavior property.

Data Source MethodsetStmtCallLimit

Default100 (Web service calls)

Data Typeint

StmtCallLimitBehavior

PurposeSpecifies the behavior of the driver when the maximum Web service call limit specified by the StmtCallLimitproperty is exceeded.



Valid ValueserrorAlways | returnResults

BehaviorIf set to errorAlways, the driver generates an exception if the maximum Web service call limit is exceed.

If set to returnResults, the driver returns any partial results it received prior to the call limit being exceeded.The driver generates a warning that not all of the results were fetched.

Data Source MethodsetStmtCallLimitBehavior

DefaulterrorAlways

Data TypeString

TransactionMode

PurposeSpecifies how the driver handles manual transactions.

Valid Valuesignore | noTransactions

BehaviorIf set to ignore, the data source does not support transactions and the driver always operates in auto-commitmode. Calls to set the driver to manual commit mode and to commit transactions are ignored. Calls to rollbacka transaction cause the driver to throw an exception indicating that no transaction is started. Metadata indicatesthat the driver supports transactions and the ReadUncommitted transaction isolation level.

If set to noTransactions, the data source and the driver do not support transactions. Metadata indicatesthat the driver does not support transactions.

Data Source MethodsetTransactionMode

DefaultnoTransactions

Data TypeString


TransactionMode

User

PurposeSpecifies the user name that is used to connect to the Salesforce instance. A user name is required.

Valid Valuesstring

where:

string

is a valid user name. The user name is case-insensitive.

Data Source MethodsetUser

DefaultNone

Data TypeString

WSCompressData

PurposeSpecifies whether the driver compresses data it sends to or receives from the Web server.

Valid Valuesnone | compress

BehaviorIf set to none, the driver sends and receives uncompressed data to and from the Web server.

If set to compress, the driver sends and receives compressed data to and from the Web server.

Notes

• Setting the WSCompressData property to none can significantly degrade performance.

Data Source MethodsetWSCompressData



Defaultcompress

Data TypeString

WSFetchSize

PurposeSpecifies the number of rows of data the driver attempts to fetch for each JDBC call.

Valid Values0 | x

where:

x

is a positive integer from 1 to 2000 that defines a number of rows.

BehaviorIf set to 0, the driver attempts to fetch up to a maximum of 2000 rows.This value typically provides the maximumthroughput.

If set to x, the driver attempts to fetch up to a maximum of the specified number of rows. Setting the valuelower than 2000 can reduce the response time for returning the initial data. Consider using a smaller WSFetchsize for interactive applications only.

NotesWSFetchSize and FetchSize can be used to adjust the trade-off between throughput and response time. Smallerfetch sizes can improve the initial response time of the query. Larger fetch sizes can improve overall responsetimes at the cost of additional memory.

Data Source MethodsetWSFetchSize

Default0 (up to a maximum of 2000 rows)

Data TypeInt

See also

• Web Service Properties on page 61



WSFetchSize

WSPoolSize

PurposeSpecifies the maximum number of Salesforce sessions the driver uses. This allows the driver to have multipleweb service requests active when multiple JDBC connections are open, thereby improving throughput andperformance.

Valid Valuesx

where:

x

is the number of Salesforce sessions the driver uses to distribute calls.This value should not exceedthe number of sessions permitted by your Salesforce account.

Notes

• You can improve performance by increasing the number of sessions specified by this property. By increasingthe number of sessions the driver uses, you can improve throughput by distributing calls across multiplesessions when multiple connections are active.

• The maximum number of sessions is determined by the setting of WSPoolSize for the connection thatinitiates the session. For subsequent connections to an active session, the setting is ignored and a warningis returned.To change the maximum number of sessions, close all connections using the Salesforce driver;then, open a new Salesforce connection with desired limit specified for this property.

Data Source MethodsetWSPoolSize

Default1

Data TypeInt

See alsoPerformance Considerations on page 72

WSRetryCount

DescriptionThe number of times the driver retries a timed-out Select request. Insert, Update, and Delete requests arenever retried. The timeout period is specified by the WSTimeout connection property.



Valid Values0 | x

where:

x

is a positive integer.

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

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

Data Source MethodsetWSRetryCount

Default0

Data TypeInt

WSTimeout

PurposeSpecifies the time, in seconds, that the driver waits for a response to a Web service request.

Valid Values0 | x

where:

x

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

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

If set to x, the driver uses the value as the default timeout for any statement created by the connection.

If a Select request times out and WSRetryCount is set to retry timed-out requests, the driver retries the requestthe specified number of times.

Data Source MethodsetWSTimeout


WSTimeout

Default120 (seconds)

Data TypeInt



5Troubleshooting

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


• Troubleshooting your application

• Troubleshooting connection pooling

• Troubleshooting statement pooling

• Using Java Logging

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

See alsoTracking JDBC calls with DataDirect Spy on page 153


Turning On and Off DataDirect Spy Logging

Once 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.WhenDataDirect Spy logging is enabled, all Connection objects returned to an application provide an implementationof the ExtLogControl interface.

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

import com.ddtek.jdbc.extensions.*

// Get Database ConnectionConnection con = DriverManager.getConnection ("jdbc:datadirect:sforce://login.salesforce.com;[email protected]; Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS; SpyAttributes=(log=(filePrefix)/tmp/spy_;logTName=yes;timestamp=yes)");

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

If Java logging is also enabled and Java API logger levels in the properties file are set to FINER or FINEST,the driver ignores the file settings of Spy logging and logs all the logging information (Spy logs and Java logs)into the log file defined by the Java logging config settings.

For example:

If both Spy logging and Java logging are specified in the URL:

LogConfigFile=C:\\props\\spy\\ddlogging_DD.properties;SpyAttributes=(log=(file)spy.log;timestamp=yes)

And the Java logger levels are set to FINER or FINEST:

# logger for web service adapter: use CONFIG, FINE, FINER, FINESTdatadirect.cloud.adapter.level = FINEST

# logger for sql engine: use CONFIG, FINE, FINER, FINESTdatadirect.cloud.sql.level = FINEST

# logger for jdbc spy: use FINER or FINESTdatadirect.jdbc.cloud.level = FINEST

And Java logging argument is:

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

Then both the Spy logs and Java logs will be logged into the log file defined by the Java logging argument,which is myfile in this example.

For more information about Java logging, see "Using Java Logging."

See alsoEnabling DataDirect Spy on page 153Using Java Logging on page 216


Chapter 5: Troubleshooting

DataDirect Spy Log Example

This section provides information to help you understand the content of your own DataDirect Spy logs.

For example, suppose your application executes the following code and performs some operations:Class.forName("com.ddtek.jdbc.sforce.SForceDriver");DriverManager.getConnection("jdbc:datadirect:sforce://login.salesforce.com;[email protected];Password=secret;SecurityToken=XaBARTsLZReM4Px47qPLOS;spyAttributes=(log=(file)c:\\temp\\spy.log)");

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:sforce:;MAXSOQLLENGTH=20000;JDBCBEHAVIOR=1;LOGINHOST=;APPLICATIONNAME=;WSFETCHSIZE=2000;PROXYHOST=;CATALOGOPTIONS=2;BULKLOADCONCURRENCYMODE=PARALLEL;LOGSOAP=false;WSPOOLSIZE=1;BULKLOADBATCHSIZE=10000;ENABLEBULKLOAD=false;STMTCALLLIMIT=0;CONNECTIONRETRYDELAY=1;READONLY=false;CLIENTUSER=;BULKLOADTHRESHOLD=4000;WORKAROUNDS=0;CONVERTNULL=1;RECORDRESTEVENTS=false;CONNECTIONRETRYCOUNT=5;READAHEAD=0;CUSTOMSUFFIX=strip;TOKEN=;STMTCALLLIMITBEHAVIOR=ErrorAlways;LOADLIBRARYPATH=;ENABLEHTTPCHUNKING=true;MAXPOOLEDSTATEMENTS=0;CRYPTOPROTOCOLVERSION=;QUERYTIMEOUT=0;PROXYPASSWORD=;SERIALIZECREATECOLUMNS=false;TRANSACTIONMODE=NoTransactions;WSRETRYCOUNT=0;PROGRAMID=;PROXYPORT=0;WSCOMPRESSDATA=Compress;SECURERANDOMALGORITHM=;DEBUGPLAYBACK=;REGISTERSTATEMENTPOOLMONITORMBEAN=false;BULKLOADPOLLINTERVAL=10;IMPORTSTATEMENTPOOL=;SERVERPATH=;LOADBALANCING=false;LOGINTIMEOUT=0;WSTIMEOUT=120;RANDOMGENERATOR=SECURERANDOM;PROXYUSER=;FAILOVERGRANULARITY=nonAtomic;ACCOUNTINGINFO=;LOGCONFIGFILE=ddlogging.properties;ENCRYPTIONMETHOD=noEncryption;FAILOVERMODE=connect;INITIALIZATIONSTRING=;BATCHPERFORMANCEWORKAROUND=false;JAVADOUBLETOSTRING=false;ENABLETESTPROCS=false;DEBUGRECORD=;AUTHENTICATIONMETHOD=none;CLIENTHOSTNAME=;CONFIGOPTIONS=;CREATEDB=NotExist;REFRESHSCHEMA=false;RESULTSETMETADATAOPTIONS=0;FAILOVERPRECONNECT=false;D2CDATASTOREID=0;SPYATTRIBUTES=(log=(file)c:\temp\spy.log);MAXDESCRIBEOBJECTS=100;INSENSITIVERESULTSETBUFFERSIZE=2048;FETCHSIZE=100;SECURITYTOKEN=89mqiEVzSigEXmr7vQqCoOuN2;SCHEMAMAP=;ENABLEREPORTPARAMETERS=false;ALTERNATESERVERS=;BULKLOADASYNC=false)5

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

spy>> DatabaseMetaData[1].getDriverVersion()spy>> OK (6.0.0.0000 (C0000.F000000.U000000))

spy>> DatabaseMetaData[1].getDatabaseProductName()spy>> OK (Salesforce)

spy>> DatabaseMetaData[1].getDatabaseProductVersion()spy>> OK (41.0)

spy>> Connection Options :6

spy>> MAXSOQLLENGTH=20000spy>> JDBCBEHAVIOR=1spy>> LOGINHOST=spy>> APPLICATIONNAME=spy>> WSFETCHSIZE=2000spy>> ...spy>> LOGINTIMEOUT=0spy>> WSTIMEOUT=120spy>> RANDOMGENERATOR=SECURERANDOMspy>> PROXYUSER=spy>> FAILOVERGRANULARITY=nonAtomicspy>> ...spy>> SCHEMAMAP=spy>> ENABLEREPORTPARAMETERS=false

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


Troubleshooting your application

spy>> ALTERNATESERVERS=spy>> BULKLOADASYNC=falsespy>> Driver Name = SForce7

spy>> Driver Version = 6.0.0.0000 (C0000.F000000.U000000))8

spy>> Database Name = Salesforce9

spy>> Database Version = 41.010

spy>> Connection[1].getWarnings()spy>> OK11

spy>> 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])12

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

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

spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 1spy>> OK (EMPNO)15

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

spy>> ResultSetMetaData[1].getColumnLabel(int column)spy>> column = 3spy>> OK (JOB)17

spy>> ResultSet[1].next()spy>> OK (true)18

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

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

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

spy>> ResultSet[1].next()spy>> OK (false)22

spy>> ResultSet[1].close()spy>> OK23

spy>> Connection[1].close()spy>> OK24

7 The name of the driver.8 The version of the driver.9 The name of the database server to which the driver connects.

10 The version of the database to which the driver connects.11 The application checks to see if there are any warnings. In this example, no warnings are present.12 The SELECT statement is executed.13 Some metadata is requested.14 Some metadata is requested.15 Some metadata is requested.16 Some metadata is requested.17 Some metadata is requested.18 The first row is retrieved and the application retrieves the result values.19 The first row is retrieved and the application retrieves the result values.20 The first row is retrieved and the application retrieves the result values.21 The first row is retrieved and the application retrieves the result values.22 The application attempts to retrieve the next row, but only one row was returned for this query.23 After the application has completed retrieving result values, the result set is closed.24 The application finishes and disconnects.



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 91

Enabling tracing with the setTracing method

You 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 Example

The 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/SalesforceNCMarkBPool: *** ConnectionPool Created25

(jdbc/SalesforceNCMarkBPool26, com.ddtek.jdbcx.sforce.SForceDataSource@1835282, 5, 5, 10, [email protected])27

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

jdbc/SalesforceNCMarkBPool: Enforced minimum!28

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

jdbc/SalesforceNCMarkBPool: Reused free connection.29


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


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

25 The Pool Manager creates a connection pool.26 The JNDI name used to look up the connection pool27 The DataSource class associated with the connection pool followed by the initial pool size, the minimum pool size, the maximum pool size,

and the user name.28 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.29 The driver requests a connection from the connection pool. The driver retrieves an available connection.


Troubleshooting connection pooling

jdbc/SalesforceNCMarkBPool: Number free connections = 1.


jdbc/SalesforceNCMarkBPool: Created new connection.30


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





jdbc/SalesforceNCMarkBPool: Connection was closed and added to the cache.31


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








30 The driver requests a connection from the connection pool. Because a connection is unavailable, the Pool Manager creates a new connection for the request.

31 A connection is closed by the application and returned to the connection pool.







jdbc/SalesforceNCMarkBPool: Enforced maximum!33


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

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

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


jdbc/SalesforceNCMarkBPool: Dumped free connection.34


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





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

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

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


Troubleshooting connection pooling








jdbc/SalesforceNCMarkBPool: Closing a pool of the group jdbc/SalesforceNCMarkBPool36


jdbc/SalesforceNCMarkBPool: Pool closed37


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.

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

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

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



See alsoStatement Pool Monitor on page 104

Generating an export file with the exportStatement method

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

Statement pool export file example

The 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]38

VERSION=139

[STMT_ENTRY]40

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

[STMT_ENTRY]41

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

38 A string that identifies the file as a statement pool export file.39 The version of the export file.40 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.41 The next statement pool entry.


Troubleshooting statement pooling

Using Java LoggingThe Salesforce driver provides a flexible and comprehensive logging mechanism that allows logging to beincorporated seamlessly with the logging of your own application or allows logging to be enabled and configuredindependently from the application.The logging mechanism can be instrumental in investigating and diagnosingissues. It also provides valuable insight into the type and number of operations requested by the applicationfrom the driver and requested by the driver from the remote data source. This information can help you tuneand optimize your application.

Logging Components

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

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

The Java Logging API defines the following levels:

• SEVERE

• WARNING

• INFO

• CONFIG

• FINE

• FINER

• FINEST

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

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

The driver exposes 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 driver and the responses from the driver back to theapplication. DataDirect Spy is used to log the JDBC calls.

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

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

OFF - Calls to the JDBC methods are not logged.

SQL Engine Logger

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.


Using Java Logging

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.

Configuring Logging

You 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 JVM for LoggingIf 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 inthe JRE/lib subdirectory of your JVM. The JRE looks for this file when it is loading.

You can also specify which properties file to use by setting the java.util.logging.config.file system property. Ata command prompt, enter:

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

where:

properties_file

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

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

• Use a single properties file for all Salesforce connections.

• Use a different properties file for each schema map. For example, if you have two maps (for example,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" for information on SchemaMap default values and how to specify valid values forSchemaMap.

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



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 219, it looks for a properties file nameduser_name.logging.properties in the directory containing the schema map for the connection, whereuser_name is your user ID used to connect to the Salesforce instance.

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

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

A sample properties file is installed in the install_dir/testforjdbc andinstall_dir/Examples/SforceSamples directories. The file is named ddlogging.properties.Youcan copy this file to the current working directory of your application or schema map configuration file directory,and modify it using a text editor for your needs.

See alsoSchemaMap on page 195LogConfigFile on page 186


Using Java Logging

6Supported SQL Statements and Extensions

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


• Alter Cache (EXT)

• Alter Index

• Alter Sequence

• Alter Session (EXT)

• Alter Table

• Create Cache (EXT)

• Create Index

• Create Sequence

• Create Table

• Create View

• Delete

• Drop Cache (EXT)

• Drop Index

• Drop Sequence


• Drop Table

• Drop View

• Explain Plan

• Insert

• Refresh Cache (EXT)

• Refresh Map (EXT)

• Select

• Update

• SQL Expressions

• Subqueries

Alter Cache (EXT)

PurposeChanges the definition of a cache on a remote table or view. An error is returned if the remote table or viewspecified does not exist.

Syntax

ALTER CACHE ON {remote_table | view} [REFERENCING (remote_table_ref[,remote_table_ref]...)] [REFRESH_INTERVAL {0 | -1 | interval_value [{M, H, D}]}] [INITIAL_CHECK [ONFIRSTCONNECT | FIRSTUSE | DEFAULT}] [PERSIST {TEMPORARY | MEMORY | DISK | DEFAULT}] [ENABLED {YES | TRUE | NO | FALSE}] [CALL_LIMIT {0 | -1 | max_calls}] [FILTER (expression)]

where:

remote_table

is the name of the remote table cache definition to be modified. The remote table name can be atwo-part name: schemaname.tablename. When specifying a two-part name, the specified remotetable must be defined in the specified schema, and you must have the privilege to alter objects inthe specified schema. When altering a relational cache, remote_table must specify the primarytable of the relational cache.

view

is the name of the view cache definition to be modified. The view name can be a two-part name:schemaname.viewname. When specifying a two-part name, the specified view must be defined inthe specified schema, and you must have the privilege to alter objects in the specified schema.Caches on views are not currently supported in the product.


Chapter 6: Supported SQL Statements and Extensions

REFERENCING

is an optional clause that specifies the name of the remote table(s) for which a relationship cache isto be created. See "Relational Caches" and "Referencing Clause" for a complete explanation.

REFRESH_INTERVAL

is an optional clause that specifies the length of time the data in the cached table can be used beforebeing refreshed. See "Refresh Interval Clause" for a complete explanation.

INITIAL_CHECK

is an optional clause that specifies when the driver initially checks whether the data in the cacheneeds refreshed. See "Initial Check Clause" for a complete explanation.

PERSIST

is an optional clause that specifies the life span of the data in the cached table or view. See "PersistClause" for a complete explanation.

ENABLED

is an optional clause that specifies whether the cache is enabled or disabled for use with SQLstatements. See "Enabled Clause" for a complete explanation.

CALL_LIMIT

is an optional clause that specifies the maximum number of Web service calls that can be used topopulate or refresh the cache. See "Call Limit Clause" for a complete explanation.

FILTER

is an optional clause that specifies a filter for the primary table to limit the number of rows that arecached in the primary table. See "Filter Clause" for a complete explanation.

Notes

• At least one of the optional clauses must be used. If two or more are specified, they must be specified inthe order shown in the grammar description.

See alsoRelational Caches on page 233Referencing Clause on page 234Refresh Interval Clause on page 234Initial Check Clause on page 235Persist Clause on page 235Enabled Clause on page 236Call Limit Clause on page 237Filter Clause on page 237


Alter Cache (EXT)

Relational Caches

If the Referencing clause is specified, the Alter Cache statement drops the existing cache and any referencedcaches and creates a new set of related caches, one for each of the tables specified in the statement. Thecache attributes for the existing cache are the default cache attributes for the new relational cache. Any attributesspecified in the Alter Cache statement override the default attributes. If the Referencing clause is not specified,the existing cache references, if any, are used.

If the cache being altered is a relational cache, the attributes specified in the Alter Cache statement apply toall of the caches that comprise the relational cache.

Alter Index

PurposeChanges the name of an existing index.

SyntaxALTER INDEX index_name RENAME TO new_name

where:

index_name

specifies an existing index name.

new_name

specifies the new index name.

Notes

• Index names must not conflict with other user-defined or system-defined names.

• Indexes on remote tables cannot be created, altered or dropped. Indexes can only be defined on localtables.

Alter Sequence

PurposeResets the next value of an existing sequence.

SyntaxALTER SEQUENCE sequence_name RESTART WITH value

where:



sequence_name

specifies an existing sequence.

value

specifies the next value to be returned through the Next Value For clause (see "Next Value forClause").

See alsoNext Value For Clause on page 239

Alter Session (EXT)

PurposeChanges various attributes of a local or remote session. A local session maintains the state of the overallconnection. A remote session maintains the state that pertains to a particular remote data source connection.

SyntaxALTER SESSION SET attribute_name=value

where:

attribute_name

specifies the name of the attribute to be changed. Attributes apply to either local or remote sessions.

value

specifies the value for that attribute.

The following table lists the local and remote session attributes, and provides descriptions of each.

Table 20: Alter Session Attributes

DescriptionSession TypeAttribute Name

Sets the current schema for the local session. The current schema isthe schema used when an identifier in a SQL statement is unqualified.The string value must be the name of a schema visible in the localsession. For example:

ALTER SESSION SET CURRENT_SCHEMA=sforce

LocalCurrent_Schema


Alter Session (EXT)

DescriptionSession TypeAttribute Name

Sets the maximum number of Web service calls the driver can makein executing a statement. Setting the Stmt_Call_Limit attribute has thesame effect as setting the StmtCallLimit connection property. It setsthe default Web service call limit used by any statement on theconnection. Executing this command on a statement overrides thepreviously set StmtCallLimit for the connection. The value specifiedmust be a positive integer or 0. The value 0 means that no call limitexists. For example:

ALTER SESSION SET STMT_CALL_LIMIT=150

LocalStmt_Call_Limit

Resets the Web service call count of a remote session to the valuespecified. The value must be 0 or a positive integer. WS_Call_Countrepresents the total number of Web service calls made to the remotedata source instance for the current session. For example:

ALTER SESSION SET sforce.WS_CALL_COUNT=0

The current value of WS_Call_Count can be obtained by referring tothe System_Remote_Sessions system table (seeSYSTEM_REMOTE_SESSIONS Catalog Table for details). Forexample:

SELECT * frominformation_schema.system_remote_sessions WHEREsession_id = cursessionid()

RemoteWs_Call_Count

Alter TableThe Alter Table statement adds or removes a column. The table being altered can be either a remote or localtable. A remote table is a Salesforce object and is exposed in the SFORCE schema. A local table is maintainedby the driver and is local to the machine on which the driver is running. A local table is exposed in the PUBLICschema.

• For information on altering a remote table, see "Altering a Remote Table."

• For information on altering a local table, see "Altering a Local Table."

Altering a Remote Table

Syntax

ALTER TABLE table_name[add_clause][drop_clause]

where:

table_name

specifies an existing remote table.



add_clause

specifies a column or a foreign key constraint to be added to the table. See "Add Clause: Columns"and "AddClause: Constraints" for a complete explanation.

drop_clause

specifies a column to be dropped from the table. See "Drop Clause: Columns" for a completeexplanation.

Notes

• You cannot drop a constraint from a remote table.

Add Clause: Columns

PurposeAdds a column to an existing table. It is optional.

Syntax

ADD [COLUMN] column_name Datatype ...[DEFAULT default_value] [[NOT]NULL] [EXT_ID] [PRIMARY KEY][START WITH starting_value]

default_value

is the default value to be assigned to the column. See "Column Definition for Remote Tables" fordetails.

starting_value

is the starting value for the Identity column. The default start value is 0.

Notes

• If NOT NULL is specified and the table is not empty, a default value must be specified. In all other respects,this command is the equivalent of a column definition in a Create Table statement.

• You cannot specify ANYTYPE, BINARY, COMBOBOX, or TIME data types in the column definition of AlterTable statements.

• If a SQL view includes SELECT * FROM for the table to which the column was added in the view’s Selectstatement, the new column is added to the view.

Example AAssuming the current schema is SFORCE, this example adds the status column with a default value ofACTIVE to the test table.

ALTER TABLE test ADD COLUMN status TEXT(30) DEFAULT 'ACTIVE'

Example BAssuming the current schema is SFORCE, this example adds a deptId column that can be used as a foreignkey column.


Alter Table

ALTER TABLE test ADD COLUMN deptId TEXT(18)

See alsoCreating a Remote Table on page 240

Add Clause: Constraints

PurposeAdds a constraint to an existing table. It is optional.

SyntaxADD [CONSTRAINT constraint_name] ...

Notes

• The only type of constraint you can add is a foreign key constraint.

• When adding a foreign key constraint, the table that contains the foreign key must be empty.

ExampleAssuming the current schema is SFORCE, a foreign key constraint is added to the deptId column of the testtable, referencing the rowId of the dept table. For the operation to succeed, the dept table must be empty.

ALTER TABLE test ADD FOREIGN KEY (deptId) REFERENCES dept(rowId)

Drop Clause: Columns

PurposeDrops a column from an existing table. It is optional.

SyntaxDROP {[COLUMN] column_name}

where:

column_name

specifies an existing column in an existing table.

Notes

• The column being dropped cannot have a constraint defined on it.

• Drop fails if a SQL view includes the column.

ExampleThis example drops the status column. For the operation to succeed, the status column cannot have aconstraint defined on it and cannot be used in a SQL view.

ALTER TABLE test DROP COLUMN status



Altering a Local Table

SyntaxALTER TABLE table_name [add_clause] [drop_clause] [rename_clause]

where:

table_name

specifies an existing local table.

add_clause

specifies a column or constraint to be added to the table. See "Add Clause: Columns" and "AddClause: Constraints" for a complete explanation.

drop_clause

specifies a column or constraint to be dropped from the table. See "Drop Clause: Columns" and"Drop Clause: Constraints" for a complete explanation.

rename_clause

specifies a new name for the table. See "Rename Clause" for a complete explanation.

See alsoAdd Clause: Columns on page 229Add Clause: Constraints on page 230Drop Clause: Columns on page 231Drop Clause: Constraints on page 231Rename Clause on page 231

Add Clause: Columns

PurposeUse the Add clause to add a column to an existing table. It is optional.

This clause adds a column to the end of the column list. It defines a column with the same syntax as the CreateTable command (see "Creating a Local Table"). If NOT NULL is specified and the table is not empty, a defaultvalue must be specified. In all other respects, this command is the equivalent of a column definition in a CreateTable statement.

SyntaxADD [COLUMN] column_nameDatatype ... [BEFORE existing_column]

Notes

• You cannot specify ANYTYPE, BINARY, COMBOBOX, or TIME data types in the column definition of AlterTable statements.

• The optional Before existing_column can be used to specify the name of an existing column so thatthe new column is inserted in a position just before the existing column.


Alter Table

• The optional Before existing_column can be used to specify the name of an existing column so thatthe new column is inserted in a position just before the existing column.

• If a SQL view includes SELECT * FROM for the table to which the column was added in the view’s Selectstatement, the new column is added to the view.

Example AAssuming the current schema is PUBLIC, this example adds the status column with a default value of ACTIVEto the test table.

ALTER TABLE test ADD COLUMN status VARCHAR(30) DEFAULT 'ACTIVE'

Example BAssuming the current schema is PUBLIC, this example adds a deptId column that can be used as a foreignkey column.

ALTER TABLE test ADD COLUMN deptId VARCHAR(18)

See alsoCreating a Local Table on page 244

Add Clause: Constraints

PurposeUse the Add clause to add a constraint to an existing table. It is optional.

This command adds a constraint using the same syntax as the Create Table command (see "ConstraintDefinition for Local Tables").

SyntaxADD [CONSTRAINT constraint_name] ...

Notes

• You cannot add a Unique constraint if one is already assigned to the same column list. A Unique constraintworks only if the values of the columns in the constraint columns list for the existing rows are unique orinclude a Null value.

• Adding a foreign key constraint to the table fails if, for each existing row in the referring table, a matchingrow (with equal values for the column list) is not found in the referenced table.

Example AAssuming the current schema is PUBLIC, this example adds a foreign key constraint to the deptId columnof the test table that references the rowId of the dept table.

ALTER TABLE test ADD CONSTRAINT test_fk FOREIGN KEY (deptId) REFERENCES dept(id)

See alsoConstraint Definition for Local Tables on page 247



Drop Clause: Columns

PurposeUse the Drop clause to drop a column from an existing table. It is optional.

SyntaxDROP {[COLUMN] column_name}

where:

column_name

specifies an existing column in an existing table.

Notes

• Drop fails if a SQL view includes the column.

Example AThis example drops the status column. For the operation to succeed, the status column cannot have aconstraint defined on it and cannot be used in a SQL view.

ALTER TABLE test DROP COLUMN status

Drop Clause: Constraints

PurposeUse the Drop clause to drop a constraint from an existing table. It is optional.

SyntaxDROP {[CONSTRAINT] constraint_name}

where:

constraint_name

specifies an existing constraint.

Notes

• The specified constraint cannot be a primary key constraint or unique constraint.

Example AThis example drops the test_fk constraint.

ALTER TABLE test DROP CONSTRAINT test_fk

Rename Clause

PurposeUse the Rename clause to rename an existing table. It is optional.


Alter Table

SyntaxRENAME TO new_name

where:

new_name

specifies the new name for the table.

Example AThis example renames the table to test2.

ALTER TABLE test RENAME TO test2

Create Cache (EXT)

PurposeThe Create Cache statement creates a cache that holds the data of a remote table.The data is not loaded intothe cache when the Create Cache statement is executed; the data is loaded the first time that the remote tableis executed or when a Refresh Cache statement on the remote table is executed. An error is returned if theremote table specified does not exist.

Syntax

CREATE CACHE ON {remote_table} [REFERENCING (remote_table_ref[,remote_table_ref]...)] [REFRESH_INTERVAL {0 | -1 | interval_value [{M, H, D}]}] [INITIAL_CHECK [{ONFIRSTCONNECT | FIRSTUSE | DEFAULT}] [PERSIST {TEMPORARY | MEMORY | DISK | DEFAULT}] [ENABLED {YES | TRUE | NO | FALSE}] [CALL_LIMIT {0 | -1 | max_calls}] [FILTER (expression)]

where:

remote_table

is the name of the remote table from which data is to be cached on the client. The name of thecached table is the same as the name of the remote table. When the table name is specified in aquery, the cached table is accessed, not the remote table.

The remote table name can be a two-part name:schemaname.tablename.When specifying a two-part name,the specified remote table must be defined in the specified schema, and you must have the privilege to createobjects in the specified schema.

REFERENCING

is an optional clause that specifies the name of the remote table(s) for which a relationship cache isto be created. See "Relational Caches" and "Referencing Clause" for a complete explanation.

REFRESH_INTERVAL

is an optional clause that specifies the length of time the data in the cached table can be used beforebeing refreshed. See "Refresh Interval Clause" for a complete explanation.



INITIAL_CHECK

is an optional clause that specifies when the driver initially checks whether the data in the cacheneeds refreshed. See "Initial Check Clause" for a complete explanation.

PERSIST

is an optional clause that specifies the life span of the data in the cached table or view. See "PersistClause" for a complete explanation.

ENABLED

is an optional clause that specifies whether the cache is enabled or disabled for use with SQLstatements. See "Enabled Clause" for a complete explanation.

CALL_LIMIT

is an optional clause that specifies the maximum number of Web service calls that can be used topopulate or refresh the cache. See "Call Limit Clause" for a complete explanation.

FILTER

is an optional clause that specifies a filter for the primary table to limit the number of rows that arecached in the primary table. See "Filter Clause" for a complete explanation.

Notes

• Caches on views are not supported.

• If two or more optional clauses are specified, they must be specified in the order shown in the grammardescription.

See alsoRelational Caches on page 233Referencing Clause on page 234Refresh Interval Clause on page 234Initial Check Clause on page 235Persist Clause on page 235Enabled Clause on page 236Call Limit Clause on page 237Filter Clause on page 237

Relational Caches

If the Referencing clause is specified, the Create Cache statement creates a set of related caches, one foreach of the tables specified in the statement. This set of caches is referred to as a related or relational cache.The set of caches in a relational cache is treated as a single entity. They are refreshed, altered, and droppedas a unit. Any attributes specified in the Create Cache statement apply to the cache created for the primarytable and to the caches created for all of the referenced tables specified.

A local session can have both standalone and relational caches defined, but only one cache can be definedon a table. If a table is referenced in a relational cache definition, a standalone cache cannot be created onthat table.


Create Cache (EXT)

Referencing Clause

PurposeThe Referencing clause specifies the name of the remote table(s) for which a relationship cache is to be created;it is optional. The specified remote table must be related to either the primary table being cached or one of theother specified related tables. The remote table name cannot include a schema name. The referenced tablesmust exist in the same schema as the primary table.

SyntaxREFERENCING (remote_table_ref[,remote_table_ref]...)]

where:

remote_table_ref

represents remote_table[.foreign_key_name]

remote_table

specifies one or more tables related to the primary table that are to be cached in conjunction withthe primary table.

foreign_key_name

specifies the name of the foreign key relationship between the remote table and the primary table(or, optionally, another related table). If a foreign key name is not specified, the driver attempts tofind a relationship between the remote table and one of the other tables specified in the relationalcache. The driver first looks for a relationship to the primary table. If a relationship to the primarytable does not exist, the driver then looks for a relationship to other referenced tables.

Refresh Interval Clause

PurposeThe Refresh Interval clause specifies the length of time the data in the cached table can be used before beingrefreshed; it is optional.The driver maintains a timestamp of when the data in a table was last refreshed. Whena cached table is used in a query, the driver checks if the current time is greater than the last refresh time plusthe value of Refresh_Interval. If it is, the driver refreshes the data in the cached table before processing thequery.

Syntax[REFRESH_INTERVAL {0 | -1 | interval_value [{M, H, D}]}]

where:

0

specifies that the cache is refreshed manually.You can use the Refresh Cache statement to refreshthe cache manually.



-1

resets the refresh interval to the default value of 12 hours.

interval_value

is a positive integer that specifies the amount of time between refreshes. The default unit of time ishours (H).You can also specify M for minutes or D for days. For example, 60M would set the timebetween refreshes to 60 minutes.The default refresh interval is 12 hours.

Initial Check Clause

PurposeThe Initial Check clause specifies when the driver performs its initial check of the data in the cache to determinewhether it needs to be refreshed; it is optional.

Syntax[INITIAL_CHECK [ONFIRSTCONNECT | FIRSTUSE | DEFAULT}]

where:

ONFIRSTCONNECT

specifies that the initial check is performed the first time a connection for a user is established.Subsequently, it is performed each time the table or view is used. A driver session begins on thefirst connection for a user and the session is active as long as at least one connection is open forthe user.

FIRSTUSE

specifies that the initial check is performed the first time the table or view is used in a query.Subsequently, it is performed each time the table or view is used.

DEFAULT

resets the value back to its default, which is FIRSTUSE.

Persist Clause

PurposeThe Persist clause specifies the life span of the data in the cached table or view; it is optional.

Syntax[PERSIST {TEMPORARY | MEMORY | DISK | DEFAULT}]

where:

TEMPORARY

specifies that the data exists for the life of the driver session. When the driver session ends, the datais discarded. A driver session begins on the first connection for a user and the session is active if atleast one connection is open for the user.


Create Cache (EXT)

MEMORY

specifies that the data exists beyond the life of the connection. While the connection is active, thecached data is stored in memory. When the connection is closed, the cached data is persisted todisk. If the connection ends abnormally, changes to the cached data may not be persisted to disk.This is the default.

DISK

specifies that the data exists beyond the life of the connection. A portion of the cached data is storedin memory while the connection is active. If the size of the cached data exceeds the cache memorythreshold, the remaining data is stored on disk. When the connection is closed, the portion of thecached data that is in memory is persisted to disk. If the connection ends abnormally, changes tothe cached data held in memory may not be persisted to disk.

DEFAULT

resets the PERSIST value back to its default, which is MEMORY.

Notes

• If you specify a value of MEMORY or DISK for the Persist clause, the remote data remains on the client pastthe lifetime of the application.

Enabled Clause

PurposeThe Enabled clause specifies whether the cache is enabled or disabled for use with SQL statements; it isoptional.

Syntax[ENABLED {YES | TRUE | NO | FALSE}]

where:

YES | TRUE

specifies that the cache is enabled. When a cache is enabled, the driver accesses the cached datafor the remote table or view when a query is executed.

The driver does not check whether the cache needs to be refreshed when the Alter Cache statementis used to enable the cache. The check occurs the next time that the cache is accessed.

NO | FALSE

specifies that the cache is disabled, which means that the driver accesses the data in the remotetable or view rather than the cache when a query is executed. The driver does not update the cachewhen inserts, updates, and deletes are performed on a remote table or view. To use the cache, youmust enable it.

All data in an existing cache is persisted on the client even when the cache is disabled, except forthe case where PERSIST is set to TEMPORARY.

The default is TRUE.



Call Limit Clause

PurposeThe Call Limit clause specifies the maximum number of Web service calls that can be used to populate orrefresh the cache; it is optional.

Syntax[CALL_LIMIT {0 | -1 | max_calls}]

where:

0

specifies no call limit.

-1

resets the call limit back to its default, which is 0 (no call limit).

max_calls

is a positive integer that specifies the maximum number of Web service calls.

The default value is 0.

Notes

• The call limit for a cache is independent of the Stmt_Call_Limit set on a local session. See "Alter Session(EXT)" for details.

If the call limit of a cache is exceeded during the population or refresh of the cache, the cache is markedas partially initialized. At the next refresh opportunity, the driver attempts to complete the population orrefresh of the cache. If the call limit (or other error) occurs during this second attempt, the cache becomesinvalid and is disabled. All data in the cache is discarded after the second attempt to populate or refreshthe cache fails. Before re-enabling the cache, consider altering the cache definition to allow more Webservice calls or specify a more restrictive filter, or both.

See alsoAlter Session (EXT) on page 225

Filter Clause

PurposeFilter is an optional clause that specifies a filter for the primary table to limit the number of rows that are cachedin the primary table. This clause is not supported for views.

Syntax[FILTER (expression)]

where:


Create Cache (EXT)

expression

is any valid Where clause. See "Where Clause" for details. Do not include the Where keyword in theclause. The filter for an existing cache can be removed by specifying an empty string for the filterexpression, for example, FILTER().

The default value is that cached data is not filtered.

ExampleThe following example filters by last activity date.

FILTER (lastactivitydate >= {d'2010-01-01'})

Example AThe Referencing clause allows multiple related tables to be cached as a single entity. The following examplecreates a cache on the remote table account.The cache is populated with all accounts that had activity in 2010.Additionally, caches are created for the following remote tables: opportunity, contact, andopportunitylineitem.These caches are populated with the opportunities and contacts that are associatedwith the accounts stored in the accounts cache and the opportunity line items associated with the opportunitiesstored in the opportunity cache.

CREATE CACHE ON account REFERENCING (opportunity, contact, opportunitylineitem)FILTER (lastactivitydate >= {d'2010-01-01'})

Example BThe following example caches all rows of the account table with a refresh interval of 12 hours, checks whetherdata of the cached table needs to be refreshed on the first use, persists the data beyond the life of the connection,and stores the data in memory while the connection is active.

CREATE CACHE ON account

Example CThe following example caches all active accounts in the account table with a refresh interval of 1 day, checkswhether data of the cached table needs to be refreshed when the connection is established, and discards thedata when the connection is closed.

CREATE CACHE ON account REFRESH_INTERVAL 1d INITIAL_CHECK ONFIRSTCONNECT PERSISTTEMPORARY FILTER(account.active = 'Yes')

See alsoWhere Clause on page 264

Create Index

PurposeCreates an index on one or more columns in a local table.

SyntaxCREATE [UNIQUE] INDEX index_name ON table_name (column_name [, ...])

where:



UNIQUE

means that key columns cannot have duplicate values.

index_name

specifies the name of the index to be created.

table_name

specifies an existing local table.

column_name

specifies an existing column.

Notes

• The driver cannot create an index in a remote table; the driver returns an error indicating that the operationcannot be performed on a remote table.

• Creating a unique constraint is the preferred way to specify that the values of a column must be unique.

Create Sequence

PurposeCreates an auto-incrementing sequence for a local table.

SyntaxCREATE SEQUENCE sequence_name [AS {INTEGER | BIGINT}] [START WITH start_value][INCREMENT BY increment_value]

where:

sequence_name

specifies the name of the sequence. By default, the sequence type is INTEGER.

start_value

specifies the starting value of the sequence. The default start value is 0.

increment_value

specifies the value of the increment; the value must be a positive integer. The default increment is1.

Next Value For Clause

PurposeSpecifies the next value for a sequence that is used in a Select, Insert, or Update statement.


Create Sequence

SyntaxNEXT VALUE FOR sequence_name

where:

sequence_name

specifies the name of the sequence from which to retrieve the value.

ExampleThis example retrieves the next value or set of values in Sequence1:

SELECT NEXT VALUE FOR Sequence1 FROM Account

Create TableUse the Create Table statement to create a new table.You can create either a remote or local table. A remotetable is a Salesforce object and is exposed in the SFORCE schema. Creating a table in the SFORCE schemacreates a remote table. A local table is maintained by the driver and is local to the machine on which the driveris running. A local table is exposed in the PUBLIC schema. Creating a table in the PUBLIC schema creates alocal table.

• For information on creating remote tables, see "Creating a Remote Table."

• For information on creating local tables, see "Creating a Local Table."

Creating a Remote Table

PurposeDefines the syntax to define a column for remote tables.

SyntaxCREATE TABLE table_name (column_definition [, ...] [, constraint_definition...])

where:

table_name

specifies the name of the new remote table. The table name can be qualified by a schema nameusing the format schema.table. If the schema is not specified, the table is created in the currentschema. See "Alter Session (EXT)" for information about changing the current schema.

column_definition

specifies the definition of a column in the new table. See "Column Definition for Remote Tables" fora complete explanation.

constraint_definition

specifies constraints on the columns of the new table. See "Constraint Definition for Remote Tables"for a complete explanation.



Notes

• Creating tables in Salesforce is not a quick operation. It can take several minutes for Salesforce to createthe table and its relationships.

See alsoAlter Session (EXT) on page 225

Column Definition for Remote Tables

PurposeDefines the syntax to define a column for remote tables.

Syntax

column_name Datatype [(precision[,scale])...] [DEFAULT default_value][[NOT]NULL][EXT_ID][PRIMARY KEY][START WITH starting_value]

where:

column_name

is the name to be assigned to the column.

Datatype

is the data type of the column to be created. See Data Types in the DataDirect Connect Series forJDBC User’s Guide for a list of supported Salesforce data types.You cannot specify ANYTYPE,BINARY, COMBOBOX, ENCRYPTEDTEXT, or TIME data types in the column definition ofCreate Table statements.

precision

is the total number of digits for NUMBER, CURRENCY, and PERCENT columns, and the length ofHTML, LONGTEXTAREA, and TEXT columns.

scale

is the number of digits to the right of the decimal point for NUMBER, CURRENCY, and PERCENTcolumns.

default_value

is the default value to be assigned to the column. The following default values are allowed in columndefinitions for remote tables:

• For character columns, a single-quoted string or NULL.

• For datetime columns, a single-quoted Date, Time, or Timestamp value or NULL.You can alsouse the following datetime SQL functions: CURRENT_DATE, CURRENT_ TIMESTAMP, TODAY,or NOW.

• For boolean columns, the literals FALSE, TRUE, NULL.

• For numeric columns, any valid number or NULL.


Create Table

starting_value

is the starting value for the Identity column. The default start value is 0.

[NOT]NULL

is used to specify whether NULL values are allowed or not allowed in a column. If NOT NULL isspecified, all rows in the table must have a column value. If NULL is specified or if neither NULL orNOT NULL is specified, NULL values are allowed in the column.

EXT_ID

is used to specify that the column is an external ID column.

PRIMARY KEY

can only be specified when the data type of the column is ID. ID columns are always the primarykey column for Salesforce.

START WITH

specifies the sequence of numbers generated for the Identity column. It can only be used when thedata type of the column definition is AUTONUMBER.

Example AAssuming the current schema is SFORCE, the remote table Test is created in the SFORCE schema. The idcolumn has a starting value of 1000.

CREATE TABLE Test (id AUTONUMBER START WITH 1000, Name TEXT(30))

Example BThe table name is qualified with a schema name that is not the current schema, creating the Test table in theSFORCE schema.The table is created with the following columns: id, Name, and Status.The Status columncontains a default value of ACTIVE.

CREATE TABLE SFORCE.Test (id NUMBER(9, 0), Name TEXT(30), Status TEXT(10) DEFAULT'ACTIVE')

Example CAssuming the current schema is SFORCE, the remote table dept is created with the name and deptIdcolumns. The deptId column can be used as an external ID column.

CREATE TABLE dept (name TEXT(30), deptId NUMBER(9, 0) EXT_ID)

Constraint Definition for Remote Tables

PurposeDefines a constraint for a remote table.

Syntax[CONSTRAINT [constraint_name] {foreign_key_constraint}]

where:



constraint_name

is ignored.The driver uses the Salesforce relationship naming convention to generate the constraintname.

foreign_key_constraint

defines a link between related tables. See "Foreign Key Clause" for the syntax.

A column defined as a foreign key in one table references a primary key in the related table. Onlyvalues that are valid in the primary key are valid in the foreign key. The following example is validbecause the foreign key values of the dept id column in the EMP table match those of the id columnin the referenced table DEPT:

Main TableReferenced Table

EMPDEPT

(Foreign Key)

dept idnameidnameid

1Mark1Dev1

3Jim1Finance2

2Mike1Sales3

The following example, however, is not valid. The value 4 in the dept id column does not match anyvalue in the referenced id column of the DEPT table.


EMPDEPT

(Foreign Key)

dept idnameidnameid

1Mark1Dev1

3Jim1Finance2

4Mike1Sales3

See alsoForeign Key Clause on page 244


Create Table

Foreign Key Clause

PurposeSpecifies a foreign key for a constraint.

Syntax

FOREIGN KEY (fcolumn_name) REFERENCES ref_table (pcolumn_name)

where:

fcolumn_name

specifies the foreign key column to which the constraint is applied.The data type of this column mustbe the same as the data type of the column it references.

ref_table

specifies the table to which the foreign key refers.

pcolumn_name

specifies the primary key column in the referenced table. For Salesforce, the primary key column isalways the rowId column.

ExampleAssuming the current schema is SFORCE, the remote table emp is created with the name, empId, and deptIdcolumns. The table contains a foreign key constraint on the deptId column, referencing the rowId in thedept table created in Example C. For the operation to succeed, the data type of the deptId column must bethe same as that of the rowId column.

CREATE TABLE emp (name TEXT(30), empId NUMBER(9, 0) EXT_ID, deptId TEXT(18),FOREIGN KEY(deptId) REFERENCES dept(rowId))

Creating a Local Table

Syntax

CREATE [{MEMORY | DISK | [GLOBAL] {TEMPORARY | TEMP}] TABLE table_name (column_definition [, ...] [, constraint_definition...]) [ON COMMIT {DELETE | PRESERVE} ROWS]

where:

MEMORY

creates the new table in memory. The data for a memory table is held entirely in memory for theduration of the local session. When the session is closed, the data for the memory table is persistedto disk.



DISK

creates the new table in on disk. A disk table caches a portion of its data in memory and the remainingdata on disk.

TEMPORARY | TEMP

creates the new table as a global temporary table. The GLOBAL qualifier is optional. The definitionof a global temporary table is visible to all connections. The data written to a global temporary tableis visible only to the connection used to write the data.

table_name

specifies the name of the new table.

column_definition

specifies the definition of a column in the new table. See "Column Definition for Local Tables" for acomplete explanation.

constraint_definition

specifies constraints on the columns of the new table. See "Constraint Definition for Local Tables"for a complete explanation.

ON COMMIT PRESERVE ROWS

preserves row values in a temporary table while the connection is open; this is the default action.

ON COMMIT DELETE ROWS

empties row values on each commit or rollback.

Notes

• If MEMORY, DISK, or TEMPORARY|TEMP is not specified, the new table is created in memory.

Column Definition for Local Tables

PurposeDefines a column for local tables.

Syntax

column_name Datatype [(precision[,scale])] [{DEFAULT default_value | GENERATED BY DEFAULT AS IDENTITY(START WITH n[, INCREMENT BY m])}] | [[NOT] NULL][IDENTITY] [PRIMARY KEY]

where:

column_name

is the name to be assigned to the column.


Create Table

Datatype

is the data type of the column to be created. See "Data Types" for a list of supported Salesforce datatypes.You cannot specify ANYTYPE, BINARY, COMBOBOX, or TIME data types in the columndefinition of Create Table statements.

precision

is the number characters for CHAR and VARCHAR columns, the number of bytes for BINARY andVARBINARY columns, and the total number of digits for DECIMAL columns.

scale

is the number of digits to the right of the decimal point for DECIMAL columns and the number offractional second digits for DATETIME columns.

default_value

is the default value to be assigned to the column. The following default values are allowed in columndefinitions for local tables:

• For character columns, a single-quoted string or NULL. The only SQL function that can be usedis CURRENT_USER.

• For datetime columns, a single-quoted Date, Time, or Timestamp value or NULL.You can alsouse the following datetime SQL functions: CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, TODAY, or NOW.

• For boolean columns, the literals FALSE, TRUE, NULL.

• For numeric columns, any valid number or NULL.

• For binary columns, any valid hexadecimal string or NULL.

IDENTITY | GENERATED BY DEFAULT AS IDENTITY

define an auto-increment column.You can only specify these clauses on INTEGER and BIGINTcolumns. Identity columns are considered primary key columns, so a table can have only one Identitycolumn.

The GENERATED BY DEFAULT AS IDENTITY clause is the standard SQL syntax for specifyingan Identity column.

The IDENTITY operator is equivalent to GENERATED BY DEFAULT AS IDENTITY without theoptional START WITH clause.

START WITH n[, INCREMENT BY m])

specifies the sequence of numbers generated for the Identity column. n and m are the starting andincrementing values, respectively, for an Identity column. The default start value is 0 and the defaultincrement value is 1.

Example AAssuming the current schema is PUBLIC, a local table is created. id is an identity column with a starting valueof 0 and an increment value of 1 because no Start With and Increment By clauses are specified.

CREATE TABLE Test (id INTEGER GENERATED BY DEFAULT AS IDENTITY, name VARCHAR(30))

This example is equivalent to the previous example.



CREATE TABLE Test (id INTEGER IDENTITY, name VARCHAR(30))

Example BAssuming the current schema is PUBLIC, a local table is created. id is an identity column with a starting valueof 2 and an increment of 2.

CREATE TABLE Test (id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 2,INCREMENT BY 2), name VARCHAR(30))

See alsoData Types on page 19

Constraint Definition for Local Tables

PurposeDefines a constraint for a local table.

Syntax

[CONSTRAINT [constraint_name] {unique_constraint |primary_key_constraint |foreign_key_constraint}]

where:

constraint_name

specifies a name for the constraint.

unique_constraint

specifies a constraint on a single column in the table. See Unique Clause for the syntax.

Values in the constrained column cannot be repeated, except in the case of null values. For example:

ColA 1 2 NULL 4 5 NULL

A single table can have multiple columns with unique constraints.

primary_key_constraint

specifies a constraint on one or more columns in the table. See Primary Key Clause for the syntax.

Values in a single column primary key column must be unique. Values across multiple constrainedcolumns cannot be repeated, but values within a column can be repeated. Null values are not allowed.For example:

Col A Col B 2 1


Create Table

3 1 4 2 5 2 6 2

Only one primary key constraint is allowed in the table.

foreign_key_constraint

defines a link between related tables. See Foreign Key Clause for the syntax.

A column defined as a foreign key in one table references a primary key in the related table. Onlyvalues that are valid in the primary key are valid in the foreign key. The following example is validbecause the foreign key values of the dept id column in the EMP table match those of the id columnin the referenced table DEPT:


EMPDEPT

(Foreign Key)

dept idnameidnameid

1Mark1Dev1

3Jim1Finance2

2Mike1Sales3

The following example, however, is not valid. The value 4 in the dept id column does not match anyvalue in the referenced id column of the DEPT table.


EMPDEPT

(Foreign Key)

dept idnameidnameid

1Mark1Dev1

3Jim1Finance2

4Mike1Sales3

Unique ClauseUNIQUE (column_name [,column_name...]

where:



column_name

specifies the column to which the constraint is applied. Multiple columns names must be separatedby commas.

Primary Key ClausePRIMARY KEY (column_name [,column_name...])

where:

column_name

specifies the primary key column to which the constraint is applied. Multiple column names must beseparated by commas.

Foreign Key Clause

FOREIGN KEY (fcolumn_name [,fcolumn_name...]) REFERENCES ref_table (pcolumn_name [,pcolumn_name...]) [ON {DELETE | UPDATE} {CASCADE | SET DEFAULT | SET NULL}]

where:

fcolumn_name

specifies the foreign key column to which the constraint is applied. Multiple column names must beseparated by commas.

ref_table

specifies the table to which a foreign key refers.

pcolumn_name

specifies the primary key column or columns referenced in the referenced table. Multiple columnnames must be separated by commas.

ON DELETE

defines the operation performed when a row in the table referenced by a foreign key constraint isdeleted. One of the following operators must be specified in the On Delete clause:

• CASCADE specifies that all rows in the foreign key table that reference the deleted row in the primary keytable are also deleted.

• SET DEFAULT specifies that the value of the foreign key column is set to the column default value for allrows in the foreign key table that reference the deleted row in the primary key table.

• SET NULL specifies that the value of the foreign key column is set to NULL for all rows in the foreign keytable that reference the deleted row in the primary key table.

ON UPDATE

defines the operation performed when the primary key of a row in the table referenced by a foreignkey constraint is updated. One of the following operators must be specified in the On Update clause:


Create Table

• CASCADE specifies that the value of the foreign key column for all rows in the foreign key table that referencethe row in the primary key table that had the primary key updated are updated with the new primary keyvalue.

• SET DEFAULT specifies that the value of the foreign key column is set to the column default value for allrows in the foreign key table that reference the row that had the primary key updated in the primary keytable.

• SET NULL specifies that the value of the foreign key column is set to NULL for all rows in the foreign keytable that reference the row that had the primary key updated in the primary key table.

Notes

• You must specify at least one constraint.

• Both the ON DELETE and ON UPDATE clauses can be used in a single foreign key definition.

ExampleAssuming the current schema is PUBLIC, the emp table is created with the name, empId, and deptId columns.The table contains a foreign key constraint on the deptId column that references the id column in the depttable. In addition, it sets the value of any rows in the deptId column to NULL that point to a deleted row inthe referenced dept table.

CREATE TABLE emp (name VARCHAR(30), empId INTEGER, deptId INTEGER,FOREIGN KEY(deptId) REFERENCES dept(id) ON DELETE SET NULL)

See alsoData Types on page 19

Create View

PurposeCreates a new view. A view is analogous to a named query. The view's query can refer to any combination ofremote and local tables as well as other views. Views are read-only; they cannot be updated.

Syntax

CREATE VIEW view_name[(view_column,...)] AS SELECT ... FROM ... [WHERE Expression] [ORDER BY order_expression [, ...]] [LIMIT limit [OFFSET offset]];

where:

view_name

specifies the name of the view.

view_column

specifies the column associated with the view. Multiple column names must be separated by commas.

The other commands used for Create View are the same as those used for Select (see "Select").



Notes

• A view can be thought of as a virtual table. The view is defined by a Select statement that is stored locally,though the data itself is not stored locally. The result set of the Select statement forms the virtual tablereturned by the view.You can use this virtual table by referring to the view name in SQL statements thesame way you refer to a table. A view is used to perform the following functions.

• Restrict a user to specific rows in a table.

• Restrict a user to specific columns.

• Join columns from multiple tables so that they function like a single table.

• Aggregate information instead of supplying details. For example, the sum of a column, or the maximumor minimum value from a column can be presented.

• Views are created by defining the Select statement that retrieves the data to be presented by the view.

• The Select statement in a View definition must return columns with distinct names. If the names of twocolumns in the Select statement are the same, use a column alias to distinguish between them. Alternatively,you can define a list of new columns for a view.

Example AThis example creates a view named myOpportunities that selects data from three tables to present a virtualtable of data.

CREATE VIEW myOpportunities AS SELECT a.name AS AccountName, o.name AS OpportunityName, o.amount AS Amount, o.description AS DescriptionFROM Opportunity o INNER JOIN Account a ON o.AccountId = a.id INNER JOIN User u ON o.OwnerId = u.id WHERE u.name = 'MyName' AND o.isClosed = 'false' ORDER BY Amount desc

You can then refer to the myOpportunities view in statements just as you would refer to a table. For example:

SELECT * FROM myOpportunities;

Example BThe myOpportunities view contains a detailed description for each opportunity, which may not be needed whenonly a summary is required. A view can be built that selects only specific myOpportunities columns as shownin this example:

CREATE VIEW myOpps_NoDesc as SELECT AccountName, OpportunityName, Amount FROM myOpportunities

The view selects the name column from both the opportunity and account tables.These columns are assignedthe alias OpportunityName and AccountName, respectively.

See alsoSelect on page 259


Create View

Delete

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

SyntaxDELETE FROM table_name [WHERE search_condition]

where:

table_name

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

search_condition

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

Notes

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

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

DELETE FROM emp WHERE emp_id = 'E10001'

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

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

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

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

Notes

• To enable Insert, Update, and Delete, set the ReadOnly connection option to false.

See alsoWhere Clause on page 264



Drop Cache (EXT)

PurposeDrops the cache defined on a remote table. To drop a relational cache, the specified table must be the primarytable of the relational cache. If a relational cache is specified, the cache for the primary table and all referencedcaches are dropped.

SyntaxDROP CACHE ON {remote_table} [IF EXISTS]

where:

remote_table

is the name of the remote table cache to be dropped. The remote table name can be a two-partname: schemaname.tablename. When specifying a two-part name, the specified remote tablemust be mapped in the specified schema, and you must have the privilege to drop objects in thespecified schema.

IF EXISTS

specifies that an error is not to be returned if a cache for the remote table or view does not exist.

Notes


Drop Index

PurposeDrops an index for a local table.

SyntaxDROP INDEX index_name [IF EXISTS]

where:

index_name

specifies an existing index.

IF EXISTS

specifies that an error is not to be returned if the index does not exist. The Drop Index commandgenerates an error if an index that is associated with a UNIQUE or FOREIGN KEY constraint isspecified.


Drop Cache (EXT)

Notes

• Indexes on a remote table cannot be dropped. Only indexes on local tables can be created, altered, anddropped.

Drop Sequence

PurposeDrops a sequence for a local table.

SyntaxDROP SEQUENCE sequence_name [IF EXISTS] [RESTRICT|CASCADE]

where:

sequence_name

specifies the name of a sequence to drop.

IF EXISTS

specifies that an error is not to be returned if the sequence does not exist.

RESTRICT

is in effect by default, meaning that the drop fails if any view refers to the sequence.

CASCADE

silently drops all dependent local objects.

Drop Table

PurposeDrops (removes) a remote or local table, its data, and its indexes. A remote table is a Salesforce object and isexposed in the SFORCE schema. Dropping a table in the SFORCE schema drops a remote table. A local tableis maintained by the driver and is local to the machine on which the driver is running. A local table is exposedin the PUBLIC schema. Dropping a table in the PUBLIC schema drops a local table.

SyntaxDROP TABLE table_name [IF EXISTS] [RESTRICT | CASCADE]

where:

table_name

specifies the name of an existing table to drop.



IF EXISTS

specifies that an error is not to be returned if the table does not exist.

RESTRICT

is in effect by default, meaning that the drop fails if any tables or views reference this table.

CASCADE

specifies that the drop extends to linked objects. If the specified table is a local table, it drops alldependent views and any foreign key constraints that link this table to other tables. If the specifiedtable is a remote table, any tables that reference the specified table also are dropped.

Drop View

PurposeDrops a view.

SyntaxDROP VIEW view_name [IF EXISTS] [RESTRICT | CASCADE]

where:

view_name

specifies the name of a view.

IF EXISTS

specifies that an error is not to be returned if the view does not exist.

RESTRICT

is in effect by default, meaning that the drop fails if any other view refers to this view.

CASCADE

silently drops all dependent views.

Explain Plan

PurposeRetrieves a detailed list of the elements in the execution plan. It generates a result set with a single columnnamed OPERATION. The individual elements that comprise the plan are returned as rows in the result set.

SyntaxEXPLAIN PLAN FOR {SELECT ... | DELETE ... | INSERT ... | UPDATE ...}


Drop View

The returned list of elements includes the indexes used for performing the query and can be used to optimizethe query.

Insert

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

• List of values to be inserted as a new row

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

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

table_name

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

column_name

is optional and specifies an existing column. Multiple column names (a column list) must be separatedby commas. A column list provides the name and order of the columns, the values of which arespecified in the Values clause. If you omit a column_name or a column list, the value expressionsmust provide values for all columns defined in the table and must be in the same order that thecolumns are defined for the table. Table columns that do not appear in the column list are populatedwith the default value, or with NULL if no default value is specified.

expression

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

select_statement

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

Notes


See alsoLiterals on page 271Select on page 259



Specifying an External ID Column

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

Syntaxcolumn_name EXT_ID [schema_name.[table_name.] ]ext_id_column

where:

EXT_ID

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

schema_name

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

table_name

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

ext_id_column

is the external ID column.

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

INSERT INTO emp (last_name, first_name, emp_id, salary, hire_date)VALUES ('Smith', 'John', 'E22345', 27500, {1999-04-06})

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

INSERT INTO emp1 (first_name, last_name, emp_id, dept, salary)SELECT first_name, last_name, emp_id, dept, salary FROM empWHERE dept = 'D050'


Insert

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

INSERT INTO emp (last_name, first_name, emp_id, salary, hire_date, accountId EXT_ID AccountNum)VALUES ('Smith', 'John', 'E22345', 27500, {1999-04-06}, 0001)

Refresh Cache (EXT)

PurposeForces the data in the cache for the specified remote table to be refreshed.

SyntaxREFRESH CACHE ON {remote_table | ALL} [CLEAN]

where:

remote_table

is the name of the remote table cache to be refreshed. The remote table name can be a two-partname: schemaname.tablename. When specifying a two-part name, the specified remote tablemust be mapped in the specified schema, and you must have the privilege to insert, update, anddelete objects in the specified schema.

ALL

forces all caches to be refreshed.

CLEAN

is optional and discards the data in the cache for the specified table or view, or all cache data if ALLis specified, and repopulates the cache with the data in the remote table or view.

Notes


Refresh Map (EXT)

PurposeThe REFRESH MAP statement adds newly discovered objects to your relational view of native data. It alsoincorporates any configuration changes made to your relational view by reloading the schema definition andassociated files.



SyntaxREFRESH MAP

Notes

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

Select

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

Syntax

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

where:

select_clause

specifies the columns from which results are to be returned by the query. See "Select" for a completeexplanation.

from_clause

specifies one or more tables on which the other clauses in the query operate. See "From" for acomplete explanation.

where_clause

is optional and restricts the results that are returned by the query. See "Where Clause" for a completeexplanation.

groupby_clause

is optional and allows query results to be aggregated in terms of groups. See "Group By Clause" fora complete explanation.

having_clause

is optional and specifies conditions for groups of rows (for example, display only the departmentsthat have salaries totaling more than $200,000). See "Having Clause" for a complete explanation.

UNION

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


Select

INTERSECT

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

EXCEPT | MINUS

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

orderby_clause

is optional and sorts the results that are returned by the query. See "Order By Clause" for a completeexplanation.

limit_clause

is optional and places an upper bound on the number of rows returned in the result. See "LimitClause" for a complete explanation.

Select Clause

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

Syntax

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

where:

LIMIT offset number

creates the result set for the Select statement first and then discards the first number of rows specifiedby offset and returns the number of remaining rows specified by number. To not discard any ofthe rows, specify 0 for offset, for example, LIMIT 0 number. To discard the first offset numberof rows and return all the remaining rows, specify 0 for number, for example, LIMIT offset0.

TOP number

is equivalent to LIMIT 0number.

column_expression

can be simply a column name (for example, last_name). More complex expressions may includemathematical operations or string manipulation (for example, salary * 1.05). See "SQLExpressions" for details.column_expression can also include aggregate functions. See "AggregateFunctions" for details.



column_alias

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

SELECT dep AS department FROM emp

DISTINCT

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

SELECT DISTINCT dep FROM emp

Notes

• Separate multiple column expressions with commas (for example, SELECT last_name, first_name,hire_date).

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

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

See alsoSQL Expressions on page 270

Aggregate FunctionsAggregate functions can also be a part of a Select clause. Aggregate functions return a single value from aset of rows. An aggregate can be used with a column name (for example, AVG(salary)) or in combinationwith a more complex column expression (for example, AVG(salary * 1.07)).

The following table lists supported aggregate functions.

Note: Doubly nested aggregates, such as SUM(COUNT(col1)), are currently not permitted by the driver.

Table 21: Aggregate Functions

ReturnsAggregate

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

AVG

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

Note: The driver does not support COUNT(DISTINCT *). For example, SELECTCOUNT(DISTINCT *) FROM mytable results in a syntax error.

COUNT


Select

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

MAX

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

MIN

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

SUM

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

SELECT COUNT(amount) AS numOpportunities, MAX(amount) AS maxAmount, AVG(amount) AS avgAmount FROM opportunity o INNER JOIN user u ON o.ownerId = u.id WHERE o.isClosed = 'false' AND u.name = 'MyName'

From Clause

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

SyntaxFROM table_name [table_alias] [,...]

where:

table_name

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

SELECT * FROM emp, dep

Subqueries can be used instead of table names. Subqueries must be enclosed in parentheses. See"Subquery in a From Clause" for an example.

table_alias

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

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

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



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

FROM emp E

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

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

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

Join in a From Clause

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

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

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

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

Note: The ON clause in a join expression must evaluate to a true or false value.

Syntax

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

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

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

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

Subquery in a From Clause

Subqueries can be used in the From clause in place of table references (table_name).

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

See alsoSubqueries on page 278


Select

Where Clause

PurposeSpecifies the conditions that rows must meet to be retrieved.

SyntaxWHERE expr1rel_operatorexpr2

where:

expr1

is either a column name, literal, or expression.

expr2

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

rel_operator

is the relational operator that links the two expressions.

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

SELECT last_name, first_name FROM emp WHERE salary >= 20000

See alsoSubqueries on page 278SQL Expressions on page 270

Group By Clause

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

SyntaxGROUP BY column_expression [,...]

where:

column_expression

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



ExampleThe following example totals the salaries in each department:

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

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


Having Clause

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

SyntaxHAVING expr1rel_operatorexpr2

where:

expr1 | expr2

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

rel_operator

is the relational operator that links the two expressions.

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

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


Union Operator

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


Select

Syntax

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

Notes

• When using the Union operator, the Select lists for each Select statement must have the same number ofcolumn expressions with the same data types and must be specified in the same order.

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

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

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

SELECT last_name, salary FROM empUNIONSELECT salary, last_name FROM raises

Intersect Operator

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

Syntax

select_statementINTERSECT [DISTINCT]select_statement

where:

DISTINCT

eliminates duplicate rows from the results.

Notes

• When using the Intersect operator, the Select lists for each Select statement must have the same numberof column expressions with the same data types and must be specified in the same order.




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


SELECT last_name, salary FROM empINTERSECTSELECT salary, last_name FROM raises

Except and Minus Operators

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

Syntax

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

where:

DISTINCT

eliminates duplicate rows from the results.

Notes

• When using one of these operators, the Select lists for each Select statement must have the same numberof column expressions with the same data types and must be specified in the same order.


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


Select


SELECT last_name, salary FROM empEXCEPTSELECT salary, last_name FROM raises

Order By Clause

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

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

where:

sort_expression

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

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

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

SELECT emp_id, last_name, first_name FROM emp

ORDER BY last_name, first_name

or

SELECT emp_id, last_name, first_name FROM emp

ORDER BY 2,3

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

See alsoSQL Expressions on page 270

Limit Clause

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

SyntaxLIMIT number_of_rows [OFFSET offset_number]



where:

number_of_rows

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

OFFSET

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

Notes

• In a compound query, the Limit clause can appear only on the final Select statement. The limit is appliedto the entire query, not to the individual Select statement to which it is attached.

ExampleThe following example returns a maximum of 20 rows.

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

Update

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

SyntaxUPDATE table_name SET column_name = expression

[, column_name = expression] [WHERE conditions]

table_name

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

column_name

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

expression

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

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

UPDATE emp SET salary=32000, exempt=1


Update

WHERE emp_id = 'E10001'

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

UPDATE emp SET salary = (SELECT avg(salary) FROM emp)

WHERE emp_id = 'E10001'

Notes


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

See alsoSubqueries on page 278Where Clause on page 264

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

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

The Salesforce driver supports both unquoted and quoted identifiers. An unquoted identifier must start with anASCII alpha character and can be followed by zero

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

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

Valid expression elements are:

• Column names

• Literals

• Operators

• Functions

Column Names

The most common expression is a simple column name.You can combine a column name with other expressionelements.



Literals

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

• Binary

• Character string

• Date

• Floating point

• Integer

• Numeric

• Time

• Timestamp

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

Table 22: Literal Syntax Examples

ExampleLiteral SyntaxSQL Type

12 or -34 or 0n

where

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

BIGINT

0

1

Min Value: 0

Max Value: 1

BOOLEAN

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

'2010-05-2118:33:05.025'

TIMESTAMP'ts'DATETIME

0.25

3.1415

-7.48

n.f

where:

n

is the integral part

f

is the fractional part

DECIMAL

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

n.fEx

where:

n is the integral part

f is the fractional part

x is the exponent

DOUBLE


SQL Expressions

ExampleLiteral SyntaxSQL Type

12 or -34 or 0n

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

INTEGER

'000482ff''hex_value'LONGVARBINARY

'This is a stringliteral'

'value'LONGVARCHAR

'2010-05-2118:33:05.025'

TIME'time'TIME

'This is a stringliteral'

'value'VARCHAR

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

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

Example

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

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

Example+1894.1204

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

Example'00af123d'

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

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



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

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

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

Notes

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

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

Example1994 or -2

Operators

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

Note: Numeric operators are restricted to numeric types. Numeric operators do not support non-numeric types.

Unary OperatorA unary operator operates on only one operand.

operator operand

Binary OperatorA binary operator operates on two operands.

operand1 operator operand2

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

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

Table 23: Arithmetic Operators

ExamplePurposeOperator

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

+ -


SQL Expressions


UPDATE emp SET sal = sal + sal *0.10

Multiplies, divides. These are binary operators.* /

SELECT sal + comm FROM emp WHEREempno > 100

Adds, subtracts. These are binary operators.+ -

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

Table 24: Concatenation Operator


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

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

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

The following table lists the supported comparison operators.

Table 25: Comparison Operators


SELECT * FROM emp WHERE sal =1500

Equality test.=

SELECT * FROM emp WHERE sal !=1500

Inequality test.!=<>

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

"Greater than" and "less than"tests.

><

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

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

>=<=




SELECT * FROM emp WHERE ENAMELIKE 'J%'

% and _ wildcards can be used tosearch for a pattern in a column.The percent sign denotes zero,one, or multiple characters, whilethe underscore denotes a singlecharacter. The right-hand side of aLIKE expression must evaluate toa string or binary.

LIKE

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

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

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

ESCAPE clause in LIKEoperator

LIKE 'pattern string' ESCAPE'c'

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

character in the pattern stringshould be treated as a regularcharacter.

The default escape character isbackslash (\).

This matches only records with name'JOE_JOHN'.

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

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

SELECT * FROM emp WHERE salBETWEEN 2000 AND 3000

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

[NOT] BETWEEN x AND y

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

Tests for existence of rows in asubquery.

EXISTS

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

Tests whether the value of thecolumn or expression is NULL.

IS [NOT] NULL

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


SQL Expressions

Table 26: Logical Operators


SELECT * FROM emp WHERE NOT (job IS NULL)SELECT * FROM emp WHERE NOT (sal BETWEEN 1000 AND 2000)

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

NOT

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

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

AND

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

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

OR

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

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

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

Table 27: Operator Precedence

OperatorPrecedence

+ (Positive), - (Negative)1

*(Multiply), / (Division)2

+ (Add), - (Subtract)3

|| (Concatenate)4

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

NOT, IN, LIKE6

AND7

OR8



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

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

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

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

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

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

Functions

The driver supports a number of functions that you can use in expressions, as listed and described in ScalarFunctions on page 282.

Conditions

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

Table 28: Conditions

DescriptionCondition

Specifies a comparison with expressions or subquery results.

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

Simple comparison

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

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

Group comparison

Tests for membership in a list or subquery.

[NOT] IN

Membership

Tests for inclusion in a range.

[NOT] BETWEEN

Range


SQL Expressions

DescriptionCondition

Tests for nulls.

IS NULL, IS NOT NULL

NULL

Tests for existence of rows in a subquery.

[NOT] EXISTS

EXISTS

Specifies a test involving pattern matching.

[NOT] LIKE

LIKE

Specifies a combination of other conditions.

CONDITION [AND/OR] CONDITION

Compound

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

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

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

IN Predicate

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

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

OR

value [NOT] IN (subquery)

ExampleSELECT * FROM emp WHERE deptno IN

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



EXISTS Predicate

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

SyntaxEXISTS (subquery)

Example

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

UNIQUE Predicate

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

SyntaxUNIQUE (subquery)

Example

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

Correlated Subqueries

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

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

Syntax

SELECT select_list FROM table1 t_alias1 WHERE expr rel_operator (SELECT column_list FROM table2 t_alias2


Subqueries

WHERE t_alias1.columnrel_operatort_alias2.column) UPDATE table1 t_alias1 SET column = (SELECT expr FROM table2 t_alias2 WHERE t_alias1.column = t_alias2.column) DELETE FROM table1 t_alias1 WHERE column rel_operator (SELECT expr FROM table2 t_alias2 WHERE t_alias1.column = t_alias2.column)

Notes

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

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

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

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

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

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

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

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

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



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

Note: The Progress DataDirect MongoDB for JDBC driver also supports the custom function escapeCAST_TO_NATIVE.

The escape sequence used by JDBC is:

{extension}

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


• Date, time, and timestamp escape sequences

• Scalar Functions

• Outer Join Escape Sequences

• LIKE escape character sequence for wildcards


• Native and Refresh Escape Sequences

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

{literal-type 'value'}

where:

literal-type

is one of the following:

Value FormatDescriptionliteral-type

yyyy-mm-ddDated

hh:mm:ss []Timet

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

Example:

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

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

{fn scalar-function}

where:

scalar-function

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

Example:

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

Table 29: Supported Scalar Functions

System FunctionsTimedate FunctionsNumericFunctions

String Functions

CURSESSIONIDCURDATEABSASCII

DATABASECURRENT_DATEACOSBIT_LENGTH

IDENTITYCURRENT_TIMEASINCHAR


Chapter 7: SQL escape sequences for JDBC

System FunctionsTimedate FunctionsNumericFunctions

String Functions

CURRENT_TIMESTAMPATANCHAR_LENGTH USER

CURTIMEATAN2CHARACTER_LENGTH

DATEDIFFBITANDCONCAT

DATE_ADDBITORDIFFERENCE

DATE_SUBBITXORHEXTORAW

DAYCEILINGINSERT

DAYNAMECOSLCASE

DAYOFMONTHCOTLEFT

DAYOFWEEKDEGREESLENGTH

DAYOFYEAREXPLOCATE

EXTRACTFLOORLOCATE_2

HOURLOGLOWER

MINUTELOG10LTRIM

MONTHMODOCTET_LENGTH

MONTHNAMEPIRAWTOHEX

NOWPOWERREPEAT

QUARTERRADIANSREPLACE

SECONDRANDRIGHT

SECONDS_SINCE_MIDNIGHTROUNDRTRIM

TIMESTAMPADDROUNDMAGICSOUNDEX

TIMESTAMPDIFFSIGNSPACE

TO_CHARSINSUBSTR

WEEKSQRTSUBSTRING

TANUCASE YEAR

TRUNCATEUPPER

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


Outer Join Escape Sequences

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.Status FROM {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.

The driver supports the following outer join escape sequences:

• Left outer joins

• Right outer joins

• Full outer joins

• Nested outer join

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

{escape 'escape-character'}

where:

escape-character

is the character used to escape the wildcard character.

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

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

Note: The right-hand side of a LIKE expression must evaluate to a string or binary.

Native and Refresh Escape SequencesThe driver supports the Native and Refresh escape sequences to embed data store-specific commands inSQL-92 statements. The Native escape sequence allows you to execute native commands directly throughthe client application, while the Refresh escape sequence is used to incorporate any changes introduced bythe Native escape into the driver's relational map of the data.



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}");



Native and Refresh Escape Sequences

8JDBC support

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


• JDBC and JVM Compatibility

• Supported functionality

JDBC and JVM CompatibilityThe drivers are compatible with JDBC 2.0, 3.0, 4.0, 4.1, and 4.2.

The drivers are supported on Java Virtual Machine (JVM) that is Java SE 8 or higher, including Oracle JDK,OpenJDK, and IBM SDK (Java) distributions.

Supported functionalityThis section lists functionality supported for the following JDBC interfaces.


Array

CommentsSupportedVersionIntroduced

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

Blob


Blob Methods

Yes4.0void free()

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

Yes2.0 CoreInputStream getBinaryStream()


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


Yes2.0 Corelong length()


Chapter 8: JDBC support


Blob Methods

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

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

Yes2.0 Corelong position(Blob, long)

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

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


Yes3.0OutputStream setBinaryStream(long)


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


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


Yes3.0void truncate(long)

CallableStatement


CallableStatement Methods

The Autonomous REST Connector and thedrivers for Aha!, GitHub, Jira, MicrosoftDynamics 365, 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 functionality



Supported for the SQL Server driver only.

All other drivers throw an "unsupportedmethod" exception.

Yes3.0Array getArray(String)


Yes4.0Reader getCharacterStream(int)

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

Yes4.0Reader getCharacterStream(String)

The Autonomous REST Connector and thedrivers for Aha!, GitHub, Jira, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, and Salesforce throw an "invalidparameter bindings" exception when yourapplication calls output parameters.

Yes2.0 CoreBigDecimal getBigDecimal(int)


Yes1.0BigDecimal getBigDecimal(int, int)


All other drivers throw "unsupportedmethod" exception.

Yes3.0BigDecimal getBigDecimal(String)



Yes2.0 CoreBlob getBlob(int)







Yes3.0Blob getBlob(String)


Yes1.0boolean getBoolean(int)



Yes3.0boolean getBoolean(String)


Yes1.0byte getByte(int)



Yes3.0byte getByte(String)


Yes1.0byte [] getBytes(int)

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

Yes3.0byte [] getBytes(String)







Yes2.0 CoreClob getClob(int)

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


Yes3.0Clob getClob(String)


Yes1.0Date getDate(int)


Yes2.0 CoreDate getDate(int, Calendar)



Yes3.0Date getDate(String)



Yes3.0Date getDate(String, Calendar)


Yes1.0double getDouble(int)







Yes3.0double getDouble(String)


Yes1.0float getFloat(int)



Yes3.0float getFloat(String)


Yes1.0int getInt(int)



Yes3.0int getInt(String)


Yes1.0long getLong(int)



Yes3.0long getLong(String)


Yes4.0Reader getNCharacterStream(int)






Yes4.0Reader getNCharacterStream(String)


Yes4.0NClob getNClob(int)


Yes4.0NClob getNClob(String)

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

Yes4.0String getNString(int)


Yes4.0String getNString(String)


Yes1.0Object getObject(int)

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



Yes3.0Object getObject(String)





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


Yes3.0Object getObject(String, Map)



No2.0 CoreRef getRef(int)

The drivers throw "unsupported method"exception.

No3.0Ref getRef(String)


Yes1.0short getShort(int)



Yes3.0short getShort(String)


Yes4.0SQLXML getSQLXML(int)


Yes4.0SQLXML getSQLXML(String)






Yes1.0String getString(int)



Yes3.0String getString(String)


Yes1.0Time getTime(int)


Yes2.0 CoreTime getTime(int, Calendar)



Yes3.0Time getTime(String)

Supported for SQL Server driver only.


Yes3.0Time getTime(String, Calendar)


Yes1.0Timestamp getTimestamp(int)






Yes2.0 CoreTimestamp getTimestamp(int, Calendar)



Yes3.0Timestamp getTimestamp(String)



Yes3.0Timestamp getTimestamp(String, Calendar)


No3.0URL getURL(int)


No3.0URL getURL(String)

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


Yes1.0void registerOutParameter(int, int)


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






The Oracle driver supports the Stringargument.

For all other drivers, the String argument isignored.

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




Yes3.0void registerOutParameter(String, int)




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



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

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





Supported for the Oracle driver only.


Yes2.0 Corevoid setArray(int, Array)



Yes4.0void setAsciiStream(String, InputStream)



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



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



Yes3.0void setBigDecimal(String, BigDecimal)



Yes4.0void setBinaryStream(String, InputStream)



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



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



Yes4.0void setBlob(String, Blob)



Yes4.0void setBlob(String, InputStream)



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







Yes3.0void setBoolean(String, boolean)



Yes3.0void setByte(String, byte)



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



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



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



Yes4.0void setClob(String, Clob)



Yes4.0void setClob(String, Reader)



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



Yes3.0void setDate(String, Date)



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



Yes3.0void setDouble(String, double)







Yes3.0void setFloat(String, float)



Yes3.0void setInt(String, int)



Yes3.0void setLong(String, long)

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

Yes4.0void setNClob(String, NClob)

Yes4.0void setNClob(String, Reader)

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

Yes4.0void setNString(String, String)

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



Yes3.0void setNull(String, int)



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



Yes3.0void setObject(String, Object)



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



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







Yes3.0void setShort(String, short)


Yes4.0void setSQLXML(String, SQLXML)



Yes3.0void setString(String, String)



Yes3.0void setTime(String, Time)



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



Yes3.0void setTimestamp(String, Timestamp)



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

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


No3.0void setURL(String, URL)

Yes1.0boolean wasNull()

Clob


Clob Methods

Yes4.0void free()




Clob Methods

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

Yes2.0 CoreInputStream getAsciiStream()


Yes2.0 CoreReader getCharacterStream()


Yes4.0Reader getCharacterStream(long, long)


Yes2.0 CoreString getSubString(long, int)


Yes2.0 Corelong length()


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

Yes2.0 Corelong position(Clob, long)


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

Yes2.0 Corelong position(String, long)


Yes3.0 CoreOutputStream setAsciiStream(long)


Yes3.0 CoreWriter setCharacterStream(long)


Yes3.0 Coreint setString(long, String)




Clob Methods


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


Yes3.0 Corevoid truncate(long)

Connection


Connection Methods

Yes1.0void clearWarnings()

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

Yes1.0void close()

Yes1.0void commit()

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 Aha, GitHub, Jira, MicrosoftDynamics 365, 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 CoreStatement createStatement(int, int)




Connection Methods

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

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

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


All other drivers throw "unsupported method"exception.

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

Yes1.0boolean getAutoCommit()

The Autonomous REST Connector and thedrivers for the listed database systemsreturn an empty string because they do nothave the concept of a catalog: Aha!,Amazon Redshift, Apache Cassandra,Apache Hive, Apache Spark SQL,Greenplum, GitHub, Jira, Impala, MicrosoftDynamics 365, MongoDB, Oracle, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, PostgreSQL, and Salesforce.

Yes1.0String getCatalog()

The Autonomous REST Connector and thedrivers for Aha!, Apache Cassandra, GitHub,Jira, Microsoft Dynamics 365, MongoDB,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, and Salesforce do notsupport storing or retrieving clientinformation.

Yes4.0String getClientInfo()


Yes4.0String getClientInfo(String)

Yes3.0int getHoldability()

Yes1.0DatabaseMetaData getMetaData()

Yes1.0int getTransactionIsolation()

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




Connection Methods

Yes1.0SQLWarning getWarnings()

Yes1.0boolean isClosed()

Yes1.0boolean isReadOnly()

Yes4.0boolean isValid()


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

Yes1.0String nativeSQL(String)

Yes1.0CallableStatement prepareCall(String)

For the Autonomous REST Connector andthe drivers for Aha!, Apache Cassandra,DB2, GitHub, Jira, Microsoft Dynamics 365,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)




Connection Methods

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

For the Autonomous REST Connector andthe drivers for Aha!, Apache Cassandra,GitHub, Jira, Microsoft Dynamics 365,MongoDB, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, andSalesforce, be aware that scroll-sensitiveresult sets are expensive from both a Webservice call and a performance perspective.The drivers expend a network round trip foreach row that is fetched.

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

All drivers throw "unsupported method"exception.

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

Supported for the Oracle and SQL Serverdrivers.


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



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

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

The Autonomous REST Connector and thedrivers for Aha!, Apache Cassandra, GitHub,Jira, Microsoft Dynamics 365, MongoDB,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, and Salesforce throw an"unsupported method" exception.

Yes3.0void releaseSavepoint(Savepoint)

Yes1.0void rollback()

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


Yes3.0void rollback(Savepoint)




Connection Methods

The Autonomous REST Connector and thedrivers for Aha!, Apache Cassandra, ApacheHive, Apache Spark SQL, GitHub, Impala,Jira, Microsoft Dynamics 365, 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 String argument.The corresponding drivers return an emptystring because they do not have the conceptof a catalog: Aha!, Amazon Redshift,Apache Cassandra, Apache Hive, ApacheSpark SQL, GitHub, Greenplum, Impala,Jira, Microsoft Dynamics 365, MongoDB,Oracle, Oracle Eloqua, Oracle Sales Cloud,Oracle Service Cloud, PostgreSQL, andSalesforce.

Yes1.0void setCatalog(String)


Yes4.0String setClientInfo(Properties)


Yes4.0String setClientInfo(String, String)

The DB2 driver supports the Holdabilityparameter value.

For other drivers, the Holdability parametervalue is ignored.

Yes3.0void setHoldability(int)

Yes1.0void setReadOnly(boolean)




Connection Methods

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


Yes3.0Savepoint setSavepoint()

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


Yes3.0Savepoint setSavepoint(String)

The Autonomous REST Connector and thedrivers for Aha!, Apache Cassandra, ApacheHive, Apache Spark SQL, GitHub, Impala,Jira, Microsoft Dynamics 365, 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)


ConnectionEventListener


ConnectionEventListener Methods

Yes3.0void connectionClosed(event)

Yes3.0void connectionErrorOccurred(event)



ConnectionPoolDataSource


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

DatabaseMetaData


DatabaseMetaData Methods

Yes4.0booleanautoCommitFailureClosesAllResultSets()

Yes1.0boolean allProceduresAreCallable()

Yes1.0boolean allTablesAreSelectable()

Yes1.0booleandataDefinitionCausesTransactionCommit()

Yes1.0booleandataDefinitionIgnoredInTransactions()

Yes2.0 Coreboolean deletesAreDetected(int)

Not supported by the SQL Server andSybase drivers.

Yes1.0boolean doesMaxRowSizeIncludeBlobs()

The Oracle driver may return results.

All other drivers return an empty result set.

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

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

Yes1.0ResultSet getCatalogs()





Yes1.0String getCatalogSeparator()

Yes1.0String getCatalogTerm()


Yes4.0String getClientInfoProperties()

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

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

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

Yes2.0 CoreConnection getConnection()

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

The Autonomous REST Connector and thedrivers for Aha!, Apache Cassandra, GitHub,Jira, Microsoft Dynamics 365, MongoDB,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, and Salesforce return anempty result set.

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

Yes4.0ResultSet getFunctions()

The Autonomous REST Connector and thedrivers for Aha!, Apache Cassandra, GitHub,Jira, Microsoft Dynamics 365, MongoDB,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, and Salesforce return anempty 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()

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 Aha!, GitHub, Jira, MicrosoftDynamics 365, Oracle Service Cloud, andSalesforce, SchemaName andProcedureName must be explicit values;they cannot be patterns.

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

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

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

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

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

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

Yes1.0String getProcedureTerm()

Yes3.0int getResultSetHoldability()

Yes1.0ResultSet getSchemas()

Yes4.0ResultSet getSchemas(catalog, pattern)

Yes1.0String getSchemaTerm()

Yes1.0String getSearchStringEscape()





Yes1.0String getSQLKeywords()

Yes3.0int getSQLStateType()

Yes1.0String getStringFunctions()

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

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

Yes1.0String getSystemFunctions()

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

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

Yes1.0ResultSet getTables(String, String, String,String [])

Yes1.0ResultSet getTableTypes()

Yes1.0String getTimeDateFunctions()

Yes1.0ResultSet getTypeInfo()

Supported for Oracle only.Yes2.0 CoreResultSet getUDTs(String, String, String,int [])

Yes1.0String getURL()

Yes1.0String getUserName()

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

Yes2.0 Coreboolean insertsAreDetected(int)

Yes1.0boolean isCatalogAtStart()

Yes1.0boolean isReadOnly()


Yes3.0boolean locatorsUpdateCopy()

Yes1.0boolean nullPlusNonNullIsNull()

Yes1.0boolean nullsAreSortedAtEnd()





Yes1.0boolean nullsAreSortedAtStart()

Yes1.0boolean nullsAreSortedHigh()

Yes1.0boolean nullsAreSortedLow()

Yes2.0 Coreboolean othersDeletesAreVisible(int)

Yes2.0 Coreboolean othersInsertsAreVisible(int)

Yes2.0 Coreboolean othersUpdatesAreVisible(int)

Yes2.0 Coreboolean ownDeletesAreVisible(int)

Yes2.0 Coreboolean ownInsertsAreVisible(int)

Yes2.0 Coreboolean ownUpdatesAreVisible(int)

Yes1.0boolean storesLowerCaseIdentifiers()

Yes1.0booleanstoresLowerCaseQuotedIdentifiers()

Yes1.0boolean storesMixedCaseIdentifiers()

Yes1.0booleanstoresMixedCaseQuotedIdentifiers()

Yes1.0boolean storesUpperCaseIdentifiers()

Yes1.0booleanstoresUpperCaseQuotedIdentifiers()

Yes1.0booleansupportsAlterTableWithAddColumn()

Yes1.0booleansupportsAlterTableWithDropColumn()

Yes1.0boolean supportsANSI92EntryLevelSQL()

Yes1.0boolean supportsANSI92FullSQL()

Yes1.0boolean supportsANSI92IntermediateSQL()

Yes2.0 Coreboolean supportsBatchUpdates()

Yes1.0booleansupportsCatalogsInDataManipulation()





Yes1.0booleansupportsCatalogsInIndexDefinitions()

Yes1.0booleansupportsCatalogsInPrivilegeDefinitions()

Yes1.0booleansupportsCatalogsInProcedureCalls()

Yes1.0booleansupportsCatalogsInTableDefinitions()

Yes1.0boolean supportsColumnAliasing()

Yes1.0boolean supportsConvert()

Yes1.0boolean supportsConvert(int, int)

Yes1.0boolean supportsCoreSQLGrammar()

Yes1.0boolean supportsCorrelatedSubqueries()

Yes1.0boolean supportsDataDefinitionAndDataManipulationTransactions()

Yes1.0booleansupportsDataManipulationTransactionsOnly()

Yes1.0booleansupportsDifferentTableCorrelationNames()

Yes1.0boolean supportsExpressionsInOrderBy()

Yes1.0boolean supportsExtendedSQLGrammar()

Yes1.0boolean supportsFullOuterJoins()

Yes3.0boolean supportsGetGeneratedKeys()

Yes1.0boolean supportsGroupBy()

Yes1.0boolean supportsGroupByBeyondSelect()

Yes1.0boolean supportsGroupByUnrelated()

Yes1.0booleansupportsIntegrityEnhancementFacility()

Yes1.0boolean supportsLikeEscapeClause()





Yes1.0boolean supportsLimitedOuterJoins()

Yes1.0boolean supportsMinimumSQLGrammar()

Yes1.0boolean supportsMixedCaseIdentifiers()

Yes1.0booleansupportsMixedCaseQuotedIdentifiers()

Yes3.0boolean supportsMultipleOpenResults()

Yes1.0boolean supportsMultipleResultSets()

Yes1.0boolean supportsMultipleTransactions()

Yes3.0boolean supportsNamedParameters()

Yes1.0boolean supportsNonNullableColumns()

Yes1.0booleansupportsOpenCursorsAcrossCommit()

Yes1.0booleansupportsOpenCursorsAcrossRollback()

Yes1.0booleansupportsOpenStatementsAcrossCommit()

Yes1.0booleansupportsOpenStatementsAcrossRollback()

Yes1.0boolean supportsOrderByUnrelated()

Yes1.0boolean supportsOuterJoins()

Yes1.0boolean supportsPositionedDelete()

Yes1.0boolean supportsPositionedUpdate()

Yes2.0 Coreboolean supportsResultSetConcurrency(int,int)

Yes3.0boolean supportsResultSetHoldability(int)

Yes2.0 Coreboolean supportsResultSetType(int)

Yes3.0boolean supportsSavePoints()

Yes1.0booleansupportsSchemasInDataManipulation()





Yes1.0booleansupportsSchemasInIndexDefinitions()

Yes1.0booleansupportsSchemasInPrivilegeDefinitions()

Yes1.0booleansupportsSchemasInProcedureCalls()

Yes1.0booleansupportsSchemasInTableDefinitions()

Yes1.0boolean supportsSelectForUpdate()

Yes4.0booleansupportsStoredFunctionsUsingCallSyntax()

Yes1.0boolean supportsStoredProcedures()

Yes1.0booleansupportsSubqueriesInComparisons()

Yes1.0boolean supportsSubqueriesInExists()

Yes1.0boolean supportsSubqueriesInIns()

Yes1.0boolean supportsSubqueriesInQuantifieds()

Yes1.0boolean supportsTableCorrelationNames()

Yes1.0booleansupportsTransactionIsolationLevel(int)

Yes1.0boolean supportsTransactions()

Yes1.0boolean supportsUnion()

Yes1.0boolean supportsUnionAll()


Yes2.0 Coreboolean updatesAreDetected(int)

Yes1.0boolean usesLocalFilePerTable()

Yes1.0boolean usesLocalFiles()



DataSource

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


DataSource Methods

Yes2.0 OptionalConnection getConnection()

Yes2.0 OptionalConnection getConnection(String, String)

Yes2.0 Optionalint getLoginTimeout()

Yes2.0 OptionalPrintWriter getLogWriter()


Yes2.0 Optionalvoid setLoginTimeout(int)

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

Yes2.0 Optionalvoid setLogWriter(PrintWriter)


Driver


Driver Methods

Yes1.0boolean acceptsURL(String)

Yes1.0Connection connect(String, Properties)

Yes1.0int getMajorVersion()

Yes1.0int getMinorVersion()

Yes1.0DriverPropertyInfo [] getPropertyInfo(String,Properties)



ParameterMetaData


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

Yes3.0int getParameterCount()


Yes3.0int getParameterMode(int)


Yes3.0int getParameterType(int)


Yes3.0String getParameterTypeName(int)


Yes3.0int getPrecision(int)


Yes3.0int getScale(int)


Yes3.0int isNullable(int)




ParameterMetaData Methods


Yes3.0boolean isSigned(int)


Yes1.0boolean jdbcCompliant()


PooledConnection


PooledConnection Methods

Yes2.0 Optionalvoid addConnectionEventListener(listener)

Yes4.0void addStatementEventListener(listener)

Yes2.0 Optionalvoid close()

A pooled connection object can have onlyone Connection object open (the one mostrecently created). The purpose of allowingthe server (PoolManager implementation)to invoke this a second time is to give anapplication server a way to take aconnection away from an application andgive it to another user (a rare occurrence).The drivers do not support the "reclaiming"of connections and will throw an exception.

Yes2.0 OptionalConnection getConnection()

Yes2.0 OptionalvoidremoveConnectionEventListener(listener)

Yes4.0voidremoveStatementEventListener(listener)

PreparedStatement


PreparedStatement Methods

Yes2.0 Corevoid addBatch()





Yes1.0void clearParameters()

Yes1.0boolean execute()

Yes1.0ResultSet executeQuery()

Yes1.0int executeUpdate()

Yes2.0 CoreResultSetMetaData getMetaData()

Yes3.0ParameterMetaDatagetParameterMetaData()



All other drivers throw an "unsupportedmethod" exception.

Yes2.0 Corevoid setArray(int, Array)

Yes4.0void setAsciiStream(int, InputStream)

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

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

Yes1.0void setBigDecimal(int, BigDecimal)

When used with Blobs, the DB2 driver onlysupports with DB2 V8.x and higher forLinux/UNIX/Windows, DB2 for z/OS (allversions), and DB2 for i.

Yes4.0void setBinaryStream(int, InputStream)


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


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


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

Yes2.0 Corevoid setBlob(int, Blob)







Yes4.0void setBlob(int, InputStream)



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

Yes1.0void setBoolean(int, boolean)

Yes1.0void setByte(int, byte)


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

Yes4.0void setCharacterStream(int, Reader)

Yes2.0 Corevoid setCharacterStream(int, Reader, int)

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

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

Yes2.0 Corevoid setClob(int, Clob)


Yes4.0void setClob(int, Reader)


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

Yes1.0void setDate(int, Date)

Yes2.0 Corevoid setDate(int, Date, Calendar)

Yes1.0void setDouble(int, double)

Yes1.0void setFloat(int, float)





Yes1.0void setInt(int, int)

Yes1.0void setLong(int, long)

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

Yes4.0void setNCharacterStream(int, Reader)


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


Yes4.0void setNClob(int, NClob)


Yes4.0void setNClob(int, Reader)


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

Yes1.0void setNull(int, int)

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

Yes4.0void setNString(int, String)

Yes1.0void setObject(int, Object)





Yes1.0void setObject(int, Object, int)

Yes1.0void setObject(int, Object, int, int)

The DB2 driver supports setting a timeoutvalue, in seconds, for a statement withDB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the execution of thestatement exceeds the timeout value, thestatement is timed out by the databaseserver, and the driver throws an exceptionindicating that the statement was timed out.The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The Informix driver throws an "unsupportedmethod" exception.

The Autonomous REST Connector and thedrivers for Aha!, GitHub, Jira, MicrosoftDynamics 365, MongoDB, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,and Salesforce ignore any value set usingthis method. Use the WSTimeout connectionproperty to set a timeout value.

The drivers for Apache Cassandra andMongoDB ignore any value set using thismethod.

All other drivers support setting a timeoutvalue, in seconds, for a statement. If theexecution of the statement exceeds thetimeout value, the statement is timed out bythe database server, and the driver throwsan exception indicating that the statementwas timed out.

Yes1.0void setQueryTimeout(int)


No2.0 Corevoid setRef(int, Ref)

Yes1.0void setShort(int, short)

Yes4.0void setSQLXML(int, SQLXML)

Yes1.0void setString(int, String)

Yes1.0void setTime(int, Time)

Yes2.0 Corevoid setTime(int, Time, Calendar)

Yes1.0void setTimestamp(int, Timestamp)





Yes2.0 Corevoid setTimestamp(int, Timestamp,Calendar)

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

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



No3.0void setURL(int, URL)

Ref


Ref MethodsRef interface

No2.0 Core(all)

ResultSet


ResultSet Methods

Yes2.0 Coreboolean absolute(int)

Yes2.0 Corevoid afterLast()

Yes2.0 Corevoid beforeFirst()

Yes2.0 Corevoid cancelRowUpdates()


Yes1.0void close()

Yes2.0 Corevoid deleteRow()

Yes1.0int findColumn(String)

Yes2.0 Coreboolean first()

Yes2.0 CoreArray getArray(int)

Yes2.0 CoreArray getArray(String)




ResultSet Methods

Yes1.0InputStream getAsciiStream(int)

Yes1.0InputStream getAsciiStream(String)

Yes2.0 CoreBigDecimal getBigDecimal(int)

Yes1.0BigDecimal getBigDecimal(int, int)

Yes2.0 CoreBigDecimal getBigDecimal(String)

Yes1.0BigDecimal getBigDecimal(String, int)

The DB2 driver supports for all DB2 versionswhen retrieving BINARY, VARBINARY, andLONGVARBINARY data. The DB2 driveronly supports with DB2 V8.x and higher forLinux/UNIX/Windows, DB2 for z/OS (allversions), and DB2 for i when retrieving Blobdata.

Yes1.0InputStream getBinaryStream(int)


Yes1.0InputStream getBinaryStream(String)



Yes2.0 CoreBlob getBlob(int)



Yes2.0 CoreBlob getBlob(String)

Yes1.0boolean getBoolean(int)

Yes1.0boolean getBoolean(String)

Yes1.0byte getByte(int)

Yes1.0byte getByte(String)




ResultSet Methods


Yes1.0byte [] getBytes(int)


Yes1.0byte [] getBytes(String)

Yes2.0 CoreReader getCharacterStream(int)

Yes2.0 CoreReader getCharacterStream(String)


Yes2.0 CoreClob getClob(int)


Yes2.0 CoreClob getClob(String)

Yes2.0 Coreint getConcurrency()


No1.0String getCursorName()

Yes1.0Date getDate(int)

Yes2.0 CoreDate getDate(int, Calendar)

Yes1.0Date getDate(String)

Yes2.0 CoreDate getDate(String, Calendar)

Yes1.0double getDouble(int)

Yes1.0double getDouble(String)

Yes2.0 Coreint getFetchDirection()

Yes2.0 Coreint getFetchSize()

Yes1.0float getFloat(int)




ResultSet Methods

Yes1.0float getFloat(String)

Yes4.0int getHoldability()

Yes1.0int getInt(int)

Yes1.0int getInt(String)

Yes1.0long getLong(int)

Yes1.0long getLong(String)

Yes1.0ResultSetMetaData getMetaData()

Yes4.0Reader getNCharacterStream(int)

Yes4.0Reader getNCharacterStream(String)

Yes4.0NClob getNClob(int)

Yes4.0NClob getNClob(String)

Yes4.0String getNString(int)

Yes4.0String getNString(String)

The DB2 driver returns a Long object whencalled on Bigint columns.

Yes1.0Object getObject(int)

The Oracle and Sybase drivers support theMap argument. For all other drivers, the Mapargument is ignored.

Yes2.0 CoreObject getObject(int, Map)

Yes1.0Object getObject(String)

The Oracle and Sybase drivers support theMap argument. For all other drivers, the Mapargument is ignored.

Yes2.0 CoreObject getObject(String, Map)


No2.0 CoreRef getRef(int)


No2.0 CoreRef getRef(String)

Yes2.0 Coreint getRow()

Yes1.0short getShort(int)

Yes1.0short getShort(String)




ResultSet Methods

Yes4.0SQLXML getSQLXML(int)

Yes4.0SQLXML getSQLXML(String)

Yes2.0 CoreStatement getStatement()

Yes1.0String getString(int)

Yes1.0String getString(String)

Yes1.0Time getTime(int)

Yes2.0 CoreTime getTime(int, Calendar)

Yes1.0Time getTime(String)

Yes2.0 CoreTime getTime(String, Calendar)

Yes1.0Timestamp getTimestamp(int)

Yes2.0 CoreTimestamp getTimestamp(int, Calendar)

Yes1.0Timestamp getTimestamp(String)

Yes2.0 CoreTimestamp getTimestamp(String, Calendar)

Yes2.0 Coreint getType()


No1.0InputStream getUnicodeStream(int)


No1.0InputStream getUnicodeStream(String)


No3.0URL getURL(int)


No3.0URL getURL(String)


Yes2.0 Corevoid insertRow()

Yes2.0 Coreboolean isAfterLast()

Yes2.0 Coreboolean isBeforeFirst()




ResultSet Methods


Yes2.0 Coreboolean isFirst()

Yes2.0 Coreboolean isLast()


Yes2.0 Coreboolean last()

Yes2.0 Corevoid moveToCurrentRow()

Yes2.0 Corevoid moveToInsertRow()

Yes1.0boolean next()

Yes2.0 Coreboolean previous()

Yes2.0 Corevoid refreshRow()

Yes2.0 Coreboolean relative(int)

Yes2.0 Coreboolean rowDeleted()

Yes2.0 Coreboolean rowInserted()

Yes2.0 Coreboolean rowUpdated()

Yes2.0 Corevoid setFetchDirection(int)

Yes2.0 Corevoid setFetchSize(int)



No3.0void updateArray(int, Array)


No3.0void updateArray(String, Array)

Yes2.0 Corevoid updateAsciiStream(int, InputStream,int)

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

Yes4.0void updateAsciiStream(String, InputStream)

Yes2.0 Corevoid updateAsciiStream(String, InputStream,int)




ResultSet Methods

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

Yes2.0 Corevoid updateBigDecimal(int, BigDecimal)

Yes2.0 Corevoid updateBigDecimal(String, BigDecimal)

Yes4.0void updateBinaryStream(int, InputStream)

Yes2.0 Corevoid updateBinaryStream(int, InputStream,int)

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

Yes4.0void updateBinaryStream(String,InputStream)

Yes2.0 Corevoid updateBinaryStream(String,InputStream, int)

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



Yes3.0void updateBlob(int, Blob)



Yes4.0void updateBlob(int, InputStream)



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




ResultSet Methods



Yes3.0void updateBlob(String, Blob)



Yes4.0void updateBlob(String, InputStream)



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

Yes2.0 Corevoid updateBoolean(int, boolean)

Yes2.0 Corevoid updateBoolean(String, boolean)

Yes2.0 Corevoid updateByte(int, byte)

Yes2.0 Corevoid updateByte(String, byte)

Yes2.0 Corevoid updateBytes(int, byte [])

Yes2.0 Corevoid updateBytes(String, byte [])

Yes4.0void updateCharacterStream(int, Reader)

Yes2.0 Corevoid updateCharacterStream(int, Reader,int)

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

Yes4.0void updateCharacterStream(String,Reader)

Yes2.0 Corevoid updateCharacterStream(String,Reader, int)

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




ResultSet Methods


Yes3.0void updateClob(int, Clob)


Yes4.0void updateClob(int, Reader)


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


Yes3.0void updateClob(String, Clob)


Yes4.0void updateClob(String, Reader)


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

Yes2.0 Corevoid updateDate(int, Date)

Yes2.0 Corevoid updateDate(String, Date)

Yes2.0 Corevoid updateDouble(int, double)

Yes2.0 Corevoid updateDouble(String, double)

Yes2.0 Corevoid updateFloat(int, float)

Yes2.0 Corevoid updateFloat(String, float)

Yes2.0 Corevoid updateInt(int, int)

Yes2.0 Corevoid updateInt(String, int)

Yes2.0 Corevoid updateLong(int, long)

Yes2.0 Corevoid updateLong(String, long)

For the Autonomous REST Connector andthe drivers for Aha!, GitHub, Jira, MicrosoftDynamics 365, MongoDB, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,and Salesforce, N methods are identical totheir non-N counterparts.

Yes4.0void updateNCharacterStream(int, Reader)




ResultSet Methods


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


Yes4.0void updateNCharacterStream(String,Reader)


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


Yes4.0void updateNClob(int, NClob)


Yes4.0void updateNClob(int, Reader)


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


Yes4.0void updateNClob(String, NClob)




ResultSet Methods

For the Autonomous REST Connector andthe drivers for GitHub, Jira, MicrosoftDynamics 365, MongoDB, Oracle Eloqua,Oracle Sales Cloud, Oracle Service Cloud,and Salesforce, N methods are identical totheir non-N counterparts.

Yes4.0void updateNClob(String, Reader)


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


Yes4.0void updateNString(int, String)


Yes4.0void updateNString(String, String)

Yes2.0 Corevoid updateNull(int)

Yes2.0 Corevoid updateNull(String)

Yes2.0 Corevoid updateObject(int, Object)

Yes2.0 Corevoid updateObject(int, Object, int)

Yes2.0 Corevoid updateObject(String, Object)

Yes2.0 Corevoid updateObject(String, Object, int)


No3.0void updateRef(int, Ref)


No3.0void updateRef(String, Ref)

Yes2.0 Corevoid updateRow()

Yes2.0 Corevoid updateShort(int, short)

Yes2.0 Corevoid updateShort(String, short)




ResultSet Methods

Yes4.0void updateSQLXML(int, SQLXML)

Yes4.0void updateSQLXML(String, SQLXML)

Yes2.0 Corevoid updateString(int, String)

Yes2.0 Corevoid updateString(String, String)

Yes2.0 Corevoid updateTime(int, Time)

Yes2.0 Corevoid updateTime(String, Time)

Yes2.0 Corevoid updateTimestamp(int, Timestamp)

Yes2.0 Corevoid updateTimestamp(String, Timestamp)

Yes1.0boolean wasNull()

ResultSetMetaData


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




ResultSetMetaData Methods

Yes1.0boolean isCaseSensitive(int)

Yes1.0boolean isCurrency(int)

Yes1.0boolean isDefinitelyWritable(int)

Yes1.0int isNullable(int)

Yes1.0boolean isReadOnly(int)

Yes1.0boolean isSearchable(int)

Yes1.0boolean isSigned(int)


Yes1.0boolean isWritable(int)


RowSet


RowSet Methods

No2.0 Optional(all)

SavePoint


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



Statement


Statement Methods

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

Yes2.0 Corevoid addBatch(String)

The DB2 driver cancels the execution of thestatement with DB2 V8.x and higher for

Yes1.0void cancel()

Linux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the statement is canceledby the database server, the driver throwsan exception indicating that it was canceled.The DB2 driver throws an "unsupportedmethod" exception with other DB2 versions.

The Autonomous REST Connector and thedrivers for Aha!, Apache Cassandra, GitHub,Impala, Informix, Jira, Microsoft Dynamics365, MongoDB, Progess OpenEdge, OracleService Cloud, Oracle Eloqua, Oracle SalesCloud, and Salesforce throw an"unsupported method" exception.

The Apache Hive, Apache Spark SQL42,Greenplum, Oracle, PostgreSQL, SQLServer, Sybase, and Amazon Redshiftdrivers cancel the execution of thestatement. If the statement is canceled bythe database server, the driver throws anexception indicating that it was canceled.

Yes2.0 Corevoid clearBatch()


Yes1.0void close()


Yes1.0boolean execute(String)

Yes3.0boolean execute(String, int)



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

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




Statement Methods



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

Yes2.0 Coreint [] executeBatch()


Yes1.0ResultSet executeQuery(String)


Yes1.0int executeUpdate(String)

Yes3.0int executeUpdate(String, int)



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



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.




Statement Methods

The Autonomous REST Connector and thedrivers for Aha!, Apache Cassandra, GitHub,Jira, MongoDB, Microsoft Dynamics 365,Oracle Eloqua, Oracle Service Cloud, andSalesforce return the ID of the last row thatwas inserted.

Auto-generated keys are not supported inany of the other drivers.

Yes1.0int getMaxFieldSize()

Yes1.0int getMaxRows()

Yes1.0boolean getMoreResults()

Yes3.0boolean getMoreResults(int)

The DB2 driver returns the timeout value,in seconds, set for the statement with

Yes1.0int getQueryTimeout()

DB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. The DB2 driver returns 0with other DB2 versions.

The Apache Hive, Apache Spark SQL,Impala, Informix and Progress OpenEdgedrivers return 0.

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 Aha!, GitHub, Jira, MicrosoftDynamics 365, 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()





Statement Methods


Yes4.0boolean isPoolable()


Throws "unsupported method" exception.No1.0void setCursorName(String)

Ignored.Yes1.0void setEscapeProcessing(boolean)

Yes2.0 Corevoid setFetchDirection(int)

Yes2.0 Corevoid setFetchSize(int)

Yes1.0void setMaxFieldSize(int)

Yes1.0void setMaxRows(int)

Yes4.0void setPoolable(boolean)

The DB2 driver supports setting a timeoutvalue, in seconds, for a statement with

Yes1.0void setQueryTimeout(int)

DB2 V8.x and higher forLinux/UNIX/Windows and DB2 V8.1 andhigher for z/OS. If the execution of thestatement exceeds the timeout value, thestatement is timed out by the databaseserver, and the driver throws an exceptionindicating that the statement was timed out.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 Aha!, Jira, GitHub, MicrosoftDynamics 365, Oracle Eloqua, Oracle SalesCloud, Oracle Service Cloud, and Salesforceignore any value set using this method. Usethe WSTimeout connection property to seta timeout.




Statement Methods

The drivers for Apache Cassandra andMongoDB driver ignore any value set usingthis method.


StatementEventListener


StatementEventListener Methods

Yes4.0void statementClosed(event)

Yes4.0void statementErrorOccurred(event)

Struct


Struct Methods

Supported for the Oracle driver only. Allother drivers throw "unsupported method"exception.

Yes2.0(all)

XAConnection


XAConnection Methods

Supported for all drivers except Aha!,Amazon Redshift, Apache Hive, ApacheSpark SQL, Autonomous REST Connector,DB2 V8.1 for z/OS, GitHub, Greenplum,Impala, Jira, Microsoft Dynamics 365,Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, PostgreSQL, and Salesforce.

Yes2.0 Optional(all)



XADataSource


XADataSource Methods

Supported for all drivers except Aha!,Amazon Redshift, Apache Hive, ApacheSpark SQL, Autonomous REST Connecter,DB2 V8.1 for z/OS, GitHub, Greenplum,Microsoft Dynamics 365, Impala, OracleEloqua, Oracle Sales Cloud, Oracle ServiceCloud, PostgreSQL, and Salesforce.


XAResource


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




9JDBC 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 the Autonomous RESTConnector and the drivers for Oracle Eloqua, Oracle Sales Cloud, OracleService Cloud, Salesforce, and Google BigQuery to extend the standardJDBC metadata results returned by the DatabaseMetaData.getColumns()method to include an additional column.

DatabaseMetadata

Methods that allow your application to perform bulk load operations.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


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


• 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();}...


Chapter 9: JDBC extensions

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

• Aha!

• Autonomous REST Connector

• GitHub

• Jira

• Microsoft Dynamics 365

• 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 30: DatabaseMetaData.getColumns() method


Provides an indication of whether the column can be used as anExternal ID. External ID columns can be used as the lookup columnfor insert and upsert operations and foreign-key relationship values.Valid values are:

• YES: The column can be used as an external ID.

• NO: The column cannot be used as an external ID.

The standard catalog table SYSTEM_COLUMNS is also extended toinclude the IS_EXTERNAL_ID column.

VARCHAR (3), NOTNULL

IS_EXTERNAL_ID

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

The Autonomous REST Connector and the drivers for Aha!, GitHub, Jira, Microsoft Dynamics 365, OracleEloqua, Oracle Sales Cloud, Oracle Service Cloud, and Salesforce extend the standard JDBC metadata resultsreturned by the DatabaseMetaData.getTables() method to include the following additional column.

Table 31: DatabaseMetaData.getTables() Method


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


DatabaseMetaData interface

DDBulkLoad interfaceDescriptionDDBulkLoad 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. This method also returnsthe number of rows that were successfully exported 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.This methodalso returns the number of rows that were successfully exported fromthe 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. This method also returns the number of rowsthat were successfully exported from the table.

long export(String)

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

long getBatchSize()

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.

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.

long getCharacterThreshold()

Returns the code page that the driver uses for the CSV file.String getCodePage()

Returns the name of the bulk load configuration file.String getConfigFile()

Returns the name of the discard file. The discard file contains rowsthat were unable to be loaded as the result of a bulk load operation.

String getDiscardFile()

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

long getErrorTolerance()



DescriptionDDBulkLoad Methods

Returns the name of the log file. The log file records information abouteach bulk load operation.

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.

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

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.

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.

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)


DDBulkLoad interface


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.

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)

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.

void setBinaryThreshold(long)




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.

void setCharacterThreshold(long)

Specifies the code page the driver uses for the CSV file.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.

void setConfigFile(String)

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.

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.

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 numRows codePage binaryThreshold timeout characterThreshold logFile errorTolerance discardFile warningTolerance configFile readBufferSize startPosition 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.

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




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.

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)




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.

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[])




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.

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.

ExtStatementPoolMonitorgetStatementPoolMonitor()


ExtConnection interface


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)




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.


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:




void setCurrentUser(String, Properties)


ExtConnection interface


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.




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.




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



ExtDatabaseMetaData interfaceThe ExtDatabaseMetaData interface supports the methods described in the following table.

DescriptionExtDatabaseMetaData 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 classThe ExtLogControl class supports the methods described in the following table.

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


ExtDatabaseMetaData interface

10Designing JDBC applications forperformance optimization

Developing performance-oriented JDBC applications is not easy. JDBC drivers do not throw exceptions to tellyou when your code is running too slow. This chapter presents some general guidelines for improving JDBCapplication performance that have been compiled by examining the JDBC implementations of numerousshipping JDBC applications. These guidelines include:

• Use DatabaseMetaData methods appropriately

• Return only required data

• Select functions that optimize performance

• Manage connections and updates

Following these general guidelines can help you solve some common JDBC system performance problems,such as those listed in the following table.

See guidelines in…SolutionProblem

Using database metadata methods onpage 362

Reduce network traffic.Network communication is slow.

Using database metadata methods onpage 362

Selecting JDBC objects and methodson page 366

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


See guidelines in…SolutionProblem

Returning data on page 364

Selecting JDBC objects and methodson page 366

Optimize application-to-driverinteraction.

Excessive calls from the application tothe driver slow performance.

Managing connections and updates onpage 369

Limit disk I/O.Disk I/O is slow.

In addition, most JDBC drivers provide options that improve performance, often with a trade-off in functionality.If your application is not affected by functionality that is modified by setting a particular option, significantperformance improvements can be realized.

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


• Using database metadata methods

• Returning data

• Selecting JDBC objects and methods

• Managing connections and updates

Using database metadata methodsBecause database metadata methods that generate ResultSet objects are slow compared to other JDBCmethods, their frequent use can impair system performance.The guidelines in this section will help you optimizesystem performance when selecting and using database metadata.

Minimizing the use of database metadata methods

Compared to other JDBC methods, database metadata methods that generate ResultSet objects are relativelyslow. Applications should cache information returned from result sets that generate database metadata methodsso that multiple executions are not needed.

Although almost no JDBC application can be written without database metadata methods, you can improvesystem performance by minimizing their use. To return all result column information mandated by the JDBCspecification, a JDBC driver may have to perform complex queries or multiple queries to return the necessaryresult set for a single call to a database metadata method. These particular elements of the SQL language areperformance-expensive.

Applications should cache information from database metadata methods. For example, call getTypeInfo() oncein the application and cache the elements of the result set that your application depends on. It is unlikely thatany application uses all elements of the result set generated by a database metadata method, so the cacheof information should not be difficult to maintain.


Chapter 10: Designing JDBC applications for performance optimization

Avoiding search patterns

Using 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 characteristics

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

ResultSet 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 query PreparedStatement WSps = WSc.prepareStatement ("SELECT * FROM UnknownTable WHERE 1 = 0");// query is never executed on the server - only preparedResultSetMetaData WSsmd=WSps.getMetaData();int numcols = WSrsmd.getColumnCount();...


Using database metadata methods

int ctype = WSrsmd.getColumnType(n)...// result column information has now been obtained// Note we also know the column ordering within the // table! This information cannot be// assumed from the getColumns example.

In both cases, a query is sent to the server. However, in Case 1, the potentially complex query must be preparedand executed, result description information must be formulated, and a result set of rows must be sent to theclient. In Case 2, we prepare a simple query where we only return result set information. Clearly, Case 2 is thebetter performing model.

To somewhat complicate this discussion, let us consider a DBMS server that does not natively support preparinga SQL statement.The performance of Case 1 does not change but the performance of Case 2 improves slightlybecause the dummy query must be evaluated in addition to being prepared. Because the Where clause of thequery always evaluates to FALSE, the query generates no result rows and should execute without accessingtable data. For this situation, Case 2 still outperforms Case 1.

In summary, always use result set metadata to return table column information, such as column names, columndata types, and column precision and scale. Only use the getColumns() method when the requested informationcannot be obtained from result set metadata (for example, using the table column default values).

Returning dataTo return data efficiently, return only the data that you need and choose the most efficient method of doing so.The guidelines in this section will help you optimize system performance when retrieving data with JDBCapplications.

Returning long data

Because retrieving long data across a network is slow and resource intensive, applications should not requestlong data unless it is necessary.

Most users do not want to see long data. If the user does want to see these result items, then the applicationcan query the database again, specifying only the long columns in the Select list. This method allows theaverage user to return the result set without having to pay a high performance penalty for network traffic.

Although the best method is to exclude long data from the Select list, some applications do not formulate theSelect list before sending the query to the JDBC driver (that is, some applications SELECT * FROMtable_name ...). If the Select list contains long data, most drivers are forced to return that long data at fetchtime, even if the application does not ask for the long data in the result set. When possible, the designer shouldattempt to implement a method that does not return all columns of the table.

For example, consider the following code:

ResultSet rs = stmt.executeQuery( "SELECT * FROM Employees WHERE SSID = '999-99-2222'");rs.next();string name = rs.getString(1);



Remember that a JDBC driver cannot interpret an application's final intention. When a query is executed, thedriver has no way to know which result columns an application will use. A driver anticipates that an applicationcan request any of the result columns that are returned. When the JDBC driver processes the rs.next request,it will probably return at least one, if not more, result rows from the database server across the network. In thiscase, a result row contains all the column values for each row, including an employee photograph if theEmployees table contains such a column. If you limit the Select list to contain only the employee name column,it results in decreased network traffic and a faster performing query at runtime. For example:

ResultSet rs = stmt.executeQuery( "SELECT name FROM Employees WHERE SSID = '999-99-2222'");rs.next();string name = rs.getString(1);

Additionally, although the getClob() and getBlob() methods allow the application to control how long data isreturned in the application, the designer must realize that in many cases, the JDBC driver emulates thesemethods due to the lack of true Large Object (LOB) locator support in the DBMS. In such cases, the drivermust return all the long data across the network before exposing the getClob() and getBlob() methods.

Reducing the size of returned data

Sometimes 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 type

Retrieving 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 sets

Most JDBC drivers cannot implement scrollable cursors because of limited support for scrollable cursors in thedatabase system. Unless you are certain that the database supports using a scrollable result set, rs, for example,do not call rs.last and rs.getRow() methods to find out how many rows the result set contains. For JDBC driversthat emulate scrollable cursors, calling rs.last results in the driver retrieving all results across the network toreach the last row. Instead, you can either count the rows by iterating through the result set or get the numberof rows by submitting a query with a Count column in the Select clause.

In general, do not write code that relies on the number of result rows from a query because drivers must fetchall rows in a result set to know how many rows the query will return.


Returning data

Selecting JDBC objects and methodsThe guidelines in this section will help you to select which JDBC objects and methods will give you the bestperformance.

Using parameter markers as arguments to stored procedures

When 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 object

JDBC drivers are optimized based on the perceived use of the functions that are being executed. Choosebetween the PreparedStatement object and the Statement object depending on how you plan to use the object.The Statement object is optimized for a single execution of a SQL statement. In contrast, the PreparedStatementobject is optimized for SQL statements to be executed two or more times.



The overhead for the initial execution of a PreparedStatement object is high. The advantage comes withsubsequent executions of the SQL statement. For example, suppose we are preparing and executing a querythat returns employee information based on an ID. Using a PreparedStatement object, a JDBC driver wouldprocess the prepare request by making a network request to the database server to parse and optimize thequery.The execute results in another network request. If the application will only make this request once duringits life span, using a Statement object instead of a PreparedStatement object results in only a single networkroundtrip to the database server. Reducing network communication typically provides the most performancegains.

This guideline is complicated by the use of prepared statement pooling because the scope of execution islonger. When using prepared statement pooling, if a query will only be executed once, use the Statementobject. If a query will be executed infrequently, but may be executed again during the life of a statement poolinside a connection pool, use a PreparedStatement object. Under similar circumstances without statementpooling, use the Statement object.

Using batches instead of prepared statements

Updating 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 Times

PreparedStatement 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 Batch

PreparedStatement ps = conn.prepareStatement( "INSERT INTO employees VALUES (?, ?, ?)");for (n = 0; n < 100; n++) { ps.setString(name[n]); ps.setLong(id[n]); ps.setInt(salary[n]); ps.addBatch();}ps.executeBatch();

In Case 1, a prepared statement is used to execute an Insert statement multiple times. In this case, 101 networkroundtrips are required to perform 100 Insert operations: one roundtrip to prepare the statement and 100additional roundtrips to execute its iterations. When the addBatch method is used to consolidate 100 Insertoperations, as demonstrated in Case 2, only two network roundtrips are required—one to prepare the statementand another to execute the batch. Although more database CPU cycles are involved by using batches,performance is gained through the reduction of network roundtrips. Remember that the biggest gain inperformance is realized by reducing network communication between the JDBC driver and the database server.


Selecting JDBC objects and methods

Choosing the right cursor

Choosing 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 effectively

JDBC provides a variety of methods to return data from a result set (for example, getInt(), getString(), andgetObject()). The getObject() method is the most generic and provides the worst performance when thenon-default mappings are specified because the JDBC driver must perform extra processing to determine thetype of the value being returned and generate the appropriate mapping. Always use the specific method forthe data type.

To further improve performance, provide the column number of the column being returned, for example,getString(1), getLong(2), and getInt(3), instead of the column name. If the column names are notspecified, network traffic is unaffected, but costly conversions and lookups increase. For example, supposeyou use:

getString("foo")...

The JDBC driver may need to convert foo to uppercase and then compare foo with all columns in the columnlist, which is costly. If the driver is able to go directly to result column 23, a large amount of processing is saved.



For example, suppose you have a result set that has 15 columns and 100 rows, and the column names arenot included in the result set.You are interested in only three columns: EMPLOYEENAME (string),EMPLOYEENUMBER (long integer), and SALARY (integer). If you specify getString("EmployeeName"),getLong("EmployeeNumber"), and getInt("Salary"), each column name must be converted to theappropriate case of the columns in the database metadata and lookups would increase considerably.Performance improves significantly if you specify getString(1), getLong(2), and getInt(15).

Retrieving auto-generated keys

Many 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 LocalGeniusList WHERE name = 'Karen'");

Retrieving pseudo-columns this way has two major flaws. First, retrieving the pseudo-column requires a separatequery to be sent over the network and executed on the server. Second, because there may not be a primarykey over the table, the search condition of the query may be unable to uniquely identify the row. In the lattercase, multiple pseudo-column values can be returned, and the application may not be able to determine whichvalue is actually the value for the most recently inserted row.

An optional feature of the JDBC 3.0 specification is the ability to return auto-generated key information for arow when the row is inserted into a table. For example:

int rowcount = stmt.executeUpdate( "INSERT INTO LocalGeniusList(name) VALUES('Karen')",// insert row AND return keyStatement.RETURN_GENERATED_KEYS);ResultSet rs = stmt.getGeneratedKeys();// key is automatically available

Now, the application contains a value that can be used in a search condition to provide the fastest access tothe row and a value that uniquely identifies the row, even when a primary key doesn't exist on the table.

The ability to return keys provides flexibility to the JDBC developer and creates performance boosts whenaccessing data.

Managing connections and updatesThe guidelines in this section will help you to manage connections and updates to improve system performancefor your JDBC applications.


Managing connections and updates

Managing connections

Connection 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 itin one step rather than two steps. For example, some applications establish a connection and then call amethod in a separate component that reattaches and gathers information about the driver. Applications thatare designed as separate entities should pass the established connection object to the data collection routineinstead of establishing 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 transactions

Committing transactions is slow because of the amount of disk I/O and potentially network round trips that arerequired. Always turn off Autocommit by using Connection.setAutoCommit(false).



What does a commit actually involve? The database server must flush back to disk every data page thatcontains updated or new data. This is usually a sequential write to a journal file, but nevertheless, it involvesdisk I/O. By default, Autocommit is on when connecting to a data source, and Autocommit mode usually impairsperformance because of the significant amount of disk I/O needed to commit every operation.

Furthermore, most database servers do not provide a native Autocommit mode. For this type of server, theJDBC driver must explicitly issue a COMMIT statement and a BEGIN TRANSACTION for every operation sentto the server. In addition to the large amount of disk I/O required to support Autocommit mode, a performancepenalty is paid for up to three network requests for every statement issued by an application.

Although using transactions can help application performance, do not take this tip too far. Leaving transactionsactive can reduce throughput by holding locks on rows for longer than necessary, preventing other users fromaccessing the rows. Commit transactions in intervals that allow maximum concurrency.

Choosing the right transaction model

Many 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 methods

Although 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 getBestRowIdentifier

Use getBestRowIdentifier() to determine the optimal set of columns to use in the Where clause for updatingdata. Pseudo-columns often provide the fastest access to the data, and these columns can only be determinedby using getBestRowIdentifier().


Managing connections and updates

Some applications cannot be designed to take advantage of positioned updates and deletes. Some applicationsformulate the Where clause by calling getPrimaryKeys() to use all searchable result columns or by callinggetIndexInfo() to find columns that may be part of a unique index. These methods usually work, but can resultin fairly complex queries.

Consider the following example:

ResultSet WSrs = WSs.executeQuery ("SELECT first_name, last_name, ssn, address, city, state, zip FROM emp");// fetchdata...WSs.executeQuery ( "UPDATE emp SET address = ? WHERE first_name = ? AND last_name = ? AND ssn = ? AND address = ? AND city = ? AND state = ? AND zip = ?");// fairly complex query

Applications should call getBestRowIdentifier() to return the optimal set of columns (possibly a pseudo-column)that identifies a specific record. Many databases support special columns that are not explicitly defined by theuser in the table definition, but are "hidden" columns of every table (for example, ROWID and TID). Thesepseudo-columns generally provide the fastest access to the data because they typically are pointers to theexact location of the record. Because pseudo-columns are not part of the explicit table definition, they are notreturned from getColumns(). To determine if pseudo-columns exist, call getBestRowIdentifier().

Consider the previous example again:

...ResultSet WSrowid = getBestRowIdentifier() (... "emp", ...);...WSs.executeUpdate("UPDATE EMP SET ADDRESS = ? WHERE ROWID = ?");// fastest access to the data!

If your data source does not contain special pseudo-columns, the result set of getBestRowIdentifier() consistsof the columns of the most optimal unique index on the specified table (if a unique index exists). Therefore,your application does not need to call getIndexInfo() to find the smallest unique index.



progress® datadirect® for jdbc™ for …jdbc for salesforce driver the progress® datadirect®...

Documents