User's Guide and Reference - Progress.com€¦ · MongoDB Driver This is your user’s guide and reference for the Progress DataDirect® for ODBC for MongoDB™ driver. The content

Progress DataDirect®

for ODBCfor MongoDB™ DriverUser's Guide and Reference

Release 8.0.1

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/02/28

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

The Progress DataDirect® for ODBC for MongoDB Driver: User's Guide and Reference: Version 8.0.14

Copyright

Table of Contents

Preface..........................................................................................................11Welcome to the Progress DataDirect for ODBC for MongoDB Driver..................................................11

What's New in this Release?................................................................................................................12

Conventions Used in This Guide..........................................................................................................15

About the Product Documentation........................................................................................................17

Contacting Technical Support...............................................................................................................18

Getting Started.............................................................................................19Configuring and Connecting on Windows.............................................................................................20

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

Configuring a Data Source........................................................................................................20

Testing the Connection..............................................................................................................21

Configuring and Connecting on UNIX and Linux..................................................................................22

Environment Configuration........................................................................................................22

Test Loading the Driver..............................................................................................................23

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

Configuring a Data Source in the System Information File........................................................23

Testing the connection...............................................................................................................24

Accessing Data in Tableau ..................................................................................................................25

What Is ODBC?............................................................................................29How Does It Work?...............................................................................................................................30

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

About the MongoDB Driver.........................................................................31Driver Requirements.............................................................................................................................32

Support for Multiple Environments.......................................................................................................32

Support for Windows Environments...........................................................................................33

Support for UNIX and Linux Environments................................................................................34

Mapping Objects to Tables...................................................................................................................40

Normalizing Native Data............................................................................................................40

Mapping Nested Complex Types...............................................................................................41

Flattening Native Data...............................................................................................................48

ODBC Compliance...............................................................................................................................49

Version String Information....................................................................................................................49

getFileVersionString Function....................................................................................................50

Data Types............................................................................................................................................51


Contents

Default Mapping of Columns with Inconsistent Native Data Types............................................52

Retrieving Data Type Information...............................................................................................52

Isolation and Lock Levels Supported....................................................................................................53

Binding Parameter Markers..................................................................................................................54

Supported Features.....................................................................................55Unicode Support...................................................................................................................................55

Using IP Addresses..............................................................................................................................56

Parameter Metadata Support...............................................................................................................56

Insert and Update Statements...................................................................................................56

Select Statements......................................................................................................................57

SQL Support.........................................................................................................................................58

Number of Connections and Statements Supported............................................................................58

MongoDB Sharding Support................................................................................................................58

Using the Driver...........................................................................................59Configuring and Connecting to Data Sources......................................................................................59

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

Configuring the Product on Windows.........................................................................................69

Using a Connection String.........................................................................................................81

Using a Logon Dialog Box.........................................................................................................82

Creating and Customizing Schemas Using the DataDirect Schema Tool ...........................................83

Starting the Schema Tool...........................................................................................................83

Creating a Schema with the Table Wizard.................................................................................99

Customizing Your Schema.......................................................................................................106

Restarting the Wizard..............................................................................................................126

Performance Considerations..............................................................................................................127

Using Security....................................................................................................................................128

Data Encryption Across the Network.......................................................................................128

SSL Encryption........................................................................................................................128

Using Security with the Schema Tool.......................................................................................130

Summary of Security-Related Options....................................................................................130

Using Identifiers..................................................................................................................................132

Configuring the SQL Engine Server...................................................................................................134

Configuring Server Mode.........................................................................................................134

Starting the SQL Engine Server..............................................................................................136

Stopping the SQL Engine Server.............................................................................................137

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

Troubleshooting.........................................................................................139Diagnostic Tools..................................................................................................................................139

ODBC Trace.............................................................................................................................139

The Test Loading Tool..............................................................................................................142


Contents

ODBC Test...............................................................................................................................143

Logging....................................................................................................................................143

Configuring Logging.................................................................................................................145

The Example Application.........................................................................................................146

Other Tools...............................................................................................................................147

Error Messages..................................................................................................................................147

Troubleshooting..................................................................................................................................148

Setup/Connection Issues.........................................................................................................148

Interoperability Issues..............................................................................................................150

Performance Issues.................................................................................................................151

Out-of-Memory Issues.............................................................................................................151

Connection Option Descriptions..............................................................153Application Using Threads..................................................................................................................156

Config Options....................................................................................................................................157

columnDiscoverySampleSize (Config Option).........................................................................158

DefaultVarcharSize (Config Option).........................................................................................159

KeywordConflictSuffix (Config Option).....................................................................................161

LeadingUnderscoreReplacement (Config Option)...................................................................162

MaxVarcharSize (Config Option).............................................................................................163

MinVarcharSize (Config Option)..............................................................................................164

SchemaFilter (Config Option)..................................................................................................165

UppercaseIdentifiers (Config Option)......................................................................................167

Create Database................................................................................................................................168

Data Source Name.............................................................................................................................169

Database ...........................................................................................................................................169

Description..........................................................................................................................................170

Encryption Method.............................................................................................................................170

Fetch Size...........................................................................................................................................171

Host Name..........................................................................................................................................173

Host Name In Certificate....................................................................................................................173

IANAAppCodePage............................................................................................................................174

Initialization String..............................................................................................................................175

JVM Arguments..................................................................................................................................176

JVM Classpath...................................................................................................................................177

Key Password.....................................................................................................................................178

Key Store............................................................................................................................................179

Key Store Password............................................................................................................................180

Log Config File...................................................................................................................................180

Login Timeout.....................................................................................................................................181

Min Long Varchar Size........................................................................................................................182

Password............................................................................................................................................183

Port Number.......................................................................................................................................183

Read Only...........................................................................................................................................184


Contents

Read Preference ................................................................................................................................185

Report Codepage Conversion Errors.................................................................................................186

Result Memory Size...........................................................................................................................186

Schema Definition..............................................................................................................................188

Server Port Number............................................................................................................................189

SQL Engine Mode..............................................................................................................................190

Transaction Mode...............................................................................................................................191

Trust Store..........................................................................................................................................191

Trust Store Password..........................................................................................................................192

User Name.........................................................................................................................................193

Validate Server Certificate..................................................................................................................193

Varchar Threshold..............................................................................................................................195

Supported SQL Statements......................................................................197Delete.................................................................................................................................................197

Insert..................................................................................................................................................198

Refresh Map (EXT).............................................................................................................................199

Reload Map (EXT)..............................................................................................................................200

Select..................................................................................................................................................200

Select Clause...........................................................................................................................202

Update................................................................................................................................................212

SQL Expressions................................................................................................................................213

Column Names........................................................................................................................213

Literals.....................................................................................................................................213

Operators.................................................................................................................................216

Functions.................................................................................................................................219

Conditions................................................................................................................................219

Subqueries.........................................................................................................................................220

IN Predicate.............................................................................................................................221

EXISTS Predicate....................................................................................................................221

UNIQUE Predicate...................................................................................................................221

Correlated Subqueries.............................................................................................................222

Custom Function Escapes..................................................................................................................223

CAST_TO_NATIVE Function Escape......................................................................................223

Part I: Reference.........................................................................................225

Code Page Values...............................................................................227IANAAppCodePage Values......................................................................................................227

ODBC API and Scalar Functions......................................................233API Functions..........................................................................................................................233


Contents

Scalar Functions......................................................................................................................235

String Functions............................................................................................................237

Numeric Functions........................................................................................................239

Date and Time Functions..............................................................................................240

System Functions.........................................................................................................242

Internationalization, Localization, and Unicode..............................243Internationalization and Localization........................................................................................243

Locale...........................................................................................................................244

Language......................................................................................................................244

Country.........................................................................................................................244

Variant...........................................................................................................................245

Unicode Character Encoding...................................................................................................245

Background...................................................................................................................245

Unicode Support in Databases.....................................................................................246

Unicode Support in ODBC............................................................................................246

Unicode and Non-Unicode ODBC Drivers...............................................................................247

Function Calls...............................................................................................................247

Data..............................................................................................................................249

Default Unicode Mapping..............................................................................................250

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

References....................................................................................................................251

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

Designing ODBC Applications for Performance Optimization......253Using Catalog Functions..........................................................................................................254

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

Avoiding Search Patterns..............................................................................................255

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

Retrieving Data........................................................................................................................256

Retrieving Long Data....................................................................................................256

Reducing the Size of Data Retrieved............................................................................256

Using Bound Columns..................................................................................................257

Using SQLExtendedFetch Instead of SQLFetch...........................................................257

Choosing the Right Data Type......................................................................................258

Selecting ODBC Functions......................................................................................................258

Using SQLPrepare/SQLExecute and SQLExecDirect..................................................258

Using Arrays of Parameters..........................................................................................258

Using the Cursor Library...............................................................................................259

Managing Connections and Updates.......................................................................................260

Managing Connections.................................................................................................260

Managing Commits in Transactions..............................................................................260

Choosing the Right Transaction Model.........................................................................261


Contents

Using Positioned Updates and Deletes.........................................................................261

Using SQLSpecialColumns...........................................................................................261

Using Indexes.....................................................................................263Introduction..............................................................................................................................263

Improving Row Selection Performance....................................................................................264

Indexing Multiple Fields...........................................................................................................264

Deciding Which Indexes to Create...........................................................................................265

Improving Join Performance....................................................................................................266

Locking and Isolation Levels............................................................267Locking....................................................................................................................................267

Isolation Levels........................................................................................................................268

Locking Modes and Levels......................................................................................................269

WorkAround Options.........................................................................271

Threading............................................................................................275

Glossary.......................................................................................................277

Index............................................................................................................281


Contents

Preface

For details, see the following topics:

• Welcome to the Progress DataDirect for ODBC for MongoDB Driver

• What's New in this Release?

• Conventions Used in This Guide

• About the Product Documentation

• Contacting Technical Support

Welcome to the Progress DataDirect for ODBC forMongoDB Driver

This is your user’s guide and reference for the Progress DataDirect® for ODBC for MongoDB™ driver.

The content of this guide assumes that you are familiar with your operating system and its commands. Itcontains the following information:

• Getting Started on page 19 explains the basics for quickly configuring and testing the drivers.

• What Is ODBC? on page 29 provides an explanation of ODBC.

• About the MongoDB Driver on page 31 explains the driver, supported environments and driver requirements.

• Supported Features on page 55 explains features supported by the driver.

• Using the Driver on page 59 guides you through configuration of the drivers. It also explains how to use thefunctionality supported by the drivers, including security features, the SQL Engine Server, and the DataDirectSchema Tool.


• Troubleshooting on page 139 explains the tools to solve common problems and documents error messages.

• The Connection Option Descriptions on page 153 section contains detailed descriptions of the connectionoptions supported by the driver.

• Supported SQL Statements on page 197 provides supported SQL statements and extensions that are specificto the data source.

• The Reference on page 225 section includes reference information about APIs, code page values, andperformance tuning.

If you are writing programs to access ODBC drivers, you need to obtain a copy of the ODBC Programmer’sReference for the Microsoft Open Database Connectivity Software Development Kit, available from MicrosoftCorporation.

For the latest information about your driver, refer to the readme file in your software package.

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

What's New in this Release?

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

• Release Notes

• Supported Configurations

• DataDirect Support Matrices

Changes Since 8.0.1 GA

• Enhancements

• The new SchemaFilter config option allows you to specify the database and collections pairs for whichyou want the driver to fetch metadata. Using this option can provide can significantly improve connectiontimes by limiting the collections for which metadata is fetched to only those that are required by yourapplication. See SchemaFilter (Config Option) on page 165 for details.

• The driver and schema tool have been enhanced to allow you to limit sampling to only new collectionswhen refreshing the schema map. This provides for quicker processing times if you only want to mapnew collections or if existing collections are unchanged.You can specify the sampling behavior usingthe following methods:

• The Schema Tool: At connection, the Schema Tool prompts you to select the sampling behavior forthe session. See Starting the Schema Tool on UNIX/Linux on page 83 or Starting the Schema Toolon Windows on page 91 for details.

• The Refresh Map SQL extension: When executing the Refresh Map SQL extension, you can specifythe NEW options in the statement to limit sampling to only new collections. See Refresh Map (EXT)on page 199 for details.


Preface

https://www.progress.com/odbc/release-history/mongodb-odbc

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

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

• The driver has been enhanced to support the native Decimal128 data type, which maps to theSQL_DECIMAL ODBC type by default. See Data Types on page 51 for details.

• The CAST_TO_NATIVE function escape has been introduced to select or insert a value of a specificnative type. This can be particularly useful when MongoDB has inconsistent native types for a givenfield. Currently, CAST_TO_NATIVE can only be used with the ObjectID type in SELECT statement filtersand literal INSERT values. See Default Mapping of Columns with Inconsistent Native Data Types onpage 52 and CAST_TO_NATIVE Function Escape on page 223 for details.

• Changed Behavior

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

Note: For the latest updates, refer to the readme file installed with the product.

Changes For 8.0.1 GA

• Driver Enhancements

• The driver has been enhanced to resolve naming conflicts that can occur when exposing native objectsusing unquoted, uppercase identifiers (the default behavior). To avoid conflicts, the driver appends anunderscore separator and integer (for example, _1) to identifiers that differ only by case. See NamingConflicts on page 126 and Using Identifiers on page 132 for details.nullnullnullnull

• 1.5x.

In addition, you can further define the default length for VARCHAR columns by tuning the newMaxVarcharSize and MinVarcharSize config options. These options allow you to specify maximum andminimum size limits for the default length generated by the DefaultVarcharSize config option. Whentuned for your data, MaxVarcharSize and MinVarcharSize can improve memory efficiency and avoid theundesired truncation of VARCHAR values.

See DefaultVarcharSize (Config Option) on page 159, MaxVarcharSize (Config Option) on page 163 andMinVarcharSize (Config Option) on page 164 for details.

• The new KeywordConflictSuffix config option allows you to specify the suffix that is appended to objectand field names that conflict with SQL engine keywords. See KeywordConflictSuffix (Config Option) onpage 161 for details.

• The driver includes a new Tableau data source file (Windows only) that provides improved functionalitywhen accessing your MongoDB data with Tableau. See Accessing Data in Tableau on page 25 fordetails.

• The driver uses the MongoDB aggregation framework to improve performance in the execution of SQLqueries using LIMIT, ORDER BY, or TOP clauses.

• The following new SQL extensions have been added to the driver:

• Refresh Map: REFRESH MAP discovers native objects that have been added to the native datastore since connection or since the last refresh and maps the objects into your relational view of


Preface

native data. It also incorporates any configuration changes made to your relational view by reloadingthe schema definition and associated files. See Refresh Map (EXT) on page 199 for details.

• Reload Map: RELOAD MAP reloads the schema definition and associated files, allowing you toupdate your relational view of native data while the driver is connected to the data store. See ReloadMap (EXT) on page 200 for details.

• The driver has been enhanced to improve the handling of large result sets and reduce the likelihood ofout-of-memory errors through the configuration of the Fetch Size connection option and the introductionof the Result Memory Size connection option. See Fetch Size on page 171 and Result Memory Size onpage 186 for additional information.

• The driver has been enhanced to further ensure data integrity when mapping inconsistent data types toa relational schema. See Default Mapping of Columns with Inconsistent Native Data Types on page 52for details.

Changes for 8.0.0 GA

• Driver Enhancements

• When first connecting to a MongoDB server, the driver automatically creates a normalized schema ofthe data and generates a SchemaDefinition for housing and sharing the normalized schema. SeeNormalizing Native Data on page 40 and Schema Definition on page 188 multiplying the value specifiedby the size of the largest value for detected in that column. This results in a default length that isproportionate to the size of the data within the column, which can improve the memory efficiency withinthe driver and application. The default value for this option has been updated to

• Native MongoDB data is fully normalized during the normalization process, regardless of the depth ofnested arrays, documents, and objects. See Normalizing Native Data on page 40 and Generating aNormalized View on page 99 for details.

• The driver uses the MongoDB aggregation framework to improve performance in the execution of SQLqueries using aggregates, GROUP BY clauses, or HAVING clauses.

• 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.See SQL Engine Mode on page 190 for details.

• The new Min Long Varchar Size connection option allows you to fetch SQL_LONGVARCHAR columnswhose size is smaller than the minimum imposed by some third-party applications, such as SQL ServerLinked Server. See Min Long Varchar Size on page 182 for details.

• The new Varchar Threshold connection option allows you to fetch columns that would otherwise exceedthe upper limit of the SQL_VARCHAR type for some third-party applications, such as SQL Server LinkedServer. See Varchar Threshold on page 195 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 252 for details.

• Schema Tool Enhancements

• The new Restart Wizard feature allows you to reset the relational view of your data from the Table Wizardmenu. See Restarting the Wizard on page 126 for details.

• The new Update Schema feature allows you to map all new native objects to your schema definitionwith a single click. See Mapping Newly Detected Objects on page 117 for details.

• Support for selecting multiple objects in the Table Wizard for improved object management whencustomizing your schema.

• Changed Behavior


Preface

The driver no longer supports in-memory tables (also referred to as "local tables").•

• The driver’s SQL engine was upgraded for this release. Consequently, there are differences in how thedriver handles some SQL queries. Visit the Progress DataDirect SQL Engine Upgrade Web page pagefor more information.

• The Normalization Depth option is no longer available in the Schema Tool because native MongoDBdata is now fully normalized, regardless of depth, during the normalization process. See NormalizingNative Data on page 40 for details.

• The 8.0.x version of the driver and Schema Tool does not support schema definitions created withprevious versions of the product. Therefore, you should reproduce your 7.1.x schema definitions withthe current release of the driver or Schema Tool.

• The 8.0 driver pushes down SQL queries to MongoDB whenever possible. Queries that cannot be pusheddown to MongoDB in the 8.0 driver may be slower than comparable queries made with previous versionsof the driver because data may be paged to disk while completing an operation. If you experience slowperformance, please contact Technical Support: https://www.progress.com/support-and-services. Ourteam will quickly address any performance issues you may encounter.

• The default value for the SQL Engine Mode connection option has been updated:

• For Windows users, the default is 0 (Auto).

• For UNIX/Linux users, the default is 2 (Direct).

See SQL Engine Mode on page 190 for details.

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

For the 32-bit driver, the default is 19932.

For the 64-bit driver, the default is 19931.

• The default value for the Schema Definition connection option has been updated:

For Windows users, the default is:

application_data_folder\Local\Progress\DataDirect\MongoDBSchema\host_name.config

For UNIX/Linux users, the default is:

~/progress/datadirect/mongodb_schema/host_name.config

See Schema Definition on page 188 for details.

Conventions Used in This GuideThe following sections describe the conventions used to highlight information that applies to specific operatingsystems and typographical conventions.

Operating System SymbolsThe drivers are supported in the Windows, UNIX, and Linux environments. When the information provided isnot applicable to all supported environments, the following symbols are used to identify that information:

The Windows symbol signifies text that is applicable only to Windows.


Preface

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

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

The UNIX symbol signifies text that is applicable only to UNIX and Linux.

TypographyThis guide uses the following typographical conventions:

ExplanationConvention

Introduces new terms with which you may not be familiar, and is used occasionallyfor emphasis.

italics

Emphasizes important information. Also indicates button, menu, and icon names onwhich you can act. For example, click Next.

bold

Indicates keys or key combinations that you can use. For example, press the ENTERkey.

BOLD UPPERCASE

Indicates SQL reserved words.UPPERCASE

Indicates syntax examples, values that you specify, or results that you receive.monospace

Indicates names that are placeholders for values that you specify. For example,filename.

monospaceditalics

Separates menus and their associated commands. For example, Select File > Copymeans that you should select Copy from the File menu.

>

The slash also separates directory levels when specifying locations under UNIX./

Indicates an "OR" separator used to delineate items.vertical rule |

Indicates optional items. For example, in the following statement: SELECT[DISTINCT], DISTINCT is an optional keyword.

Also indicates sections of the Windows Registry.

brackets [ ]

Indicates that you must select one item. For example, {yes | no} means that you mustspecify either yes or no.

braces { }

Indicates that the immediately preceding item can be repeated any number of timesin succession. An ellipsis following a closing bracket indicates that all information inthat unit can be repeated.

ellipsis . . .


Preface

About the Product DocumentationThis guide provides specific information about your Progress DataDirect for ODBC driver.You can view thisdocumentation in the HTML format installed with the product. The documentation is also available in PDFformat .You can download the PDF version of the documentation at:

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

This guide is installed with the product as an HTML-based help system.This help system is located in the helpsubdirectory of the product installation directory.You can use the help system with any of the following browsers:

• Microsoft Edge on Windows 10

• Internet Explorer 7.x and higher

• Firefox 3.x and higher

• Safari 5.x

• Google Chrome 44.x and earlier

On all platforms, you can access the entire Help system by opening the following file from within your browser:

install_dir/help/MongoDBHelp/index.html

where install_dir is the path to the product installation directory.

Or, from a command-line environment, at a command prompt, enter:

browser_exe install_dir/help/MongoDBHelp/index.html

where browser_exe is the name of your browser executable and install_dir is the path to the productinstallation directory.

After the browser opens, the left pane displays the Table of Contents, Index, and Search tabs for the entiredocumentation library. When you have opened the main screen of the Help system in your browser, you canbookmark it in the browser for quick access later.

Note: Security features set in your browser can prevent the Help system from launching. A security warningmessage is displayed. Often, the warning message provides instructions for unblocking the Help system forthe current session. To allow the Help system to launch without encountering a security warning message, thesecurity settings in your browser can be modified. Check with your system administrator before disabling anysecurity features.

Help is also available from the setup dialog box for each driver. When you click Help, your browser opens tothe correct topic without opening the help Table of Contents. A grey toolbar appears at the top of the browserwindow.

This tool bar contains previous and next navigation buttons. If, after viewing the help topic, you want to seethe entire library, click:


Preface

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

on the left side of the toolbar, which opens the left pane and displays the Table of Contents, Index, and Searchtabs.

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

https://www.progress.com/support

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

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

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

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

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

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

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

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

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

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

March 2020, 8.0.1 Release of the Progress DataDirect for ODBC for MongoDB Driver, Version 0001


Preface

https://www.progress.com/support

1Getting 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 "About the MongoDB Driver" and "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 in Tableau


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.

Data Source Name: Type a string that identifies this data source configuration, such as Accounting.

Host Name: Type the URL of the interface to which you want to connect.

Port Number: Type the port number of the server listener. The default is 27017.

Database: Type the name of the database to which you want to connect. The default isINFORMATION_SCHEMA.


Chapter 1: Getting Started

Important: This value is case-insensitive if you have access privileges to query the list of databases onthe server. If you do not have access, it is case-sensitive.

Schema Definition: Type the name and location of the configuration file where the relational map of nativedata is written.The driver either creates or looks for this file when connecting to the database. For example,C:\Users\Default\AppData\Local\Progress\DataDirect\MongoDBSchema\MainServer.config.

The default value is:

application_data_folder\Local\Progress\DataDirect\MongoDB Schema\host_name.config

where:

application_data_folder

is the application data folder for your platform and data source type.

host_name

is the value specified for the Host Name connection option.

See Schema Definition on page 188 "Schema Definition" for details.

3. To take full advantage of the driver's features, click Schema Tool to customize your schema definition usingthe Schema Tool.You can also customize your schema definition later if the need arises. See "Creatingand Customizing Schemas Using the DataDirect Schema Tool" for information about using the SchemaTool.

See alsoSchema Definition on page 188Creating and Customizing Schemas Using the DataDirect Schema Tool on page 83

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.


Configuring and Connecting on Windows

See alsoUsing a Logon Dialog Box on page 82Using a Connection String on page 81

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 59

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 Solaris, where xx represents the version number of the driver:

