user's guide and reference - progress.com...2020/06/08 · data source name.....151...

Progress DataDirect®

for ODBCfor Salesforce™ DriverUser's Guide and Reference

Release 8.0.0

Copyright

© 2020 Progress Software Corporation and/or one of its subsidiaries or affiliates. Allrights reserved.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/06/08

3The Progress DataDirect® for ODBC for Salesforce Driver: User's Guide and Reference: Version 8.0.0

The Progress DataDirect® for ODBC for Salesforce Driver: User's Guide and Reference: Version 8.0.04

Copyright

Table of Contents

Welcome to the Progress DataDirect for ODBC for Salesforce™

Driver...13What's New in this Release?................................................................................................................14

Driver Requirements.............................................................................................................................17

ODBC Compliance...............................................................................................................................17

Version String Information....................................................................................................................18

getFileVersionString Function....................................................................................................19

Support for Multiple Environments.......................................................................................................19

Support for Windows Environments...........................................................................................20

Support for UNIX and Linux Environments................................................................................22

Mapping Objects to Tables...................................................................................................................27

Data Types............................................................................................................................................28

Contacting Technical Support...............................................................................................................30

Getting Started.............................................................................................31Configuring and Connecting on Windows.............................................................................................32

Setting the Library Path Environment Variable (Windows)........................................................32

Configuring a Data Source........................................................................................................32

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

Configuring and Connecting on UNIX and Linux..................................................................................33

Environment Configuration........................................................................................................34

Test Loading the Driver..............................................................................................................34

Setting the Library Path Environment Variable (UNIX and Linux)..............................................35

Configuring a Data Source........................................................................................................35

Testing the Connection..............................................................................................................36

Accessing Data With Third-Party Applications......................................................................................36

Using the Driver...........................................................................................37Configuring and Connecting to Data Sources......................................................................................38

Configuring the Product on UNIX/Linux.....................................................................................38

Configuring the Product Using the GUI.....................................................................................47

Using a Connection String.........................................................................................................69

Using a Logon Dialog Box.........................................................................................................70

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

Performance Considerations................................................................................................................71

Using the SQL Engine Server..............................................................................................................73

Configuring the SQL Engine Server on Windows......................................................................73

Configuring the SQL Engine Server on UNIX/Linux..................................................................76

Configuring Java Logging for the SQL Engine Server...............................................................78


Contents

Using Client-Side Caches.....................................................................................................................78

Creating a Cache.......................................................................................................................79

Modifying a Cache Definition.....................................................................................................79

Disabling and Enabling a Cache................................................................................................80

Refreshing Cache Data.............................................................................................................80

Dropping a Cache......................................................................................................................81

Cache MetaData........................................................................................................................81

Catalog Tables......................................................................................................................................81

SYSTEM_CACHES Catalog Table............................................................................................81

SYSTEM_CACHE_REFERENCES Catalog Table....................................................................83

SYSTEM_REMOTE_SESSIONS Catalog Table........................................................................84

SYSTEM_SESSIONINFO Catalog Table...................................................................................85

SYSTEM_SESSIONS Catalog Table.........................................................................................86

Using Reports.......................................................................................................................................88

Using Security......................................................................................................................................88

Authentication............................................................................................................................88

Data Encryption Across the Network.........................................................................................90

SSL Encryption..........................................................................................................................90

Summary of Security-Related Options......................................................................................92

Using DataDirect Connection Pooling..................................................................................................92

Creating a Connection Pool.......................................................................................................93

Adding Connections to a Pool....................................................................................................93

Removing Connections from a Pool..........................................................................................93

Handling Dead Connections in a Pool.......................................................................................94

Connection Pool Statistics.........................................................................................................95

Configuring Pooling-Related Options.........................................................................................95

Using Identifiers....................................................................................................................................96

Using IP Addresses..............................................................................................................................96

Timeouts...............................................................................................................................................97

Views and Remote/Local Tables...........................................................................................................97

SQL Support.........................................................................................................................................98

Isolation and Lock Levels Supported....................................................................................................98

Number of Connections and Statements Supported............................................................................98

Unicode Support...................................................................................................................................98

Parameter Metadata Support...............................................................................................................99

Insert and Update Statements...................................................................................................99

Select Statements......................................................................................................................99

Using DataDirect Bulk Load...............................................................................................................100

Bulk Export and Load Methods...............................................................................................101

Exporting Data from a Database.............................................................................................101

Bulk Loading to a Database.....................................................................................................103

The Bulk Load Configuration File............................................................................................104

Sample Applications................................................................................................................106

Character Set Conversions......................................................................................................106

External Overflow Files............................................................................................................107


Contents

Summary of DataDirect Bulk Load Related Options................................................................107

Using Bulk API with SQL Statements ................................................................................................109

Summary of Options for Using Bulk API with SQL Statements ..............................................110

Troubleshooting.........................................................................................113Diagnostic Tools..................................................................................................................................113

ODBC Trace.............................................................................................................................113

The Test Loading Tool..............................................................................................................116

ODBC Test...............................................................................................................................117

Logging....................................................................................................................................117

Configuring Logging.................................................................................................................119

The Example Application.........................................................................................................120

Other Tools...............................................................................................................................121

Error Messages..................................................................................................................................121

Troubleshooting..................................................................................................................................122

Setup/Connection Issues.........................................................................................................122

Interoperability Issues..............................................................................................................124

Performance Issues.................................................................................................................125

Connection Option Descriptions..............................................................127Access Token......................................................................................................................................133

Application Using Threads..................................................................................................................134

Authentication Method........................................................................................................................134

Bulk Fetch Threshold..........................................................................................................................135

Bulk Load Asynchronous....................................................................................................................136

Bulk Load Batch Size.........................................................................................................................137

Bulk Load Concurrency Mode............................................................................................................137

Bulk Load Poll Interval........................................................................................................................138

Bulk Load Threshold...........................................................................................................................139

Bulk Load Timeout..............................................................................................................................140

Client ID..............................................................................................................................................140

Client Secret.......................................................................................................................................141

Config Options....................................................................................................................................142

AuditColumns (Config Option).................................................................................................143

CustomSuffix (Config Option)..................................................................................................144

KeywordConflictSuffix (Config Option).....................................................................................144

MapSystemColumnNames (Config Option).............................................................................145

NumberFieldMapping (Config Option).....................................................................................146

UppercaseIdentifiers (Config Option)......................................................................................147

Connection Pooling.............................................................................................................................148

Connection Reset...............................................................................................................................149

Create Database................................................................................................................................149

Create Map.........................................................................................................................................150


Contents

Data Source Name.............................................................................................................................151

Database............................................................................................................................................151

Description..........................................................................................................................................152

Enable Bulk Fetch...............................................................................................................................153

Enable Bulk Load...............................................................................................................................154

Enable Primary Key Chunking............................................................................................................155

Fetch Size...........................................................................................................................................155

Field Delimiter.....................................................................................................................................156

Host Name..........................................................................................................................................157

IANAAppCodePage............................................................................................................................158

Initialization String..............................................................................................................................159

JVM Arguments..................................................................................................................................160

JVM Classpath...................................................................................................................................161

LoadBalance Timeout.........................................................................................................................162

Log Config File...................................................................................................................................162

Login Timeout.....................................................................................................................................163

Logon Domain....................................................................................................................................164

Max Pool Size.....................................................................................................................................164

Min Pool Size......................................................................................................................................165

Password............................................................................................................................................166

Primary Key Chunk Size.....................................................................................................................167

Proxy Host..........................................................................................................................................168

Proxy Password..................................................................................................................................168

Proxy Port...........................................................................................................................................169

Proxy User..........................................................................................................................................169

Read Only...........................................................................................................................................170

Record Delimiter.................................................................................................................................171

Refresh Dirty Cache...........................................................................................................................171

Refresh Schema.................................................................................................................................172

Refresh Token.....................................................................................................................................173

Report Codepage Conversion Errors.................................................................................................174

Schema Map......................................................................................................................................175

Security Token....................................................................................................................................176

Server Port Number............................................................................................................................177

SQL Engine Mode..............................................................................................................................178

Statement Call Limit...........................................................................................................................179

Statement Call Limit Behavior............................................................................................................179

Transaction Mode...............................................................................................................................180

User Name.........................................................................................................................................181

WSFetch Size.....................................................................................................................................181

WSPoolSize........................................................................................................................................182

WSRetry Count..................................................................................................................................183

WSTimeout.........................................................................................................................................184


Contents

Supported SQL Statements and Extensions...........................................185Alter Cache (EXT)..............................................................................................................................186

Relational Caches....................................................................................................................188

Alter Index...........................................................................................................................................188

Alter Sequence...................................................................................................................................188

Alter Session (EXT)............................................................................................................................189

Alter Table...........................................................................................................................................190

Altering a Remote Table...........................................................................................................190

Altering a Local Table...............................................................................................................193

Create Cache (EXT)...........................................................................................................................196

Relational Caches....................................................................................................................198

Referencing Clause.................................................................................................................198

Refresh Interval Clause...........................................................................................................199

Initial Check Clause.................................................................................................................199

Persist Clause..........................................................................................................................200

Enabled Clause.......................................................................................................................200

Call Limit Clause......................................................................................................................201

Filter Clause.............................................................................................................................202

Create Index.......................................................................................................................................203

Create Sequence................................................................................................................................203

Next Value For Clause.............................................................................................................204

Create Table.......................................................................................................................................204

Creating a Remote Table.........................................................................................................205

Creating a Local Table.............................................................................................................209

Create View........................................................................................................................................216

Delete.................................................................................................................................................217

Drop Cache (EXT)..............................................................................................................................218

Drop Index..........................................................................................................................................219

Drop Sequence...................................................................................................................................219

Drop Table..........................................................................................................................................220

Drop View...........................................................................................................................................220

Explain Plan........................................................................................................................................221

Insert..................................................................................................................................................221

Specifying an External ID Column...........................................................................................222

Refresh Cache (EXT).........................................................................................................................223

Refresh Map (EXT).............................................................................................................................224

Select..................................................................................................................................................224

Select Clause...........................................................................................................................226

Update................................................................................................................................................235

SQL Expressions................................................................................................................................236

Column Names........................................................................................................................237

Literals.....................................................................................................................................237

Operators.................................................................................................................................239


Contents

Functions.................................................................................................................................243

Conditions................................................................................................................................243

Subqueries.........................................................................................................................................244

IN Predicate.............................................................................................................................244

EXISTS Predicate....................................................................................................................245

UNIQUE Predicate...................................................................................................................245

Correlated Subqueries.............................................................................................................245

Part I: Reference.........................................................................................247

What Is ODBC?...................................................................................249How Does It Work?..................................................................................................................250

Why Do Application Developers Need ODBC?........................................................................250

Code Page Values...............................................................................251IANAAppCodePage Values......................................................................................................251

ODBC API and Scalar Functions......................................................257API Functions..........................................................................................................................257

Scalar Functions......................................................................................................................259

String Functions............................................................................................................261

Numeric Functions........................................................................................................263

Date and Time Functions..............................................................................................264

System Functions.........................................................................................................266

Internationalization, Localization, and Unicode..............................267Internationalization and Localization........................................................................................267

Locale...........................................................................................................................268

Language......................................................................................................................268

Country.........................................................................................................................268

Variant...........................................................................................................................269

Unicode Character Encoding...................................................................................................269

Background...................................................................................................................269

Unicode Support in Databases.....................................................................................270

Unicode Support in ODBC............................................................................................270

Unicode and Non-Unicode ODBC Drivers...............................................................................271

Function Calls...............................................................................................................271

Data..............................................................................................................................273

Default Unicode Mapping..............................................................................................274

Driver Manager and Unicode Encoding on UNIX/Linux...........................................................274

References....................................................................................................................275


Contents

Character Encoding in the odbc.ini and odbcinst.ini Files.......................................................276

Designing ODBC Applications for Performance Optimization......277Using Catalog Functions..........................................................................................................278

Caching Information to Minimize the Use of Catalog Functions...................................278

Avoiding Search Patterns..............................................................................................279

Using a Dummy Query to Determine Table Characteristics..........................................279

Retrieving Data........................................................................................................................280

Retrieving Long Data....................................................................................................280

Reducing the Size of Data Retrieved............................................................................280

Using Bound Columns..................................................................................................281

Using SQLExtendedFetch Instead of SQLFetch...........................................................281

Choosing the Right Data Type......................................................................................282

Selecting ODBC Functions......................................................................................................282

Using SQLPrepare/SQLExecute and SQLExecDirect..................................................282

Using Arrays of Parameters..........................................................................................282

Using the Cursor Library...............................................................................................283

Managing Connections and Updates.......................................................................................284

Managing Connections.................................................................................................284

Managing Commits in Transactions..............................................................................284

Choosing the Right Transaction Model.........................................................................285

Using Positioned Updates and Deletes.........................................................................285

Using SQLSpecialColumns...........................................................................................285

Using Indexes.....................................................................................287Introduction..............................................................................................................................287

Improving Row Selection Performance....................................................................................288

Indexing Multiple Fields...........................................................................................................288

Deciding Which Indexes to Create...........................................................................................289

Improving Join Performance....................................................................................................290

Locking and Isolation Levels............................................................291Locking....................................................................................................................................291

Isolation Levels........................................................................................................................292

Locking Modes and Levels......................................................................................................293

WorkAround Options.........................................................................295

Threading............................................................................................299


Contents

DataDirect Bulk Load.........................................................................301DataDirect Bulk Load Functions..............................................................................................301

Utility Functions.......................................................................................................................302

GetBulkDiagRec and GetBulkDiagRecW.....................................................................302

Export, Validate, and Load Functions......................................................................................304

ExportTableToFile and ExportTableToFileW.................................................................304

LoadTableFromFile and LoadTableFromFileW..............................................................307

Using the TableName Parameter with the Salesforce Driver........................................309

SetBulkOperation..........................................................................................................311

GetBulkOperation ........................................................................................................312

DataDirect Bulk Load Statement Attributes.............................................................................314

SQL_BULK_EXPORT_PARAMS..................................................................................314

SQL_BULK_EXPORT...................................................................................................315

Glossary.......................................................................................................317

Index............................................................................................................321


Contents

1Welcome to the Progress DataDirect forODBC for Salesforce™ Driver

The Progress DataDirect for ODBC Salesforce driver supports the standard SQL query language to fetch, insert,update, and delete data from Salesforce.com, Force.com, and Database.com. To support SQL access toSalesforce, the driver creates a map of the Salesforce data model and translates SQL statements provided bythe application to Salesforce 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 using the SQLForeignKeys and SQLPrimaryKeys functions.

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.

Note: For the Salesforce Web Service API versions supported by the Salesforce driver, refer to the SupportedConfigurations page on the Progress DataDirect Web site.You can also query theSYSTEM_REMOTE_SESSIONS system table to get the version of the Web Service API the driver supports.

For details, see the following topics:

• What's New in this Release?

• Driver Requirements

• ODBC Compliance

• Version String Information


https://www.progress.com/support/evaluation/supported-configurations

https://www.progress.com/support/evaluation/supported-configurations

• Support for Multiple Environments

• Mapping Objects to Tables

• Data Types

• Contacting Technical Support

What's New in this Release?

Changes Since 8.0.0

• Driver Enhancements

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

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

• Changed Behavior

• 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 Driver Requirements on page 17 formore details on 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 configuration options have been deprecated. However, the driver will continue to support them untilthe next major release of the driver.

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

• The following Windows platforms have reached the end of their product lifecycle and are no longersupported by the driver:

• Windows 8.0 (versions 8.1 and higher are still supported)

• Windows Vista (all versions)

• Windows XP (all versions)

• Windows Server 2003 (all versions)

Changes For 8.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 Enable Bulk Fetch, Bulk FetchThreshold, Enable Primary Key Chunking, and PK Chunk Size connection options. See Summary ofOptions for Using Bulk API with SQL Statements on page 110 for details.


Chapter 1: Welcome to the Progress DataDirect for ODBC for Salesforce™ Driver

• The driver has been enhanced to support multiple simultaneous sessions.This allows the driver to scaleperformance by distributing the workload across multiple sessions.The number of active sessions shouldnot exceed the number permitted by your Salesforce account and can be limited by the setting of thenew WSPoolSize connection option. See WSPoolSize on page 182 for details.

• The following Refresh Map SQL extension has been added to the driver. REFRESH MAP discoversnative objects that have been added to the native data store since connection or since the last refreshand maps the objects into your relational view of native data. It also incorporates any configurationchanges made to your relational view by reloading the schema map and associated files. See RefreshMap (EXT) on page 224 for details.

• The SQL Engine Mode connection option now supports Auto mode. When this setting is enabled, thedriver automatically determines whether the SQL engine runs in server or direct mode based on availability.In addition, the default value for the SQL Engine Mode connection option on Windows has been updatedto 0 (Auto). See SQL Engine Mode on page 178 for details.

• The driver is now compiled using Visual Studio 2015 for improved security.

• The driver includes a new Tableau data source file (Windows only) that provides improved functionalitywhen accessing your Salesforce data with Tableau. Refer to Windows quick start for details.

• The driver and Driver Manager have been enhanced to support UTF-8 encoding in the odbc.ini andodbcinst.ini files. See Character Encoding in the odbc.ini and odbcinst.ini Files on page 276 fordetails.

• Changed Behavior

• Support for HP-UX PA-RISC 32-bit, Oracle Solaris SPARC 32-bit, and Oracle Solaris x86 32-bit platformshas been depricated.

• Support for Windows XP and Windows Server 2003 has been deprecated.

• The Salesforce driver has been updated to require a JVM that is version Java SE 7 or higher. Thischange has been implemented to remain compliant with Salesforce security standards. See DriverRequirements on page 17 for more details on JVM.

• In addition to the information listed here, refer to the compatability FAQ for guidance on upgrading fromthe Progress DataDirect for ODBC for Salesforce 7.1 driver to the 8.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 185.

• The 8.0 driver pushes queries to Salesforce whenever possible. Queries that cannot be pushed toSalesforce with the 8.0 driver may be slower than comparable queries made with earlier versions of thedriver 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 28 details.

• The Database connection option has been replaced by the new Schema Map option. Similar to Database,Schema Map is used to specify the name and location of the configuration file where the relational mapof native data is written; however, there are changes to the file name format and default behavior. TheDatabase attribute will continue to be supported for this release, but it will be deprecated in subsequentversions of the product. See Schema Map on page 175 for details.

• The Create Database connection option has been replaced by the new Create Map option.The CreateDBattribute will continue to be supported for this release, but it will be deprecated in subsequent versionsof the product. See Create Map on page 150 for details.


What's New in this Release?

https://documentation.progress.com/output/DataDirect/odbcquickstarts/salesforceodbc_win_quickstart/index.html

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

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

https://www.progress.com/support

• The Logon Domain connection option has been deprecated. As a result, the User Name option has beenupdated to accept the user name and domain. See User Name on page 181 for details.

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

• The Server DB Directory connection option has been deprecated. To specify the location of databasefiles, use the Schema Map connection option. See Schema Map on page 175 for details.

• The default value for the Server Port Number connection option has been updated:

• For the 32-bit driver, the default is 19938.

• For the 64-bit driver, the default is 19937.

• The default value for the JVM Arguments connection option has been updated:

• For the 32-bit driver when the SQL Engine Mode connection option is set to 2 (Direct):

-Xmx256m

• For all other configurations:

-Xmx1024m

• The default value of the Enable Bulk Load connection option has been updated to 1 (enabled). By default,the bulk load protocol is used for inserts, updates, and deletes when the size of the operation exceedsthe threshold determined by the Bulk Load Threshold option. See Enable Bulk Load on page 154 fordetails.

• The default value for the Statement Call Limit connection option has been updated to 100. By default,the driver can make a maximum of 100 Web service calls when executing any single SQL statement ormetadata query. See Statement Call Limit on page 179 for details.

• The default value for the AuditColumns config option has been updated to All (AuditColumns=All).By default, the driver includes the all of the audit columns and the master record id column in its tabledefinitions. See AuditColumns (Config Option) on page 143 for details.

• The default value for the CustomSuffix config option has been updated to Include(CustomSuffix=Include). By default, the driver includes the "__c" suffix table and column nameswhen mapping the remote data model to the relational data model. See CustomSuffix (Config Option)on page 144 for details.

• The default value for the MapSystemColumnNames config option has been updated to 0(MapSystemColumnNames=0). By default, the driver does not change the names of the Salesforcesystem columns when mapping them to the relational model. See MapSystemColumnNames (ConfigOption) on page 145 for details.

• The short attribute name for the Config Options connection option has changed from CO to CFGO. SeeConfig Options on page 142 for details.

• The Security tab has been removed from the setup dialog. As a result:

• The Security Token connection option has been moved to the General tab.

• The User Name connection option has been moved to the General tab.



Driver RequirementsThe 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.

ODBC ComplianceThe Progress DataDirect for ODBC for Salesforce driver is compliant with the Open Database Connectivity(ODBC) specification. See "ODBC API and Scalar Functions" for a list of the Core and Level 1 functionssupported by the driver for the Salesforce.com Web Services API.

The Salesforce driver extends the standard results returned by the SQLColumns ODBC function to include theIS_EXTERNAL_ID column, as shown in the following table.

Table 1: Extended Functionality for the SQLColumns Function

DescriptionData TypeColumn

Provides an indication of whether the column can be usedas an External ID. External ID columns can be used as thelookup column for insert and upsert operations andforeign-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 alsoextended to include the IS_EXTERNAL_ID column.

VARCHAR (3), NOTNULL

IS_EXTERNAL_ID

The Salesforce driver supports only the following Level 2 functions:

• SQLColumnPrivileges

• SQLDescribeParam

• SQLForeignKeys

• SQLPrimaryKeys

• SQLProcedures

• SQLTablePrivileges

See alsoODBC API and Scalar Functions on page 257


Driver Requirements

Version String InformationThe driver for Salesforce has a version string of the format:

XX.YY.ZZZZ(BAAAA, UBBBB, JDDDDDD)

The Driver Manager on UNIX and Linux has a version string of the format:

XX.YY.ZZZZ(UBBBB)

The component for the Unicode conversion tables (ICU) has a version string of the format:

XX.YY.ZZZZ

where:

XX is the major version of the product.

YY is the minor version of the product.

ZZZZ is the build number of the driver or ICU component.

AAAA is the build number of the driver's bas component.

BBBB is the build number of the driver's utl component.

DDDDDD is the version of the Java components used by the driver.

For example:

08.00.0017 (B0254, U0180, J000109) |__| |___| |___| |____| Driver Bas Utl Java

On Windows, you can check the version string through the properties of the driver DLL. Right-click thedriver DLL and select Properties. The Properties dialog box appears. On the Details tab, the File Version willbe listed with the other file properties.

You can always check the version string of a driver on Windows by looking at the About tab of the driver’sSetup dialog.

On UNIX and Linux, you can check the version string by using the test loading tool shipped withthe product. This tool, ivtestlib for 32-bit drivers and ddtestlib for 64-bit drivers, is located ininstall_directory/bin.

The syntax for the tool is:

ivtestlib shared_object

or

ddtestlib shared_object

For example, for the 32-bit driver on Linux:

ivtestlib ivsfrc28.so



returns:

08.00.0001 (B0002, U0001, J000003)

For example, for the Driver Manager on Linux:

ivtestlib libodbc.so

returns:

08.00.0001 (U0001)

For example, for the 64-bit Driver Manager on Linux:

ddtestlib libodbc.so

returns:

08.00.0001 (U0001)

For example, for the 32-bit ICU component on Linux:

ivtestlib libivicu28.so08.00.0001

Note: On AIX, Linux, and Solaris, the full path to the driver does not have to be specified for the test loadingtool. The HP-UX version of the tool, however, requires the full path.

getFileVersionString Function

Version string information can also be obtained programmatically through the function getFileVersionString.This function can be used when the application is not directly calling ODBC functions.

This function is defined as follows and is located in the driver's shared object:

const unsigned char* getFileVersionString();

This function is prototyped in the qesqlext.h file shipped with the product.

Support for Multiple EnvironmentsYour Progress DataDirect driver is ODBC-compliant for Windows, UNIX, and Linux operating systems. Thissection explains the environment-specific differences when using the database drivers in your operatingenvironment.

The sections "Support for Windows Environments" and "Support for UNIX and Linux Environments" containinformation specific to your operating environment.

The following sections refer to threading models. See "Threading" for an explanation of threading.

Note: Support for operating environments and database versions are continually being added. For the latestinformation about supported platforms and databases, refer to the Progress DataDirect certification matricespage at https://www.progress.com/matrices/datadirect.


Support for Multiple Environments

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

See alsoSupport for Windows Environments on page 20Support for UNIX and Linux Environments on page 22Threading on page 299

Support for Windows Environments

The following are requirements for the 32- and 64-bit drivers on Windows operating systems.

32-Bit Driver

• All required network software that is supplied by your database system vendors must be 32-bit compliant.

• If your application was built with 32-bit system libraries, you must use 32-bit driver. If your application wasbuilt with 64-bit system libraries, you must use 64-bit driver (see "64-bit Driver").The database to which youare connecting can be either 32-bit or 64-bit enabled.

• The following processors are supported:

• x86: Intel

• x64: Intel and AMD

• The following operating systems are supported for your Progress DataDirect for ODBC driver. All editions aresupported unless otherwise noted.

• Windows Server 2016

• Windows 10

• Windows 8.1


• Windows 7


• A 32-bit Java Virtual Machine (JVM), Java SE 8 or higher, is required. Also, you must set the PATHenvironment variable to the directory containing your 32-bit JVM’s jvm.dll file, and that directory’s parentdirectory. See "Driver Requirements" for more details on JVM.

• An application that is compatible with components that were built using Microsoft Visual Studio 2015 compilerand the standard Win32 threading model.

• You must have ODBC header files to compile your application. For example, Microsoft Visual Studio includesthese files.

See also64-Bit Driver on page 21Driver Requirements on page 17



64-Bit Driver



• Intel

• AMD

• The following operating systems are supported for your 64-bit driver. All editions are supported unlessotherwise noted.


• Windows 10

• Windows 8.1


• Windows 7


• An application that is compatible with components that were built using Microsoft C/C++ Optimizing CompilerVersion 14.00.40310.41 and the standard Windows 64 threading model.

• A 64-bit JVM, Java SE 8 or higher, is required. Also, you must set the PATH environment variable to thedirectory containing your 64-bit JVM’s jvm.dll file, and that directory’s parent directory. See "DriverRequirements" for more details on JVM.

• You must have ODBC header files to compile your application. For example, Microsoft Visual Studio includesthese files.

See alsoDriver Requirements on page 17

Setup of the DriverThe driver must be configured before it can be used. See "Getting Started" for information about using theWindows ODBC Administrator. See "Configuring and Connecting to Data Sources" for details about driverconfiguration.

See alsoGetting Started on page 31Configuring and Connecting to Data Sources on page 38

Driver File Names for WindowsThe prefix for all 32-bit driver file names is iv. The prefix for all 64-bit driver file names is dd. The file extensionis .dll, which indicates dynamic link libraries. For example, the 32-bit Salesforce driver file name isivsfrcnn.dll, where nn is the revision number of the driver.

For the 8.0 version of the 32-bit driver, the file name is:



ivsfrc28.dll


ddsfrc28.dll

Refer to the readme file shipped with the product for a complete list of installed files.

Support for UNIX and Linux Environments

The following are requirements for the 32- and 64-bit drivers on UNIX/Linux operating systems.

32-Bit Driver


• If your application was built with 32-bit system libraries, you must use 32-bit drivers. If your application wasbuilt with 64-bit system libraries, you must use 64-bit drivers (see "64-Bit Driver Requirements"). Thedatabase to which you are connecting can be either 32-bit or 64-bit enabled.

• For the Salesforce driver: A 32-bit Java Virtual Machine (JVM), Java SE 8 or higher, is required. Also, youmust set the library path environment variable of your operating system to the directory containing yourJVM’s libjvm.so [a] file and that directory’s parent directory.

The library path environment variable is:

• LD_LIBRARY_PATH on Oracle Solaris, Linux, and HP-UX Itanium

• LIBPATH on AIX

See "Driver Requirements" for more details on JVM.

AIX

• IBM POWER processor

• AIX 5L operating system, version 5.3 fixpack 5 and higher, 6.1, and 7.1

• An application compatible with components that were built using Visual Age C++ 6.0.0.0 and the AIX nativethreading model

• IBM SDK, JAVA Technology Edition, Version 6 Service Refresh 9 or higher

• Before you can use the driver, you must set the LIBPATH environment variable to include the paths containingthe libjvm.so library and the libnio.so library, which are installed in a subdirectory of your JavaDevelopment Kit (JDK). For example, you would add the following paths for Java 8 installed in the /usrdirectory:

/usr/java8/jre/lib/amd64/server:/usr/java8/jre/lib/amd64

In this example, /usr/java8/jre/lib/amd64/server is the location of libjvm.so, while/usr/java8/jre/lib/amd64 is the location of libnio.so.

Note: The driver is compiled using the –brtl loader option.Your application must support runtime linkingfunctionality.



HP-UX

• Intel Itanium II (IPF) processor is supported.

• HP-UX IPF 11i Versions 2 and 3 (B.11.23 and B.11.3x) are supported.

• An application compatible with components that were built using HP aC++ 5.36 and the HP-UX 11 native(kernel) threading model (posix draft 10 threads).

Note:

• Do not link with the –lc linker option.

• Set the LD_PRELOAD environment variable to the libjvm.so from your JVM installation.

Linux


• x86: Intel


• The following operating systems are supported:

• CentOS Linux 4.x, 5.x, 6.x, and 7.x

• Debian Linux 7.11, 8.5

• Oracle Linux 4.x, 5.x, 6.x, and 7.x

• Red Hat Enterprise Linux 4.x, 5.x, 6.x, and 7.x

• SUSE Linux Enterprise Server 10.x, and 11.x

• Ubuntu Linux 14.04, 16.04

• An application compatible with components that were built using g++ GNU project C++ Compiler version3.4.6 and the Linux native pthread threading model (Linuxthreads).

Oracle Solaris

• x64: Intel and AMD processor is supported.

• Oracle Solaris 10 and 11.x operating systems are supported.

• An application compatible with components that were built using Oracle C++ 5.8 and the Solaris native(kernel) threading model

See also64-Bit Driver on page 23Driver Requirements on page 17

64-Bit DriverAll required network software that is supplied by your database system vendors must be 64-bit compliant.

• A 64-bit Java Virtual Machine (JVM), Java SE 8 or higher, is required. Also, you must set the library pathenvironment variable of your operating system to the directory containing your JVM’s libjvm.so [a] fileand that directory’s parent directory.




• LD_LIBRARY_PATH on Linux, HP-UX Itanium, and Oracle Solaris

• LIBPATH on AIX

See "Driver Requirements" for more details on JVM.

AIX

• IBM POWER Processor

• AIX 5L operating system, version version 5.3 fixpack 5 and higher, 6.1, and 7.1

• An application compatible with components that were built using Visual Age C++ version 6.0.0.0 and theAIX native threading model

• IBM SDK, JAVA Technology Edition, Version 6 Service Refresh 9 or higher

• Before you can use the driver, you must set the LIBPATH environment variable to include the paths containingthe libjvm.so library and the libnio.so library, which are installed in a subdirectory of your JavaDevelopment Kit (JDK). For example, you would add the following paths for Java 8 installed in the /usrdirectory:

:/usr/java8_64/jre/lib/ppc64/classic:/usr/java8_64/jre/lib/ppc64

In this example, /usr/java8_64/jre/lib/ppc64/classic is the location of libjvm.so, while/usr/java8_64/jre/lib/ppc64 is the location of libnio.so.

Note: The driver is compiled using the –brtl loader option.Your application must support runtime linkingfunctionality.

HP-UX

• HP-UX IPF 11i operating system, Versions 2 and 3 (B.11.23 and B.11.31)

• HP aC++ v. 5.36 and the HP-UX 11 native (kernel) threading model (posix draft 10 threads)

Note: Do not link with the –lc linker option.

Note: Set the LD_PRELOAD environment variable to the libjvm.so of your JVM installation.

Linux



• CentOS Linux 4.x, 5.x, 6.x, and 7.x

• Debian Linux 7.11 and 8.5

• Oracle Linux 4.x, 5.x, 6.x, and 7.x

• Red Hat Enterprise Linux AS, ES, and WS version 4.x, 5.x, 6.x, and 7.x

• SUSE Linux Enterprise Server 10.x, and 11.x

• Ubuntu Linux 14.04 and 16.04



• For x64:

• SUSE Linux Enterprise Server 10.x, 11, and 12

• An application compatible with components that were built using g++ GNU project C++ Compiler version3.4 and the Linux native pthread threading model (Linuxthreads)

Oracle Solaris


• Oracle SPARC


• The following operating systems are supported:

• For Oracle SPARC: Oracle Solaris 8, 9, 10, and 11.x

• For x64: Oracle Solaris 10 and Oracle Solaris 11.x Express

• For Oracle SPARC: An application compatible with components that were built using Sun Studio 11, C++compiler version 5.8 and the Solaris native (kernel) threading model

• For x64: An application compatible with components that were built using Sun C++ Compiler version 5.8and the Solaris native (kernel) threading model

See alsoDriver Requirements on page 17

AIXIf you are building 64-bit binaries, you must pass the define ODBC64. The example Application provides ademonstration of this. See the installed file example.txt for details.

You must also include the correct compiler switches if you are building 64-bit binaries. For instance, to buildexample, you would use:

xlC_r –DODBC64 -q64 -qlonglong -qlongdouble -qvftable -o example-I../include example.c -L../lib -lc_r -lC_r -lodbc

HP-UX 11 aCCThe ODBC drivers require certain runtime library patches. The patch numbers are listed in the readme file foryour product. HP-UX patches are publicly available from the HP Web site http://www.hp.com.

HP updates the patch database regularly; therefore, the patch numbers in the readme file may be supersededby newer versions. If you search for the specified patch on an HP site and receive a message that the patchhas been superseded, download and install the replacement patch.

If you are building 64-bit binaries, you must pass the define ODBC64. The example Application provides ademonstration of this. See the installed file example.txt for details.You must also include the +DD64 compilerswitch if you are building 64-bit binaries. For instance, to build example, you would use:

aCC -Wl,+s +DD64 -DODBC64 -o example -I../include example.c -L../lib -lodbc



http://www.hp.com

LinuxIf you are building 64-bit binaries, you must pass the define ODBC64. The example Application provides ademonstration of this. See the installed file example.txt for details.

You must also include the correct compiler switches if you are building 64-bit binaries. For instance, to buildexample, you would use:

g++ -o example -DODBC64 -I../include example.c -L../lib -lodbc -lodbcinst -lc

Oracle SolarisIf you are building 64-bit binaries, you must pass the define ODBC64. The example Application provides ademonstration of this. See the installed file example.txt for details.

You must also include the -xarch=v9 compiler switch if you are building 64-bit binaries. For instance, to buildexample, you would use:

CC -mt –DODBC64 -xarch=v9 -o example -I../include example.c -L../lib -lodbc –lCrun

Setup of the Environment and the DriversOn UNIX and Linux, several environment variables and the system information file must be configured beforethe drivers can be used. See the following topics for additional information:

• "Configuring and Connecting on UNIX and Linux" contains a brief description of these variables.

• "Configuring and Connection to Data Sources" provides details about driver configuration.

• "Configuring the Product on UNIX/Linux" provides complete information about using the drivers on UNIXand Linux.

See alsoConfiguring and Connecting on UNIX and Linux on page 33Configuring and Connecting to Data Sources on page 38Configuring the Product on UNIX/Linux on page 38

Driver Names for UNIX/LinuxThe drivers are ODBC API-compliant dynamic link libraries, referred to in UNIX and Linux as shared objects.The prefix for all 32-bit driver file names is iv. The prefix for all 64-bit driver file names is dd. The driver filenames are lowercase and the extension is .so, the standard form for a shared object. For example, the 32-bitdriver file name is ivsfrcnn.so, where nn is the revision number of the driver.


ivsfrc28.so


ddsfrc28.so

Refer to the readme file shipped with the product for a complete list of installed files.



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 SQLForeignKeys and SQLPrimaryKeys functions to reportrelationships 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 option 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 alsoSchema Map on page 175Using Identifiers on page 96Config Options on page 142UppercaseIdentifiers (Config Option) on page 147AuditColumns (Config Option) on page 143CustomSuffix (Config Option) on page 144MapSystemColumnNames (Config Option) on page 145


Mapping Objects to Tables

Data TypesThe following table lists the data types supported by the Salesforce driver for local tables, how the Salesforcedata types exposed by the Salesforce Web Service API map to them, and how the Salesforce Web ServiceAPI data types map to the ODBC data types.

Table 2: Salesforce Data Types for Local Tables

ODBC Data TypeWeb Service API Data TypeSalesforce Data Type

SQL_WVARCHARanytypeANYTYPE

SQL_WVARCHARstringAUTONUMBER

SQL_LONGVARBINARYbinaryBINARY

SQL_BITbooleanCHECKBOX

SQL_WVARCHARcomboboxCOMBOBOX

SQL_DECIMALcurrencyCURRENCY

SQL_TYPE_DATEdateDATE

SQL_TYPE_TIMESTAMPdatetimeDATETIME

SQL_WVARCHARemailEMAIL

SQL_WVARCHARencryptedtextENCRYPTEDTEXT

SQL_WLONGVARCHARhtmlHTML

SQL_WVARCHARidID

SQL_INTEGERdoubleINT

SQL_WLONGVARCHARlongtextareaLONGTEXTAREA

SQL_WVARCHARmultipicklistMULTISELECTPICKLIST

SQL_DOUBLE1doubleNUMBER

SQL_DECIMALpercentPERCENT

SQL_WVARCHARphonePHONE

SQL_WVARCHARpicklistPICKLIST

1 If scale does not = 0 or precision > 9 or the NumberFieldMapping key of the ConfigOptions connection option is set to 2.SQL_INTEGER if scale = 0 and precision <= 9 and the NumberFieldMapping key of the ConfigOptions connection option is setto 1.




SQL_WVARCHARreferenceREFERENCE

SQL_WVARCHARstringTEXT

SQL_WVARCHARtextareaTEXTAREA

SQL_TYPE_TIMEtimeTIME

SQL_WVARCHARurlURL

The following table lists the data types supported by the Salesforce driver for remote tables, how the Salesforcedata types exposed by the Salesforce Web Service API map to them, and how the Salesforce Web ServiceAPI data types map to the ODBC data types.

Table 3: Salesforce Data Types for Remote Tables


SQL_WVARCHARanytypeANYTYPE

SQL_WVARCHARstringAUTONUMBER

SQL_LONGVARBINARYbinaryBINARY

SQL_BITbooleanCHECKBOX

SQL_WVARCHARcomboboxCOMBOBOX

SQL_DOUBLEcurrencyCURRENCY

SQL_WVARCHARDataCategoryGroupReferenceDATACATEGORYGROUPREFERENCE

SQL_TYPE_DATEdateDATE

SQL_TYPE_TIMESTAMPdatetimeDATETIME

SQL_WVARCHARemailEMAIL

SQL_WLONGVARCHARhtmlHTML

SQL_WVARCHARidID

SQL_INTEGERdoubleINT

SQL_WLONGVARCHARlongtextareaLONGTEXTAREA

SQL_WVARCHARmultipicklistMULTISELECTPICKLIST

SQL_DOUBLE1doubleNUMBER

SQL_DOUBLEpercentPERCENT


Data Types


SQL_WVARCHARphonePHONE

SQL_WVARCHARpicklistPICKLIST

SQL_WVARCHARreferenceREFERENCE

SQL_WVARCHARstringTEXT

SQL_WVARCHARtextareaTEXTAREA

SQL_TYPE_TIMEtimeTIME

SQL_WVARCHARurlURL

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


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

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

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

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

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

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

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

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

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

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




2Getting Started

This chapter provides basic information about configuring your driver immediately after installation, testing yourconnection, and accessing your data with some commonly used third-party applications.To take full advantageof the features of the driver, read "Using the Driver".

Information that the driver needs to connect to a database is stored in a data source. The ODBC specificationdescribes three types of data sources: user data sources, system data sources (not a valid type on UNIX/Linux),and file data sources. On Windows, user and system data sources are stored in the registry of the local computer.The difference is that only a specific user can access user data sources, whereas any user of the machine canaccess system data sources. On all platforms, file data sources, which are simply text files, can be storedlocally or on a network computer, and are accessible to other machines.

When you define and configure a data source, you store default connection values for the driver that are usedeach time you connect to a particular database.You can change these defaults by modifying the data source.


• Configuring and Connecting on Windows

• Configuring and Connecting on UNIX and Linux

• Accessing Data With Third-Party Applications


Configuring and Connecting on Windows

The following basic information enables you to configure a data source and test connect with a driverimmediately after installation. On Windows, you can configure and modify data sources through the ODBCAdministrator using a driver Setup dialog box. Default connection values are specified through the options onthe tabs of the Setup dialog box and are stored either as a user or system data source in the Windows Registry,or as a file data source in a specified location.

Setting the Library Path Environment Variable (Windows)

Before you can use your driver, you must set the PATH environment variable to include the path of the jvm.dllfile of your Java™ Virtual Machine (JVM).

Note: The installer program sets the PATH environment variable to include the path of the jvm.dll file bydefault.

Configuring a Data Source

To configure a data source:

1. From the Progress DataDirect program group, start the ODBC Administrator and click either the User DSN,System DSN, or File DSN tab to display a list of data sources.

• User DSN: If you installed a default DataDirect ODBC user data source as part of the installation, selectthe appropriate data source name and click Configure to display the driver Setup dialog box.

If you are configuring a new user data source, click Add to display a list of installed drivers. Select theappropriate driver and click Finish to display the driver Setup dialog box.

• System DSN: To configure a new system data source, click Add to display a list of installed drivers.Select the appropriate driver and click Finish to display the driver Setup dialog box.

• File DSN: To configure a new file data source, click Add to display a list of installed drivers. Select thedriver and click Advanced to specify attributes; otherwise, click Next to proceed. Specify a name forthe data source and click Next.Verify the data source information; then, click Finish to display the driverSetup dialog box.

The General tab of the Setup dialog box appears by default.

Note: The General tab displays only fields that are required for creating a data source. The fields on allother tabs are optional, unless noted otherwise in this book.

2. On the General tab, provide the following information; then, click Apply.

Host Name: Type the URL or IP address of the Salesforce instance to which you want to connect. Thedefault is login.salesforce.com.

User Name: Type your logon ID, including domain, for Salesforce. For example, [email protected].


Chapter 2: Getting Started

Security Token: If your Salesforce instance requires a security token, type your Salesforce generatedsecurity token. This value is case-sensitive.

Note: You must provide the following information in the logon dialog box.

Password: Type your case-sensitive password for the Salesforce instance. This value is case-sensitive.

Testing the Connection

To test the connection:

1. After you have configured the data source, you can click Test Connect on the Setup dialog box to attemptto connect to the data source using the connection options specified in the dialog box. The driver returns amessage indicating success or failure. A logon dialog box appears as described in "Using a Logon DialogBox."

2. Supply the requested information in the logon dialog box and click OK. Note that the information you enterin the logon dialog box during a test connect is not saved.

• If the driver can connect, it releases the connection and displays a Connection Established message.Click OK.

• If the driver cannot connect because of an incorrect environment or connection value, it displays anappropriate error message. Click OK.

3. On the driver Setup dialog box, click OK. The values you have specified are saved and are the defaultsused when you connect to the data source.You can change these defaults by using the previously describedprocedure to modify your data source.You can override these defaults by connecting to the data sourceusing a connection string with alternate values. See "Using a Connection String" for information about usingconnection strings.

See alsoUsing a Connection String on page 69Using a Logon Dialog Box on page 70

Configuring and Connecting on UNIX and LinuxThe following basic information enables you to configure a data source and test connect with a driver immediatelyafter installation. See "Configuring and Connecting to Data Sources" for detailed information about configuringthe UNIX and Linux environments and data sources.

Note: In the following examples, xx in a driver filename represents the driver level number.

See alsoConfiguring and Connecting to Data Sources on page 38


Configuring and Connecting on UNIX and Linux

Environment Configuration

To configure the environment:

1. Check your permissions:You must log in as a user with full r/w/x permissions recursively on the entireproduct installation directory.

2. From your login shell, determine which shell you are running by executing:

echo $SHELL

3. Run one of the following product setup scripts from the installation directory to set variables: odbc.sh orodbc.csh. For Korn, Bourne, and equivalent shells, execute odbc.sh. For a C shell, execute odbc.csh.After running the setup script, execute:

env

to verify that the installation_directory/lib directory has been added to your shared library path.

4. Set the ODBCINI environment variable. The variable must point to the path from the root directory to thesystem information file where your data source resides. The system information file can have any name,but the product is installed with a default file called odbc.ini in the product installation directory. Forexample, if you use an installation directory of /opt/odbc and the default system information file, from theKorn or Bourne shell, you would enter:

ODBCINI=/opt/odbc/odbc.ini; export ODBCINI

From the C shell, you would enter:

setenv ODBCINI /opt/odbc/odbc.ini

Test Loading the Driver

The ivtestlib (32-bit drivers) and ddtestlib (64-bit drivers) test loading tools are provided to test load drivers andhelp diagnose configuration problems in the UNIX and Linux environments, such as environment variables notcorrectly set or missing database client components.This tool is installed in the /bin subdirectory in the productinstallation directory. It attempts to load a specified ODBC driver and prints out all available error informationif the load fails.

For example, if the drivers are installed in /opt/odbc/lib, the following command attempts to load the 32-bitdriver on Linux, where xx represents the version number of the driver:

ivtestlib /opt/odbc/lib/ivsfrcxx.so

Note: On Solaris, AIX, and Linux, the full path to the driver does not have to be specified for the tool. TheHP-UX version, however, requires the full path.

If the load is successful, the tool returns a success message along with the version string of the driver. If thedriver cannot be loaded, the tool returns an error message explaining why.



Setting the Library Path Environment Variable (UNIX and Linux)

Before you can use the Salesforce driver, you must set the library path environment variable for your UNIX/Linuxoperating system to include the directory containing your JVM’s libjvm.so [a] file, and that directory’s parentdirectory.

NOTE FOR HP-UX:You also must set the LD_PRELOAD environment variable to the fully qualified path ofthe libjvm.so.

32-bit Driver: Library Path Environment Variable

Set the library path environment variable to include the directory containing your 32-bit JVM’s libjvm.so [a]file, and that directory’s parent directory.

• LD_LIBRARY_PATH on Solaris, Linux, and HP-UX (Itanium)

• LIBPATH on AIX

64-bit Driver: Library Path Environment Variable

Set the library path environment variable to include the directory containing your 64-bit JVM’s libjvm.so [a]file, and that directory’s parent directory.

• LD_LIBRARY_PATH on Solaris, HP-UX (Itanium), and Linux

• LIBPATH on AIX

Configuring a Data Source

The default odbc.ini file installed in the installation directory is a template in which you create data sourcedefinitions.You enter your site-specific database connection information using a text editor. Each data sourcedefinition must include the keyword Driver=, which is the full path to the driver.

The following examples show the minimum connection string options that must be set to complete a testconnection, where xx represents iv for 32-bit or dd for 64-bit drivers, and yy represents the extension. Thevalues for the options are samples and are not necessarily the ones you would use.

[ODBC Data Sources]Salesforce=DataDirect 8.0 Salesforce

[Salesforce]Driver=ODBCHOME/lib/xxsfrc28.yyHostName=test.salesforce.comUserName=JohnDoePassword=secretSecurityToken=XaBARTsLZReM4Px47qPLOS

Connection Option Descriptions:

• HostName: The URL or IP address of the Salesforce instance to which you want to connect. The defaultis login.salesforce.com.

• UserName:Your logon ID for Salesforce

• Password:Your case-sensitive password for the Salesforce instance.

• SecurityToken: If required by your instance, your case-sensitive security token for the Salesforce instance.


Configuring and Connecting on UNIX and Linux

Testing the Connection

The driver installation includes an ODBC application called example that can be used to connect to a datasource and execute SQL.The application is located in the installation_directory/samples/exampledirectory.

To run the program after setting up a data source in the odbc.ini, enter example and follow the prompts toenter your data source name, user name, and password. If successful, a SQL> prompt appears and you cantype in SQL statements such as SELECT * FROM table. If example is unable to connect, the appropriateerror message is returned.

Accessing Data With Third-Party ApplicationsFor procedures related to accessing data with common third-party applications, such as Tableau and Excel,refer to the Quick Start that corresponds to your data source and platform athttps://www.progress.com/documentation/datadirect-connectors.



https://www.progress.com/documentation/datadirect-connectors

3Using the Driver

This section guides you through the configuring and connecting to data sources. In addition, it explains howto use the functionality supported by your driver.


• Configuring and Connecting to Data Sources

• Connecting Through a Proxy Server

• Performance Considerations

• Using the SQL Engine Server

• Using Client-Side Caches

• Catalog Tables

• Using Reports

• Using Security

• Using DataDirect Connection Pooling

• Using Identifiers

• Using IP Addresses

• Timeouts

• Views and Remote/Local Tables

• SQL Support


• Isolation and Lock Levels Supported

• Number of Connections and Statements Supported

• Unicode Support

• Parameter Metadata Support

• Using DataDirect Bulk Load

• Using Bulk API with SQL Statements

Configuring and Connecting to Data SourcesAfter you install the driver, you configure data sources to connect to the database. See "Getting Started" foran explanation of different types of data sources. The data source contains connection options that allow youto tune the driver for specific performance. If you want to use a data source but need to change some of itsvalues, you can either modify the data source or override its values at connection time through a connectionstring.

If you choose to use a connection string, you must use specific connection string attributes. See "Using aConnection String" for an alphabetical list of driver connection string attributes and their initial default values.

See alsoGetting Started on page 31Using a Connection String on page 69

Configuring the Product on UNIX/Linux

This chapter contains specific information about using your driver in the UNIX and Linux environments.

See "Environment Variables" for additional platform information.

See alsoEnvironment Variables on page 38

Environment VariablesThe first step in setting up and configuring the driver for use is to set several environment variables. Thefollowing procedures require that you have the appropriate permissions to modify your environment and toread, write, and execute various files.You must log in as a user with full r/w/x permissions recursively on theentire Progress DataDirect for ODBC installation directory.

Library Search Path

The library search path variable can be set by executing the appropriate shell script located in the ODBC homedirectory. From your login shell, determine which shell you are running by executing:

echo $SHELL


Chapter 3: Using the Driver

C shell login (and related shell) users must execute the following command before attempting to useODBC-enabled applications:

source ./odbc.csh

Bourne shell login (and related shell) users must initialize their environment as follows:

. ./odbc.sh

Executing these scripts sets the appropriate library search path environment variable:

• LD_LIBRARY_PATH on HP-UX IPF, Linux, and Oracle Solaris

• LIBPATH on AIX

The library search path environment variable must be set so that the ODBC core components and drivers canbe located at the time of execution. After running the setup script, execute:

env

to verify that the installation_directory/lib directory has been added to your shared library path.

ODBCINI

Setup installs in the product installation directory a default system information file, named odbc.ini, thatcontains data sources. See "Data Source Configuration on UNIX/Linux" for an explanation of the odbc.inifile. The system administrator can choose to rename the file and/or move it to another location. In either case,the environment variable ODBCINI must be set to point to the fully qualified path name of the odbc.ini file.

For example, to point to the location of the file for an installation on /opt/odbc in the C shell, you would setthis variable as follows:

setenv ODBCINI /opt/odbc/odbc.ini

In the Bourne or Korn shell, you would set it as:

ODBCINI=/opt/odbc/odbc.ini;export ODBCINI

As an alternative, you can choose to make the odbc.ini file a hidden file and not set the ODBCINI variable.In this case, you would need to rename the file to .odbc.ini (to make it a hidden file) and move it to theuser’s $HOME directory.

The driver searches for the location of the odbc.ini file as follows:

1. The driver checks the ODBCINI variable

2. The driver checks $HOME for .odbc.ini

If the driver does not locate the system information file, it returns an error.

See alsoData Source Configuration on UNIX/Linux on page 41

ODBCINST

Setup installs in the product installation directory a default file, named odbcinst.ini, for use with DSN-lessconnections. See "DSN-Less Connections" for an explanation of the odbcinst.ini file. The systemadministrator can choose to rename the file or move it to another location. In either case, the environmentvariable ODBCINST must be set to point to the fully qualified path name of the odbcinst.ini file.


Configuring and Connecting to Data Sources

For example, to point to the location of the file for an installation on /opt/odbc in the C shell, you would setthis variable as follows:

setenv ODBCINST /opt/odbc/odbcinst.ini


ODBCINST=/opt/odbc/odbcinst.ini;export ODBCINST

As an alternative, you can choose to make the odbcinst.ini file a hidden file and not set the ODBCINSTvariable. In this case, you would need to rename the file to .odbcinst.ini (to make it a hidden file) andmove it to the user’s $HOME directory.

The driver searches for the location of the odbcinst.ini file as follows:

1. The driver checks the ODBCINST variable

2. The driver checks $HOME for .odbcinst.ini

If the driver does not locate the odbcinst.ini file, it returns an error.

See alsoDSN-less Connections on page 45

DD_INSTALLDIR

This variable provides the driver with the location of the product installation directory so that it can accesssupport files. DD_INSTALLDIR must be set to point to the fully qualified path name of the installation directory.

For example, to point to the location of the directory for an installation on /opt/odbc in the C shell, you wouldset this variable as follows:

setenv DD_INSTALLDIR /opt/odbc


DD_INSTALLDIR=/opt/odbc;export DD_INSTALLDIR

The driver searches for the location of the installation directory as follows:

1. The driver checks the DD_INSTALLDIR variable

2. The driver checks the odbc.ini or the odbcinst.ini files for the InstallDir keyword (see "ConfigurationThrough the System Information (odbc.ini) File" for a description of the InstallDir keyword)

If the driver does not locate the installation directory, it returns an error.

The next step is to test load the driver.

See alsoConfiguration Through the System Information (odbc.ini) File on page 41

The Test Loading ToolThe second step in preparing to use a driver is to test load it.



The ivtestlib (32-bit driver) and ddtestlib (64-bit driver) test loading tools are provided to test load drivers andhelp diagnose configuration problems in the UNIX and Linux environments, such as environment variables notcorrectly set or missing database client components.This tool is installed in the /bin subdirectory in the productinstallation directory. It attempts to load a specified ODBC driver and prints out all available error informationif the load fails.

For example, if the driver is installed in /opt/odbc/lib, the following command attempts to load the 32-bitdriver on Linux, where xx represents the version number of the driver:




See "Version String Information" for details about version strings.

The next step is to configure a data source through the system information file.

See alsoVersion String Information on page 18

Data Source Configuration on UNIX/LinuxIn the UNIX and Linux environments, a system information file is used to store data source information. Setupinstalls a default version of this file, called odbc.ini, in the product installation directory. This is a plain textfile that contains data source definitions.

Configuration Through the System Information (odbc.ini) File

To configure a data source manually, you edit the odbc.ini file with a text editor. The content of this file isdivided into three sections.

Note: The driver and driver manager support ASCII and UTF-8 encoding in the odbc.ini file. For additionaldetails, see "Character Encoding in the odbc.ini and odbcinst.ini Files".

At the beginning of the file is a section named [ODBC Data Sources] containingdata_source_name=installed-driver pairs, for example:

Salesforce=DataDirect 8.0 Salesforce

The driver uses this section to match a data source to the appropriate installed driver.

The [ODBC Data Sources] section also includes data source definitions. The default odbc.ini containsa data source definition for the driver. Each data source definition begins with a data source name in squarebrackets, for example, [Salesforce 2].The data source definitions contain connection string attribute=valuepairs with default values.You can modify these values as appropriate for your system. "Connection OptionDescriptions" describes these attributes. See "Sample Default odbc.ini File" for sample data sources.

The second section of the file is named [ODBC File DSN] and includes one keyword:

[ODBC File DSN]DefaultDSNDir=

This keyword defines the path of the default location for file data sources (see "File Data Sources").



Note: This section is not included in the default odbc.ini file that is installed by the product installer.Youmust add this section manually.

The third section of the file is named [ODBC] and includes several keywords, for example:

[ODBC]IANAAppCodePage=4InstallDir=/opt/odbcTrace=0TraceFile=odbctrace.outTraceDll=/opt/odbc/lib/ivtrc28.soODBCTraceMaxFileSize=102400ODBCTraceMaxNumFiles=10

The IANAAppCodePage keyword defines the default value that the UNIX/Linux driver uses if individual datasources have not specified a different value. See "IANAAppCodePage" in the "Connection Option Descriptions"chapter and "Code Page Values" for details. The default value is 4.

The InstallDir keyword must be included in this section. The value of this keyword is the path to the installationdirectory under which the /lib and /locale directories are contained.The installation process automaticallywrites your installation directory to the default odbc.ini file.

For example, if you choose an installation location of /opt/odbc, then the following line is written to the[ODBC] section of the default odbc.ini:

InstallDir=/opt/odbc

Note: If you are using only DSN-less connections through an odbcinst.ini file and do not have an odbc.inifile, then you must provide [ODBC] section information in the [ODBC] section of the odbcinst.ini file. Thedriver and Driver Manager always check first in the [ODBC] section of an odbc.ini file. If no odbc.ini fileexists or if the odbc.ini file does not contain an [ODBC] section, they check for an [ODBC] section in theodbcinst.ini file. See "DSN-less Connections" for details.

ODBC tracing allows you to trace calls to the ODBC driver and create a log of the traces for troubleshootingpurposes. The following keywords all control tracing: Trace, TraceFile, TraceDLL, ODBCTraceMaxFileSize,and ODBCTraceMaxNumFiles.

For a complete description of these keywords and discussion of tracing, see "ODBC Trace."

See alsoCharacter Encoding in the odbc.ini and odbcinst.ini Files on page 276Connection Option Descriptions on page 127Sample Default odbc.ini File on page 43File Data Sources on page 46IANAAppCodePage on page 158Code Page Values on page 251DSN-less Connections on page 45ODBC Trace on page 113



Sample Default odbc.ini File

The following is a sample odbc.ini file that the installer program installs in the installation directory. Alloccurrences of ODBCHOME are replaced with your installation directory path during installation of the file.Values that you must supply are enclosed by angle brackets (< >). If you are using the installed odbc.inifile, you must supply the values and remove the angle brackets before that data source section will operateproperly. Commented lines are denoted by the # symbol. This sample shows a 32-bit driver with the driver filename beginning with iv. A 64-bit driver file would be identical except that driver name would begin with ddand the list of data sources would include only the 64-bit drivers.

[ODBC Data Sources]Salesforce=DataDirect 8.0 Salesforce

[Salesforce]Driver=ODBCHOME/lib/ivsfrc28.soDescription=DataDirect 8.0 SalesforceApplicationUsingThreads=1BulkFetchThreshold=3000BulkLoadAsync=0BulkLoadBatchSize=1024BulkLoadConcurrencyMode=1BulkLoadPollInterval=10BulkLoadProtocol=0BulkLoadThreshold=4000BulkLoadTimeout=0ConnectionReset=0ConfigOptions=CreateMap=2EnableBulkFetch=1EnableBulkLoad=1EnablePKChunking=1ExtendedOptions=FetchSize=100HostName=login.salesforce.comInitializationString=IANAAppCodePage=JVMArgs=-Xmx256mJVMClasspath=LoadBalanceTimeout=0LogConfigFile=LoginTimeout=15LogonID=MaxPoolSize=100MinPoolSize=0PKChunkSize=100000Pooling=0ProxyHost=ProxyPassword=ProxyPort=ProxyUser=ReadOnly=0RefreshSchema=0 ReportCodepageConversionErrors=0SchemaMap=SecurityToken=ServerPortNumber=19928SQLEngineMode=2StmtCallLimit=100StmtCallLimitBehavior=2TransactionMode=0WSFetchSize=0WSPoolSize=1WSRetryCount=0WSTimeout=120

[ODBC]IANAAppCodePage=4



InstallDir=ODBCHOMETrace=0TraceFile=odbctrace.outTraceDll=ODBCHOME/lib/ivtrc28.soODBCTraceMaxFileSize=102400ODBCTraceMaxNumFiles=10[ODBC File DSN]DefaultDSNDir=UseCursorLib=0

To modify or create data sources in the odbc.ini file, use the following procedures.

• To modify a data source:

a) Using a text editor, open the odbc.ini file.

b) Modify the default attributes in the data source definitions as necessary based on your system specifics,for example, enter the host name and port number of your system in the appropriate location.

Consult the "Salesforce Attributes" table in Connection Option Descriptions for other specific attributevalues.

c) After making all modifications, save the odbc.ini file and close the text editor.

Important: The "Connection Option Descriptions" section lists both the long and short names of theattribute. When entering attribute names into odbc.ini, you must use the long name of the attribute.The short name is not valid in the odbc.ini file.

• To create a new data source:

a) Using a text editor, open the odbc.ini file.

b) Copy an appropriate existing default data source definition and paste it to another location in the file.

c) Change the data source name in the copied data source definition to a new name. The data sourcename is between square brackets at the beginning of the definition, for example, [Salesforce].

d) Modify the attributes in the new definition as necessary based on your system specifics, for example,enter the host name and port number of your system in the appropriate location.

Consult the "Salesforce Attributes" table in "Connection Option Descriptions" for other specific attributevalues.

e) In the [ODBC] section at the beginning of the file, add a new data_source_name=installed-driver paircontaining the new data source name and the appropriate installed driver name.

f) After making all modifications, save the odbc.ini file and close the text editor.

Important: The "Salesforce Attributes" table in "Connection Option Descriptions" lists both the long andshort name of the attribute.When entering attribute names into odbc.ini, you must use the long nameof the attribute. The short name is not valid in the odbc.ini file.

See alsoConnection Option Descriptions on page 127



The Example ApplicationProgress DataDirect ships an application, named example, that is installed in the /samples/examplesubdirectory of the product installation directory. Once you have configured your environment and data source,use the example application to test passing SQL statements.To run the application, enter example and followthe prompts to enter your data source name, user name, and password.

If successful, a SQL> prompt appears and you can type in SQL statements, such as SELECT * FROMtable_name. If example is unable to connect to the database, an appropriate error message appears.

Refer to the example.txt file in the example subdirectory for an explanation of how to build and use thisapplication.

For more information, see The Example Application in Progress DataDirect for ODBC Drivers Reference.

DSN-less ConnectionsConnections to a data source can be made via a connection string without referring to a data source name(DSN-less connections). This is done by specifying the "DRIVER=" keyword instead of the "DSN=" keyword ina connection string, as outlined in the ODBC specification. A file named odbcinst.ini must exist when thedriver encounters DRIVER= in a connection string.

Setup installs a default version of this file in the product installation directory (see "ODBCINST" for details aboutrelocating and renaming this file).This is a plain text file that contains default DSN-less connection information.You should not normally need to edit this file. The content of this file is divided into several sections.

Note: The driver and driver manager support ASCII and UTF-8 encoding in the odbcinst.ini file. Foradditional details, see "Character Encoding in the odbc.ini and odbcinst.ini Files."

At the beginning of the file is a section named [ODBC Drivers] that lists installed drivers, for example,

DataDirect 8.0 Salesforce=Installed

This section also includes additional information for each driver.

The final section of the file is named [ODBC]. The [ODBC] section in the odbcinst.ini file fulfills the samepurpose in DSN-less connections as the [ODBC] section in the odbc.ini file does for data source connections.See "Configuration Through the System Information (odbc.ini) File" for a description of the other keywords thissection.

Note: The odbcinst.ini file and the odbc.ini file include an [ODBC] section. If the information in thesetwo sections is not the same, the values in the odbc.ini [ODBC] section override those of the odbcinst.ini[ODBC] section.

See alsoODBCINST on page 39Character Encoding in the odbc.ini and odbcinst.ini Files on page 276Configuration Through the System Information (odbc.ini) File on page 41



https://documentation.progress.com/output/DataDirect/odbcreferencehelp/index.html#context/ODBC/example_application

Sample odbcinst.ini File

The following is a sample odbcinst.ini. All occurrences of ODBCHOME are replaced with your installationdirectory path during installation of the file. Commented lines are denoted by the # symbol.This sample showsa 32-bit driver with the driver file name beginning with iv; a 64-bit driver file would be identical except thatdriver names would begin with dd.

[ODBC Drivers]DataDirect 8.0 Salesforce=Installed

[DataDirect 8.0 Salesforce]Driver=ODBCHOME/lib/ivsfrc28.soJarFile=ODBCHOME/java/lib/sforce.jarAPILevel=0ConnectFunctions=YYYCPTimeout=60DriverODBCVer=3.52FileUsage=0HelpRootDirectory=ODBCHOME/Help/SalesforceHelpSQLLevel=0UsageCount=1

[ODBC]#This section must contain values for DSN-less connections#if no odbc.ini file exists. If an odbc.ini file exists,#the values from that [ODBC] section are used.

IANAAppCodePage=4InstallDir=ODBCHOMETrace=0TraceFile=odbctrace.outTraceDll=ODBCHOME/lib/ivtrc28.soODBCTraceMaxFileSize=102400ODBCTraceMaxNumFiles=10

File Data SourcesThe Driver Manager on UNIX and Linux supports file data sources. The advantage of a file data source is thatit can be stored on a server and accessed by other machines, either Windows, UNIX, or Linux. See "GettingStarted" for a general description of ODBC data sources on both Windows and UNIX.

A file data source is simply a text file that contains connection information. It can be created with a text editor.The file normally has an extension of .dsn.

For example, a file data source for the driver would be similar to the following:

[ODBC]Driver=DataDirect 8.0 Salesforce Port=19937HostName=login.salesforce.comLogonID=jsmith@defcorp.comSchemaMap=~/progress/datadirect/salesforce_schema/[email protected]=XaBARTsLZReM4Px47qPLOS

It must contain all basic connection information plus any optional attributes. Because it uses the DRIVER=keyword, an odbcinst.ini file containing the driver location must exist (see "DSN-less Connections").

The file data source is accessed by specifying the FILEDSN= instead of the DSN= keyword in a connectionstring, as outlined in the ODBC specification. The complete path to the file data source can be specified in thesyntax that is normal for the machine on which the file is located. For example, on Windows:

FILEDSN=C:\Program Files\Common Files\ODBC\DataSources\Salesforce2.dsn



or, on UNIX and Linux:

FILEDSN=/home/users/john/filedsn/Salesforce2.dsn

If no path is specified for the file data source, the Driver Manager uses the DefaultDSNDir property, which isdefined in the [ODBC File DSN] setting in the odbc.ini file to locate file data sources (see "Data SourceConfiguration on UNIX/Linux" for details). If the [ODBC File DSN] setting is not defined, the Driver Manageruses the InstallDir setting in the [ODBC] section of the odbc.ini file. The Driver Manager does not supportthe SQLReadFileDSN and SQLWriteFileDSN functions.

As with any connection string, you can specify attributes to override the default values in the data source:

FILEDSN=/home/users/john/filedsn/Salesforce2.dsn;UID=james;PWD=test01

See alsoGetting Started on page 31DSN-less Connections on page 45Getting Started on page 31Data Source Configuration on UNIX/Linux on page 41

UTF-16 Applications on UNIX and LinuxBecause the DataDirect Driver Manager allows applications to use either UTF-8 or UTF-16 Unicode encoding,applications written in UTF-16 for Windows platforms can also be used on UNIX and Linux platforms.

The Driver Manager assumes a default of UTF-8 applications; therefore, two things must occur for it to determinethat the application is UTF-16:

• The definition of SQLWCHAR in the ODBC header files must be switched from "char *" to "short *". To dothis, the application uses #define SQLWCHARSHORT.

• The application must set the encoding for the environment or connection using one of the following attributes.If your application passes UTF-8 encoded strings to some connections and UTF-16 encoded strings toother connections in the same environment, encoding should be set for the connection only; otherwise,either method can be used.

• To configure the encoding for the environment, set the ODBC environment attributeSQL_ATTR_APP_UNICODE_TYPE to a value of SQL_DD_CP_UTF16, for example:

rc = SQLSetEnvAttr(*henv,SQL_ATTR_APP_UNICODE_TYPE,(SQLPOINTER)SQL_DD_CP_UTF16, SQL_IS_INTEGER);

• To configure the encoding for the connection only, set the ODBC connection attributeSQL_ATTR_APP_UNICODE_TYPE to a value of SQL_DD_CP_UTF16. For example:

rc = SQLSetConnectAttr(hdbc, SQL_ATTR_APP_UNICODE_TYPE, SQL_DD_CP_UTF16,SQL_IS_INTEGER);

Configuring the Product Using the GUI

On Windows, data sources are stored in the Windows Registry.You can configure and modify data sourcesthrough the ODBC Administrator using a driver Setup dialog box, as described in this section.

On UNIX and Linux, the GUI is not supported.



When the driver is first installed, the values of its connection options are set by default. These values appearon the driver Setup dialog box tabs when you create a new data source.You can change these default valuesby modifying the data source. In the following procedure, the description of each tab is followed by a table thatlists the connection options for that tab and their initial default values. This table links you to a completedescription of the options and their connection string attribute equivalents. The connection string attributes areused to override the default values of the data source if you want to change these values at connection time.

To configure a Salesforce data source:

1. Start the ODBC Administrator by selecting its icon from the Progress DataDirect for ODBC program group.

2. Select a tab:

• User DSN: If you are configuring an existing user data source, select the data source name and clickConfigure to display the driver Setup dialog box.

If you are configuring a new user data source, click Add to display a list of installed drivers. Select thedriver and click Finish to display the driver Setup dialog box.

• System DSN: If you are configuring an existing system data source, select the data source name andclick Configure to display the driver Setup dialog box.

If you are configuring a new system data source, click Add to display a list of installed drivers. Selectthe driver and click Finish to display the driver Setup dialog box.

• File DSN: If you are configuring an existing file data source, select the data source file and click Configureto display the driver Setup dialog box.

If you are configuring a new file data source, click Add to display a list of installed drivers; then, selecta driver. Click Advanced if you want to specify attributes; otherwise, click Next to proceed. Specify aname for the data source and click Next. Verify the data source information; then, click Finish to displaythe driver Setup dialog box.

3. The General tab of the Setup dialog box appears by default.

Figure 1: General tab



On this tab, provide values for the options in the following table; then, click Apply. The table provides linksto descriptions of the connection options. The General tab displays fields that are required for creating adata source. The fields on all other tabs are optional, unless noted otherwise.

DescriptionConnection Options: General

Specifies the name of a data source in your Windows Registry orodbc.ini file.

Default: NoneData Source Name on page 151

Specifies an optional long description of a data source.This descriptionis not used as a runtime connection attribute, but does appear in theODBC.INI section of the Registry and in the odbc.ini file.

Default: None

Description on page 152

The base Salesforce URL or IP address of your Salesforce instance.If you are logging into a Salesforce instance other than the default, youmust provide the root of the Salesforce URL or IP address.

Default: login.salesforce.com

Host Name on page 157

The default user ID and domain that is used to connect to yourdatabase. For example, [email protected].

Default: NoneUser Name on page 181

Specifies the security token required to make a connection to aSalesforce instance that is configured for a security token.

Default: Empty stringSecurity Token on page 176

Specifies the name and location of the configuration file where therelational map of native data is written. The driver looks for this filewhen connecting to a Salesforce instance. If the file does not exist, thedriver creates one.

Default:

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

Schema Map on page 175

4. At any point during the configuration process, you can click Test Connect to attempt to connect to the datasource using the connection options specified in the driver Setup dialog box. A logon dialog box appears(see "Using a Logon Dialog Box" for details). Note that the information you enter in the logon dialog boxduring a test connect is not saved.

5. To further configure your driver, click on the following tabs. The corresponding sections provide details onthe fields specific to each configuration tab:

• SQL Engine tab allows you to configure the SQL Engine's behavior.

• Advanced tab allows you to configure advanced behavior.

• Web Service tab allows you to configure the behavior of communications between the driver and theweb service.

• Pooling tab allows you to configure connection pooling behavior.



• Bulk tab allows you to specify settings for DataDirect Bulk Load.

6. Click OK. When you click OK, the values you have specified become the defaults when you connect to thedata source.You can change these defaults by using this procedure to reconfigure your data source.Youcan override these defaults by connecting to the data source using a connection string with alternate values.

See alsoUsing a Logon Dialog Box on page 70

SQL Engine TabThe SQL Engine Tab allows you to specify additional data source settings. The fields are optional unlessotherwise noted. On this tab, provide values for the options in the following tables; then, click Apply.

Figure 2: SQL Engine tab

The SQL Engine can be run in one of two modes: direct mode or server mode. When set to direct mode, boththe driver and its SQL engine run in the ODBC application's address space. Some applications may experienceproblems loading the JVM because the process exceeds the available heap space. To avoid this issue, youcan configure the driver to operate in server mode. Server mode allows the driver to connect to an SQL engineJVM running as a separate service.

By default, the driver is set to 0 - Auto. In this setting, the SQL Engine attempts to run in server mode first, butwill failover to direct mode if server mode is unavailable. If you prefer that the SQL engine runs exclusively ina particular mode, set the SQL Engine Mode option to 1 – Server to run only in server mode or 2 – Direct torun only in direct mode.



Table 4: SQL Engine Tab Connection Options

DefaultConnection Options: SQLEngine

If set to 0 - Auto, the SQL engine attempts to run in server mode first;however, if server mode is unavailable, it runs in direct mode.

If set to 1 - Server, the SQL engine runs in server mode.The SQL engineoperates in a separate process from the driver within its own JVM. If theSQL engine is unavailable, the connection will fail.

If set to 2 - Direct, the SQL engine runs in direct mode. The driver andits SQL engine run in a single process within the same JVM.

Important: When the SQL engine is configured to run in server mode(0-Auto | 1-Server), you must start the SQL Engine service before usingthe driver (see "Starting the SQL Engine Server" for more information).Multiple drivers on different clients can use the same service.

Important: Changes you make to the server mode configuration affectall DSNs sharing the service.

Default: 0 - Auto

SQL Engine Mode on page 178

A string that contains the arguments that are passed to the JVM that thedriver is starting. The location of the JVM must be specified on the driverlibrary path. Values that include special characters or spaces must beenclosed in curly braces { } when used in a connection string.

Default:

For the 32-bit driver when the SQL Engine Mode is set to 2 - Direct:-Xmx256m

For all other configurations: -Xmx1024m

JVM Arguments on page 160

Specifies the CLASSPATH for the Java Virtual Machine (JVM) used bythe driver. The CLASSPATH is the search string the JVM uses to locatethe Java jar files the driver needs.

Separate multiple jar files by a semi-colon on Windows platforms and bya colon on all other platforms. CLASSPATH values with multiple jar filesmust be enclosed in curly braces { } when used in a connection string.

Note: If no value is specified, the driver automatically detects theCLASSPATHs for all ODBC drivers installed on your machine.

Default: Empty String

JVM Classpath on page 161

Specifies the Hostname of the Proxy Server. The value specified can bea host name, a fully qualified domain name, or an IPv4 or IPv6 address.

Default: None

Proxy Host on page 168



DefaultConnection Options: SQLEngine

Specifies the port number where the Proxy Server is listening for HTTPand/or HTTPS requests.

Default: None

Proxy Port on page 169

Specifies the user name needed to connect to the Proxy Server.

Default: None

Proxy User on page 169

Specifies the password needed to connect to the Proxy Server.

Default: None

Proxy Password on page 168

When set to 0 - Auto or 1 – Server , additional configuration settings that are specific to server mode areexposed in the setup dialog. The settings for server mode are read only in the Driver Setup Dialog. For adescription of these settings, see the table below.

To define the settings for server mode, click Edit Server Settings from the SQL Engine tab. The SQL EngineService Setup dialog box appears.

Caution: Modifying the Server Settings will affect all DSNs using this service.

Note: You must be an administrator to modify the server mode settings. Otherwise, the Edit Server Settingsbutton does not appear on the SQL Engine tab.

You use the SQL Engine Service Setup dialog box to configure server mode and to start or stop the service.See "Configuring Server Mode" for detailed information.

Table 5: Server Mode Configuration Options

DescriptionConfiguration Options:SQL Engine Service

Specifies a valid port on which the SQL engine listens for requests from thedriver.

Default:

For the 32-bit driver: 19938

For the 64-bit driver: 19937

Server Port Number on page177

Specifies fully qualified path to the Java SE 8 or higher JVM executable thatyou want to use to run the SQL Engine Server.The path must not contain doublequotation marks.

Default: The fully qualified path to the Java SE 8 or higher JVM executable(java.exe)

Java Path

If you finished configuring your driver, proceed to Step 6 on page 50 in "Configuring the Product Using theGUI." Optionally, you can further configure your driver by clicking on the following tabs. The following sectionsprovide details for the fields specific to each configuration tab:



• General tab allows you to configure options that are required for creating a data source.


• Web Service tab allows you to configure the behavior of communications between the driver and the webservice.



See alsoStarting the SQL Engine Server on page 75Configuring Server Mode on page 74Configuring the Product Using the GUI on page 47

Advanced TabThe Advanced Tab allows you to specify additional data source settings.The fields are optional unless otherwisenoted. On this tab, provide values for the options in the following table; then, click Apply.

Figure 3: Advanced tab



DescriptionConnection Options: Advanced

Determines whether the driver creates a new schema map whenestablishing the connection.

If set to 0 - No, the driver uses the current schema map specified by theSchema Map option. If one does not exist, the connection fails.

If set to 1 - ForceNew, the driver deletes the current schema map specifiedby the Schema Map option and creates a new one at the same location.

If set to 2 - NotExist, the driver uses the current schema map specifiedby the Schema Map option. If one does not exist, the driver creates one.

Default: 2 -NotExist

Create Map on page 150

Specifies how the driver handles manual transactions.

If set to 1 - Ignore, the data source does not support transactions and thedriver always operates in auto-commit mode. Calls to set the driver tomanual commit mode and to commit transactions are ignored. Calls torollback a transaction cause the driver to return an error indicating that notransaction is started. Metadata indicates that the driver supportstransactions and the ReadUncommitted transaction isolation level.

If set to 0 - No Transactions, the data source and the driver do not supporttransactions. Metadata indicates that the driver does not supporttransactions.

Default: 0 - No Transactions

Transaction Mode on page 180

Determines whether the driver works with applications using multiple ODBCthreads.

If set to enabled, the driver works with single-threaded and multi-threadedapplications.

If set to disabled, the driver does not work with multi-threaded applications.If using the driver with single-threaded applications, this value avoidsadditional processing required for ODBC thread-safety standards.

Default: Enabled

Application Using Threads onpage 134

Determines whether the driver automatically refreshes the information ina remote schema (rebuilds the schema map for the schema) the first timea user connects to the specified embedded database.

If set to 1 (Enabled), the driver automatically refreshes the schema mapthe first time a user connects to the specified database.

If set to 0 (Disabled), the driver does not automatically refresh the schemamap the first time a user connects to the specified database.

Default: 0 (Disabled)

Refresh Schema on page 172

Specifies the number of rows that the driver processes before returningdata to the application. Smaller fetch sizes can improve the initial responsetime of the query. Larger fetch sizes improve overall fetch times at the costof additional memory.

Default: 100

Fetch Size on page 155



DescriptionConnection Options: Advanced

If enabled, the connection has read-only access.

If disabled, the connection is opened for read/write access, and you canuse all commands supported by the product.

Default: Enabled

Read Only on page 170

The number of seconds the driver waits for a connection to be establishedbefore returning control to the application and generating a timeout error.

If set to -1, the connection request does not time out. The driver silentlyignores the SQL_ATTR_LOGIN_TIMEOUT attribute.

If set to 0, the connection request does not time out, but the driver respondsto the SQL_ATTR_LOGIN_TIMEOUT attribute.

If set to x, the connection request times out after the specified number ofseconds unless the application overrides this setting with theSQL_ATTR_LOGIN_TIMEOUT attribute.

Default: 15

Login Timeout on page 163

The number of seconds the driver waits for a connection to be establishedbefore returning control to the application and generating a timeout error.

If set to 0 - Ignore Errors, the driver substitutes 0x1A for each characterthat cannot be converted and does not return a warning or error.

If set to 1 - Return Error, the driver returns an error instead of substituting0x1A for unconverted characters.

If set to 2 - Return Warning, the driver substitutes 0x1A for each characterthat cannot be converted and returns a warning.

Default: 0 - Ignore Errors

Report Codepage ConversionErrors on page 174

Specifies the filename of the configuration file used to initialize the driverlogging mechanism. If the driver cannot locate the specified file whenestablishing the connection, the connection fails and the driver returns anerror.

Default: None

Log Config File on page 162

One or multiple SQL commands to be executed by the driver after it hasestablished the connection to the database and has performed allinitialization for the connection. If the execution of a SQL command fails,the connection attempt also fails and the driver returns an error indicatingwhich SQL command or commands failed.

Default: None

Initialization String on page 159

Determines how the mapping of the native data model to the relationaldata model is configured, customized, and updated.

Default: None

Config Options on page 142



Extended Options: Type a semi-colon separated list of connection options and their values. Use thisconfiguration option to set the value of undocumented connection options that are provided by ProgressDataDirect Technical Support.You can include any valid connection option in the Extended Options string, forexample:

CreateMap=0;UndocumentedOption1=value [;UndocumentedOption2=value;]

If the Extended Options string contains option values that are also set in the setup dialog or data source, thevalues of the options specified in the Extended Options string take precedence. However, connection optionsthat are specified on a connection string override any option value specified in the Extended Options string.

If you finished configuring your driver, proceed to Step 6 on page 50 in "Configuring the Product Using theGUI." Optionally, you can further configure your driver by clicking on the following tabs. The following sectionsprovide details on the fields specific to each configuration tab:



• Web Service tab allows you to configure the behavior of communications between the driver and webservice.



See alsoConfig Options on page 142Configuring the Product Using the GUI on page 47

Security TabThe Security tab allows you to specify your security settings. The fields are optional unless otherwise noted.On this tab, provide values for the options in the following table; then, click Apply.



See "Using Security" for a general description of authentication and encryption and their configurationrequirements.

Figure 4: Security tab

DescriptionConnection Options: Security

Determines which authentication method the driver uses when establishinga connection.

If set to USERIDPASSWORD, the driver uses user ID/passwordauthentication when establishing a connection.

If set to OAUTH2.0, the driver uses OAuth 2.0 authentication whenestablishing a connection.

Default: USERIDPASSWORD

Authentication Method on page 134

Specifies the consumer key for your application.The driver uses this valuewhen authenticating to a Salesforce instance using OAuth 2.0(AuthenticationMethod=oauth2.0).

Client ID on page 140

Specifies the consumer secret for your application.This value can optionallybe specified when authenticating to a Salesforce instance using OAuth2.0 (AuthenticationMethod=oauth2.0).

Client Secret on page 141



DescriptionConnection Options: Security

Specifies the refresh token used to either request a new access token orrenew an expired access token. When the refresh token is specified, theaccess token generated at connection is used to authenticate to aSalesforce instance when OAuth 2.0 is enabled(AuthenticationMethod=oauth2.0).

Note: If a value for the Access Token option is not specified, the driveruses the value of the Refresh Token option to make a connection. If bothvalues are not specified, the driver cannot make a successful connection.If both are specified, the driver ignores the Access Token value and usesthe Refresh Token value to generate a new Access Token value.

Refresh Token on page 173

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

Note: If a value for the Access Token option is not specified, the driveruses the value of the Refresh Token option to make a connection. If bothvalues are not specified, the driver cannot make a successful connection.If both are specified, the driver ignores the Access Token value and usesthe Refresh Token value to generate a new Access Token value.

Access Token on page 133

If you finished configuring your driver, proceed to Step 6 on page 50 in "Configuring the Product Using theGUI." Optionally, you can further configure your driver by clicking on the following tabs. The following sectionsprovide details on the fields specific to each configuration tab:



• Advanced tab allows you to configure the Advanced behavior.




See alsoConfig Options on page 142Configuring the Product Using the GUI on page 47



Web Service TabThe Web Service Tab allows you to specify additional datasource settings. The fields are optional unlessotherwise noted. On this tab, provide values for the options in the following table; then, click Apply.

Figure 5: Web Service tab

DescriptionConnection Options:Security

Specifies the maximum number of Web service calls the driver can make whenexecuting 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 Web servicecalls on a single connection that can be made when executing a SQL statement.

Default: 100

Statement Call Limit on page179

Specifies the behavior of the driver when the maximum Web service call limitspecified by the Statement Call Limit option is exceeded.

If set to 1 - ErrorAlways, the driver returns an error if the maximum Web servicecall limit is exceed.

If set to 2 - ReturnResults, the driver returns any partial results it receivedprior to the call limit being exceeded. The driver generates a warning that notall of the results were fetched.

Default: 1 - ErrorAlways

Statement Call Limit Behavioron page 179



DescriptionConnection Options:Security

Specifies the number of rows of data the driver attempts to fetch for each ODBCcall.

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 specified numberof rows. Setting the value lower than 2000 can reduce the response time forreturning the initial data. Consider using a smaller WSFetch Size for interactiveapplications only.

Default: 0

WSFetch Size on page 181

The number of times the driver retries a timed-out Select request. Insert, Update,and Delete requests are never retried. The timeout period is specified by theWSTimeout (WST) connection option.

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 of times.

Default: 0

WSRetry Count on page 183

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.

Default: 120

WSTimeout on page 184

Specifies the maximum number of sessions the driver uses when multipleconnections to Salesforce are established.This allows the driver to have multipleweb service requests active when multiple ODBC connections are open, therebyimproving throughput and performance.

Note: The value specified should not exceed the number of sessions permittedby your Salesforce account.

Default: 1

WSPoolSize on page 182

If you finished configuring your driver, proceed to Step 6 on page 50 in "Configuring the Product Using theGUI". Optionally, you can further configure your driver by clicking on the following tabs. The following sectionsprovide details on the fields specific to each configuration tab:








See alsoConfiguring the Product Using the GUI on page 47

Pooling TabThe Pooling Tab allows you to specify connection pooling data source settings. The fields are optional unlessotherwise noted. On this tab, provide values for the options in the following table; then, click Apply.

See "Using DataDirect Connection Pooling" for a general description of connection pooling.

Figure 6: Pooling tab

DescriptionConnection Options:Pooling

Specifies whether to use the driver’s connection pooling.

If enabled, the driver uses connection pooling.

If disabled, the driver does not use connection pooling.

Default: Disabled

Connection Pooling on page148

If enabled, the state of connections removed from the connection pool for reuseby an application is reset to the initial configuration of the connection. Resettingthe state can negatively impact performance because additional commandsmust be sent over the network to the server to reset the state of the connection.

If disabled, the state of connections is not reset.

Default: Disabled

Connection Reset on page149



DescriptionConnection Options:Pooling

The maximum number of connections allowed within a single connection pool.When the maximum number of connections is reached, no additionalconnections can be created in the connection pool.

Default: 100

Max Pool Size on page 164

Specifies the minimum number of connections that are opened and placed ina connection pool, in addition to the active connection, when the pool is created.The connection pool retains this number of connections, even when someconnections exceed their Load Balance Timeout value.

If set to 0, no connections are opened in addition to the current existingconnection.

Default: 0

Min Pool Size on page 165

Specifies the number of seconds to keep inactive connections open in aconnection pool.

If set to 0, inactive connections are kept open.

If set to x, inactive connections are closed after the specified number of secondspasses.

Default: 0

LoadBalance Timeout onpage 162

If you finished configuring your driver, proceed to Step 6 on page 50 in "Configuring the Product Using theGUI". Optionally, you can further configure your driver by clicking on the following tabs. The following sectionsprovide details on the fields specific to each configuration tab:






See alsoUsing DataDirect Connection Pooling on page 92Configuring the Product Using the GUI on page 47

Bulk TabThe Bulk tab allows you to specify DataDirect Bulk Load data source settings. The fields are optional unlessotherwise noted. On this tab, provide values for the options in the following table; then, click Apply.



See "Using DataDirect Bulk Load" for a general description of DataDirect Bulk Load.

Figure 7: Bulk tab

DescriptionConnection Options: Bulk

Specifies whether the driver can use the Salesforce Bulk API for selects basedon the value of the Bulk Fetch Threshold connection option. If the number ofrows expected in the result set exceeds the value of Bulk Fetch Thresholdoption, the driver uses the Salesforce Bulk API to execute the select operation.Using the Salesforce Bulk API may significantly reduce the number of Webservice calls used to execute a statement and, therefore, may improveperformance.

If enabled, the driver can use the Salesforce Bulk API for selects based on thevalue of the Bulk Fetch Threshold connection option. If the number of rowsexpected in the result set exceeds the value of Bulk Fetch Threshold option,the driver uses the Salesforce Bulk API to execute the select operation.

If disabled, the driver does not use the Salesforce Bulk API, and the Bulk FetchThreshold option is ignored.

Default: Enabled

Note:

If there is a TOP or LIMIT clause in the select query, the driver considers theTOP or LIMIT clause value as the expected number of rows in the result setand compares it with the value of the Bulk Fetch Threshold option to chooseeither Bulk API or REST API for executing the select query.

If the value of TOP or LIMIT clause is greater than that of the Bulk FetchThreshold option, but the actual row count in the result set is less, theperformance of the select query might be affected adversely.

Enable Bulk Fetch on page153




Specifies whether the driver can use the Salesforce Bulk API for inserts, updates,and deletes based on the value of the Bulk Load Threshold connection option.If the number of affected rows exceeds the value of Bulk Load Threshold option,the driver uses the Salesforce Bulk API to execute the insert, update, or deleteoperation. Using the Salesforce Bulk API may significantly reduce the numberof Web service calls used to execute a statement and, therefore, may improveperformance.

If enabled, the driver can use the Salesforce Bulk API for inserts, updates, anddeletes based on the value of the Bulk Load Threshold connection option. Ifthe number of affected rows exceeds the value of Bulk Load Threshold option,the driver uses the Salesforce Bulk API to execute the insert, update, or deleteoperation.

If disabled, the driver does not use the Salesforce Bulk API, and the Bulk LoadThreshold option is ignored.

Default: Enabled

Enable Bulk Load on page154

Determines whether the driver treats bulk load operations as synchronous orasynchronous.

If disabled, bulk load operations are synchronous. The driver does not returnfrom the function that invoked an operation until the operation is complete orthe BulkLoadTimeout period has expired. If the operation times out, the driverreturns an error.

If enabled, bulk load operations are asynchronous. The driver returns from thefunction that invoked an operation after the operation is submitted to the server.The driver does not verify the completion status of the bulk load operation.

Default: Disabled

Bulk Load Asynchronous onpage 136

Determines whether multiple batches associated with a bulk load operation areprocessed by Salesforce in parallel or one at a time.

If set to 0 - Serial, multiple batches associated with a bulk load operation areprocessed one at a time.

If set to 1 - Parallel, multiple batches associated with a bulk load operation areprocessed in parallel. The order in which the batches are processed can vary.

Default: 1 - Parallel

Bulk Load ConcurrencyMode on page 137

Determines when the driver uses bulk load for insert, update, delete, or batchoperations.

If set to 0, the driver always uses bulk load to execute insert, update, delete,or batch operations.

If set to x, the driver only uses bulk load if the Enable Bulk Load option isenabled and the number of rows to be updated by an insert, update, delete, orbatch operation exceeds the threshold. If the operation times out, the driverreturns an error.

Default: 4000

Bulk Load Threshold on page139




The time, in seconds, that the driver waits for a Salesforce bulk job to complete.

A value of zero means there is no timeout.

Default: 0

Bulk Load Timeout on page140

The number of rows that the driver sends to the database at a time during bulkoperations.

Default: 1024

Bulk Load Batch Size onpage 137

Specifies the number of seconds the driver waits to request bulk operationstatus. This interval is used by the driver the first time it requests status and forall subsequent status requests.

Default: 10

Bulk Load Poll Interval onpage 138

Specifies the character that the driver will use to delimit the field entries in abulk load data file.

Default: None

Field Delimiter on page 156

Specifies the character that the driver will use to delimit the record entries in abulk load data file.

Default: None

Record Delimiter on page 171

Specifies a number of rows that, if exceeded, signals the driver to use theSalesforce Bulk API for select operations. For this behavior to take effect, theEnable Bulk Fetch option must be enabled.

Default: 30000 (rows)

Bulk Fetch Threshold onpage 135

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

If enabled, the driver uses PK chunking for select operations when the expectednumber of rows in the result set is greater than the values of the Bulk FetchThreshold and Primary Key Chunk Size options. For this behavior to take effect,the Enable Bulk Fetch option must also be enabled.

If disabled, the driver does not use PK chunking when executing selectoperations, and the Primary Key Chunk Size option is ignored.

Default: Enabled

Enable Primary KeyChunking on page 155

Specifies the size, in rows, of a primary key (PK) chunk when PK chunking hasbeen enabled via the Enable Primary Key Chunking option. The SalesforceBulk API splits the query into chunks of this size.


Primary Key Chunk Size onpage 167

If your application is already coded to use parameter array batch functionality, you can leverage DataDirectBulk Load features through the Enable Bulk Load connection option. Enabling this option automatically convertsthe parameter array batch operation to use the database bulk load protocol.



If you are not using parameter array batch functionality, you can export data to a bulk load data file, verify themetadata of the bulk load configuration file against the structure of the target table, and bulk load data to atable. Use the following steps to accomplish these tasks.

1. To export data from a table to a bulk load data file, click Export Table from the Bulk tab. The Export Tabledialog box appears.

Figure 8: ODBC Salesforce Export Table Driver Setup dialog box

Both a bulk data file and a bulk configuration file are produced by exporting a table. The configuration filehas the same name as the data file, but with an XML extension. See "Using DataDirect Bulk Load" for detailsabout these files.

The bulk export operation can create a log file and can also export to external files. See "External OverflowFiles" for more information. The export operation can be configured such that if any errors or warningsoccur:

• The operation always completes.

• The operation always terminates.

• The operation terminates after a certain threshold of warnings or errors is exceeded.

Table Name: A string that specifies the name of the source database table and, optionally, the columnscontaining the data to be exported. The driver uses the table name in the FROM clause of a SELECT *FROM tablename SQL statement. If you want to only export certain columns from your Salesforce table,then you can enter a SELECT statement in this field using the format:

(SELECT column1, column2, ... FROM tablename)

For example, to export data from the Salesforce ACCOUNT table excluding some of the audit columns,enter the following SQL in the Table Name field:

(SELECT SYS_NAME, TYPE, BILLINGSTREET, BILLINGCITY, BILLINGSTATE, BILLINGPOSTALCODE, BILLINGCOUNTRY, SHIPPINGSTREET, SHIPPINGCITY, SHIPPINGSTATE, SHIPPINGPOSTALCODE, SHIPPINGCOUNTRY, PHONE, FAX, WEBSITE, INDUSTRY, ANNUALREVENUE, NUMBEROFEMPLOYEES, DESCRIPTION FROM ACCOUNT)

Export Filename: A string that specifies the path (relative or absolute) and file of the bulk load data file towhich the data is to be exported. It also specifies the file name of the bulk configuration file. The file namemust be the fully qualified path to the bulk data file. These files must not already exist; if one of both of themalready exists, an error is returned.



Log Filename: A string that specifies the path (relative or absolute) and file name of the bulk log file. Thelog file is created if it does not exist. The file name must be the fully qualified path to the log file. Eventslogged to this file are:

• Total number of rows fetched

• A message for each row that failed to export

• Total number of rows that failed to export

• Total number of rows successfully exported

Information about the load is written to this file, preceded by a header. Information about the next load isappended to the end of the file.

If you do not supply a value for Log Filename, no log file is created.

Error Tolerance: A value that specifies the number of errors to tolerate before an operation terminates. Avalue of 0 indicates that no errors are tolerated; the operation fails when the first error is encountered.

The default of -1 means that an infinite number of errors is tolerated.

Warning Tolerance: A value that specifies the number of warnings to tolerate before an operation terminates.A value of 0 indicates that no warnings are tolerated; the operation fails when the first warning is encountered.

The default of -1 means that an infinite number of warnings is tolerated.

Code Page: A value that specifies the code page value to which the driver must convert all data for storagein the bulk data file. See "Character Set Conversions" for more information.

The default value on Windows is the current code page of the machine.

Click Export Table to connect to the database and export data to the bulk data file or click Cancel.

2. To bulk load data from the bulk data file to a database table, click Load Table from the Bulk tab. The LoadFile dialog box appears.

Figure 9: ODBC Salesforce Load File Driver Setup dialog box

The load operation can create a log file and can also create a discard file that contains rows rejected duringthe load. The discard file is in the same format as the bulk load data file. After fixing reported issues in thediscard file, the bulk load can be reissued using the discard file as the bulk load data file.



The export operation can be configured such that if any errors or warnings occur:

• The operation always completes.

• The operation always terminates.


If a load fails, the Load Start and Load Count options can be used to control which rows are loaded whena load is restarted after a failure.

Table Name: A string that specifies the name of the target database table and, optionally, the columns intowhich the data is loaded.

The fields defined in the load data file must have the same ordering of the fields defined in the Salesforcedestination table. Because Salesforce defines additional audit columns that are managed by the database,your load data file may not contain data to load into these fields.

In this case, you can specify the exact columns that you want for the data to be inserted into using a TableName string of the format:

table(column1, column2, ...)

For example, if your load data file contains only five fields of billing data that you wanted to load into theSalesforce ACCOUNT table, then the Table Name field would contain:

ACCOUNT(BILLINGSTREET, BILLINGCITY, BILLINGSTATE, BILLINGPOSTALCODE, BILLINGCOUNTRY)

Load Data Filename: A string that specifies the path (relative or absolute) and file name of the bulk datafile from which the data is loaded.

Configuration Filename: A string that specifies the path (relative or absolute) and file name of the bulkconfiguration file.

Log Filename: A string that specifies the path (relative or absolute) and file name of the bulk log file. Thefile name must be the fully qualified path to the log file. Specifying a value for Log Filename creates the fileif it does not already exist. Events logged to this file are:

• Total number of rows read

• Message for each row that failed to load

• Total number of rows that failed to load

• Total number of rows successfully loaded


If you do not specify a value for Log Filename, no log file is created.

Discard Filename: A string that specifies the path (relative or absolute) and file name of the bulk discardfile. Any row that cannot be inserted into the database as result of bulk load is added to this file, with thelast row rejected added to the end of the file.


If you do not specify a value for Discard Filename, a discard file is not created.

Error Tolerance: A value that specifies the number of errors to tolerate before an operation terminates. Avalue of 0 indicates that no errors are tolerated; the operation fails when the first error is encountered.

The default of -1 means that an infinite number of errors is tolerated.



Load Start: A value that specifies the first row to be loaded from the data file. Rows are numbered startingwith 1. For example, when Load Start is 10, the first 9 rows of the file are skipped and the first row loadedis row 10. This option can be used to restart a load after a failure.

The default value is 1.

Read Buffer Size (KB): A value that specifies the size, in KB, of the buffer that is used to read the bulkdata file for a bulk load operation.


Warning Tolerance: A value that specifies the number of warnings to tolerate before an operation terminates.A value of 0 indicates that no warnings are tolerated; the operation fails when the first warning is encountered.


Load Count: A value that specifies the number of rows to be loaded from the data file. The bulk loadoperation loads rows up to the value of Load Count from the file to the database. It is valid for Load Countto specify more rows than exist in the data file. The bulk load operation completes successfully when eitherthe number of rows specified by the Load Count value has been loaded or the end of the data file is reached.This option can be used in conjunction with Load Start to restart a load after a failure.

The default value is the maximum value for SQLULEN. If set to 0, no rows are loaded.

Click Load Table to connect to the database and load the table or click Cancel.

If you finished configuring your driver, proceed to Step 6 on page 50 in Configuring the Product Using the GUIon page 47. Optionally, you can further configure your driver by clicking on the following tabs. The followingsections provide details on the fields specific to each configuration tab:






See alsoUsing DataDirect Bulk Load on page 100External Overflow Files on page 107Character Set Conversions on page 106Configuring the Product Using the GUI on page 47

Using a Connection String

If you want to use a connection string for connecting to a database, or if your application requires it, you mustspecify either a DSN (data source name), a File DSN, or a DSN-less connection in the string. The differenceis whether you use the DSN=, FILEDSN=, or the DRIVER= keyword in the connection string, as described inthe ODBC specification. A DSN or FILEDSN connection string tells the driver where to find the default connectioninformation. Optionally, you may specify attribute=value pairs in the connection string to override the defaultvalues stored in the data source.

The DSN connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...]



The FILEDSN connection string has the form:

FILEDSN=filename.dsn[;attribute=value[;attribute=value]...]

The DSN-less connection string specifies a driver instead of a data source. All connection information mustbe entered in the connection string because the information is not stored in a data source.

The DSN-less connection string has the form:

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value]...]

"Connection Option Descriptions" lists the long and short names for each attribute, as well as the initial defaultvalue when the driver is first installed.You can specify either long or short names in the connection string.

An example of a DSN connection string with overriding attribute values for Salesforce for Linux/UNIX/Windowsis:

DSN=Salesforce;UID=JOHN;PWD=XYZZY

A FILEDSN connection string is similar except for the initial keyword:

FILEDSN=Salesforce;UID=JOHN;PWD=XYZZY

A DSN-less connection string must provide all necessary connection information:

DRIVER=DataDirect 8.0 Salesforce;UID=JohnQPublic;PWD=XYZZY;HOST=login.salesforce.com;SM=C:\Users\Default\AppData\Local\Progress\DataDirect\Salesforce Schema\JohnQPublic.config;SecurityToken=XaBARTsLZReM4Px47qPLOS


Using a Logon Dialog Box

Some ODBC applications display a logon dialog box when you are connecting to a data source. In these cases,the host name has already been specified.

Figure 10: Logon to Salesforce dialog box

In this dialog box, provide the following information:

1. In the Host Name field, type the URL or the IP address of the Salesforce instance to which you want toconnect.

2. Optionally, in the Schema Map field, type the name and location of the configuration file where the relationalmap of native data is written.

3. In the User Name field, type the default user ID and domain that is used to connect to your Salesforceinstance. For example, [email protected]



4. In the Password field, type the password that is used to connect to your Salesforce instance.

5. Click OK to complete the logon.

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

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 Proxy Host, Proxy Port, Proxy User, and Proxy Password connection attributes.See "Connection Option Descriptions" for details about these attributes.


Performance ConsiderationsApplication Using Threads (ApplicationUsingThreads): The driver coordinates concurrent databaseoperations (operations from different threads) by acquiring locks. Although locking prevents errors in the driver,it also decreases performance. If your application does not make ODBC calls from different threads, the driverhas no reason to coordinate operations. In this case, the ApplicationUsingThreads attribute should be disabled(set to 0).

Note: If you are using a multi-threaded application, you must enable the Application Using Threads option.


Connecting Through a Proxy Server

Connection Pooling (Pooling): If you enable the driver to use connection pooling, you can set additionaloptions that affect performance:

• Load Balance Timeout (LoadBalanceTimeout):You can define how long to keep connections in the pool.The time that a connection was last used is compared to the current time and, if the timespan exceeds thevalue of the Load Balance Timeout option, the connection is destroyed.The Min Pool Size option can causesome connections to ignore this value.

• Connection Reset (ConnectionReset ): Resetting a re-used connection to the initial configuration settingsimpacts performance negatively because the connection must issue additional commands to the server.

• Max Pool Size (MaxPoolSize): Setting the maximum number of connections that the pool can contain toolow might cause delays while waiting for a connection to become available. Setting the number too highwastes resources.

• Min Pool Size (MinPoolSize ): A connection pool is created when the first connection with a uniqueconnection string connects to the database.The pool is populated with connections up to the minimum poolsize, if one has been specified. The connection pool retains this number of connections, even when someconnections exceed their Load Balance Timeout value.

Enable Bulk Fetch (EnableBulkFetch): The Enable Bulk Fetch option can be used to improve performanceby enabling the driver to use the Salesforce Bulk API for selects. Using the Salesforce Bulk API may significantlyreduce the number of Web service calls used to execute a statement and, therefore, may improve performance.When Enable Bulk Fetch is set to 1 (enabled), the driver uses the Salesforce Bulk API based on the value ofthe Bulk Fetch Threshold connection option. If the number of rows expected in the result set exceeds the valueof Bulk Fetch Threshold option, the driver uses the Salesforce Bulk API to execute the select operation.

Note:

If there is a TOP or LIMIT clause in the select query, the driver considers the TOP or LIMIT clause value asthe expected number of rows in the result set and compares it with the value of the Bulk Fetch Threshold optionto choose either Bulk API or REST API for executing the select query.

If the value of TOP or LIMIT clause is greater than that of the Bulk Fetch Threshold option, but the actual rowcount in the result set is less, the performance of the select query might be affected adversely.

Enable Bulk Load (EnableBulkLoad): The Enable Bulk Load option can be used to improve performance byenabling the driver to use the Salesforce Bulk API for inserts, updates, and deletes. Using the Salesforce BulkAPI may significantly reduce the number of Web service calls used to execute a statement and, therefore, mayimprove performance. When Enable Bulk Load is set to 1 (enabled), the driver uses the Salesforce Bulk APIbased on the value of the Bulk Load Threshold connection option. If the number of affected rows exceeds thevalue of Bulk Load Threshold option, the driver uses the Salesforce Bulk API to execute the insert, update, ordelete operation.

Enable Primary Key Chunking (EnablePKChunking):The Enable Primary Key Chunking option can be usedto improve performance by enabling the driver to use PK chunking for bulk fetch operations. When EnablePrimary Key Chunking is set to 1(enabled), the driver uses PK chunking to execute the select operations if theexpected number of rows in the result set is greater than the values of the Bulk Fetch Threshold and PrimaryKey Chunk Size options. For this behavior to take effect, the Enable Bulk Fetch option must also be set to 1(enabled).

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 chunkingis supported for sharing objects as long as the parent object is supported.

Fetch Size/WS Fetch Size (FetchSize/WSFetchSize): The connection options Fetch Size and WSFetch Sizecan be used to adjust the trade-off between throughput and response time. In general, setting larger valuesfor WSFetch Size and Fetch Size 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 WSFetch Sizeis set to 500, the driver must make 200 Web service calls to get the 100,000 rows. If, however, WSFetch Sizeis 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 Fetch Size to 50 (the numberof rows displayed on a page) and WSFetch Size 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.

WSPoolSize (WSPoolSize)PK chunking is supported for all custom objects and the: WSPoolSize determinesthe maximum number of sessions the driver uses when there are multiple active connections to Salesforce.By increasing this number, you increase the number of sessions the driver uses to distribute calls to Salesforce,thereby improving throughput and performance. For example, if WSPoolSize is set to 1, and you have twoopen connections, the session must complete a call from one connection before it can begin processing a callfrom the other connection. However, if WSPoolSize is equal to 2, a second session is opened that allows callsfrom both connections to be processed simultaneously.

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

Using the SQL Engine ServerSome applications may experience problems loading the JVM required for the SQL engine because the processexceeds the available heap space. If your application experiences problems loading the JVM, you can configurethe driver to operate in server mode.

In direct mode, the driver operates with the SQL engine and JVM running in a single process. While in servermode, the driver's SQL engine runs in a separate process with its own JVM instead of trying to load the SQLengine and JVM in the same process used by the driver.

For Windows, the driver is configured to attempt to run in server mode first by default. However, if server modeis unavailable, the SQL engine will failover to run in direct mode. For non-Windows platforms, the driver operatesin direct mode by default.

Note: You must be an administrator to start or stop the service, or to configure any settings for the service.

See the following sections for details on configuring the SQL Engine Server on your platform.

Configuring the SQL Engine Server on Windows

The following sections describe how to configure, start, and stop the SQL Engine Server on Windows platforms.

On Windows, the driver is configured to run in Auto mode by default. This means that driver attempts to run inserver mode first; however, if server mode is unavailable, the SQL engine will failover to run in direct mode.


Using the SQL Engine Server

Configuring Server Mode

1. Set the SQL Engine Mode connection option to a value of 0 - Auto or 1 - Server. All fields on the SQLEngine tab become read only, and the Edit Server Settings button appears.

Note: Server mode is enabled when the SQL Engine Mode connection option is set to 0 - Auto or 1- Server.When set 0 - Auto, the SQL engine attempts to run in server mode first, but will failover to direct mode ifserver mode is unavailable. When set to 1 - Server, the SQL engine mode runs exclusively in server mode.

2. Click Edit Server Setting to display the ODBC Salesforce SQL Engine Service Setup dialog box. Use thisdialog box to define settings for Server Mode and to start and stop the Progress DataDirect Salesforce SQLEngine service.

The SQL Engine Service Setup dialog box appears.

JVM Arguments: A string that contains the arguments that are passed to the JVM that the driver is starting.The location of the JVM must be specified on your PATH. See "JVM Arguments."

JVM Class Path: Specifies the CLASSPATH for the JVM used by the driver. See "JVM Classpath."

Server Port Number: Specifies a valid port on which the SQL engine listens for requests from the driver.By default, the server listens on port 19937 for 64-bit installations and 19938 for 32-bit installations.. See"Server Port Number" for more information.

Java Path: Specifies fully qualified path to the Java SE 8 or higher JVM executable that you want to useto run the SQL Engine Server. The path must not contain double quotation marks.

Services: Shows the Salesforce ODBC SQL engine service that runs as a separate process instead ofbeing loaded within the process of an ODBC application.



Start (Stop): Starts or stops the Salesforce service. A message window is displayed, confirming that theSalesforce service was started or stopped.

Apply: Applies the changes.

3. When you complete your changes, click Apply.

4. Click OK to save the changes and return to the SQL Engine tab or click Cancel.

See alsoJVM Arguments on page 160JVM Classpath on page 161Server Port Number on page 177

Starting the SQL Engine ServerIn server mode, you must start the SQL engine server before using the driver. Before starting the SQL engineserver, choose a directory to store the local database files. Make sure that you have the correct permissionsto write to this directory.

By default, the JVM Classpath is set to the sforce.jar file in the installation directory.

To start the SQL engine server:

1. Start the ODBC Administrator by selecting its icon from the Progress DataDirect for ODBC program group.

2. Select a tab:

• User DSN: If you are configuring an existing user data source, select the data source name and clickConfigure to display the driver Setup dialog box.

If you are configuring a new user data source, click Add to display a list of installed drivers. Select the driverand click Finish to display the driver Setup dialog box.

• System DSN: If you are configuring an existing system data source, select the data source name andclick Configure to display the driver Setup dialog box.

If you are configuring a new system data source, click Add to display a list of installed drivers. Select thedriver and click Finish to display the driver Setup dialog box.

• File DSN: If you are configuring an existing file data source, select the data source file and click Configureto display the driver Setup dialog box.

If you are configuring a new file data source, click Add to display a list of installed drivers; then, select adriver. Click Advanced if you want to specify attributes; otherwise, click Next to proceed. Specify a namefor the data source and click Next.Verify the data source information; then, click Finish to display the driverSetup dialog box.

3. On the ODBC Salesforce Driver Setup dialog box, select the SQL Engine tab; then, select 0 - Auto or 1-Server from the SQL Engine Mode drop-down list.

Note: Server mode is enabled when the SQL Engine Mode connection option is set to 0 - Auto or 1- Server.When set 0 - Auto, the SQL engine attempts to run in server mode first, but will failover to direct mode ifserver mode is unavailable. When set to 1 - Server, the SQL engine mode runs exclusively in server mode.

4. Click Edit Server Settings.

5. When you complete your changes, click Apply.



6. Verify that Progress DataDirect Salesforce SQL Engine is selected in the Services drop-down list, and then,click Start to start the service. A message window appears to confirm that the service is running. Click OK.

7. Click OK to close the ODBC Salesforce SQL Engine Service Setup dialog box.

Note: If you made changes after starting the service, a message window is displayed:

If you want the service to run with the new settings, click No. Then, click Stop to stop the service, and thenclick Start to restart the service. Then, click OK to close the ODBC Salesforce SQL Engine Service Setupdialog box.

Stopping the SQL Engine ServerTo stop the SQL engine server:

1. Open the ODBC Salesforce Driver Setup dialog box and select the SQL Engine tab.

2. Select 0 - Auto or 1 - Server from the SQL Engine Mode drop-down list. Then, click Edit Server Settings.

Note: Server mode is enabled when the SQL Engine Mode connection option is set to 0 - Auto or 1 -Server. When set 0 - Auto, the SQL engine attempts to run in server mode first, but will failover to directmode if server mode is unavailable.When set to 1 - Server, the SQL engine mode runs exclusively in servermode.

3. Click Stop to stop the service. A message window appears to confirm that the service is stopped. Click OK.

4. Click OK to close the ODBC Salesforce SQL Engine Service Setup dialog box.

Configuring the SQL Engine Server on UNIX/Linux

The following sections describe how to configure, start, and stop the SQL Engine Server on UNIX and Linuxplatforms.

By default, the driver operates in direct mode by default on UNIX and Linux platforms.

Configuring and Starting the SQL Engine Server on UNIX/LinuxIn server mode, you must start the SQL engine server before using the driver. Before starting the SQL engineserver, verify that you have the correct permissions to write to the directory specified by the SchemaMap option.

To configure the SQL engine server, specify values for the Java options in the following JVM argument to suityour environment. See the "SQL Engine Server Java Options" table for a description of these options.

java -Xmx<heap_size>m -cp "<jvm_classpath>" com.ddtek.phoenix.sql.Server -port <port_number> -Dhttp.proxyHost=<proxy_host> -Dhttp.proxPort=<proxy_port>-Dhttp.proxyUser=<proxy_user> -Dhttp.proxyPassword=<proxy_password>



For example:

java -Xmx1024m -cp "/opt/Progress/DataDirect/ODBC_80_64bit/java/lib/sforce.jar" com.ddtek.phoenix.sql.Server -port 19938 [email protected] -Dhttp.proxPort=12345 -Dhttp.proxyUser=JohnQPublic -Dhttp.proxyPassword=secret

To start the SQL engine service, execute the JVM Argument after configuring the Java options. A confirmationmessage is returned once the server is online.

Table 6: SQL Engine Server Java Options

DescriptionJava Option

Required Java Options

Specifies the CLASSPATH for the Java Virtual Machine (JVM) used by the driver.The CLASSPATH is the search string the JVM uses to locate the Java jar files thedriver needs. The Salesforce driver's JVM is located on the following path:

install_dir/java/lib/sforce.jar

-cp

Specifies a valid port on which the SQL engine listens for requests from the driver.We recommend specifying one of the following values:

• 19938 (32-bit drivers)

• 19937 (64-bit drivers)

-port

Optional Java Options

Specifies the maximum memory heap size, in megabytes, for the JVM. The defaultsize is determined by your JVM. We recommend specifying a size no smaller than1024.

Note: Although this option is not required to start the SQL engine server, we highlyrecommend specifying a value.

-Xmx

Specifies the Hostname of the Proxy Server. The value specified can be a hostname, a fully qualified domain name, or an IPv4 or IPv6 address.

-Dhttp.proxyHost

Specifies the port number where the Proxy Server is listening for HTTP and/orHTTPS requests.

-Dhttp.proxyPort

Specifies the user name needed to connect to the Proxy Server.-Dhttp.proxyUser

Specifies the password needed to connect to the Proxy Server.-Dhttp.proxyPassword

Stopping the SQL Engine ServerTo stop the SQL engine server, choose one of the following:

• Using an application, execute SHUTDOWN SQL.

• From a command line, press Ctrl + C.



A message is returned to confirm that the service is stopped.

Configuring Java Logging for the SQL Engine Server

Java logging can be configured by placing a logging configuration file named ddlog.properties in thedirectory specified by the Schema Map option. The simple way to create one of these is to make a copy of theddlog.properties file, which is located in your driver installation directory, in theinstall_dir/Sample/Example subdirectory. For more information on logging in Salesforce, see "ConfiguringLogging".

See alsoSchema Map on page 175Configuring Logging on page 119

Using 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. Cachingdata on a table level allows the caches to be queried, filtered, and sorted in other queries. Once a cache iscreated, its use is transparent to the application. For example, if a cache is created on the Account table, thenall subsequent queries that reference Account access the Account cache. Disabling or dropping the cacheallows references to the Account table to access the remote data again. Because the use of the cache istransparent, no changes to the application are required to take advantage of the cache.

You must specifically create a cache before it can be populated; caches are not created automatically. Afteryou have created a cache on a table, the cache will be 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 storedlocally in the cache 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 as much as possible.

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

• Create Cache

• Alter Cache

• Refresh Cache

• Drop Cache

See the following sections for overviews of each extension. Refer to "SQL Statements and Extensions" fordescriptions of the syntax of these extensions.



See alsoSupported SQL Statements and Extensions on page 185

Creating a Cache

You create a cache using the Create Cache statement (refer to "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 can optionally specify a filter for the table. The filter determines whether the cacheholds all of the data in the remote table or a subset of the data that matches the filter.You can also specifyattributes for the Create Cache statement that determine:

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

• How often the cache data is refreshed

• Whether the cache is initially enabled

• Whether 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, you might have three tables, Account,Contact, and Opportunity, where both a contact and an opportunity belong to a particular account. Using arelational cache, you could specify that accounts that have had activity in the past year be cached, as well ascaching the opportunities and contacts for only those cached accounts.

See alsoCreate Cache (EXT) on page 196

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 186


Using Client-Side Caches

Disabling and Enabling a Cache

When 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. For example, assume that a cache was created on Account with a filter set to cacheaccounts that have had activity in the past year.You may want to run a query to get information about anaccount that has not been active for two years. One alternative would be to drop the Account cache, run thequery, and then recreate the cache on Account, but this can be problematic. First, you must recreate the cacheand make sure it had the same attributes as before. Second, the data in the cache is discarded and needs tobe refetched when the cache is recreated. Depending on the amount of cached data, this could take a significantamount of time. To address this type of issue, the Salesforce driver can temporarily disable a cache. When acache is disabled, its definition and data are maintained. Any queries that reference a table with a disabledcache access the remote table. When you want to access cached data again, the cache can be enabled.

Refreshing Cache Data

To 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 223SYSTEM_CACHES Catalog Table on page 81



Dropping a Cache

You can drop an existing cache using the Drop Cache statement (refer to "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 of the data in that cache is discarded.

See alsoDrop Cache (EXT) on page 218

Cache MetaData

The Salesforce driver maintains information about the caches that have been created. The driver provides twosystem tables to expose the cache information, the SYSTEM_CACHES table and theSYSTEM_CACHE_REFERENCES table.

The SYSTEM_CACHES and SYSTEM_CACHE_REFERENCES system tables exist in theINFORMATION_SCHEMA schema. See "Catalog Tables" for a complete description of the contents of thesesystem tables.

See alsoCatalog Tables on page 81

Catalog TablesThe Salesforce driver provides a standard set of catalog tables that maintain the information returned by variousODBC catalog functions such as SQLTables, SQLColumns, SQLDescribeParam and SQLDescribeCol. Ifpossible use the ODBC catalog functions to obtain this information instead of querying the catalog tablesdirectly.

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").

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


Catalog Tables

Table 7: 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),NOTNULL

CACHE_TYPE

The refresh interval (in minutes).INTEGER,NOTNULL

REFRESH_INTERVAL

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

VARCHAR(20),NOTNULL

INITIAL_CHECK

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

VARCHAR(20),NOTNULL

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 been created, but the data has not beenpopulated.

Initialized: The cache has been created and the datahas been populated.

Load aborted: The cache has been created, but the lastattempt to populate the data failed. The cache is still valid.The next access attempts to populate the data again.

Invalid: The cache is invalid. The second attempt topopulate the data failed.

Dirty: An insert or update operation has been performedon the cache and the cache has not been refreshed.

VARCHAR(30)STATUS

See alsoSYSTEM_CACHE_REFERENCES Catalog Table on page 83

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_CACHES table, which is sorted on the followingcolumns: TABLE_SCHEMA, TABLE_NAME, and REF_TABLE_NAME.

Table 8: SYSTEM_CACHE_REFERENCES


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


Catalog Tables

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.

VARCHAR(128),NOT NULL

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 9: 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 havemultiple instances.

The Salesforce value for INSTANCE has thefollowing 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 towhich the session is connected.

For Salesforce, this is the version of the WebService API the driver is using to connect toSalesforce.


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 informationneeded to log into the remote data source.The password value is not displayed.

LONGVARCHAR,NOT NULL

SESSION_OPTIONS

The number of Web service calls madethrough this remote session.The value of theWS_CALL_COUNT column can be resetusing the 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_SESSIONINFO Catalog Table

The system table named SYSTEM_SESSIONINFO describes details about your connection to Salesforce.


Catalog Tables

The following table defines the keys for the SYSTEM_SESSIONINFO table. The values change based on yourdata source settings.

Table 10: SYSTEM_SESSIONINFO Catalog Table

DescriptionKey

Autocommit is always enabled.AUTOCOMMIT

The location and the filename prefix for the datamapping and configuration files.

DATABASE

Indicates whether the database the session isconnected to is read only.

DATABASE_ READONLY

The fully qualified path to the directory or folder thatcontains the database and mapping files.

DB_FILE_LOCATION

The filename prefix of the database and mapping filesthe driver is using.

DB_FILE_PREFIX

Currently always zero.IDENTITY

Currently always zero.MAXROWS

The fully qualified path to the directory or folder thatcontains the logging configuration file.

LOG_CONFIG_FILE

The name of the remote Salesforce schema.SCHEMA

The ID for this session.SESSION_ID

Indicates whether the session is read only.SESSION_READONLY

The user that is associated with this session.USER

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.

Table 11: SYSTEM_SESSIONS


A unique ID that identifies thissession. The system functionCURSESSIONID( ) returns thesession ID associated with theconnection. See "Scalar Functions"for details on CURSESSIONID().

INTEGER, NOT NULLSESSION_ID

The date and time the session wasestablished.

DATETIME, NOT NULLCONNECTED

The name of the schema map thatthe session is using.

VARCHAR (128), NOT NULLUSER_NAME

For internal use only.BOOLEANIS_ADMIN

For future use.BOOLEAN, NOT NULLAUTOCOMMIT

True if the connection is inread-only mode. The READONLYstatus is based on whether theconnection has been explicitly setto read-only mode by the Read Onlyconnection option.

BOOLEAN, NOT NULLREADONLY

For future use.INTEGER, NOT NULLMAXROWS

For future use.BIGINT, NULLABLELAST_IDENTITY

For future use.INTEGER, NOT NULLTRANSACTION_SIZE

The current schema for the session.The current schema may bechanged using the ALTERSESSION SETCURRENT_SCHEMA statement.

VARCHAR (128), NOT NULLCURRENT_SCHEMA

The maximum number of Webservice calls that the driver uses inattempting to execute a query to aremote data source. The statementcall limit for the session may bechanged via the ALTER SESSIONSET STMT_CALL_LIMIT statement.

INTEGER, NOT NULLSTMT_CALL_LIMIT

See alsoScalar Functions on page 259


Catalog Tables

Using ReportsThe Salesforce driver exposes reports defined on a Salesforce instance as stored procedures. An applicationcan obtain a list of the reports defined on a Salesforce instance by calling the SQLProcedures catalog function.The names of the reports that can be invoked through the driver are listed in the PROCEDURE_NAME namecolumn of the SQLProcedures results.

Salesforce organizes reports into folders. The Salesforce driver incorporates the folder name and report nameinto the procedure name reported by SQLProcedures. The driver creates the reported procedure name byprepending the folder name to the report name using an underscore to join them. Additionally, any spaces inthe report or folder names are replaced with an underscore character. Like all identifier name metadata returnedby the driver, the procedure name is uppercase. For example, if a report named Opportunity Pipeline is in thefolder Opportunity Reports, it would be rendered as:

OPPORTUNITY_REPORTS_OPPORTUNITY_PIPELINE

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

SQLRETURN retVal;HSTMT hStmt = NULL;SQLWCHAR* sql;sql = L"{call OPPORTUNITY_REPORTS_OPPORTUNITY_PIPELINE}";retVal = SQLExecDirect(hStmt, sql, SQL_NTS);if (SQL_SUCCESS == retVal) { // process results}

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.

Using SecurityThe driver supports the data encryption security feature, which converts data into a form that cannot be easilyunderstood by unauthorized users.

For current information, refer to the security matrix on the Progress DataDirect Web site:

Progress DataDirect Security Support Matrix

Authentication

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

The Salesforce driver supports the following methods of authentication:



https://documentation.progress.com/output/DataDirect/securitymatrix/

• 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 alsoSecurity Tab on page 56

Configuring OAuth 2.0 authenticationThe 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 options:

• Set the Authentication Method option to oauth2.0.

• Set at least one of the following options:

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

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

If a value for the Access Token option is not specified, the driver uses the value of the Refresh Token optionto make a connection. If both values are not specified, the driver cannot make a successful connection. Ifboth are specified, the driver ignores the Access Token value and uses the Refresh Token value to generatea new Access Token value.

• Set the Client ID option to specify the consumer key for your application.

• Set the Schema Map option 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 Schema Map optionmust be specified every time you authenticate to a Salesforce instance using OAuth 2.0.

• Optionally, set the Client Secret option to specify the consumer secret for your application.

The following examples show how to connect to a Salesforce instance using OAuth2.0 authentication.

Using a connection string:

DRIVER=DataDirect 8.0 Salesforce;AuthenticationMethod=oauth2.0;SchemaMap=ABC;clientId=RaARBTsXZTeN4Qx67qPLOS;RefreshToken=YaTARBsRZLeM4Px47qSOLP;AccessToken=ZbTARBsRZLeM4Px56qOLPS

Using the odbc.ini file:

Driver=ODBCHOME/lib/xxsfrc28.yyAuthenticationMethod=oauth2.0SchemaMap=ABCclientId=RaARBTsXZTeN4Qx67qPLOSRefreshToken=YaTARBsRZLeM4Px47qSOLPAccessToken=ZbTARBsRZLeM4Px56qOLPS

See alsoAuthentication Method on page 134Access Token on page 133


Using Security

Refresh Token on page 173Client ID on page 140Schema Map on page 175Client Secret on page 141

Data Encryption Across the Network

If your database connection is not configured to use data encryption, data is sent across the network in a formatthat is designed for fast transmission and can be decoded by interceptors, given some time and effort. Forexample, text data is often sent across the wire as clear text. Because this format does not provide completeprotection from interceptors, you may want to use data encryption to provide a more secure transmission ofdata.

For example, you may want to use data encryption in the following scenarios:

• You have offices that share confidential information over an intranet.

• You send sensitive data, such as credit card numbers, over a database connection.

• You need to comply with government or industry privacy and security requirements.

Your Progress DataDirect for ODBC driver supports Secure Sockets Layer (SSL). SSL is an industry-standardprotocol for sending encrypted data over database connections. SSL secures the integrity of your data byencrypting information and providing client/server authentication.

Note: Data encryption may adversely affect performance because of the additional overhead (mainly CPUusage) required to encrypt and decrypt data.

SSL Encryption

SSL works by allowing the client and server to send each other encrypted data that only they can decrypt. SSLnegotiates the terms of the encryption in a sequence of events known as the SSL handshake. During thehandshake, the driver negotiates the highest SSL/TLS protocol available.The result of this negotiation determinesthe encryption cipher suite to be used for the SSL session.

The encryption cipher suite defines the type of encryption that is used for any data exchanged through an SSLconnection. Some cipher suites are very secure and, therefore, require more time and resources to encryptand decrypt data, while others provide less security, but are also less resource intensive.

The handshake involves the following types of authentication:

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

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

Note: The version of SSL that is used and which SSL cryptographic algorithm is used depends on which JVMyou are using. Refer to your JVM documentation for more information about its SSL support.



CertificatesSSL requires the use of a digitally-signed document, an x.509 standard certificate, for authentication and thesecure exchange of data. The purpose of this certificate is to tie the public key contained in the certificatesecurely to the person/company that holds the corresponding private key.Your Progress DataDirect for ODBC

drivers supports many popular formats. Supported formats include:

• DER Encoded Binary X.509

• Base64 Encoded X.509

• PKCS #12 / Personal Information Exchange

SSL Server AuthenticationWhen the client makes a connection request, the server presents its public certificate for the client to acceptor deny. The client checks the issuer of the certificate against a list of trusted Certificate Authorities (CAs) thatresides in an encrypted file on the client known as a truststore. If the certificate matches a trusted CA in thetruststore, an encrypted connection is established between the client and server. If the certificate does notmatch, the connection fails and the driver generates an error.

Most truststores are password-protected. The driver must be able to locate the truststore and unlock thetruststore with the appropriate password. Two connection string attributes are available to the driver to providethis information: TrustStore and TrustStorePassword. The value of TrustStore is a pathname that specifies thelocation of the truststore file.The value of TrustStorePassword is the password required to access the contentsof the truststore.

Alternatively, you can configure the driver to trust any certificate sent by the server, even if the issuer is not atrusted CA. Allowing a driver to trust any certificate sent from the server is useful in test environments becauseit eliminates the need to specify truststore information on each client in the test environment.ValidateServerCertificate, another connection string attribute, allows the driver to accept any certificate returnedfrom the server regardless of whether the issuer of the certificate is a trusted CA.

Finally, the connection string attribute, HostNameInCertificate, allows an additional method of server verification.When a value is specified for HostNameInCertificate, it must match the host name of the server, which hasbeen established by the SSL administrator. This prevents malicious intervention between the client and theserver and ensures that the driver is connecting to the server that was requested.

SSL Client AuthenticationIf the server is configured for SSL client authentication, the server asks the client to verify its identity after theserver identity has been proven. Similar to server authentication, the client sends a public certificate to theserver to accept or deny. The client stores its public certificate in an encrypted file known as a keystore. Publiccertificates are paired with a private key in the keystore. To send the public certificate, the driver must accessthe private key.

Like the truststore, most keystores are password-protected. The driver must be able to locate the keystore andunlock the keystore with the appropriate password. Two connection string attributes are available to the driverto provide this information: KeyStore and KeyStorePassword.The value of KeyStore is a pathname that specifiesthe location of the keystore file.The value of KeystorePassword is the password required to access the keystore.

The private keys stored in a keystore can be individually password-protected. In many cases, the same passwordis used for access to both the keystore and to the individual keys in the keystore. It is possible, however, thatthe individual keys are protected by passwords different from the keystore password.The driver needs to knowthe password for an individual key to be able to retrieve it from the keystore. An additional connection stringattribute, KeyPassword, allows you to specify a password for an individual key.


Using Security

Summary of Security-Related Options

The following table summarizes how security-related connection options work with the drivers. See "ConnectionOption Descriptions" for details about configuring the options.

Table 12: Summary: Security Connection Options

DescriptionOption

Specifies the security token required to make a connection to a Salesforceinstance that is configured for a security token. If a security token is required andyou do not supply one, the driver returns an error indicating that an invalid useror password was supplied. Contact your Salesforce administrator to find out if asecurity token is required.

Default: None

Security Token(SecurityToken)

The default user ID and domain used to connect to your database. For example,[email protected].

Default: None

User Name (LogonID)


Using DataDirect Connection PoolingConnection pooling allows you to reuse connections rather than creating a new one every time the driver needsto establish a connection to the underlying database.Your Progress DataDirect for ODBC driver enables connectionpooling without requiring changes to your client application.

Note: Connection pooling works only with connections that are established using SQLConnect orSQLDriverConnect with the SQL_DRIVER_NO_PROMPT argument and only with applications that arethread-enabled.

DataDirect connection pooling that is implemented by the DataDirect driver is different than connection poolingimplemented by the Windows Driver Manager. The Windows Driver Manager opens connections dynamically,up to the limits of memory and server resources. DataDirect connection pooling, however, allows you to controlthe number of connections in a pool through the Min Pool Size (minimum number of connections in a pool)and Max Pool Size (maximum number of connections in a pool) connection options. In addition, DataDirectconnection pooling is cross-platform, allowing it to operate on UNIX and Linux. See "Connection OptionDescriptions" for details about how the connection options manage DataDirect connection pooling.

Important: On a Windows system, do not use both Windows Driver Manager connection pooling and DataDirectconnection pooling at the same time.




Creating a Connection Pool

Each connection pool is associated with a specific connection string. By default, the connection pool is createdwhen the first connection with a unique connection string connects to the data source. The pool is populatedwith connections up to the minimum pool size before the first connection is returned. Additional connectionscan be added until the pool reaches the maximum pool size. If the Max Pool Size option is set to 10 and allconnections are active, a request for an eleventh connection has to wait in queue for one of the 10 poolconnections to become idle. The pool remains active until the process ends or the driver is unloaded.

If a new connection is opened and the connection string does not exactly match an existing pool, a new poolmust be created. By using the same connection string, you can enhance the performance and scalability ofyour application.

Adding Connections to a Pool

A connection pool is created in the process of creating each unique connection string that an application uses.When a pool is created, it is populated with enough connections to satisfy the minimum pool size requirement,set by the Min Pool Size connection option. The maximum pool size is set by the Max Pool Size connectionoption. If an application needs more connections than the number set by Min Pool Size, The driver allocatesadditional connections to the pool until the number of connections reaches the value set by Max Pool Size.

Once the maximum pool size has been reached and no usable connection is available to satisfy a connectionrequest, the request is queued in the driver.The driver waits for the length of time specified in the Login Timeoutconnection option for a usable connection to return to the application. If this time period expires and a connectionhas not become available, the driver returns an error to the application.

A connection is returned to the pool when the application calls SQLDisconnect.Your application is stillresponsible for freeing the handle, but this does not result in the database session ending.

Removing Connections from a Pool

A connection is removed from a connection pool when it exceeds its lifetime as determined by the Load BalanceTimeout connection option. In addition, DataDirect has created connection attributes described in the followingtable to give your application the ability to reset connection pools. If connections are in use at the time of thesecalls, they are marked appropriately. When SQLDisconnect is called, the connections are discarded insteadof being returned to the pool.


Using DataDirect Connection Pooling

Table 13: Pool Reset Connection Attributes

DescriptionConnection Attribute

Calling SQLSetConnectAttr (SQL_ATTR_CLEAR_POOLS,SQL_CLEAR_ALL_CONN_POOL) clears all the connectionpools associated with the driver that created theconnection.This is a write-only connection attribute.The driverreturns an error if SQLGetConnectAttr(SQL_ATTR_CLEAR_POOLS) is called.

SQL_ATTR_CLEAR_POOLS Value:SQL_CLEAR_ALL_CONN_POOL

Calling SQLSetConnectAttr (SQL_ATTR_CLEAR_POOLS,SQL_CLEAR_CURRENT_CONN_POOL) clears theconnection pool that is associated with the currentconnection.This is a write-only connection attribute.The driverreturns an error if SQLGetConnectAttr(SQL_ATTR_CLEAR_POOLS) is called.

SQL_ATTR_CLEAR_POOLS Value:SQL_CLEAR_CURRENT_CONN_POOL

Note: By default, if removing a connection causes the number of connections to drop below the numberspecified in the Min Pool Size option, a new connection is not created until an application needs one.

Handling Dead Connections in a Pool

What happens when an idle connection loses its physical connection to the database? For example, supposethe database server is rebooted or the network experiences a temporary interruption. An application thatattempts to connect could receive errors because the physical connection to the database has been lost.

Your Progress DataDirect for ODBC driver handles this situation transparently to the user. The application doesnot receive any errors on the connection attempt because the driver simply returns a connection from aconnection pool. The first time the connection handle is used to execute a SQL statement, the driver detectsthat the physical connection to the server has been lost and attempts to reconnect to the server before executingthe SQL statement. If the driver can reconnect to the server, the result of the SQL execution is returned to theapplication; no errors are returned to the application.

The driver uses connection failover option values, if they are enabled, when attempting this seamlessreconnection; however, it attempts to reconnect even if these options are not enabled. See for informationabout configuring the driver to connect to a backup server when the primary server is not available.

Note: If the driver cannot reconnect to the server (for example, because the server is still down), an error isreturned indicating that the reconnect attempt failed, along with specifics about the reason the connectionfailed.

The technique that Progress DataDirect uses for handling dead connections in connection pools allows formaximum performance of the connection pooling mechanism. Some drivers periodically test the server with adummy SQL statement while the connections sit idle. Other drivers test the server when the application requeststhe use of the connection from the connection pool. Both of these approaches add round trips to the databaseserver and ultimately slow down the application during normal operation.



Connection Pool Statistics

Progress DataDirect has created a connection attribute to monitor the status of the DataDirect for ODBC connectionpools. This attribute, which is described in the following table, allows your application to fetch statistics for thepool to which a connection belongs.

Table 14: Pool Statistics Connection Attribute

DescriptionConnection Attribute

Calling SQLGetConnectAttr (SQL_ATTR_POOL_INF,SQL_GET_POOL_INFO) returns a PoolInfoStruct that contains thestatistics for the connection pool to which this connection belongs.This PoolInfoStruct is defined in qesqlext.h. Forexample:SQLGetConnectAttr(hdbc, SQL_ATTR_POOL_INFO,PoolInfoStruct *,SQL_LEN_BINARY_ATTR(PoolInfoStruct), &len);This is aread-only connection attribute. The driver returns an error ifSQLSetConnectAttr (SQL_ATTR_POOL_INFO) is called.

SQL_ATTR_POOL_INFO Value:SQL_GET_POOL_INFO

Configuring Pooling-Related Options

The following table summarizes how connection pooling-related connection options work with the drivers. See"Connection Option Descriptions" for details about configuring the options.

Table 15: Summary: Connection Pooling Connection Options

CharacteristicOption

Specifies whether to use the driver’s connection pooling.

If set to 1 (Enabled), the driver uses connection pooling.

If set to 0 (Disabled), the driver does not use connection pooling.


Connection Pooling(Pooling)

Determines whether the state of connections that are removed from the connectionpool for reuse by the application is reset to the initial configuration of the connection.

If set to 1 (Enabled), the state of connections removed from the connection pool forreuse by an application is reset to the initial configuration of the connection.

If set to 0 (Disabled), the state of connections is not reset.


Connection Reset(ConnectionReset)

An integer value to specify the amount of time, in seconds, to keep connections openin a connection pool.

Default: 0

LoadBalance Timeout(LoadBalanceTimeout)


Using DataDirect Connection Pooling


An integer value to specify the maximum number of connections within a single pool.

Default: 100

Max Pool Size(MaxPoolSize)

An integer value to specify the minimum number of connections that are opened andplaced in a connection pool when it is created.

Default: 0

Min Pool Size(MinPoolSize)


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.

Using IP AddressesThe driver supports Internet Protocol (IP) addresses in the IPv4 and IPv6 formats.

If your network supports named servers, the server name specified in the data source can resolve to an IPv4or IPv6 address.

In the following connection string example, the IP address for the Salesforce server is specified in IPv6 format:

DRIVER=DataDirect Salesforce Driver;HostName=2001:DB8:0000:0000:8:800:200C:417A;PORT=19937;[email protected];PWD=XYZZYYou;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect\Salesforce Schema\[email protected];SecurityToken=XaBARTsLZReM4Px47qPLOS



In addition to the normal IPv6 format, the drivers in the preceding tables support IPv6 alternative formats forcompressed and IPv4/IPv6 combination addresses. For example, the following connection string specifies theserver using IPv6 format, but uses the compressed syntax for strings of zero bits:

DRIVER=DataDirect Salesforce Driver;HostName=2001:DB8:0:0:8:800:200C:417A;PORT=19937;[email protected];PWD=XYZZYYou;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect\Salesforce Schema\[email protected];SecurityToken=XaBARTsLZReM4Px47qPLOS

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

DRIVER=DataDirect Salesforce Driver;HostName=2001:DB8:0:0:8:800:123.456.78.90;PORT=19937;[email protected];PWD=XYZZYYou;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect\Salesforce Schema\[email protected];SecurityToken=XaBARTsLZReM4Px47qPLOS

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

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

TimeoutsThe following types of timeout situations can occur when connecting to Salesforce:

• Session timeouts. Most remote data sources impose a limit on the duration of active sessions, meaninga session can fail with a session timeout error if the session extends past the limit. This is particularly truewhen connection pooling is used. The driver automatically attempts to re-establish a new session if thedriver receives a session timeout error from a data source. The driver uses the initial servername, port (ifappropriate), remote user ID, and remote password (encrypted) to re-establish the session. If the attemptfails, the driver returns an error indicating that the session timed out and the attempt to re-establish thesession failed.

• Web service request timeouts.You can configure the driver to never time out while waiting for a responseto a Web service request or to wait for a specified interval before timing out by setting the connection optionWSTimeout. For fetch requests only, if the request times out, you can configure driver to retry the requesta specified number of times by setting the WSRetry Count. connection option. If all subsequent attemptsto retry a request fails, the driver returns an error indicating that the service request timed out and thesubsequent requests failed. See "Connection Option Descriptions" for details on the WS Timeout and WSRetry Count connection options.

See alsoWSTimeout on page 184WSRetry Count on page 183Connection Option Descriptions on page 127

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.


Timeouts

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

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 machineon which the driver is running. A local table is exposed in the PUBLIC schema.

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


SQL SupportSee "Supported SQL Statements and Extensions" for information about the SQL statements and extensionssupported by the Salesforce driver.


Isolation and Lock Levels SupportedSalesforce supports isolation level 0 (read uncommitted).

See "Locking and Isolation Levels" for details.

See alsoLocking and Isolation Levels on page 291

Number of Connections and Statements SupportedThe driver supports multiple connections and multiple statements per connection.

Unicode SupportThe Salesforce driver is fully Unicode enabled. On UNIX and Linux platforms, the driver supports both UTF-8and UTF-16. On Windows platforms, the Salesforce driver supports UCS-2/UTF-16 only.

The driver supports the Unicode ODBC W (Wide) function calls, such as SQLConnectW.This allows the DriverManager to transmit these calls directly to the driver. Otherwise, the Driver Manager would incur the additionaloverhead of converting the W calls to ANSI function calls, and vice versa.

See "UTF-16 Applications on UNIX and Linux" for related details. Also, refer to "Internationalization, Localization,and Unicode" for a more detailed explanation of Unicode.



See alsoUTF-16 Applications on UNIX and Linux on page 47Internationalization, Localization, and Unicode on page 267

Parameter Metadata SupportThe driver supports returning parameter metadata as described in this section.

Insert and Update Statements

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

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

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

• UPDATE foo 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 ANSI SQL92 entry-level predicates, for example, such as COMPARISON, BETWEEN, IN, LIKE, and EXISTS predicateconstructs. 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) < ?


Parameter Metadata Support

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 = ?

Using DataDirect Bulk LoadThe driver supports DataDirect Bulk Load, a feature that allows your application to send large numbers of rowsof data to a Salesforce instance. The driver sends data to a Salesforce instance using the Salesforce Bulk APIinstead of the Web Service API. Similar to batch operations, using the Bulk API significantly reduces the numberof Web service calls the driver uses to transfer data and may improve performance.

Bulk load operations are accomplished by exporting the results of a query from a database into acomma-separated value (CSV) file, a bulk load data file. The driver then loads the data from bulk load data fileinto a different database.The file can be used by any DataDirect for ODBC drivers. In addition, the bulk load datafile is supported by other DataDirect product lines that feature bulk loading, for example, a DataDirect Connectfor ADO.NET data provider that supports bulk load.

Suppose that you had customer data on a Salesforce server and need to export it to a DB2 server. The driverwould perform the following steps:

1. Application using Salesforce driver sends query to and receives results from Salesforce server.

2. Driver exports results to bulk load data file.

3. Driver retrieves results from bulk load data file.

4. Driver bulk loads results on DB2 server.



Bulk Export and Load Methods

You can take advantage of DataDirect Bulk Load either through the Driver setup dialog or programmatically.

Applications that are already coded to use parameter array batch functionality can leverage DataDirect BulkLoad features through the Enable Bulk Load connection option on the Bulk tab of the Driver setup dialog.Enabling this option automatically converts the parameter array batch operation to use the Salesforce bulkload protocol without any code changes to your application.

If you are not using parameter array batch functionality, the bulk operation buttons Export Table and LoadTable on the Bulk tab of the driver Setup dialog also allow you to use bulk load functionality without any codechanges. See the individual driver chapters for a description of the Bulk tab.

If you want to integrate bulk load functionality seamlessly into your application, you can include code to usethe bulk load functions exposed by the driver.

For your applications to use DataDirect Bulk Load functionality, they must obtain driver connection handlesand function pointers, as follows:

1. Use SQLGetInfo with the parameter SQL_DRIVER_HDBC to obtain the driver’s connection handle fromthe Driver Manager.

2. Use SQLGetInfo with the parameter SQL_DRIVER_HLIB to obtain the driver’s shared library or DLL handlefrom the Driver Manager.

3. Obtain function pointers to the bulk load functions using the function name resolution method specific toyour operating system. The bulk.c example program shipped with the drivers contains the functionresolveName that illustrates how to obtain function pointers to the bulk load functions.

This is detailed in the code samples that follow.

Exporting Data from a Database

You can export data from a database in one of three ways:

• From a table by using the driver Setup dialog

• From a table by using DataDirect functions

• From a result set by using DataDirect statement attributes

From the DataDirect driver Setup dialog, select the Bulk tab and click Export Table. See "Bulk Tab" for adescription of this procedure.

Your application can export a table using the DataDirect functions ExportTableToFile (ANSI application) orExportTableToFileW (Unicode application). The application must first obtain driver connection handles andfunction pointers, as shown in the following example:

HDBC hdbc;HENV henv;void *driverHandle;HMODULE hmod;PExportTableToFile exportTableToFile;

char tableName[128];char fileName[512];char logFile[512];int errorTolerance;int warningTolerance;int codePage;


Using DataDirect Bulk Load

/* Get the driver's connection handle from the DM. This handle must be used when calling directly into the driver. */

rc = SQLGetInfo (hdbc, SQL_DRIVER_HDBC, &driverHandle, 0, NULL);if (rc != SQL_SUCCESS) { ODBC_error (henv, hdbc, SQL_NULL_HSTMT); EnvClose (henv, hdbc); exit (255);}

/* Get the DM's shared library or DLL handle to the driver. */

rc = SQLGetInfo (hdbc, SQL_DRIVER_HLIB, &hmod, 0, NULL);if (rc != SQL_SUCCESS) { ODBC_error (henv, hdbc, SQL_NULL_HSTMT); EnvClose (henv, hdbc); exit (255);}exportTableToFile = (PExportTableToFile) resolveName (hmod, "ExportTableToFile");if (! exportTableToFile) { printf ("Cannot find ExportTableToFile!\n"); exit (255);}

rc = (*exportTableToFile) ( driverHandle, (const SQLCHAR *) tableName, (const SQLCHAR *) fileName, codePage, errorTolerance, warningTolerance, (const SQLCHAR *) logFile);if (rc == SQL_SUCCESS) { printf ("Export succeeded.\n");}else { driverError (driverHandle, hmod);}

Your application can export a result set using the DataDirect statement attributes SQL_BULK_EXPORT andSQL_BULK_EXPORT_PARAMS.

The export operation creates a bulk load data file with a .csv extension in which the exported data is stored.For example, assume that a Salesforce source table named GBMAXTABLE contains four columns.The resultingbulk load data file GBMAXTABLE.csv containing the results of a query would be similar to the following:

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"

A bulk load configuration file with and .xml extension is also created when either a table or a result set isexported to a bulk load data file. See "The Bulk Load Configuration File" for an example of a bulk loadconfiguration file.

In addition, a log file of events as well as external overflow files can be created during a bulk export operation.The log file is configured through either the driver Setup dialog Bulk tab, the ExportTableToFile function, or theSQL_BULK_EXPORT statement attribute.The external overflow files are configured through connection options;see "External Overflow Files" for details.



See alsoThe Bulk Load Configuration File on page 104External Overflow Files on page 107

Bulk Loading to a Database

You can load data from the bulk load data file into the target database through the DataDirect driver Setupdialog by selecting the Bulk tab and clicking Load Table. See "Bulk Tab" for a description of this procedure.

Your application can also load data from the bulk load data file into the target database using the using theDataDirect functions LoadTableFromFile (ANSI application) or LoadTableFromFileW (Unicode application).The application must first obtain driver connection handles and function pointers, as shown in the followingexample:

HDBC hdbc;HENV henv;void *driverHandle;HMODULE hmod;PLoadTableFromFile loadTableFromFile;char tableName[128];char fileName[512];char configFile[512];char logFile[512];char discardFile[512];int errorTolerance;int warningTolerance;int loadStart;int loadCount;int readBufferSize;

/* Get the driver's connection handle from the DM. This handle must be used when calling directly into the driver.*/

rc = SQLGetInfo (hdbc, SQL_DRIVER_HDBC, &driverHandle, 0, NULL);if (rc != SQL_SUCCESS) { ODBC_error (henv, hdbc, SQL_NULL_HSTMT); EnvClose (henv, hdbc); exit (255);}/* Get the DM's shared library or DLL handle to the driver. */

rc = SQLGetInfo (hdbc, SQL_DRIVER_HLIB, &hmod, 0, NULL);if (rc != SQL_SUCCESS) { ODBC_error (henv, hdbc, SQL_NULL_HSTMT); EnvClose (henv, hdbc); exit (255);}

loadTableFromFile = (PLoadTableFromFile) resolveName (hmod, "LoadTableFromFile");if (! loadTableFromFile) { printf ("Cannot find LoadTableFromFile!\n"); exit (255);}

rc = (*loadTableFromFile) ( driverHandle, (const SQLCHAR *) tableName, (const SQLCHAR *) fileName, errorTolerance, warningTolerance, (const SQLCHAR *) configFile, (const SQLCHAR *) logFile, (const SQLCHAR *) discardFile,



loadStart, loadCount, readBufferSize);if (rc == SQL_SUCCESS) { printf ("Load succeeded.\n");}else { driverError (driverHandle, hmod);}

Use the BulkLoadBatchSize connection attribute to specify the number of rows the driver loads to the datasource at a time when bulk loading data. Performance can be improved by increasing the number of rows thedriver loads at a time because fewer network round trips are required. Be aware that increasing the numberof rows that are loaded also causes the driver to consume more memory on the client.

A log file of events as well as a discard file that contains rows rejected during the load can be created duringa bulk load operation. These files are configured through either the driver Setup dialog Bulk tab or theLoadTableFromFile function.

The discard file is in the same format as the bulk load data file. After fixing reported issues in the discard file,the bulk load can be reissued using the discard file as the bulk load data file.

In addition to bulk Insert, the driver also supports bulk Delete, Update, and Upsert.This functionality is enabledwith the SetBulkOperation function which is implemented in the driver. See "DataDirect Bulk Load Functions"for a full description of these functions.

See alsoBulk Tab on page 62DataDirect Bulk Load Functions on page 301

The Bulk Load Configuration File

A bulk load configuration file is created when either a table or a result set is exported to a bulk load data file.This file has the same name as the bulk load data file, but with an .xml extension.

The bulk load configuration file defines in its metadata the names and data types of the columns in the bulkload data file.The file defines these names and data types based on the table or result set created by the querythat exported the data.

It also defines other data properties, such as length for character and binary data types, the character encodingcode page for character types, precision and scale for numeric types, and nullability for all types.

When a bulk load data file cannot read its configuration file, the following defaults are assumed:

• All data is read in as character data. Each value between commas is read as character data.

• The default character set is defined, on Windows, by the current Windows code page. On UNIX/Linux, it isthe IANAAppCodePage value, which defaults to 4.

For example, the format of the bulk load data file GBMAXTABLE.csv (discussed in "Exporting Data from aDatabase") is defined by the bulk load configuration file, GBMAXTABLE.xml, as follows:

<?xml version="1.0" encoding="utf-8"?><table codepage="UTF-16LE" xsi:noNamespaceSchemaLocation="http://media.datadirect.com/download/docs/ns/bulk/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>

See alsoExporting Data from a Database on page 101

Bulk Load Configuration File SchemaThe bulk load configuration file is supported by an underlying XML Schema defined at:

http://media.datadirect.com/download/docs/ns/bulk/BulkData.xsd

The bulk load configuration file must conform to the bulk load configuration XML schema. Each bulk exportoperation generates a bulk load configuration file in UTF-8 format. If the bulk load data file cannot be createdor does not comply with the XML Schema described in the bulk load configuration file, an error is generated.

Verification of the Bulk Load Configuration FileYou can verify the metadata in the configuration file against the data structure of the target database table.This insures that the data in the bulk load data file is compatible with the target database table structure.

The verification does not check the actual data in the bulk load data file, so it is possible that the load can faileven though the verification succeeds. For example, if you were to update the bulk load data file manually suchthat it has values that exceed the maximum column length of a character column in the target table, the loadwould fail.

Not all of the error messages or warnings that are generated by verification necessarily mean that the load willfail. Many of the messages simply notify you about possible incompatibilities between the source and targettables. For example, if the bulk load data file has a column that is defined as an integer and the column in thetarget table is defined as smallint, the load may still succeed if the values in the source column are small enoughthat they fit in a smallint column.

To verify the metadata in the bulk load configuration file through the DataDirect driver Setup dialog, select theBulk tab and click Verify. See the individual driver chapters of the drivers that support bulk load for a descriptionof this procedure.

Your application can also verify the metadata of the bulk load configuration file using the DataDirect functionsValidateTableFromFile (ANSI application) or ValidateTableFromFileW (Unicode application). The applicationmust first obtain driver connection handles and function pointers, as shown in the following example:

HDBC hdbc;HENV henv;void *driverHandle;HMODULE hmod;PValidateTableFromFile validateTableFromFile;char tableName[128];char configFile[512];char messageList[10240];SQLLEN numMessages;/* Get the driver's connection handle from the DM. This handle must be used when calling directly into the driver. */rc = SQLGetInfo (hdbc, SQL_DRIVER_HDBC, &driverHandle, 0, NULL);if (rc != SQL_SUCCESS) { ODBC_error (henv, hdbc, SQL_NULL_HSTMT); EnvClose (henv, hdbc); exit (255);}/* Get the DM's shared library or DLL handle to the driver. */



http://media.datadirect.com/download/docs/ns/bulk/BulkData.xsd

rc = SQLGetInfo (hdbc, SQL_DRIVER_HLIB, &hmod, 0, NULL);if (rc != SQL_SUCCESS) { ODBC_error (henv, hdbc, SQL_NULL_HSTMT); EnvClose (henv, hdbc); exit (255);}validateTableFromFile = (PValidateTableFromFile) resolveName (hmod, "ValidateTableFromFile");if (!validateTableFromFile) { printf ("Cannot find ValidateTableFromFile!\n"); exit (255);}messageList[0] = 0;numMessages = 0;rc = (*validateTableFromFile) ( driverHandle, (const SQLCHAR *) tableName, (const SQLCHAR *) configFile, (SQLCHAR *) messageList, sizeof (messageList), &numMessages);printf ("%d message%s%s\n", numMessages, (numMessages == 0) ? "s" : ((numMessages == 1) ? " : " : "s : "), (numMessages > 0) ? messageList : "");if (rc == SQL_SUCCESS) { printf ("Validate succeeded.\n");}else { driverError (driverHandle, hmod);}

Sample Applications

Progress DataDirect provides a sample application that demonstrates the bulk export, verification, and bulkload operations. This application is located in the \samples\bulk subdirectory of the product installationdirectory along with a text file named bulk.txt. Please consult bulk.txt for instructions on using the samplebulk load application.

A bulk streaming application is also provided in the \samples\bulkstrm subdirectory along with a text filenamed bulkstrm.txt. Please consult bulkstrm.txt for instructions on using the bulk streaming application.

Character Set Conversions

It is most performance-efficient to transfer data between databases that use the same character sets. At times,however, you might need to bulk load data between databases that use different character sets.You can dothis by choosing a character set for the bulk load data file that will accommodate all data. If the source tablecontains character data that uses different character sets, then one of the Unicode character sets, UTF-8,UTF-16BE, or UTF-16LE must be specified for the bulk load data file. A Unicode character set should also bespecified in the case of a target table uses a different character set than the source table to minimize conversionerrors. If the source and target tables use the same character set, that set should be specified for the bulk loaddata file.

A character set is defined by a code page.The code page for the bulk load data file is defined in the configurationfile and is specified through either the Code Page option of the Export Table driver Setup dialog or through theIANAAppCodePage parameter of the ExportTableToFile function. Any code page listed in "Code Page Values"is supported for the bulk load data file.

Any character conversion errors are handled based on the value of the Report Codepage Conversion Errorsconnection option. See the individual driver chapters for a description of this option.



The configuration file may optionally define a second code page value for each character column(externalfilecodepage). If character data is stored in an external overflow file (see "External OverflowFiles"), this second code page value is used for the external file.

See alsoCode Page Values on page 251External Overflow Files on page 107

External Overflow Files

In addition to the bulk load data file, DataDirect Bulk Load can store bulk data in external overflow files. Theseoverflow files are located in the same directory as the bulk load data file. Different files are used for binary dataand character data. Whether or not to use external overflow files is a performance consideration. For example,binary data is stored as hexadecimal-encoded character strings in the main bulk load data file, which increasesthe size of the file per unit of data stored. External files do not store binary data as hex character strings, and,therefore, require less space. On the other hand, more overhead is required to access external files than toaccess a single bulk load data file, so each bulk load situation must be considered individually.

The value of the Bulk Binary Threshold connection option determines the threshold, in KB, over which binarydata is stored in external files instead of in the bulk load data file. Likewise, the Bulk Character Thresholdconnection option determines the threshold for character data.

In the case of an external character data file, the character set of the file is governed by the bulk loadconfiguration file. If the bulk load data file is Unicode and the maximum character size of the source data is 1,then the data is stored in its source code page. See "Character Set Conversions".

The file name of the external file contains the bulk load data file name, a six-digit number, and a ".lob" extensionin the following format: CSVfilename_nnnnnn.lob. Increments start at 000001.lob.

See alsoCharacter Set Conversions on page 106

Summary of DataDirect Bulk Load Related Options

The following table summarizes how DataDirect Bulk Load related connection options work with the driver.See "Connection Option Descriptions" for details about configuring the options.



Table 16: Summary: Bulk Load Connection Options


Determines whether the driver treats bulk load operations as synchronousor asynchronous.

If set to 0 (Disabled), bulk load operations are synchronous.The driver doesnot return from the function that invoked an operation until the operation iscomplete or the BulkLoadTimeout period has expired. If the operation timesout, the driver returns an error.

If set to 1 (Enabled), bulk load operations are asynchronous. The driverreturns from the function that invoked an operation after the operation issubmitted to the server. The driver does not verify the completion status ofthe bulk load operation.


Bulk Load Asynchronous(BulkLoadAsync)

The number of rows that the driver sends to the database at a time duringbulk operations.

Default: 1024

Bulk Load Batch Size(BulkLoadBatchSize)

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

If set to 0 (Serial), multiple batches associated with a bulk load operationare processed one at a time.

If set to 1 (Parallel), multiple batches associated with a bulk load operationare processed in parallel.The order in which the batches are processed canvary.

Default: 1 - Parallel

Bulk Load Concurrency Mode(BulkLoadConcurrencyMode)

Specifies the number of seconds the driver waits to request bulk operationstatus. This interval is used by the driver the first time it requests status andfor all subsequent status requests.

Default: 10

Bulk Load Poll Interval(BulkLoadPollInterval)

Determines when the driver uses bulk load for insert, update, delete, or batchoperations.

If set to 0, the driver always uses bulk load to execute insert, update, delete,or batch operations.

If set to x, the driver only uses bulk load if the number of rows to be updatedby an insert, update, delete, or batch operation exceeds the threshold. If theoperation times out, the driver returns an error.

Default: 4000

Bulk Load Threshold(BulkLoadThreshold)




The time, in seconds, that the driver waits for a Salesforce bulk job tocomplete.


Default: 0

Bulk Load Timeout(BulkLoadTimeout)

Specifies the character that the driver will use to delimit the field entries ina bulk load data file.

Default: None

Field Delimiter(BulkLoadFieldDelimiter)

Specifies the character that the driver will use to delimit the record entriesin a bulk load data file.

Default: None

Record Delimiter(BulkLoadRecordDelimiter)


Using Bulk API with SQL StatementsThe driver uses Salesforce Bulk API for executing selects, inserts, deletes, and updates based on the valuesof the Enable Bulk Load and Enable Bulk Fetch connection options.

For information on other connection options that influence the behavior of Salesforce Bulk API, see "Summaryof Options for Using Bulk API with SQL Statements."

Using Bulk API with Inserts, Updates, and Deletes:

When the Enable Bulk Load option is enabled (EnableBulkLoad=1), the driver uses the Salesforce Bulk APIfor inserts, updates, and deletes based on the values of the Bulk Load Threshold connection option. If thenumber of affected rows exceeds the value of Bulk Load Threshold option, the driver uses the Salesforce BulkAPI to execute the insert, update, or delete operation.

You can further configure bulk load behavior by specifying the number of rows the driver loads at a time usingthe Bulk Load Batch Size connection option. Performance can be improved by increasing the number of rowsthe driver loads at a time because fewer network round trips are required. Be aware that increasing the numberof rows that are loaded also causes the driver to consume more memory on the client.

Using Bulk API with Selects:

When the Enable Bulk Fetch option is enabled (EnableBulkFetch=1), the driver uses the Salesforce BulkAPI for selects based on the values of the Bulk Fetch Threshold connection option. If the number of rowsexpected in the result set exceeds the value of Bulk Fetch Threshold option, the driver uses the SalesforceBulk API to execute the select operation.


Using Bulk API with SQL Statements

Note:



See alsoEnable Bulk Load on page 154Enable Bulk Fetch on page 153Summary of Options for Using Bulk API with SQL Statements on page 110

Summary of Options for Using Bulk API with SQL Statements

The following table describes connection options related to using bulk API when executing selects, inserts,updates, and deletes. See "Connection Option Descriptions" in each driver chapter for details about configuringthe options.

Table 17: Summary: Connection Options for Using Bulk API with SQL Statements


Specifies a number of rows that, if exceeded, signals the driver to use theSalesforce Bulk API for select operations. For this behavior to take effect,the Enable Bulk Fetch option must be set to 1 (enabled).

If 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 whenthe value of x is exceeded.


Bulk Fetch Threshold(BulkFetchThreshold)

The number of rows that the driver sends to the database at a time duringbulk operations.

Default: 1024

Bulk Load Batch Size(BulkLoadBatchSize)

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

If set to 0 (Serial), multiple batches associated with a bulk load operationare processed one at a time.

If set to 1 (Parallel), multiple batches associated with a bulk load operationare processed in parallel.The order in which the batches are processed canvary.

Default: 1 (Parallel)

Bulk Load Concurrency Mode(BulkLoadConcurrencyMode)




Determines when the driver uses bulk load for insert, update, and deletes.

If set to 0, the driver always uses bulk load to execute insert, update, anddeletes.

If set to x, the driver only uses bulk load if the Enable Bulk Load option isset to a value of 1 (enabled) and the number of rows to be updated by aninsert, update, or delete exceeds the threshold. If the operation times out,the driver returns an error.

Default: 4000

Bulk Load Threshold(BulkLoadThreshold)

The time, in seconds, that the driver waits for a Salesforce bulk job tocomplete.


Default: 0

Bulk Load Timeout(BulkLoadTimeout)

Specifies whether the driver can use the Salesforce Bulk API for selectsbased on the value of the Bulk Fetch Threshold connection option.

If set to 1 (Enabled), the driver can use the Salesforce Bulk API for selectsbased on the value of the Bulk Fetch Threshold connection option. If thenumber of rows expected in the result set exceeds the value of Bulk FetchThreshold option, the driver uses the Salesforce Bulk API to execute theselect operation.

If set to 0 (Disabled), the driver does not use the Salesforce Bulk API, andthe Bulk Load Threshold option is ignored.

Default: 1 (Enabled)

Note:

If there is a TOP or LIMIT clause in the select query, the driver considersthe TOP or LIMIT clause value as the expected number of rows in the resultset and compares it with the value of the Bulk Fetch Threshold option tochoose either Bulk API or REST API for executing the select query.

If the value of TOP or LIMIT clause is greater than that of the Bulk FetchThreshold option, but the actual row count in the result set is less, theperformance of the select query might be affected adversely.

Enable Bulk Fetch(EnableBulkFetch)


Using Bulk API with SQL Statements


Specifies whether the driver can use the Salesforce Bulk API for inserts,updates, and deletes based on the value of the Bulk Load Thresholdconnection option.

If set to 1 (Enabled), the driver can use the Salesforce Bulk API for inserts,updates, and deletes based on the value of the Bulk Load Thresholdconnection option. If the number of affected rows exceeds the value of BulkLoad Threshold option, the driver uses the Salesforce Bulk API to executethe insert, update, or delete operation.

If set to 0 (Disabled), the driver does not use the Salesforce Bulk API, andthe Bulk Load Threshold option is ignored.


Enable Bulk Load(EnableBulkLoad)

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

If set to 1 (Enabled), the driver uses PK chunking for select operations whenthe expected number of rows in the result set is greater than the values ofthe Bulk Fetch Threshold and Primary Key Chunk Size options. For thisbehavior to take effect, the Enable Bulk Fetch option must also be set to 1(enabled).

If set to 0 (Disabled), the driver does not use PK chunking when executingselect operations, and the Primary Key Chunk Size option is ignored.


Enable Primary Key Chunking(EnablePKChunking)

Specifies the size, in rows, of a primary key (PK) chunk when PK chunkinghas been enabled via the Enable Primary Key Chunking option. TheSalesforce Bulk API splits the query into chunks of this size.


Primary Key Chunk Size(PKChunkSize)




4Troubleshooting

This part guides you through troubleshooting your Progress DataDirect for ODBC for Salesforce. It provides youwith solutions to common problems and documents error messages that you may receive.


• Diagnostic Tools

• Error Messages

• Troubleshooting

Diagnostic ToolsThis chapter discusses the diagnostic tools you use when configuring and troubleshooting your ODBCenvironment.

ODBC Trace

ODBC tracing allows you to trace calls to ODBC drivers and create a log of the traces.

Creating a Trace LogCreating a trace log is particularly useful when you are troubleshooting an issue.

To create a trace log:


1. Enable tracing (see "Enabling Tracing" for more information).

2. Start the ODBC application and reproduce the issue.

3. Stop the application and turn off tracing.

4. Open the log file in a text editor and review the output to help you debug the problem.

For a complete explanation of tracing, refer to the following Progress DataDirect Knowledgebase document:

http://knowledgebase.progress.com/articles/Article/3049

See alsoEnabling Tracing on page 114

Enabling TracingProgress DataDirect provides a tracing library that is enhanced to operate more efficiently, especially inproduction environments, where log files can rapidly grow in size. The DataDirect tracing library allows you tocontrol the size and number of log files.

On Windows, you can enable tracing through the Tracing tab of the ODBC Data Source Administrator.

On UNIX and Linux, you can enable tracing by directly modifying the [ODBC] section in the system information(odbc.ini) file.

Windows ODBC Administrator

On Windows, open the ODBC Data Source Administrator and select the Tracing tab. To specify the pathand name of the trace log file, type the path and name in the Log File Path field or click Browse to select a logfile. If no location is specified, the trace log resides in the working directory of the application you are using.

Click Select DLL in the Custom Trace DLL pane to select the DataDirect enhanced tracing library,xxtrcyy.dll, where xx represents either iv (32-bit version) or dd (64-bit version), and yy represents thedriver level number, for example, ivtrc28.dll.The library is installed in the \Windows\System32 directory.

After making changes on the Tracing tab, click Apply for them to take effect.

Enable tracing by clicking Start Tracing Now. Tracing continues until you disable it by clicking Stop TracingNow. Be sure to turn off tracing when you are finished reproducing the issue because tracing decreases theperformance of your ODBC application.

When tracing is enabled, information is written to the following trace log files:

• Trace log file (trace_filename.log) in the specified directory.

• Trace information log file (trace_filenameINFO.log). This file is created in the same directory as thetrace log file and logs the following SQLGetInfo information:

• SQL_DBMS_NAME

• SQL_DBMS_VER

• SQL_DRIVER_NAME

• SQL_DRIVER_VER

• SQL_DEFAULT_TXN_ISOLATION


Chapter 4: Troubleshooting

http://knowledgebase.progress.com/articles/Article/3049

The DataDirect enhanced tracing library allows you to control the size and number of log files. The file sizelimit of the log file (in KB) is specified by the Windows Registry key ODBCTraceMaxFileSize. Once the sizelimit is reached, a new log file is created and logging continues in the new file until it reaches its file size limit,after which another log file is created, and so on.

The maximum number of files that can be created is specified by the Registry key ODBCTraceMaxNumFiles.Once the maximum number of log files is created, tracing reopens the first file in the sequence, deletes thecontent, and continues logging in that file until the file size limit is reached, after which it repeats the processwith the next file in the sequence. Subsequent files are named by appending sequential numbers, starting at1 and incrementing by 1, to the end of the original file name, for example, SQL1.LOG, SQL2.LOG, and so on.

The default values of ODBCTraceMaxFileSize and ODBCTraceMaxNumFiles are 102400 KB and 10,respectively. To change these values, add or modify the keys in the following Windows Registry section:

[HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI\ODBC]

Warning: Do not edit the Registry unless you are an experienced user. Consult your system administrator ifyou have not edited the Registry before.

Edit each key using your values and close the Registry.

System Information (odbc.ini) File

The [ODBC] section of the system information file includes several keywords that control tracing:

Trace=[0 | 1]TraceFile=trace_filenameTraceDll=ODBCHOME/lib/xxtrcyy.zzODBCTraceMaxFileSize=file_sizeODBCTraceMaxNumFiles=file_numberTraceOptions=0

where:

Trace=[0 | 1]

Allows you to enable tracing by setting the value of Trace to 1. Disable tracing by setting the valueto 0 (the default). Tracing continues until you disable it. Be sure to turn off tracing when you arefinished reproducing the issue because tracing decreases the performance of your ODBC application.

TraceFile=trace_filename

Specifies the path and name of the trace log file. If no path is specified, the trace log resides in theworking directory of the application you are using.

TraceDll=ODBCHOME/lib/xxtrcyy.zz

Specifies the library to use for tracing. The driver installation includes a DataDirect enhanced libraryto perform tracing, xxtrcyy.zz, where xx represents either iv (32-bit version) or dd (64-bit version),yy represents the driver level number, and zz represents so. For example, ivtrc28.so is the32-bit version of the library. To use a custom shared library instead, enter the path and name of thelibrary as the value for the TraceDll keyword.

The DataDirect enhanced tracing library allows you to control the size and number of log files withthe ODBCTraceMaxFileSize and ODBCTraceMaxNumFiles keywords.


Diagnostic Tools

ODBCTraceMaxFileSize=file_size

The ODBCTraceMaxFileSize keyword specifies the file size limit (in KB) of the log file. Once this filesize limit is reached, a new log file is created and logging continues in the new file until it reachesthe file size limit, after which another log file is created, and so on. The default is 102400.

ODBCTraceMaxNumFiles=file_number

The ODBCTraceMaxNumFiles keyword specifies the maximum number of log files that can becreated. The default is 10. Once the maximum number of log files is created, tracing reopens thefirst file in the sequence, deletes the content, and continues logging in that file until the file size limitis reached, after which it repeats the process with the next file in the sequence. Subsequent filesare named by appending sequential numbers, starting at 1 and incrementing by 1, to the end of theoriginal file name, for example, odbctrace1.out, odbctrace2.out, and so on.

TraceOptions=[0 | 1 | 2 | 3]

The ODBCTraceOptions keyword specifies whether to print the current timestamp, parent processID, process ID, and thread ID for all ODBC functions to the output file. The default is 0.

• If set to 0, the driver uses standard ODBC tracing.

• If set to 1, the log file includes a timestamp on ENTRY and EXIT of each ODBC function.

• If set to 2, the log file prints a header on every line. By default, the header includes the parentprocess ID and process ID.

• If set to 3, both TraceOptions=1 and TraceOptions=2 are enabled. The header includes atimestamp as well as a parent process ID and process ID.

Example

In the following example of trace settings, tracing has been enabled, the name of the log file isodbctrace.out, the library for tracing is ivtrc28.so, the maximum size of the log file is 51200KB, and the maximum number of log files is 8. Timestamp and other information is included inodbctrace.out.

Trace=1TraceFile=ODBCHOME/lib/odbctrace.outTraceDll=ODBCHOME/lib/ivtrc28.soODBCTraceMaxFileSize=51200ODBCTraceMaxNumFiles=8TraceOptions=3

The Test Loading Tool

Before using the test loading tool, be sure that your environment variables are set correctly. See "EnvironmentVariables" for details about environment variables.

The ivtestlib (32-bit drivers) and ddtestlib (64-bit drivers) test loading tools are provided to test load drivers andhelp diagnose configuration problems in the UNIX and Linux environments, such as environment variables notcorrectly set or missing database client components.This tool is installed in the /bin subdirectory in the productinstallation directory. It attempts to load a specified ODBC driver and prints out all available error informationif the load fails.

For example, if the drivers are installed in /opt/odbc/lib, the following command attempts to load the 32-bitdriver on Linux, where xx represents the version number of the driver:






See "Version String Information" for details about version strings.

See alsoEnvironment Variables on page 38Version String Information on page 18

ODBC Test

On Windows, Microsoft®

ships with its ODBC SDK an ODBC-enabled application, named ODBC Test, that youcan use to test ODBC drivers and the ODBC Driver Manager. ODBC 3.52 includes both ANSI andUnicode-enabled versions of ODBC Test.

To use ODBC Test, you must understand the ODBC API, the C language, and SQL. For more informationabout ODBC Test, refer to the Microsoft ODBC SDK Guide.

Logging

The Salesforce driver provides a flexible and comprehensive logging mechanism of its Java components thatallows logging to be incorporated seamlessly with the logging of your application or 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 ComponentsThe driver uses the Java Logging API to configure and control 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, warnings that occur in the drivercan be written to a logger at the WARNING level, while progress or flow information can be written to a loggerat the INFO 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

• CONFIG

• FINE


Diagnostic Tools

• FINER

• FINEST

• INFO

• WARNING

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, and SEVERE to its log. Messages of level FINER or FINEST are not written to the log.

The driver exposes loggers for the following functional areas:

• Driver to SQL Communication

• SQL Engine

• Web service adapter

Driver to SQL Communication Logger

Namedatadirect.cloud.drivercommunication

DescriptionLogs all calls made by the driver to the SQL Engine and the responses from the SQL Engine back to the driver.

Message LevelsCONFIG - Errors and Warnings encountered by the communication protocol are logged at this level.

FINER - The message type and arguments for requests and responses sent between the driver and SQLEngine are logged at this level. Data transferred between the driver and SQL Engine is not logged.

FINEST - Data transferred between the driver and SQL Engine is logged at this level.

DefaultOFF

SQL Engine Logger

Namedatadirect.cloud.sql.level

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

Wire Protocol Adapter Logger

Namedatadirect.cloud.adapter.level

DescriptionLogs the calls the driver makes to the remote data source and the responses it receives from the remote datasource.

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

FINE - In addition to the information logged by the CONFIG level, information about calls made by the wireprotocol adapter and responses received by the wire protocol adapter are written at this level. In particular, thecalls made to execute the query and the calls to fetch or send the data are logged. The log entries for the callsto execute the query include the Salesforce-specific query being executed. The actual data sent or fetched isnot written at this level.

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

FINEST - In addition to the information logged by the CONFIG, FINE, and FINER levels, data associated withthe calls made by the wire protocol 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 on page 119 for details.

• Using the driver. See Using the Driver on page 120 for details.

Using the JVMIf you want to configure logging using the properties file that is shipped with your JVM, use a text editor tomodify the properties file in your JVM. Typically, this file is named logging.properties and is located 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 systemproperty. At a command prompt, enter:

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

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


Diagnostic Tools

Using the DriverIf 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 schema maps([email protected] and [email protected], for example), you can load one propertiesfile for the [email protected] schema map and load another properties file for [email protected] schema map.

Note: By default, the name of the schema map is the user ID specified for the connection.You can specifythe name of the schema map using the SchemaMap attribute. See "Connection Option Descriptions" for detailson using LogConfigFile and other connection options.

By default, the driver looks for the file named ddlogging.properties in the current working directory toload for all Salesforce connections. If the driver is operating in Server mode, the driver uses theddlogging.properties file that is stored in the location specified by the Schema Map connection option.

If a properties file is specified for the LogConfigFile connection option, the driver uses the following process todetermine which file to load:

1. The driver looks for the file specified by the LogConfigFile connection option.

2. If the driver cannot find the file in Step 1 on page 120, 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 120, it looks for a properties file named ddlog.propertiesin the current working directory.

4. If the driver cannot find the file in Step 3 on page 120, 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 filenamed ddlogging.properties is installed in the install_dir\samplessubdirectory of your product installation directory, where install_dir is your product installation directory.For example, you can find the ddlogging.properties file in install_dir\Samples\Bulkstrm,install_dir\Samples\Bulk, and install_dir\Samples\Example.You can copy this file to the currentworking directory of your application or schema map configuration file directory, and modify it using a text editorfor your needs.


The Example Application

Progress DataDirect provides a simple C application, named example, that is useful for:

• Executing any type of SQL statement

• Testing database connections

• Testing SQL statements

• Verifying your database environment



The example application is installed in the /samples/example subdirectory in the product installation directory.Refer to example.txt or example64.txt in the example directory for an explanation of how to build anduse this application.

Other Tools

The Progress DataDirect Support Web site provides other diagnostic tools that you can download to assist youwith troubleshooting.These tools are not shipped with the product. Refer to the Progress DataDirect Web page:

https://www.progress.com/support/evaluation/download-resources/download-tools

Progress DataDirect also provides a knowledgebase that is useful in troubleshooting problems. Refer to theProgress DataDirect Knowledgebase page:

http://progresscustomersupport-survey.force.com/ConnectKB

Error MessagesError messages can be generated from:

• ODBC driver

• Database system

• ODBC driver manager

An error reported on an ODBC driver has the following format:

[vendor] [ODBC_component] message

where ODBC_component is the component in which the error occurred. For example, an error message fromthe Progress DataDirect for ODBC for Salesforce driver would look like this:

[DataDirect] [Salesforce ODBC Driver] Invalid precision specified.

If you receive this type of error, check the last ODBC call made by your application for possible problems orcontact your ODBC application vendor.

An error that occurs in the data source includes the data store name, in the following format:

[vendor] [ODBC_component] [data_store] message

With this type of message, ODBC_component is the component that received the error specified by the datastore. For example, you may receive the following message from a Salesforce database:

[DataDirect] [Salesforce ODBC Driver] [Salesforce] Specified length too long for CHAR column

This type of error is generated by the database system. Check your Salesforce system documentation for moreinformation or consult your database administrator.

On Windows, the Microsoft Driver Manager is a DLL that establishes connections with drivers, submitsrequests to drivers, and returns results to applications. An error that occurs in the Driver Manager has thefollowing format:

[vendor] [ODBC XXX] message


Error Messages

https://www.progress.com/support/evaluation/download-resources/download-tools

http://progresscustomersupport-survey.force.com/ConnectKB

For example, an error from the Microsoft Driver Manager might look like this:

[Microsoft] [ODBC Driver Manager] Driver does not support this function

If you receive this type of error, consult the Programmer’s Reference for the Microsoft ODBC SoftwareDevelopment Kit available from Microsoft.

On UNIX and Linux, the Driver Manager is provided by Progress DataDirect. For example, an error from theDataDirect Driver Manager might look like this:

[DataDirect][ODBC lib] String data code page conversion failed.

UNIX and Linux error handling follows the X/Open XPG3 messaging catalog system. Localized error messagesare stored in the subdirectory:

locale/localized_territory_directory/LC_MESSAGES

where localized_territory_directory depends on your language.

For instance, German localization files are stored in locale/de/LC_MESSAGES, where de is the locale forGerman.

If localized error messages are not available for your locale, then they will contain message numbers insteadof text. For example:

[DataDirect] [ODBC 20101 driver] 30040

TroubleshootingIf you are having an issue while using your driver, first determine the type of issue that you are encountering:

• Setup/connection

• Performance

• Interoperability (ODBC application, ODBC driver, ODBC Driver Manager, or data source)

• Out-of-Memory

This chapter describes these three types of issues, provides some typical causes of the issues, lists somediagnostic tools that are useful to troubleshoot the issues, and, in some cases, explains possible actions youcan take to resolve the issues.

Setup/Connection Issues

You are experiencing a setup/connection issue if you are encountering an error or hang while you are tryingto make a database connection with the ODBC driver or are trying to configure the ODBC driver.



Some common errors that are returned by the ODBC driver if you are experiencing a setup/connection issueinclude:

• Specified driver could not be loaded.

• Data source name not found and no default driver specified.

• Cannot open shared library: libodbc.so.

• Unable to connect to destination.

• Invalid username/password; logon denied.

Troubleshooting the IssueSome common reasons that setup/connection issues occur are:

• The library path environment variable is not set correctly.

Note: The 32-bit and 64-bit drivers for Salesforce require that you set the library path environment for youroperating system to the directory containing your 32-bit JVM’s libjvm.so [a] file, and that directory’sparent directory before using the driver.

HP-UX ONLY:

• When setting the library path environment variable on HP-UX operating systems, specifying the parentdirectory is not required.

• You also must set the LD_PRELOAD environment variable to the fully qualified path of the libjvm.so.


32-bit Drivers

• PATH on Windows

• LD_LIBRARY_PATH on Solaris, Linux, and HP-UX Itanium

• LIBPATH on AIX

64-bit Drivers

• PATH on Windows

• LD_LIBRARY_PATH on Solaris, HP-UX Itanium, and Linux

• LIBPATH on AIX

• The database and/or listener are not started.

• The ODBCINI environment variable is not set correctly for the ODBC drivers on UNIX and Linux.

• The ODBC driver’s connection attributes are not set correctly in the system information file on UNIX andLinux. See "Data Source Configuration on UNIX/Linux" for more information. For example, the host nameor port number are not correctly configured. See "Connection Option Descriptions" for a list of connectionstring attributes that are required for each driver to connect properly to the underlying database.

For UNIX and Linux users: See "Configuring the Product on UNIX/Linux" for more information. Seealso "The Test Loading Tool" for information about a helpful diagnostic tool.


Troubleshooting

See alsoData Source Configuration on UNIX/Linux on page 41Connection Option Descriptions on page 127Configuring the Product on UNIX/Linux on page 38The Test Loading Tool on page 116

Interoperability Issues

Interoperability issues can occur with a working ODBC application in any of the following ODBC components:ODBC application, ODBC driver, ODBC Driver Manager, and/or data source. See "What Is ODBC?" for moreinformation about ODBC components.

For example, any of the following problems may occur because of an interoperability issue:

• SQL statements may fail to execute.

• Data may be returned/updated/deleted/inserted incorrectly.

• A hang or core dump may occur.

See alsoWhat Is ODBC? on page 249

Troubleshooting the IssueIsolate the component in which the issue is occurring. Is it an ODBC application, an ODBC driver, an ODBCDriver Manager, or a data source issue?

To troubleshoot the issue:

1. Test to see if your ODBC application is the source of the problem. To do this, replace your working ODBCapplication with a more simple application. If you can reproduce the issue, you know your ODBC applicationis not the cause.

On Windows, you can use ODBC Test, which is part of the Microsoft ODBC SDK, or the exampleapplication that is shipped with your driver. See "ODBC Test" and "The example Application" for details.

On UNIX and Linux, you can use the example application that is shipped with your driver. See"The example Application" for details.

2. Test to see if the data source is the source of the problem. To do this, use the native database tools thatare provided by your database vendor.

3. If neither the ODBC application nor the data source is the source of your problem, troubleshoot the ODBCdriver and the ODBC Driver Manager.

In this case, we recommend that you create an ODBC trace log to provide to Technical Support. See "ODBCTrace" for details.

See alsoODBC Test on page 117The Example Application on page 120



ODBC Trace on page 113

Performance Issues

Developing performance-oriented ODBC applications is not an easy task.You must be willing to change yourapplication and test it to see if your changes helped performance. Microsoft’s ODBC Programmer’s Referencedoes not provide information about system performance. In addition, ODBC drivers and the ODBC DriverManager do not return warnings when applications run inefficiently.

Some general guidelines for developing performance-oriented ODBC applications include:

• Use catalog functions appropriately.

• Retrieve only required data.

• Select functions that optimize performance.

• Manage connections and updates.

See "Designing ODBC Applications for Performance Optimization" for complete information.

See alsoDesigning ODBC Applications for Performance Optimization on page 277


Troubleshooting

5Connection Option Descriptions

The following connection option descriptions are listed alphabetically by the GUI name that appears on thedriver Setup dialog box. The connection string attribute name, along with its short name, is listed immediatelyunderneath the GUI name.

In most cases, the GUI name and the attribute name are the same; however, some exceptions exist. If youneed to look up an option by its connection string attribute name, please refer to the alphabetical table ofconnection string attribute names.

Also, a few connection string attributes, for example, Password, do not have equivalent options that appearon the GUI. They are in the list of descriptions alphabetically by their attribute names.

The following table lists the connection string attributes supported by the Salesforce driver.

Table 18: Salesforce Attribute Names

DefaultAttribute (Short Name)

NoneAccessToken (AT)

1 (Enabled)ApplicationUsingThreads (AUT)

USERIDPASSWORDAuthentication Method (AM)

30000 (rows)BulkFetchThreshold (BFT)

0 (Disabled)BulkLoadAsync (BLA)

1024BulkLoadBatchSize (BLBS)

1 (Parallel)BulkLoadConcurrencyMode (BLCM)



NoneBulkLoadFieldDelimiter (BLFD)

10BulkLoadPollInterval (BLPI)

NoneBulkLoadRecordDelimiter (BLRD)

4000 (rows)BulkLoadThreshold (BLTH)

0BulkLoadTimeout (BLTO)

NoneClientID (CI)

NoneClientSecret (CS)

Empty stringConfigOptions (CFGO)

Important: The configuration options have beendeprecated. However, the driver will continue tosupport them until the next major release of the driver.

0 (Disabled)ConnectionReset (CR)

NoneCreateDB (CDB)

Note: The CreateDB option has been replaced byCreateMap.

2 (NotExist)CreateMap (CM)

NoneDataSourceName (DSN)

NoneDatabase

Note: The Database option has been replaced bySchemaMap.

NoneDescription (n/a)

1 (Enabled)EnableBulkFetch (EBF)

1 (Enabled)EnableBulkLoad (EBL)

100FetchSize (FS)

login.salesforce.comHostName (HOST)


Chapter 5: Connection Option Descriptions


4 (ISO 8559-1 Latin-1)IANAAppCodePage UNIX ONLY

Empty stringInitializationString (IS)

For the 32-bit driver when the SQL Engine Mode isset to 2 (Direct):

-Xmx256m

For all other configurations:

-Xmx1024m

JVMArgs (JVMA)

install_dir\java\lib\sforce.jarJVMClasspath (JVMC)

0LoadBalanceTimeout (LBT)

Empty stringLogConfigFile (LCF)

15LoginTimeout (LT)

NoneLogonDomain (LD)

Note: Support for the LogonDomain connection optionhas been deprecated. The full user name, includingthe domain, is now specified using the User Nameoption.

NoneLogonID (UID)

100MaxPoolSize (MXPS)

0MinPoolSize (MNPS)

NonePassword (PWD)

0 (Disabled)Pooling (POOL)

Empty stringProxyHost (PXHN)

Empty stringProxyPassword (PXPW)

Empty stringProxyPort (PXPT)

Empty stringProxyUser (PXUN)

0 (Disabled)ReadOnly (RO)



NARefreshDirtyCache (RDC)

Note: Support for the RefeshDirtyCache option hasbeen deprecated.

0 (Disabled)RefreshSchema (RS)

NoneRefreshToken (RT)

0 (Ignore Errors)ReportCodepageConversionErrors (RCCE)

For Windows:

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

For UNIX/Linux:

~/progress/datadirect/salesforce_schema/logonid.config

SchemaMap (SM)

Empty stringSecurityToken (STK)

For the 32-bit driver:

19938


19937

ServerPortNumber (SPN)

For Windows:

0 (Auto)

For UNIX/Linux:

The SQL engine runs in Direct mode by default.

SQLEngineMode (SEM)

100StmtCallLimit (SCL)

1 (ErrorAlways)StmtCallLimitBehavior (SCLB)

0 (No Transactions)TransactionMode (TM)

0WSFetchSize (WSFS)

1WSPoolSize (WSPS)




0WSRetryCount (WSRC)

120WSTimeout (WST)


• Access Token

• Application Using Threads

• Authentication Method

• Bulk Fetch Threshold

• Bulk Load Asynchronous

• Bulk Load Batch Size

• Bulk Load Concurrency Mode

• Bulk Load Poll Interval

• Bulk Load Threshold

• Bulk Load Timeout

• Client ID

• Client Secret

• Config Options

• Connection Pooling

• Connection Reset

• Create Database

• Create Map

• Data Source Name

• Database

• Description

• Enable Bulk Fetch

• Enable Bulk Load

• Enable Primary Key Chunking

• Fetch Size

• Field Delimiter

• Host Name

• IANAAppCodePage


• Initialization String

• JVM Arguments

• JVM Classpath

• LoadBalance Timeout

• Log Config File

• Login Timeout

• Logon Domain

• Max Pool Size

• Min Pool Size

• Password

• Primary Key Chunk Size

• Proxy Host

• Proxy Password

• Proxy Port

• Proxy User

• Read Only

• Record Delimiter

• Refresh Dirty Cache

• Refresh Schema

• Refresh Token

• Report Codepage Conversion Errors

• Schema Map

• Security Token

• Server Port Number

• SQL Engine Mode

• Statement Call Limit

• Statement Call Limit Behavior

• Transaction Mode

• User Name

• WSFetch Size

• WSPoolSize

• WSRetry Count

• WSTimeout



Access Token

AttributeAccessToken (AT)

PurposeSpecifies the access token required to authenticate to a Salesforce instance when OAuth 2.0 is enabled(AuthenticationMethod=oauth2.0).

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 Access Token option is not specified, the driver uses the value of the Refresh Token optionto make a connection.

• If both Access Token and Refresh Token values are not specified, the driver cannot make a successfulconnection.

• If both Access Token and Refresh Token values are specified, the driver ignores the Access Token valueand uses the Refresh Token value to generate a new Access Token value.

DefaultNone

GUI TabSecurity tab

See alsoConfiguring OAuth 2.0 authentication on page 89


Refresh Token on page 173


Access Token

Application Using Threads

AttributeApplicationUsingThreads (AUT)

PurposeDetermines whether the driver works with applications using multiple ODBC threads.

Valid Values0 | 1

BehaviorIf set to 1 (Enabled), the driver works with single-threaded and multi-threaded applications.

If set to 0 (Disabled), the driver does not work with multi-threaded applications. If using the driver withsingle-threaded applications, this value avoids additional processing required for ODBC thread-safety standards.

Notes

• This connection option can affect performance.

Default1 (Enabled)

GUI TabAdvanced tab

See alsoPerformance Considerations on page 71

Authentication Method

AttributeAuthenticationMethod (AM)

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.

DefaultuserIDPassword

GUI TabSecurity tab

See AlsoAuthentication on page 88

Bulk Fetch Threshold

AttributeBulkFetchThreshold (BFT)

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 Enable Bulk Fetch option must be set to 1 (enabled).

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 Enable Bulk Fetch option is set to 0 (disabled), the Bulk Fetch Threshold option is ignored.

• The Enable Primary Key Chunking connection option can be used to break bulk fetch operations into smaller,more manageable batches for improved performance.

Default30000 (rows)


Bulk Fetch Threshold

GUI TabBulk tab

See also

• Enable Bulk Load on page 154

• Enable Primary Key Chunking on page 155

• Statement Call Limit on page 179

Bulk Load Asynchronous

AttributeBulkLoadAsync (BLA)

PurposeDetermines whether the driver treats bulk load operations as synchronous or asynchronous.

Valid Values0 | 1

BehaviorIf set to 0 (Disabled), bulk load operations are synchronous. The driver does not return from the function thatinvoked an operation until the operation is complete or the BulkLoadTimeout period has expired. If the operationtimes out, the driver returns an error.

If set to 1 (Enabled), bulk load operations are asynchronous. The driver returns from the function that invokedan operation after the operation is submitted to the server. The driver does not verify the completion status ofthe bulk load operation.

Default0 (Disabled)

GUI TabBulk tab

See Also

• Bulk Load Timeout on page 140

• Using DataDirect Bulk Load on page 100



Bulk Load Batch Size

AttributeBulkLoadBatchSize (BLBS)

PurposeThe number of rows that the driver sends to the database at a time during bulk operations. This value appliesto all methods of bulk loading.

Valid Valuesx

where:

x

is a positive integer that specifies the number of rows to be sent.

Default1024

GUI TabBulk tab

See Also


Bulk Load Concurrency Mode

AttributeBulkLoadConcurrencyMode (BLCM)

PurposeDetermines whether multiple batches associated with a bulk load operation are processed by Salesforce inparallel or one at a time.

Valid Values0 | 1

BehaviorIf set to 0 (Serial), multiple batches associated with a bulk load operation are processed one at a time.


Bulk Load Batch Size

If set to 1 (Parallel), multiple batches associated with a bulk load operation are processed in parallel.The orderin which the batches are processed can vary.

Default1 (Parallel)

GUI TabBulk tab

See Also


Bulk Load Poll Interval

AttributeBulkLoadPollInterval (BLPI)

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 the number of seconds the driver waits before requesting bulkoperation status.

Default10

GUI TabBulk tab

See Also




Bulk Load Threshold

AttributeBulkLoadThreshold (BLTH)

PurposeDetermines when the driver uses bulk load for inserts, updates, or deletes. If the Enable Bulk Load option isset to 1 (enabled) and the number of rows affected by an insert, update, delete, or batch operation exceedsthe threshold specified by this option, the driver uses the Salesforce Bulk API to perform the operation.

Valid Values0 | x

where:

x

is a positive integer that represents a threshold (number of rows).

BehaviorIf set to 0, the driver always uses bulk load to execute inserts, updates, or deletes.

If set to x, the driver only uses bulk load if the Enable Bulk Load option is set to a value of 1 (enabled) and thenumber of rows to be updated by an inserts, updates, or deletes exceeds the threshold. If the operation timesout, the driver returns an error.

Notes

• If the Enable Bulk Load option is set to 0 (disabled), this option is ignored.

• Do not set the Bulk Load Threshold option to a value greater than the Web service call limit set by theStatement Call Limit option. If the value set for Bulk Load Threshold is greater than the value of StatementCall Limit, the driver would never use the Salesforce Bulk API because the Web service call limit is reachedbefore the driver reaches the threshold to switch to the Salesforce Bulk API.

Default4000

GUI TabBulk tab

See Also


• Statement Call Limit on page 179



Bulk Load Threshold

Bulk Load Timeout

AttributeBulkLoadTimeout (BLTO)

PurposeThe time, in seconds, that the driver waits for a Salesforce bulk job to complete. A value of zero means thereis no timeout.

Valid Valuesx

where:

x

is a positive integer that represents a number of seconds the driver waits before requesting bulkoperation status.

Default0

GUI TabBulk tab

See Also


Client ID

AttributeClientID (CI)

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.

DefaultNone

GUI TabSecurity tab



Client Secret

AttributeClientSecret (CS)

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

DefaultNone

GUI TabSecurity tab

See AlsoConfiguring OAuth 2.0 authentication on page 89



Client Secret

Config Options

Important: The configuration options have been deprecated. However, the driver will continue to support themuntil the next major release of the driver.

AttributeConfigOptions (CFGO)

PurposeDetermines how the mapping of the remote data model to the relational data model is configured, customized,and updated.

Notes

• This option 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. IfConfig Options is specified on a connection after the initial configuration, the values specified for ConfigOptions must match the values specified for the initial configuration.

Valid Values{ key = value [; key = value ]}

where:

key

is one of the following values:

• AuditColumns

• CustomSuffix

• MapSystemColumnNames

• NumberFieldMapping

• UppercaseIdentifiers

The value is a set of key value pairs separated by a semicolon (;).The value must be enclosed in curly brackets.For example:

{AuditColumns=All;CustomSuffix=strip;KeywordConflictSuffix=;MapSystemColumnNames=1;NumberFieldMapping=2;UppercaseIdentifiers=false}

Default

AuditColumns=All;CustomSuffix=Include;KeywordConflictSuffix=;MapSystemColumnNames=0;NumberFieldMapping=1;UppercaseIdentifiers=true;

GUI TabAdvanced tab



AuditColumns (Config Option)

AttributeAuditColumns

PurposeDetermines whether the driver includes audit fields, which Salesforce adds to all objects defined in a Salesforceinstance, as table columns when it defines the remote data model to relational table mapping.

The audit columns added by Salesforce are:

• IsDeleted

• CreatedById

• CreatedDate

• LastModifiedById

• LastModifiedDate

• SystemModstamp

Valid ValuesAll | AuditOnly | MasterOnly | None

The value for this option is specified as a key=value pair in the Config Options field. See "Config Options" fordetails.

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.

DefaultAll

Notes

• In a typical Salesforce instance, not all users are granted access to the Audit or MasterRecordId columns.If AuditColumns 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.

GUI TabThe value for config options are specified in the Config Options field on the Advanced tab.

See alsoConfig Options on page 142


Config Options

CustomSuffix (Config Option)

AttributeCustomSuffix

PurposeDetermines whether the driver includes or strips the _c suffix from the table and column names when mappingthe remote data model to the relational data model. Salesforce adds the suffix to all custom objects and fields.

Valid ValuesInclude | Strip

The value for this option is specified as a key=value pair in the Config Options field. See "ConfigOptions" fordetails.

BehaviorIf set to Include, the driver includes the _c suffix.

If set to Strip, the driver strips the _c suffix.

DefaultInclude


See also

• Config Options on page 142

KeywordConflictSuffix (Config 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.

The value for this option is specified as a key=value pair in the Config Options field. See "Config Options"for details.



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.

Notes

• Do 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 CASEis returned. The custom object is ignored.

DefaultEmpty string



MapSystemColumnNames (Config Option)

AttributeMapSystemColumnNames

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.


Config Options

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

The value for this config option is specified as a key=value pair in the Config Options field. See "ConfigOptions" for details.

Default0



NumberFieldMapping (Config Option)

AttributeNumberFieldMapping

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 Values1 | 2 | 3

BehaviorIf set to 1, the driver maps NUMBER fields with a precision of 9 or less and a scale of 0 to the INTEGER SQLtype and maps all other NUMBER fields to the DOUBLE SQL type.

If set to 2, the driver maps all NUMBER fields to the DOUBLE SQL type regardless of their precision.

If set to 3, the driver maps all NUMBER fields to the DECIMAL SQL type. It can be used when the precisionof the NUMBER field is greater than the precision of a DOUBLE value.

The value for this option is specified as a key=value pair in the Config Options field. See "Config Options"for details.

Default1


See also

• Config Options on page 142

UppercaseIdentifiers (Config Option)

AttributeUppercaseIdentifiers

PurposeSpecifies whether the driver maps all identifier names to uppercase.

Valid Valuestrue | false

The value for this option is specified as a key=value pair in the Config Options field. See "Config Options" fordetails.

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"


Config Options

Notes

• Do not change the value of UppercaseIdentifiers unless the data source you are connecting to has objectswith names that differ only by case.

Defaulttrue



Connection Pooling

AttributePooling (POOL)

PurposeSpecifies whether to use the driver’s connection pooling.

Valid Values0 | 1

BehaviorIf set to 1 (Enabled), the driver uses connection pooling.

If set to 0 (Disabled), the driver does not use connection pooling.

Notes

• The application must be thread-enabled to use connection pooling.


Default0 (Disabled)

GUI TabPooling tab




Connection Reset

AttributeConnectionReset (CR)

PurposeDetermines whether the state of connections that are removed from the connection pool for reuse by theapplication is reset to the initial configuration of the connection.

Valid Values0 | 1

BehaviorIf set to 1 (Enabled), the state of connections removed from the connection pool for reuse by an application isreset to the initial configuration of the connection. Resetting the state can negatively impact performancebecause additional commands must be sent over the network to the server to reset the state of the connection.

If set to 0 (Disabled), the state of connections is not reset.

Notes


Default0 (Disabled)

GUI TabPooling tab

See alsoThis connection option can affect performance. See Performance Considerations on page 71 for details.

Create Database

AttributeCreateDB (CDB)

Purpose

Note: The Create Database option has been replaced by Create Map. The CreateDB attribute will continueto be supported for this release, but will be deprecated in subsequent versions of the product.

Determines whether the driver creates a new embedded database when establishing the connection.


Connection Reset


BehaviorIf set to 0 (No), the driver uses the current schema map specified by Database. If one does not exist, theconnection fails.

If set to 1 (ForceNew), the driver deletes the current schema map specified by Database and creates a newone at the same location.

Warning: This causes all views, data caches, and map customizations defined in the current database to belost.

If set to 2 (NotExist), the driver uses the current schema map specified by Database. If one does not exist, thedriver creates one.

DefaultNone

GUI TabNone

Create Map

AttributeCreateMap (CM)

PurposeDetermines whether the driver creates a new schema map when establishing the connection.


BehaviorIf set to 0 (No), the driver uses the current schema map specified by the Schema Map option. If one does notexist, the connection fails.

If set to 1 (ForceNew), the driver deletes the current schema map specified by the Schema Map option 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 2 (NotExist), the driver uses the current schema map specified by the Schema Map option. If one doesnot exist, the driver creates one.



Default2 (NotExist)

GUI TabAdvanced tab

See also

• Schema Map on page 175

Data Source Name

AttributeDataSourceName (DSN)

PurposeSpecifies the name of a data source in your Windows Registry or odbc.ini file.

Valid Valuesstring

where:

string

is the name of a data source.

DefaultNone

GUI TabGeneral tab

Database

AttributeDatabase (DBN)


Data Source Name

Purpose

Note: The Database option has been replaced by Schema Map. The Database attribute will continue to besupported for this release, but will be deprecated in subsequent versions of the product.

Specifies the file name prefix the driver uses to create or locate the set of files that define the Object mappingand the embedded database used by the connection.

Valid Valuesprefix | path+prefix

where:

prefix

is the file name prefix for the embedded database. For example, if Database is set to a value ofJohnQPublic, the embedded database files that are created or loaded have the formjohnqpublic.xxx.

path+prefix

is a relative or absolute path appended to the file name prefix. The path defines the directory thedriver uses to store the newly created database files or locate the existing database files. For example,if Database is set to a value of C:\data\db\johnqpublic, the driver either creates or looks forthe database johnqpublic.xxx in the directory C:\data\db. If you do not specify a path, the currentworking directory is used.

Notes

• The driver parses the User ID value and removes all non-alphanumeric characters. For example, if UserID is specified as John.Q.Public, the value used for Database is JohnQPublic.

DefaultNone

GUI TabNone

See Also

• Schema Map on page 175

Description

AttributeDescription (n/a)



PurposeSpecifies an optional long description of a data source. This description is not used as a runtime connectionattribute, but does appear in the ODBC.INI section of the Registry and in the odbc.ini file.

Valid Valuesstring

where:

string

is a description of a data source.

DefaultNone

GUI TabGeneral tab

Enable Bulk Fetch

AttributeEnableBulkFetch (EBF)

PurposeSpecifies whether the driver can use the Salesforce Bulk API for selects based on the value of the Bulk FetchThreshold connection option. If the number of rows expected in the result set exceeds the value of Bulk FetchThreshold option, the driver uses the Salesforce Bulk API to execute the select operation. Using the SalesforceBulk API may significantly reduce the number of Web service calls used to execute a statement and, therefore,may improve performance.

Note:



Valid Values1 | 0

BehaviorIf set to 1, the driver can use the Salesforce Bulk API for selects based on the value of the Bulk Fetch Thresholdconnection option. If the number of rows expected in the result set exceeds the value of Bulk Fetch Thresholdoption, the driver uses the Salesforce Bulk API to execute the select operation.


Enable Bulk Fetch

If set to 0, the driver does not use the Salesforce Bulk API, and the Bulk Fetch Threshold option is ignored.

Default1

GUI TabBulk tab

See Also

• Bulk Fetch Threshold on page 135

• Performance Considerations on page 71

Enable Bulk Load

AttributeEnableBulkLoad (EBL)

PurposeSpecifies whether the driver can use the Salesforce Bulk API for inserts, updates, and deletes based on thevalue of the Bulk Load Threshold connection option. If the number of affected rows exceeds the value of BulkLoad Threshold option, the driver uses the Salesforce Bulk API to execute the insert, update, or delete operation.Using the Salesforce Bulk API may significantly reduce the number of Web service calls used to execute astatement 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 ofthe Bulk Load Threshold connection option. If the number of affected rows exceeds the value of Bulk LoadThreshold option, 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 Bulk Load Threshold option is ignored.

Default1

GUI TabBulk tab

See Also

• Bulk Load Threshold on page 139




Enable Primary Key Chunking

AttributeEnablePKChunking (EPKC)

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

BehaviorIf set to 1 (Enabled), the driver uses PK chunking for select operations when the expected number of rows inthe result set is greater than the values of the Bulk Fetch Threshold and Primary Key Chunk Size options. Forthis behavior to take effect, the Enable Bulk Fetch option must also be set to 1 (enabled).

If set to 0 (Disabled), the driver does not use PK chunking when executing select operations, and the PrimaryKey Chunk Size option 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.

Default1 (Enabled)

GUI TabBulk tab

See Also


• Primary Key Chunk Size on page 167



Fetch Size

AttributeFetchSize (FS)


Enable Primary Key Chunking

PurposeSpecifies the maximum number of rows that the driver processes before returning data to the application.Smaller fetch sizes can improve the initial response time of the query. Larger fetch sizes improve overall fetchtimes at the cost of additional memory.

FetchSize is related to, but different than, WSFetchSize. WSFetchSize specifies the number of rows of rawdata that the driver fetches from the remote data source, while FetchSize specifies how many of these rawdata rows the driver processes before returning data to the application. Processing the data includes convertingfrom the remote data source data type to the driver SQL data type used by the application. If FetchSize isgreater than WSFetchSize, the driver makes multiple round trips to the data source to get the requested numberof rows before returning control to the application.

Valid Values0 | x

where:

x

is a positive integer.

BehaviorIf set to 0, the driver fetches and processes all of the rows of the result before returning control to the application.

If set to x, the driver fetches and processes the specified number of rows before returning data to the application.

Notes

• WSFetchSize and FetchSize 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.

Default100

GUI TabAdvanced tab

See Also

• WSFetch Size on page 181

Field Delimiter

AttributeBulkLoadFieldDelimiter (BLFD)

PurposeSpecifies the character that the driver will use to delimit the field entries in a bulk load data file.



Valid Valuesx

where:

x

is any printable character.

For simplicity, avoid using a value that can be in the data, including all alphanumeric characters, the dash(-),the colon(:), the period (.), the forward slash (/), the space character, the single quote (') and the double quote(").You can use some of these characters as delimiters if all of the data in the file is contained within doublequotes.

Notes

• The Bulk Load Field Delimiter character must be different from the Bulk Load Record Delimiter.

DefaultNone

GUI TabBulk tab

See Also


Host Name

AttributeHostName (HOST)

PurposeThe base Salesforce URL or IP address of your Salesforce instance. If you are logging into a Salesforceinstance other than the default, you must provide the root of the Salesforce URL or IP address.

Valid Valuesurl | ip_address

where:

url

is the is the root of the Salesforce URL to which you want to connect.

ip_address

is the is the IP address of the Salesforce instance to which you want to connect.


Host Name

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 HostName attribute to connect to the productioninstance or test.salesforce.com to connect to the sandbox instance:

URLSalesforce Instance

login.salesforce.comProduction

test.salesforce.comSandbox

Defaultlogin.salesforce.com

GUI TabGeneral tab

IANAAppCodePage

AttributeIANAAppCodePage (IACP)

PurposeAn Internet Assigned Numbers Authority (IANA) value.You must specify a value for this option if your applicationis not Unicode enabled or if your database character set is not Unicode. See for details.

The driver uses the specified IANA code page to convert "W" (wide) functions to ANSI.

The driver and Driver Manager both check for the value of IANAAppCodePage in the following order:

• In the connection string

• In the Data Source section of the system information file (odbc.ini)

• In the ODBC section of the system information file (odbc.ini)

If the driver does not find an IANAAppCodePage value, the driver uses the default value of 4 (ISO 8859-1Latin-1).

Valid ValuesIANA_code_page

where:

IANA_code_page

is one of the valid values listed in “Values for the Attribute IANAAppCodePage" in "IANAAppCodePageValues." The value must match the database character encoding and the system locale.



Default4 (ISO 8559-1 Latin-1)

GUI TabNA

See Also

• Internationalization, Localization, and Unicode on page 267

• IANAAppCodePage Values on page 251

Initialization String

AttributeInitializationString (IS)

PurposeOne or multiple SQL commands to be executed by the driver after it has established the connection to thedatabase and has performed all initialization for the connection. If the execution of a SQL command fails, theconnection attempt also fails and the driver returns an error indicating which SQL command or commandsfailed.

Valid Valuesstring

where:

string

is one or multiple SQL commands.

Multiple commands must be separated by semicolons. In addition, if this option 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 MAP command in the connection URL. For example:

DSN=Salesforce;UID={[email protected]};PWD=secret;InitializationString=(REFRESH MAP)

DefaultNone


Initialization String

GUI TabAdvanced tab

JVM Arguments

AttributeJVMArgs (JVMA)

PurposeA string that contains the arguments that are passed to the JVM that the driver is starting. The location of theJVM must be specified on the driver library path. For information on setting the location of the JVM in yourenvironment, see:

• Setting the Library Path Environment Variable (Windows) on page 32

• Setting the Library Path Environment Variable (UNIX and Linux) on page 35.

When specifying the heap size for the JVM, note that the JVM tries to allocate the heap memory as a singlecontiguous range of addresses in the application’s memory address space. If the application's address spaceis fragmented so that there is no contiguous range of addresses big enough for the amount of memory specifiedfor the JVM, the driver fails to load, because the JVM cannot allocate its heap. This situation is typicallyencountered only with 32-bit applications, which have a much smaller application address space. If you encounterproblems with loading the driver in an application, try reducing the amount of memory requested for the JVMheap. If possible, switch to a 64-bit version of the application.

Valid Valuesstring

where:

string

contains arguments that are defined by the JVM. Values that include special characters or spacesmust be enclosed in curly braces { } when used in a connection string.

ExampleTo set the heap size used by the JVM to 256 MB and the http proxy information, specify:

{-Xmx256m -Dhttp.proxyHost=johndoe -Dhttp.proxyPort=808}

To set the heap size to 256 MB and configure the JVM for remote debugging, specify:

{-Xmx256m -Xrunjdwp:transport=dt_socket, address=9003,server=y,suspend=n -Xdebug}

DefaultFor the 32-bit driver when the SQL Engine Mode connection option is set to 2 (Direct):

-Xmx256m

For all other configurations:

-Xmx1024m



GUI TabSQL Engine tab

JVM Classpath

AttributeJVMClasspath (JVMC)

PurposeSpecifies the CLASSPATH for the Java Virtual Machine (JVM) used by the driver. The CLASSPATH is thesearch string the JVM uses to locate the Java jar files the driver needs.

Valid Valuesstring

where:

string

specifies the CLASSPATH. Separate multiple jar files by a semi-colon on Windows platforms andby a colon on Linux and UNIX platforms. CLASSPATH values with multiple jar files must be enclosedin curly braces { } when used in a connection string.

If your process employs multiple drivers that use a JVM, the value of the JVM Classpath for allaffected drivers must include an absolute path to all the jar files for drivers used in that process. Inaddition, the value specified must be identical for all drivers. For example, if you are using theSalesforce and MongoDB drivers on Windows, you would specify a value of{c:\install_dir\java\lib\sforce.jar; c:\install_dir\java\lib\mongodb.jar}for both drivers. If the value for any of the affected drivers is missing a file path or is different fromthe one specified for the other drivers, the drivers will return an error at connection that the JVM isalready running.

ExampleOn Windows:

{.;c:\install_dir\java\lib\sforce.jar}

On UNIX:

{.:/home/user1/install_dir/java/lib/sforce.jar}

Defaultinstall_dir\java\lib\sforce.jar



JVM Classpath

LoadBalance Timeout

AttributeLoadBalanceTimeout (LBT)

PurposeSpecifies the number of seconds to keep inactive connections open in a connection pool. An inactive connectionis a database session that is not associated with an ODBC connection handle, that is, a connection in the poolthat is not in use by an application.

Valid Values0 | x

where:

x

is a positive integer that specifies a number of seconds.

BehaviorIf set to 0, inactive connections are kept open.

If set to x, inactive connections are closed after the specified number of seconds passes.

Notes

• The Min Pool Size option may cause some connections to ignore this value.


Default0

GUI TabPooling tab


Log Config File

AttributeLogConfigFile (LCF)



PurposeSpecifies the filename of the configuration file used to initialize the driver logging mechanism.

If the driver cannot locate the specified file when establishing the connection, the connection fails and the driverreturns an error.

Valid Valuesstring

where:

string

is the relative or fully qualified path of the configuration file used to initialize the driver loggingmechanism. If the specified file does not exist, the driver continues searching for an appropriateconfiguration file as described in "Logging".

DefaultEmpty string

GUI TabAdvanced tab

See Also

• Logging on page 117

Login Timeout

AttributeLoginTimeout (LT)

PurposeThe number of seconds the driver waits for a connection to be established before returning control to theapplication and generating a timeout error. To override the value that is set by this connection option for anindividual connection, set a different value in the SQL_ATTR_LOGIN_TIMEOUT connection attribute usingthe SQLSetConnectAttr() function.

Valid Values0 | x

where:

x

is a positive integer that specifies a number of seconds.

BehaviorIf set to 0, inactive connections are kept open.


Login Timeout

If set to x, inactive connections are closed after the specified number of seconds passes.

Default15

GUI TabAdvanced tab

Logon Domain

AttributeLogonDomain (LD)

Purpose

Note: The Logon Domain connection option has been deprecated. As a result, the user name option has beenenhanced to accept the complete Salesforce user id value, including the domain.

Specifies the domain part of the Salesforce user id. If Logon Domain is not an empty string, the driver firstappends the @ character to the end of the User Name value and then appends the value of Logon Domain.

Valid Valuesstring

where:

string

is a valid user ID domain.

DefaultNone

GUI TabNone

See also

• User Name on page 181

Max Pool Size

AttributeMaxPoolSize (MXPS)



PurposeThe maximum number of connections allowed within a single connection pool. When the maximum number ofconnections is reached, no additional connections can be created in the connection pool.

Valid ValuesAn integer from 1 to 65535

For example, if set to 20, the maximum number of connections allowed in the pool is 20.

NotesThis connection option can affect performance.

Default100

GUI TabPooling tab


Min Pool Size

AttributeMinPoolSize (MNPS)

PurposeSpecifies the minimum number of connections that are opened and placed in a connection pool, in addition tothe active connection, when the pool is created. The connection pool retains this number of connections, evenwhen some connections exceed their Load Balance Timeout value.

Valid Values0 | x

where:

x

is an integer from 1 to 65535.

For example, if set to 5, the start-up number of connections in the pool is 5 in addition to the current existingconnection.

BehaviorIf set to 0, no connections are opened in addition to the current existing connection.


Min Pool Size

Notes


Default0

GUI TabPooling tab

See AlsoSee Performance Considerations on page 71 for details.

Password

AttributePassword (PWD)

PurposeSpecifies the password to use to connect to your Salesforce instance. A password is required. Contact yoursystem administrator to obtain your password.

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

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.

Optionally, you can specify the security token in the Security Token option. Do not specify the security tokenin both options.

DefaultNone



GUI TabLogon dialog

See alsoSecurity Token on page 176

Primary Key Chunk Size

AttributePKChunkSize (PKCS)

PurposeSpecifies the size, in rows, of a primary key (PK) chunk when PK chunking has been enabled via the EnablePrimary Key Chunking option. The Salesforce Bulk API splits the query into chunks of this size.

Valid Valuesx

where:

x

is a positive integer less than or equal to 250,000 rows. The driver requests, via the Salesforce BulkAPI, 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. Primary Key Chunk Size may be set to a maximumvalue of 250,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 Bulk Fetch Threshold and Primary Key Chunk Size options.

Default100000 (rows)

GUI TabBulk tab

See Also

• Enable Primary Key Chunking on page 155



Primary Key Chunk Size

Proxy Host

AttributeProxyHost (PXHN)

PurposeSpecifies the Hostname of the Proxy Server. The value specified can be a host name, a fully qualified domainname, or an IPv4 or IPv6 address.

Valid Valuesserver_name | IP_address

where:

server_name

is the name of the server or a fully qualified domain name to which you want to connect.

The IP address can be specified in either IPv4 or IPv6 format, or a combination of the two. See"Using IP Addresses" for details about these formats.

DefaultEmpty string


See Also

• Using IP Addresses on page 96

Proxy Password

AttributeProxyPassword (PXPW)

PurposeSpecifies the password needed to connect to the Proxy Server.

Valid ValuesString

where:



String

specifies the password to use to connect to the Proxy Server. Contact your system administrator toobtain your password.

DefaultEmpty string


Proxy Port

AttributeProxyPort (PXPT)

PurposeSpecifies the port number where the Proxy Server is listening for HTTP and/or HTTPS requests.

Valid Valuesport_name

where:

port_name

is the port number of the server listener. Check with your system administrator for the correct number.

DefaultNone


Proxy User

AttributeProxyUser

PurposeSpecifies the user name needed to connect to the Proxy Server.


Proxy Port

Valid ValuesThe default user ID that is used to connect to the Proxy Server.

DefaultEmpty string


Read Only

AttributeReadOnly (RO)

PurposeSpecifies whether the connection has read-only access to the data source.

Valid Values0 | 1

BehaviorIf set to 1 (Enabled), the connection has read-only access. The following commands are the only commandsthat you can use when a connection if read-only:

• Call (if the procedure does not update data)

• Explain Plan

• Select (except Select Into)

• Set Schema

The driver returns an error if any other command is executed.

If set to 0 (Disabled), the connection is opened for read/write access, and you can use all commands supportedby the product.

Default0 (Disabled)

GUI TabAdvanced tab



Record Delimiter

AttributeBulkLoadRecordDelimiter (BLRD)

PurposeSpecifies the character that the driver will use to delimit the record entries in a bulk load data file.

Valid Valuesx

where:

x

is any printable character.

For simplicity, avoid using a value that can be in the data, including all alphanumeric characters, the dash(-),the colon(:), the period (.), the forward slash (/), the space character, the single quote (') and the double quote(").You can use some of these characters as delimiters if all of the data in the file is contained within doublequotes.

Notes

• The Bulk Load Record Delimiter character must be different from the Bulk Load Field Delimiter.

DefaultNone

GUI TabBulk tab

See Also


Refresh Dirty Cache

AttributeRefreshDirtyCache (RDC)


Record Delimiter

Purpose

Note: The Refresh Dirty Cache option has been deprecated. Now, for every fetch operation, the driver refreshesthe cached object to pick up changes made to tables and rows.

Specifies whether the driver refreshes a dirty cache on the next fetch operation from the cache. A cache ismarked as dirty when a row is inserted into or deleted from a cached table or a row in the cached table isupdated.

Valid Values1 | 0

BehaviorIf set to 1 (Enabled), a dirty cache is refreshed when the cache is referenced in a fetch operation. The cachestate is set to initialized if the refresh succeeds.

If set to 0 (Disabled), a dirty cache is not refreshed when the cache is referenced in a fetch operation.

DefaultNA

GUI TabAdvanced tab

See alsoRefreshing Cache Data on page 80

Refresh Schema

AttributeRefreshSchema (RS)

PurposeDetermines whether the driver automatically refreshes the information in a remote schema (rebuilds the schemamap for the schema) the first time a user connects to the specified embedded database. The database isopened when the user first makes a connection with the application.When all connections associated with thatuser are closed, then the driver closes the database. The database must be reopened before it can be usedagain.

Valid Values1 | 0

BehaviorIf set to 1 (Enabled), the driver automatically refreshes the schema the first time a user connects to the specifieddatabase. Any schema objects that have changed since the last time the schema map was rebuilt are reflectedin the metadata.



If set to 0 (Disabled), the driver does not automatically refresh the schema the first time a user connects to thespecified database.

Notes

• This connection option is functionally equivalent to executing the Refresh Map statement (see to "RefreshMap (EXT)").You can refresh a schema manually at any time by using the Refresh Map statement.

Default0 (Disabled)

GUI TabAdvanced tab

See Also

• Refresh Map (EXT) on page 224

Refresh Token

AttributeRefreshToken (RT)

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 Access Token option is not specified, the driver uses the value of the Refresh Token optionto make a connection.

• If both Access Token and Refresh Token values are not specified, the driver cannot make a successfulconnection.

• If both Access Token and Refresh Token values are specified, the driver ignores the Access Token valueand uses the Refresh Token value to generate a new Access Token value.


Refresh Token

DefaultNone

GUI TabSecurity tab



Access Token on page 133

Report Codepage Conversion Errors

AttributeReportCodepageConversionErrors (RCCE)

PurposeSpecifies how the driver handles code page conversion errors that occur when a character cannot be convertedfrom one character set to another.

An error message or warning can occur if an ODBC call causes a conversion error, or if an error occurs duringcode page conversions to and from the database or to and from the application.The error or warning generatedis Code page conversion error encountered. In the case of parameter data conversion errors, thedriver adds the following sentence:Error in parameter x, where x is the parameter number.The standardrules for returning specific row and column errors for bulk operations apply.


BehaviorIf set to 0 (Ignore Errors), the driver substitutes 0x1A for each character that cannot be converted and doesnot return a warning or error.

If set to 1 (Return Error), the driver returns an error instead of substituting 0x1A for unconverted characters.

If set to 2 (Return Warning), the driver substitutes 0x1A for each character that cannot be converted and returnsa warning.

Default0 (Ignore Errors)

GUI TabAdvanced tab



Schema Map

AttributeSchemaMap (SM)

PurposeSpecifies either the name or the absolute path and name of the configuration file where the relational map ofnative data is written. The driver looks for this file when connecting to a Salesforce instance. If the file doesnot exist, the driver creates one.

Valid Valuesstring

where:

string

is either the name or the absolute path and name (including the .config extension) of theconfiguration file. For example, if Schema Map is set to a value of:

• ABC, the driver either creates or looks for the configuration file ABC in the user's home directory,provided the HOME environment variable has been set.

• C:\Users\Default\AppData\Local\Progress\DataDirect\Salesforce_Schema\[email protected],the driver either creates or looks for the configuration file [email protected] in thedirectoryC:\Users\Default\AppData\Local\Progress\DataDirect\Salesforce_Schema.

Notes

• If using OAuth 2.0 authentication, a value for the Schema Map option 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 a schema map using the name and location you haveprovided. If you do not provide a name and location, the driver creates one 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.


Schema Map

DefaultThe default value is determined by the User Name connection option, platform, and data source type. Thefollowing is a list of default values by platform:

• Windows platforms:

• User Data Source:

user_profile\AppData\Local\Progress\DataDirect\Salesforce_Schema\user_name.config

• System Data Source:

C:\Users\Default\AppData\Local\Progress\DataDirect\Salesforce_Schema\user_name.config

• UNIX/Linux:

~/progress/datadirect/salesforce_schema/LogonID.config

GUI TabGeneral tab

See Also

• Refresh Map (EXT) on page 224

• User Name on page 181

• Configuring OAuth 2.0 authentication on page 89

Security Token

AttributeSecurityToken (STK)

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.

Optionally, you can specify the security token in the Password option by appending the security token to thepassword, for example, secretXaBARTsLZReM4Px47qPLOS. Do not specify the security token in both options.



Notes

• When setting the security token using a data source on Windows, the Security Token option is encrypted.

DefaultEmpty string

GUI TabGeneral tab

Server Port Number

AttributeServerPortNumber (SPN)

PurposeSpecifies a valid port on which the SQL engine listens for requests from the driver.

Valid Valuesport_name

where:

port_name

is the port number of the server listener. Check with your system administrator for the correct number.

Notes

• This option is ignored when SQL Engine Mode is set to 2 (Direct).

DefaultFor the 32-bit driver:

19938


19937



Server Port Number

SQL Engine Mode

AttributeSQLEngineMode (SEM)

PurposeSpecifies whether the driver’s SQL engine runs in the same 32-bit process as the driver (direct mode) or runsin a process that is separate from the driver (server mode).You must be an administrator to modify the servermode configuration values, and to start or stop the SQL engine service.


BehaviorIf set to 0 (Auto), the SQL engine attempts to run in server mode first; however, if server mode is unavailable,it runs in direct mode. To use server mode with this value, you must start the SQL Engine service before usingthe driver (see "Starting the SQL Engine Server" for more information).

If set to 1 (Server), the SQL engine runs in server mode.The SQL engine operates in a separate process fromthe driver within its own JVM.You must start the SQL Engine service before using the driver (see "Starting theSQL Engine Server" for more information).

If set to 2 (Direct), the SQL engine runs in direct mode. The driver and its SQL engine run in a single processwithin the same JVM.

Important: Changes you make to the server mode configuration affect all DSNs sharing the service.

DefaultFor Windows:

0 (Auto)

For UNIX/Linux:

2 (Direct)


See Also

• Starting the SQL Engine Server on page 75



Statement Call Limit

AttributeStmtCallLimit (SCL)

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 the StmtCall Limit Behavior option.

Default100 (Web service calls)

GUI TabWeb Service tab

Statement Call Limit Behavior

AttributeStmtCallLimitBehavior (SCLB)


Statement Call Limit

PurposeSpecifies the behavior of the driver when the maximum Web service call limit specified by the Statement CallLimit option is exceeded.

Valid Values1 | 2

BehaviorIf set to 1 (ErrorAlways), the driver returns an error if the maximum Web service call limit is exceed.

If set to 2 (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.

Default1 (ErrorAlways)


Transaction Mode

AttributeTransactionMode (TM)

PurposeSpecifies how the driver handles manual transactions.

Valid Values0 | 1

BehaviorIf set to 1 (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 return an error indicating that no transaction is started. Metadata indicatesthat the driver supports transactions and the ReadUncommitted transaction isolation level.

If set to 0 (No Transactions), the data source and the driver do not support transactions. Metadata indicatesthat the driver does not support transactions.

Default0 (No Transactions)

GUI TabAdvanced tab



User Name

AttributeLogonID (UID)

PurposeThe default user ID, including the domain, that is used to connect to your the Salesforce instance.Your ODBCapplication may override this value or you may override it in the logon dialog box or connection string.

Valid Valuesuserid

where:

userid

is a valid user ID with permissions to access the database.

[email protected]

DefaultNone

GUI TabGeneral tab

WSFetch Size

AttributeWSFetchSize (WSFS)

PurposeSpecifies the number of rows of data the driver attempts to fetch for each ODBC call.

Valid Values0 | x

where:

x

is a positive integer from 1 to 2000 that defines a number of rows.


User Name

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.

Notes

• WSFetchSize and FetchSize 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.

Default0 (up to a maximum of 2000 rows)


See alsoFetch Size on page 155

WSTimeout on page 184

WSPoolSize

AttributeWSPoolSize (WSPS)

PurposeSpecifies the maximum number of Salesforce sessions the driver uses. This allows the driver to have multipleweb service requests active when multiple ODBC 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 option. 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 ODBCdriver; then, open a new ODBC Salesforce connection with desired limit specified for this option.

Default1



WSRetry Count

AttributeWSRetryCount (WSRC)

PurposeThe 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 (WST) connection option.

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.

Default0


See alsoWSTimeout on page 184


WSRetry Count

WSTimeout

AttributeWSTimeout (WST)

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 (WSRC) is set to retry timed-out requests, the driver retriesthe request the specified number of times.

Default120 (seconds)


See alsoWSRetry Count on page 183



6Supported SQL Statements and Extensions

The Salesforce driver provides support for the SQL statements and the SQL extensions described in thischapter. SQL extensions 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)

PurposeThe Alter Cache statement changes the definition of a cache on a remote table or view. An error is returned ifthe remote table or view specified 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 188Referencing Clause on page 198Refresh Interval Clause on page 199Initial Check Clause on page 199Persist Clause on page 200Enabled Clause on page 200Call Limit Clause on page 201Filter Clause on page 202


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

PurposeThe Alter Index statement changes the name of an existing index. Index names must not conflict with otheruser-defined or system-defined names.

SyntaxALTER INDEX index_name RENAME TO new_name

where:

index_name

specifies an existing index name.

new_name

specifies the new index name.

Alter Sequence

PurposeThe Alter Sequence statement resets 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").

Notes

• Indexes on remote tables cannot be created, altered or dropped. Indexes can only be defined on local tablesby the driver.

See alsoNext Value For Clause on page 204

Alter Session (EXT)

PurposeThe Alter Session statement changes various attributes of a database session or a remote session. A databasesession maintains the state of the overall connection. A remote session maintains the state that pertains to aparticular 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 database sessions orremote sessions.

value

refers to the specific value setting for that attribute.

The following table lists the database and remote session attributes, and provides their descriptions.

Table 20: Alter Session Attributes

DescriptionSession TypeAttribute Name

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

ALTER SESSION SET CURRENT_SCHEMA=sforce

DatabaseCurrent_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 hasthe same effect as setting the StmtCallLimit connection option. 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=10

DatabaseStmt_Call_Limit

Resets the Web service call count of a remote session to the valuespecified. The value must be zero or a positive integer.WS_Call_Count represents the total number of Web service callsmade to the remote data source instance for the current session. Forexample:

ALTER SESSION SET sforce.WS_CALL_COUNT=0

The current value of WS_Call_Count can be obtained by referringto the System_Remote_Sessions system table (see"SYSTEM_REMOTE_SESSIONS Catalog Table" for details). Forexample:

SELECT * FROMinformation_schema.system_remote_sessions WHEREsession_id = cursessionid()

RemoteWs_Call_Count

See alsoSYSTEM_REMOTE_SESSIONS Catalog Table on page 84

Alter Table

PurposeThe 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

SyntaxALTER 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 "Add Clause: Constraints" for a complete explanation.

drop_clause

specifies a column to be dropped from the table. See "Add Clause Columns" for a completeexplanation.

Notes

• You cannot drop a constraint from a remote table.

See alsoAdd Clause: Columns on page 191Add Clause: Constraints on page 192Drop Clause: Columns on page 192

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 table. It defines a column with the same syntax as the Create Table command(see "Column Definition for Remote Tables").

SyntaxADD [COLUMN] column_nameDatatype ... [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.


Alter Table

• 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 test ADD COLUMN deptId TEXT(18)

See alsoColumn Definition for Remote Tables on page 205

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 "Create Table").

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.

Example AAssuming 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)

See alsoCreate Table on page 204

Drop Clause: Columns

PurposeUse the Drop clause to drop a column from an existing table. It is optional.

SyntaxDROP {[COLUMN] column_name | [CONSTRAINT] constraint_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.

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

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 194Add Clause: Constraints on page 194Drop Clause: Columns on page 195Drop Clause: Constraints on page 195Rename Clause on page 196


Alter Table

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.

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

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 212

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:


Alter Table

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.

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 198Referencing Clause on page 198


Create Cache (EXT)

Refresh Interval Clause on page 199Initial Check Clause on page 199Persist Clause on page 200Enabled Clause on page 200Call Limit Clause on page 201Filter Clause on page 202

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

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.


Create Cache (EXT)

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.

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.


Notes

• The call limit for a cache is independent of the Stmt_Call_Limit set on a database session. See "Alter Session(EXT)" for details.


Create Cache (EXT)

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 189

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:

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 230

Create Index

PurposeThe Create Index statement creates 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

PurposeThe Create Sequence statement creates an auto-incrementing sequence for a local table.


Create Index

SyntaxCREATE SEQUENCE sequence_name [AS {INTEGER | BIGINT}] [START WITH start_value] [INCREMENTBY 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

PurposeUse the Next Value For clause to specify the next value for a sequence that is used in a Select, Insert, orUpdate statement.

SyntaxNEXT VALUE FOR sequence_name

where:

sequence_name

specifies the name of the sequence from which to retrieve the value.

ExampleThe following example retrieves the next value or set of values in Sequence1:

SELECT NEXT VALUE FOR Sequence1 FROM Account

Create Table• For information on creating remote tables, see "Altering a Remote Table."

• For information on creating local tables, see "Creating a Local Table."



Creating a Remote Table

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

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 189Column Definition for Remote Tables on page 205Constraint Definition for Remote Tables on page 207

Column Definition for Remote Tables

PurposeDefines the syntax to define a column for remote tables.

Syntaxcolumn_name Datatype [(precision[,scale])...] [DEFAULTdefault_value][[NOT]NULL][EXT_ID][PRIMARY KEY] [START WITH starting_value]

where:


Create Table

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" for a list of supported Salesforce datatypes.You cannot specify ANYTYPE, BINARY, COMBOBOX, ENCRYPTEDTEXT, or TIME datatypes in the column definition of Create Table statements.

precision

is the total number of digits for DECIMAL columns, the number of seconds for DATETIME columns,and the length of HTML, LONGTEXTAREA, and TEXT columns.

scale

is the number of digits to the right of the decimal point for DECIMAL columns.

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 also use thefollowing 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.

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)

See alsoData Types on page 28

Constraint Definition for Remote Tables

PurposeDefines the syntax to define 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 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)


Create Table


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 208

Foreign Key Clause

PurposeDefines the syntax to specify a foreign key for a constraint.

SyntaxFOREIGN 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 "Column Definition for Remote Tables". For the operation to succeed, the data type ofthe deptId column must be the 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))

See alsoColumn Definition for Remote Tables on page 205

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 database session. When the database is closed, the data for the memory table ispersisted to disk.

DISK

creates the new table on disk. A disk table caches a portion of its data in memory and the remainingdata on disk.

TEMPORARY and TEMP

are equivalent and create the new table as a global temporary table.The GLOBAL qualifier is optional.The definition of a global temporary table is visible to all connections. The data written to a globaltemporary table is visible only to the connection used to write the data.


Create Table

Note: If MEMORY, DISK, or TEMPORARY/TEMP is not specified, the new table is created inmemory.

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.

See alsoColumn Definition for Local Tables on page 210Constraint Definition for Local Tables on page 212

Column Definition for Local Tables

PurposeUse the following syntax to define 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.

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 ofseconds 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 used isCURRENT_USER.

• For datetime columns, a single-quoted Date, Time, or Timestamp value or NULL.You can also use thefollowing 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

defines an auto-increment column. Either clause can be specified only on INTEGER or 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

CREATE TABLE Test (id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 2,INCREMENT BY 2), name VARCHAR(30))

See alsoData Types on page 28

Constraint Definition for Local Tables

PurposeDefines the syntax to define 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 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 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



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


Create Table


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}]

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

is a clause that defines the operation performed when a row in the table referenced by a foreign keyconstraint is deleted. One of the following operators must be specified in the On Delete clause:

where:

• CASCADE specifies that all rows in the foreign key table that reference the deleted row in theprimary key table are also deleted.

• SET DEFAULT specifies that the value of the foreign key column is set to the column defaultvalue for all rows 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 theforeign key table that reference the deleted row in the primary key table.

ON UPDATE

is a clause that defines the operation performed when the primary key of a row in the table referencedby a foreign key constraint is updated. One of the following operators must be specified in the OnUpdate clause:

• CASCADE specifies that the value of the foreign key column for all rows in the foreign key tablethat reference the row in the primary key table that had the primary key updated are updated withthe new primary key value.

• SET DEFAULT specifies that the value of the foreign key column is set to the column defaultvalue for all rows in the foreign key table that reference the row that had the primary key updatedin the primary key table.

• SET NULL specifies that the value of the foreign key column is set to NULL for all rows in theforeign key table 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, FOREIGNKEY(deptId) REFERENCES dept(id)) ON DELETE SET NULL)

See alsoForeign Key Clause on page 208


Create Table

Create View

PurposeThe Create View statement creates a new view. A view is analogous to a named query. The view's query canrefer to any combination of remote and local tables as well as other views. Views are read-only; they cannotbe 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. A Select statement is stored in the database; however, the dataaccessible through a view is not stored in the database. The result set of the Select statement forms thevirtual table returned by the view.You can use this virtual table by referring to the view name in SQLstatements the same way you refer to a table. A view is used to perform any or all of these 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 database tables to presenta virtual table 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 the following 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 224

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.


Delete

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 230

Drop Cache (EXT)

PurposeThe Drop Cache statement drops the cache defined on a remote table.To drop a relational cache, the specifiedtable must be the primary table of the relational cache. If a relational cache is specified, the cache for theprimary table and all referenced caches 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

PurposeThe Drop Index statement drops 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.

Notes

• Indexes on a remote table cannot be dropped. Only indexes on local tables can be created, altered, anddropped.

Drop Sequence

PurposeThe Drop Sequence statement drops a sequence for local tables.

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.


Drop Index

RESTRICT

is in effect by default, meaning that the drop fails if any view refers to the sequence.

CASCADE

silently drops all dependent database objects.

Drop Table

PurposeThe Drop Table statement drops (removes) a remote or local table, its data, and its indexes. A remote table isa Salesforce object and is exposed in the SFORCE schema. Dropping a table in the SFORCE schema dropsa remote table. A local table is maintained by the driver and is local to the machine on which the driver isrunning. A local table is exposed in the PUBLIC schema. Dropping a table in the PUBLIC schema drops a localtable.

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 are dropped also.

Drop View

PurposeThe Drop View statement drops 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

PurposeThe Explain Plan statement can be used with any query to retrieve a detailed list of the elements in the executionplan. Explain Plan generates a result set with a single column named OPERATION. The individual elementsthat comprise the plan are returned as rows in the result set.

SyntaxEXPLAIN PLAN FOR {SELECT ... | DELETE ... | INSERT ... | UPDATE ...}

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.


Explain Plan

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 237Select on page 224

Specifying an External ID Column

To specify an external ID column to look up the value of a foreign key column, use the following syntax:

column_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 AThe following example uses a list of expressions to insert records. Each Insert statement adds one record tothe database table. In this case, one record is added to the table emp. Values are specified for five columns.The remaining columns in the table are assigned the default value or NULL if no default value is specified.

INSERT INTO emp (last_name, first_name, emp_id, salary, hire_date)VALUES ('Smith', 'John', 'E22345', 27500, {1999-04-06})

Example BThe following example uses a Select statement to insert records. The number of columns in the result of theSelect statement must match exactly the number of columns in the table if no column list is specified, or it mustmatch the number of column names specified in the column list. A new entry is created in the table for everyrow of the Select result.

INSERT INTO emp1 (first_name, last_name, emp_id, dept, salary)SELECT first_name, last_name, emp_id, dept, salary FROM empWHERE dept = 'D050'

Example CThe following example uses a list of expressions to insert records and specifies an external ID column (a foreignkey column) 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)

PurposeThe Refresh Cache statement forces the data in the cache for the specified remote table to be refreshed.

SyntaxREFRESH CACHE ON {remote_table | ALL} [CLEAN]

where:


Refresh Cache (EXT)

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 table must be mapped in the specifiedschema, and you must have the privilege to insert, update, and delete 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 map 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 Clause" for acomplete explanation.

from_clause

specifies one or more tables on which the other clauses in the query operate. See "From Clause"for a complete 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.

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

See alsoSelect Clause on page 226From Clause on page 228Where Clause on page 230Group By Clause on page 231Having Clause on page 231Union Operator on page 232Intersect Operator on page 232Except and Minus Operators on page 233Order By Clause on page 234Limit Clause on page 235

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 236Aggregate Functions on page 227

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 column expression canbe preceded by the DISTINCT operator.The DISTINCT operator eliminates duplicate values from an aggregateexpression.

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

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

MAX


Select

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

MIN

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

SUM

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

COUNT (DISTINCT last_name)

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

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.

See alsoSubquery in a From Clause on page 230

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.


Select

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 alsoFor more information about subqueries, see "Subqueries".

See alsoSubqueries on page 244

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 244SQL Expressions on page 236



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.

See alsoSubqueries on page 244SQL Expressions on page 236

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.


Select

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

See alsoSQL Expressions on page 236Subqueries on page 244

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

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.


Select

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

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.


Update

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

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 244Where Clause on page 230

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 or more ASCII alphanumeric characters. Unquoted identifiersare 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.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


SQL Expressions

ExampleLiteral SyntaxSQL Type

0.25

3.1415

-7.48

n.f

where:

n

is the integral part

f

is the fractional part

DECIMAL

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

n.fEx

where:

n is the integral part

f is the fractional part

x is the exponent

DOUBLE

12 or -34 or 0n

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

INTEGER

'000482ff''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'). Review this section.

• The format for a Date literal is DATE'yyyy-mm-dd'.

• The format for a Time literal is TIME'hh:mm:ss'.

• The format for a Timestamp literal is TIMESTAMP'yyyy-mm-dd hh:mm:ss.SSSSSS'.

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


SQL Expressions

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.

+ -

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 Salesforce driver considers the UNKNOWN resultas 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%\_%' 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 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 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


SQL Expressions

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

Table 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



OperatorPrecedence

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 Salesforce driver supports a number of functions that you can use in expressions, as listed and describedin "Scalar Functions."

See alsoScalar Functions on page 259

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


SQL Expressions

DescriptionCondition

Tests for membership in a list or subquery.

[NOT] IN

Membership

Tests for inclusion in a range.

[NOT] BETWEEN

Range

Tests for nulls.

IS NULL, IS NOT NULL

NULL

Tests for existence of rows in a subquery.

[NOT] EXISTS

EXISTS

Specifies a test involving pattern matching.

[NOT] LIKE

LIKE

Specifies a combination of other conditions.

CONDITION [AND/OR] CONDITION

Compound

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

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

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

IN Predicate

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

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

OR

value [NOT] IN (subquery)



ExampleSELECT * FROM emp WHERE deptno IN

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

EXISTS Predicate

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

SyntaxEXISTS (subquery)

Example

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

UNIQUE Predicate

PurposeThe Unique predicate is used to determine whether duplicate rows exist in a virtual table (one returned 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.


Subqueries

Syntax

SELECT select_list FROM table1 t_alias1 WHERE expr rel_operator (SELECT column_list FROM table2 t_alias2 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)



IReference

This part provides detailed reference information about your Progress DataDirect for ODBC driver.


• What Is ODBC?

• Code Page Values

• ODBC API and Scalar Functions

• Internationalization, Localization, and Unicode

• Designing ODBC Applications for Performance Optimization

• Using Indexes

• Locking and Isolation Levels

• WorkAround Options

• Threading

• DataDirect Bulk Load



Part I: Reference

7What Is ODBC?

The Open Database Connectivity (ODBC) interface by Microsoft allows applications to access data in databasemanagement systems (DBMS) using SQL as a standard for accessing the data. ODBC permits maximuminteroperability, which means a single application can access different DBMS. Application end users can thenadd ODBC database drivers to link the application to their choice of DBMS.

The ODBC interface defines:

• A library of ODBC function calls of two types:

• Extended functions that support additional functionality, including scrollable cursors

• Core functions that are based on the X/Open and SQL Access Group Call Level Interface specification

• SQL syntax based on the X/Open and SQL Access Group SQL CAE specification (1992)

• A standard set of error codes

• A standard way to connect and logon to a DBMS

• A standard representation for data types

The ODBC solution for accessing data led to ODBC database drivers, which are dynamic-link libraries onWindows and shared objects on UNIX and Linux. These drivers allow an application to gain access to one ormore data sources. ODBC provides a standard interface to allow application developers and vendors of databasedrivers to exchange data between applications and data sources.


• How Does It Work?

• Why Do Application Developers Need ODBC?


How Does It Work?

The ODBC architecture has four components:

• An application, which processes and calls ODBC functions to submit SQL statements and retrieve results

• A Driver Manager, which loads drivers for the application

• A driver, which processes ODBC function calls, submits SQL requests to a specific data source, and returnsresults to the application

• A data source, which consists of the data to access and its associated operating system, DBMS, and networkplatform (if any) used to access the DBMS

The following figure shows the relationship among the four components:

Why Do Application Developers Need ODBC?

Using ODBC, you, as an application developer can develop, compile, and ship an application without targetinga specific DBMS. In this scenario, you do not need to use embedded SQL; therefore, you do not need torecompile the application for each new environment.


Chapter 7: What Is ODBC?

8Code Page Values

This chapter lists supported code page values, along with a description, for your driver.


• IANAAppCodePage Values

IANAAppCodePage Values

The following table lists supported code page values for the IANAAppCodePage connection option. See"Connection Option Descriptions" for information about this attribute.

To determine the correct numeric value (the MIBenum value) for the IANAAppCodePage connection stringattribute, perform the following steps:

1. Determine the code page of your database.

2. Determine the MIBenum value that corresponds to your database code page. To do this, go to:

http://www.iana.org/assignments/character-sets

On this web page, search for the name of your database code page. This name will be listed as an alias orthe name of a character set, and will have a MIBenum value associated with it.

3. Check the following table to make sure that the MIBenum value you looked up on the IANA Web page issupported by your Progress DataDirect for ODBC driver. If the value is not listed, contact Progress TechnicalSupport to request support for that value.


http://www.iana.org/assignments/character-sets

Table 29: IANAAppCodePage Values

DescriptionValue (MIBenum)

US_ASCII3

ISO_8859_14

ISO_8859_25

ISO_8859_36

ISO_8859_47

ISO_8859_58

ISO_8859_69

ISO_8859_710

ISO_8859_811

ISO_8859_912

JIS_Encoding16

Shift_JIS17

EUC_JP18

ISO_646_IRV30

KS_C_560136

ISO_2022_KR37

EUC_KR38

ISO_2022_JP39

ISO_2022_JP_240

GB_2312_8057

ISO_2022_CN104

ISO_2022_CN_EXT105

ISO_8859_13109

ISO_8859_14110

ISO_8859_15111


Chapter 8: Code Page Values


GBK113

HP_ROMAN82004

IBM8502009

IBM8522010

IBM4372011

IBM8622013

IBM-Thai2016

WINDOWS-31J2024

GB23122025

Big52026

MACINTOSH2027

IBM0372028

IBM0382029

IBM2732030

IBM2772033

IBM2782034

IBM2802035

IBM2842037

IBM2852038

IBM2902039

IBM2972040

IBM4202041

IBM4242043

IBM5002044

IBM8512045

IBM8552046



IBM8572047

IBM8602048

IBM8612049

IBM8632050

IBM8642051

IBM8652052

IBM8682053

IBM8692054

IBM8702055

IBM8712056

IBM9182062

IBM10262063

KOI8_R2084

HZ_GB_23122085

IBM8662086

IBM7752087

IBM008582089

IBM011402091

IBM011412092

IBM011422093

IBM011432094

IBM011442095

IBM011452096

IBM011462097

IBM011472098

IBM011482099




IBM011492100

IBM10472102

WINDOWS_12502250

WINDOWS_12512251

WINDOWS_12522252

WINDOWS_12532253

WINDOWS_12542254

WINDOWS_12552255

WINDOWS_12562256

WINDOWS_12572257

WINDOWS_12582258

TIS_6202259

IBM-9392000000939 2

IBM-943_P14A-20002000000943 2

IBM-10252000001025 2

IBM-43962000004396 2

IBM-50262000005026 2

IBM-50352000005035 2

See alsoConnection Option Descriptions on page 127Contacting Technical Support on page 30

2 These values are assigned by Progress DataDirect and do not appear in http://www.iana.org/assignments/character-sets.


9ODBC API and Scalar Functions

This chapter lists the ODBC API functions that your Progress DataDirect for ODBC driver supports. In addition,it lists the scalar functions that you use in SQL statements.


• API Functions

• Scalar Functions

API Functions

Your Progress DataDirect for ODBC driver is Level 1 compliant, that is, it supports all ODBC Core and Level 1functions. It also supports a limited set of Level 2 functions, as described in the following table.


Table 30: Function Conformance for ODBC 2.x Applications

Level 2 FunctionsLevel 1 FunctionsCore Functions

SQLBrowseConnect

SQLDataSources

SQLDescribeParam

SQLExtendedFetch (forward scrollingonly)

SQLMoreResults

SQLNativeSql

SQLNumParams

SQLParamOptions

SQLSetScrollOptions

SQLColumns

SQLDriverConnect

SQLGetConnectOption

SQLGetData

SQLGetFunctions

SQLGetInfo

SQLGetStmtOption

SQLGetTypeInfo

SQLParamData

SQLPutData

SQLSetConnectOption

SQLSetStmtOption

SQLSpecialColumns

SQLStatistics

SQLTables

SQLAllocConnect

SQLAllocEnv

SQLAllocStmt

SQLBindCol

SQLBindParameter

SQLCancel

SQLColAttributes

SQLConnect

SQLDescribeCol

SQLDisconnect

SQLDrivers

SQLError

SQLExecDirect

SQLExecute

SQLFetch

SQLFreeConnect

SQLFreeEnv

SQLFreeStmt

SQLGetCursorName

SQLNumResultCols

SQLPrepare

SQLRowCount

SQLSetCursorName

SQLTransact

The functions for ODBC 3.x Applications that the driver supports are listed in the following table. Any additionsto these supported functions or differences in the support of specific functions are listed in "ODBC Compliance".


Chapter 9: ODBC API and Scalar Functions

Table 31: Function Conformance for ODBC 3.x Applications

SQLGetDescField

SQLGetDescRec

SQLGetDiagField

SQLGetDiagRec

SQLGetEnvAttr

SQLGetFunctions

SQLGetInfo

SQLGetStmtAttr

SQLGetTypeInfo

SQLMoreResults

SQLNativeSql

SQLNumParens

SQLNumResultCols

SQLParamData

SQLPrepare

SQLPutData

SQLRowCount

SQLSetConnectAttr

SQLSetCursorName

SQLSetDescField

SQLSetDescRec

SQLSetEnvAttr

SQLSetStmtAttr

SQLSpecialColumns

SQLStatistics

SQLTables

SQLTransact

SQLAllocHandle

SQLBindCol

SQLBindParameter

SQLBrowseConnect (except for Progress)

SQLBulkOperations

SQLCancel

SQLCloseCursor

SQLColAttribute

SQLColumns

SQLConnect

SQLCopyDesc

SQLDataSources

SQLDescribeCol

SQLDisconnect

SQLDriverConnect

SQLDrivers

SQLEndTran

SQLError

SQLExecDirect

SQLExecute

SQLExtendedFetch

SQLFetch

SQLFetchScroll (forward scrolling only)

SQLFreeHandle

SQLFreeStmt

SQLGetConnectAttr

SQLGetCursorName

SQLGetData

See alsoODBC Compliance on page 17

Scalar Functions

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


{fn scalar-function}

where scalar-function is one of the functions listed in the following tables. For example:

SELECT {fn UCASE(NAME)} FROM EMP

Table 32: Scalar Functions

System FunctionsTimedate FunctionsNumeric FunctionsString Functions

CURSESSIONIDCURDATEABSASCII

CURRENT_USERCURTIMEACOSBIT_LENGTH

DATABASEDAYASINCHAR

IDENTITYDATEDIFFATANCHAR_LENGTH

USERDAYNAMEATAN2CHARACTER_LENGTH

DAYOFMONTHBITANDCONCAT

DAYOFWEEKBITORDIFFERENCE

DAYOFYEARBITXORHEXTORAW

EXTRACTCEILINGINSERT

HOURCOSLCASE

MINUTECOTLEFT

MONTHDEGREESLENGTH

MONTHNAMEEXPLOCATE

NOWFLOORLOCATE2

QUARTERLOGLOWER

SECONDLOG10LTRIM

SECONDS_SINCE_MIDNIGHTMODOCTET_LENGTH

TIMESTAMPADDPIRAWTOHEX

TIMESTAMPDIFFPOWERREPEAT

TO_CHARRADIANSREPLACE

WEEKRANDRIGHT

YEARROUNDRTRIM

ROUNDMAGICSOUNDEX



System FunctionsTimedate FunctionsNumeric FunctionsString Functions

SIGNSPACE

SINSUBSTR

SQRTSUBSTRING

TANUCASE

TRUNCATEUPPER

String FunctionsThe following table lists the supported string functions.

The string functions listed accept the following arguments:

• string_exp can be the name of a column, a string literal, or the result of another scalar function, wherethe underlying data type is SQL_CHAR, SQL_VARCHAR, or SQL_LONGVARCHAR.

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

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

Character string literals must be surrounded in single quotation marks.

Table 33: Scalar String Functions

ReturnsFunction

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

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

[ODBC 3.0 only]

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

CHAR(code)

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

CHAR_LENGTH(string_exp)

[ODBC 3.0 only]

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

CHARACTER_LENGTH(string_exp)[ODBC 3.0 only]

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

CONCAT(string_exp1, string_exp2)


ReturnsFunction

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

DIFFERENCE(string_exp1,string_exp2)

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

INSERT(string_exp1, start, length,string_exp2)

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

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

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

LENGTH(string_exp)

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

LOCATE(string_exp1,string_exp2[,start])

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

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

OCTET_LENGTH(string_exp)

[ODBC 3.0 only]

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

POSITION(character_exp INcharacter_exp)

[ODBC 3.0 only]

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

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

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

The characters of string_exp with trailing blanks removed.RTRIM(string_exp)

A data source dependent string representing the sound of the words instring_exp.

SOUNDEX(string_exp)

A string consisting of count spaces.SPACE(count)

A string derived from string_exp beginning at the character position startfor length characters.

SUBSTRING(string_exp, start,length)

Lowercase characters in string_exp converted to uppercase.UCASE(string_exp)



Numeric FunctionsThe following table lists the numeric functions that ODBC supports.

The numeric functions listed accept the following arguments:

• numeric_exp can be a column name, a numeric literal, or the result of another scalar function, where theunderlying data type is SQL_NUMERIC, SQL_DECIMAL, SQL_TINYINT, SQL_SMALLINT, SQL_INTEGER,SQL_BIGINT, SQL_FLOAT, SQL_REAL, or SQL_DOUBLE.

• float_exp can be a column name, a numeric literal, or the result of another scalar function, where theunderlying data type is SQL_FLOAT.

• integer_exp can be a column name, a numeric literal, or the result of another scalar function, where theunderlying data type is SQL_TINYINT, SQL_SMALLINT, SQL_INTEGER, or SQL_BIGINT.

Table 34: Scalar Numeric Functions

ReturnsFunction

Absolute value of numeric_exp.ABS(numeric_exp)

Arccosine of float_exp as an angle in radians.ACOS(float_exp)

Arcsine of float_exp as an angle in radians.ASIN(float_exp)

Arctangent of float_exp as an angle in radians.ATAN(float_exp)

Arctangent of the x and y coordinates, specified by float_exp1 andfloat_exp2 as an angle in radians.

ATAN2(float_exp1, float_exp2)

Smallest integer greater than or equal to numeric_exp.CEILING(numeric_exp)

Cosine of float_exp as an angle in radians.COS(float_exp)

Cotangent of float_exp as an angle in radians.COT(float_exp)

Number if degrees converted from numeric_exp radians.DEGREES(numeric_exp)

Exponential value of float_exp.EXP(float_exp)

Largest integer less than or equal to numeric_exp.FLOOR(numeric_exp)

Natural log of float_exp.LOG(float_exp)

Base 10 log of float_exp.LOG10(float_exp)

Remainder of integer_exp1 divided by integer_exp2.MOD(integer_exp1, integer_exp2)

Constant value of pi as a floating-point number.PI()

Value of numeric_exp to the power of integer_exp.POWER(numeric_exp, integer_exp)

Number of radians converted from numeric_exp degrees.RADIANS(numeric_exp)


ReturnsFunction

Random floating-point value using integer_exp as the optional seedvalue.

RAND([integer_exp])

numeric_exp rounded to integer_exp places right of the decimal (leftof the decimal if integer_exp is negative).

ROUND(numeric_exp, integer_exp)

Indicator of the sign of numeric_exp. If numeric_exp < 0, -1 is returned.If numeric_exp = 0, 0 is returned. If numeric_exp > 0, 1 is returned.

SIGN(numeric_exp)

Sine of float_exp, where float_exp is an angle in radians.SIN(float_exp)

Square root of float_exp.SQRT(float_exp)

Tangent of float_exp, where float_exp is an angle in radians.TAN(float_exp)

numeric_exp truncated to integer_exp places right of the decimal. (Ifinteger_exp is negative, truncation is to the left of the decimal.)

TRUNCATE(numeric_exp, integer_exp)

Date and Time FunctionsThe following table lists the date and time functions that ODBC supports.

The date and time functions listed accept the following arguments:

• date_exp can be a column name, a date or timestamp literal, or the result of another scalar function, wherethe underlying data type can be represented as SQL_CHAR, SQL_VARCHAR, SQL_DATE, orSQL_TIMESTAMP.

• time_exp can be a column name, a timestamp or timestamp literal, or the result of another scalar function,where the underlying data type can be represented as SQL_CHAR, SQL_VARCHAR, SQL_TIME, orSQL_TIMESTAMP.

• timestamp_exp can be a column name; a time, date, or timestamp literal; or the result of another scalarfunction, where the underlying data type can be represented as SQL_CHAR, SQL_VARCHAR, SQL_TIME,SQL_DATE, or SQL_TIMESTAMP.

Table 35: Scalar Time and Date Functions

ReturnsFunction

Current date.CURRENT_DATE()

[ODBC 3.0 only]

Current local time. The time-precision argumentdetermines the seconds precision of the returned value.

CURRENT_TIME[(time-precision)]

[ODBC 3.0 only]

Current local date and local time as a timestamp value.The timestamp-precision argument determines theseconds precision of the returned timestamp.

CURRENT_TIMESTAMP([timestamp-precision])

[ODBC 3.0 only]

Current date as a date value.CURDATE()



ReturnsFunction

Current local time as a time value.CURTIME()

Character string containing a data-source-specific nameof the day for the day portion of date_exp.

DAYNAME(date_exp)

Day of the month in date_exp as an integer value (1–31).DAYOFMONTH(date_exp)

Day of the week in date_exp as an integer value (1–7).DAYOFWEEK(date_exp)

Day of the year in date_exp as an integer value (1–366).DAYOFYEAR(date_exp)

Any of the date and time terms can be extracted fromdatetime_value.

EXTRACT({YEAR | MONTH | DAY | HOUR | MINUTE |SECOND} FROM datetime_value)

Hour in time_exp as an integer value (0–23).HOUR(time_exp)

Minute in time_exp as an integer value (0–59).MINUTE(time_exp)

Month in date_exp as an integer value (1–12).MONTH(date_exp)

Character string containing the data source-specific nameof the month.

MONTHNAME(date_exp)

Current date and time as a timestamp value.NOW()

Quarter in date_exp as an integer value (1–4).QUARTER(date_exp)

Second in date_exp as an integer value (0–59).SECOND(time_exp)

Timestamp calculated by adding integer_exp intervalsof type interval to time_exp. interval can be one of thefollowing values:

SQL_TSI_FRAC_SECOND

SQL_TSI_SECOND

SQL_TSI_MINUTE

SQL_TSI_HOUR

SQL_TSI_DAY

SQL_TSI_WEEK

SQL_TSI_MONTH

SQL_TSI_QUARTER

SQL_TSI_YEAR

Fractional seconds are expressed in billionths of asecond.

TIMESTAMPADD(interval, integer_exp, time_exp)


ReturnsFunction

Integer number of intervals of type interval by whichtime_exp2 is greater than time_exp1. interval has thesame values as TIMESTAMPADD. Fractional secondsare expressed in billionths of a second.

TIMESTAMPDIFF(interval, time_exp1, time_exp2)

Week of the year in date_exp as an integer value (1–53).WEEK(date_exp)

Year in date_exp. The range is data-source dependent.YEAR(date_exp)

System FunctionsThe following table lists the system functions that ODBC supports.

Table 36: Scalar System Functions

ReturnsFunction

Name of the database, corresponding to the connection handle (hdbc).DATABASE()

value, if exp is null.IFNULL(exp,value)

Authorization name of the user.USER()



10Internationalization, Localization, andUnicode

This chapter provides an overview of how internationalization, localization, and Unicode relate to each other.It also provides a background on Unicode, and how it is accommodated by Unicode and non-Unicode ODBCdrivers.


• Internationalization and Localization

• Unicode Character Encoding

• Unicode and Non-Unicode ODBC Drivers

• Driver Manager and Unicode Encoding on UNIX/Linux

• Character Encoding in the odbc.ini and odbcinst.ini Files

Internationalization and Localization

Software that has been designed for internationalization is able to manage different linguistic and culturalconventions transparently and without modification. The same binary copy of an application should run on anylocalized version of an operating system without requiring source code changes.

Software that has been designed for localization includes language translation (such as text messages, icons,and buttons), cultural data (such as dates, times, and currency), and other components (such as input methodsand spell checkers) for meeting regional market requirements.


Properly designed applications can accommodate a localized interface without extensive modification. Theapplications can be designed, first, to run internationally, and, second, to accommodate the language- andcultural-specific elements of a designated locale.

LocaleA locale represents the language and cultural data chosen by the user and dynamically loaded into memoryat runtime. The locale settings are applied to the operating system and to subsequent application launches.

While language is a fairly straightforward item, cultural data is a little more complex. Dates, numbers, andcurrency are all examples of data that is formatted according to cultural expectations. Because culturalpreferences are bound to a geographic area, country is an important element of locale. Together these twoelements (language and country) provide a precise context in which information can be presented. Localepresents information in the language and form that is best understood and appreciated by the local user.

LanguageA locale's language is specified by the ISO 639 standard. The following table lists some commonly usedlanguage codes.

LanguageLanguage Code

Englishen

Dutchnl

Frenchfr

Spanishes

Chinesezh

Japaneseja

Vietnamesevi

Because language is correlated with geography, a language code might not capture all the nuances of usagein a particular area. For example, French and Canadian French may use different phrases and terms to meandifferent things even though basic grammar and vocabulary are the same. Language is only one element oflocale.

CountryThe locale's country identifier is also specified by an ISO standard, ISO 3166, which describes valid two-lettercodes for all countries. ISO 3166 defines these codes in uppercase letters. The following table lists somecommonly used country codes.

CountryCountry Code

United StatesUS

FranceFR

IrelandIE

CanadaCA

MexicoMX

The country code provides more contextual information for a locale and affects a language's usage, wordspelling, and collation rules.


Chapter 10: Internationalization, Localization, and Unicode

VariantA variant is an optional extension to a locale. It identifies a custom locale that is not possible to create with justlanguage and country codes. Variants can be used by anyone to add additional context for identifying a locale.The locale en_US represents English (United States), but en_US_CA represents even more information andmight identify a locale for English (California, U.S.A). Operating system or software vendors can use thesevariants to create more descriptive locales for their specific environments.

Unicode Character Encoding

In addition to locale, the other major component of internationalizing software is the use of the UniversalCodeset, or Unicode. Most developers know that Unicode is a standard encoding that can be used to supportmultilingual character sets. Unfortunately, understanding Unicode is not as simple as its name would indicate.Software developers have used a number of character encodings, from ASCII to Unicode, to solve the manyproblems that arise when developing software applications that can be used worldwide.

BackgroundMost legacy computing environments have used ASCII character encoding developed by the ANSI standardsbody to store and manipulate character strings inside software applications. ASCII encoding was convenientfor programmers because each ASCII character could be stored as a byte. The initial version of ASCII usedonly 7 of the 8 bits available in a byte, which meant that applications could use only 128 different characters.This version of ASCII could not account for European characters and was completely inadequate for Asiancharacters. Using the eighth bit to extend the total range of characters to 256 added support for most Europeancharacters. Today, ASCII refers to either the 7-bit or 8-bit encoding of characters.

As the need increased for applications with additional international support, ANSI again increased the functionalityof ASCII by developing an extension to accommodate multilingual software. The extension, known as theDouble-Byte Character Set (DBCS), allowed existing applications to function without change, but provided forthe use of additional characters, including complex Asian characters. With DBCS, characters map to eitherone byte (for example, American ASCII characters) or two bytes (for example, Asian characters). The DBCSenvironment also introduced the concept of an operating system code page that identified how characterswould be encoded into byte sequences in a particular computing environment. DBCS encoding provided across-platform mechanism for building multilingual applications.

The DataDirect for ODBC UNIX and Linux drivers can use double-byte character sets. The drivers normally usethe character set defined by the default locale "C" unless explicitly pointed to another character set.The defaultlocale "C" corresponds to the 7-bit US-ASCII character set. Use the following procedure to set the locale to adifferent character set:

1. Add the following line at the beginning of applications that use double-byte character sets:

setlocale (LC_ALL, "");

This is a standard UNIX function. It selects the character set indicated by the environment variable LANGas the one to be used by X/Open compliant, character-handling functions. If this line is not present, or ifLANG is not set or is set to NULL, the default locale "C" is used.

2. Set the LANG environment variable to the appropriate character set. The UNIX command locale -a canbe used to display all supported character sets on your system.

For more information, refer to the man pages for "locale" and "setlocale."


Using a DBCS, however, was not ideal; many developers felt that there was a better way to solve the problem.A group of leading software companies joined forces to form the Unicode Consortium.Together, they produceda new solution to building worldwide applications—Unicode. Unicode was originally designed as a fixed-width,uniform two-byte designation that could represent all modern scripts without the use of code pages.The UnicodeConsortium has continued to evaluate new characters, and the current number of supported characters is over109,000.

Although it seemed to be the perfect solution to building multilingual applications, Unicode started off with asignificant drawback—it would have to be retrofitted into existing computing environments. To use the newparadigm, all applications would have to change. As a result, several standards-based transliterations weredesigned to convert two-byte fixed Unicode values into more appropriate character encodings, including, amongothers, UTF-8, UCS-2, and UTF-16.

UTF-8 is a standard method for transforming Unicode values into byte sequences that maintain transparencyfor all ASCII codes. UTF-8 is recognized by the Unicode Consortium as a mechanism for transforming Unicodevalues and is popular for use with HTML, XML, and other protocols. UTF-8 is, however, currently used primarilyon AIX, HP-UX, Solaris, and Linux.

UCS-2 encoding is a fixed, two-byte encoding sequence and is a method for transforming Unicode values intobyte sequences. It is the standard for Windows 95, Windows 98, Windows Me, and Windows NT.

UTF-16 is a superset of UCS-2, with the addition of some special characters in surrogate pairs. UTF-16 is thestandard encoding for Windows 7 and higher. Microsoft recommends using UTF-16 for new applications.

See "Unicode Support" to determine which encodings your driver supports.

See alsoUnicode Support on page 98

Unicode Support in DatabasesRecently, database vendors have begun to support Unicode data types natively in their systems. With Unicodesupport, one database can hold multiple languages. For example, a large multinational corporation could storeexpense data in the local languages for the Japanese, U.S., English, German, and French offices in onedatabase.

Not surprisingly, the implementation of Unicode data types varies from vendor to vendor. For example, theMicrosoft SQL Server 2000 implementation of Unicode provides data in UTF-16 format, while Oracle providesUnicode data types in UTF-8 and UTF-16 formats. A consistent implementation of Unicode not only dependson the operating system, but also on the database itself.

Unicode Support in ODBCPrior to the ODBC 3.5 standard, all ODBC access to function calls and string data types was through ANSIencoding (either ASCII or DBCS). Applications and drivers were both ANSI-based.

The ODBC 3.5 standard specified that the ODBC Driver Manager be capable of mapping both Unicode functioncalls and string data types to ANSI encoding as transparently as possible.This meant that ODBC 3.5-compliantUnicode applications could use Unicode function calls and string data types with ANSI drivers because theDriver Manager could convert them to ANSI. Because of character limitations in ANSI, however, not allconversions are possible.

The ODBC Driver Manager version 3.5 and later, therefore, supports the following configurations:

• ANSI application with an ANSI driver

• ANSI application with a Unicode driver

• Unicode application with a Unicode driver



• Unicode application with an ANSI driver

A Unicode application can work with an ANSI driver because the Driver Manager provides limitedUnicode-to-ANSI mapping. The Driver Manager makes it possible for a pre-3.5 ANSI driver to work with aUnicode application. What distinguishes a Unicode driver from a non-Unicode driver is the Unicode driver'scapacity to interpret Unicode function calls without the intervention of the Driver Manager, as described in thefollowing section.

Unicode and Non-Unicode ODBC Drivers

The way in which a driver handles function calls from a Unicode application determines whether it is considereda "Unicode driver."

Function CallsInstead of the standard ANSI SQL function calls, such as SQLConnect, Unicode applications use "W" (wide)function calls, such as SQLConnectW. If the driver is a true Unicode driver, it can understand "W" functioncalls and the Driver Manager can pass them through to the driver without conversion to ANSI. The ProgressDataDirect for ODBC for Salesforce Driver supports "W" function calls.

If a driver is a non-Unicode driver, it cannot understand W function calls, and the Driver Manager must convertthem to ANSI calls before sending them to the driver. The Driver Manager determines the ANSI encodingsystem to which it must convert by referring to a code page. On Windows, this reference is to the Active CodePage. On non-Windows platforms, it is to the IANAAppCodePage connection string attribute, part of theodbc.ini file.

The following examples illustrate these conversion streams for the Progress DataDirect for ODBC drivers. TheDriver Manager on UNIX and Linux determines the type of Unicode encoding of both the application and thedriver, and performs conversions when the application and driver use different types of encoding. Thisdetermination is made by checking two ODBC attributes: SQL_ATTR_APP_UNICODE_TYPE andSQL_ATTR_DRIVER_UNICODE_TYPE, which can be set for either the environment, using SQLSetEnvAttr,or the connection, using SQLSetConnectAttr. "Driver Manager and Unicode Encoding on UNIX/Linux" describesin detail how this is done.

See alsoDriver Manager and Unicode Encoding on UNIX/Linux on page 274

Unicode Application with a Non-Unicode Driver

An operation involving a Unicode application and a non-Unicode driver incurs more overhead because functionconversion is involved.

Windows

1. The Unicode application sends UCS-2/UTF-16 function calls to the Driver Manager.

2. The Driver Manager converts the function calls from UCS-2/UTF-16 to ANSI.The type of ANSI is determinedby the Driver Manager through reference to the client machine’s Active Code Page.

3. The Driver Manager sends the ANSI function calls to the non-Unicode driver.

4. The driver returns ANSI argument values to the Driver Manager.

5. The Driver Manager converts the function calls from ANSI to UCS-2/UTF-16 and returns these convertedcalls to the application.


UNIX and Linux

1. The Unicode application sends function calls to the Driver Manager. The Driver Manager expects the stringarguments in these function calls to be UTF-8 or UTF-16 based on the value of theSQL_ATTR_APP_UNICODE_TYPE attribute. Note that the SQL_ATTR_APP_UNICODE_TYPE attributecan be set for the environment, using SQLSetEnvAttr, or the connection, using SQLSetConnectAttr.

2. The Driver Manager converts the function calls from UTF-8 or UTF-16 to ANSI. The type of ANSI isdetermined by the Driver Manager through reference to the client machine’s value for the IANAAppCodePageconnection string attribute.

3. The Driver Manager sends the converted ANSI function calls to the non-Unicode driver.

4. The driver returns ANSI argument values to the Driver Manager.

5. The Driver Manager converts the function calls from ANSI to UTF-8 or UTF-16 and returns these convertedcalls to the application.

Unicode Application with a Unicode Driver

An operation involving a Unicode application and a Unicode driver that use the same Unicode encoding isefficient because no function conversion is involved. If the application and the driver each use different typesof encoding, there is some conversion overhead. See "Driver Manager and Unicode Encoding on UNIX/Linux"for details.

Windows

1. The Unicode application sends UCS-2 or UTF-16 function calls to the Driver Manager.

2. The Driver Manager does not have to convert the UCS-2/UTF-16 function calls to ANSI. It passes theUnicode function call to the Unicode driver.

3. The driver returns UCS-2/UTF-16 argument values to the Driver Manager.

4. The Driver Manager returns UCS-2/UTF-16 function calls to the application.

UNIX and Linux

1. The Unicode application sends function calls to the Driver Manager. The Driver Manager expects the stringarguments in these function calls to be UTF-8 or UTF-16 based on the value of theSQL_ATTR_APP_UNICODE_TYPE attribute. Note that the SQL_ATTR_APP_UNICODE_TYPE attributecan be set for the environment, using SQLSetEnvAttr, or the connection, using SQLSetConnectAttr.

2. The Driver Manager passes Unicode function calls to the Unicode driver.The Driver Manager has to performfunction call conversions if the SQL_ATTR_APP_UNICODE_TYPE is different from theSQL_ATTR_DRIVER_UNICODE_TYPE.

3. The driver returns argument values to the Driver Manager. Whether these are UTF-8 or UTF-16 argumentvalues is based on the value of the SQL_ATTR_DRIVER_UNICODE_TYPE attribute.

4. The Driver Manager returns appropriate function calls to the application based on theSQL_ATTR_APP_UNICODE_TYPE attribute value. The Driver Manager has to perform function callconversions if the SQL_ATTR_DRIVER_UNICODE_TYPE value is different from theSQL_ATTR_APP_UNICODE_TYPE value.




DataODBC C data types are used to indicate the type of C buffers that store data in the application. This is incontrast to SQL data types, which are mapped to native database types to store data in a database (data store).ANSI applications bind to the C data type SQL_C_CHAR and expect to receive information bound in the sameway. Similarly, most Unicode applications bind to the C data type SQL_C_WCHAR (wide data type) and expectto receive information bound in the same way. Any ODBC 3.5-compliant Unicode driver must be capable ofsupporting SQL_C_CHAR and SQL_C_WCHAR so that it can return data to both ANSI and Unicode applications.

When the driver communicates with the database, it must use ODBC SQL data types, such as SQL_CHARand SQL_WCHAR, that map to native database types. In the case of ANSI data and an ANSI database, thedriver receives data bound to SQL_C_CHAR and passes it to the database as SQL_CHAR. The same is trueof SQL_C_WCHAR and SQL_WCHAR in the case of Unicode data and a Unicode database.

When data from the application and the data stored in the database differ in format, for example, ANSI applicationdata and Unicode database data, conversions must be performed. The driver cannot receive SQL_C_CHARdata and pass it to a Unicode database that expects to receive a SQL_WCHAR data type. The driver or theDriver Manager must be capable of converting SQL_C_CHAR to SQL_WCHAR, and vice versa.

The simplest cases of data communication are when the application, the driver, and the database are all ofthe same type and encoding, ANSI-to-ANSI-to-ANSI or Unicode-to-Unicode-to-Unicode. There is no dataconversion involved in these instances.

When a difference exists between data types, a conversion from one type to another must take place at thedriver or Driver Manager level, which involves additional overhead. The type of driver determines whetherthese conversions are performed by the driver or the Driver Manager. "Driver Manager and Unicode Encodingon UNIX/Linux" describes how the Driver Manager determines the type of Unicode encoding of the applicationand driver.

The following sections discuss two basic types of data conversion in the Progress DataDirect for ODBC driverand the Driver Manager. How an individual driver exchanges different types of data with a particular databaseat the database level is beyond the scope of this discussion.


Unicode Driver

The Unicode driver, not the Driver Manager, must convert SQL_C_CHAR (ANSI) data to SQL_WCHAR(Unicode) data, and vice versa, as well as SQL_C_WCHAR (Unicode) data to SQL_CHAR (ANSI) data, andvice versa.

The driver must use client code page information (Active Code Page on Windows and IANAAppCodePageattribute on UNIX/Linux) to determine which ANSI code page to use for the conversions.The Active Code Pageor IANAAppCodePage must match the database default character encoding; if it does not, conversion errorsare possible.

ANSI Driver

The Driver Manager, not the ANSI driver, must convert SQL_C_WCHAR (Unicode) data to SQL_CHAR (ANSI)data, and vice versa (see "Unicode Support in ODBC" for a detailed discussion). This is necessary becauseANSI drivers do not support any Unicode ODBC types.

The Driver Manager must use client code page information (Active Code Page on Windows and theIANAAppCodePage attribute on UNIX/Linux) to determine which ANSI code page to use for the conversions.The Active Code Page or IANAAppCodePage must match the database default character encoding. If not,conversion errors are possible.


See alsoUnicode Support in ODBC on page 270

Default Unicode MappingThe following table shows the default Unicode mapping for an application’s SQL_C_WCHAR variables.

Default Unicode MappingPlatform

UCS-2/UTF-16Windows

UTF-8AIX

UTF-8HP-UX

UTF-8Solaris

UTF-8Linux

Connection Attribute for Unicode

If you do not want to use the default Unicode mappings for SQL_C_WCHAR, a connection attribute is availableto override the default mappings. This attribute determines how character data is converted and presented toan application and the database.

DescriptionAttribute

Sets the SQL_C_WCHAR type for parameter andcolumn binding to the Unicode type, either

SQL_ATTR_APP_WCHAR_TYPE (1061)

SQL_DD_CP_UTF16 (default for Windows) orSQL_DD_CP_UTF8 (default for UNIX/Linux).

You can set this attribute before or after you connect. After this attribute is set, all conversions are made basedon the character set specified.

For example:

rc = SQLSetConnectAttr (hdbc, SQL_ATTR_APP_WCHAR_TYPE, (void *)SQL_DD_CP_UTF16, SQL_IS_INTEGER);

SQLGetConnectAttr and SQLSetConnectAttr for the SQL_ATTR_APP_WCHAR_TYPE attribute return a SQLState of HYC00 for drivers that do not support Unicode.

This connection attribute and its valid values can be found in the file qesqlext.h, which is installed with theproduct.

Driver Manager and Unicode Encoding on UNIX/Linux

Unicode ODBC drivers on UNIX and Linux can use UTF-8 or UTF-16 encoding. To use a singleUTF-8 or UTF-16 application with either a UTF-8 or UTF-16 driver, the Driver Manager must be able to determinewith which type of encoding the application and driver use and, if necessary, convert them accordingly.



To make this determination, the Driver Manager supports a set of ODBC attributes that can be set for theenvironment or the connection. If your application uses both UTF-8 and UTF-16 drivers in the same environment,encoding should be set for the connection only; otherwise, either method can be used.

• To configure the encoding type for the environment, set the ODBC environment attributesSQL_ATTR_APP_UNICODE_TYPE and SQL_ATTR_DRIVER_UNICODE_TYPE using SQLSetEnvAttr.

• To configure the encoding for the connection only, set the ODBC connection attributeSQL_ATTR_APP_UNICODE_TYPE and SQL_ATTR_DRIVER_UNICODE_TYPE using SQLSetConnectAttr.

The attributes support values of SQL_DD_CP_UTF8 and SQL_DD_CP_UTF16. The default value isSQL_DD_CP_UTF8.

Note: You must specify a value for SQL_ATTR_DRIVER_UNICODE_TYPE when using third-party drivers.However, for DataDirect drivers, the driver manager detects the Unicode type for the driver by default.

The Driver Manager performs the following steps before actually connecting to the driver.

1. Determine the application Unicode type: Applications that use UTF-16 encoding for their string types needto set SQL_ATTR_APP_UNICODE_TYPE accordingly at connection, or, if setting the encoding type forthe environment, before connecting to any driver. When the Driver Manager reads this attribute, it expectsall string arguments to the ODBC "W" functions to be in the specified Unicode format. This attribute alsoindicates how the SQL_C_WCHAR buffers must be encoded.

2. Determine the driver Unicode type: The Driver Manager must determine through which Unicode encodingthe driver supports its "W" functions. This is done as follows:

a. SQLGetEnvAttr(SQL_ATTR_DRIVER_UNICODE_TYPE) or SQLGetConnectATTR(SQL_ATTR_DRIVER_UNICODE_TYPE) is called in the driver by the Driver Manager. The driver, ifcapable, returns either SQL_DD_CP_UTF16 or SQL_DD_CP_UTF8 to indicate to the Driver Managerwhich encoding it expects.

b. If the preceding call to SQLGetEnvAttr fails, the Driver Manager looks either in the Data Source sectionof the odbc.ini specified by the connection string or in the connection string itself for a connectionoption named DriverUnicodeType. Valid values for this option are 1 (UTF-16) or 2 (UTF-8). The DriverManager assumes that the Unicode encoding of the driver corresponds to the value specified.

c. If neither of the preceding attempts are successful, the Driver Manager assumes that the Unicodeencoding of the driver is UTF-8.

3. Determine if the driver supports SQL_ATTR_WCHAR_TYPE: SQLSetConnectAttr(SQL_ATTR_WCHAR_TYPE, x) is called in the driver by the Driver Manager, where x is eitherSQL_DD_CP_UTF8 or SQL_DD_CP_UTF16, depending on the value of theSQL_ATTR_APP_UNICODE_TYPE setting. If the driver returns any error on this call to SQLSetConnectAttr,the Driver Manager assumes that the driver does not support this connection attribute.

If an error occurs, the Driver Manager returns a warning. The Driver Manager does not convert all boundparameter data from the application Unicode type to the driver Unicode type specified bySQL_ATTR_DRIVER_UNICODE_TYPE. Neither does it convert all data bound as SQL_C_WCHAR to theapplication Unicode type specified by SQL_ATTR_APP_UNICODE_TYPE.

Based on the information it has gathered prior to connection, the Driver Manager either does not have to convertfunction calls, or, before calling the driver, it converts to either UTF-8 or UTF-16 all string arguments to callsto the ODBC "W" functions.

ReferencesThe Java Tutorials, http://docs.oracle.com/javase/tutorial/i18n/index.html


http://docs.oracle.com/javase/tutorial/i18n/index.html

Unicode Support in the Solaris Operating Environment, May 2000, Sun Microsystems, Inc., 901 San AntonioRoad, Palo Alto, CA 94303-4900

Character Encoding in the odbc.ini and odbcinst.ini Files

The odbc.ini and odbcinst.ini files can use ANSI or UTF-8 encoding. To ensure encodingcompatibility between these files and the application, the Driver Manager converts encoding when necessary.This allows applications with different encoding to write to or read from the odbc.ini or odbcinst.ini fileusing the following functions:

ANSI functions:

• SQLWritePrivateProfileString

• SQLGetPrivateProfileString

Unicode (wide or "W") functions:

• SQLWritePrivateProfileStringW

• SQLGetPrivateProfileStringW

For the Driver Manager to accomplish this task, it must determine the encoding format your application andfile use. How the Driver Manager makes this determination is dependent on the encoding of the function calledby the application.

When a Unicode function is called, the Driver Manager assumes that the odbc.ini and odbcinst.ini filesuse UTF-8 encoding, while encoding for the application is determined by the ODBC_App_Unicode_Typevariable in the system environment:

• If the variable is set to ODBC_App_Unicode_Type=1, the Driver Manager expects that application usesinput and output strings encoded as UTF-16. When the application calls SQLWritePrivateProfileStringW,the Driver Manager converts UTF-16 input strings and writes them as UTF-8 in the file.When the applicationcalls SQLGetPrivateProfileStringW, the Driver Manager returns the requested values using UTF-16 encoding.

• If any other value is specified for ODBC_App_Unicode_Type, or if the variable is not defined, the DriverManager assumes that the application and file use UTF-8. When this occurs, the Driver Manager does notconvert strings passed between the application and file.

When an ANSI function is called, the Driver Manager assumes that application and file use ANSI encoding. Inthis scenario, the Driver Manger does not convert strings passed between the application and file.

For more information about the odbc.ini and odbcinst.ini files, see "Configuring the Product onUNIX/Linux."

See alsoConfiguring the Product on UNIX/Linux on page 38



11Designing ODBC Applications forPerformance Optimization

Developing performance-oriented ODBC applications is not easy. Microsoft’s ODBC Programmer’s Referencedoes not provide information about system performance. In addition, ODBC drivers and the ODBC drivermanager do not return warnings when applications run inefficiently. This chapter contains some generalguidelines that have been compiled by examining the ODBC implementations of numerous shipping ODBCapplications. These guidelines include:

• Use catalog functions appropriately

• Retrieve only required data

• Select functions that optimize performance

• Manage connections and updates

Following these general rules will help you solve some common ODBC performance problems, such as thoselisted in the following table.

Table 37: Common Performance Problems Using ODBC Applications

See guidelines in...SolutionProblem

"Using Catalog Functions"Reduce network traffic.Network communication is slow.

"Using Catalog Functions"

"Selecting ODBC Functions"

Simplify queries.The process of evaluating complexSQL queries on the database serveris slow and can reduce concurrency.


See guidelines in...SolutionProblem

"Retrieving Data"

"Selecting ODBC Functions"

Optimizeapplication-to-driverinteraction.

Excessive calls from the applicationto the driver slow performance.

"Managing Connections and Updates"Limit disk input/output.Disk I/O is slow.


• Using Catalog Functions

• Retrieving Data

• Selecting ODBC Functions

• Managing Connections and Updates

Using Catalog Functions

Because catalog functions, such as those listed here, are slow compared to other ODBC functions, their frequentuse can impair system performance:

• SQLColumns

• SQLForeignKeys

• SQLGetTypeInfo

• SQLSpecialColumns

• SQLStatistics

• SQLTables

SQLGetTypeInfo is included in this list of expensive ODBC functions because many drivers must query theserver to obtain accurate information about which types are supported (for example, to find dynamic typessuch as user defined types).

Caching Information to Minimize the Use of Catalog FunctionsTo return all result column information mandated by the ODBC specification, a driver may have to performmultiple queries, joins, subqueries, or unions to return the required result set for a single call to a catalogfunction. These particular elements of the SQL language are performance expensive.

Although it is almost impossible to write an ODBC application without catalog functions, their use should beminimized. By caching information, applications can avoid multiple executions.

For example, call SQLGetTypeInfo once in the application and cache the elements of the result set that yourapplication depends on. It is unlikely that any application uses all elements of the result set generated by acatalog function, so the cached information should not be difficult to maintain.


Chapter 11: Designing ODBC Applications for Performance Optimization

Avoiding Search PatternsPassing NULL arguments or search patterns to catalog functions generates time-consuming queries. In addition,network traffic potentially increases because of unwanted results. Always supply as many non-NULL argumentsto catalog functions as possible. Because catalog functions are slow, applications should invoke them efficiently.Any information that the application can send the driver when calling catalog functions can result in improvedperformance and reliability.

For example, consider a call to SQLTables where the application requests information about the table"Customers." Often, this call is coded as shown, using as many NULL arguments as possible:

rc = SQLTables (hstmt, NULL, 0, NULL, 0, "Customers", SQL_NTS, NULL, 0);

A driver processes this SQLTables call into SQL that looks like this:

SELECT ... FROM SysTables WHERE TableName = ’Customers’UNION ALLSELECT ... FROM SysViews WHERE ViewName = ’Customers’UNION ALLSELECT ... FROM SysSynonyms WHERE SynName = ’Customers’ ORDER BY ...

In our example, the application provides scant information about the object for which information was requested.Suppose three "Customers" tables were returned in the result set: the first table owned by the user namedBeth, the second owned by the sales department, and the third a view created by management.

It may not be obvious to the end user which table to choose. If the application had specified the OwnerNameargument in the SQLTables call, only one table would be returned and performance would improve. Lessnetwork traffic would be required to return only one result row and unwanted rows would be filtered by thedatabase. In addition, if the TableType argument was supplied, the SQL sent to the server can be optimizedfrom a three-query union into a single Select statement as shown:

SELECT ... FROM SysTables WHERE TableName = 'Customers' AND Owner = 'Beth'

Using a Dummy Query to Determine Table CharacteristicsAvoid using SQLColumns to determine characteristics about a table. Instead, use a dummy query withSQLDescribeCol.

Consider an application that allows the user to choose the columns that will be selected. Should the applicationuse SQLColumns to return information about the columns to the user or prepare a dummy query and callSQLDescribeCol?

Case 1: SQLColumns Method

rc = SQLColumns (... "UnknownTable" ...);// This call to SQLColumns will generate a query to the system catalogs... // possibly a join which must be prepared, executed, and produce a result setrc = SQLBindCol (...);rc = SQLExtendedFetch (...);// user must retrieve N rows from the server // N = # result columns of UnknownTable// result column information has now been obtained

Case 2: SQLDescribeCol Method

// prepare dummy query rc = SQLPrepare (... "SELECT * FROM UnknownTable WHERE 1 = 0" ...);// query is never executed on the server - only preparedrc = SQLNumResultCols (...);for (irow = 1; irow <= NumColumns; irow++) { rc = SQLDescribeCol (...) // + optional calls to SQLColAttributes


}// result column information has now been obtained// Note we also know the column ordering within the table! // This information cannot be assumed from the SQLColumns example.

In both cases, a query is sent to the server, but in Case 1, the query must be evaluated and form a result setthat must be sent to the client. Clearly, Case 2 is the better performing model.

To complicate this discussion, let us consider a database server that does not natively support preparing aSQL statement.The performance of Case 1 does not change, but the performance of Case 2 improves slightlybecause the dummy query is evaluated before being prepared. Because the Where clause of the query alwaysevaluates to FALSE, the query generates no result rows and should execute without accessing table data.Again, for this situation, Case 2 outperforms Case 1.

Retrieving Data

To retrieve data efficiently, return only the data that you need, and choose the most efficient method of doingso. The guidelines in this section will help you optimize system performance when retrieving data with ODBCapplications.

Retrieving Long DataBecause retrieving long data across the network is slow and resource-intensive, applications should not requestlong data (SQL_LONGVARCHAR, SQL_WLONGVARCHAR, and SQL_LONGVARBINARY data) unless it isnecessary.

Most users do not want to see long data. If the user does need to see these result items, the application canquery the database again, specifying only long columns in the select list. This technique allows the averageuser to retrieve the result set without having to pay a high performance penalty for network traffic.

Although the best approach is to exclude long data from the select list, some applications do not formulate theselect list before sending the query to the ODBC driver (that is, some applications simply SELECT * FROMtable_name ...). If the select list contains long data, the driver must retrieve that data at fetch time even ifthe application does not bind the long data in the result set. When possible, use a technique that does notretrieve all columns of the table.

Reducing the Size of Data RetrievedSometimes, long data must be retrieved. 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 data being retrieved to somemanageable limit by calling SQLSetStmtAttr with the SQL_ATTR_MAX_LENGTH option.

Eliminating SQL_LONGVARCHAR, SQL_WLONGVARCHAR, and SQL_LONGVARBINARY data from theresult set is ideal for optimizing performance.

Many application developers mistakenly assume that if they call SQLGetData with a container of size x thatthe ODBC driver only retrieves x bytes of information from the server. Because SQLGetData can be calledmultiple times for any one column, most drivers optimize their network use by retrieving long data in largechunks and then returning it to the user when requested. For example:

char CaseContainer[1000];...rc = SQLExecDirect (hstmt, "SELECT CaseHistory FROM Cases WHERE CaseNo = 71164", SQL_NTS);...rc = SQLFetch (hstmt);rc = SQLGetData (hstmt, 1, CaseContainer,(SWORD) sizeof(CaseContainer), ...);



At this point, it is more likely that an ODBC driver will retrieve 64 KB of information from the server instead of1 KB. In terms of network access, one 64-KB retrieval is less expensive than 64 retrievals of 1 KB. Unfortunately,the application may not call SQLGetData again; therefore, the first and only retrieval of CaseHistory would beslowed by the fact that 64 KB of data must be sent across the network.

Many ODBC drivers allow you to limit the amount of data retrieved across the network by supporting theSQL_MAX_LENGTH attribute.This attribute allows the driver to communicate to the database server that onlyx bytes of data are relevant to the client. The server responds by sending only the first x bytes of data for allresult columns. This optimization substantially reduces network traffic and improves client performance. Theprevious example returned only one row, but consider the case where 100 rows are returned in the resultset—the performance improvement would be substantial.

Using Bound ColumnsRetrieving data through bound columns (SQLBindCol) instead of using SQLGetData reduces the ODBC callload and improves performance.

Consider the following code fragment:rc = SQLExecDirect (hstmt, "SELECT <20 columns> FROM Employees WHERE HireDate >= ?", SQL_NTS);do { rc = SQLFetch (hstmt); // call SQLGetData 20 times} while ((rc == SQL_SUCCESS) || (rc == SQL_SUCCESS_WITH_INFO));

Suppose the query returns 90 result rows. In this case, 1891 ODBC calls are made (20 calls to SQLGetDatax 90 result rows + 91 calls to SQLFetch).

Consider the same scenario that uses SQLBindCol instead of SQLGetData:rc = SQLExecDirect (hstmt, "SELECT <20 columns> FROM Employees WHERE HireDate >= ?", SQL_NTS);// call SQLBindCol 20 timesdo {rc = SQLFetch (hstmt);} while ((rc == SQL_SUCCESS) || (rc == SQL_SUCCESS_WITH_INFO));

The number of ODBC calls made is reduced from 1891 to 111 (20 calls to SQLBindCol + 91 calls to SQLFetch).In addition to reducing the call load, many drivers optimize how SQLBindCol is used by binding result informationdirectly from the database server into the user’s buffer. That is, instead of the driver retrieving information intoa container and then copying that information to the user’s buffer, the driver simply requests the informationfrom the server be placed directly into the user’s buffer.

Using SQLExtendedFetch Instead of SQLFetchUse SQLExtendedFetch to retrieve data instead of SQLFetch. The ODBC call load decreases (resulting inbetter performance) and the code is less complex (resulting in more maintainable code).

Most ODBC drivers now support SQLExtendedFetch for forward only cursors; yet, most ODBC applicationsuse SQLFetch to retrieve data. Consider the examples in "Using Bound Columns", this time usingSQLExtendedFetch instead of SQLFetch:

rc = SQLSetStmtOption (hstmt, SQL_ROWSET_SIZE, 100);// use arrays of 100 elementsrc = SQLExecDirect (hstmt, "SELECT <20 columns> FROM Employees WHERE HireDate >= ?", SQL_NTS);// call SQLBindCol 1 time specifying row-wise bindingdo { rc = SQLExtendedFetch (hstmt, SQL_FETCH_NEXT, 0, &RowsFetched,RowStatus);} while ((rc == SQL_SUCCESS) || (rc == SQL_SUCCESS_WITH_INFO));

Notice the improvement from the previous examples. The initial call load was 1891 ODBC calls. By choosingODBC calls carefully, the number of ODBC calls made by the application has now been reduced to 4 (1SQLSetStmtOption + 1 SQLExecDirect + 1 SQLBindCol + 1 SQLExtendedFetch). In addition to reducing thecall load, many ODBC drivers retrieve data from the server in arrays, further improving the performance byreducing network traffic.


For ODBC drivers that do not support SQLExtendedFetch, the application can enable forward-only cursorsusing the ODBC cursor library:

(rc=SQLSetConnectOption (hdbc, SQL_ODBC_CURSORS, SQL_CUR_USE_IF_NEEDED);

Although using the cursor library does not improve performance, it should not be detrimental to applicationresponse time when using forward-only cursors (no logging is required). Furthermore, using the cursor librarymeans that the application can always depend on SQLExtendedFetch being available.This simplifies the codebecause the application does not require two algorithms (one using SQLExtendedFetch and one usingSQLFetch).

See alsoUsing Bound Columns on page 281

Choosing the Right Data TypeRetrieving and sending certain data types can be expensive. When you are working with data on a large scale,select the data type that can be processed most efficiently. For example, integer data is processed faster thanfloating-point data. Floating-point data is defined according to internal database-specific formats, usually in acompressed format. The data must be decompressed and converted into a different format so that it can beprocessed by the wire protocol.

Selecting ODBC Functions

The guidelines in this section will help you select which ODBC functions will give you the best performance.

Using SQLPrepare/SQLExecute and SQLExecDirectUsing SQLPrepare/SQLExecute is not always as efficient as SQLExecDirect. Use SQLExecDirect for queriesthat will be executed once and SQLPrepare/SQLExecute for queries that will be executed multiple times.

ODBC drivers are optimized based on the perceived use of the functions that are being executed.SQLPrepare/SQLExecute is optimized for multiple executions of statements that use parameter markers.SQLExecDirect is optimized for a single execution of a SQL statement. Unfortunately, more than 75% of allODBC applications use SQLPrepare/SQLExecute exclusively.

Consider the case where an ODBC driver implements SQLPrepare by creating a stored procedure on theserver that contains the prepared statement. Creating stored procedures involve substantial overhead, but thestatement can be executed multiple times. Although creating stored procedures is performance-expensive,execution is minimal because the query is parsed and optimization paths are stored at create procedure time.

Using SQLPrepare/SQLExecute for a statement that is executed only once results in unnecessary overhead.Furthermore, applications that use SQLPrepare/SQLExecute for large single execution query batches exhibitpoor performance. Similarly, applications that always use SQLExecDirect do not perform as well as those thatuse a logical combination of SQLPrepare/SQLExecute and SQLExecDirect sequences.

Using Arrays of ParametersPassing arrays of parameter values for bulk insert operations, for example, with SQLPrepare/SQLExecute andSQLExecDirect can reduce the ODBC call load and network traffic.To use arrays of parameters, the applicationcalls SQLSetStmtAttr with the following attribute arguments:

• SQL_ATTR_PARAMSET_SIZE sets the array size of the parameter.



• SQL_ATTR_PARAMS_PROCESSED_PTR assigns a variable filled by SQLExecute, which contains thenumber of rows that are actually inserted.

• SQL_ATTR_PARAM_STATUS_PTR points to an array in which status information for each row of parametervalues is returned.

Note: ODBC 3.x replaced the ODBC 2.x call to SQLParamOptions with calls to SQLSetStmtAttr using theSQL_ATTR_PARAMSET_SIZE, SQL_ATTR_PARAMS_PROCESSED_ARRAY, andSQL_ATTR_PARAM_STATUS_PTR arguments.

Before executing the statement, the application sets the value of each data element in the bound array. Whenthe statement is executed, the driver tries to process the entire array contents using one network roundtrip.For example, let us compare the following examples, Case 1 and Case 2.

Case 1: Executing Prepared Statement Multiple Timesrc = SQLPrepare (hstmt, "INSERT INTO DailyLedger (...) VALUES (?,?,...)", SQL_NTS);// bind parameters...do { // read ledger values into bound parameter buffers ... rc = SQLExecute (hstmt); // insert row} while ! (eof);

Case 2: Using Arrays of ParametersSQLPrepare (hstmt, " INSERT INTO DailyLedger (...) VALUES (?,?,...)", SQL_NTS);SQLSetStmtAttr (hstmt, SQL_ATTR_PARAMSET_SIZE, (UDWORD)100, SQL_IS_UINTEGER);SQLSetStmtAttr (hstmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &rows_processed, SQL_IS_POINTER);// Specify an array in which to return the status of // each set of parameters.SQLSetStmtAttr(hstmt, SQL_ATTR_PARAM_STATUS_PTR, ParamStatusArray, SQL_IS_POINTER);// pass 100 parameters per execute// bind parameters...do { // read up to 100 ledger values into // bound parameter buffers ... rc = SQLExecute (hstmt); // insert a group of 100 rows} while ! (eof);

In Case 1, if there are 100 rows to insert, 101 network roundtrips are required to the server, one to prepare thestatement with SQLPrepare and 100 additional roundtrips for each time SQLExecute is called.

In Case 2, the call load has been reduced from 100 SQLExecute calls to only 1 SQLExecute call. Furthermore,network traffic is reduced considerably.

Using the Cursor LibraryIf the driver provides scrollable cursors, do not use the cursor library.The cursor library creates local temporarylog files, which are performance-expensive to generate and provide worse performance than native scrollablecursors.

The cursor library adds support for static cursors, which simplifies the coding of applications that use scrollablecursors. However, the cursor library creates temporary log files on the user’s local disk drive to accomplish thetask. Typically, disk I/O is a slow operation. Although the cursor library is beneficial, applications should notautomatically choose to use the cursor library when an ODBC driver supports scrollable cursors natively.


Typically, ODBC drivers that support scrollable cursors achieve high performance by requesting that thedatabase server produce a scrollable result set instead of emulating the capability by creating log files. Manyapplications use:

rc = SQLSetConnectOption (hdbc, SQL_ODBC_CURSORS, SQL_CUR_USE_ODBC);

but should use:

rc = SQLSetConnectOption (hdbc, SQL_ODBC_CURSORS, SQL_CUR_USE_IF_NEEDED);

Managing Connections and Updates

The guidelines in this section will help you to manage connections and updates to improve system performancefor your ODBC applications.

Managing ConnectionsConnection management is important to application performance. Optimize your application by connectingonce and using multiple statement handles, instead of performing multiple connections. Avoid connecting toa data 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. Some ODBC applications are designed to call informational gathering routinesthat have no record of already attached connection handles. For example, some applications establish aconnection and then call a routine in a separate DLL or shared library that reattaches and gathers informationabout the driver. Applications that are designed as separate entities should pass the already connected HDBCpointer to the data collection routine instead of establishing a second connection.

Another bad practice is to connect and disconnect several times throughout your application to process SQLstatements. Connection handles can have multiple statement handles associated with them. Statement handlescan provide memory storage for information about SQL statements. Therefore, applications do not need toallocate new connection handles to process SQL statements. Instead, applications should use statementhandles to manage multiple SQL statements.

You can significantly improve performance with connection pooling, especially for applications that connectover a network or through the World Wide Web. With connection pooling, closing connections does not closethe physical connection to the database. When an application requests a connection, an active connectionfrom the connection pool is reused, avoiding the network round trips needed to create a new connection.

Connection and statement handling should be addressed before implementation. Spending time and thoughtfullyhandling connection management improves application performance and maintainability.

Managing Commits in TransactionsCommitting data is extremely disk I/O intensive and slow. If the driver can support transactions, always turnautocommit off.

What does a commit actually involve? The database server must flush back to disk every data page thatcontains updated or new data. This is not a sequential write but a searched write to replace existing data inthe table. By default, autocommit is on when connecting to a data source. Autocommit mode usually impairssystem performance because of the significant amount of disk I/O needed to commit every operation.

Some database servers do not provide an Autocommit mode. For this type of server, the ODBC driver mustexplicitly issue a COMMIT statement and a BEGIN TRANSACTION for every operation sent to the server. Inaddition to the large amount of disk I/O required to support Autocommit mode, a performance penalty is paidfor 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 long times, preventing other users from accessingthe rows. Commit transactions in intervals that allow maximum concurrency.

Choosing the Right Transaction ModelMany systems support distributed transactions; that is, transactions that span multiple connections. Distributedtransactions are at least four times slower than normal transactions due to the logging and network round tripsnecessary to communicate between all the components involved in the distributed transaction. Unless distributedtransactions are required, avoid using them. Instead, use local transactions when possible.

Using Positioned Updates and DeletesUse positioned updates and deletes or SQLSetPos to update data. Although positioned updates do not applyto all types of applications, developers should use positioned updates and deletes when it makes sense.Positioned updates (either through UPDATE WHERE CURRENT OF CURSOR or through SQLSetPos) allow thedeveloper to signal the driver to "change the data here" by positioning the database cursor at the appropriaterow to be changed. The designer is not forced to build a complex SQL statement, but simply supplies the datato be changed.

In addition to making the application more maintainable, positioned 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 to be changed are not needed. If the row must be located,the server typically has an internal pointer to the row available (for example, ROWID).

Using SQLSpecialColumnsUse SQLSpecialColumns to determine the optimal set of columns to use in the Where clause for updatingdata. Often, pseudo-columns provide the fastest access to the data, and these columns can only be determinedby using SQLSpecialColumns.

Some applications cannot be designed to take advantage of positioned updates and deletes.These applicationstypically update data by forming a Where clause consisting of some subset of the column values returned inthe result set. Some applications may formulate the Where clause by using all searchable result columns orby calling SQLStatistics to find columns that are part of a unique index. These methods typically work, but canresult in fairly complex queries.

Consider the following example:

rc = SQLExecDirect (hstmt, "SELECT first_name, last_name, ssn, address, city, state, zip FROM emp", SQL_NTS);// fetchdata...rc = SQLExecDirect (hstmt, "UPDATE EMP SET ADDRESS = ? WHERE first_name = ? AND last_name = ? AND ssn = ? AND address = ? AND city = ? AND state = ? AND zip = ?", SQL_NTS);// fairly complex query

Applications should call SQLSpecialColumns/SQL_BEST_ROWID to retrieve the optimal set of columns(possibly a pseudo-column) that identifies a given record. Many databases support special columns that arenot explicitly defined by the user in the table definition but are "hidden" columns of every table (for example,ROWID and TID). These pseudo-columns provide the fastest access to data because they typically point tothe exact location of the record. Because pseudo-columns are not part of the explicit table definition, they arenot returned from SQLColumns. To determine if pseudo-columns exist, call SQLSpecialColumns.


Consider the previous example again:

...rc = SQLSpecialColumns (hstmt, ..... ’emp’, ...);...rc = SQLExecDirect (hstmt, "SELECT first_name, last_name, ssn, address, city, state, zip, ROWID FROM emp", SQL_NTS);// fetch data and probably "hide" ROWID from the user...rc = SQLExecDirect (hstmt, "UPDATE emp SET address = ? WHERE ROWID = ?",SQL_NTS);// fastest access to the data!

If your data source does not contain special pseudo-columns, the result set of SQLSpecialColumns consistsof columns of the optimal unique index on the specified table (if a unique index exists).Therefore, your applicationdoes not need to call SQLStatistics to find the smallest unique index.



12Using Indexes

This chapter discusses the ways in which you can improve the performance of database activity using indexes.It provides general guidelines that apply to most databases. Consult your database vendor’s documentationfor more detailed information.


• Introduction

• Improving Row Selection Performance

• Indexing Multiple Fields

• Deciding Which Indexes to Create

• Improving Join Performance

Introduction

An index is a database structure that you can use to improve the performance of database activity. A databasetable can have one or more indexes associated with it.

An index is defined by a field expression that you specify when you create the index. Typically, the fieldexpression is a single field name, like emp_id. An index created on the emp_id field, for example, contains asorted list of the employee ID values in the table. Each value in the list is accompanied by references to therows that contain that value.


A database driver can use indexes to find rows quickly. An index on the emp_id field, for example, greatlyreduces the time that the driver spends searching for a particular employee ID value. Consider the followingWhere clause:

WHERE EMP_id = 'E10001'

Without an index, the server must search the entire database table to find those rows having an employee IDof E10001. By using an index on the emp_id field, however, the server can quickly find those rows.

Indexes may improve the performance of SQL statements.You may not notice this improvement with smalltables, but it can be significant for large tables; however, there can be disadvantages to having too manyindexes. Indexes can slow down the performance of some inserts, updates, and deletes when the driver hasto maintain the indexes as well as the database tables. Also, indexes take additional disk space.

Improving Row Selection Performance

For indexes to improve the performance of selections, the index expression must match the selection conditionexactly. For example, if you have created an index whose expression is last_name, the following Selectstatement uses the index:

SELECT * FROM emp WHERE last_name = 'Smith'

This Select statement, however, does not use the index:

SELECT * FROM emp WHERE UPPER(last_name) = 'SMITH'

The second statement does not use the index because the Where clause contains UPPER(last_name), whichdoes not match the index expression last_name. If you plan to use the UPPER function in all your Selectstatements and your database supports indexes on expressions, then you should define an index using theexpression UPPER(last_name).

Indexing Multiple Fields

If you often use Where clauses that involve more than one field, you may want to build an index containingmultiple fields. Consider the following Where clause:

WHERE last_name = 'Smith' AND first_name = 'Thomas'

For this condition, the optimal index field expression is last_name, first_name. This creates a concatenatedindex.

Concatenated indexes can also be used for Where clauses that contain only the first of two concatenated fields.The last_name, first_name index also improves the performance of the following Where clause (even thoughno first name value is specified):


Chapter 12: Using Indexes

last_name = 'Smith'

Consider the following Where clause:

WHERE last_name = 'Smith' AND middle_name = 'Edward' AND first_name = 'Thomas'

If your index fields include all the conditions of the Where clause in that order, the driver can use the entireindex. If, however, your index is on two nonconsecutive fields, for example, last_name and first_name, thedriver can use only the last_name field of the index.

The driver uses only one index when processing Where clauses. If you have complex Where clauses thatinvolve a number of conditions for different fields and have indexes on more than one field, the driver choosesan index to use. The driver attempts to use indexes on conditions that use the equal sign as the relationaloperator rather than conditions using other operators (such as greater than). Assume you have an index onthe emp_id field as well as the last_name field and the following Where clause:

WHERE emp_id >= 'E10001' AND last_name = 'Smith'

In this case, the driver selects the index on the last_name field.

If no conditions have the equal sign, the driver first attempts to use an index on a condition that has a lowerand upper bound, and then attempts to use an index on a condition that has a lower or upper bound.The driveralways attempts to use the most restrictive index that satisfies the Where clause.

In most cases, the driver does not use an index if the Where clause contains an OR comparison operator. Forexample, the driver does not use an index for the following Where clause:

WHERE emp_id >= 'E10001' OR last_name = 'Smith'

Deciding Which Indexes to Create

Before you create indexes for a database table, consider how you will use the table. The most commonoperations on a table are:

• Inserting, updating, and deleting rows

• Retrieving rows

If you most often insert, update, and delete rows, then the fewer indexes associated with the table, the betterthe performance. This is because the driver must maintain the indexes as well as the database tables, thusslowing down the performance of row inserts, updates, and deletes. It may be more efficient to drop all indexesbefore modifying a large number of rows, and re-create the indexes after the modifications.

If you most often retrieve rows, you must look further to define the criteria for retrieving rows and create indexesto improve the performance of these retrievals. Assume you have an employee database table and you willretrieve rows based on employee name, department, or hire date.You would create three indexes—one onthe dept field, one on the hire_date field, and one on the last_name field. Or perhaps, for the retrievals basedon the name field, you would want an index that concatenates the last_name and the first_name fields (see"Indexing Multiple Fields" for details).

Here are a few rules to help you decide which indexes to create:

• If your row retrievals are based on only one field at a time (for example, dept='D101'), create an indexon these fields.

• If your row retrievals are based on a combination of fields, look at the combinations.

• If the comparison operator for the conditions is And (for example, city = 'Raleigh' AND state ='NC'), then build a concatenated index on the city and state fields. This index is also useful for retrievingrows based on the city field.


• If the comparison operator is OR (for example, dept = 'D101' OR hire_date > {01/30/89}), anindex does not help performance. Therefore, you need not create one.

• If the retrieval conditions contain both AND and OR comparison operators, you can use an index if the ORconditions are grouped. For example:

dept = 'D101' AND (hire_date > {01/30/89} OR exempt = 1)

In this case, an index on the dept field improves performance.

• If the AND conditions are grouped, an index does not improve performance. For example:

(dept = 'D101' AND hire_date) > {01/30/89}) OR exempt = 1

See alsoIndexing Multiple Fields on page 288

Improving Join Performance

When joining database tables, index tables can greatly improve performance. Unless the proper indexes areavailable, queries that use joins can take a long time.

Assume you have the following Select statement:SELECT * FROM dept, emp WHERE dept.dept_id = emp.dept_id

In this example, the dept and emp database tables are being joined using the dept_id field. When the driverexecutes a query that contains a join, it processes the tables from left to right and uses an index on the secondtable’s join field (the dept field of the emp table). To improve join performance, you need an index on the joinfield of the second table in the FROM clause.

If the FROM clause includes a third table, the driver also uses an index on the field in the third table that joinsit to any previous table. For example:

SELECT * FROM dept, emp, addr WHERE dept.dept_id = emp.dept AND emp.loc = addr.loc

In this case, you should have an index on the emp.dept field and the addr.loc field.


Chapter 12: Using Indexes

13Locking and Isolation Levels

This chapter discusses locking and isolation levels and how their settings can affect the data you retrieve.Salesforce supports isolation level 0 (read uncommitted).


• Locking

• Isolation Levels

• Locking Modes and Levels

Locking

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

Locking is critical in multiuser databases, where different users can try to access or modify the same recordsconcurrently. Although such concurrent database activity is desirable, it can create problems. Without locking,for example, if two users try to modify the same record at the same time, they might encounter problems rangingfrom retrieving bad data to deleting data that the other user needs. If, however, the first user to access a recordcan lock that record to temporarily prevent other users from modifying it, such problems can be avoided. Lockingprovides a way to manage concurrent database access while minimizing the various problems it can cause.


Isolation Levels

An isolation level represents a particular locking strategy employed in the database system to improve dataconsistency. The higher the isolation level, the more complex the locking strategy behind it. The isolation levelprovided by the database determines whether a transaction will encounter the following behaviors in dataconsistency:

User 1 modifies a row. User 2 reads the same row before User 1 commits.User 1 performs a rollback. User 2 has read a row that has never really existedin the database. User 2 may base decisions on false data.

Dirty reads

User 1 reads a row, but does not commit. User 2 modifies or deletes the samerow and then commits. User 1 rereads the row and finds it has changed (orhas been deleted).

Non-repeatable reads

User 1 uses a search condition to read a set of rows, but does not commit.User 2 inserts one or more rows that satisfy this search condition, then commits.

Phantom reads

User 1 rereads the rows using the search condition and discovers rows thatwere not present before.

Isolation levels represent the database system’s ability to prevent these behaviors. The American NationalStandards Institute (ANSI) defines four isolation levels:

• Read uncommitted (0)

• Read committed (1)

• Repeatable read (2)

• Serializable (3)

In ascending order (0–3), these isolation levels provide an increasing amount of data consistency to thetransaction. At the lowest level, all three behaviors can occur. At the highest level, none can occur.The successof each level in preventing these behaviors is due to the locking strategies they use, which are as follows:

Locks are obtained on modifications to the database and held until end oftransaction (EOT). Reading from the database does not involve any locking.

Read uncommitted (0)

Locks are acquired for reading and modifying the database. Locks are releasedafter reading but locks on modified objects are held until EOT.

Read committed (1)

Locks are obtained for reading and modifying the database. Locks on allmodified objects are held until EOT. Locks obtained for reading data are held

Repeatable read (2)

until EOT. Locks on non-modified access structures (such as indexes andhashing structures) are released after reading.

All data read or modified is locked until EOT. All access structures that aremodified are locked until EOT. Access structures used by the query are lockeduntil EOT.

Serializable (3)

The following table shows what data consistency behaviors can occur at each isolation level.

Table 38: Isolation Levels and Data Consistency

Phantom ReadNonrepeatable ReadDirty ReadLevel

YesYesYes0, Read uncommitted

YesYesNo1, Read committed


Chapter 13: Locking and Isolation Levels

Phantom ReadNonrepeatable ReadDirty ReadLevel

YesNoNo2, Repeatable read

NoNoNo3, Serializable

Although higher isolation levels provide better data consistency, this consistency can be costly in terms of theconcurrency provided to individual users. Concurrency is the ability of multiple users to access and modify datasimultaneously. As isolation levels increase, so does the chance that the locking strategy used will createproblems in concurrency.

The higher the isolation level, the more locking involved, and the more time users may spend waiting for datato be freed by another user. Because of this inverse relationship between isolation levels and concurrency,you must consider how people use the database before choosing an isolation level.You must weigh thetrade-offs between data consistency and concurrency, and decide which is more important.

Locking Modes and Levels

Different database systems use various locking modes, but they have two basic modes in common: sharedand exclusive. Shared locks can be held on a single object by multiple users. If one user has a shared lock ona record, then a second user can also get a shared lock on that same record; however, the second user cannotget an exclusive lock on that record. Exclusive locks are exclusive to the user that obtains them. If one userhas an exclusive lock on a record, then a second user cannot get either type of lock on the same record.

Performance and concurrency can also be affected by the locking level used in the database system. Thelocking level determines the size of an object that is locked in a database. For example, many database systemslet you lock an entire table, as well as individual records. An intermediate level of locking, page-level locking,is also common. A page contains one or more records and is typically the amount of data read from the diskin a single disk access.The major disadvantage of page-level locking is that if one user locks a record, a seconduser may not be able to lock other records because they are stored on the same page as the locked record.



Chapter 13: Locking and Isolation Levels

14WorkAround Options

Progress DataDirect has included non-standard connection options your driver that enable you to take fulladvantage of packaged ODBC-enabled applications requiring non-standard or extended behavior.

To use these options, we recommend that you create a separate user data source for each application.

Your driver features the Extended Options configuration field on the Advanced tab of the driver’s Setupdialog box.You can use the Extended Options field to enter undocumented connection options when instructedby Progress DataDirect Technical Support.

Alternatively, you can make the change by updating the Registry. After you create the data source,

• On Windows, using the registry editor REGEDIT, open theHKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI section of the registry. Select the data sourcethat you created.

• On UNIX/Linux, using a text editor, open the odbc.ini file to edit the data source that you created.

Add the string WorkArounds= (or WorkArounds2=) with a value of n (WorkArounds=n or WorkArounds2=n),where the value n is the cumulative value of all options added together. For example, if you wanted to use bothWorkArounds=1 and WorkArounds=8, you would enter in the data source:

WorkArounds=9

Warning: Each of these options has potential side effects related to its use. An option should only be used toaddress the specific problem for which it was designed. For example, WorkArounds=2 causes the driver toreport that database qualifiers are not supported, even when they are. As a result, applications that use qualifiersmay not perform correctly when this option is enabled.

The following list includes both WorkArounds and WorkArounds2.


WorkArounds=1. Enabling this option causes the driver to return 1 instead of 0 if the value forSQL_CURSOR_COMMIT_BEHAVIOR or SQL_CURSOR_ROLLBACK_BEHAVIOR is 0. Statements areprepared again by the driver.

WorkArounds=2. Enabling this option causes the driver to report that database qualifiers are not supported.Some applications cannot process database qualifiers.

WorkArounds=8. Enabling this option causes the driver to return 1 instead of -1 for SQLRowCount. If anODBC driver cannot determine the number of rows affected by an Insert, Update, or Delete statement, it mayreturn -1 in SQLRowCount. This may cause an error in some products.

WorkArounds=16. Enabling this option causes the driver not to return an INDEX_QUALIFIER. For SQLStatistics,if an ODBC driver reports an INDEX_QUALIFIER that contains a period, some applications return a "tablenameis not a valid name" error.

WorkArounds=32. Enabling this option causes the driver to re-bind columns after calling SQLExecute forprepared statements.

WorkArounds=64. Enabling this option results in a column name of Cposition where position is the ordinalposition in the result set. For example, "SELECT col1, col2+col3 FROM table1" produces the columnnames "col1" and C2. For result columns that are expressions, SQLColAttributes/SQL_COLUMN_NAMEreturns an empty string. Use this option for applications that cannot process empty string column names.

WorkArounds=256. Enabling this option causes the value of SQLGetInfo/SQL_ACTIVE_CONNECTIONS tobe returned as 1.

WorkArounds=512. Enabling this option prevents ROWID results.This option forces the SQLSpecialColumnsfunction to return a unique index as returned from SQLStatistics.

WorkArounds=2048. Enabling this option causes DATABASE= instead of DB= to be returned. For some datasources, Microsoft Access performs more efficiently when the output connection string of SQLDriverConnectreturns DATABASE= instead of DB=.

WorkArounds=65536. Enabling this option strips trailing zeros from decimal results, which prevents MicrosoftAccess from issuing an error when decimal columns containing trailing zeros are included in the unique index.

WorkArounds=131072. Enabling this option turns all occurrences of the double quote character (") into theaccent grave character (`). Some applications always quote identifiers with double quotes. Double quoting cancause problems for data sources that do not return SQLGetInfo/SQL_IDENTIFIER_QUOTE_CHAR =double_quote.

WorkArounds=524288. Enabling this option forces the maximum precision/scale settings. The MicrosoftFoundation Classes (MFC) bind all SQL_DECIMAL parameters with a fixed precision and scale, which cancause truncation errors.

WorkArounds=1048576. Enabling this option overrides the specified precision and sets the precision to 256.Some applications incorrectly specify a precision of 0 for character types when the value will beSQL_NULL_DATA.

WorkArounds=2097152. Enabling this option overrides the specified precision and sets the precision to 2000.Some applications incorrectly specify a precision of -1 for character types.

WorkArounds=4194304. Enabling this option converts, for PowerBuilder users, all catalog function argumentsto uppercase unless they are quoted.

WorkArounds=16777216. Enabling this option allows MS Access to retrieve Unicode data types as it expectsthe default conversion to be to SQL_C_CHAR and not SQL_C_WCHAR.

WorkArounds=33554432. Enabling this option prevents MS Access from failing when SQLError returns anextremely long error message.

WorkArounds=67108864. Enabling this option allows parameter bindings to work correctly with MSDASQL.

WorkArounds=536870912. Enabling this option allows re-binding of parameters after calling SQLExecute forprepared statements.


Chapter 14: WorkAround Options

WorkArounds=1073741824. Enabling this option addresses the assumption by the application that ORDERBY columns do not have to be in the SELECT list. This assumption may be incorrect for data sources such asInformix.

WorkArounds2=2. Enabling this option causes the driver to ignore the ColumnSize/DecimalDigits specifiedby the application and use the database defaults instead. Some applications incorrectly specify theColumnSize/DecimalDigits when binding timestamp parameters.

WorkArounds2=4. Enabling this option reverses the order in which Microsoft Access returns native types sothat Access uses the most appropriate native type. Microsoft Access uses the last native type mapping, asreturned by SQLGetTypeInfo, for a given SQL type.

WorkArounds2=8. Enabling this option causes the driver to add the bindoffset in the ARD to the pointersreturned by SQLParamData. This is to work around an MSDASQL problem.

WorkArounds2=16. Enabling this option causes the driver to ignore calls to SQLFreeStmt(RESET_PARAMS)and only return success without taking other action. It also causes parameter validation not to use the bindoffset when validating the charoctetlength buffer. This is to work around a MSDASQL problem.

WorkArounds2=24. Enabling this option allows a flat-file driver, such as dBASE, to operate properly underMSDASQL.

WorkArounds2=32. Enabling this option appends "DSN=" to a connection string if it is not already included.Microsoft Access requires "DSN" to be included in a connection string.

WorkArounds2=128. Enabling this option causes 0 to be returned bySQLGetInfo(SQL_ACTIVE_STATEMENTS). Some applications open extra connections ifSQLGetInfo(SQL_ACTIVE_STATEMENTS) does not return 0.

WorkArounds2=256. Enabling this option causes the driver to return Buffer Size for Long Data on calls toSQLGetData with a buffer size of 0 on columns of SQL type SQL_LONGVARCHAR or SQL_LONGVARBINARY.Applications should always set this workaround when using MSDASQL and retrieving long data.

WorkArounds2=512. Enabling this option causes the flat-file drivers to return old literal prefixes and suffixesfor date, time, and timestamp data types. Microsoft Query 2000 does not correctly handle the ODBC escapesthat are currently returned as literal prefix and literal suffix.

WorkArounds2=1024. Enabling this option causes the driver to return "N" forSQLGetInfo(SQL_MULT_RESULT_SETS). ADO incorrectly interprets SQLGetInfo(SQL_MULT_RESULT_SETS)to mean that the contents of the last result set returned from a stored procedure are the output parameters forthe stored procedure.

WorkArounds2=2048. Enabling this option causes the driver to accept 2.x SQL type defines as valid. ODBC3.x applications that use the ODBC cursor library receive errors on bindings for SQL_DATE, SQL_TIME, andSQL_TIMESTAMP columns. The cursor library incorrectly rebinds these columns with the ODBC 2.x typedefines.

WorkArounds2=4096. Enabling this option causes the driver to internally adjust the length of empty strings.The ODBC Driver Manager incorrectly translates lengths of empty strings when a Unicode-enabled applicationuses a non-Unicode driver. Use this workaround only if your application is Unicode-enabled.

WorkArounds2=8192. Enabling this option causes Microsoft Access not to pass the error -7748. MicrosoftAccess only asks for data as a two-byte SQL_C_WCHAR, which is an insufficient buffer size to store the UCS2character and the null terminator; thus, the driver returns a warning, "01004 Data truncated" and returns a nullcharacter to Microsoft Access. Microsoft Access then passes error -7748.



Chapter 14: WorkAround Options

15Threading

The ODBC specification mandates that all drivers must be thread-safe, that is, drivers must not fail whendatabase requests are made on separate threads. It is a common misperception that issuing requests onseparate threads always results in improved throughput. Because of network transport and database serverlimitations, some drivers serialize threaded requests to the server to ensure thread safety.

The ODBC 3.0 specification does not provide a method to find out how a driver services threaded requests,although this information is useful to an application. All the Progress DataDirect for ODBC drivers provide thisinformation to the user through the SQLGetInfo information type 1028.

The result of calling SQLGetInfo with 1028 is a SQL_USMALLINT flag that denotes the session’s thread model.A return value of 0 denotes that the session is fully thread-enabled and that all requests use the threadedmodel. A return value of 1 denotes that the session is restricted at the connection level. Sessions of this typeare fully thread-enabled when simultaneous threaded requests are made with statement handles that do notshare the same connection handle. In this model, if multiple requests are made from the same connection, thefirst request received by the driver is processed immediately and all subsequent requests are serialized. Areturn value of 2 denotes that the session is thread-impaired and all requests are serialized by the driver.

Consider the following code fragment:

rc = SQLGetInfo (hdbc, 1028, &ThreadModel, NULL, NULL);

If (rc == SQL_SUCCESS) { // driver is a DataDirect driver that can report threading information

if (ThreadModel == 0) // driver is unconditionally thread-enabled; application can take advantage of // threading

else if (ThreadModel == 1) // driver is thread-enabled when thread requests are from different connections // some applications can take advantage of threading

else if (ThreadModel == 2) // driver is thread-impaired; application should only use threads if it reduces


// program complexity

}else // driver is not guaranteed to be thread-safe; use threading at your own risk


Chapter 15: Threading

16DataDirect Bulk Load

This chapter contains detailed information about the functions and statement attributes associated with DataDirectBulk Load.

For a full discussion of the features and operation of DataDirect Bulk Load, see "Using DataDirect Bulk Load."


• DataDirect Bulk Load Functions

• Utility Functions

• Export, Validate, and Load Functions

• DataDirect Bulk Load Statement Attributes

DataDirect Bulk Load Functions

The following DataDirect functions and parameters are not part of the standard ODBC API. They includefunctions for returning errors and warnings on bulk operations as well as functions for bulk export, loading, andverification:

• GetBulkDiagRec and GetBulkDiagRecW on page 302

• ExportTableToFile and ExportTableToFileW on page 304

• LoadTableFromFile and LoadTableFromFileW on page 307

• SetBulkOperation on page 311

• GetBulkOperation on page 312


Note: For your application to use DataDirect Bulk Load functionality, it must obtain driver connection handlesand function pointers, as follows:

1. Use SQLGetInfo with the parameter SQL_DRIVER_HDBC to obtain the driver’s connection handle fromthe Driver Manager.

2. Use SQLGetInfo with the parameter SQL_DRIVER_HLIB to obtain the driver’s shared library or DLL handlefrom the Driver Manager.

3. Obtain function pointers to the bulk load functions using the function name resolution method specific toyour operating system.The bulk.c source file shipped with the drivers contains the function resolveNamethat illustrates how to obtain function pointers to the bulk load functions.

All of this is detailed in the code examples shown in the following sections. All of these functions can be foundin the commented bulk.c source file that ships with the drivers. This file is located in the \samples\bulksubdirectory of the product installation directory along with a text file named bulk.txt. Please consult bulk.txtfor instructions about the bulk.c file.

Utility Functions

The example code in this section shows utility functions to which the DataDirect functions for bulk exporting,verification, and bulk loading refer, as well as the DataDirect functions GetBulkDiagRec and GetBulkDiagRecW.

GetBulkDiagRec and GetBulkDiagRecW

Syntax

SQLReturnGetBulkDiagRec (SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLCHAR* Sqlstate, SQLINTEGER* NativeError, SQLCHAR* MessageText, SQLSMALLINT BufferLength, SQLSMALLINT* TextLength);GetBulkDiagRecW (SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLWCHAR* Sqlstate, SQLINTEGER* NativeError, SQLWCHAR* MessageText, SQLSMALLINT BufferLength, SQLSMALLINT* TextLength);

The standard ODBC return codes are returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO,SQL_INVALID_HANDLE, SQL_NO_DATA, and SQL_ERROR.

DescriptionGetBulkDiagRec (ANSI application) and GetBulkDiagRecW (Unicode application) return errors and warningsgenerated by bulk operations. The argument definition, return values, and function behavior is the same as forthe standard ODBC SQLGetDiagRec and SQLGetDiagRecW functions with the following exceptions:

• The GetBulkDiagRec and GetBulkDiagRecW functions can be called after a bulk load, export or validatefunction is invoked to retrieve any error messages generated by the bulk operation. Calling these functionsafter any function except a bulk function is not recommended.


Chapter 16: DataDirect Bulk Load

• The values returned in the Sqlstate and MessageText buffers by the GetBulkDiagRecW function are encodedas UTF-16 on Windows platforms. On UNIX and Linux platforms, the values returned for Sqlstate andMessageText are UTF-16 if the value of the SQL_ATTR_APP_UNICODE_TYPE is SQL_DD_CP_UTF16and UTF-8 if the value of SQL_ATTR_APP_UNICODE_TYPE is SQL_DD_CP_UTF8.

• The handle passed as the Handle argument must be a driver connection handle obtained by callingSQLGetInfo (<ODBC Conn Handle>, SQL_DRIVER_HDBC).

• SQL_HANDLE_DBC is the only value accepted for HandleType. Any other value causes an error to bereturned.

Example

#include "qesqlext.h"

#ifndef NULL#define NULL 0#endif

#if (! defined (_WIN32)) && (! defined (_WIN64))typedef void * HMODULE;#endif

/* Get the address of a routine in a shared library or DLL. */void * resolveName ( HMODULE hmod, const char *name){#if defined (_WIN32) || defined (_WIN64)

return GetProcAddress (hmod, name);#elif defined (hpux) void *routine = shl_findsym (hmod, name);

shl_findsym (hmod, name, TYPE_PROCEDURE, &routine);

return routine;#else return dlsym (hmod, name);#endif}/* Get errors directly from the driver's connection handle. */void driverError (void *driverHandle, HMODULE hmod){ UCHAR sqlstate[16]; UCHAR errmsg[SQL_MAX_MESSAGE_LENGTH * 2]; SDWORD nativeerr; SWORD actualmsglen; RETCODE rc; SQLSMALLINT i; PGetBulkDiagRec getBulkDiagRec;

getBulkDiagRec = (PGetBulkDiagRec) resolveName (hmod, "GetBulkDiagRec");

if (! getBulkDiagRec) { printf ("Cannot find GetBulkDiagRec!\n"); return; }

i = 1;loop: rc = (*getBulkDiagRec) (SQL_HANDLE_DBC, driverHandle, i++, sqlstate, &nativeerr, errmsg, SQL_MAX_MESSAGE_LENGTH - 1, &actualmsglen);

if (rc == SQL_ERROR) {


printf ("GetBulkDiagRec failed!\n"); return; }

if (rc == SQL_NO_DATA_FOUND) return;

printf ("SQLSTATE = %s\n", sqlstate); printf ("NATIVE ERROR = %d\n", nativeerr); errmsg[actualmsglen] = '\0'; printf ("MSG = %s\n\n", errmsg); goto loop;}

Export, Validate, and Load Functions

The example code in this section shows the DataDirect functions for bulk exporting, verification, and bulkloading.

ExportTableToFile and ExportTableToFileW

Syntax

SQLReturnExportTableToFile (HDBC hdbc, SQLCHAR* TableName, SQLCHAR* FileName, SQLLEN IANAAppCodePage, SQLLEN ErrorTolerance, SQLLEN WarningTolerance, SQLCHAR* LogFile)ExportTableToFileW (HDBC hdbc, SQLWCHAR* TableName, SQLWCHAR* FileName, SQLLEN IANAAppCodePage, SQLLEN ErrorTolerance, SQLLEN WarningTolerance, SQLWCHAR* LogFile)

The standard ODBC return codes are returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO,SQL_INVALID_HANDLE, and SQL_ERROR.

PurposeExportTableToFile (ANSI application) and ExportTableToFileW (Unicode application) bulk export a table to aphysical file. Both a bulk data file and a bulk configuration file are produced by this operation.The configurationfile has the same name as the data file, but with an XML extension. The bulk export operation can create a logfile and can also export to external files. See "External Overflow Files" for more information.The export operationcan be configured such that if any errors or warnings occur:

• The operation always completes

• The operation always terminates




Parameters

hdbc

is the driver’s connection handle, which is not the handle returned by SQLAllocHandle orSQLAllocConnect. To obtain the driver's connection handle, the application must then use thestandard ODBC function SQLGetInfo (ODBC Conn Handle, SQL_DRIVER_HDBC).

TableName

is a null-terminated string that specifies the name of the source database table that contains the datato be exported.

FileName

is a null-terminated string that specifies the path (relative or absolute) and file name of the bulk loaddata file to which the data is to be exported. It also specifies the file name of the bulk configurationfile.The file name must be the fully qualified path to the bulk data file.This file must not already exist.If the file already exists, an error is returned.

IANAAppCodePage

specifies the code page value to which the driver must convert all data for storage in the bulk datafile. See "IANAAppCodePage" for details about IANAAppCodePage. Refer to "Character SetConversions" for more information.

The default value on Windows is the current code page of the machine. On UNIX/Linux, the defaultvalue is 4.

ErrorTolerance

specifies the number of errors to tolerate before an operation terminates. A value of 0 indicates thatno errors are tolerated; the operation fails when the first error is encountered. The default of -1means that an infinite number of errors is tolerated. WarningTolerance specifies the number ofwarnings to tolerate before an operation terminates. A value of 0 indicates that no warnings aretolerated; the operation fails when the first warning is encountered.


LogFile

is a null-terminated character string that specifies the path (relative or absolute) and file name of thebulk log file. Events logged to this file are:


• A message for each row that failed to export



Information about the load is written to this file, preceded by a header. Information about the nextload is appended to the end of the file.

If LogFile is NULL, no log file is created.


Example

HDBC hdbc;HENV henv;void *driverHandle;HMODULE hmod;PExportTableToFile exportTableToFile;

char tableName[128];char fileName[512];char logFile[512];int errorTolerance;int warningTolerance;int codePage;





exportTableToFile = (PExportTableToFile) resolveName (hmod, "ExportTableToFile");if (! exportTableToFile) { printf ("Cannot find ExportTableToFile!\n"); exit (255);}

rc = (*exportTableToFile) ( driverHandle, (const SQLCHAR *) tableName, (const SQLCHAR *) fileName, codePage, errorTolerance, warningTolerance, (const SQLCHAR *) logFile);if (rc == SQL_SUCCESS) { printf ("Export succeeded.\n");}else { driverError (driverHandle, hmod);}

See alsoExternal Overflow Files on page 107IANAAppCodePage on page 158Character Set Conversions on page 106



LoadTableFromFile and LoadTableFromFileW

Syntax

SQLReturnLoadTableFromFile (HDBC hdbc, SQLCHAR* TableName, SQLCHAR* FileName, SQLLEN ErrorTolerance, SQLLEN WarningTolerance, SQLCHAR* ConfigFile, SQLCHAR* LogFile, SQLCHAR* DiscardFile, SQLULEN LoadStart, SQLULEN LoadCount, SQLULEN ReadBufferSize)LoadTableFromFileW (HDBC hdbc, SQLWCHAR* TableName, SQLWCHAR* FileName, SQLLEN ErrorTolerance, SQLLEN WarningTolerance, SQLWCHAR* ConfigFile, SQLWCHAR* LogFile, SQLWCHAR* DiscardFile, SQLULEN LoadStart, SQLULEN LoadCount, SQLULEN ReadBufferSize)


PurposeLoadTableFromFile (ANSI application) and LoadTablefromFileW (Unicode application) bulk load data from afile to a table. The load operation can create a log file and can also create a discard file that contains rowsrejected during the load. The discard file is in the same format as the bulk load data file. After fixing reportedissues in the discard file, the bulk load can be reissued using the discard file as the bulk load data file.

The load operation can be configured such that if any errors or warnings occur:

• The operation always completes

• The operation always terminates


If a load fails, the LoadStart and LoadCount parameters can be used to control which rows are loaded whena load is restarted after a failure.

Parametershdbc

is the driver’s connection handle, which is not the handle returned by SQLAllocHandle or SQLAllocConnect.To obtain the driver's connection handle, the application must then use the standard ODBC function SQLGetInfo(ODBC Conn Handle, SQL_DRIVER_HDBC).

TableName

is a null-terminated character string that specifies the name of the target database table into which the data isto be loaded. For the Salesforce driver, the value of this parameter can vary. See "Using the TableNameParameter" for more information.

FileName


is a null-terminated string that specifies the path (relative or absolute) and file name of the bulk data file fromwhich the data is to be loaded. The file name must be the fully qualified path to the bulk data file.

ErrorTolerance

specifies the number of errors to tolerate before an operation terminates. A value of 0 indicates that no errorsare tolerated; the operation fails when the first error is encountered. The default of -1 means that an infinitenumber of errors is tolerated.

WarningTolerance

specifies the number of warnings to tolerate before an operation terminates. A value of 0 indicates that nowarnings are tolerated; the operation fails when the first warning is encountered. The default of -1 means thatan infinite number of warnings is tolerated.

ConfigFile

is a null-terminated character string that specifies the path (relative or absolute) and file name of the bulkconfiguration file.

LogFile

is a null-terminated character string that specifies the path (relative or absolute) and file name of the bulk logfile. The file name must be the fully qualified path to the log file. Events logged to this file are:

• Total number of rows read

• Message for each row that failed to load.

• Total number of rows that failed to load

• Total number of rows successfully loaded


If LogFile is NULL, no log file is created.

DiscardFile is a null-terminated character string that specifies the path (relative or absolute) and file nameof the bulk discard file. The file name must be the fully qualified path to the discard file. Any row that cannotbe inserted into database as result of bulk load is added to this file, with the last row to be rejected added tothe end of the file.


If DiscardFile is NULL, no discard file is created.

LoadStart specifies the first row to be loaded from the data file. Rows are numbered starting with 1. Forexample, when LoadStart=10, the first 9 rows of the file are skipped and the first row loaded is row 10. Thisparameter can be used to restart a load after a failure.

LoadCount specifies the number of rows to be loaded from the data file. The bulk load operation loads rowsup to the value of LoadCount from the file to the database. It is valid for LoadCount to specify more rows thanexist in the data file. The bulk load operation completes successfully when either the LoadCount value hasbeen loaded or the end of the data file is reached.This parameter can be used in conjunction with LoadStartto restart a load after a failure.

ReadBufferSize specifies the size, in KB, of the buffer that is used to read the bulk data file for a bulk loadoperation. The default is 2048.

Example

HDBC hdbc;HENV henv;void *driverHandle;



HMODULE hmod;PLoadTableFromFile loadTableFromFile;char tableName[128];char fileName[512];char configFile[512];char logFile[512];char discardFile[512];int errorTolerance;int warningTolerance;int loadStart;int loadCount;int readBufferSize;





loadTableFromFile = (PLoadTableFromFile) resolveName (hmod, "LoadTableFromFile");if (! loadTableFromFile) { printf ("Cannot find LoadTableFromFile!\n"); exit (255);}rc = (*loadTableFromFile) ( driverHandle, (const SQLCHAR *) tableName, (const SQLCHAR *) fileName, errorTolerance, warningTolerance, (const SQLCHAR *) configFile, (const SQLCHAR *) logFile, (const SQLCHAR *) discardFile, loadStart, loadCount, readBufferSize);if (rc == SQL_SUCCESS) { printf ("Load succeeded.\n");}else { driverError (driverHandle, hmod);}

Using the TableName Parameter with the Salesforce DriverThe value required in the TableName parameter varies, depending on the bulk operation specified in theSetBulkOperation function. The following paragraphs describe the TableName value based on whether theBulk Operation type is set to INSERT, DELETE, or UPSERT.

BULK_OPERATION_INSERTtable_name [(column_list)]

where:


column_list

is (columnSpec[, columnSpec]…)

columnSpec

can be columnName or foreignKeyColumnName EXT_ID externalIdColumnName

The column names define the mapping between columns in the table and columns in the bulk datafile. The column names can also indicate which columns are External ID columns. See "SQLStatements and Extensions" for more information.

The SQL equivalent of this function is:

INSERT INTO table_name [( column_list )] VALUES (? … ?)

BULK_OPERATION_DELETEtable_name (column_list)

where:

column_list

is the ID column, which identifies the row to delete.

For DELETE, the ID column is the only valid column in the column list.


DELETE FROM table_name WHERE <column> = ? AND <column> = ? …

BULK_OPERATION_UPDATEtable_name (column_list)

where:

column_list

is ID_column, <update column>[,<update column>]…

ID_column

must be one of the columns in the column list. The ID column identifies which row to update; theother columns are the list of columns to be updated.


UPDATE table_name SET <update column> = ? … WHERE <ID column> = ? …

BULK_OPERATION_UPSERTtable_name (column_list)

where:

column_list

is the same as for INSERT except that at least one of the columns must be identified as an externalID (see BULK_OPERATION_INSERT on page 309).

For UPSERT, column_list can be (columnSpec[, columnSpec]…)



columnSpec

can be one of the following:

• columnName

• foreignKeyColumnName EXT_ID externalIdColumnName

• extIdColumn EXT_ID

where extIdColumn is the column that is checked to determine whether the row already existsin the database.

The SQL equivalent of this function is one of the following:

• If no row matching the table’s key columns is found:

INSERT INTO table_name [(column_list)] VALUES (? … ?)

• If a row matching the table’s key columns is found:

UPDATE table_name SET <table column> = ? … WHERE <key column> = ? …

See "Specifying an External ID Column" for more information.


SetBulkOperation

Syntax

SQLReturnSetBulkOperation (HDBC hdbc, SQLULEN Operation)

The standard ODBC return codes are returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO,SQL_INVALID_HANDLE, SQL_NO_DATA, and SQL_ERROR.

PurposeSpecifies the bulk operation to be performed when the LoadTableFromFile and LoadTablefromFileW methodsare called. The bulk operation remains set until SetBulkOperation is called again. When a connection isestablished, the initial bulk operation is BULK_OPERATION_INSERT.

Parameters

hdbc

is the driver’s connection handle, which is not the handle returned by SQLAllocHandle orSQLAllocConnect. To obtain the driver's connection handle, the application must use SQLGetInfo(ODBC Conn Handle,SQL_DRIVER_HDBC).

Operation

is an integer value that specifies the bulk operation to set on the connection. It can have one of thefollowing values:

• 1 - BULK_OPERATION_INSERT


• 2 - BULK_OPERATION_UPDATE

• 3 - BULK_OPERATION_DELETE

• 4 - BULK_OPERATION_UPSERT

Example

HDBC hdbc;HENV henv;void *driverHandle;HMODULE hmod;PSetBulkOperation setBulkOperation;/* Get the driver's connection handle from the DM. This handle must be used when calling directly into the driver. */

rc = SQLGetInfo (hdbc, SQL_DRIVER_HDBC, &driverHandle, 0, NULL);if (rc != SQL_SUCCESS) { ODBC_error (henv, hdbc, SQL_NULL_HSTMT); EnvClose (henv, hdbc); exit (255);}/* Get the DM's shared library or DLL handle to the driver. */

rc = SQLGetInfo (hdbc, SQL_DRIVER_HLIB, &hmod, 0, NULL);if (rc != SQL_SUCCESS) { ODBC_error (henv, hdbc, SQL_NULL_HSTMT); EnvClose (henv, hdbc); exit (255);}/* Set the Bulk Operation type to DELETE. Any subsequent call to LoadTableFromFile(W) will result in a bulk delete of the rows specified. */

setBulkOperation = (PSetBulkOperation) resolveName (hmod, "SetBulkOperation");if (! setBulkOperation) { printf ("Cannot find SetBulkOperation!\n"); exit (255);}

rc = (*setBulkOperation) ( driverHandle, BULK_OPERATION_DELETE);if (rc == SQL_SUCCESS) { printf ("Set Bulk operation(DELETE) succeeded.\n");}else { driverError (driverHandle, hmod);}/* */

See alsoLoadTableFromFile and LoadTableFromFileW on page 307

GetBulkOperation

Syntax

SQLReturnGetBulkOperation (HDBC hdbc, SQLULEN Operation)




PurposeReturns the bulk operation currently set on the connection. The bulk operation specifies the operation to beperformed when the LoadTableFromFile or LoadTableFromFileW methods are called (see "LoadTableFromFileand LoadTableFromFileW").

Parameters

hdbc

is the driver’s connection handle, which is not the handle returned by SQLAllocHandle orSQLAllocConnect. To obtain the driver's connection handle, the application must then use thestandard ODBC function SQLGetInfo (ODBC Conn Handle, SQL_DRIVER_HDBC).

Operation

is a pointer to the location where current bulk operation specified for the connection is returned. Thereturned value is one of the operation values defined by SetBulkOperation.

Example

HDBC hdbc;HENV henv;void *driverHandle;HMODULE hmod;PGetBulkOperation getBulkOperation;SQLULEN bulkOperationType;





/* Get the current value for bulk operation. */

getBulkOperation = (PGetBulkOperation) resolveName (hmod, "GetBulkOperation");if (! getBulkOperation) { printf ("Cannot find GetBulkOperation!\n"); exit (255);}

rc = (*getBulkOperation) ( driverHandle, &bulkOperationType);if (rc == SQL_SUCCESS) { printf ("Current bulk operation is: %u.\n", bulkOperationType);}else { driverError (driverHandle, hmod);}


/* */

See alsoLoadTableFromFile and LoadTableFromFileW on page 307SetBulkOperation on page 311

DataDirect Bulk Load Statement Attributes

In addition to exporting tables with the ExportTableToFile methods, result sets can be exported to a bulk loaddata file through the use of two DataDirect statement attributes, SQL_BULK_EXPORT_PARAMS andSQL_BULK_EXPORT. SQL_BULK_EXPORT_PARAMS is used to configure information about where andhow the data is to be exported. SQL_BULK_EXPORT begins the bulk export operation.

SQL_BULK_EXPORT_PARAMSThe ValuePtr argument to SQLSetStmtAttr or SQLSetStmtAttrW when the attribute argument isSQL_BULK_EXPORT_PARAMS is a pointer to a BulkExportParams structure. The definitions of the fields inthe BulkExportParams structure are the same as the corresponding arguments in the "ExportTableTo File andExportTableToFileW" methods except that the generation of the log file is controlled by the EnableLoggingfield. When EnableLogging is set to 1, the driver writes events that occur during the export to a log file. Eventslogged to this file are:

• A message for each row that failed to export.




The log file is located in the same directory as the bulk load data file and has the same base name as the bulkload data file with a .log extension. When EnableLogging is set to 0, no logging takes place

If the bulk export parameters are not set prior to setting the SQL_BULK_EXPORT attribute, the driver usesthe current driver code page value, defaults EnableLogging to 1 (enabled), and defaults ErrorTolerance andWarningTolerance to -1 (infinite).

The SQL_BULK_EXPORT_PARAMS structure is as follows:

struct BulkExportParams { SQLLEN Version; /* Must be the value 1 */ SQLLEN IANAAppCodePage; SQLLEN EnableLogging; SQLLEN ErrorTolerance; SQLLEN WarningTolerance;};

See alsoExportTableToFile and ExportTableToFileW on page 304



SQL_BULK_EXPORTThe ValuePtr argument to SQLSetStmtAttr or SQLSetStmtAttrW when the attribute argument isSQL_BULK_EXPORT is a pointer to a string that specifies the file name of the bulk load data file to which thedata in the result set will be exported.

Result set export occurs when the SQL_BULK_EXPORT statement attribute is set. If using theSQL_BULK_EXPORT_PARAMS attribute to set values for the bulk export parameters, theSQL_BULK_EXPORT_PARAMS attribute must be set prior to setting the SQL_BULK_EXPORT attribute. Onceset, the bulk export parameters remain set for the life of the statement. If the bulk export parameters are notset prior to setting the SQL_BULK_EXPORT attribute, the driver uses the current driver code page value,defaults EnableLogging to 1 (enabled), and defaults ErrorTolerance and WarningTolerance to -1 (infinite).

Both a bulk load data file and a bulk load configuration file are produced by this operation. The configurationfile has the same base name as the bulk load data file, but with an XML extension. The configuration file iscreated in the same directory as the bulk load data file.


Glossary

applicationAn application, as it relates to the ODBC standard, performs tasks such as: requesting a connection to a datasource; sending SQL requests to a data source; processing errors; and terminating the connection to a datasource. It may also perform functions outside the scope of the ODBC interface.

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

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

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

conformanceThere are two types of conformance levels for ODBC drivers—ODBC API and ODBC SQL grammar (see SSLclient/server authentication on page 320). Knowing the conformance levels helps you determine the range offunctionality available through the driver, even if a particular database does not support all of the functionalityof a particular level.

For ODBC API conformance, most quality ODBC drivers support Core, Level 1, and a defined set of Level 2functions, depending on the database being accessed.

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

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


connection stringA string passed in code that specifies connection information directly to the Driver Manager and driver.

data sourceA data source includes both the source of data itself, such as relational database, a flat-file database, or evena text file, and the connection information necessary for accessing the data. Connection information may includesuch things as server location, database name, logon ID, and other driver options. Data source information isusually stored in a DSN (Data Source Name).

driverAn ODBC driver communicates with the application through the Driver Manager and performs tasks such as:establishing a connection to a data source; submitting requests to the data source; translating data to and fromother formats; returning results to the application; and formatting errors into a standard code and returningthem to the application.

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

DSN (Data Source Name)A DSN stores the data source information (see Data Source) necessary for the Driver Manager to connect tothe database. This can be configured either through the ODBC Administrator or in a DSN file. On Windows,the information is called a system or user DSN and is stored in the Registry. Data source information can alsobe stored in text configuration files, as is the case on non-Windows platforms. Applications deployed in theglobal assembly cache must have a strong name to handle name and version conflicts.

DTC (Distributed Transaction Coordinator)On Windows platforms, the DTC is a system service that is part of COM+ services. COM+ components thatuse DTC can enlist ODBC connections in distributed transactions. This makes it possible to scale transactionsfrom one to many computers without adding special code.

failoverFailover allows an application to connect to an alternate, or backup, database server if the primary databaseserver is unavailable, for example, because of a hardware failure or traffic overload. Progress DataDirect forODBC drivers provide different levels of failover: connection failover, extended connection failover, and selectfailover.

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

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

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

• Read uncommitted (0)

• Read committed (1)

• Repeatable read (2)

• Serializable (3)

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

load balancingSee client load balancing.


Glossary

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

MTS (Microsoft Transaction Server)MTS is a component-based transaction processing system for developing, deploying, and managinghigh-performance, scalable, and robust enterprise, Internet, and intranet server applications. MTS was theprecursor to COM+, the current version of this processing system (see DTC (Distributed TransactionCoordinator)).

ODBC AdministratorThe ODBC Data Source Administrator manages database drivers and configures DSNs. On computers runningthe Windows 7 and higher operating systems, this application is located in the Windows Control Panel underAdministrative Tools. Its icon is named "Data Sources (ODBC)."

In Linux environments, the DataDirect Linux ODBC Data Source Administrator is located in the /tools directoryof the product installation directory.

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

Performance Tuning WizardAn applet shipped with your driver that leads you step-by-step through a series of questions about yourapplication. Based on your answers, the Wizard provides the optimal settings for driver connection propertiesthat affect performance.

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

SQL Grammar

ODBC defines a core grammar that roughly corresponds to the X/Open and SQL Access Group SQL CAEspecification (1992). ODBC also defines a minimum grammar, to meet a basic level of ODBC conformance,and an extended grammar, to provide for common DBMS extensions to SQL. The following list summarizesthe grammar included in each conformance level:

Minimum SQL Grammar:

• Data Definition Language (DDL): CREATE TABLE and DROP TABLE.

• Data Manipulation Language (DML): simple SELECT, INSERT, UPDATE SEARCHED, and DELETESEARCHED.

• Expressions: simple (such as A > B + C).

• Data types: CHAR, VARCHAR, or LONG VARCHAR.

Core SQL Grammar:

• Minimum SQL grammar and data types.

• DDL: ALTER TABLE, CREATE INDEX, DROP INDEX, CREATE VIEW, DROP VIEW, GRANT, and REVOKE.

• DML: full SELECT.

• Expressions: subquery, set functions such as SUM and MIN.


Glossary

• Data types: DECIMAL, NUMERIC, SMALLINT, INTEGER, REAL, FLOAT, DOUBLE PRECISION.

Extended SQL Grammar:

• Minimum and Core SQL grammar and data types.

• DML: outer joins, positioned UPDATE, positioned DELETE, SELECT FOR UPDATE, and unions.

• Expressions: scalar functions such as SUBSTRING and ABS, date, time, and timestamp literals.

• Data types: BIT, TINYINT, BIGINT, BINARY, VARBINARY, LONG VARBINARY, DATE, TIME, TIMESTAMP.

• Batch SQL statements.

• Procedure calls.

Secure Sockets Layer (SSL)SSL is an industry-standard protocol for sending encrypted data over database connections. SSL secures theintegrity of your data by encrypting information and providing SSL client/SSL server authentication. See alsoSSL client/server authentication.

SSL client/server authenticationSSL works by allowing the client and server to send each other encrypted data that only they can decrypt. SSLnegotiates the terms of the encryption in a sequence of events known as the SSL handshake. The handshakeinvolves the following types of authentication:

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

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

UnicodeUnicode, developed by the Unicode Consortium, is a standard that attempts to provide unique coding for allinternational language characters. The current number of supported characters is over 109,000.

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


Glossary

Index

AAccess Token 133Add clause

constraints 192adding connections to a connection pool 93address, IP 96Administrator

Windows ODBC and tracing 114Administrator, Data Source

Windows 32Advanced options 53aggregate functions 227AIX, See UNIX and LinuxAlter Cache (EXT) 186Alter Index 188Alter Sequence 188Alter Session (EXT) 189Alter Table 190application 317Application Using Threads connection option 134arithmetic operators 240arrays of parameter values, passing 282AuditColumns config option 143authentication

SSL client 91SSL server 91user ID/password 88

Authentication Method 134authentication methods 56Autocommit mode 284

Bbatch inserts/selects, using bulk API for 109binary

literals 239operators 239

bound columns 281bulk

configuring 62export and load methods 101exporting data from a database 101loading to a database 103

bulk APIbatch inserts/selects 109

Bulk Fetch Threshold connection option 135bulk load

bulk data configuration file 105configuration file 315data file 315

bulk load (continued)external overflow file 107functions

bulk errors 302bulk export 304bulk load 307, 311–312utility 302

overview 100sample application 106statement attributes 314validating files 104verifying the configuration file 105

Bulk Load Asynchronous connection option 136Bulk Load Batch Size connection option 137Bulk Load Concurrency Mode connection option 137Bulk Load Poll Interval connection option 138Bulk Load Threshold connection option 139Bulk Load Timeout connection option 140Bulk Tab 62

Ccache

changing the definition of a cache 186creating 196disabling 80enabling 80, 200initial check of data 199metadata 81modifying a definition 79refreshing 223refreshing data 80relational 198setting the life span of data 200

Cachecreating 79dropping a 81

caches, client-side 78caching information to improve performance 278Call Limit clause 201call load, reducing 281catalog functions, using 278catalog tables 81changes to behavior for release 8.0.0 14character encoding 269character set conversions 106character string literals 238ClearPool and ClearAllPools methods 93client code page, See code pagesClient ID 140client load balancing 317


Index

Client Secret 141client-side caches 78Close() method

effect on the connection string 93code pages

IANAAppCodePage attribute 158, 251column

definition 210names 237

column mapping with bulk load 309comma-separated value (CSV) format file

character set conversions 106use in bulk load 105

comparison operators 240concatenation operator 240conditions 243config options

AuditColumns 143CustomSuffix 144KeywordConflictSuffix 144MapSystemColumnNames 145NumberFieldMapping 146UppercaseIdentifiers 147

Config Options connection option 142configuration file

bulk data 105configuring

connection pooling 61server mode 74user ID/password authentication

Salesforce 89configuring a data source

UNIX and Linux 35Windows

using a GUI 47configuring Java logging 119conformance 317connecting

proxy server 71connecting via connection string

data source 69connection attribute

ApplicationUsingThreads 134BulkFetchThreshold 135BulkLoadAsync 136BulkLoadBatchSize 137BulkLoadConcurrencyMode 137BulkLoadFieldDelimiter 156BulkLoadPollInterval 138BulkLoadRecordDelimiter 171BulkLoadThreshold 139BulkLoadTimeout 140ConfigOptions 142ConnectionReset 149CreateDB 149CreateMap 150

connection attribute (continued)Database 151DataSourceName 151Description 152EnableBulkFetch 153EnableBulkLoad 154EnablePKChunking 155FetchSize 155HostName 157InitializationString 159JVMArgs 160JVMClasspath 161LoadBalanceTimeout 162LogConfigFile 162LoginTimeout 163LogonDomain 164LogonID 181MaxPoolSize 164MinPoolSize 165Password 166PKChunkSize 167ProxyHost 168ProxyPassword 168ProxyPort 169ProxyUser 169ReadOnly 170RefreshDirtyCache 171RefreshSchema 172ReportCodepageConversionErrors 174SchemaMap 148, 175SecurityToken 176ServerPortNumber 177SQLEngineMode 178StmtCallLimit 179StmtCallLimitBehavior 179TransactionMode 180WSFetchSize 181WSPoolSize 182WSRetryCount 183WSTimeout 184

connection handles 284connection issues 122connection option

Authentication Method 134connection options

Access Token 133Application Using Threads 134Bulk Fetch Threshold 135Bulk Load Asynchronous 136Bulk Load Batch Size 137Bulk Load Concurrency Mode 137Bulk Load Poll Interval 138Bulk Load Threshold 139Bulk Load Timeout 140Client ID 140Client Secret 141


Index

connection options (continued)Config Options 142Connection Reset 149Create Database 149Create Map 150Data Source Name 151Database 151Description 152Enable Primary Key Chuncking 155EnableBulkFetch 153EnableBulkLoad 154Fetch Size 155Field Delimiter 156for Bulk Load 107, 110Host Name 157IANAAppCodePage 158Initialization String 159JVM Arguments 160JVM Classpath 161LoadBalance Timeout 162Log Config File 162Login Timeout 163Logon Domain 164Max Pool Size 164Min Pool Size 165Password 166Primary Key Chunk Size 167Proxy Host 168Proxy Password 168Proxy Port 169Proxy User 169Read Only 170Record Delimiter 171Refresh Dirty Cache 171Refresh Schema 172Refresh Token 173Report Codepage Conversion Errors 174required 47Schema Map 148, 175Security Token 176Server Port Number 177SQL Engine Mode 178Statement Call Limit 179Statement Call Limit Behavior 179TransactionMode 180User Name 181WSFetch Size 181WSPoolSize 182WSRetry Count 183WSTimeout 184

connection pooladding connections 93ClearPool and ClearAllPools methods 93creating 93dead connections 94removing connections 93

connection pool (continued)returning connections to 93when a physical connection to a server is lost 94

connection pooling 92, 317connection properties

for connection pooling 95for security 92

Connection Reset connection option 149connection retry 317connection string 318connection string attributes 127connection string options

effect of Close and Dispose methods 93connections

optimizing 284supported 98

constraint definition 207, 212contacting Technical Support 30correlated subqueries 245Create Cache

Referencing clause 198Refresh Interval clause 199

Create Cache (EXT) 196Create Database connection option 149–150Create Index 203Create Sequence 203Create Table statement 204Create View statement 216creating a local table 208CSV, See comma-separated valuecursor library, performance implications of using 283CustomSuffix config option 144

Ddata encryption 50, 53, 90data retrieval, optimizing 280data source

configuringUNIX and Linux 33, 41Windows 32

connecting via connection string 69connecting via logon dialog box 70

Data Source AdministratorWindows 32

Data Source Name connection option 151data types

choosing 282Salesforce 28

Database connection option 151database connections, testing 120DataDirect Bulk Load

about 100character set conversions 106external overflow file 107

date and time functions 264


Index

date/time literals 239ddlogging.properties file 120ddtestlib tool 40, 116dead connections in a connection pool 94Delete statement 217Description connection option 152determining optimal set of columns 285diagnostic tools 113dirty reads 292Dispose() method, effect on the connection string 93distributed transactions 285double-byte character sets in UNIX and Linux 269driver

API and scalar functions 257code page values 251logging for 117ODBC compliance 17optimizing application performance 277threading 299using DataDirect bulk load 301

Driver Managererror messages 121support 46version string 18

driver requirements 17Driver to SQL Communication logger 118drivers

version string information 18Drop Cache (EXT) 218Drop clause 192, 195Drop Index 219Drop Sequence 219Drop Table statement 220Drop View 220DSN (Data Source Name) 318DTC (Distributed Transaction Coordinator) 318

EEnable Bulk Fetch connection option 153Enable Bulk Load connection option 154Enable Primary Key Chunking connection option 155Enabled clause 200enabling tracing 114encryption

data 90SSL 90

environmentvariables 38

environment variable, library path 123error messages

general 121UNIX and Linux 121Windows 121

examplebulk load sample application 106

example (continued)character set conversions 106

example application 120Except operator 233executing SQL 120EXISTS predicate 245Explain Plan 221exporting result sets to a bulk load data file 314ExportTableToFile 304ExportTableToFileW 304Extended Options 50, 53, 295external ID column

specifying 222external overflow file 107

Ffailover 318Fetch Size connection option 155Field Delimiter connection option 156Filter clause 202Foreign Key clause 212From clause 228functionality

changes 14new 14

functions, ODBCDataDirect functions for bulk operations 301selecting for performance 282

GGeneral Tab 47GetBulkDiagRec 302GetBulkDiagRecW 302GetBulkOperation 312Group By clause 231

Hhandles

connection 284statement 284

Having clause 231Host Name connection option 157

IIANAAppCodePage

connection option values 251IANAAppCodePage connection option

connection attribute 158IANAAppCodePage values 251identifiers, using 96


Index

improvingdatabase performance 287index performance 287join performance 290ODBC application performance 125, 277record selection performance 288

IN predicate 244index 318indexes

deciding which to create 289improving performance 287overview 287

indexing multiple fields 288Initial Check clause 199Initialization String connection option 159Insert statement 221integer literals 239internationalization 267interoperability issues 124Intersect operator 232IP addresses 96IPv4 96IPv6 96isolation level 318isolation levels

about 292read committed 292read uncommitted 292repeatable read 292serializable 292

isolation levels and data consistencycompared 292dirty reads 292non-repeatable reads 292phantom reads 292

ivtestlib tool 40, 116

JJava logging

configuring 119SQL engine logger 118

Java Logging for the SQL Engine Server 78Java Path 74join in a From clause 229JVM Arguments connection option 160JVM Classpath connection option 161

KKerberos 318KeywordConflictSuffix config option 144

Llibrary path environment variable

setting on UNIX/Linux 35setting on Windows 32

Limit clause 235Linux, See UNIX and Linuxliterals

about 237binary 239character string 238date/time 239integer 239numeric 238

load balancing 318LoadBalance Timeout connection option 162LoadTableFromFile 307LoadTableFromFileW 307local table

constraints 212creating 208defining columns 210deleting rows 217

local tables 97locale 268localization 267locking 291locking level 319locking levels 98locking modes and levels 293Log Config File connection option 162logging, Java

components 117configuring 119SQL engine logger 118

logical operators 242Login Timeout connection option 163Logon Domain connection option 164long data, retrieving 280

Mmanaging connections 284mapping objects to tables 27MapSystemColumnNames config option 145Max Pool Size connection option 164MIBenum value 251Min Pool Size connection option 165Minus operator 233MTS (Microsoft Transactcion Server) 319

NNew Features and Enhancements for Release 8.0.0 14Next Value For clause 204non-repeatable reads 292


Index

NumberFieldMapping config option 146numeric functions 263numeric literals 238

Ooauth2.0 56object

mapping to tables 27ODBC

API functions 257call load, reducing 281designing for performance 277functions, selecting for performance 282how the architecture works 250scalar functions 259specification 17

ODBC Administrator 319ODBC application performance design 125ODBC conformance 17ODBC Test 117ODBC Trace 113odbc.ini

encoding 276sample 43

odbc.ini (system information) fileconfiguring with 41

odbc.ini filecontrolling tracing with 115

odbcinst.iniencoding 276

Open Database Connectivity, See ODBC specificationOpenSSL cipher suites

driver support 90operators

arithmetic 240comparison 240concatenation 240logical 242precedence 242

optimization, performance 277Order By clause 234OS authentication 319overflow files for bulk load operations 107

Pparameter metadata 99parameter values, passing arrays of 282Password connection option 166performance 125performance considerations 71performance optimization

avoiding catalog functions 278avoiding search patterns 279commits in transactions 284

performance optimization (continued)managing connections 284overview 277reducing the size of retrieved data 280retrieving long data 280using a dummy query 279using bound columns 281

Performance Tuning Wizard 319performance, improving

database using indexes 287index 287join 290record selection 288

Persist clause 200phantom reads 292Pooling Tab 61positioned updates and deletes 285predicate

EXISTS 245IN 244UNIQUE 245

Primary Key Chunk Size connection option 167Primary Key clause 212properties file for Java logging

JVM 119Proxy Host connection option 168Proxy Password connection option 168Proxy Port connection option 169proxy server, connecting through 71Proxy User connection option 169

Rread committed 292Read Only connection option 170read uncommitted 292reauthentication 319Record Delimiter connection option 171Refresh Cache (EXT) 223Refresh Dirty Cache connection option 171Refresh Map (EXT) 224Refresh Schema connection option 172Refresh Token 173relational cache 198remote table

altering 190altering a table 190changing the definition of a cache 186creating 205dropping a table in the SFORCE schema 220refreshing data in the cache 223

removing connections from a connection pool 93Rename clause 196repeatable read 292Report Codepage Conversion Errors connection option174


Index

reports 88retrieving data, optimizing 280returning the bulk operation on the connection 312

SSalesforce

configuringuser ID/password authentication 89

user ID/password authenticationconfiguring 89

Salesforce driverdata types 28

scalar functions, ODBC 259Schema Map connection option 148, 175scrollable cursors 283search patterns, avoiding 279Secure Sockets Layer, See See SSLSecure Sockets Layer (SSL) 320security

authentication 88Security options 56Security Token connection option 176Select clause 226Select statement 224serializable isolation level 292Server DB Directory 74server mode, configuring 74Server Port Number connection option 177Services 74SetBulkOperation 311setting library path environment variable

on UNIX/Linux 35on Windows 32

setup issues 122SQL

executing 120expressions 236

SQL engine logger 118SQL Engine Mode connection option 178SQL engine, starting

UNIX/Linux 76SQL engine, stopping

UNIX/Linux 77SQL engine, using

UNIX/Linux 76Windows 73

SQL Grammar 320SQL statement support 185SQL statements

Alter Cache 186Alter Index 188Alter Sequence 188Alter Session 189Create Sequence 203Drop Cache 218

SQL statements (continued)Drop Index 219Drop Sequence 219Drop Table 220Drop View 220Explain Plan 221Insert 221Refresh Cache 223Update 235

SQL supported 98SQLExecDirect, advantages of using 282SQLFetch, disadvantage of using 281SQLSpecialColumns, determining optimal set of columns285SSL

client authentication 91encryption 90server authentication 91

SSL client/server authentication 320standards, ODBC specification compliance 17starting

SQL engine serverUNIX/Linux 76

statement attributes for DataDirect bulk load operations314Statement Call Limit Behavior connection option 179Statement Call Limit connection option 179statement handles, using to manage SQL statements284statements supported 98static cursors 283stopping the SQL engine server

UNIX/Linx 77string functions 261subqueries

correlated 245overview 244

subquery in a From clause 230system functions 266system information file (.odbc.ini) 41, 115SYSTEM_CACHE_REFERENCES Catalog Table 83SYSTEM_CACHES catalog table 81SYSTEM_REMOTE_SESSIONS system table 84SYSTEM_SESSIONINFO system table 85SYSTEM_SESSIONS table 86

Ttables

local 97Technical Support, contacting 30test connect

UNIX and Linux 36testing database connections 120testing the connection

Windows 33


Index

threading, overview 299time functions 264timeouts 97tools

diagnostic 113other 121

trace log 113tracing

creating a trace log 113enabling with system information file 115enabling with Windows ODBC Administrator 114

tracking JDBC calls 117Transaction Mode connection option 180transactions, managing commits 284troubleshooting 113, 122

UUCS-2 269unary operator 239undocumented connection options 50, 53Unicode

character encoding 269ODBC drivers 271support in databases 270support in ODBC 270

Unicode support 98Union operator 232Unique clause 212UNIQUE predicate 245UNIX and Linux

configuring a data source 35configuring through the system information (odbc.ini)file 41data source configuration 33, 41double-byte character sets 269driver names 26environment

DD_INSTALLDIR 40ddtestlib tool 40introduction 38ivtestlib tool 40library search path 38ODBCINI 39ODBCINST 39system information file (.odbc.ini) 41

error messages 121system information (odbc.ini) file, configuring through41system requirements 22

Update statement 235updates, optimizing 284UppercaseIdentifiers config option 147user ID/password

authentication 88user ID/password authentication

configuringSalesforce 89

User Name connection option 181userIDPassword 56using

bulk API for batch inserts/selects 109identifiers 96SQL engine

UNIX/Linux 76Windows 73

UTF-16 269UTF-16 Applications 47UTF-8 269

Vvalidating bulk load files 104version string information 18views

caches not supported 196Create View statement 216creating 216Filter clause 202life span of data 200

WWeb Service tab 59What's new? 14Where clause 230Windows

configuring a data source 47Data Source Administrator 32data source configuration 32driver names 21error messages 121system requirements 20

Windows ODBC Administrator and tracing 114wire protocol adapter logger 119WorkAround options for ODBC drivers 295WSFetch Size connection option 181WSPoolSize connection option 182WSRetry Count connection option 183WSTimeout connection option 184


Index

user's guide and reference - progress.com...2020/06/08 · data source name.....151...

Documents