ivtestlib /opt/odbc/lib/ivmongoxx.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 driver for MongoDB, you must set the library path environment variable for yourUNIX/Linux operating system to include the directory containing your JVM’s libjvm.so [sl | a] file, and thatdirectory’s parent directory.

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 [sl | a]file, and that directory’s parent directory.

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

• SHLIB_PATH on HP PA-RISC

• 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 [sl | 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 in the System Information File

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.


Configuring and Connecting on UNIX and Linux

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.

To take advantage of the driver's features, we recommended that you launch the DataDirect Schema Tool;although, it is not required to test the connection. For additional information on the DataDirect Schema Tool,see "Creating and Customizing Schemas Using the DataDirect Schema Tool."

[ODBC Data Sources]MongoDB=DataDirect 8.0 MongoDB Driver

[MongoDB]Driver=ODBCHOME/lib/xxmongo28.yyDatabase=mongodb2HostName=MongodbServerPortNumber=27017SchemaDefinition=~/progress/datadirect/mongodb_schema/MongodbServer.config

Connection Option Descriptions:

Database: The name of the database to which you want to connect by default. The default isINFORMATION_SCHEMA.

Important: This value is case-insensitive if you have access privileges to query the list of databases on theserver. If you do not have access, it is case-sensitive.

HostName: Either the name or the IP address of the server to which you want to connect.

PortNumber: The port number of the server listener. The default is 27017.

SchemaDefinition: The name and location of the configuration file where the relational map of native datais written. The driver either creates or looks for this file when connecting to the database. The default is:

~/progress/datadirect/mongodb_schema/hostname.config

where:

hostname

is the value specified for the HostName connection option.

See "Schema Definition" for details.

See alsoCreating and Customizing Schemas Using the DataDirect Schema Tool on page 83Schema Definition on page 188

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 in TableauAfter you have configured your data source, you can use the driver to access your MongoDB data with Tableau.Tableau is a business intelligence software program that allows you to easily create reports and visualizedrepresentations of your data. By using the driver with Tableau, you can improve performance when retrievingdata while leveraging the driver's relational mapping tools.

To use the driver to access data with Tableau:

1. Navigate to the \tools\Tableau subdirectory of the Progress DataDirect installation directory; then,locate the Tableau data source file, DataDirect MongoDB.tdc.

2. Copy the DataDirect MongoDB.tdc into the following directory:

C:\Users\user_name\Documents\My Tableau Repository\Datasources

3. Open Tableau. If the Connect menu does not open by default, select Data > New Data Source or the Add

New Data Source button to open the menu.

4. From the Connect menu, select Other Databases (ODBC).

5. The Server Connection dialog appears.


Accessing Data in Tableau

In the DSN field, select the data source you want to use from the drop down menu. For example, MyMongoDB DSN. Then, click Connect. The Logon to MongoDB dialog appears pre-populated with theconnection information you provided in your data source.

6. If required, type your user name and password; then, click OK. The Logon dialog closes. Then, click OKon the Server Connection dialog.

7. The Data Source window appears.



By default, Tableau connects live, or directly, to your data. We recommend that you use the default settingsto avoid extracting all of your data. However, if you prefer, you can import your data by selecting the Extractoption at the top of the dialog.

8. In the Schema field, select the database you want to use. The tables stored in this database are nowavailable for selection in the Table field.

You have successfully accessed your data and are now ready to create reports with Tableau. For moreinformation, refer to the Tableau product documentation at: http://www.tableau.com/support/help.


Accessing Data in Tableau

http://www.tableau.com/support/help



2What 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 2: What Is ODBC?

3About the MongoDB Driver

The Progress DataDirect for ODBC for MongoDB driver supports SQL to select data from MongoDB databasesand some insert, update, and delete capabilities. The driver supports MongoDB version 2.2 and higher.

The driver translates the SQL statements provided by an application into native queries, enabling you to leverageyour knowledge of SQL. Additionally, the driver creates a relational schema of your native MongoDB data tosupport SQL access to MongoDB's flexible schema data model. The relational schema created by the driveris written to a configuration file that can be shared among client machines accessing a common data store.The configuration file can be modified subsequently using the DataDirect Schema Tool.

The DataDirect Schema Tool is included with the driver. The Schema Tool enables you to customize andperfect the relational schema used to access your MongoDB data. The Schema Tool provides metadata,statistics, and a hierarchical view of your data, as it guides you through the mapping process.You can use theSchema Tool's Table Wizard to expose tabular relationships among your MongoDB data collections. Usingthe Schema Tool, you can create new relational views of your data with options to flatten, normalize, or customizeyour MongoDB data. In turn, the Schema Tool allows you to define data types consistently within columns, acritical step in ensuring data integrity.

Once you have an established relational schema, the relationships among objects can be reported throughthe following metadata methods: SQLColumns, SQLForeignKeys, SQLGetTypeInfo, SQLPrimaryKeys,SQLSpecialColumns, SQLStatistics, and SQLTables. Furthermore, when performing joins, the driver leveragesdata relationships in MongoDB collections, minimizing the amount of data that needs to be fetched over thenetwork.

The driver can be used with industry standard tools, including:

QlikViewCognos

SAP Crystal ReportsMicrosoft Access

SAS/Access for ODBCMicrosoft Excel


SQL Server Linked ServerOracle Business Intelligence (OBIEE)

TableauOracle Gateway


• Driver Requirements

• Support for Multiple Environments

• Mapping Objects to Tables

• ODBC Compliance

• Version String Information

• Data Types

• Isolation and Lock Levels Supported

• Binding Parameter Markers

Driver RequirementsThe driver requires one of the following Java Virtual Machines (JVM):

• Oracle JDK 8 or higher (LTS version)

• OpenJDK 8 or higher (LTS version)

• IBM SDK (Java) 7 or higher (LTS version)

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.

See alsoSupport for Windows Environments on page 33Support for UNIX and Linux Environments on page 34


Chapter 3: About the MongoDB Driver

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

Threading on page 275

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 whichyou are 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.

• An application that is compatible with components that were built using Microsoft Visual Studio 2010 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 33

64-Bit Driver



• Intel


Support for Multiple Environments

• 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 32-bit JVM’s jvm.dll file, and that directory’s parent directory.

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

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 19Configuring and Connecting to Data Sources on page 59

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 MongoDB driver file name isivmongonn.dll, where nn is the revision number of the driver.

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

ivmongo28.dll


ddmongo28.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 Requirements


• 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 driver for MongoDB: A 32-bit Java Virtual Machine (JVM), Java SE 8 or higher, is required. Also,you must set the library path environment variable of your operating system to the directory containing yourJVM’s libjvm.so [sl | a] file and that directory’s parent directory.

The library path environment variable is:

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

• SHLIB_PATH on HP-UX PA-RISC

• LIBPATH on AIX

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 6 installed in the /usrdirectory:

:/usr/java6/jre/lib/ppc/classic:/usr/java6/jre/lib/ppc

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

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

HP-UX


• PA-RISC

• Intel Itanium II (IPF)

• The following operating systems are supported:

• For PA-RISC: HP-UX 11i Versions 2 and 3 (B.11.23 and B.11.3x)

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

• For PA-RISC: An application compatible with components that were built using HP aC++ 3.60 and theHP-UX 11 native (kernel) threading model (posix draft 10 threads).



All of the standard 32-bit UNIX drivers are supported on HP PA-RISC.

• For IPF: An application compatible with components that were built using HP aC++ 5.36 and the HP-UX11 native (kernel) threading model (posix draft 10 threads)

Note: For PA-RISC users: Set the LD_PRELOAD environment variable to the libjvm.sl from your JVMinstallation.

Note: For Itanium users:

• 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



• 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, 11, and 12

• 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


• Oracle SPARC

• x86: Intel



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

• For x86/x64: Oracle Solaris 10, Oracle Solaris 11.x

• 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 x86/x64: An application compatible with components that were built using Sun C++ 5.8 and the Solarisnative (kernel) threading model



See also64-Bit Driver Requirements on page 37

64-Bit Driver RequirementsAll 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 [sl | a]file and that directory’s parent directory.

• The library path environment variable is:

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

• LIBPATH on AIX

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 6 installed in the /usrdirectory:

:/usr/java6_64/jre/lib/ppc64/classic:/usr/java6_64/jre/lib/ppc64

In this example, /usr/java6_64/jre/lib/ppc64/classic is the location of libjvm.so, while/usr/java6_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, 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, 11, and 12

• Ubuntu Linux 14.04, 16.04

• 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



• 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

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.



http://www.hp.com

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

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 Connecting to Data Sources on page 59 provides details about driver configuration.

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

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 ivmongonn.so, where nn is the revision number of the driver. For the driver on HP-UXPA-RISC only, the extension is .sl, for example, ivmongonn.sl.


ivmongo28.so


ddmongo28.so

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



Mapping Objects to TablesData mapping describes how elements are mapped between two distinct data models.To support SQL accessto a MongoDB database, the MongoDB database must be mapped to a relational schema. Native MongoDBdata can be either normalized or flattened to create a relational schema.

Normalization takes place upon initial connection with the driver or when establishing a new schema definitionusing the Schema Tool. During the normalization process, MongoDB collections are normalized into sets ofparent-child tables. The child tables correspond to complex types, such as arrays and embedded documents(or subdocuments), and have a foreign key relationship to the parent table.

Flattening can only take place by establishing a schema definition using the Schema Tool. When flatteningdata with the Schema Tool, MongoDB collections are flattened into single, relational tables. All fields, includingthose that may comprise complex types, are organized as columns within the relational table.

Whether you normalize or flatten your native data, the relational schema is written to the schema definitionconfiguration file. This configuration file is an XML file that may be shared across servers. The configurationfile can be subsequently modified using the Schema Tool.

See alsoSchema Definition on page 188Creating and Customizing Schemas Using the DataDirect Schema Tool on page 83

Normalizing Native Data

When you first connect to a MongoDB server, the driver automatically generates a normalized view of yourdata.You can also use the Schema Tool to normalize your native MongoDB data. When your native data isnormalized, each MongoDB collection is decompounded into a set of parent-child tables. Fields containingsimple types are mapped as columns in a parent table, while complex types, such as subdocuments and arrays,are mapped as child tables. Child tables share a foreign key relationship with their parent table.

Note: Child tables are only extracted from arrays if all the sampled rows in the column have the native Arraydata type. See "Config Options" for information on setting the sample size.

For example, the collection residents contains the array vehicles and subdocuments in the addressdocument (or object). The collection's JSON structure can be rendered as follows:

{"_id": "ajx363", "name": "Sydney Smith", "address": {"street": "101 Main Street", "city": "Raleigh", "state": "NC"}, "county": "Wake", "vehicles: ["car", "boat", "bicycle"]}

{"_id": "tzn525", "name": "Cora Welch", "address": {"street": "191 First Street", "city": "Chapel Hill", "state": "NC"}, "county": "Orange", "vehicles": ["scooter", "truck", "bicycle"]}

The collection has been decompounded into separate but related tables.The normalization of the residentscollection yields one parent table and two child tables. In the parent table, the _id field is mapped as a primarykey column, and fields with other simple types are mapped as relational columns. The parent table adopts thename RESIDENTS and takes the following form:



COUNTYNAME_ID (PK)

WakeSydney Smithajx363

OrangeCora Welchtzn525

The information in the vehicles array maps to a RESIDENTS_VEHICLES child table. In this table, a columnwhich refers back to the parent table is mapped as a concatenation of the parent table and the _id field:RESIDENTS_ID. (This column establishes a foreign key relationship to the parent table based on the _idfield.) The vehicles array is mapped to the column VEHICLES. Each value in the VEHICLES columncorresponds to an element in the vehicles array. In addition, the driver generates a third column to establisha primary key for the child table: VEHICLES_GENERATED_ID. (This automatically generated column enablesthe driver to normalize nested arrays to any depth. The format of the unique keys are internal to the driver.)This child table would take the following form:

VEHICLES_GENERATED_ID (PK)VEHICLESRESIDENTS_ID (FK)

unique keycarajx363

unique keyboatajx363

unique keybicycleajx363

unique keybicycletzn525

unique keyscootertzn525

unique keytrucktzn525

The information in the address object maps to a RESIDENTS_ADDRESS child table. In this table, a columnwhich refers back to the parent table is mapped as a concatenation of the parent name and the _id field:RESIDENTS_ID. (This column establishes a foreign key relationship to the parent table and functions as aprimary key within the child table.) Each subdocument found in the address object is mapped as a column.This table would take the following form:

STATECITYSTREETRESIDENTS_ID (PK &FK)

NCRaleigh101 Main Streetajx363

NCChapel Hill191 First Streettzn525

See alsoConfig Options on page 157

Mapping Nested Complex Types

The following examples illustrate several ways the normalization of complex types are handled.


Mapping Objects to Tables

A Subdocument Nested in a SubdocumentIn this example, the subdocument location contains the subdocuments city and state in the employeecollection:

{"_id": pdn313, "name": "Charlotte", "manager": {"name": "Robert", "department": "Development", "location": {"city": "Tulsa", "state": "OK"}}}

{"_id": gkx136, "name": "Benjamin", "manager": {"name": "Michael", "department": "Quality Assurance", "location": {"city": "Dallas", "state": "TX"}}}

First, the EMPLOYEE parent table would be derived from the simple types _id and name as follows:

NAME_ID

Charlottepdn313

Benjamingkx136

Second, the EMPLOYEE_MANAGER child table would be derived from the manager object. The id_ field ismapped as EMPLOYEE_ID. (This column establishes a foreign key relationship to the parent table and functionsas a primary key within the child table.) In turn, the name and department subdocuments are mapped ascolumns. The resulting table would take the following form:

DEPARTMENTNAMEEMPLOYEE_ID (PK & FK)

DevelopmentRobertpdn313

Quality AssuranceMichaelgkx136

Third, an EMPLOYEE_MANAGER_LOCATION child table would be derived from the location object. The id_field is mapped as EMPLOYEE_MANAGER_ID. (As in the previous table, this column establishes a foreign keyrelationship to the parent table and functions as a primary key within the child table.) The city and statesubdocuments, which indicate the location of an employee's manager, are mapped as CITY and STATEcolumns. The resulting table would take the following form:

STATECITYEMPLOYEE_MANAGER_ID (PK& FK)

OKTulsapdn313

TXDallasgkx136



Subdocuments Nested in an ArrayIn the collection employee, the addresses array contains the subdocuments: label, street, city, andstate.

{"_id": ajx456, "name": "Andrea", "addresses": [ {"label": "Home", "street": "101 Main St", "city": "Raleigh", "state": "NC"}, {"label": "Work", "street": "303 Main St", "city": "Morrisville","state": "NC"} ]}

First, the EMPLOYEE parent table is derived from the simple types _id and name as follows:

NAME_ID

Andreaajx456

Second, the EMPLOYEE_ADDRESSES child table would be derived from the addresses array. In this scenario,the id_ field is mapped as EMPLOYEE_ID and retains a foreign key column relationship to the parent table.Next, each of the subdocuments in the array are mapped as columns. The driver also generates an additionalcolumn to establish a primary key for the child table:ADDRESSES_GENERATED_ID.This automatically generatedcolumn enables the driver to normalize nested arrays to any depth. The unique keys are internal to the driver.The resulting table takes the following form:

ADDRESSES_

GENERATED_ID

(PK)

STATECITYSTREETLABELEMPLOYEE_ID(FK)

unique keyNCRaleigh101 Main StHomeajx456

unique keyNCMorrisville303 Main StWorkajx456

An Array Nested in a DocumentIn a separate scenario, the manager document contains the emails array in the employee collection. Thecollection has the following JSON structure:

{"_id": ajp211, "name": "Mark", "manager": {"name": "Cynthia", "emails": ["[email protected]", "[email protected]"]}}{"_id": mpc393, "name": "Deborah", "manager": {"name": "Cynthia", "emails": ["[email protected]", "[email protected]"]}}{"_id": dlm215, "name": "Jason", "manager": {"name": "Chris", "emails": ["[email protected]", "[email protected]"]}}

Again, the EMPLOYEE parent table would be derived from the simple types _id and name as follows:



NAME_ID

Markajp211

Deborahmpc393

Jasondlm215

Next, the EMPLOYEE_MANAGER child table would be derived from the manager object. As in previous examples,the id_ field is mapped as EMPLOYEE_ID and retains a foreign key relationship to the parent table. In turn,the nested name subdocument (the name of the manager) is mapped as a column. Next, the emails array ismapped to the column EMAILS. Each value in the EMAILS column corresponds to an element in the emailsarray. The driver also generates an additional column to establish a primary key for the child table:MANAGER_GENERATED_ID. Note that the names and emails in the following this child table are those of themanagers but are linked to the employee identification number.

MANAGER_

GENERATED_ID

(PK)

EMAILSNAMEEMPLOYEE_ID (FK)

unique [email protected]






An Array Nested in an ArrayIn the collection offices, the departments array contains an employees array.

{"_id": au32, "city": "Bedford", "departments": [{"name": "Development", "employees": [ {"first": "Leslie", "last": "Jacobs"}, {"first": "Emma", "last": "Alves"}, {"first": "Brad", "last": "Jones"} ] }, {"name": "Human Resources", "employees": [ {"first": "Joseph", "last": "Lu"}, {"first": "Margaret", "last": "Baker"}, {"first": "Chetna", "last": "Campbell"} ] }, {"name": "IT", "employees": [ {"first": "Caroline", "last": "Evans"},



{"first": "Markus", "last": "Campanella"}, {"first": "Jennifer", "last": "Bradley"} ] }] },{"_id": xn44, "city": "Morrisville", "departments": [{"name": "Development", "employees": [ {"first": "Charles", "last": "Scott"}, {"first": "Mary", "last": "Gonzales"}, {"first": "Phil", "last": "McEnroe"} ] }, {"name": "Operations", "employees": [ {"first": "Rachel", "last": "Cullingford"}, {"first": "Lance", "last": "Friedman"}, {"first": "Amanda", "last": "Giachetti"} ] }, {"name": "IT", "employees": [ {"first": "Ingrid", "last": "Burkis"}, {"first": "Catherine", "last": "Wheeler"}, {"first": "Jacob", "last": "Williams"} ] }]}

First, an OFFICES parent table is derived from the _id and city simple types. The _id field is mapped asthe primary key column _ID, and the city field is mapped as the relational column CITY.

CITY_ID (PK)

Bedfordau32

Morrisvillexn44

Next, an OFFICES_DEPARTMENTS child table is derived from the departments array. The OFFICES_IDcolumn is generated to establish a foreign key relationship to the parent table based on the _id field. Thedepartments array is mapped to the column DEPARTMENTS. Each value in the DEPARTMENTS columncorresponds to an element in the departments array.The DEPARTMENTS_GENERATED_ID column is generatedto establish a primary key for the child table. (The unique keys are internal to the driver.)

DEPARTMENTS_GENERATED_ID(PK)

DEPARTMENTSOFFICES_ID (FK)

unique keyDevelopmentau32

unique keyHuman Resourcesau32

unique keyITau32

unique keyDevelopmentxn44

unique keyOperationsxn44

unique keyITxn44



The employees array nested in the departments array is mapped as anOFFICES_DEPARTMENTS_EMPLOYEES child table. (This table is the child of the OFFICES_DEPARTMENTStable and the grandchild of the OFFICES table.) The OFFICES_DEPARTMENTS_ID column establishes a foreignkey relationship to the parent array based on the automatically generated primary key from theOFFICES_DEPARTMENTS table. The FIRST and LAST columns are derived from the the first and lastfields contained in each employees array.The EMPLOYEES_GENERATED_ID column is generated to establisha primary key for the child table.



EMPLOYEES_

GENERATED_ID

(PK)

LASTFIRSTOFFICES_

DEPARTMENTS_ID

(FK)

unique keyJacobsLeslieauto-generated key fromthe parent array

unique keyAlvesEmmaauto-generated key fromthe parent array (arrayparent)

unique keyJonesBradauto-generated key fromthe parent array

unique keyLuJosephauto-generated key fromthe parent array

unique keyBakerMargaretauto-generated key fromthe parent array

unique keyCampbellChetnaauto-generated key fromthe parent array

unique keyEvansCarolineauto-generated key fromthe parent array

unique keyCampanellaMarkusauto-generated key fromthe parent array

unique keyBradleyJenniferauto-generated key fromthe parent array

unique keyScottCharlesauto-generated key fromthe parent array

unique keyGonzalesMaryauto-generated key fromthe parent array

unique keyMcEnroePhilauto-generated key fromthe parent array

unique keyCullingfordRachelauto-generated key fromthe parent array

unique keyFriedmanLanceauto-generated key fromthe parent array

unique keyGiachettiAmandaauto-generated key fromthe parent array



EMPLOYEES_

GENERATED_ID

(PK)

LASTFIRSTOFFICES_

DEPARTMENTS_ID

(FK)

unique keyBurkisIngridauto-generated key fromthe parent array

unique keyWheelerCatherineauto-generated key fromthe parent array

unique keyWilliamsJacobauto-generated key fromthe parent array

Flattening Native Data

You can use the Schema Tool to flatten MongoDB collections into relational tables. The following exampleshows how the source data is flattened.

A data source has a collection called employee with the following structure:

{"_id": pdn313, "name": "Charlotte", "manager": {"name": "Robert", "emails": ["[email protected]", "[email protected]"] }}

The employee collection would be flattened into a relational table with the following structure:

MANAGER_EMAILS_1MANAGER_EMAILS_0MANAGER_NAMENAME_ID

[email protected]@email.comRobertCharlottepdn313

All fields are retained as separate columns in the resulting relational table. Simple types such as _id and namecorrespond directly to columns. In turn, subdocuments are flattened into columns using the<objectname>_<fieldname> pattern. Next, the emails array is flattened into two columns, using anextended version of the <arrayname>_<arrayindex> pattern:<objectname>_<arrayname>_<arrayindex>.

Note: As subdocuments or arrays are discovered at deeper and deeper levels, the<objectname>_<fieldname> or <arrayname>_<arrayindex> pattern is extended, for example,<objectname>_<objectname>_<fieldname>.



ODBC ComplianceThe Progress DataDirect for ODBC for MongoDB driver is compliant with the Open Database Connectivity (ODBC)3.52 specification. The driver is ODBC core compliant with the exception of transaction support. In addition,the driver supports some Level 1 and Level 2 features. See "ODBC API and Scalar Functions" for a list of theCore, Level 1, and Level 2 functions supported by the driver.

The driver supports only the following Level 2 functions:

• SQLColumnPrivileges

• SQLDescribeParam

• SQLForeignKeys

• SQLPrimaryKeys

• SQLProcedures

• SQLTablePrivileges

See alsoODBC API and Scalar Functions on page 233

Version String InformationThe driver for MongoDB 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.01.0017 (B0254, U0180, J000109) |__| |___| |___| |____| Driver Bas Utl Java


ODBC Compliance

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 Oracle Solaris:

ivtestlib ivmongo28.so

returns:

08.01.0001 (B0002, U0001, J000003)

For example, for the Driver Manager on Solaris:

ivtestlib libodbc.so

returns:

08.01.0001 (U0001)

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

ddtestlib libodbc.so

returns:

08.01.0001 (U0001)

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

ivtestlib libivicu28.so08.01.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.

Data TypesThe following table lists the MongoDB data types and their default mapping for ODBC. Default mappings canbe overridden using the Schema Tool. See "Defining Columns" for additional information.

Table 1: Default Mapping for MongoDB Data Types

ODBC Data TypeMongoDB Data Type

SQL_WLONGVARCHAR (-10)Array1

SQL_BIGINT (-5)Bigint

SQL_VARBINARY (-3)BinData

SQL_BIT (-7)Boolean

SQL_TIMESTAMP (93)Date

SQL_DECIMAL (3)Decimal1282

SQL_DOUBLE (8)Double

SQL_INTEGER (4)Integer

SQL_WLONGVARCHAR (-10)Object1

SQL_WVARCHAR (-9)ObjectID3

SQL_WVARCHAR (-9)4, 5, 6String

1 Complex data types can be returned as strings in the JSON format, or can be normalized such that nested elements are returnedas columns in a new logical table.

2 The driver reports a precision of 68 characters for this type; however, the native type limits the maximum number of digits beforeor after the decimal to 34 digits.

3 The CAST_TO_NATIVE function escape may be needed to select or insert a value of the ObjectID type when MongoDB hasinconsistent native types for a given field. See "Default Mapping of Columns with Inconsistent Native Data Types" and"CAST_TO_NATIVE Function Escape" for details..

4 When the driver discovers a String column with a value that is less than or equal to 4000 characters, the column is mapped asWVARCHAR and the precision is 4000 characters.When a String column with a value greater than 4000 characters is discovered,the column is mapped as WLONGVARCHAR and precision is 16 MB.

5 During the initial discovery and normalization process, you can use the DefaultVarcharSize configuration option to specify thedefault length of fields that are discovered and mapped as WVarchar by the driver. If the driver discovers a field with String dataof a greater length, the String data is truncated to the length of the specified value. See "DefaultVarcharSize (Config Option)"for details.

6 You can map String to CHAR, VARCHAR, or LONGVARCHAR, regardless of the column size, using the Schema Tool. See"Creating and Customizing Schemas Using the DataDirect Schema Tool" and "Defining Columns" for details.


Data Types

See alsoDefining Columns on page 123CAST_TO_NATIVE Function Escape on page 223DefaultVarcharSize (Config Option) on page 159Creating and Customizing Schemas Using the DataDirect Schema Tool on page 83

Default Mapping of Columns with Inconsistent Native Data Types

Due to the flexibility of the MongoDB schema data model, your native data sources may not enforce consistentdata types. To ensure data integrity when mapping to a relational model, the driver describes columns withinconsistent native data types as a single SQL data type. The driver determines which SQL type to use basedon the combination of native types detected when sampling data. The following table lists combinations ofMongoDB data types and their default mapping for ODBC. If you need to change the ODBC data type, defaultmappings can be overridden using the Schema Tool. See "Defining Columns" for additional information.

Note: In some cases, a value with a specific native type can be concealed or obscured because the driverdescribes a field with inconsistent native types as a column with a single SQL type. The CAST_TO_NATIVEfunction escape allows users to send a value as it is defined in the MongoDB database, rather than how it isdescribed in the relational model of the data. Currently, CAST_TO_NATIVE can only be used with the ObjectIDtype in SELECT statement filters and literal INSERT values. See "CAST_TO_NATIVE Function Escape" fordetails.

Table 2: Default Mapping for Columns Containing Inconsistent MongoDB Data Types

ODBC Data TypeMongoDB Data Types

SQL_BIGINT (-5)Bigint and Integer

SQL_DOUBLE (8)Double and Integer

SQL_WVARCHAR (-9) or WLONGVARCHAR (-10)7All other combinations

See alsoDefining Columns on page 123CAST_TO_NATIVE Function Escape on page 223Config Options on page 157

Retrieving Data Type Information

At times, you might need to get information about the data types that are supported by the data source, forexample, precision and scale.You can use the ODBC function SQLGetTypeInfo to do this.

On Windows, you can use ODBC Test to call SQLGetTypeInfo against the ODBC data source to return thedata type information. See "Diagnostic Tools" for details about ODBC Test.

7 Whether columns are mapped as either WVARCHAR (-9) or WLONGVARCHAR (-10) depends on the size of the data of thesampled rows and the setting of the defaultVarcharSize configuration option. See "Config Options" for details.



On UNIX, Linux, or Windows, an application can call SQLGetTypeInfo. Here is an example of a C function thatcalls SQLGetTypeInfo and retrieves the information in the form of a SQL result set.

void ODBC_GetTypeInfo(SQLHANDLE hstmt, SQLSMALLINT dataType){ RETCODE rc;

// There are 19 columns returned by SQLGetTypeInfo. // This example displays the first 3.// Check the ODBC 3.x specification for more information.// Variables to hold the data from each column char typeName[30]; short sqlDataType; unsigned long columnSize;

SQLINTEGER strlenTypeName, strlenSqlDataType, strlenColumnSize;

rc = SQLGetTypeInfo(hstmt, dataType); if (rc == SQL_SUCCESS) {

// Bind the columns returned by the SQLGetTypeInfo result set. rc = SQLBindCol(hstmt, 1, SQL_C_CHAR, &typeName, (SDWORD)sizeof(typeName), &strlenTypeName); rc = SQLBindCol(hstmt, 2, SQL_C_SHORT, &sqlDataType, (SDWORD)sizeof(sqlDataType), &strlenSqlDataType); rc = SQLBindCol(hstmt, 3, SQL_C_LONG, &columnSize, (SDWORD)sizeof(columnSize), &strlenColumnSize);

// Print column headings printf ("TypeName DataType ColumnSize\n"); printf ("-------------------- ---------- ----------\n");

do {

// Fetch the results from executing SQLGetTypeInfo rc = SQLFetch(hstmt); if (rc == SQL_ERROR) {// Procedure to retrieve errors from the SQLGetTypeInfo function ODBC_GetDiagRec(SQL_HANDLE_STMT, hstmt); break; }

// Print the results if ((rc == SQL_SUCCESS) || (rc == SQL_SUCCESS_WITH_INFO)) {printf ("%-30s %10i %10u\n", typeName, sqlDataType, columnSize); }

} while (rc != SQL_NO_DATA); }}

See "Data Types" for information about how a database's data types map to the standard ODBC data types.

See alsoDiagnostic Tools on page 139Data Types on page 51

Isolation and Lock Levels SupportedThe driver supports isolation level 0 (read uncommitted).


Isolation and Lock Levels Supported

See alsoLocking and Isolation Levels on page 267Transaction Mode on page 191

Binding Parameter MarkersAn ODBC application can prepare a query that contains dynamic parameters. Each parameter in a SQLstatement must be associated, or bound, to a variable in the application before the statement is executed.When the application binds a variable to a parameter, it describes that variable and that parameter to the driver.Therefore, the application must supply the following information:

• The data type of the variable that the application maps to the dynamic parameter

• The SQL data type of the dynamic parameter (the data type that the database system assigned to theparameter marker)

The two data types are identified separately using the SQLBindParameter function.You can also use descriptorAPIs as described in the Descriptor section of the ODBC specification (version 3.0 and higher).

The driver relies on the binding of parameters to know how to send information to the database system in itsnative format. If an application furnishes incorrect parameter binding information to the ODBC driver, the resultswill be unpredictable. For example, the statement might not be executed correctly.

To ensure interoperability, your driver uses only the parameter binding information that is provided by theapplication.



4Supported Features

This section describes some of the supported features that will allow you to take full advantage of the ProgressDataDirect for ODBC for Salesforce Driver.


• Unicode Support

• Using IP Addresses

• Parameter Metadata Support

• SQL Support

• Number of Connections and Statements Supported

• MongoDB Sharding Support

Unicode SupportThe driver is fully Unicode enabled. The driver supports the following Unicode formats according to platform:

• Windows platforms: UCS-2/UTF-16.

• UNIX and Linux platforms: UTF-8 and UTF-16.

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, see "Internationalization, Localization,and Unicode" for a more detailed explanation of Unicode.

See alsoUTF-16 Applications on UNIX and Linux on page 68Internationalization, Localization, and Unicode on page 243

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 MongoDB server is specified in IPv6 format:

DRIVER=DataDirect MongoDB Driver;HostName=2001:DB8:0000:0000:8:800:200C:417A;PORT=27017;DB=MONGODBACCT;UID=JOHN;PWD=XYZZYYou;SchemaDefinition=C:\Users\Default\AppData\Local\Progress\DataDirect\MongoDB Schema\MainServer.config

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 MongoDB Driver;HostName=2001:DB8:0:0:8:800:200C:417A;PORT=27017;DB=MONGODBACCT;UID=JOHN;PWD=XYZZYYou;SchemaDefinition=C:\Users\Default\AppData\Local\Progress\DataDirect\MongoDB Schema\MainServer.config

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

DRIVER=DataDirect MongoDB Driver;HostName=2001:DB8:0:0:8:800:123.456.78.90;PORT=27017;DB=MONGODBACCT;UID=JOHN;PWD=XYZZYYou;SchemaDefinition=C:\Users\Default\AppData\Local\Progress\DataDirect\MongoDB Schema\MainServer.config

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

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

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


Chapter 4: Supported Features

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

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

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 = ?


Parameter Metadata Support

SQL SupportThe driver for MongoDB provides support for standard SQL (primarily SQL 92), and a set of SQL extensions.For additional information, see "Supported SQL Statements."

See alsoSupported SQL Statements on page 197

Number of Connections and Statements SupportedThe driver supports multiple connections and multiple statements per connection.

MongoDB Sharding SupportMongoDB employs sharding as a horizontal scaling solution for supporting large sets of data. It is designed toprovide scalable throughput and storage capacity. To accomplish this, MongoDB shares logical databasesacross multiple independent replica sets (clustered servers), or shards. By distributing data across servers,operations are delegated only to the servers that store data relevant to the task. This increases the availabilityof servers and CPU capacity, resulting in increased throughput. If operations exceed the available processingcapacity of the clusters, additional servers can be added to the cluster, which reduces the number of operationsperformed by each server and can improve performance. A similar principle applies to storage capacity, whereservers can be added to accommodate increased storage requirements.

Caution: Although the driver connects to a MongoDB sharded cluster transparently, you must verify that allthe values of the primary key column are unique before enabling write operations (See "Read Only"). Thevalues for the default primary key of _ID are generated by a MongoDB database; however, in a sharded cluster,these values are not guaranteed to be unique across shards unless _ID is designated as the shard key in theMongoDB cluster. If duplicate identifiers are mapped to a relational view, write operations can produce undesiredresults.You can prevent this behavior by confirming that the values of _ID key are configured to be uniqueacross shards, or by designating a new primary key using the Schema Tool. See "Designating a Primary Key"for additional information.

See alsoRead Only on page 184Designating a Primary Key on page 124


Chapter 4: Supported Features

5Using 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

• Creating and Customizing Schemas Using the DataDirect Schema Tool

• Performance Considerations

• Using Security

• Using Identifiers

• Configuring the SQL Engine Server

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 19Using a Connection String on page 81

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 60

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

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

• SHLIB_PATH on HP-UX PA-RISC

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.


Chapter 5: Using the Driver

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 63

ODBCINST

Setup installs in the product installation directory a default file, named odbcinst.ini, for use with DSN-lessconnections. See "DNS-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.

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.


Configuring and Connecting to Data Sources

See alsoDSN-less Connections on page 66

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 63

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 Solaris, 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 49

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 obcinst.ini Files."

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

MongoDB=DataDirect 8.0 MongoDB Driver.

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, [MongoDB 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 252Connection Option Descriptions on page 153Sample Default odbc.ini File on page 64File Data Sources on page 67IANAAppCodePage on page 174Code Page Values on page 227DSN-less Connections on page 66ODBC Trace on page 139

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]MongoDB=DataDirect 8.0 MongoDB

[MongoDB]Driver=ODBCHOME/lib/ivmongo28.soDescription=DataDirect 8.0 MongoDB ApplicationUsingThreads=1ConfigOptions=CreateDB=2DataSourceName=Database=INFORMATION_SCHEMA EncryptionMethod=0ExtendedOptions=FetchSize=100HostName=HostNameInCertificate=



InitializationString=JVMArgs=-Xmx256mJVMClasspath=KeyPassword=Keystore=KeystorePassword=LogConfigFile=LoginTimeout=15LogonID=MinLongVarcharSize=Password=PortNumber=27017ReadOnly=1ReadPreference=primaryReportCodepageConversionErrors=0ResultMemorySize=-1SchemaDefinition=~/progress/datadirect/mongodb_schema/host_name.configServerPortNumber=19932SQLEngineMode=2TransactionMode=0Truststore=TruststorePassword=ValidateServerCertificate=1VarcharThreshold=

[ODBC]IANAAppCodePage=4InstallDir=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 "MongoDB 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, [MongoDB].



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 "MongoDB 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 "MongoDB 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 153

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 MongoDB=Installed

This section also includes additional information for each driver.



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

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 these twosections is not the same, the values in the odbc.ini [ODBC] section override those of the odbcinst.ini[ODBC] section.

See alsoODBCINST on page 61Character Encoding in the odbc.ini and odbcinst.ini Files on page 252Configuration Through the System Information (odbc.ini) File on page 63

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 MongoDB=Installed

[DataDirect 8.0 MongoDB]Driver=ODBCHOME/lib/ivmongo28.soJarFile=ODBCHOME/java/lib/mongodb.jarAPILevel=1ConnectFunctions=YYYCPTimeout=60DriverODBCVer=3.52FileUsage=0HelpRootDirectory=ODBCHOME/helpSetup=SQLLevel=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 MongoDBPort=27017HostName=MongoDB2LogonID=JOHN

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\MongoDB2.dsn

or, on UNIX and Linux:

FILEDSN=/home/users/john/filedsn/MongoDB2.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/MongoDB2.dsn;UID=james;PWD=test01

See alsoGetting Started on page 19DSN-less Connections on page 66Data Source Configuration on UNIX/Linux on page 63

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 on Windows

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.

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 MongoDB 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 169

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 170

The name or the IP address of the server to which you want to connect.

Default: NoneHost Name on page 173

Specifies the port number of the server listener.

Default: 27017Port Number on page 183



DescriptionConnection Options: General

Specifies the name of the database to which you want to connect. Thisvalue will also be used as the default qualifier for unqualified tablenames in queries.

Important: This value is case-insensitive if you have access privilegesto query the list of databases on the server. If you do not have access,it is case-sensitive.

Note: This option is required if your server requires authentication.

Default: INFORMATION_SCHEMA

Database on page 169

Specifies the name and location of the configuration file where therelational map of native data is written. The driver either creates orlooks for this file when connecting to the database.

Default:


See "Schema Definition' for details.

Schema Definition on page 188

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 take full advantage of the features of the driver, we recommend that you create or customize your schemadefinition using the schema tool. Click Schema Tool to open the Schema Tool in a separate window. Aftercreating or customizing your schema definition, proceed to the next step. See "Creating and CustomizingSchemas Using the DataDirect Schema Tool" for information on using the Schema Tool.

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

• Security tab allows you to specify security settings for the data source and Schema Tool.

7. 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 alsoSchema Definition on page 188Using a Logon Dialog Box on page 82Creating and Customizing Schemas Using the DataDirect Schema Tool on page 83



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 3: SQL Engine Tab Connection Options

DefaultConnection Options: SQLEngine

Specifies whether the driver’s SQL engine runs in the same process asthe driver (direct mode) or runs in a process that is separate from thedriver (server mode).

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 190

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 176

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 177



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 4: 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: 19932

For the 64-bit driver: 19931

Server Port Number on page189

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

Specifies the path of the working directory for the SQL engine service to use tostore the newly created database files or locate the existing database files.

If the Schema Definition connection option contains a file name prefix, the user’slocal database is created at the path specified by Server DB Directory. However,if the Schema Definition connection option contains a fully qualified path, theuser’s local database is created using that path; the path specified by ServerDB Directory is ignored.

Default: The path of the working directory for the SQL Engine service

Server DB Directory

If you finished configuring your driver, proceed to Step 7 on page 71 in "Configuring the Product on Windows."Optionally, you can further configure your driver by clicking on the following tabs.The following sections providedetails for the fields specific to each configuration tab:

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





See alsoStarting the SQL Engine Server on page 136Configuring Server Mode on page 134Configuring the Product on Windows on page 69

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 the internal files required for arelational view of the native data when establishing a connection.

If set to 0 - No, the driver uses the current embedded database specifiedby Schema Definition. If one does not exist, the connection fails.

If set to 2 - NotExist, the driver uses the current embedded databasespecified by Schema Definition. If one does not exist, the driver createsone.

Default: 2 -NotExist

Create Database on page 168




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 191

Specifies a preference for the type of member (server node) of a replicaset to which the driver attempts to connect.

If set to none, the driver attempts to connect to only the member authorizedby the application.

If set to primary, the driver attempts to connect to only the primary memberof a replica set. If the primary member is unavailable, the connection fails.

If set to primaryPreferred, the driver attempts to connect to the primarymember first; but if it is unavailable, the driver attempts to connect tosecondary members.

If set to secondary, the driver attempts to connect to only secondarymembers of a replica set. If the secondary members of the replica set areunavailable, the connection fails.

If set to secondaryPreferred, the driver attempts to connect to secondarymembers first; but if they are unavailable, the driver attempts to connectto the primary member.

Default: primary

Read Preference on page 185

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 156

Specifies whether the connection has read-only access to the data source.

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 184




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 181

Specifies the maximum number of rows that the driver processes beforereturning data to the application for a single fetch request when executinga Select.

If set to 0, the driver fetches and processes all of the rows of the resultbefore returning control to the application.

If set to x (number of rows), the driver limits the number of rows that maybe processed and returned to the application for a single fetch request.

Default: 100

Fetch Size on page 171

Specifies the maximum size, in megabytes, of an intermediate result setthat the driver holds in memory.

If set to -1, the maximum size of an intermediate result set that the driverholds in memory is determined by a percentage of the max Java heapsize.When this threshold is reached, the driver writes a portion of the resultset to disk.

If set to 0, the SQL Engine holds intermediate results in memory regardlessof size. Setting Result Memory Size to 0 can increase performance for anyresult set that can easily fit within the JVM's free heap space, but candecrease performance for any result set that can barely fit within the JVM'sfree heap space.

If set to x, the SQL Engine holds intermediate results in memory that areno larger than the size specified.When this threshold is reached, the driverwrites a portion of the result set to disk.

Default: -1

Result Memory Size on page 186

Specifies the threshold at which the driver describes columns of the datatype VARCHAR as LONGVARCHAR. If the size of the VARCHAR columnexceeds the value specified, the driver will describe the column asLONGVARCHAR when calling SQLDescribeCol and SQLColumns. Thisoption allows you to fetch columns that would otherwise exceed the upperlimit of the VARCHAR type for some third-party applications, such as SQLServer Linked Server.

Default: None. If no value is specified, the driver will not change thedescribed type for VARCHAR columns.

Varchar Threshold on page 195




Specifies the minimum count of characters the driver reports for columnsmapped as LONGVARCHAR. If the size of a LONGVARCHAR column isless than the value specified, the driver will increase the reported size ofthe column to this value when calling SQLDescribeCol and SQLColumns.This allows you to fetch LONGVARCHAR columns whose size is smallerthan the minimum imposed by some third-party applications, such as SQLServer Linked Server.

Default: None. If no value is specified, the driver will not change the columnsize reported for LONGVARCHAR columns.

Min Long Varchar Size on page182

Specifies how the driver handles code page conversion errors that occurwhen a character cannot be converted from one character set to another.

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 186

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 180

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 175

Determines how the mapping of the native data model to the relationaldata model is configured, customized, and updated. See "Config Options"for more details.

Default: None

Config Options on page 157

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:

CreateDB=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 7 on page 71 in "Configuring the Product on Windows."Optionally, you can further configure your driver by clicking on the following tabs.The following sections providedetails on the fields specific to each configuration tab:




See alsoConfig Options on page 157Configuring the Product on Windows on page 69

Security TabThe Security tab allows you to specify your security settings for the data source and Schema Tool. The fieldsare 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

The default user ID that is used to connect to your database.Your ODBCapplication may override this value or you may override it in the logon dialogbox or connection string.

Default: None

User Name on page 193

The method used to encrypt data sent between the driver or Schema Tool andthe database server.

If set to 0 - No Encryption, data is not encrypted.

If set to 1 - SSL, data is encrypted using SSL. If the server is not configured forSSL, the connection fails.

Default: 0 - No Encryption

Encryption Method on page170

Determines whether the driver and/or Schema Tool validates the certificate thatis sent by the database server when SSL encryption is enabled.

If enabled, the driver validates the certificate that is sent by the database server.Any certificate from the server must be issued by a trusted CA in the truststorefile. If the Host Name In Certificate option is specified, the driver also validatesthe certificate using a host name.The Host Name In Certificate option providesadditional security against man-in-the-middle (MITM) attacks by ensuring thatthe server the driver is connecting to is the server that was requested.

If disabled, the driver does not validate the certificate that is sent by the databaseserver.The driver ignores any truststore information specified by the Trust Storeand Trust Store Password options.

Default: Enabled

Validate Server Certificate onpage 193

The directory that contains the truststore file and the truststore file name to beused when SSL is enabled (Encryption Method=1) and server authenticationis used.

Default: None

Trust Store on page 191

Specifies the password that is used to access the truststore file when SSL isenabled (Encryption Method=1) and server authentication is used.

Default: None

Trust Store Password onpage 192

The fully qualified path and file name of the keystore file to be used when SSLis enabled (Encryption Method=1) and SSL client authentication is enabledon the database server.

Default: None

Key Store on page 179

The password used to access the keystore file when SSL is enabled(Encryption Method=1) and SSL client authentication is enabled on thedatabase server.

Default: None

Key Store Password on page180



DescriptionConnection Options:Security

The password used to access the individual keys in the keystore file when SSLis enabled (Encryption Method=1) and SSL client authentication is enabledon the database server.

Default: None

Key Password on page 178

A host name for certificate validation when SSL encryption is enabled(Encryption Method=1) and validation is enabled (Validate ServerCertificate=1).

Default: None

Host Name In Certificate onpage 173

If you finished configuring your driver, proceed to Step 7 on page 71 in "Configuring the Product on Windows."Optionally, you can further configure your driver by clicking on the following tabs.The following sections providedetails on the fields specific to each configuration tab:




See alsoUsing Security on page 128Configuring the Product on Windows on page 69

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 MongoDB for Linux/UNIX/Windowsis:

DSN=MongoDB;UID=JOHN;PWD=XYZZY

A FILEDSN connection string is similar except for the initial keyword:

FILEDSN=MongoDB;UID=JOHN;PWD=XYZZY

A DSN-less connection string must provide all necessary connection information:

DRIVER=DataDirect 8.0 MongoDB;UID=JOHN;PWD=XYZZY;HOST=MongodbServer;PORT=27017;DB=Mongodb1;SD=C:\Users\Default\AppData\Local\Progress\DataDirect\MongoDB Schema\MainServer.config


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 5: Logon to MongoDB dialog box

In this dialog box, provide the following information:

1. In the Host Name field, type the name or the IP address of the server to which you want to connect to whichyou want to connect.

2. In the Port Number field, type the port number of the server listener.

3. In the Schema Definition field, type the name and location of the configuration file where the relational mapof native data is written.

4. In the Database field, type the name of the database to which you want connect.

Important: This value is case-insensitive if you have access privileges to query the list of databases onthe server. If you do not have access, it is case-sensitive.

5. Type your logon ID in the User Name field.



6. Type your password in the Password field.

7. Click OK to complete the logon.

Creating and Customizing Schemas Using theDataDirect Schema Tool

After installation, you can create and define your schema map using the DataDirect Schema Tool.The SchemaTool allows you to map your NoSQL data model to a relational model that exposes your data to relational,SQL-based applications. Using the Schema Tool's Table Wizard, you decide whether to extract your nativedata into flattened, normalized, or customized relational views. Once you select a relational model, you canfurther customize your schema by defining column data types and the order in which columns appear. Theschema maps created by the Schema Tool are stored in configuration files that allow them to be shared acrossservers.

Starting the Schema Tool

The DataDirect Schema tool allows you to create a schema definition or modify an existing one. When youcreate a schema definition using the schema tool, the definition is written to a configuration file in a directorythat you specify (refer to the "Schema Definition" connection option topic in your driver documentation fordetails). Because schema definitions are stored separately from the tool, they can be shared across networksand modified as needed.

Note: When an existing schema is opened, the Schema Tool automatically compares the content of theschema configuration file to a snapshot of the data on the wire. When new native objects are discovered, theSchema Tool displays them in a specialized, hierarchical view of the data and allows you to update your schemaaccordingly. See "Mapping Newly Detected Objects" for more information.

To create or modify a schema definition using the Schema Tool:

• For UNIX/Linux users, go to Starting the Schema Tool on UNIX/Linux on page 83.

• For Windows users, go to Starting the Schema Tool on Windows on page 91.

See alsoMapping Newly Detected Objects on page 117

Starting the Schema Tool on UNIX/LinuxTo create a new schema definition or modify an existing one, follow these steps:

1. From the command prompt, switch to the installation directory. Enter:

java –jar schematool.jar

The default installation directory is:

For 32-bit drivers:

/opt/Progress/DataDirect/ODBC_80/Tools

For 64-bit drivers:


Creating and Customizing Schemas Using the DataDirect Schema Tool

/opt/Progress/DataDirect/ODBC_80_64bit/Tools

Note: The Schema Tool is only offered as a GUI application. If your system does not support GUIapplications, you will receive an error when opening the Schema Tool.

2. The Open Schema Definition window appears.

Choose if you want to create a schema definition or open an existing one. Select one of the following options:

• Recent Schema Definition. Choose this option if you want to open a schema definition that you haverecently opened. From the drop down menu, select the directory path of the schema definition that youwant to open. Skip to Step 4.

• Browse to Schema Definition. Choose the option to open an existing schema definition. Click theBrowse button to browse to and select the configuration file that contains the schema definition that youwant to open. Skip to Step 4.

• Create New Schema Definition. Choose this option to create a schema definition. Proceed to the nextstep.

3. In the Schema Definition Location field, specify the path and file name of the schema definition configurationfile in either of the following ways.

Note: The path is an absolute path to the directory that stores the schema definition file(~/progress/datadirect/mongodb_schema/).The file name is the full name of the schema definitionfile, including the .config extension (MainServer.config). Refer to the "Schema Definition" connectionoption topic in your driver documentation for details.



• Type the schema definition path and file name directly in the Schema Definition Location field, for example,~/progress/datadirect/mongodb_schema/MainServer.config.

• Click Create. Specify the schema definition path by navigating to the directory where you want to storethe configuration file. Type the name for your configuration file (for example, MySchema.config) in theFile Name field. Click Create New Schema Definition.You are returned to the Open Schema Definitionwindow where the Schema Definition Location field has been populated with the path and file name ofthe schema definition's configuration file.

4. In the fields provided, enter values for each of the connection options described in the following table.

Table 5: Schema Tool Connection Options

CharacteristicOption

Specifies the name or the IP address of the server to which you wantto connect.

Host Name

Specifies the port number of the server listener.Port Number

5. Optionally, specify the config options values to determine how native data is mapped to the relationalschema. In the Configuration Options field, enter a semicolon separated list of config options and theirvalues. For example, columnDiscoverySampleSize=1000;UppercaseIdentifiers=true;. Configoptions are described in the following table.

Table 6: Schema Tool Config Options

CharacteristicConfig Option

Specifies the number of rows the driver fetches per collection whensampling data to detect columns and gather column statistics. Theinformation collected in these samples is used when defining a schemadefinition with the Schema Tool. Larger fetch sizes return samples thatare more representative of your data, but at the expense of slowerperformance when generating a configuration file. See About ColumnInformation and Statistics on page 110 for additional information on howsampling is used for statistics.

The default is 1000.

columnDiscoverySampleSize




Determines the default length of fields that are mapped as VARCHAR.

Valid values:

length | multiplier

where:

length

is the default length in characters given to columns that arediscovered and mapped as VARCHAR.

multiplier

is a positive number immediately followed by the characterx. For example, 3x. The positive integer is multiplied by thesize of the largest object detected in a column to determinethe default VARCHAR length for that column.

Note: When specifying a multiplier, you can define the maximum andminimum limits of the default length generated with the MaxVarcharSizeand MinVarcharSize config options.

The default is 1.5x

DefaultVarcharSize

Specifies a string of up to five alphanumeric characters that the driverappends to any object or field name that conflicts with a SQL enginekeyword.

string

where:

string

is a string of up to five alphanumeric characters.

For example, a field called CASE exists in the native MongoDB data.To avoid a naming conflict with the SQL engine keyword CASE, youcould set KeywordConflictSuffix=TAB. In this scenario, the drivermaps the Case object to the CASETAB column.

There is no default value.

KeywordConflictSuffix




LeadingUnderscoreReplacement specifies the string of characters thatreplace leading underscores used in identifiers for collections,documents, and arrays.

Valid values:

string

where:

string

is comprised of any Unicode character or group of characters,including spaces.

For example, MongoDB collections automatically include the _id field.By specifying LeadingUnderscoreReplacement=XX, the _id fieldbecomes the XXID column in the relational view of the data.

Note: The Table Wizard builds table and column identifiers byconcatenating the names of nested collections, documents, and arrays.When specifying a value for LeadingUnderscoreReplacement, considerthat the total length of identifiers must not exceed 128 characters inlength.

There is no default value. When no value is specified, a leadingunderscore is used in identifiers.

LeadingUnderscoreReplacement

Specifies the maximum default length of fields that are mapped asVARCHAR when a multiplier is specified for the DefaultVarcharSizeconfig option (DefaultVarcharSize=multiplier).


MaxVarcharSize

Specifies the minimum default length, in characters, of fields that aremapped as VARCHAR when a multiplier value is specified for theDefaultVarcharSize config option(DefaultVarcharSize=multiplier).

The default is 255.

MinVarcharSize




Specifies a comma-separated list of database and collection pairs forwhich you want the driver to fetch metadata. SchemaFilter cansignificantly improve connection times by limiting the collections forwhich metadata is fetched to only those that are required by yourapplication. This value takes the following form:

SchemaFilter=database_name:collection_name[[,database_name:collection_name]...]

See "SchemaFilter (Config Option)" for detailed list of supported values.

SchemaFilter

Defines how the driver maps identifiers.

If set to true, the driver maps identifiers to uppercase.

If set to false, The driver maps identifiers to the mixed case name ofthe object being mapped. If mixed case identifiers are used, SQLstatements must enclose those identifiers in double quotes, and thecase of the identifier, must exactly match the case of the identifier name.

See "Naming Conflicts" for additional information about using identifiers.

The default is true.

Note: If you receive an error message indicating that naming conflictshave occurred, you must specify the UppercaseIdentifiers config optionsto false before the driver will connect to a database.

UppercaseIdentifiers

6. Optionally, specify values for security-related connection options to determine the security settings usedwhen accessing data with the Schema Tool. In the Configuration Options field, enter a semicolon separatedlist of connection options attributes and their values. For example,EncryptionMethod=SSL;ValidateServerCertificate=true;HostNameInCertificate=Server3. Security-related options are described in the following table. Foradditional information, see "Using Security with the Schema Tool". For more information on these and otherconnection options, refer to the "Connection Option Descriptions" chapter in your driver documentation.

Important: The Connection Options field currently supports only the SSL related options described in thefollowing table. Do not enter attributes and values for other connection options in this field.

Note: Security-related options are configured separately for the driver and Schema Tool. To configuresecurity settings for the driver, see "Configuring the Product on UNIX/Linux."



Table 7: Schema Tool Security Connection Options

Valid ValuesConnection Option

Attribute

The method used to encrypt data sent between the Schema Tool and thedatabase server. If set to noEncryption, data is not encrypted.

If set to SSL, data is encrypted using SSL. If the server is not configured forSSL, the connection fails.

Note: The driver and Schema Tool use different valid values for theEncryptionMethod option.

EncryptionMethod

A host name for certificate validation when SSL encryption is enabled(Encryption Method=SSL) and validation is enabled (Validate ServerCertificate=true).

HostNameInCertificate

The password used to access the individual keys in the keystore file when SSLis enabled (Encryption Method=SSL) and SSL client authentication isenabled on the database server.

KeyPassword

The fully qualified path and file name of the keystore file to be used when SSLis enabled (Encryption Method=SSL) and SSL client authentication isenabled on the database server.

Keystore

The password used to access the keystore file when SSL is enabled(Encryption Method=SSL) and SSL client authentication is enabled on thedatabase server.

KeystorePassword

The fully qualified path and file name for the truststore file to be used when SSLis enabled (Encryption Method=SSL) and server authentication is used.The password that is used to access the truststore file when SSL is enabled (

Truststore

Encryption Method=SSL) and server authentication is used.TruststorePassword



Valid ValuesConnection Option

Attribute

The default user ID that is used to connect to your database.Your ODBCapplication may override this value or you may override it in the logon dialogbox or connection string.

LoginID

Determines whether the Schema Tool validates the certificate that is sent bythe database server when SSL encryption is enabled.

If set to true, the driver validates the certificate that is sent by the databaseserver. Any certificate from the server must be issued by a trusted CA in thetruststore file. If the Host Name In Certificate option is specified, the driver alsovalidates the certificate using a host name.The Host Name In Certificate optionprovides additional security against man-in-the-middle (MITM) attacks byensuring that the server the driver is connecting to is the server that wasrequested.

If set to false, the driver does not validate the certificate that is sent by thedatabase server. The driver ignores any truststore information specified by theTrust Store and Trust Store Password options.

Note: The driver and Schema Tool use different valid values for theValidateServerCertificate option.

ValidateServerCertificate

7. Choose whether to use user ID/password authentication. (User ID/password authentication authenticatesthe user to the database using a database user name and password.)

• If you are not using user ID/password authentication, clear the Use AuthenticationThe password thatis used to access the truststore file check box. Skip to Step 9.

• If you are using user ID/password authentication, select Use Authentication. Fields for the authenticationconnection options are exposed in the window. Proceed to the next step.

Note: Your authentication settings determine for which databases the Schema Tool retrieves metadata. Ifauthentication is not used, the Schema Tool retrieves metadata for all databases on the server. Ifauthentication is used, the Schema Tool returns only the metadata for the database specified in the DatabaseName option. However, if you are assigned the clusterAdmin role, the Schema Tool returns metadata forall the databases on the server for which you have read privileges when authentication is enabled.

8. In the fields provided, enter values for each of the authentication connection options described in the followingtable.

Table 8: Schema Tool Authentication Connection Options


Specifies the name of the database to which you want to connect.Database Name




If Use Authentication is selected, specifies the user ID that is usedto connect to your database.

User Name

If Use Authentication is selected, specifies the password to use toconnect to your database.

Password

9. To create a new schema definition or open an existing one, click Open Schema Definition.

• If you are creating a new schema definition, proceed to Creating a Schema with the Table Wizard onpage 99.

• If you are modifying an existing schema definition, proceed to the next step.

10. If you are using an existing schema map, choose one of the following sampling behaviors to execute atconnection:

• All Collections: The driver samples all new and existing collections to detect changes. This providesthe most accurate view of your data, but, depending on the number and size of your collections, cantake a long time to process.

• Only New Collections:The driver samples only newly discovered collections.This provides the quickestprocessing time, allowing you to begin using the tool faster. If you only want to map new collections, orif your existing collections are unchanged, this method is recommended.

See alsoSchemaFilter (Config Option) on page 165Naming Conflicts on page 126Using Security with the Schema Tool on page 130Connection Option Descriptions on page 153Configuring the Product on UNIX/Linux on page 60

Starting the Schema Tool on WindowsTo create or modify a schema definition, follow these steps:

1. From the Progress DataDirect program group, click ODBC Administrator.

2. Select a tab:


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.


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.




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. Select the driver you want to use from the Create New Data Source window. Then click Finish.

The the General tab of the driver setup dialog box appears.

4. In the General tab, enter the appropriate information for each connection option; then, click Apply. Thefollowing table provides a short description of each. For more information on these and other connectionoptions, refer to the "Connection Option Descriptions" chapter in your driver documentation.

Table 9: Summary: Setup Dialog Connection Options


Specifies the name of a data source in your Windows Registry or odbc.ini file.Data Source Name

Specifies an optional long description of a data source.Description

The name or the IP address of the server to which you want to connect.Host Name

Specifies the port number of the server listener.Port Number




Specifies the name of the database to which you want to connect.Database

Specifies the name and location of the configuration file where the relationalmap of native data is written. For example,C:\Users\Default\AppData\Local\Progress\DataDirect\MongoDBSchema\MainServer.config. The default is:


Refer to the "Schema Definition" connection option topic in your driverdocumentation for details.

Schema Definition

Note: Your authentication settings determine for which databases the Schema Tool retrieves metadata. Ifauthentication is not used, the Schema Tool retrieves metadata for all databases on the server. Ifauthentication is used, the Schema Tool returns only the metadata for the database specified in the Databaseoption field. However, if you are assigned the clusterAdmin role, the Schema Tool returns metadata for allthe databases on the server for which you have read privileges when authentication is enabled.

5. Optionally, click the Advanced tab to specify the config options values to determine how native data ismapped to the relational schema.



In the Config Options field, enter a semicolon separated list of config options and their values. For example,columnDiscoverySampleSize=1000;UppercaseIdentifiers=true;. Click Apply; then, click onthe General tab. The following table provides a short description of each config option.

Table 10: Schema Tool Config Options


Specifies the number of rows the driver fetches per collection whensampling data to detect columns and gather column statistics. Theinformation collected in these samples is used when defining a schemadefinition with the Schema Tool. Larger fetch sizes return samples thatare more representative of your data, but at the expense of slowerperformance when generating a configuration file. See "About ColumnInformation and Statistics" for additional information on how samplingis used for statistics.


columnDiscoverySampleSize

Determines the default length of fields that are mapped as VARCHAR.

Valid values:

length | multiplier

where:

length

is the default length in characters given to columns that arediscovered and mapped as VARCHAR.

multiplier

is a positive number immediately followed by the characterx. For example, 3x. The positive integer is multiplied by thesize of the largest object detected in a column to determinethe default VARCHAR length for that column.

Note: When specifying a multiplier, you can define the maximum andminimum limits of the default length generated with the MaxVarcharSizeand MinVarcharSize config options.

The default is 1.5x

DefaultVarcharSize




Specifies a string of up to five alphanumeric characters that the driverappends to any object or field name that conflicts with a SQL enginekeyword.

string

where:

string


For example, a field called CASE exists in the native MongoDB data.To avoid a naming conflict with the SQL engine keyword CASE, youcould set KeywordConflictSuffix=TAB. In this scenario, the drivermaps the Case object to the CASETAB column.

There is no default value.

KeywordConflictSuffix

LeadingUnderscoreReplacement specifies the string of characters thatreplace leading underscores used in identifiers for collections,documents, and arrays.

Valid values:

string

where:

string

is comprised of any Unicode character or group of characters,including spaces.

For example, MongoDB collections automatically include the _id field.By specifying LeadingUnderscoreReplacement=XX, the _id fieldbecomes the XXID column in the relational view of the data.

Note: The Table Wizard builds table and column identifiers byconcatenating the names of nested collections, documents, and arrays.When specifying a value for LeadingUnderscoreReplacement, considerthat the total length of identifiers must not exceed 128 characters inlength.

LeadingUnderscoreReplacement

Specifies the maximum default length of fields that are mapped asVARCHAR when a multiplier is specified for the DefaultVarcharSizeconfig option (DefaultVarcharSize=multiplier).


MaxVarcharSize




Specifies the minimum default length, in characters, of fields that aremapped as VARCHAR when a multiplier value is specified for theDefaultVarcharSize config option(DefaultVarcharSize=multiplier).

The default is 255.

MinVarcharSize

Specifies a comma-separated list of database and collection pairs forwhich you want the driver to fetch metadata. SchemaFilter cansignificantly improve connection times by limiting the collections forwhich metadata is fetched to only those that are required by yourapplication. This value takes the following form:

SchemaFilter=database_name:collection_name[[,database_name:collection_name]...]

See "SchemaFilter (Config Option)" for detailed list of supported values.

SchemaFilter

Defines how the driver maps identifiers.

If set to true, the driver maps identifiers to uppercase.

If set to false, The driver maps identifiers to the mixed case name ofthe object being mapped. If mixed case identifiers are used, SQLstatements must enclose those identifiers in double quotes, and thecase of the identifier, must exactly match the case of the identifier name.

See "Naming Conflicts" for additional information about using identifiers.

The default is true.

Note: If you receive an error message indicating that naming conflictshave occurred, you must specify the UppercaseIdentifiers config optionsto false before the driver will connect to a database.

UppercaseIdentifiers

6. Optionally, click the Security tab to specify values for security-related connection options to determine thesecurity settings used when accessing data with the Schema Tool and driver.



Enter the appropriate information for each connection option that is applicable to your security environment;then, click Apply. The following table provides a short description of each. For more information on theseand other connection options, refer to the "Connection Option Descriptions" chapter in your driverdocumentation.

DescriptionConnection

Options

Specifies the default user ID that is used to connect to your database.Your ODBCapplication may override this value or you may override it in the logon dialog box orconnection string.

User Name

The method used to encrypt data sent between the Schema Tool and the databaseserver.

If set to 0 - No Encryption, data is not encrypted.

If set to 1 - SSL, data is encrypted using SSL. If the server is not configured for SSL,the connection fails.

Encryption Method



DescriptionConnection

Options

Determines whether the driver and/or Schema Tool validates the certificate that issent by the database server when SSL encryption is enabled.

If enabled, the driver validates the certificate that is sent by the database server. Anycertificate from the server must be issued by a trusted CA in the truststore file. If theHost Name In Certificate option is specified, the driver also validates the certificateusing a host name. The Host Name In Certificate option provides additional securityagainst man-in-the-middle (MITM) attacks by ensuring that the server the driver isconnecting to is the server that was requested.

If disabled, the driver does not validate the certificate that is sent by the databaseserver. The driver ignores any truststore information specified by the Trust Store andTrust Store Password options.

Validate ServerCertificate

Specifies the directory that contains the truststore file and the truststore file name tobe used when SSL is enabled (Encryption Method=1) and server authenticationis used.

Trust Store

Specifies the password that is used to access the truststore file when SSL is enabled(Encryption Method=1) and server authentication is used.

Trust StorePassword

Specifies the fully qualified path and file name of the keystore file to be used whenSSL is enabled (Encryption Method=1) and SSL client authentication is enabledon the database server.

Key Store

Specifies the password used to access the keystore file when SSL is enabled(Encryption Method=1) and SSL client authentication is enabled on the databaseserver.

Key Store Password

Specifies the password used to access the individual keys in the keystore file whenSSL is enabled (Encryption Method=1) and SSL client authentication is enabledon the database server.

Key Password

Specifies the host name for certificate validation when SSL encryption is enabled(Encryption Method=1) and validation is enabled (Validate ServerCertificate=1).

Host Name InCertificate

7. Click on the Schema Tool button to open the Schema Tool.

• If you are creating a new schema definition, proceed to Creating a Schema with the Table Wizard onpage 99.

• If you are modifying an existing schema definition, proceed to the next step.

8. If you are using an existing schema map, choose one of the following sampling behaviors to execute atconnection:

• All Collections: The driver samples all new and existing collections to detect changes. This providesthe most accurate view of your data, but, depending on the number and size of your collections, cantake a long time to process.

• Only New Collections:The driver samples only newly discovered collections.This provides the quickestprocessing time, allowing you to begin using the tool faster. If you only want to map new collections, orif your existing collections are unchanged, this method is recommended.



See alsoAbout Column Information and Statistics on page 110SchemaFilter (Config Option) on page 165Naming Conflicts on page 126About Column Information and Statistics on page 110Naming Conflicts on page 126

Creating a Schema with the Table Wizard

It is recommended that you create a relational schema before you connect to a server. This process beginswith the DataDirect Schema Tool Table Wizard. Once you open the Table Wizard according to the instructionsdescribed in Starting the Schema Tool on page 83, the Table Wizard prompts you to select one of the followinginitial views to begin the process of creating a relational schema:

• Normalized View which presents your data in a relational format, mapping subdocuments and arrays aschild tables with foreign key relationship to a parent table. For instructions on how to generate a normalizedview of your data, see Generating a Normalized View on page 99.

• Flattened View which presents your data in a relational format, mapping subdocuments and arrays ascolumns within a comprehensive relational table. For instructions on how to generate a flattened view ofyour data, see Generating a Flattened View on page 101.

• Custom View which allows you to choose the native data you want to map to a relational schema. Thisview is ideal if your server contains a large number of databases/collections, but you only want to queryfrom a select few. For instructions on how to begin the customization process with Custom View, seeStarting with Custom View on page 103.

See alsoStarting the Schema Tool on page 83

Generating a Normalized ViewAfter you open the Table Wizard according to the instructions in "Starting the Schema Tool," you can generatea normalized view of your data by taking the following steps:

1. Select Normalized View under Select an initial view for your data in the Table Wizard window.

The Table Wizard displays a graphic which shows how objects, such as embedded documents and arrays,are normalized into a relational structure.



2. Click OK to generate the normalized schema.

The Schema Tool's main display appears with a normalized view of your data in the left-hand panel.

Note: If you want to change the initial view of your data later, select File>Restart Wizard from the TableWizard dialog. Be aware that restarting the wizard also overwrites any customizations you have made toyour schema definition. See "Restarting the Wizard" for more information.

3. Click the Save button to save the schema.

4. Click database and table nodes to tour the normalized schema structure.

A normalized view of your data has been generated and saved.



The Table Wizard has decomposed each collection into a parent table with multiple child tables. In the parent

table, the _id field is mapped as a primary key column and is denoted with the ID icon . The parent tablealso contains any columns derived from simple types (in contrast to subdocuments and arrays). In turn, childtables are derived from any complex types discovered in the source data. The child tables share a foreign keyrelationship with the parent table.When a subdocument is normalized into a child table, the primary key column

and the foreign key column are one and the same. Such a column is denoted with the ID/FK icon . Whenan array is normalized into a child table, the primary key column and foreign key column are distinct columns.

The primary key column is denoted with the ID icon , while the foreign key column is denoted with the FK

icon . For more information on relational mapping, refer to "Mapping Objects to Tables" in your driverdocumentation.

Depending on your work flow, you can now proceed with customizing the schema. See "Customizing YourSchema" for details.

See alsoStarting the Schema Tool on page 83Restarting the Wizard on page 126Customizing Your Schema on page 106

Generating a Flattened ViewAfter you open the Table Wizard according to the instructions in "Starting the Schema Tool," you can generatea flattened view of your database by taking the following steps:

1. Select Flattened View under Select an initial view for your data in the Table Wizard window.

The Table Wizard presents a graphic which shows how objects, such as subdocuments and arrays, areflattened into a relational structure.



2. Click OK to generate the flattened schema.

The Schema Tool's main display appears with the flattened view of your data in the left-hand panel.


3. Click the Save button to save the schema.

4. Click database and table nodes to tour the flattened schema structure.

A flattened view of your data has been generated and saved. The Schema Tool's main display appears witha flattened view of your data in the left-hand panel:



The Table Wizard has decomposed each collection into a relational table.The _id field is mapped as a primary

key column and denoted with the ID icon . Fields with simple types, such as address and name, aremapped as the corresponding columns ADDRESS and NAME. Subdocuments are flattened into columns usingthe <objectname>_<fieldname> pattern, and nested arrays are flattened into columns using the<arrayname>_<arrayindex> pattern. For more information on relational mapping, refer to "Mapping Objectsto Tables" in the driver documentation.

Depending on your work flow, you can now proceed with customizing the schema. See "Customizing YourSchema" for details.

See alsoStarting the Schema Tool on page 83Restarting the Wizard on page 126Customizing Your Schema on page 106

Starting with Custom ViewInstead of generating a normalized or flattened view of your data first, you can begin the process of customizingthe relational view of your data by selecting Custom View in the Table Wizard. This view is ideal if your servercontains a large number of databases/collections, but you only want to query from a select few. Take thefollowing steps to start the customization process with the Table Wizard:

1. Open the Table Wizard according to the instructions in "Starting the Schema Tool":



2. Select Custom View under Select an initial view for your data in the Table Wizard window.

3. Click OK.


The Schema Tool's main display appears:



4. From the main display, click the Add Table(s) button.

The Schema Tool Native View window appears:



From the Schema Tool Native View, you can begin customizing your relational schema by selecting objectsto map from the Available Schemas tree. See "Mapping Native Objects" and "Customizing Your Schema" fordetails.

See alsoStarting the Schema Tool on page 83Restarting the Wizard on page 126Mapping Native Objects on page 112Customizing Your Schema on page 106

Customizing Your Schema

Depending on your work flow, you can either customize your database schema when you first create it or returnto a schema you have already created and modify it as the need arises. In either case, the DataDirect SchemaTool helps you accomplish several key tasks. See the following topics for details.



• Viewing Information and Statistics on page 107

• Mapping Native Objects in a Schema on page 112

• Adding Columns on page 120

• Removing Objects from a Schema on page 121

• Removing Columns on page 122

• Defining Columns on page 123

• Designating a Primary Key on page 124

• Naming Conflicts on page 126

Viewing Information and StatisticsThe Schema Tool provides information and statistics about your data that you can use to modify your schemadefinitions. Column information and statistics are affected by the Schema Tool's configuration (see "AboutColumn Information and Statistics" for details).The following steps demonstrate how you can access informationand statistics.

1. To view database and table information, select the database you want to investigate from the left panel inthe main display.

Available database and table information is displayed in the panel to the right. In addition to other information,table names and whether they are visible in your relational schema are provided.



2. To view table and column information, select the table you want to investigate.

Available information is displayed in the panel to the right, including the position of the column, the columndata type, and (if applicable) column parameters.

Note: The Column Information pane is interactive. From this pane, in the main display, you can add columns,rename columns, change a column's data type, change data type parameters, and change the order inwhich columns appear in a table. See "Defining Columns" for details.

3. For column statistics, select a column in either the right or left panel.

Note: Column information and statistics are affected by the Schema Tool's configuration. See "AboutColumn Information and Statistics" for details.

When you select a column from the right panel, column statistics are displayed in the following way.



When you select the column from the left panel, column statistics are displayed in the following way.



See alsoAbout Column Information and Statistics on page 110Defining Columns on page 123

About Column Information and Statistics

Column information and statistics are based on the number of rows sampled. The default sample size is setto 1000 rows.You can adjust the sample size by specifying a different number of rows for thecolumnDiscoverySampleSize value in the Config Options connection option. Refer to "Connection OptionDescriptions" in your driver documentation for details on setting this and other options.

When the sample size is less than the total number of rows in a table, statistics are based on the sample andnot all the values in the table. For example, the table CONTACTS has 20,000 rows of data. If the sample sizeis 5000 rows, statistics are based on the first 5000 rows of data returned. Statistics are not collected on theremaining 15,000 rows of data. In turn, when the sample size is equal to or greater than the number of rowsin a table, statistics are based on all the rows within the table.



Information and Statistics Displayed in the Column Information PaneWhen you select a column (or field) from the Column Information pane, you receive the following informationon the data types found in the column:

• Data Type is the name of the native data type. (Refer to "Data Types" in the driver documentation forinformation on supported data types.)

• Max Display Length is the longest value found in a column within the sample. For example, in a sample ofthe column LAKES, the values Jordan and Durgam Cheruvu are found. In this scenario, the maximumdisplay length would be 14.

• Min Array Size is the minimum number of elements found in an array. For example, in a sample of thecolumn EMAIL, the Schema Tool finds 2 email addresses in one row and 5 email addresses in another.The Min Array Size would be 2.

• Max Array Size is the maximum number of elements found in an array. For example, in a sample of thecolumn EMAIL, the Schema Tool finds 2 email addresses in one row and 5 email addresses in another.The Max Array Size would be 5.

• Occurrences/Density displays:

1. The number of rows within the sample size containing a column value as the given data type (occurrences)

2. The percentage of rows within the sample size containing the column as a given data type (density)

How Sample Size Affects Occurrences/DensityThe following examples show how sample size affects the Occurrences/Density values.

• In a scenario where the sample size has been set to 5000, the first 5000 rows of the column EMAIL contain1000 occurrences of the Array data type and 3000 occurrences of the String data type. When the EMAILcolumn is selected, the Density/Occurrences values for ARRAY would appear as 1000 (20.00%) whilethe values for STRING would appear as 3000 (60.00%).

• In a scenario where the sample size has been set to 10000 rows, the column NAMES is selected from atable with 8000 rows. In this case, column statistics are based on all the data in the column. If 2000 Stringdata types are discovered, the Occurrences/Density values would appear as 2000 (25.00%). In turn, if4000 Object data types are discovered, the Occurrences/Density values would appear as 4000 (50.00%).

How Sample Size Affects MappingSample size affects column information as well as column statistics. For example, if the Schema Tool discoversthat all the sampled rows in a column have the Double data type, that data type is mapped as Double in therelational view of the table. In contrast, if the Schema Tool discovers a column with multiple data types withinthe sampled rows, the SQL type is determined by the combination of data types detected within the column.For details, see Default Mapping of Columns with Inconsistent Data Types.

Column Size for VarcharFor columns mapped to Varchar, the driver truncates values that exceed the column size defined for the columnwhen constructing the relational map of your data. For example, if you have a column with a defined columnsize of 150 that contains a value with 200 characters, the driver returns only the first 150 characters of thatvalue.

During the initial discovery and normalization process, you can use the defaultVarcharSize configuration optionto specify the default length of fields that are discovered and mapped as Varchar by the driver. If the driverdiscovers a field with String data of a greater length, the field is truncated to the length of the specified value.

After the initial discovery and normalization process, you can define the column size of individual columns fromthe main display of the Schema Tool. In the main display, select the table from the Available Schemas pane.In the Column Information pane, you can specify a new column size in the VARCHAR Size field.



If you merely want to find out the size of a Varchar column, you can execute the getColumns function. Thecolumn size defined will be the value of the COLUMN_SIZE column.

Column Size for VarbinaryFor columns mapped to Varbinary, the driver truncates values that exceed the column size defined for thecolumn when constructing the relational map of your data. For example, if you have a column with a definedcolumn size of 8000 that contains a value with 9000 bytes, the driver will return only the first 8000 bytes of thatvalue. The default maximum size of Varbinary columns is set 8000 bytes.

After the initial discovery and normalization process, you can define the column size of individual columns fromthe main display of the Schema Tool. In the main display, select the table from the Available Schemas pane.In the Column Information pane, you can specify a new column size in the VARCHAR Size field.

If you merely want to find out the size of the Varbinary column, you can execute the getColumns function. Thecolumn size defined will be the value of the COLUMN_SIZE column.

Mapping Native Objects in a SchemaAfter selecting an initial relational view of your data, you may want to map additional native objects to yourschema definition. To map native objects in a schema, see the following topics:

• Mapping Native Objects on page 112

• Mapping Newly Detected Objects on page 117

Mapping Native Objects

You can map native objects in your relational schema when you first create a schema definition or after youhave already created one. In either case, this process is carried out through the Schema Tool Native Viewdialog.

1. From the Schema Tool's main display, click Add Table(s) button to open the Schema Tool Native Viewdialog.

A hierarchical view of your native data appears in the window.You can click on nodes to see how objectsare nested.



2. Select either Flatten or Normalize. Then select the objects you want to include in your schema.

Flatten has been selected in the following example. A native view of the data is presented. residentscorresponds to the native residents collection, address corresponds to an embedded document in thecollection, vehicles corresponds to an array in the collection, and so forth.



Normalize has been selected in the following example. Because the Schema Tool handles normalizationof objects more than one level deep, you can only select tables when Normalize is selected. However, youcan tailor these tables by excluding columns once they have been added to your schema (see "RemovingObjects from a Schema" for details).



3. Click OK.

The Schema Tool's main display appears.

4. Click the Save button to save your modification of the schema definition.

This following example shows how the residents collection has been flattened into the relational RESIDENTStable.

Note: Refer to "Mapping Objects to Tables" in the driver documentation for details on how the Schema Toolflattens data.



This following example shows how the residents collection has been normalized into a set of parent-childtables.

Note: Refer to "Mapping Objects to Tables" in the driver documentation for details on how the Schema Toolnormalizes data.



See alsoRemoving Objects from a Schema on page 121

Mapping Newly Detected Objects

When you open an existing schema with the Schema Tool, the Schema Tool automatically compares thecontent of the schema configuration file to a new sample of the data from the server. When new native objectsare detected, the Schema Tool identifies the newly detected objects by highlighting the objects in a hierarchicalview of the native data. This information is displayed in the New Native Objects window which opens over theSchema Tool's main display window. In the following example, a number of new objects have been discovered:



If you want to include all the new objects in your schema, click the Update Schema button. All new objects inthe view will be added using the same relational view as the initial view you selected for your schema in "Creatinga Schema with the Table Wizard." For example, if you selected a normalized initial view, the objects will benormalized when they are added to the schema. For schema definitions with a custom initial view, new objectsare added using a normalized view.

Alternatively, you can add new objects manually as described in "Mapping Native Object." By manually addingthe objects, you can choose which new objects are added to your schema as well as customize how they mapto the relational view, including whether they are flattened or normalized.You can leave the New Native Objectswindow open as a reference while you modify your schema. Keep in mind that this window is a partial view ofthe native data: it highlights new objects and displays the parents of new objects to show where they arelocated.

After you are done reviewing the new native objects view, you can close the window. This view will remainavailable until you save your schema. Once you save, any new objects not added to the schema will be removed

from the view. To reopen the window, click the New Native Objects button .

Note: You can map new native objects without using the Schema Tool by executing the REFRESH MAPstatement. See "Refresh Map (EXT)" for details.

See alsoCreating a Schema with the Table Wizard on page 99Mapping Native Objects on page 112



Extracting a New TableYou can map a single object multiple times by extracting a new table from an existing relational table. In effect,you are adding the same table to your schema under a new name. Any subsequently named table will refer tothe same native object as the original table.

Take the following steps to extract a new table:

1. Navigate to the Schema Tool's main display.

2. In the Available Schemas panel, right-click the table you want to add to your schema under a new name,and select Extract New Table.

The Schema Tool Native View window appears. In the Column Information pane, you can view the columnsassociated with the table you are adding to the schema.

3. If you want to remove a column from your new table, select the column in the Column Information pane;

then, click the Remove Column button . Repeat this step for any additional columns you would like toremove.

4. Optionally, define your columns in the Column Information pane. From this pane, you can rename columns,change a column's data type, change data type parameters (if applicable), and change the order in whichcolumns appear in a table. See "Defining Columns" for details.



5. In the New Table Name field, type a unique name for the table. Then click OK. A confirmation message willbe displayed. Click OK again.

The Schema Tool returns you to the main display.

6. In the left-hand panel, check the schema to ensure that the new table has been added. To save your work,

click the Save button or select File > Save.

A table has been added to your relational schema, and the modified schema has been saved.Your SQL-basedapplications can use the name of the newly mapped table when running queries against the modified schema.

See alsoDefining Columns on page 123

Adding ColumnsWhen you add a column to a table, you are mapping the field of the native data source to your relational schema.The functionality described here is intended to be used when you want to map a field that does not appear inyour relational schema. (It should not be used for duplicating or renaming a column that is already present inyour schema.) Take the following steps to add a new column to your schema.

Note: You can map or add objects, including columns, to your relational schema in other ways. See "MappingNative Objects in Schema" for details.

1. Open the Add Column window in either of the following ways:

• From the Available Schemas panel, right-click the table and select Add Column.

• If you have the table you are modifying selected, you can click the Add Column button .

The Add Column window appears.

2. Enter the name of the native field you want to add as a column, or select it from the drop-down list. Thename of the native field is case-sensitive.

Note: You can add fields that were not initially discovered by the Schema Tool. In this scenario, the nameof the native field will not be available in the drop-down list, and you will have to enter the correct name inthe Source Column Name field. When adding array elements, you will need to add not only the name ofthe element but also its index value. When indexing array elements, the element in the first position isindexed as 0, the element in the second position as 1, the element in the third position as 2, and so on. Forexample, the object Coordinates is an array in which the first element is the longitude and the secondelement is the latitude. In this case, you could specify Coordinates.0 as the source column whose columnname is Longitude, and you could map Coordinates.1 to a column name of Latitude.

3. Enter a name for the column and click Add.



The Schema Tool returns to the main display. The native field now appears as a column in the table.

4. Click the Save button or select File>Save to save the modified schema.

See alsoMapping Native Objects in a Schema on page 112

Removing Objects from a SchemaWhen you remove an object, you are hiding it from the relational view of your data and, by extension, fromyour SQL-based applications. The native data itself is not changed in any way. Because the native objectpersists, objects that have been removed can be added back to your relational schema (see "Mapping NativeObjects in a Schema").

The following instructions illustrate how you can remove or hide any object that appears in the Schema Tool'sAvailable Schemas panel.

Note: You can also remove columns from the Column Information pane. See "Removing Columns" for details.

1. Navigate to the Schema Tool's main display.

2. Select the object(s) you want to remove in the Available Schemas pane.

Note: You can select any combination of databases, tables, or columns to be hidden. However, becausenormalized child tables have a foreign key relationship to a parent table, child tables must be hidden beforetheir parent tables.



Note: You can select consecutive objects by selecting an object, holding down the Shift key, and thenselecting the last object.You can select non-consecutive objects by holding down the Crtl key and thenselecting the objects you want to hide.

3. Once you have selected the object(s), you can hide the object(s) in either of the following ways:

• Click the Remove Object(s) button above the Available Schemas pane.

• Right-click your selected object(s) and select Remove Object(s).

4. Click the button or select File>Save to save the modified schema.

The object is removed from your schema and is no longer visible to your application. When parent objects areremoved, their children are also hidden. If your application attempts to access any removed object, the driverwill return an error.

See alsoMapping Native Objects in a Schema on page 112Removing Columns on page 122

Removing ColumnsWhen you remove a column from a table, you are hiding it from the relational view of your data.You can removecolumns directly from the Column Information pane in either the main display or the Schema Tool Native View.

Note: You can hide or remove objects, including columns, from your relational schema in other ways. See"Removing Objects from a Schema" for details.

Note: Primary key columns cannot be removed from the relational view. To remove the column currentlymarked as the primary key, you must designate a new primary key before beginning this procedure. For moreinformation, see "Designating a Primary Key."

1. Navigate to the main display.You can access the Column Information pane in one of the following ways:

• If you want to remove columns for an existing table, click the table of the column you want to remove.

• If you want to remove columns when extracting a new table, right-click on a table you want to add toyour schema under a new name, and select Extract New Table. See "Extracting a New Table" forgeneral information on extracting tables.

2. Under Column Information, select the column you want to remove and click the Remove Column button

.

3. Click the Save button or select File>Save to save the modified schema.

See alsoRemoving Objects from a Schema on page 121Designating a Primary Key on page 124Extracting a New Table on page 119



Defining ColumnsYour native data source may not enforce consistent data types. Therefore, you may need to define columndata types to ensure data integrity as you build a relational map of your data. The DataDirect Schema Toolallows you to define a schema by letting you define column data types and specify the order in which columnsappear.

Note: The Schema Tool provides basic information about your data that will help you design schemas thatsuit your needs. For details, see "Viewing Information and Statistics" and "About Column Information andStatistics."

The following steps illustrate how you can define columns and specify the order of columns through the ClientInformation pane.

1. Navigate to the main display.You can access the Column Information pane in one of the following ways:

• If you want to define columns for an existing table, click the table that contains the columns you want todefine.

• If you want to define columns when extracting a new table, right-click on a table you want to add to yourschema under a new name, and select Extract New Table. See "Extracting a New Table" for generalinformation on extracting tables.

This is a view of the Column Information pane from the main display.

2. To change a column's name, double-click the Mapped Name field and enter the new name for the column.



3. To change a column's data type, click the column's SQL Type field and select an alternative data type fromthe drop-down list.

4. To change the size or length of applicable data types, double-click the column's VARCHAR Size field andenter the desired value.

5. To reorder columns, select the column you would like to reposition. Use the up and down arrows to movethe selected column left or right in the table.

Note: By default, columns are ordered left to right in the order in which they are discovered by the SchemaTool.

6. Save your changes from the main display. Click the Save button or select File>Save to save the modifiedschema.

See alsoViewing Information and Statistics on page 107About Column Information and Statistics on page 110Extracting a New Table on page 119

Designating a Primary KeyThe Schema Tool allows you to designate the primary key column for your relational table view. By default,the primary key is set to the _ID column, which contains identifiers generated by your database that are usedto define rows. Although the _ID column typically provides a set of unique row identifiers that work seamlesslywith your application, you may want to designate a different primary key depending on your server configurationor the conceptual design of your data.

If you connect to a shard server that does not use the _ID field as the shard key, you must designate a newprimary key to ensure accurate joins on reads and avoid damaging data on writes. See your databasedocumentation for details on shard keys.

Based on the conceptual design of your data, you may prefer to designate a user-generated column as yourprimary key. User generated columns consist of data provided by users that may have significance externalto the database, such as order numbers or employee identification numbers. When designated as the primarykey, these columns can provide a real world association between your data and your identifiers, which maybetter complement the design of your data and your operational needs. Designating a new primary key allowsyou to further tailor the relational view to match your data concepts by permitting you to hide the _ID columnfrom relational tables. In the default settings, the Schema Tool prohibits hiding the _ID column because it isdesignated as the primary key. See "Removing Columns" for additional information.

Caution: If you designate a primary key column other than _id in the Schema Tool, verify that all values inthe column are unique when fetched as the mapped SQL type of the column before disabling the Read Onlyconnection option. Executing write operations against data with duplicate primary keys can produce undesiredresults. It is also critical that all values of the primary key column are able to be represented as the SQL typeto which the column is mapped without any conversion errors or loss of precision. When conversion errorsoccur, the driver converts incompatible values to null, creating the potential for duplicate identifiers of null.

To designate a primary key:

1. Navigate to the main display.



2. In the Available Schemas pane, expand the tree to display your parent table's columns.

3. Right click on the column that you want to designate as your new primary key; then, select Mark As PrimaryKey.

Note: Columns mapped from complex data types, such as arrays and objects, cannot be designated asthe primary key.

The icon for the column you selected will change to the ID icon , indicating that it is now the primarykey. In a normalized view, foreign key columns will automatically be updated and renamed to reflect thenew primary key.

4. Save your changes from the main display. Click the Save button or select File>Save to save the modifiedschema.

See alsoRemoving Columns on page 122



Naming ConflictsWhen you generate a relational schema with the Schema Tool, the driver exposes native objects as unquoted,uppercase identifiers by default. Since native objects are case sensitive in MongoDB, the driver avoids namingconflicts by appending identifiers which have the same name but different cases with an underscore separatorand integer (for example, _1). If one of the conflicting names contains only uppercase characters, that namewill remain unaltered. For example, if the collections Test, TEST, and test exist in the native data, the driverwill expose the collections as tables in the following manner:

Table 11: Name Conflict Resolution Example

Table NameCollection Name

TEST_1Test

TESTTEST

TEST_2test

Note: When you initially connect to your native data with the Schema Tool, a warning message will appear ifthe driver detects any naming conflicts. This message will not appear in subsequent connections unless anaming conflict has been introduced into the native data.

Alternatively, you can use UppercaseIdentifiers to retain the names of native objects in the relational view ofyour data. When UppercaseIdentifiers is set to false, the driver maps the names of native objects as quotedidentifiers, maintaining the case of native object names in the relational view of native data. For details, see"Using Identifiers" and "ConfigOptions" in the driver documentation.

The remaining topics in this section discuss two specific naming conflict scenarios.

See alsoStarting the Schema Tool on page 83

Restarting the Wizard

If you want to reset the relational view of your schema definition, you can do so by restarting the wizard.Restarting the wizard overwrites your existing relational view, including customizations, and allows you toreselect the initial relational view of your data.

Note that restarting the wizard only resets how native objects map to the relational view. Therefore, afterrestarting, your schema definition will continue to use the existing file name and connection settings, includingsecurity and configuration option settings.

To restart the wizard, click the restart button or select File>Restart the Wizard from the Table Wizardwindow. Then follow the instructions in "Creating a Schema with the Table Wizard" to create a new relationalview of your data.

See alsoCreating a Schema with the Table Wizard on page 99



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.

Encryption Method (EncryptionMethod): Data encryption may adversely affect performance because of theadditional overhead (mainly CPU usage) that is required to encrypt and decrypt data.

Fetch Size (FetchSize): Fetch Size can be used to adjust the trade-off between throughput and responsetime. In general, setting larger values for Fetch Size will improve throughput, but can slow the response time.For example, if an application attempts to fetch 100,000 rows from the data source and Fetch Size is set to500, the driver must make 200 round trips across the network to get the 100,000 rows. If, however, Fetch Sizeis set to 2000, the driver only needs to make 50 trips to retrieve 100,000 rows. Network round trips are expensive,so generally, minimizing the network round trips increases throughput. For many applications, throughput isthe primary performance measure, but for interactive applications, such as Web applications, response time(how fast the first set of data is returned) is more important than throughput. By specifying smaller values, youcan improve response time, as there is less of a delay waiting for the server to transmit data.

Note: Fetch Size provides a suggestion to the driver as to the number of rows that should be returned to theapplication. The driver may fetch fewer rows to conserve memory when processing exceptionally wide rows.

JVM Arguments (JVMArgs): Used in conjunction with the Result Memory Size connection option, you canaddress memory and performance concerns by adjusting the max Java heap size using the JVM Argumentsconnection option. By increasing the max Java heap size, you increase the amount of data the driver accumulatesin memory. This can reduce the likelihood of out-of-memory errors and improve performance by ensuring thatresult sets fit easily within the JVM's free heap space. In addition, when a limit is imposed by setting ResultMemory Size to -1 or x, increasing the max Java heap size can improve performance by reducing the needto write to disk, or removing it altogether.

Read Preference (ReadPreference): This connection option allows you to specify your preference for whichreplica set members are read when executing queries. Executing queries against primary members (read-writeserver nodes) returns the most recent version of the data, but increases the workload of the primary membersand may negatively affect performance. If your application does not require the most recent version of data,consider setting this connection option to read from secondary members (read-only server nodes) to improveperformance.

Result Memory Size (ResultMemorySize): Since Result Memory Size specifies the maximum size of anintermediate result set that the driver holds in memory, it can affect performance in two ways. First, if the valueof the result set is larger than the value specified for Result Memory Size, the driver writes a portion of theresult set to disk. Since writing to disk is an expensive operation, performance losses will be incurred. Second,when you remove any limit on the size of an intermediate result set by setting Result Memory Size to 0, youcan realize performance gains for result sets that easily fit within the JVM's free heap space. However, thesame setting can diminish performance for result sets that barely fit within the JVM's free heap space.


Performance Considerations

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

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.



https://documentation.progress.com/output/DataDirect/securitymatrix/

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

Using Security with the Schema Tool

The Schema Tool supports the SSL encryption security feature, which converts data into a form that cannotbe easily understood by unauthorized users. For more information on the SSL Encryption feature, see "SSLEncryption."

When creating or opening a schema definition, the Schema Tool accesses data from the server for the purposeof object mapping and generating column statistics.This process requires data to be transferred over networks,which can make data vulnerable to interception by unauthorized parties. If your data contains sensitiveinformation, you should consider enabling SSL encryption to provide a more secure transmission of data.

To enable SSL encryption, you must specify the appropriate values for security-related options. Configuringthese options for the Schema Tool requires using different processes for the Windows and Unix/Linux versionsof the product. See the following sections for information about configuring security on the Schema Tool foryour platform. For a list of security-related options, see "Summary of Security-Related Options."

See alsoSSL Encryption on page 128Summary of Security-Related Options on page 130

Configuring Security for the Schema Tool on WindowsTo configure security for the Schema Tool, specify values for the connection options on the Security tab of thedriver setup dialog when configuring a data source. Note that the values provided will determine the behaviorfor both the Schema Tool and the driver. For more information on configuring a data source, see "Configuringthe Product on Windows."

See alsoConfiguring the Product on Windows on page 69

Configuring Security for the Schema Tool on UNIX/LinuxTo configure the security feature, specify values for the security-related options when creating a schemadefinition with the Schema Tool. Values for these options can be specified as attribute-value pairs in theConnection Option field of the Open Schema Definition window. See "Starting the Schema Tool on UNIX/Linux"for detailed instructions. For a list of security related options, see "Summary of Security-Related Options."

Configuring security options for the Schema Tool will not affect the behavior of the driver. To fully enable thesecurity for the product, you must configure security for the driver and the Schema Tool independently. See"Configuring the Product on UNIX/Linux" for instructions on configuring the driver.

See alsoStarting the Schema Tool on UNIX/Linux on page 83Summary of Security-Related Options on page 130Configuring the Product on UNIX/Linux on page 60

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

The method used to encrypt data sent between the driver or Schema Tool andthe database server.

For the driver: 0 | 1

For the Schema Tool: noEncryption | SSL

If set to 0 (No Encryption) or noEncryption, data is not encrypted.

If set to 1 (SSL) or SSL, data is encrypted using SSL. If the server is notconfigured for SSL, the connection fails.

Default:

For the driver: 0 (No Encryption)

For the Schema Tool: noEncryption

Encryption Method(EncryptionMethod)

A host name for certificate validation when SSL encryption is enabled(Encryption Method=1) and validation is enabled (Validate ServerCertificate=1).

Default: None

Host Name In Certificate(HostNameInCertificate)

The password required to access an individual key in the keystore.

Default: None

Key Password(KeyPassword)

The absolute path and file name that specifies the location of the keystore file.

Default: None

Key Store (Keystore)

The password required to access the keystore.

Default: None

Key Store Password(KeystorePassword)

The absolute path and file name that specifies the location of the truststore file.

Default: None

Trust Store (Truststore)

The password required to access the truststore.

Default: None

Trust Store Password(TruststorePassword)


Using Security

DescriptionOption

The default user ID used to connect to your database.

Default: None

User Name (LogonID)

Determines whether the driver and/or Schema Tool validates the certificate thatis sent by the database server when SSL encryption is enabled.

For the driver: 0 | 1

For the Schema Tool: true | false

If set to 1 or true (Enabled), the driver or Schema Tool validates the certificatethat is sent by the database server.

If set to 0 or false (Disabled), the driver or Schema Tool does not validate thecertificate that is sent by the database server. The driver and/or Schema Toolignores any truststore information specified by the Trust Store and Trust StorePassword options.

Default:

For the driver: 1 (Enabled)

For the Schema Tool: true (Enabled)

Validate Server Certificate(ValidateServerCertificate)


Using IdentifiersIdentifiers are used to refer to objects exposed by the driver, such as tables and columns. The driver supportsboth quoted and unquoted identifiers for naming objects. The maximum length of both quoted and unquotedidentifiers is 128 characters. Quoted identifiers must be enclosed in double quotation marks (""). A quotedidentifier can contain any Unicode character, including the space character, and is case-sensitive. The driverrecognizes the Unicode escape sequence \uxxxx as a Unicode character.You can specify a double quotationmark in a quoted identifier by escaping it with a double quotation mark. Unquoted identifiers must start with anASCII alpha character and can be followed by zero or more ASCII alpha or numeric characters.

By default, the driver exposes native objects as unquoted, uppercase identifiers when creating the relationalschema of your native data. Since native objects are case sensitive in MongoDB, the driver avoids namingconflicts by appending identifiers which have the same name but different cases with an underscore separatorand integer (for example, _1). If one of the conflicting names contains only uppercase characters, that namewill remain unaltered. For example, if the collections Test, TEST, and test are found, the driver will exposethe collections as tables in the following manner:



Table 13: Name Conflict Resolution Example

Table NameCollection Name

TEST_1Test

TESTTEST

TEST_2test

Note: When you initially connect to your native data with the Schema Tool, a warning message will appear ifthe driver detects any naming conflicts. This message will not appear in subsequent connections unless anaming conflict has been introduced into the native data.

The driver allows you to change default behavior related to identifiers and manage identifiers directly throughthe use of the configuration options described in the following sections.

UppercaseIdentifiers OptionThe UppercaseIdentifiers configuration option determines whether native objects are mapped as unquoted,uppercase identifiers (the default) or quoted, mixed case identifiers that correspond directly with native objectnames. Therefore, as an alternative to the driver's default behavior, you can use UppercaseIdentifiers to retainthe names of native objects in the relational view of your data. When UppercaseIdentifiers is set to false, thedriver maps the names of native objects as quoted identifiers, maintaining the case of native object names inthe relational view of native data. If these identifiers are called in a SQL statement, the statement must enclosethe identifiers in double quotation marks and they must exactly match the case of the identifier name. Forexample, when UppercaseIdentifiers=false, you would use the following statement to query the Accounttable:

SELECT "id", "name" FROM "Account"

The setting for UppercaseIdentifiers also affects the use of catalog functions. When object names are passedas arguments to catalog functions, the case of the value must match the case of the name in the database. IfUppercaseIdentifiers=true (the default) when the schema definition was created, the value passed tothe catalog function must be uppercase because unquoted identifiers are automatically converted to uppercaseby the driver. If UppercaseIdentifiers=false when the schema definition was created, the value passedto the catalog function must match the case of the name as it was defined. In addition, whenUppercaseIdentifiers=false, object names in results returned from catalog functions are returned inthe case that they are stored in the database.

KeywordConflictSuffix OptionYou can use the KeywordConflictSuffix configuration option to avoid naming conflicts when the name of anobject corresponds to the name of a SQL engine keyword. KeywordConflictSuffix specifies a string of up tofive alphanumeric characters that the driver appends to any object or field name that conflicts with a SQLengine keyword. For example, if you specify KeywordConflictSuffix=TAB, the driver maps the Caseobject to CASETAB.

LeadingUnderscoreReplacement OptionThe LeadingUnderscoreReplacement configuration option allows you to replace leading underscores with astring when leading underscores are used in identifiers for collections and fields. For example, MongoDBcollections automatically include the _id field. By specifying LeadingUnderscoreReplacement=XX, the _idfield becomes the XXID column in the relational view of the data. In addition, any other fields or collectionswith a leading underscore would be modified in the same manner.


Using Identifiers

See alsoConfig Options on page 157Starting the Schema Tool on page 83Naming Conflicts on page 126

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

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 MongoDB SQL Engine Service Setup dialog box. Use thisdialog box to define settings for Server Mode and to start and stop the Progress DataDirect MongoDB 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 19931 for 64-bit installations and 19932 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.

Server DB Directory: This option does not currently apply to MongoDB.

Services: Shows the MongoDB ODBC SQL engine service that runs as a separate process instead of beingloaded within the process of an ODBC application.

Start (Stop): Starts or stops the MongoDB service. A message window is displayed, confirming that theMongoDB 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.


Configuring the SQL Engine Server

See alsoJVM Arguments on page 176JVM Classpath on page 177Server Port Number on page 189

Starting the SQL Engine Server

In 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 mongodb.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:


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.


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.


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 MongoDB Driver Setup dialog box, select the SQL Engine tab; then, select 0 - Auto or1- 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 directmode if server mode is unavailable. When set to 1 - Server, the SQL engine mode runs exclusively inserver mode.

4. Click Edit Server Settings.

5. When you complete your changes, click Apply.

6. Verify that Progress DataDirect MongoDB 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 MongoDB 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 MongoDB SQL Engine Service Setupdialog box.

Stopping the SQL Engine Server

To stop the SQL engine server:

1. Open the ODBC MongoDB 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 ServerSettings.

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 inserver mode.

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 MongoDB SQL Engine Service Setup dialog box.

Configuring Java Logging for the SQL Engine Server

Java logging can be configured by placing a logging configuration file named ddlog.properties in theServer DB directory (see "Configuring Server Mode" for information on configuring Server DB Directory). Thesimple way to create one of these is to make a copy of the ddlog.properties file, which is located in yourdriver installation directory, in the install_dir/Sample/Example subdirectory. For more information onlogging in MongoDB, see "Configuring Logging."

See alsoConfiguring Server Mode on page 134Configuring Logging on page 145


Configuring the SQL Engine Server



6Troubleshooting

This part guides you through troubleshooting your Progress DataDirect for ODBC for MongoDB driver. It providesyou with 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 140

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 6: 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 either so or sl. For example, ivtrc28.sois the 32-bit version of the library. To use a custom shared library instead, enter the path and nameof the library 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 Solaris, where xx represents the version number of the driver:






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

See alsoEnvironment Variables on page 60Version String Information on page 49

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 driver for MongoDB provides a flexible and comprehensive logging mechanism of its Java componentsthat allows 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 MongoDB-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 145 for details.

• Using the driver. See Using the Driver on page 146 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 MongoDB connections.

• Use a different properties file for each schema definition. For example, if you have two definitions(johnsmith.xxx and pattijohnson.xxx, for example), you can load one properties file for the johnsmith.xxxdatabase and load another properties file for the pattijohnson.xxx database.

Note: By default, the name of the schema definition is the user ID specified for the connection.You can specifythe name of the schema definition using the SchemaDefinition attribute. See "Connection Option Descriptions"for details on using LogConfigFile and other connection options.

By default, the driver looks for the file named ddlogging.properties in the current working directory to load forall MongoDB connections. If the SQLEngineMode connection option is set to Server, the driver uses theddlogging.properties file that is specified by the Server DB Directory 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 146, it looks for a properties file nameddatabase_name.logging.properties in the directory containing the embedded database for the connection,where database_name is the name of the embedded database.

3. If the driver cannot find the file in Step 2 on page 146, 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 146, 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 embedded database directory, and modify it using a text editor for yourneeds.


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 MongoDB driver would look like this:

[DataDirect] [MongoDB 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 MongoDB database:

[DataDirect] [MongoDB ODBC Driver] [MongoDB] Specified length too long for CHAR column

This type of error is generated by the database system. Check your MongoDB 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 MongoDB require that you set the library path environment for youroperating system to the directory containing your 32-bit JVM’s libjvm.so [sl | 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[sl].

The library path environment variable is:

32-bit Drivers

• PATH on Windows

• LD_LIBRARY_PATH on Solaris, Linux and HP-UX Itanium

• SHLIB_PATH on HP-UX PA_RISC

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


Troubleshooting

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.

See alsoData Source Configuration on UNIX/Linux on page 63Connection Option Descriptions on page 153Configuring the Product on UNIX/Linux on page 60The Test Loading Tool on page 142

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 29

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 143The Example Application on page 146ODBC Trace on page 139

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 253

Out-of-Memory Issues

When processing large sets of data, out-of-memory errors can occur when the size of an intermediate resultexceeds the available memory allocated to the JVM. If you are encountering these errors, you can tune theFetch Size, Result Memory Size, and JVM Arguments connection options to fit your environment:

• Reduce Fetch Size to reduce demands on the driver's internal memory. By lowering the maximum numberof rows as specified by Fetch Size, you lower the number of rows the driver is required to process beforereturning data to the application. Thus, you reduce demands on the driver's internal memory, and, in turn,decrease the likelihood of out-of-memory errors.

• To tune Result Memory Size, decrease the value specified until results are successfully returned. Intermediateresults larger than the specified setting will be written to disk as opposed to held in memory.When configuredcorrectly, this avoids memory limitations by not relying on memory to process larger intermediate results.Be aware that while writing to disk reduces the risk of out-of-memory errors, it also negatively impactsperformance. For optimal performance, decrease this value only to a size necessary to avoid errors.

Note: By default, Result Memory Size is set to -1, which sets the maximum size of intermediate resultsheld in memory to a percentage of the max Java heap size. If you received errors using the defaultconfiguration, use the max Java heap size divided by 4 as a starting point when tuning this option.

• Increase the JVM heap size using the JVM Arguments connection option. By increasing the max Java heapsize, you increase the amount of data the driver can accumulate in memory and avoid out-of-memory errors.

See "Fetch Size", "Result Memory Size", and "JVM Arguments" for additional information.


Troubleshooting

See alsoFetch Size on page 171Result Memory Size on page 186JVM Arguments on page 176



7Connection 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. For example:

Application Using Threads

Attribute

ApplicationUsingThreads (AUT)

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 driver for MongoDB.

Table 14: MongoDB Attribute Names

DefaultAttribute (Short Name)

1 (Enabled)ApplicationUsingThreads (AUT)

Empty StringConfigOptions (CO)

2 (NotExist)CreateDB (CDB)

NoneDataSourceName (DSN)



INFORMATION_SCHEMADatabase (DB)

NoneDescription (n/a)

0 (No Encryption)EncryptionMethod (EM)

100FetchSize (FS)

NoneHostName (HOST)

NoneHostNameInCertificate (HNIC)

4 (ISO 8559-1 Latin-1)IANAAppCodePage (IACP) (UNIX and Linux only)

NoneInitializationString (IS)

For the 32-bit driver when the SQL Engine Mode is set to2 (Direct):

-Xmx256m

For all other configurations:

-Xmx1024m

JVMArgs (JVMA)

The default is an empty string, which means that the driverautomatically detects the CLASSPATHs for all ODBCdrivers installed on your machine and specifies them whenlaunching the JVM.

JVMClasspath (JVMC)

NoneKeyPassword (KP)

NoneKeystore (KS)

NoneKeystorePassword (KSP)

NoneLogConfigFile (LCF)

15LoginTimeout (LT)

NoneLogonID (UID)

NoneMinLongVarcharSize (MINLVS)

NonePassword (PWD)

27017PortNumber (PORT)

1 (Enabled)ReadOnly (RO)

primaryReadPreference (RP)


Chapter 7: Connection Option Descriptions


0 (Ignore Errors)ReportCodepageConversionErrors (RCCE)

-1ResultMemorySize (RMS)

For Windows:


For UNIX/Linux:

~/progress/datadirect/mongodb_schema/hostname.config

SchemaDefinition (SD)

For the 32-bit driver:

19932


19931

ServerPortNumber (SPN)

For Windows:

0 (Auto)

For UNIX/Linux:

2 (Direct)

SQLEngineMode (SEM)

0 (No Transactions)TransactionMode (TM)

NoneTruststore (TS)

NoneTruststorePassword (TSP)

1 (Enabled)ValidateServerCertificate (VSC)

NoneVarcharThreshold (VT)


• Application Using Threads

• Config Options

• Create Database

• Data Source Name

• Database

• Description

• Encryption Method

• Fetch Size


• Host Name

• Host Name In Certificate

• IANAAppCodePage

• Initialization String

• JVM Arguments

• JVM Classpath

• Key Password

• Key Store

• Key Store Password

• Log Config File

• Login Timeout

• Min Long Varchar Size

• Password

• Port Number

• Read Only

• Read Preference

• Report Codepage Conversion Errors

• Result Memory Size

• Schema Definition

• Server Port Number

• SQL Engine Mode

• Transaction Mode

• Trust Store

• Trust Store Password

• User Name

• Validate Server Certificate

• Varchar Threshold

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 127

Config Options

AttributeConfigOptions (CO)

PurposeDetermines how the mapping of the native 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:


Config Options

key

is one of the following values:

• columnDiscoverySampleSize

• DefaultVarcharSize

• KeywordConflictSuffix

• LeadingUnderscoreReplacement

• MaxVarcharSize

• MinVarcharSize

• SchemaFilter

• UppercaseIdentifiers

The value is a set of key value pairs separated by a semicolon (;).The value must be enclosed in curly brackets.For example:

{columnDiscoverySampleSize=2000;DefaultVarcharSize=2x;KeywordConflictSuffix=TAB;LeadingUnderscoreReplacement=XX;MaxVarcharSize=5000;MinVarcharSize=500;SchemaFilter=oem_sales:november;UppercaseIdentifiers=false}

See the following sections for description of these options and their values.

Default

{columnDiscoverySampleSize=1000;DefaultVarcharSize=1.5x;KeywordConflictSuffix=;LeadingUnderscoreReplacement=_;MaxVarcharSize=4000;MinVarcharSize=255;SchemaFilter=;UppercaseIdentifiers=true}

GUI TabAdvanced tab

See Also

• columnDiscoverySampleSize (Config Option) on page 158

• DefaultVarcharSize (Config Option) on page 159

• KeywordConflictSuffix (Config Option) on page 161

• LeadingUnderscoreReplacement (Config Option) on page 162

• MaxVarcharSize (Config Option) on page 163

• MinVarcharSize (Config Option) on page 164

• SchemaFilter (Config Option) on page 165

• UppercaseIdentifiers (Config Option) on page 167

columnDiscoverySampleSize (Config Option)

AttributecolumnDiscoverySampleSize



PurposeSpecifies the number of rows the driver fetches per collection when sampling data to detect columns and gathercolumn statistics. The information collected in these samples is used when defining a schema definition withthe DataDirect Schema Tool. Larger fetch sizes return samples that are more representative of your data, butat the expense of slower performance.

Valid Valuesx

where:

x

The number of rows the driver fetches per collection.

The value for this option is specified as a key=value pair in the Config Options field. See "Config Options" fordetails.

Default1000

GUI TabFor Windows:

The value for config options are specified in the Config Options field on the Advanced tab.

For UNIX/Linux:

The value for config options are specified in the Config Options field on the Schema Tool. For details, see"Starting the Schema Tool UNIX/Linux."

See also

• Config Options on page 157

• Starting the Schema Tool on UNIX/Linux on page 83

DefaultVarcharSize (Config Option)

AttributeDefaultVarcharSize

PurposeDetermines the default length of fields that are mapped as VARCHAR.

Valid Valueslength | multiplier

where:

length

is the default length in characters given to columns that are discovered and mapped as VARCHAR.


Config Options

multiplier

is a positive number immediately followed by the character x. For example, 3x. The positive integeris multiplied by the size of the largest object detected in a column to determine the default VARCHARlength for that column.

The value for this option is specified as a key=value pair in the Config Options field. See "Config Options"for details.

BehaviorIf set to length, the value specified is the default length in characters for the all fields that are discovered andmapped as VARCHAR. Values that exceed the specified default length are truncated when selected via thedriver.

If set to multiplier, the default length for a VARCHAR column is defined by multiplying the multipliervalue by the size, in characters, of the largest value detected in that column. Values that exceed the defaultlength defined for the column are truncated when selected via the driver.

Note: When specifying a multiplier, you can define the maximum and minimum limits of the default lengthgenerated with the MaxVarcharSize and MinVarcharSize config options.

ExampleFor character values:

When DefaultVarcharSize is set to 2000 and the largest detected field in a column is less than or equal to2000 characters, String is mapped as VARCHAR and the precision is 2000 characters. When a VARCHARfield with a size greater than 2000 characters is discovered, the driver truncates the value to 2000 characters.

For multiplier values:

When DefaultVarcharSize is set to 1.5x and the largest detected field in a column is 2000 characters, thedefault length of fields mapped to VARCHAR is determined by multiplying 1.5 by 2000, which results in a defaultlength of 3000 characters. When a value in that column exceeds 3000 characters, the driver truncates thevalue to 3000 characters.

Notes

• We recommend specifying a multiplier value for this option. Specifying a multiplier can improve memoryefficiency within the driver and the ODBC application by having the length for every VARCHAR columnproportionate to the size of the data for a given column.

• When a column with a String size greater than 4000 is discovered, the column is mapped as LONGVARCHARand precision is 16 MB.

• The default length of fields for columns mapped as VARCHAR can be overridden using the Schema Tool.See "About Column Information and Statistics" for details.

• DefaultVarcharSize is not applied to columns that contain only ObjectIDs. Columns that contain onlyObjectIDs are mapped as VARCHAR.

Default1.5x

GUI TabFor Windows:




For UNIX/Linux:

The value for config options are specified in the Config Options field on the Schema Tool. For details, see"Starting the Schema Tool on UNIX/Linux."

See also


• MaxVarcharSize (Config Option) on page 163


• About Column Information and Statistics on page 110

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



ExampleA field called CASE exists in the native MongoDB 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.

DefaultNone

GUI TabFor Windows:


For UNIX/Linux:


See also



Config Options


LeadingUnderscoreReplacement (Config Option)

AttributeLeadingUnderscoreReplacement

PurposeSpecifies the string of characters that replace leading underscores used in identifiers for collections, documents,and arrays.

Valid Valuesstring

where:

string

is comprised of any Unicode character or group of characters, including spaces.

For example, MongoDB collections automatically include the _id field. By specifyingLeadingUnderscoreReplacement=XX, the _id field becomes the XXID column in the relational view of thedata.

The value for this config option is specified as a key=value pair in the Config Options field. See "Config Options"for details.

Notes

• The Table Wizard builds table and column identifiers by concatenating the names of nested collections,documents, and arrays. When specifying a value for LeadingUnderscoreReplacement, consider that thetotal length of identifiers must not exceed 128 characters in length.

DefaultNone. When no value is specified, a leading underscore is used in identifiers.

GUI TabFor Windows:


For UNIX/Linux:


See also





MaxVarcharSize (Config Option)

AttributeMaxVarcharSize

PurposeSpecifies the maximum default length of fields that are mapped as VARCHAR when a multiplier is specifiedfor the DefaultVarcharSize config option (DefaultVarcharSize=multiplier).

MaxVarcharSize limits the size of the default length of VARCHAR fields that are determined by multiplying themultiplier value of the DefaultVarcharSize config option by the largest value detected in that column. When thelargest value detected is significantly larger than the rest of the data in the column, this option can improve thememory efficiency of applications by limiting the size of the default length and, therefore, the amount of datastored in a field.

Valid Valuesx

where:

x

is the maximum size of the default length in characters given to columns that are mapped asVARCHAR.


ExampleFor example, MaxVarcharSize is set to 3000 and DefaultVarcharSize is set to 3x. When the largest detectedvalue in a column mapped to VARCHAR is 500 characters, the driver determines that the default length forthat column is 1500 characters by multiplying the largest detected value (500) by the setting ofDefaultVarcharSize (3). However, suppose the largest detected value is 2000 characters. The driver calculatesa default value of 6000 characters, but, since this would exceed the value for MaxVarcharSize, the defaultlength is set to 3000 characters.

Notes

• This option can improve memory efficiency of applications by limiting the size of memory stored in VARCHARfields.

• When a column with a String size greater than 4000 is discovered, the column is mapped as LONGVARCHARand precision is 16 MB.

• You can configure a minimum limit for the default length of fields that are mapped as VARCHAR using theMinVarcharSize config option.


Default4000


Config Options

GUI TabFor Windows:


For UNIX/Linux:


See also





• #unique_206

MinVarcharSize (Config Option)

AttributeMinVarcharSize

PurposeSpecifies the minimum default length, in characters, of fields that are mapped as VARCHAR when a multipliervalue is specified for the DefaultVarcharSize config option (DefaultVarcharSize=multiplier).

MinVarcharSize enforces a minimum size for the default length of VARCHAR fields that are determined bymultiplying the value of the DefaultVarcharSize config option by the largest value detected in that column.When the default length would be less than the minimum value specified for this option, the driver increasesthe default length to the minimum. When correctly configured, this option can prevent the undesired truncationof VARCHAR values.

Valid Valuesx

where:

x

is the maximum size of the default length in characters given to columns that are mapped asVARCHAR.




ExampleFor example, MinVarcharSize is set to 1000 and DefaultVarcharSize is set to 3x. When the largest detectedvalue in a column mapped to VARCHAR is 1000 characters, the driver determines that the default length forthat column is 3000 characters by multiplying the size of the largest detected value (1000) by the setting ofDefaultVarcharSize (3). However, suppose the largest detected value is 200 characters. The driver calculatesa default length of 600 characters, but, since this would be less than the setting for MinVarcharSize, the lengthis set to 1000.

Notes

• This option can be configured to avoid the undesired truncation of values by enforcing a minimum size offields that are mapped as VARCHAR.

• You can configure a maximum limit for the default length of fields that are mapped as VARCHAR using theMaxVarcharSize config option.


Default255

GUI TabFor Windows:


For UNIX/Linux:


See also






SchemaFilter (Config Option)

AttributeSchemaFilter

PurposeSpecifies a comma-separated list of database and collection pairs for which you want the driver to fetchmetadata. SchemaFilter can significantly improve connection times by limiting the collections for which metadatais fetched to only those that are required by your application. If you do not specify a value, the driver fetchesmetadata for all the collections in every database that your account has access to, which can adversely impactperformance during the initial connection to a database.


Config Options

Valid Valuesdatabase_name:collection_name[[,database_name:collection_name]...]

where:

database_name

is a literal value or regular expression for the database that contains collections for which the driverfetches metadata.

collection_name

is a literal value or regular expression of the collection for which the driver fetches metadata.

A schema or table name value can be:

• A literal name that does not contain either a comma ( , ) or a colon ( : )

• A literal name that contains a comma ( , ) or a colon ( : ) that is bounded by a slash ( / ) at the beginningand end. For example, a collection named sales:2019 would be represented by /sales:2019/

• A regular expression bounded by a slash ( / ) at the beginning and end, such as /sales.*\d/

• An asterisk ( * ), which represents all databases or collections within the corresponding schema(s).

The value for this config option is specified as a key=value pair in the Config Options field. See "Config Options"for details.

Examples

• Literal values: The following example returns metadata for only the november and march collections inthe oem_sales database.

SchemaFilter=oem_sales:november,oem_sales:march

• Wildcard values: If you want the driver to fetch metadata for all the tables in a schema, replace the valuefor the table or schema name with an * (wildcard) character. For example, the following returns metadatafor all the tables in the oem_sales and for tables named customers in all databases.

SchemaFilter=oem_sales:*,*:customers

• Partial wildcard values:You can also use the asterisk to specify partial values for databases and collections.For example, the following returns metadata for all tables in the that end with region that are in schemasthat begin with sales.

SchemaFilter=/sales.*/:/.*region/

• Regular expressions: The following returns metadata for tables named tax in all databases that start withyear which end with a number.

SchemaFilter=*/year.*\d/:tax

DefaultNone

GUI TabFor Windows:




For UNIX/Linux:


See also



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 "id", "name" FROM "Account"

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

GUI TabFor Windows:


For UNIX/Linux:


Config Options

The value for config options are specified in the Config Options field on the Schema Tool. For details, see"Starting the Schema Tool UNIX/Linux."

See also



Create Database

AttributeCreateDB (CDB)

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

Valid Values0 | 2

BehaviorIf set to 0 (No), the driver uses the current group of internal files specified by the Schema Definition connectionoption. If the files do not exist, the connection fails.

If set to 2 (NotExist), the driver uses the current group of files specified by Schema Definition connection option.If the files do not exist, the driver creates them.

Notes

• The internal files share the same directory as the schem definition's configuration file. This directory isspecified by the value you enter for the Schema Definition Connection Option.

• You can refresh the internal files related to an existing relational view of your data in one of two ways. First,you can use the SQL extensions Refresh Map or Reload Map. Refresh Map runs a discover against yournative data and updates your internal files accordingly, while Reload Map refreshes the internal files tointegrate configuration changes without running a discovery. Second, you can refresh these internal filesby launching the DataDirect Schema Tool and opening the corresponding schema definition configurationfile. When an existing schema is opened with the Schema Tool, the Schema Tool automatically comparesthe content of the schema configuration file to a snapshot of the data on the wire. When new native objectsare detected, the Schema Tool displays the newly detected objects by highlighting them in a hierarchicalview of the native data.

Default2 (NotExist)

GUI TabAdvanced tab



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

PurposeSpecifies the name of the database to which you want to connect.This value is also used as the default qualifierfor unqualified table names in queries.

Valid Valuesdatabase_name

where:

database_name

is the name of a valid database. If you do not specify a value, the default is the database defined bythe system administrator for each user.

Important: This value is case-insensitive if you have access privileges to query the list of databases on theserver. If you do not have access, this value is case-sensitive.


Data Source Name

Notes

• This option is required if your server requires authentication.

DefaultINFORMATION_SCHEMA

GUI TabGeneral tab

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

Encryption Method

AttributeEncryptionMethod (EM)

PurposeThe method used to encrypt data sent between the driver or Schema Tool and the database server.



For Windows platforms, the values specified for security-related options when creating a data sourcedetermine the behavior of both the driver and the Schema Tool.

To fully enable SSL on UNIX and Linux platforms, you must specify values for security-relatedoptions separately for the driver and the Schema Tool. For the driver, these values are specified in the datasource or connection string used to configure the driver. For the Schema Tool, these values are specified whencreating a schema definition with the Table Wizard. See "Using Security with the Schema Tool" for details.

In addition, the driver and Schema Tool use a different set of valid values when configuring the EncryptionMethodoption. The valid values and behavior for both components are listed in the following sections.

Valid ValuesFor the driver:

0 | 1

For the Schema Tool (UNIX and Linux Only):

noEncryption | SSL

BehaviorIf set to 0 (No Encryption) or noEncryption , data is not encrypted.

If set to 1 (SSL) or SSL, data is encrypted using SSL. If the server is not configured for SSL, the connectionfails.

Notes

• This connection option can affect performance.

DefaultFor the driver:

0 (No Encryption)

For the Schema Tool:

noEncryption

GUI TabSecurity tab


Fetch Size

AttributeFetchSize (FS)


Fetch Size

PurposeSpecifies the maximum number of rows that the driver processes before returning data to the application fora single fetch request when executing a Select.This value provides a suggestion to the driver as to the numberof rows that should be returned to the application. The driver may fetch fewer rows to conserve memory whenprocessing exceptionally wide rows.

Valid Values0 | x

where:

x

is a positive integer.

BehaviorIf set to 0, the driver fetches and processes all of the rows of the result before returning control to the application.Setting Fetch Size to 0 may diminish performance and increase the likelihood of out-of-memory errors.

If set to x, the driver limits the number of rows that may be processed and returned to the application for asingle fetch request.To optimize throughput, the driver uses an internal algorithm to determine how many rowsshould be returned based on the width of rows in the result set. Therefore, the driver may return fewer rowswhen the result set contains wide rows. Alternatively, the driver may return the maximum number of rows asspecified by Fetch Size when the result set contains narrow rows.

Notes

• The Fetch Size connection option provides a suggestion to the driver as to the number of rows that shouldbe returned to the application, but it is not a determining factor when exceptionally wide rows are beingprocessed. When exceptionally wide rows are being processed, the driver reduces the number of rowsreturned but uses an algorithm to maximize throughput. When rows are not exceptionally wide, Fetch Sizecan be used to adjust the trade-off between throughput and response time. Smaller fetch sizes can improvethe initial response time of the query. Larger fetch sizes can improve overall response times at the cost ofadditional memory.

• By lowering the maximum number of rows as specified by Fetch Size, you lower the number of rows thedriver is required to process before returning data to the application. Thus, you reduce demands on thedriver's internal memory, and, in turn, decrease the likelihood of out-of-memory errors.

• The Result Memory Size connection option can also be used to reduce demands on the driver's internalmemory and decrease the likelihood of out-of-memory errors.

Default100

GUI TabAdvanced tab

See also

• Performance Considerations on page 127

• Result Memory Size on page 186



Host Name

AttributeHostName (HOST)

PurposeThe name or the IP address of the server to which you want to connect.

Valid Valuesserver_name | IP_address

where:

server_name

is the name of the server to which you want to connect.

IP_address

is the IP address of the server 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 IPAddresses on page 56 for details about these formats.

ExampleIf your network supports named servers, you can specify a server name such as MainServer. Or, you canspecify an IP address such as 199.226.224.34.

DefaultNone

GUI TabGeneral tab

Host Name In Certificate

AttributeHostNameInCertificate (HNIC)

PurposeA host name for certificate validation when SSL encryption is enabled (Encryption Method=1) and validationis enabled (Validate Server Certificate=1). This option provides additional security againstman-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that wasrequested.


Host Name



Valid Valueshost_name | #SERVERNAME#

where:

host_name

is the host name specified in the certificate. Consult your SSL administrator for the correct value.

BehaviorIf set to a host name, the driver examines the subjectAltName values included in the certificate. If a dnsNamevalue is present in the subjectAltName values, then the driver compares the value specified for Host Name InCertificate with the dnsName value. The connection succeeds if the values match. The connection fails if theHost Name In Certificate value does not match the dnsName value.

If no subjectAltName values exist or a dnsName value is not in the list of subjectAltName values, then thedriver and/or Schema Tool compares the value specified for Host Name In Certificate with the commonNamepart of the Subject name in the certificate. The commonName typically contains the host name of the machinefor which the certificate was created. The connection succeeds if the values match. The connection fails if theHost Name In Certificate value does not match the commonName.

If multiple commonName parts exist in the Subject name of the certificate, the connection succeeds if the HostName In Certificate value matches any of the commonName parts.

DefaultNone

GUI TabSecurity 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 "Internationalization, Localization,and Unicode" 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 systemlocale.

Default4 (ISO 8559-1 Latin-1)

GUI TabNA

See Also

• Internationalization, Localization, and Unicode on page 243

• IANAAppCodePage Values on page 227

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:


Initialization String

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.

DefaultNone

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 20

• Setting the Library Path Environment Variable (UNIX and Linux) on page 23.

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.

If you do not specify a value, the driver automatically detects the CLASSPATHs for all ODBC drivers installedon your machine and specifies them when launching the JVM.

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\mongodb.jar;c:\install_dir\java\lib\sforce.jar} forboth drivers. If the value for any of the affected drivers is missing a file path or is different from theone specified for the other drivers, the drivers will return an error at connection that the JVM is alreadyrunning.


JVM Classpath

ExampleOn Windows:

{.;c:\install_dir\java\lib\mongodb.jar}

On UNIX:

{.:/home/user1/install_dir/java/lib/mongodb.jar}

DefaultThe default is an empty string, which means that the driver automatically detects the CLASSPATHs for allODBC drivers installed on your machine and specifies them when launching the JVM.


Key Password

AttributeKeyPassword (KP)

PurposeThe password used to access the individual keys in the keystore file when SSL is enabled (EncryptionMethod=1) and SSL client authentication is enabled on the database server. Keys stored in a keystore canbe individually password-protected. To extract the key from the keystore, the driver must have the passwordof the key.



Valid Valueskey_password

where:

key_password

is the password of a key in the keystore.

DefaultNone



GUI TabSecurity tab

Key Store

AttributeKeystore (KS)

PurposeThe fully qualified path and file name of the keystore file to be used when SSL is enabled (EncryptionMethod=1) and SSL client authentication is enabled on the database server. The keystore file contains thecertificates that the client sends to the server in response to the server’s certificate request. If you do not specifya directory, the current directory is used.



Valid Valueskeystore_directory

where:

keystore_directory

is the location of the keystore file.

Notes

• The keystore and truststore files can be the same file.

DefaultNone

GUI TabSecurity tab


Key Store

Key Store Password

AttributeKeystorePassword (KSP)

PurposeThe password used to access the keystore file when SSL is enabled (Encryption Method=1) and SSLclient authentication is enabled on the database server.The keystore file contains the certificates that the clientsends to the server in response to the server’s certificate request.



Valid Valueskeystore_password

where:

keystore_password

is the password of the keystore file.

Notes

• The keystore and truststore files may be the same file; therefore, they may have the same password.

DefaultNone

GUI TabSecurity 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 "Using the Driver."

Defaultddlogging.properties

GUI TabAdvanced tab

See Also

• Using the Driver on page 146

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 Values-1 | 0 | x

where:

x

is a positive integer that represents a number of seconds.

BehaviorIf set to -1, the connection request does not time out. The driver silently ignores theSQL_ATTR_LOGIN_TIMEOUT attribute.


Login Timeout

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

If set to x, the connection request times out after the specified number of seconds unless the applicationoverrides this setting with the SQL_ATTR_LOGIN_TIMEOUT attribute.

Default15

GUI TabAdvanced tab

Min Long Varchar Size

AttributeMinLongVarcharSize (MINLVS)

PurposeSpecifies the minimum count of characters the driver reports for columns mapped as SQL_LONGVARCHAR.If the size of a SQL_LONGVARCHAR column is less than the value specified, the driver will increase thereported size of the column to this value when calling SQLDescribeCol and SQLColumns. This allows you tofetch SQL_LONGVARCHAR columns whose size is smaller than the minimum imposed by some third-partyapplications, such as SQL Server Linked Server.

Valid Valuesx

where:

x

is the minimum size in characters the driver will report for columns mapped to theSQL_LONGVARCHAR type.

Notes

• Configuring the VarcharThreshold and MinLongVarcharSize options allows you to fetch SQL_VARCHARand SQL_LONGVARCHAR columns with sizes that fall between the data-type ranges used by someapplications, such as SQL Server Linked Server.

DefaultNone. If no value is specified, the driver will not change the column size reported for SQL_LONGVARCHARcolumns.

GUI TabAdvanced tab



See alsoVarchar Threshold on page 195

Password

AttributePassword (PWD)

PurposeSpecifies the password to use to connect to your database. Contact your system administrator to obtain yourpassword.

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

where:

password

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

DefaultNone

GUI TabLogon Dialog

Port Number

AttributePortNumber (PORT)

PurposeSpecifies the port number of the server listener.

Valid Valuesport_number

where:


Password

port_number

is the port number of the server listener. Check with your database administrator for the correctnumber.

Default27017

GUI TabGeneral tab

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 is read-only:

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

Caution: Before disabling the Read Only option, verify that all values in the primary key column are unique.Executing write operations against data with duplicate primary keys can produce unpredictable and undesiredresults.

Default1 (Enabled)

GUI TabAdvanced tab



Read Preference

AttributeReadPreference (RP)

PurposeSpecifies a preference for the type of member (server node) of a replica set to which the driver attempts toconnect. Connections to the primary member (read-write server nodes) return the most recent version of thedata when executing Select queries, but increase the workload of the primary member and may negativelyaffect performance. To reduce the demand on the primary member, secondary members (read-only servernodes) can be used at the expense of reading stale data.

Valid Valuesnone | primary | primaryPreferred | secondary | secondaryPreferred

BehaviorIf set to none, the driver attempts to connect to only the member authorized by the application.

If set to primary, the driver attempts to connect to only the primary member of a replica set. If the primarymember is unavailable, the connection fails.

If set to primaryPreferred, the driver attempts to connect to the primary member first; but if it is unavailable,the driver attempts to connect to secondary members.

If set to secondary, the driver attempts to connect to only secondary members of a replica set. If the secondarymembers of the replica set are unavailable, the connection fails.

If set to secondaryPreferred, the driver attempts to connect to secondary members first; but if they areunavailable, the driver attempts to connect to the primary member.

Notes

• When connected to secondary members (read-only) of a replica set, the driver will return an error whenattempting to execute write operations.To enable write operations, disconnect from the secondary member;then, establish a new connection to a primary (read-write) member.You should verify that the ReadPreference option is configured to tolerate a connection to a primary member before attempting to establishthe new connection.

• If the Read Preference option is configured to connect to a secondary member, the replica set that the driveris connecting to must contain a secondary member; otherwise, the driver will return an error when attemptingto connect to a secondary member.

• This option only affects the member to which the driver connects and only during the connection process.For example, if you specified a value of secondary, the driver will not attempt to identify a new secondarymember if the secondary member it is connected to is promoted to the primary member.

Defaultprimary

GUI TabAdvanced tab


Read Preference


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.

Valid Values0 | 1 | 2

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

Result Memory Size

AttributeResultMemorySize (RMS)

PurposeSpecifies the maximum size, in megabytes, of an intermediate result set that the driver holds in memory.Whenthis threshold is reached, the driver writes a portion of the result set to disk in temporary files.



Valid Values-1 | 0 | x

where:

x

is a positive integer.

BehaviorIf set to -1, the maximum size of an intermediate result set that the driver holds in memory is determined bya percentage of the max Java heap size. When this threshold is reached, the driver writes a portion of theresult set to disk.

If set to 0, the SQL Engine holds intermediate results in memory regardless of size. Setting Result MemorySize to 0 can increase performance for any result set that can easily fit within the JVM's free heap space, butcan decrease performance for any result set that can barely fit within the JVM's free heap space.

If set to x, the SQL Engine holds intermediate results in memory that are no larger than the size specified.When this threshold is reached, the driver writes a portion of the result set to disk.

Notes

• By default, Result Memory Size is set to -1. When set to -1, the maximum size of an intermediate resultthat the driver holds in memory is a percentage of the max Java heap size. When processing large sets ofdata, out-of-memory errors can occur when the size of the result set exceeds the available memory allocatedto the JVM. In this scenario, you can tune Result Memory Size to suit your environment.To begin, set ResultMemory Size equal to the max Java heap size divided by 4. Proceed by decreasing this value until resultsare successfully returned. As a result, the maximum size of an intermediate result set the driver holds inmemory will be reduced, and some portion of the result sets will be written to disk. Be aware that whilewriting to disk reduces the risk of out-of-memory errors, it also negatively impacts performance. For optimalperformance, decrease this value only to a size necessary to avoid errors.

• You can also address memory and performance concerns by adjusting the max Java heap size using theJVM Arguments connection option. By increasing the max Java heap size, you increase the amount of datathe driver accumulates in memory. This can reduce the likelihood of out-of-memory errors and improveperformance by ensuring that result sets fit easily within the JVM's free heap space. In addition, when alimit is imposed by setting Result Memory Size to -1 or x, increasing the max Java heap size can improveperformance by reducing the need to write to disk, or removing it altogether.

• The Fetch Size connection option can also be used to reduce demands on the driver's internal memory anddecrease the likelihood of out-of-memory errors.

Default-1

GUI TabAdvanced tab

See also

• Performance Considerations on page 127

• Fetch Size on page 171

• JVM Arguments on page 176


Result Memory Size

Schema Definition

AttributeSchemaDefinition (SD)

PurposeSpecifies the name and location of the configuration file where the relational map of native data is written. Thedriver looks for this file when connecting to a MongoDB server. If the file does not exist, the driver creates one.

Valid Valuesstring

where:

string

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

Notes

• When connecting to a MongoDB server, the driver looks for the SchemaDefinition configuration file. If theconfiguration file does not exist, the driver creates a SchemaDefinition using the name and location youhave provided. If you do not provide a name and location for SchemaDefinition, the driver creates aSchemaDefinition using default values.

• The Schema Tool uses the path specified in this connection option to store log and internal files.

DefaultThe default value is determined by the Host Name connection option, platform, and data source type. Whenyou specify a value for the host name connection option, the driver uses it to create the filename prefix for theconfig file. For example, if you specify a host name of MainServer, the default config file will be namedMainServer.config. The path component of the default value is dependent on the platform and, for someWindows platforms, data source type. The following is a list of default values by platform:

• Windows XP:

user_profile\Application Data\Local\Progress\DataDirect\MongoDBSchema\host_name.config

• All other Windows platforms:

• User Data Source:

user_profile\AppData\Local\Progress\DataDirect\MongoDB Schema\host_name.config

• System Data Source:

C:\Users\Default\AppData\Local\Progress\DataDirect\MongoDBSchema\host_name.config



• UNIX:

~/progress/datadirect/mongodb_schema/host_name.config

GUI TabGeneral tab

See AlsoHost Name on page 173

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 unless SQL Engine Mode is set to 1 (Server).

DefaultFor the 32-bit driver:

19932


19931



Server Port Number

SQL Engine Mode

AttributeSQLEngineMode (SEM)

PurposeSpecifies whether the driver’s SQL engine runs in the same process as the driver (direct mode) or runs in aprocess that is separate from the driver (server mode).You must be an administrator to modify the server modeconfiguration values, and to start or stop the SQL engine service.

Valid Values0 | 1 | 2

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.

Notes

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



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

Trust Store

AttributeTruststore (TS)

PurposeThe directory that contains the truststore file and the truststore file name to be used when SSL is enabled(Encryption Method=1) and server authentication is used. The truststore file contains a list of the validCertificate Authorities (CAs) that are trusted by the client machine for SSL server authentication. If you do notspecify a directory, the current directory is used.

Note: The ODBC MongoDB Wire Protocol driver and Schema Tool support only truststores generated by aJava Keytool. Truststores using the PKCS12 format are not currently supported.



Transaction Mode


Valid Valuestruststore_directory\filename

where:

truststore_directory

is the directory where the truststore file is located

filename

is the file name of the truststore file.

Notes

• The keystore and truststore files may be the same file.

DefaultNone

GUI TabSecurity tab

Trust Store Password

AttributeTruststorePassword (TSP)

PurposeThe password that is used to access the truststore file when SSL is enabled (Encryption Method=1) andserver authentication is used.The truststore file contains a list of the Certificate Authorities (CAs) that the clienttrusts.





Valid Valuestruststore_password

where:

truststore_password

is a valid password for the truststore file.

Notes

• The truststore and keystore files may be the same file; therefore, they may have the same password

DefaultNone

GUI TabSecurity tab

User Name

AttributeLogonID (UID)

PurposeThe default user ID that is used to connect to your database.Your ODBC application may override this valueor 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.

GUI TabSecurity tab

Validate Server Certificate

AttributeValidateServerCertificate (VSC)


User Name

PurposeDetermines whether the driver and/or Schema Tool validates the certificate that is sent by the database serverwhen SSL encryption is enabled. When using SSL server authentication, any certificate sent by the servermust be issued by a trusted Certificate Authority (CA). Allowing the driver and/or Schema Tool to trust anycertificate returned from the server even if the issuer is not a trusted CA is useful in test environments becauseit eliminates the need to specify truststore information on each client in the test environment.

Truststore information is specified using the Trust Store and Trust Store Password options.



In addition, the driver and Schema Tool use a different set of valid values when configuring theValidateServerCertificate option. The valid values and behavior for both components are listed in the followingsections.

Valid ValuesFor the driver:

0 | 1

For the Schema Tool:

true | false

BehaviorIf set to 1 (Enabled) or true, the driver or Schema Tool validates the certificate that is sent by the databaseserver. Any certificate from the server must be issued by a trusted CA in the truststore file. If the Host NameIn Certificate option is specified, the driver and/or Schema Tool also validates the certificate using a host name.The Host Name In Certificate option provides additional security against man-in-the-middle (MITM) attacks byensuring that the server the driver and/or Schema Tool is connecting to is the server that was requested.

If set to 0 (Disabled) or false, the driver or Schema Tool does not validate the certificate that is sent by thedatabase server.The driver and/or Schema Tool ignores any truststore information specified by the Trust Storeand Trust Store Password options.

Default1 (Enabled)

GUI TabSecurity Tab on page 79



Varchar Threshold

AttributeVarcharThreshold (VT)

PurposeSpecifies the threshold at which the driver describes columns of the data type VARCHAR as LONGVARCHAR.If the size of the VARCHAR column exceeds the value specified, the driver will describe the column asLONGVARCHAR when calling SQLDescribeCol and SQLColumns. This option allows you to fetch columnsthat would otherwise exceed the upper limit of the VARCHAR type for some third-party applications, such asSQL Server Linked Server.

Valid Valuesx

where:

x

is the maximum size in characters of columns the driver will describe as VARCHAR.

Notes

• Configuring the VarcharThreshold and MinLongVarcharSize options allows you to fetch VARCHAR andLONGVARCHAR columns with sizes that fall between the data-type ranges used by some applications,such as SQL Server Linked Server.

DefaultNone. If no value is specified, the driver will not change the described type for VARCHAR columns.

GUI TabAdvanced tab

See alsoMin Long Varchar Size on page 182


Varchar Threshold



8Supported SQL Statements

The MongoDB driver supports the SQL statements, the SQL extensions, and the custom function escapeCAST_TO_NATIVE, as described in the following topics.


• Delete

• Insert

• Refresh Map (EXT)

• Reload Map (EXT)

• Select

• Update

• SQL Expressions

• Subqueries

• Custom Function Escapes

Delete

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


SyntaxDELETE FROM table_name [WHERE search_condition]

where:

table_name

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

search_condition

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

Notes

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

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

DELETE FROM emp WHERE emp_id = 'E10001'

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

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

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

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

Notes

• Insert, Update, and Delete are supported for MongoDB for simple types at the root level.

• To enable Insert, Update, and Delete, set the ReadOnly connection option to false.

See alsoWhere Clause on page 206

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


Chapter 8: Supported SQL Statements

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

table_name

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

column_name

is optional and specifies an existing column. Multiple column names (a column list) must be separatedby commas. A column list provides the name and order of the columns, the values of which arespecified in the Values clause. If you omit a column_name or a column list, the value expressionsmust provide values for all columns defined in the table and must be in the same order that thecolumns are defined for the table. Table columns that do not appear in the column list are populatedwith the default value, or with NULL if no default value is specified.

expression

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

select_statement

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

Notes



See alsoLiterals on page 213Select on page 200

Refresh Map (EXT)

PurposeThe REFRESH MAP statement adds newly discovered objects to your relational view of native data. It alsoincorporates any configuration changes made to your relational view by reloading the schema definition andassociated files.

SyntaxREFRESH MAP [NEW]


Refresh Map (EXT)

where

NEW

limits the sampling performed by the driver to only those collections that are newly discovered.Whenexecuting REFRESH MAP, this can offer significant performance gains if you only want to samplenew collections or the existing collections are unchanged. If NEW is not specified in the statement,all collections are resampled.

Notes

• Newly discovered objects are mapped using the same relational view as the one you selected as your initialview in "Creating a Schema with the Table Wizard." If you did not select a view with the Schema Tool, orselected a custom view, the driver maps new objects using a normalized view.

• REFRESH MAP is an expensive query since it involves the discovery of native data. However, by specifyingNEW in the statement, you can reduce the overhead associated with this query by sampling only newcollections.

See alsoCreating a Schema with the Table Wizard on page 99

Reload Map (EXT)

PurposeThe RELOAD MAP statement reloads the schema definition and associated files. This allows you to updateyour relational view of native data while the driver is connected to the data store.

SyntaxRELOAD MAP

Notes

• RELOAD MAP does not discover changes made to the native data store.

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 202From Clause on page 204Where Clause on page 206Group By Clause on page 207Having Clause on page 207Union Operator on page 208Intersect Operator on page 209Except and Minus Operators on page 210Order By Clause on page 210Limit Clause on page 211

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 213Aggregate Functions on page 203

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.

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

COUNT

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

MAX

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

MIN

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

SUM


Select

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 206

Outer Join Escape Sequences

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

Syntax

{oj outer-join}

where outer-join is

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

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

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

The following outer join escape sequences are supported by MongoDB databases:

• Left outer joins

• Right outer joins

• Full outer joins

• Nested outer joins

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


Select

Syntax

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

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

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

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

Subquery in a From Clause

Subqueries can be used in the From clause in place of table references (table_name).

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

See alsoSubqueries on page 220

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 220SQL Expressions on page 213

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.

NotesThe driver uses the MongoDB aggregation framework whenever possible. In some instances, MongoDB mayaggregate data in unexpected ways. For example, if you use the GROUP BY clause to return zip codes andthe database contains the zip code 15237 as both a string and an integer, then two rows will be returned for15237 (one for the string representation and another for the integer representation).

See alsoSubqueries on page 220SQL Expressions on page 213

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


Select

where:

expr1 | expr2

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

rel_operator

is the relational operator that links the two expressions.

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

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

NotesThe driver uses the MongoDB aggregation framework whenever possible. In some instances, MongoDB mayaggregate data in unexpected ways. For example, if you use the HAVING clause to return zip codes and thedatabase contains the zip code 15237 as both a string and an integer, then two rows will be returned for 15237(one for the string representation and another for the integer representation).

See alsoSQL Expressions on page 213Subqueries on page 220

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


Select

Except and Minus Operators

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

Syntax

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

where:

DISTINCT

eliminates duplicate rows from the results.

Notes

• When using one of these operators, the Select lists for each Select statement must have the same numberof column expressions with the same data types and must be specified in the same order.


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


SELECT 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 213

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


Select

Update

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

SyntaxUPDATE table_name SET column_name = expression

[, column_name = expression] [WHERE conditions]

table_name

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

column_name

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

expression

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

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

UPDATE emp SET salary=32000, exempt=1

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 220Where Clause on page 206



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


SQL Expressions

Table 16: Literal Syntax Examples

ExampleLiteral SyntaxSQL Type

12 or -34 or 0n

where

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

BIGINT

0

1

Min Value: 0

Max Value: 1

BOOLEAN

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

'2010-05-2118:33:05.025'

TIMESTAMP'ts'DATETIME

0.25

3.1415

-7.48

n.f

where:

n

is the integral part

f

is the fractional part

DECIMAL

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

n.fEx

where:

n is the integral part

f is the fractional part

x is the exponent

DOUBLE

12 or -34 or 0n

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

INTEGER

'000482ff''hex_value'LONGVARBINARY

'This is a stringliteral'

'value'LONGVARCHAR

'2010-05-2118:33:05.025'

TIME'time'TIME

'This is a stringliteral'

'value'VARCHAR



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

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

Example

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

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

Example+1894.1204

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

Example'00af123d'

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

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

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

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

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

Notes

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

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

Example1994 or -2


SQL Expressions

Operators

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

Unary OperatorA unary operator operates on only one operand.

operator operand

Binary OperatorA binary operator operates on two operands.

operand1 operator operand2

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

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

Table 17: Arithmetic Operators

ExamplePurposeOperator

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

+ -

UPDATE emp SET sal = sal + sal *0.10

Multiplies, divides. These are binary operators.* /

SELECT sal + comm FROM emp WHEREempno > 100

Adds, subtracts. These are binary operators.+ -

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

Table 18: Concatenation Operator


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

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



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

The following table lists the supported comparison operators.

Table 19: Comparison Operators


SELECT * FROM emp WHERE sal =1500

Equality test.=

SELECT * FROM emp WHERE sal !=1500

Inequality test.!=<>

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

“Greater than" and "less than"tests.

><

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

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

>=<=

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

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

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

ESCAPE clause in LIKEoperator

LIKE ’pattern string’ ESCAPE’c’

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

character in the pattern stringshould be treated as a regularcharacter.

The default escape character isbackslash (\).

This matches only records with name’JOE_JOHN’.

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

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

SELECT * FROM emp WHERE salBETWEEN 2000 AND 3000

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

[NOT] BETWEEN x AND y


SQL Expressions


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

Tests for existence of rows in asubquery.

EXISTS

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

Tests whether the value of thecolumn or expression is NULL.

IS [NOT] NULL

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

Table 20: Logical Operators


SELECT * FROM emp WHERE NOT (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 21: Operator Precedence

OperatorPrecedence

+ (Positive), - (Negative)1

*(Multiply), / (Division)2

+ (Add), - (Subtract)3

|| (Concatenate)4

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

NOT, IN, LIKE6

AND7

OR8

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

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

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

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

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

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

Functions

The MongoDB driver supports a number of functions that you can use in expressions, as listed and describedin Scalar Functions on page 235.

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.


SQL Expressions

Table 22: Conditions

DescriptionCondition

Specifies a comparison with expressions or subquery results.

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

Simple comparison

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

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

Group comparison

Tests for membership in a list or subquery.

[NOT] IN

Membership

Tests for inclusion in a range.

[NOT] BETWEEN

Range

Tests for nulls.

IS NULL, IS NOT NULL

NULL

Tests for existence of rows in a subquery.

[NOT] EXISTS

EXISTS

Specifies a test involving pattern matching.

[NOT] LIKE

LIKE

Specifies a combination of other conditions.

CONDITION [AND/OR] CONDITION

Compound

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

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

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



IN Predicate

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

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

OR

value [NOT] IN (subquery)

ExampleSELECT * FROM emp WHERE deptno IN

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

EXISTS Predicate

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

SyntaxEXISTS (subquery)

Example

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

UNIQUE Predicate

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

SyntaxUNIQUE (subquery)

Example

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


Subqueries

Correlated Subqueries

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

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

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)

Custom Function EscapesThe MongoDB driver supports the custom function escape CAST_TO_NATIVE, as described in the followingtopic.

CAST_TO_NATIVE Function Escape

PurposeThe CAST_TO_NATIVE function escape can be used in a filter to select or insert a value of a specific nativetype.

In some cases, a value with a specific native type can be concealed or obscured because the driver describesa field with inconsistent native types as a column with a single SQL type. For example, the driver maps aMongoDB _id field with the native types String and ObjectId to a relational _ID column with theSQL_WVARCHAR type. In this context, the CAST_TO_NATIVE function escape allows users to send a valueas it is defined in the MongoDB database, rather than how it is described in the relational model of the data.

Currently, CAST_TO_NATIVE can only be used with the ObjectID type in SELECT statement filters and literalINSERT values.

Syntax

{fn CAST_TO_NATIVE('value','native_type')}

where:

value

is the value to be selected or inserted.

native_type

is the native type that in part defines the value.


Custom Function Escapes

Example SelectThe following statement selects records from Account where the _ID field has an ObjectID value of507f1f77bcf86cd799439011.

SELECT * FROM Account WHERE _ID = {fn CAST_TO_NATIVE('507f1f77bcf86cd799439011','objectid')}

Example InsertThe following statement inserts the ObjectID value 507f1f77bcf86cd799439011 into the _ID field.

INSERT INTO Account(_ID) VALUES ({fn CAST_TO_NATIVE('507f1f77bcf86cd799439011','objectid')})



IReference

This part provides detailed reference information about your Progress DataDirect for ODBC driver.


• 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



Part I: Reference

9Code 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 23: 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 9: 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 8

IBM-943_P14A-20002000000943 8

IBM-10252000001025 8

IBM-43962000004396 8

IBM-50262000005026 8

IBM-50352000005035 8


8 These values are assigned by Progress DataDirect and do not appear in http://www.iana.org/assignments/character-sets.




10ODBC 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 24: 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 10: ODBC API and Scalar Functions

Table 25: 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 49

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 26: 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 27: 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 28: 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 29: 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 30: 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()



11Internationalization, 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 11: 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, Windows Server 2012, and Windows 8.1. Microsoft recommends usingUTF-16 for new applications.

See "Unicode Support" to determine which encodings your driver supports.

See alsoUnicode Support on page 55

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 MongoDB 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 250

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 246

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 60



12Designing 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 31: 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 12: 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 257

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.



13Using 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 13: 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 264

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 13: Using Indexes

14Locking and Isolation Levels

This chapter discusses locking and isolation levels and how their settings can affect the data you retrieve.Different database systems support different locking and isolation levels.


• 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 32: Isolation Levels and Data Consistency

Phantom ReadNonrepeatable ReadDirty ReadLevel

YesYesYes0, Read uncommitted

YesYesNo1, Read committed


Chapter 14: 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 14: Locking and Isolation Levels

15WorkAround 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 15: 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 15: WorkAround Options

16Threading

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

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 280). 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

Aaddress, IP 56Administrator

Windows ODBC and tracing 140Administrator, Data Source

Windows 20Advanced options 75aggregate functions 203AIX, See UNIX and Linuxapplication 277Application Using Threads connection option 156arithmetic operators 216arrays

mapping 41arrays of parameter values, passing 258authentication

SSL client 129SSL server 129

Autocommit mode 260

Bbinary

literals 215operators 216

bindingdynamic parameters 54parameter markers 54

bound columns 257BSON 31bulk load 277

Ccaching information to improve performance 254call load, reducing 257catalog functions, using 254changes to behavior for release 8.0.0 12changes to behavior for release 8.0.1 12character encoding 245character string literals 215client code page, See code pagesclient load balancing 277code pages

IANAAppCodePage attribute 174, 227column

names 213column information and statistics

sample size 110columnDiscoverySampleSize config option 158

columns 123comparison operators 217complex types

arrays 41documents 41

concatenation operator 216conditions 219config options

columnDiscoverySampleSize 158DefaultVarcharSize 159KeywordConflictSuffix 126, 132, 161LeadingUnderscoreReplacement 126, 132, 162MaxVarcharSize 163MinVarcharSize 164SchemaFilter 165UppercaseIdentifiers 126, 132, 167

Config Options connection option 157configuring

server mode 134configuring a data source

UNIX and Linux 23Windows

using a GUI 69configuring Java logging 145conformance 277connecting via connection string

data source 81connection attribute

ApplicationUsingThreads 156MinLongVarcharSize 182ResultMemorySize 186VarcharThreshold 195

connection attributesEncryptionMethod 170HostNameInCertificate 173KeyPassword 178Keystore 179KeystorePassword 180LogonID 193Truststore 191TruststorePassword 192ValidateServerCertificate 193

connection handles 260connection issues 148connection option

Min Long Varchar Size 182Varchar Threshold 195

connection optionsApplication Using Threads 156Config Options 157Create Database 168


Index

connection options (continued)Data Source Name 169Database 169Description 170Encryption Method 170Fetch Size 171Host Name 173Host Name In Certificate 173IANAAppCodePage 174Initialization String 175JVM Arguments 176JVM Classpath 177Key Password 178Key Store 179Key Store Password 180Log Config File 180Login Timeout 181overview 153Port Number 183Read Only 184Read Preference 185Report Codepage Conversion Errors 186required 69Result Memory Size 186Schema Definition 188Server Port Number 189SQL Engine Mode 190Transaction Mode 191Trust Store 191Trust Store Password 192User Name 193Validate Server Certificate 193

connection pooling 277connection properties

for security 130connection retry 277connection string 278connection string attributes 153connections

optimizing 260supported 58

contacting Technical Support 18correlated subqueries 222Create Database connection option 168cursor library, performance implications of using 259custom view

starting with 103

Ddata encryption 72, 75, 79, 128data retrieval, optimizing 256data source

configuringUNIX and Linux 22, 63Windows 20

data source (continued)connecting via connection string 81connecting via logon dialog box 82

Data Source AdministratorWindows 20

Data Source Name connection option 169data types

choosing 258complex 41

Database connection option 169database connections, testing 146database information 107databases, supported 31DataDirect Schema Tool 83date and time functions 240date/time literals 215ddlogging.properties file 146ddtestlib tool 62, 142DefaultVarcharSize config option 159Delete statement 197determining optimal set of columns 261diagnostic tools 139dirty reads 268distributed transactions 261documentation

about 17documents

mapping 41double-byte character sets in UNIX and Linux 245driver

API and scalar functions 233code page values 227connection option descriptions 153logging for 143ODBC compliance 49optimizing application performance 253supported features 55threading 275

Driver Managererror messages 147support 67version string 49

driver requirements 32Driver to SQL Communication logger 144drivers

version string information 49DSN (Data Source Name) 278DTC (Distributed Transaction Coordinator) 278dynamic parameters, binding 54

Eembedded database

creating 168enabling tracing 140


Index

encryptiondata 128SSL 128

Encryption Method, connection option 170environment

variables 60environment variable, library path 149error messages

general 147UNIX and Linux 147Windows 147

example application 146Except operator 210executing SQL 146EXISTS predicate 221Extended Options 72, 75, 271extracting a new table 119

Ffailover 278Fetch Size connection option 171flattened view

generating 101Flattening Native Data 48From clause

Outer Join Escape Sequences 205function escapes 223functionality

changes 12new 12

functions, ODBCselecting for performance 258

GGeneral Tab 69Group By clause 207

Hhandles

connection 260statement 260

Having clause 207Host Name connection option 173Host Name In Certificate, connection option 173

IIANAAppCodePage

connection attribute 174connection option values 227

IANAAppCodePage values 227

identifiersnaming conflicts 126, 132

improvingdatabase performance 263index performance 263join performance 266ODBC application performance 151, 253record selection performance 264

IN predicate 221index 278indexes

deciding which to create 265improving performance 263overview 263

indexing multiple fields 264Initialization String connection option 175Insert statement 198integer literals 215internationalization 243interoperability issues 150Intersect operator 209IP addresses 56IPv4 56IPv6 56isolation level 278isolation levels

about 268read committed 268read uncommitted 268repeatable read 268serializable 268

isolation levels and data consistencycompared 268dirty reads 268non-repeatable reads 268phantom reads 268

ivtestlib tool 62, 142

JJava logging

configuring 145SQL engine logger 144

Java Logging for the SQL Engine Server 137Java Path 134join in a From clause 205JVM Arguments connection option 176JVM Classpath connection option 177

KKerberos 278Key Password, connection option 178Key Store Password, connection option 180Key Store, connection option 179KeywordConflictSuffix config option 126, 132, 161


Index

LLeadingUnderscoreReplacement config option 126, 132, 162library path environment variable

setting on UNIX/Linux 23setting on Windows 20

Limit clause 211Linux, See UNIX and Linuxliterals

about 213binary 215character string 215date/time 215integer 215numeric 215

load balancing 278local table

deleting rows 197locale 244localization 243locking 267locking level 279locking levels 53locking modes and levels 269Log Config File connection option 180logging, Java

components 143configuring 145SQL engine logger 144

logical operators 218Login Timeout connection option 181long data, retrieving 256

Mmanaging connections 260mapping

complex types 41mapping newly detected objects 117mapping objects 112mapping objects to tables 40MaxVarcharSize config option 163metadata methods 31MIBenum value 227Min Long Varchar Size connection option 182Minus operator 210MinVarcharSize config option 164MongoDB driver

overview 31MTS (Microsoft Transactcion Server) 279

Nnaming conflicts

identifiers 126, 132

nestedarrays 41documents 41

New Features and Enhancements for Release 8.0.0 12New Features and Enhancements for Release 8.0.1 12New Native Objects window 117non-repeatable reads 268normalization

naming conflicts 126, 132normalized view

generating 99normalizing

arrays 41complex types 41documents 41

numeric functions 239numeric literals 215

Oobjects

mapping to tables 40ODBC

API functions 233call load, reducing 257designing for performance 253functions, selecting for performance 258how the architecture works 30scalar functions 235specification 49

ODBC Administrator 279ODBC application performance design 151ODBC conformance 49ODBC Test 143ODBC Trace 139odbc.ini

encoding 252sample 64

odbc.ini (system information) fileconfiguring with 63

odbc.ini filecontrolling tracing with 141

odbcinst.iniencoding 252

Open Database Connectivity, See ODBC specificationOpenSSL cipher suites

driver support 128operators

arithmetic 216comparison 217concatenation 216logical 218precedence 218

optimization, performance 253Order By clause 210OS authentication 279


Index

out of memory errorstroubleshooting 151

Outer Join Escape Sequences 205

Pparameter markers, binding 54parameter metadata 56parameter values, passing arrays of 258Password connection option 183performance 151performance considerations 127performance optimization

avoiding catalog functions 254avoiding search patterns 255commits in transactions 260managing connections 260overview 253reducing the size of retrieved data 256retrieving long data 256using a dummy query 255using bound columns 257

Performance Tuning Wizard 279performance, improving

database using indexes 263index 263join 266record selection 264

phantom reads 268Port Number connection option 183positioned updates and deletes 261predicate

EXISTS 221IN 221UNIQUE 221

primary keydesignating a 124

properties file for Java loggingJVM 145

Rread committed 268Read Only connection option 184Read Preference 185read uncommitted 268reauthentication 279Refresh Map (EXT) 199relational view

resetting 126Reload Map (EXT) 200repeatable read 268Report Codepage Conversion Errors connection option186Restart the Wizard 126Result Memory Size connection option 186

retrieving data, optimizing 256

Ssample size

column information and statistics 110scalar functions, ODBC 235schema

customizing 103flattening 99, 101normalizing 99Table Wizard 99views 99

schema definition 40Schema Definition

customizing 106Schema Definition connection option 188Schema Tool

extracting a new table 119mapping newly detected objects 117mapping objects 112security 130security, configuring

UNIX and Linux 130Windows 130

starting 83starting on UNIX/Linux 83starting on Windows 91

SchemaFilter config option 165scrollable cursors 259search patterns, avoiding 255Secure Sockets Layer, See See SSLSecure Sockets Layer (SSL) 280security

configuring 79Schema Tool

UNIX and Linux 130Windows 130

Security Tab 79Select clause 202Select statement 200serializable isolation level 268Server DB Directory 134server mode, configuring 134Server Port Number connection option 189Services 134setting library path environment variable

on UNIX/Linux 23on Windows 20

setup issues 148shard key 124sharding, support for 58SQL

executing 146expressions 213supported 58


Index

SQL engine logger 144SQL Engine Mode connection option 190SQL engine, starting 136SQL engine, stopping 137SQL engine, using 134SQL functionality 31SQL Grammar 280SQL Server Linked Server

fetching columns 182, 195SQL statement support 197SQL statements

Insert 198Update 212

SQLExecDirect, advantages of using 258SQLFetch, disadvantage of using 257SQLSpecialColumns, determining optimal set of columns261SSL

client authentication 129encryption 128server authentication 129

SSL client/server authentication 280standards, ODBC specification compliance 49starting

SQL engine server 136statement handles, using to manage SQL statements260statements supported 58static cursors 259stopping the SQL engine server 137string functions 237subdocuments

mapping 41subqueries

correlated 222overview 220

subquery in a From clause 206supported databases 31system functions 242system information file (.odbc.ini) 63, 141

Ttable information 107table wizard 31Table Wizard

about 99custom view 103flattened view 101normalized view 99

Tableauexporting data to 25using the driver with 25

Technical Support, contacting 18test connect

UNIX and Linux 24

testing database connections 146threading

overview 156using multiple threads 156

threading, overview 275time functions 240tools

diagnostic 139other 147

trace log 139tracing

creating a trace log 139enabling with system information file 141enabling with Windows ODBC Administrator 140

tracking JDBC calls 143Transaction Mode connection option 191transactions, managing commits 260troubleshooting 139, 148Trust Store Password, connection option 192Trust Store, connection option 191

UUCS-2 245unary operator 216undocumented connection options 72, 75Unicode

character encoding 245ODBC drivers 247support 55support in databases 246support in ODBC 246

Union operator 208UNIQUE predicate 221UNIX and Linux

configuring a data source 23configuring through the system information (odbc.ini)file 63data source configuration 22, 63double-byte character sets 245driver names 39environment

DD_INSTALLDIR 62ddtestlib tool 62introduction 60ivtestlib tool 62library search path 60ODBCINI 61ODBCINST 61system information file (.odbc.ini) 63

error messages 147system information (odbc.ini) file, configuring through63system requirements 34

Update statement 212updates, optimizing 260


Index

UppercaseIdentifiers config option 126, 132, 167user ID/password authentication 280User Name, connection option 193using

SQL engine 134UTF-16 245UTF-16 Applications 68UTF-8 245

VValidate Server Certificate, connection option 193Varchar Threshold connection option 195version string information 49

WWhat's new? 12Where clause 206Windows

configuring a data source 69Data Source Administrator 20data source configuration 20driver names 34error messages 147system requirements 33

Windows ODBC Administrator and tracing 140wire protocol adapter logger 145WorkAround options for ODBC drivers 271


Index


Index