ProgressDataDirect for ODBC forApacheCassandra Driver•Troubleshootingonpage83explainsthetoolstosolvecommonproblemsanddocumentserrormessages

Progress DataDirect forODBC for ApacheCassandraUser's Guide and Reference

Release 8.0.0

Copyright

© 2020 Progress Software Corporation and/or one of its subsidiaries or affiliates. Allrights reserved.These materials and all Progress® software products are copyrighted and all rights are reserved by ProgressSoftware Corporation. The information in these materials is subject to change without notice, and ProgressSoftware Corporation assumes no responsibility for any errors that may appear therein. The references inthese materials to specific platforms supported are subject to change.

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

Updated: 2020/10/08

3The Progress DataDirect for ODBC for Apache Cassandra™ Driver: User's Guide and Reference: Version 8.0.0

The Progress DataDirect for ODBC for Apache Cassandra™ Driver: User's Guide and Reference: Version 8.0.04

Copyright

Table of Contents

Preface..........................................................................................................11Welcome to the Progress DataDirect for ODBC for Apache Cassandra™ Driver..................................11

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

Conventions Used in This Guide..........................................................................................................13

About the Product Documentation........................................................................................................15

Contacting Technical Support...............................................................................................................16

Getting Started.............................................................................................17Configuring and Connecting on Windows.............................................................................................18

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

Configuring a Data Source........................................................................................................18

Testing the Connection..............................................................................................................19

Configuring and Connecting on UNIX and Linux..................................................................................20

Environment Configuration........................................................................................................20

Test Loading the Driver..............................................................................................................20

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

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

Testing the Connection..............................................................................................................22

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

What Is ODBC?............................................................................................23How Does It Work?...............................................................................................................................24

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

About the Apache Cassandra Driver.........................................................25Driver Requirements.............................................................................................................................26

Support for Multiple Environments.......................................................................................................26

Support for Windows Environments...........................................................................................26

Support for UNIX and Linux Environments................................................................................28

ODBC Compliance...............................................................................................................................33

Version String Information....................................................................................................................34

getFileVersionString Function....................................................................................................35

Data Types............................................................................................................................................35

Retrieving Data Type Information...............................................................................................37

Complex Type Normalization................................................................................................................38

Collection Types.........................................................................................................................38

Tuple and User-Defined Types...................................................................................................42


Contents

Nested Complex Types..............................................................................................................44

Isolation and Lock Levels Supported....................................................................................................46

Binding Parameter Markers..................................................................................................................46

Supported Features.....................................................................................47Unicode Support...................................................................................................................................47

Using IP Addresses..............................................................................................................................48

Parameter Metadata Support...............................................................................................................48

Insert and Update Statements...................................................................................................48

Select Statements......................................................................................................................49

SQL Support.........................................................................................................................................50

Number of Connections and Statements Supported............................................................................50

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

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

Data Source Configuration Using a GUI....................................................................................61

Using a Connection String.........................................................................................................74

Using a Logon Dialog Box.........................................................................................................75

Performance Considerations................................................................................................................76

Using the SQL Engine Server..............................................................................................................77

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

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

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

Using Failover in a Cluster....................................................................................................................82

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

Troubleshooting...........................................................................................85Diagnostic Tools....................................................................................................................................85

ODBC Trace...............................................................................................................................85

The Test Loading Tool................................................................................................................88

ODBC Test.................................................................................................................................89

Logging......................................................................................................................................89

Configuring Logging...................................................................................................................91

The demoodbc Application........................................................................................................92

The Example Application...........................................................................................................93

Other Tools.................................................................................................................................93

Error Messages....................................................................................................................................93

Troubleshooting....................................................................................................................................94

Setup/Connection Issues...........................................................................................................95

Interoperability Issues................................................................................................................96

Performance Issues...................................................................................................................97

Out-of-Memory Issues...............................................................................................................97


Contents

Operation Timeouts...................................................................................................................98

Connection Option Descriptions..............................................................101Application Using Threads..................................................................................................................104

Ascii Size ...........................................................................................................................................105

Authentication Method........................................................................................................................106

Cluster Nodes.....................................................................................................................................106

Config Options....................................................................................................................................107

Create Map.........................................................................................................................................108

Data Source Name.............................................................................................................................109

Decimal Precision ..............................................................................................................................110

Decimal Scale ....................................................................................................................................110

Description..........................................................................................................................................111

Fetch Size...........................................................................................................................................112

Host Name..........................................................................................................................................113

IANAAppCodePage............................................................................................................................114

Initialization String..............................................................................................................................115

JVM Arguments..................................................................................................................................115

JVM Classpath...................................................................................................................................116

Keyspace Name.................................................................................................................................117

Log Config File...................................................................................................................................118

Login Timeout.....................................................................................................................................119

Native Fetch Size................................................................................................................................119

Password............................................................................................................................................120

Port Number.......................................................................................................................................121

Query Timeout....................................................................................................................................121

Read Consistency..............................................................................................................................122

Read Only...........................................................................................................................................123

Report Codepage Conversion Errors.................................................................................................124

Result Memory Size...........................................................................................................................124

Schema Map......................................................................................................................................126

Server Port Number............................................................................................................................127

SQL Engine Mode..............................................................................................................................128

Transaction Mode...............................................................................................................................129

User Name.........................................................................................................................................129

Varchar Size.......................................................................................................................................130

Varint Precision...................................................................................................................................130

Write Consistency...............................................................................................................................131

Supported SQL Functionality...................................................................133Data Definition Language (DDL)........................................................................................................133

Native and Refresh Escape Clauses.......................................................................................134

Delete.................................................................................................................................................134


Contents

Insert..................................................................................................................................................135

Refresh Map (EXT).............................................................................................................................137

Select..................................................................................................................................................137

Select Clause...........................................................................................................................139

Update................................................................................................................................................148

SQL Expressions................................................................................................................................150

Column Names........................................................................................................................151

Literals.....................................................................................................................................151

Operators.................................................................................................................................153

Functions.................................................................................................................................157

Conditions................................................................................................................................157

Subqueries.........................................................................................................................................158

IN Predicate.............................................................................................................................158

EXISTS Predicate....................................................................................................................159

UNIQUE Predicate...................................................................................................................159

Correlated Subqueries.............................................................................................................159

Part I: Reference.........................................................................................161

Code Page Values...............................................................................163IANAAppCodePage Values......................................................................................................163

ODBC API and Scalar Functions......................................................169API Functions..........................................................................................................................169

Scalar Functions......................................................................................................................172

String Functions............................................................................................................173

Numeric Functions........................................................................................................175

Date and Time Functions..............................................................................................176

System Functions.........................................................................................................178

Internationalization, Localization, and Unicode..............................179Internationalization and Localization........................................................................................179

Locale...........................................................................................................................180

Language......................................................................................................................180

Country.........................................................................................................................180

Variant...........................................................................................................................181

Unicode Character Encoding...................................................................................................181

Background...................................................................................................................181

Unicode Support in Databases.....................................................................................182

Unicode Support in ODBC............................................................................................182

Unicode and Non-Unicode ODBC Drivers...............................................................................183

Function Calls...............................................................................................................183


Contents

Data..............................................................................................................................185

Default Unicode Mapping..............................................................................................186

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

References....................................................................................................................187

Designing ODBC applications for performance optimization........189Using catalog functions............................................................................................................190

Caching information to minimize the use of catalog functions......................................190

Avoiding search patterns...............................................................................................191

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

Retrieving data.........................................................................................................................192

Retrieving long data......................................................................................................192

Reducing the size of data retrieved...............................................................................192

Using bound columns...................................................................................................193

Using SQLExtendedFetch instead of SQLFetch...........................................................193

Choosing the right data type.........................................................................................194

Selecting ODBC functions.......................................................................................................194

Using SQLPrepare/SQLExecute and SQLExecDirect..................................................194

Using arrays of parameters...........................................................................................194

Using the cursor library.................................................................................................195

Managing connections and updates........................................................................................196

Managing connections..................................................................................................196

Managing commits in transactions................................................................................196

Choosing the right transaction model...........................................................................197

Using positioned updates and deletes..........................................................................197

Using SQLSpecialColumns...........................................................................................197

Using Indexes.....................................................................................199Introduction..............................................................................................................................199

Improving Row Selection Performance....................................................................................200

Indexing Multiple Fields...........................................................................................................200

Deciding Which Indexes to Create...........................................................................................201

Improving Join Performance....................................................................................................202

Locking and Isolation Levels............................................................203Locking....................................................................................................................................203

Isolation Levels........................................................................................................................204

Locking Modes and Levels......................................................................................................205

WorkAround Options.........................................................................207


Contents

Threading............................................................................................211

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


Contents

Preface

For details, see the following topics:

• Welcome to the Progress DataDirect for ODBC for Apache Cassandra™ 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 forApache Cassandra™ Driver

This book is your user’s guide and reference for the Progress DataDirect®

for ODBC for Apache CassandraTM

driver.

The content of this book assumes that you are familiar with your operating system and its commands. It containsthe following information:

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

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

• About the Apache Cassandra Driver on page 25 explains the driver, supported environments and driverrequirements.

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

• Using the Driver on page 51 guides you through configuring the driver. It also explains how to use thefunctionality supported by the driver such as Authentication and SSL encryption.


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

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

• Supported SQL Functionality on page 133 provides supported SQL statements and extensions that arespecific to the data source.

• The Reference on page 161 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?

Changes Since the 8.0.0 Release

• Certifications:

• Certified with Red Hat Enterprise 7.3 (driver version 08.00.0074 (B0238, U0156))

• Certified with Windows Server 2016 (driver version 08.00.0074 (B0238, U0156))

• Enhancements

• The driver has been enhanced to support connection failover and client load balancing when connectingto a cluster.You can enable this new functionality by specifying a comma-separated list of membernodes using the new Cluster Nodes (ClusterNodes) connection option. See Using Failover in a Clusteron page 82 and Cluster Nodes on page 106 for details.

• The driver has been enhanced to include timestamp in the internal packet logs by default. If you wantto disable the timestamp logging in packet logs, set PacketLoggingOptions=1. The internal packetlogging is not enabled by default. To enable it, set EnablePacketLogging=1.

• The driver has been enhanced to support the Duration data type, which maps to the SQL_VARCHARODBC type. See Data Types on page 35 for details.

• The driver has been enhanced to support all the data consistency levels for read and write operationsthat are supported by Apache Cassandra data stores. Data consistency levels are configured using theRead Consistency and Write Consistency connection options. For additional information, see ReadConsistency on page 122 and Write Consistency on page 131.

• Changed Behavior

• Java SE 7 has reached the end of its product life cycle and will no longer receive generally availablesecurity updates. As a result, the drivers will no longer support JVMs that are version Java SE 7 orearlier. Support for distributed versions of Java SE 7 and earlier will also end, including IBM SDK (JavaEdition).


Preface

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

Highlights of the 8.0.0 Release

• Certified against Apache Cassandra versions 2.0, 2.1, 2.2, and 3.7.

• Certified against DataStax Enterprise 4.7, 4.8, and 5.0.

• Supports SQL read-write access to Apache Cassandra data sources. See Supported SQL Functionality onpage 133 for details.

• Supports CQL Binary Protocol.

• The driver supports the core SQL-92 grammar.

• Support for all ODBC Core and Level 1 functions and some Level 1 and Level 2 features. See ODBCCompliance on page 33 for details.

• Supports user ID and password authentication. See Authentication Method on page 106 for details.

• Supports Cassandra data types, including the complex types Tuple, user-defined types, Map, List and Set.See Data Types on page 35 for details.

• Generates a relational view of Cassandra data. Tuple and user-defined types are flattened into a relationalparent table, while collection types are mapped as relational child tables. See Complex Type Normalizationon page 38 for details.

• Supports Native and Refresh escape clauses to embed CQL commands in SQL-92 statements. See Nativeand Refresh Escape Clauses on page 134 for details.

• Supports Cassandra's tunable consistency functionality with Read Consistency on page 122 and WriteConsistency on page 131 connection options.

• Supports the handling of large result sets with Fetch Size on page 112, Native Fetch Size on page 119, andResult Memory Size on page 124 connection options.

• Supports applications that do not support unbounded Cassandra data types through the Ascii Size on page105, Decimal Precision on page 110, Decimal Scale on page 110, Varchar Size on page 130, and VarintPrecision on page 130 connection options.

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:


Preface

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

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/CassandraHelp/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/CassandraHelp/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


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.

October 2020, Release 8.0.0 for the Progress DataDirect for ODBC for Apache Cassandra Driver, Version0001


Preface

https://www.progress.com/support

1Getting Started

This chapter provides basic information about configuring your driver immediately after installation and testingyour connection.To take full advantage of the features of the driver, read "About the Apache Cassandra 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 Windows, UNIX, and Linux, file data sources, which are simply text files, canbe stored locally or on a network computer, and are accessible to other machines.

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


• Configuring and Connecting on Windows

• Configuring and Connecting on UNIX and Linux

• Accessing Data With Third-Party Applications


Configuring and Connecting on Windows

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

Setting the Library Path Environment Variable (Windows)

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

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

Configuring a Data Source

To configure a data source:

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

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

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

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

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

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

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

2. On the General tab, provide the following information; then, select the Schema Map tab.

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


Chapter 1: Getting Started

Keyspace Name: Type the name of the keyspace to which you want to connect. The default is system.

3. On the Schema Map tab, provide the following information; then, click Apply:

Schema Map: Type 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. For example,C:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_Schema\MainServer.config.

The default value is:

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

where:

application_data_folder

is the name and location of the application data folder.

host_name

is the value specified for the Host Name connection option.

See alsoSchema Map on page 126

Testing the Connection

To test the connection:

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

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

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

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

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

See alsoUsing a Logon Dialog Box on page 75Using a Connection String on page 74


Configuring and Connecting on Windows

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 51

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/ivcsndrxx.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 Apache Cassandra, you must set the library path environment variable foryour UNIX/Linux operating system to include the directory containing your JVM’s libjvm.so [sl | a] file, andthat directory’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 on UNIX and Linux platforms.You enter your site-specific database connection information usinga text editor. Each data source definition must include the keyword Driver=, which is the full path to the driver.

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

[ODBC Data Sources]Apache Cassandra=DataDirect 8.0 Apache Cassandra Driver

[Apache Cassandra]Driver=ODBCHOME/lib/xxcsndr28.yyHostName=CassandraServerKeyspaceName=CassandraKeyspace2


Configuring and Connecting on UNIX and Linux

PortNumber=9042SchemaMap=/home/users/jsmith/Progress/DataDirect/Cassandra_Schema/CassandraServer.config

Connection Option Descriptions:

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

KeySpaceName: The name of the keyspace to which you want to connect. The default is system.

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

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

users_home_directory/Progress/DataDirect/Cassandra_Schema/host_name.config

where:

users_home_directory

is the user's home directory.

host_name

is the value specified for the HostName connection option.

See "Schema Map" for details.


Testing the Connection

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

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

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




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 Apache Cassandra Driver

The Progress DataDirect for ODBC for Apache Cassandra driver supports read-write access to Apache Cassandraversions 2.0 and higher. To support SQL access to Cassandra, the driver creates a relational map of nativeCassandra data and translates SQL statements to CQL. Cassandra complex data types Map, List, Set, Tuple,and user-defined types are supported alongside primitive CQL types. The driver optimizes performance whenexecuting joins by leveraging data relationships among Cassandra objects to minimize the amount of data thatneeds to be fetched over the network. Relationships among objects can be reported with the following metadatamethods: SQLColumns, SQLForeignKeys, SQLGetTypeInfo, SQLPrimaryKeys, SQLSpecialColumns,SQLStatistics, and SQLTables. Furthermore, when performing joins, the driver leverages data relationshipsamong Cassandra objects, minimizing the amount of data that needs to be fetched over the network.


• Driver Requirements

• Support for Multiple Environments

• ODBC Compliance

• Version String Information

• Data Types

• Complex Type Normalization

• Isolation and Lock Levels Supported

• Binding Parameter Markers


Driver RequirementsThe driver requires a Java Virtual Machine (JVM): J2SE 6 or higher.

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 26Support for UNIX and Linux Environments on page 28Threading on page 211

Support for Windows Environments

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

32-Bit Driver

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

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

• The following processors are supported:

• x86: Intel

• x64: Intel and AMD

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

• Windows Server 2016



Chapter 3: About the Apache Cassandra Driver

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


• Windows 10

• Windows 8.1

• Windows 7

• A 32-bit Java Virtual Machine (JVM), J2SE 6 or higher, is required. Also, you must set the PATH environmentvariable to the directory containing your 32-bit JVM’s jvm.dll file, and that directory’s parent directory.

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

64-Bit Driver



• Intel

• AMD

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




• Windows 10

• Windows 8.1

• Windows 7

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

• A 64-bit JVM, J2SE 6 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.


Support for Multiple Environments

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

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

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

ivcsndr28.dll


ddcsndr28.dll

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

Support for UNIX and Linux Environments

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

32-Bit Driver


• If your application was built with 32-bit system libraries, you must use 32-bit drivers. If your application wasbuilt with 64-bit system libraries, you must use 64-bit drivers (see 64-Bit Drivers on page 30). The databaseto which you are connecting can be either 32-bit or 64-bit enabled.

• For the driver for Apache Cassandra : A 32-bit Java Virtual Machine (JVM), J2SE 6 or higher, is required.Also, you must set the library path environment variable of your operating system to the directory containingyour 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

• 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

• 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 and 8.5

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

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

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

• Ubuntu Linux 14.04 and 16.04

• 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 Oracle C++ 5.8 and theSolaris native (kernel) threading model

See also64-Bit Drivers on page 30

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

• For the driver for Apache Cassandra: A 64-bit Java Virtual Machine (JVM), J2SE 6 or higher, is required.Also, you must set the library path environment variable of your operating system to the directory containingyour 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 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



• 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 and 8.5

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

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

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

• Ubuntu Linux 14.04 and 16.04

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

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

Oracle Solaris


• Oracle SPARC



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

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



http://www.hp.com

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


ivcsndr28.so


ddcsndr28.so

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

ODBC ComplianceThe Progress DataDirect for ODBC for Apache Cassandra driver is compliant with the Open Database Connectivity(ODBC) 3.52 specification.The driver is ODBC core compliant and supports some Level 1 and Level 2 features.See "ODBC API and Scalar Functions" for a list of the Core, Level 1, and Level 2 functions supported by thedriver.

The driver supports only the following Level 2 functions:

• SQLColumnPrivileges

• SQLDescribeParam

• SQLForeignKeys

• SQLPrimaryKeys

• SQLProcedures

• SQLTablePrivileges

See alsoODBC API and Scalar Functions on page 169


ODBC Compliance

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

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

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

XX.YY.ZZZZ(UBBBB)

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

XX.YY.ZZZZ

where:

XX is the major version of the product.

YY is the minor version of the product.

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

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

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

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

For example:

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

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

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

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

The syntax for the tool is:

ivtestlib shared_object

or

ddtestlib shared_object

For example, for the 32-bit driver on Oracle Solaris:

ivtestlib ivcsndr28.so



returns:

08.00.0001 (B0002, U0001, J000003)

For example, for the Driver Manager on Solaris:

ivtestlib libodbc.so

returns:

08.00.0001 (U0001)

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

ddtestlib libodbc.so

returns:

08.00.0001 (U0001)

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

ivtestlib libivicu28.so08.00.0001

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

getFileVersionString Function

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

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

const unsigned char* getFileVersionString();

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

Data TypesThe following table lists the Apache Cassandra data types and their default mapping for ODBC.

Table 1: Default Mapping for Apache Cassandra Data Types

ODBC Data TypeApache Cassandra Data Type

SQL_VARCHAR (12)ASCII1

SQL_BIGINT (-5)Bigint

SQL_LONGVARBINARY (-4)Blob

1 ASCII precision is set to 4000 by default, but you can use the AsciiSize connection option to configure Ascii precision. See "AsciiSize" for details.


Data Types

ODBC Data TypeApache Cassandra Data Type

SQL_BIT (-7)Boolean

SQL_BIGINT (-5)Counter2

SQL_TYPE_DATE (91)Date

SQL_DECIMAL (3)Decimal3

SQL_DOUBLE (8)Double

SQL_VARCHAR (12)Duration4

SQL_REAL (7)Float

SQL_VARCHAR (12)Inet

SQL_INTEGER (4)Int

SQL_WLONGVARCHAR (-10)List

SQL_WLONGVARCHAR (-10)Map

SQL_WLONGVARCHAR (-10)Set

SQL_SMALLINT (5)Smallint

SQL_TYPE_TIME (92)Time

SQL_TYPE_TIMESTAMP (93)Timestamp

SQL_CHAR (1)TimeUUID

SQL_TINYINT (-6)TinyInt

SQL_WLONGVARCHAR (-10)Tuple

SQL_WLONGVARCHAR (-10)Usertype

SQL_CHAR (1)UUID

SQL_WVARCHAR (9)Varchar5

SQL_DECIMAL (3)Varint6

2 Update is supported for Counter columns when all the other columns in the row comprise that row’s primary key. See "Update"for details.

3 By default, Decimal precision is set to 38 and scale is set to 10; however, you can use the DecimalPrecision and DecimalScaleconnection options to configure Decimal precision and scale. See "Decimal Precision" and "Decimal Scale" for details.

4 Currently, the Duration type is supported only in simple columns, and not in Collection types.5 Varchar precision is set to 4000 by default, but you can use the VarcharSize connection option to configure Varchar precision.

See "Varchar Size" for details.6 Varint precision is set to 38 by default, but you can use the VarintPrecision connection option to configure Varint precision. See

"Varint Precision" for details.



See alsoAscii Size on page 105Update on page 148Decimal Precision on page 110Decimal Scale on page 110Varchar Size on page 130Varint Precision on page 130

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.

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


Data Types

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 85Data Types on page 35

Complex Type NormalizationTo support SQL access to Apache Cassandra, the driver maps the Cassandra data model to a relationalschema. This process involves the normalization of complex types.You may need to be familiar with thenormalization of complex types to formulate SQL queries correctly. The driver handles the normalization ofcomplex types in the following manner:

• If collection types (Map, List, and Set) are discovered, the driver normalizes the Cassandra table into a setof parent-child tables. Primitive types are mapped to a parent table, while each collection type is mappedto a child table that has a foreign key relationship to the parent table.

• Non-nested Tuple and user-defined types (also referred to as Usertype) are flattened into a parent tablealongside primitive types.

• Any nested complex types (Tuple, user-defined types, Map, List, and Set) are exposed as JSON-stylestrings in the parent table.

The normalization of complex types is described in greater detail in the following topics.

Collection Types

Cassandra collection types include the Map, List, and Set types. If collection types are discovered, the drivernormalizes the native data into a set of parent-child tables. Primitive types are normalized in a parent table,while each collection type is normalized in a child table that has a foreign key relationship to the parent table.Take for example the following Cassandra table:

CREATE TABLE employee ( empid int PRIMARY KEY, phone map<varchar, varint>, client list<varchar>, review set<date>);

The following employee table is a tabular representation of the native Cassandra table with data included. Inthis example, four distinct relational tables are created. A parent table is created based on the empid column,and a child table is created for each of the three collection types (Map, List, and Set).



Table 2: employee (native)

reviewclientphoneempid

(primary key)

set<date>list<varchar>map<varchar, varint>int

2013-12-07

2015-01-22

2016-01-10

Li

Kumar

Jones

home: 2855551122

mobile: 2855552347

office: 2855555566

spouse: 2855556782

103

2015-01-22

2016-01-12

Yanev

Bishop

Bogdanov

home: 2855555678

mobile: 2855553335

office: 2855555462

105

The Parent TableThe parent table is comprised of the primitive integer type column empid and takes its name from the nativetable. A SQL statement would identify the column as employee.empid.

Table 3: employee (relational parent)

empid

(primary key)

int

103

105

A SQL insert on the employee parent table would take the form:

INSERT INTO employee (empid) VALUES (107)

The Map Child TableThe Map collection is normalized into a three column child table called employee_phone. The name of thetable is formulated by concatenating the name of the native table and the name of the Map column. A foreignkey relationship to the parent table is maintained via the employee_empid column, and the Map's key valuepairs are resolved into separate keycol and valuecol columns. In a SQL statement, these columns wouldbe identified as the employee_phone.employee_empid, employee_phone.keycol, andemployee_phone.valuecol, respectively.


Complex Type Normalization

Table 4: employee_phone (relational child of the map column)

valuecolkeycolemployee_empid

(foreign key)

varintvarcharint

2855551122home103

2855552347mobile103

2855555566office103

2855556782spouse103

2855555678home105

2855553335mobile105

2855555462office105

A SQL insert on the employee_phone child table would take the form7:

INSERT INTO employee_phone (employee_empid, keycol, valuecol) VALUES (107, 'mobile', 2855552391)

The List Child TableThe List collection is normalized into a three column child table called employee_client. The name of thetable is formulated by concatenating the name of the native table and the name of the List column. A foreignkey relationship to the parent table is maintained via the employee_empid column; the order of the elementsin the List is maintained via the current_list_index column; and the elements themselves are containedin the client column. SQL statements would identify these columns asemployee_client.employee_empid, employee_client.current_list_index, andemployee_client.client, respectively.

Table 5: employee_client (relational child of the list column)

clientcurrent_list_indexemployee_empid

(foreign key)

varcharintint

Li0103

Kumar1103

Jones2103

7 The driver supports an insert on a child table prior to an insert on a parent table, circumventing referential integrity constraintsassociated with traditional RDBMS. To maintain integrity between parent and child tables, it is recommended that an insert firstbe performed on the parent table for each foreign key value added to the child. If such an insert is not first performed, the driverautomatically inserts a row into the parent table that contains only the primary key values and NULL values for all non-primarykey columns.



clientcurrent_list_indexemployee_empid

(foreign key)

varcharintint

Yanev0105

Bishop1105

Bogdanov2105

A SQL insert on the employee_client child table would take the form7:

INSERT INTO employee_client (employee_empid, client) VALUES (107, 'Nelson')

The Set Child TableThe Set collection is normalized into a two column child table called employee_review. The name of thetable is formulated by concatenating the name of the native table and the name of the Set column. A foreignkey relationship to the parent table is maintained via the employee_empid column, while the elements of theSet are given in natural order in the review column. In this child table, SQL statements would identify thesecolumns as employee_review.employee_empid and employee_review.review

Table 6: employee_review (relational child of the set column)

reviewemployee_empid

(foreign key)

dateint

2013-12-07103

2015-01-22103

2016-01-10103

2015-01-22105

2016-01-12105

A SQL insert on the employee_client child table would take the form7:

INSERT INTO employee_review (employee_empid, review) VALUES (107, '2015-01-20')

Update SupportUpdate is supported for primitive types, non-nested Tuple types, and non-nested user-defined types. Updateis also supported for value columns (valuecol) in non-nested Map types.The driver does not support updateson List types, Set types, or key columns (keycol) in Map types because the values in each are part of theprimary key of their respective child tables and primary key columns cannot be updated. If an Update isattempted when not allowed, the driver issues the following error message:



[DataDirect][Cassandra ODBC Driver][Cassandra]syntax error or access rule violation:UPDATE not permitted for column: column_name

Tuple and User-Defined Types

The driver supports Tuple and user-defined complex types which were introduced with Apache Cassandra 2.1.As long as there are no complex types nested in either the Tuple or user-defined types, the driver normalizesTuple and user-defined types by flattening them into a relational version of the native Cassandra table. Takefor example the following Cassandra table:

CREATE TABLE agents1 ( agentid int PRIMARY KEY, email varchar, contact tuple<varchar,varchar,varchar>);

The following agents1 table is a tabular representation of the native Cassandra table with data included.

Table 7: agents1 (native)

contactemailagentid

(primary key)

tuple<varchar, varchar, varchar>varcharint

tv

newspaper

blog

[email protected]

radio

tv

magazine

[email protected]

For the relational version of agents1, all fields are retained as separate columns, and columns with primitivetypes (agentid and email) correspond directly to columns in the native table. In turn, tuple fields are flattenedinto columns using a <tuplename>_<ordinal> naming pattern. The driver normalizes agents1 in thefollowing manner.

Table 8: agents1 (relational)

contact_3contact_2contact_1emailagentid

(primary key)

varcharvarcharvarcharvarcharint

[email protected]

[email protected]



A SQL command would take the following form:

INSERT INTO agents1 (agentid,email,contact_1,contact_2,contact_3) VALUES (839,'[email protected]','radio','tv','magazine')

The driver also flattens user-defined types when normalizing native Cassandra tables. In the following example,the native Cassandra agents2 table incorporates the user-defined address type.

CREATE TYPE address ( street varchar, city varchar, state varchar, zip int);CREATE TABLE agents2 ( agentid int PRIMARY KEY, email varchar, location frozen<address>);

The following agents2 table is a tabular representation of the native Cassandra table with data included.


locationemailagentid

(primary key)

address<street: varchar, city: varchar,state: varchar, zip: int>

varcharint

street: 1551 Main Street

city: Pittsburgh

state: PA

zip: 15237

[email protected]

street: 422 First Street

city: Richmond

state: VA

zip: 23235

[email protected]

As with the previous example, all fields are retained as separate columns in the relational version of the table,and columns with primitive types (agentid and email) correspond directly to columns in the native table.Here a <columnname>_<fieldname> naming pattern is used to flatten the fields of the user-defined addresstype into columns. The driver normalizes agents2 in the following manner.




location_ziplocation_statelocation_citylocation_streetemailagentid

(primary key)

intvarcharvarcharvarcharvarcharint

15237PAPittsburgh1551 MainStreet

[email protected]

23235VARichmond422 FirstStreet

[email protected]

A SQL command would take the following form:

INSERT INTO agents2 (agentid,email,location_street,location_city,location_state,location_zip) VALUES (839,'[email protected]','9 Fifth Street', 'Morrisville', 'NC', 27566)

Nested Complex Types

The nesting of complex types within Tuple and user-defined types is permitted in CQL. The driver does notnormalize such nested types, but rather the data is passed as a JSON-style string. For example, consider thetable contacts which contains the columns id and contact. While id is a primitive int column, contactis a user-defined info column which contains name, email, and location fields. The location field itselfis a nested user-defined address column which contains street, city, state, and zip fields. In CQL, thestructure of this table would take the following form:

CREATE TYPE address ( street varchar, city varchar, state varchar, zip int);CREATE TYPE info ( name varchar, email varchar, location frozen<address>);CREATE TABLE contacts ( id int PRIMARY KEY, contact frozen<info>);

The following tabular representation of the contacts table shows how the driver returns data when complextypes are nested in other complex types. Because the complex user-defined type address is embedded inthe complex user-defined type info, the entire contact column is returned by the driver as a JSON string.

Note: You can retrieve this string data by calling the DatabaseMetaData.getColumns() method.



Table 11: contacts (relational)

contactid

(primary key)

info<name: varchar, email: varchar, location: address<street: varchar, city:varchar, state: varchar, zip: int>>

int

{name: 'Jude', email: '[email protected]', location: {street:'101 Main Street', city: 'Albany', state:'NY', zip: 12210}}

034

{name: 'Karen', email: '[email protected]', location: {street:'150 First Street', city: 'Portland', state: 'OR', zip: 97214}}

056

When executing SQL commands involving nested complex types, the data must be passed as a JSON string.Furthermore, the syntax you use to connote the JSON string depends on whether you are passing the stringdirectly in a SQL command or binding the JSON string as a parameter to a variable in the application.

Note: Hints for parsing JSON-style strings are provided in the Remark column of the getColumns() result.

Connoting the JSON-Style String in a SQL StatementWhen passing the string directly in a SQL command, you must use the correct SQL syntax and escapes tomaintain the structure of the data. To begin, the entire JSON string must be passed in single quotation marks('). Furthermore, if the JSON string contains nested strings, two single quotation marks are used to indicatestring values. The first quotation mark is an escape connoting the second embedded quotation mark. Thefollowing command inserts a new row into the contacts table.

Note: In accordance with typical programming language syntax, the Insert statement is placed in doublequotation marks. However, in the JSON string, two single quotation marks are used to indicate string values.The first quotation mark is an escape connoting the second embedded quotation mark.

SQLExecDirect( pstmt, "INSERT INTO contacts (id, contact)VALUES (075, '{name: ''Albert'', email: ''[email protected]'', location: {street: ''12 North Street'', city: ''Durham'', state:''NC'', zip: 27704}}')", SQL_NTS);

After the insert has been executed, the Select command SELECT contact FROM contacts WHERE id= 75 returns:

{name: 'Albert',email: '[email protected]',location: {street: '12 North Street', city: 'Durham', state:'NC', zip: 27704 }}



Connoting the JSON-Style String as a Parameter VariableWhen binding the JSON string as a parameter to a variable in the application, you must follow your programminglanguage syntax by placing the JSON string in double quotation marks. Escapes are not used to connoteembedded single quotation marks. For example:

STRING string_variable = "{name: 'Albert', email: '[email protected]', location: {street: '12 North Street', city: 'Durham', state:'NC', zip: 27704}}"

Isolation and Lock Levels SupportedThe driver supports isolation level 0 (Read Uncommitted).

See alsoLocking and Isolation Levels on page 203Transaction Mode on page 129

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 Apache Cassandra driver.


• Unicode Support

• Using IP Addresses

• Parameter Metadata Support

• SQL Support

• Number of Connections and Statements Supported

Unicode SupportThe driver is fully Unicode enabled. On UNIX and Linux platforms, the driver supports both UTF-8 and UTF-16.On Windows platforms, the driver supports UCS-2/UTF-16 only.

The driver supports the Unicode ODBC W (Wide) function calls, such as SQLConnectW.This allows the DriverManager to transmit these calls directly to the driver. Otherwise, the Driver Manager would incur the additionaloverhead of converting the W calls to ANSI function calls, and vice versa.

See "UTF-16 Applications on UNIX and Linux" for related details. Also, see "Internationalization, Localizationand Unicode" for a more detailed explanation of Unicode.


See alsoUTF-16 Applications on UNIX and Linux on page 60Internationalization, Localization, and Unicode on page 179

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 Apache Cassandra server is specified inIPv6 format:

DRIVER=DataDirect Apache Cassandra Driver;HostName=2001:DB8:0000:0000:8:800:200C:417A;PORT=9042;KN=CASSANDRAKEYSPACE2;UID=JOHN;PWD=XYZZYYou;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_Schema\MainServer.config

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

DRIVER=DataDirect Apache Cassandra Driver;HostName=2001:DB8:0:0:8:800:200C:417A;PORT=9042;KN=CASSANDRAKEYSPACE2;UID=JOHN;PWD=XYZZYYou;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_Schema\MainServer.config

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

DRIVER=DataDirect Apache Cassandra Driver;HostName=2001:DB8:0:0:8:800:123.456.78.90;PORT=9042;DB=CASSANDRAKEYSPACE2;UID=JOHN;PWD=XYZZYYou;SchemaMap=C:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_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 Apache Cassandra driver provides support for standard SQL (primarily SQL 92), and a set of SQLextensions.

See alsoSupported SQL Functionality on page 133

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


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

• Performance Considerations

• Using the SQL Engine Server

• Using Failover in a Cluster

• Using Identifiers

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 17Using a Connection String on page 74

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 52

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 55

ODBCINST

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

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 58

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 55

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 driversand help diagnose configuration problems in the UNIX and Linux environments, such as environment variablesnot correctly set or missing database client components. This tool is installed in the /bin subdirectory in theproduct installation directory. It attempts to load a specified ODBC driver and prints out all available errorinformation if the load fails.

The test loading tool is provided to test load drivers and help diagnose configuration problems in the UNIX andLinux environments, such as environment variables not correctly set or missing database client components.This tool is installed in the bin subdirectory in the product installation directory. It attempts to load a specifiedODBC driver and prints out all available error information if 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:



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.



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 34

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.

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

Apache Cassandra=DataDirect 8.0 Apache Cassandra 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, [Apache Cassandra]. The data source definitions contain connection stringattribute=value pairs with default values.You can modify these values as appropriate for your system."Connection Option Descriptions" describes these attributes. See "Sample Default odbc.ini File" for sampledata 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 "IANAAAppCodePage" in "Connection Option Descriptions"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 theinstallation directory under which the /lib and /locale directories are contained. The installation processautomatically writes 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 alsoConnection Option Descriptions on page 101Sample Default odbc.ini File on page 56File Data Sources on page 59IANAAppCodePage on page 114Code Page Values on page 163DSN-less Connections on page 58ODBC Trace on page 85

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 dd andthe list of data sources would include only the 64-bit drivers.

[ODBC Data Sources]Apache Cassandra=DataDirect 8.0 Apache Cassandra

[Apache Cassandra]Driver=ODBCHOME/lib/ivcsndr28.soDescription=DataDirect 8.0 Apache Cassandra ApplicationUsingThreads=1AsciiSize=4000AuthenticationMethod=0ClusterNodes=ConfigOptions=CreateMap=2DataSourceName=DecimalPrecision=38DecimalScale=10 FetchSize=100HostName=



InitializationString=JVMArgs=-Xmx256m JVMClasspath=KeySpaceName=LogConfigFile=LoginTimeout=15LogonID=NativeFetchSize=10000Password=PortNumber=9042ReadConsistency=4ReadOnly=1ReportCodepageConversionErrors=0ResultMemorySize=-1SchemaMap=ServerPortNumber=19934SQLEngineMode=0TransactionMode=0VarcharSize=4000VarintPrecision=38WriteConsistency=4

[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 "Apache Cassandra Attribute Names" table in "Connection Option Descriptions" for otherspecific attribute values.

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

Important: The "Apache Cassandra Attribute Names" table in "Connection Option Descriptions" listsboth the long and short names of the attribute.When entering attribute names into odbc.ini, you mustuse 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, [Apache Cassandra].

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 "Apache Cassandra Attribute Names" table in "Connection Option Descriptions" for otherspecific attribute values.

e) In the [ODBC] section at the beginning of the file, add a new data_source_name=installed-driverpair containing 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 "Apache Cassandra Attribute Names" table in "Connection Option Descriptions" listsboth the long and short name of the attribute. When entering attribute names into odbc.ini, you mustuse the long name of the attribute. The short name is not valid in the odbc.ini file.

See alsoConnection Option Descriptions on page 101

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 in aconnection 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.

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

DataDirect 8.0 Apache Cassandra Driver=Installed

This section also includes additional information for each driver.

The next section of the file is named [Administrator]. The keyword in this section,AdminHelpRootDirectory, is required for the Linux ODBC Administrator to locate its help system. Theinstallation process automatically provides the correct value for this keyword.

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.



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

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

See alsoODBCINST on page 53Configuration Through the System Information (odbc.ini) File on page 55

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 Apache Cassandra=Installed

[DataDirect 8.0 Apache Cassandra]Driver=ODBCHOME/lib/ivcsndr28.soJarFile=ODBCHOME/java/lib/cassandra.jarAPILevel=1ConnectFunctions=YYYCPTimeout=60DriverODBCVer=3.52FileUsage=0HelpRootDirectory=ODBCHOME/CassandraHelpSetup=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 Apache Cassandra Port=9042HostName=Cassandra2



KeyspaceName=CassandraKeyspace2SchemaMap=/home/users/jsmith/Progress/DataDirect/Cassandra_Schema/Cassandra2.configLogonID=jsmith

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

or, on UNIX and Linux:

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

See alsoGetting Started on page 17DSN-less Connections on page 58Data Source Configuration on UNIX/Linux on page 55

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



Data Source Configuration Using a GUI

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

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 Apache Cassandra 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 109

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 111

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

Default: NoneHost Name on page 113

Specifies the port number of the server listener.

Default: 9042Port Number on page 121



DescriptionConnection Options: General

Specifies the name of the keyspace to which you want to connect.

Default: systemKeyspace Name on page 117

A comma-separated list of member nodes in your cluster to which thedriver attempts to connect. Specifying a value for this option enablesconnect time failover and load balancing.

Default: None

Cluster Nodes on page 106

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

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

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

• Advanced tab allows you to configure advanced behavior.

• Schema Map tab allows you to configure mapping behavior.

• Security tab allows you to configure security settings.

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

See alsoUsing a Logon Dialog Box on page 75



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

DefaultConnection Options: SQLEngine

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

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

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

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

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

Default: 0 - Auto

SQL Engine Mode on page 128

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 115

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 116

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 13: 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: 19934

For the 64-bit driver: 19933

Server Port Number on page127

Specifies fully qualified path to the JVM executable that you want to use to runthe SQL Engine Server. The path must not contain double quotation marks.

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

Java Path

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

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




See alsoData Source Configuration Using a GUI on page 61



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

If set to 0 - No, the driver uses the current group of internal files specified bythe Schema Map connection option. If the files do not exist, the connection fails.

If set to 1 - ForceNew, the driver deletes the current group of files specified bythe Schema Map connection option and creates new files in the same location.

If set to 2 - NotExist, the driver uses the current group of files specified by theSchema Map connection option. If the files do not exist, the driver creates them.

Default: 2 - NotExist

Create Map on page 108




Specifies how the driver handles manual transactions.

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

If set to 1 - Ignore, the data source does not support transactions and the driveralways operates in auto-commit mode.

Default: 0 - No Transactions

Transaction Mode on page129

Specifies how many replicas must respond to a read request before returningdata to the client application.

If set to 1 - one, data is returned from the closest replica. This setting providesthe highest availability, but increases the likelihood of stale data being read.

If set to 4 - quorum, data is returned after a quorum of replicas has respondedfrom any data center.

If set to 5 - all, data is returned to the application after all replicas haveresponded.This setting provides the highest consistency and lowest availability.

Default: 4 - quorum

Read Consistency on page122

Determines the number of replicas on which the write must succeed beforereturning an acknowledgment to the client application.

If set to 1 - one, a write must succeed on at least one replica node.

If set to 4 - quorum, a write must succeed on a quorum of replica nodes.

If set to 5 - all, a write must succeed on all replica nodes in the cluster for thatpartition key.This setting provides the highest consistency and lowest availability.

Default: 4 - quorum

Write Consistency on page131

Determines whether the driver works with applications using multiple ODBCthreads.

If disabled, the driver does not work with multi-threaded applications. If usingthe driver with single-threaded applications, this value avoids additionalprocessing required for ODBC thread-safety standards.

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

Default: Enabled

Application Using Threadson page 104

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 can use allcommands supported by the product.

Default: Disabled

Read Only on page 123




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

Default: 15

Login Timeout on page 119

Specifies the number of rows that the driver processes before returning data tothe application when executing a Select.

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

If set to x, the driver limits the number of rows that may be processed andreturned to the application for a single fetch request.

Default: 100

Fetch Size on page 112

Specifies the number of rows of data the driver attempts to fetch from the nativedata source on each request submitted to the server.

If set to 0, the driver requests that the server return all rows for each requestsubmitted to the server. Block fetching is not used.

If set to x, the driver attempts to fetch up to a maximum of the specified numberof rows on each request submitted to the server.

Default: 10000

Native Fetch Size on page119

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

If set to -1, the maximum size of an intermediate result set that the driver holdsin memory is determined by a percentage of the max Java heap size. Whenthis threshold is reached, the driver writes a portion of the result set to disk.

If set to 0, the driver holds intermediate results in memory regardless of size.Setting Result Memory Size to 0 can increase performance for any result setthat can easily fit within the JVM's free heap space, but can decreaseperformance for any result set that can barely fit within the JVM's free heapspace.

If set to x, the driver holds intermediate results in memory that are no largerthan the size specified. When this threshold is reached, the driver writes aportion of the result set to disk.

Default: -1

Result Memory Size on page124




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

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

If set to 1 - Return Error, the driver returns an error instead of substituting 0x1Afor unconverted characters.

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

Default: 0 - Ignore Errors

Report CodepageConversion Errors on page124

Specifies the filename of the configuration file used to initialize the driver loggingmechanism.

Default: ddlogging.properties

Log Config File on page 118

One or multiple SQL commands to be executed by the driver after it hasestablished the connection to the database and has performed all initializationfor the connection. If the execution of a SQL command fails, the connectionattempt also fails and the driver returns an error indicating which SQL commandor commands failed.

Default: None

Initialization String on page115

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 Customer Support.You can include any valid connection option in the Extended Options string, forexample:

KeyspaceName=mykeyspace;UndocumentedOption1=value [;UndocumentedOption2=value;]

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

If you finished configuring your driver, proceed to Step 6 on page 63 in "Data Source Configuration 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:








Schema Map TabThe Schema Map tab allows you to configure the options that control the relational mapping of your data. Thefields are optional unless otherwise noted. On this tab, provide values for the options in the following table;then, click Apply.

Figure 4: Schema Map tab


Specifies the name and location of the configuration file where the relationalmap of native data is written. The driver looks for this file when connecting to aserver. If the file does not exist, the driver creates one.

Default:


Schema Map on page 126

Specifies the precision reported for ASCII columns in column and result-setmetadata.

Default: 4000

Ascii Size on page 105




Specifies the precision reported for Varchar columns in column and result-setmetadata.

Default: 4000

Varchar Size on page 130

Specifies the precision reported for Decimal columns in column and result-setmetadata.

Default: 38

Decimal Precision on page110

Specifies the maximum scale reported for Decimal columns in column andresult-set metadata.

Default: 10

Decimal Scale on page 110

Specifies the precision reported for Varint columns in column and result-setmetadata.

Default: 38

Varint Precision on page 130

Note: The Config Options connection option is not currently supported by thedriver.

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

Default:None

Config Options on page 107









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

Figure 5: Security tab


The default user ID that is used to connect to your database.

Default: None

User Name on page 129

Specifies the method the driver uses to authenticate the user to the server whena connection is established. If the specified authentication method is notsupported by the database server, the connection fails and the driver generatesan error.

If set to -1 - No Authentication, the driver sends the user ID and password inclear text to the server for authentication.

If set to 0 - User ID/Password, the driver sends the user ID in clear text andan encrypted password to the server for authentication.

Default: 0 - User ID/Password

Authentication Method onpage 106









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 Apache Cassandra forLinux/UNIX/Windows is:

DSN=Apache Cassandra;UID=JOHN;PWD=XYZZY

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

FILEDSN=Apache Cassandra;UID=JOHN;PWD=XYZZY

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

DRIVER=DataDirect Apache Cassandra;UID=JOHN;PWD=XYZZY;HOST=CassandraServer;PORT=9042;DB=Cassandra1;SM=/home/users/jsmith/Progress/DataDirect/Cassandra_Schema/CassandraServer.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 6: Logon to Apache Cassandra 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 Map field, type the name and location of the configuration file where the relational map ofnative data is written. See "Schema Map" for details.

4. In the Keyspace Name field, type the name of the keyspace to which you want connect.

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

6. Type your password in the Password field.

7. From the Authentication Method drop-down box, select one the following:

• For no authentication, select -1 - No Authentication.

• To authenticate by passing the user ID in clear text and an encrypted password, select 0 - UserID/Password.

8. Click OK to complete the logon.




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.

Fetch Size (FetchSize) and Native Fetch Size (NativeFetchSize): The connection options Fetch Size andNative Fetch Size can be used to adjust the trade-off between throughput and response time. In general, settinglarger values for Fetch Size and Native Fetch Size will improve throughput, but can reduce response time.

For example, if an application attempts to fetch 100,000 rows from the native data source and Native FetchSize is set to 500, the driver must make 200 round trips across the network to get the 100,000 rows. If, however,Native Fetch Size is set to 10000, the driver only needs to make 10 round trips to retrieve 100,000 rows.Network round trips are expensive, so generally, minimizing these round trips increases throughput.

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

Note: Fetch Size provides a suggestion to the driver as to the number of rows it should internally processbefore returning control to the application.The driver may fetch fewer rows to conserve memory when processingexceptionally 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, increasing the max Java heap size can improve performance by reducing the need to writeto disk, or removing it altogether.

Read Consistency (ReadConsistency): The Read Consistency connection option manages the trade-offbetween the consistency and availability of your data. By setting Read Consistency to all, data is returnedto the application only after all replicas have responded.With this setting, the data returned is highly consistent.However, it may take longer for data to be returned to the application, and, in some scenarios, operationtimeouts can occur. In contrast, setting Read Consistency to quorum (default) or one reduces the number ofreplicas required to respond to a read request. While the data may not be as consistent, results are returnedmore quickly to the application.

Result Memory Size (ResultMemorySize): Result Memory Size can affect performance in two main ways.First, if the size of the result set is larger than the value specified for Result Memory Size, the driver writes aportion of the result set to disk. Since writing to disk is an expensive operation, performance losses will beincurred. Second, when you remove any limit on the size of an intermediate result set by setting Result MemorySize to 0, you can realize performance gains for result sets that easily fit within the JVM's free heap space.However, the same setting can diminish performance for result sets that barely fit within the JVM's free heapspace.



Write Consistency (WriteConsistency): The Write Consistency connection option determines the numberof replicas on which the write must succeed before returning an acknowledgment to the client application. Bysetting this option to all, a write must succeed on all replica nodes in the cluster for that partition key. Thissetting provides high consistency. However, it may take longer for the successful execution of a write operation.In contrast, setting Write Consistency to quorum (default) or one reduces the number of replicas that mustacknowledge the completion of a write command. While the data may not be as consistent across clusters,the write operation is completed more quickly.

See alsoApplication Using Threads on page 104Fetch Size on page 112Native Fetch Size on page 119JVM Arguments on page 115Read Consistency on page 122Result Memory Size on page 124Write Consistency on page 131

Using the SQL Engine ServerSome applications may experience problems loading the JVM required for the SQL engine because the processexceeds the available heap space. If your application experiences problems loading the JVM, you can configurethe driver to operate in server mode.

In direct mode, the driver operates with the SQL engine and JVM running in a single process. While in servermode, the driver's SQL engine runs in a separate process with its own JVM instead of trying to load the SQLengine and JVM in the same process used by the driver.

For Windows, the driver is configured to attempt to run in server mode first by default. However, if server modeis unavailable, the SQL engine will failover to run in direct mode. For non-Windows platforms, the driver operatesin direct mode by default.

Note: You must be an administrator to start or stop the service, or to configure any settings for the service.

See the following sections for details on configuring the SQL Engine Server on your platform.

Configuring the SQL Engine Server on Windows

The following sections describe how to configure, start, and stop the SQL Engine Server on Windows platforms.

On Windows, the driver is configured to run in Auto mode by default. This means that driver attempts to run inserver mode first; however, if server mode is unavailable, the SQL engine will failover to run in direct mode.

Configuring Server Mode on Windows

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.


Using the SQL Engine Server

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 Cassandra SQL Engine Service Setup dialog box. Use thisdialog box to define settings for Server Mode and to start and stop the Progress DataDirect Cassandra 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 19933 for 64-bit installations and 19934 for 32-bit installations. See"Server Port Number" for more information.

Java Path: Specifies fully qualified path to the Java SE 6 or higher JVM executable that you want to useto run the SQL Engine Server. The path must not contain double quotation marks.

Services: Shows the Cassandra ODBC SQL engine service that runs as a separate process instead ofbeing loaded within the process of an ODBC application.

Start (Stop): Starts or stops the Cassandra service. A message window is displayed, confirming that theCassandra service was started or stopped.

Apply: Applies the changes.

3. When you complete your changes, click Apply.

4. Click OK to save the changes and return to the SQL Engine tab or click Cancel.



See alsoJVM Arguments on page 115JVM Classpath on page 116Server Port Number on page 127

Starting the SQL Engine Server on WindowsIn 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 cassandra.jar file in the installation directory.

To start the SQL engine server:

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

2. Select a tab:

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

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

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

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

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

If you are configuring a new file data source, click Add to display a list of installed drivers; then, select adriver. Click Advanced if you want to specify attributes; otherwise, click Next to proceed. Specify a namefor the data source and click Next.Verify the data source information; then, click Finish to display the driverSetup dialog box.

3. On the ODBC Cassandra Driver Setup dialog box, select the SQL Engine tab; then, select 0 - Auto or 1-Server from the SQL Engine Mode drop-down list.


4. Click Edit Server Settings.

5. When you complete your changes, click Apply.

6. Verify that Progress DataDirect Cassandra 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 Cassandra 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 Cassandra SQL Engine Service Setupdialog box.

Stopping the SQL Engine Server on WindowsTo stop the SQL engine server:

1. Open the ODBC Cassandra Driver Setup dialog box and select the SQL Engine tab.

2. Select 0 - Auto or 1 - Server from the SQL Engine Mode drop-down list. Then, click Edit Server Settings.


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 Cassandra SQL Engine Service Setup dialog box.

Configuring the SQL Engine Server on UNIX/Linux

The following sections describe how to configure, start, and stop the SQL Engine Server on UNIX and Linuxplatforms.

By default, the driver operates in direct mode by default on UNIX and Linux platforms.

Configuring and Starting the SQL Engine Server on UNIX/LinuxIn server mode, you must start the SQL engine server before using the driver. Be aware that you must havepermissions to write to the directory specified by the SchemaMap option to start the SQL engine server.

To configure the SQL engine server, specify values for the Java options in the following JVM argument:

java -Xmx<heap_size>m -cp "<jvm_classpath>" com.ddtek.cassandracloud.sql.Server -port <port_number> -Dhttp.proxyHost=<proxy_host> -Dhttp.proxPort=<proxy_port>-Dhttp.proxyUser=<proxy_user> -Dhttp.proxyPassword=<proxy_password>

See the "SQL Engine Server Java Options" table for a description of these options.

For example:

java -Xmx1024m -cp "/opt/Progress/DataDirect/ODBC_80_64bit/java/lib/cassandra.jar" com.ddtek.cassandracloud.sql.Server -port 19933 [email protected] -Dhttp.proxPort=12345 -Dhttp.proxyUser=JohnQPublic -Dhttp.proxyPassword=secret

To start the SQL engine service, execute the JVM Argument after configuring the Java options. A confirmationmessage is returned once the server is online.



Table 14: SQL Engine Server Java Options

DescriptionJava Option

Required Java Options

Specifies the CLASSPATH for the Java Virtual Machine (JVM) used by the driver.The CLASSPATH is the search string the JVM uses to locate the Java jar files thedriver needs. The Cassandra driver's JVM is located on the following path:

install_dir/java/lib/cassandra.jar

-cp

Specifies a valid port on which the SQL engine listens for requests from the driver.We recommend specifying one of the following values:

• 19934 (32-bit drivers)

• 19933 (64-bit drivers)

-port

Optional Java Options

Specifies the maximum memory heap size, in megabytes, for the JVM. The defaultsize is determined by your JVM. We recommend specifying a size no smaller than1024.

Note: Although this option is not required to start the SQL engine server, we highlyrecommend specifying a value.

-Xmx

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

-Dhttp.proxyHost

Specifies the port number where the Proxy Server is listening for HTTP and/orHTTPS requests.

-Dhttp.proxyPort

Specifies the user name needed to connect to the Proxy Server.-Dhttp.proxyUser

Specifies the password needed to connect to the Proxy Server.-Dhttp.proxyPassword

Stopping the SQL Engine Server on UNIX/LinuxTo stop the SQL engine server, choose one of the following:

• Using an application, execute SHUTDOWN SQL.

• From a command line, press Ctrl + C.

If successful, a message is returned to confirm that the service has stopped.



Configuring Java Logging for the SQL Engine Server

Java logging can be configured by placing a logging configuration file named ddlog.properties in thedirectory specified by the SchemaMap option (see "Schema Map" for details). The simple way to create oneof these is to make a copy of the ddlog.properties file, which is located in your driver installation directory,in the install_dir/Sample/Example subdirectory. For more information on logging in Cassandra, see"Configuring Logging."

See alsoSchema Map on page 126Configuring Logging on page 91

Using Failover in a ClusterTo ensure availability to Cassandra data sources, the driver supports connection failover and client loadbalancing when connecting to clusters:

• Connection failover provides protection for new connections to a cluster. If a member node of the clusteris unavailable, for example, because of hardware failure or traffic overload, the driver fails over to anothermember node to attempt the connection. If a connection to a node is dropped, the driver does not fail overthe connection.

• Client load balancing helps distribute new connections in your environment so that no one server isoverwhelmed with connection requests. When client load balancing is enabled, the order in which membernodes are tried is random.

You can enable connection failover and load balancing by specifying a list of the member nodes for your clusterusing the Cluster Nodes (ClusterNodes) option. The list should be comprised of a comma-separated servernames or IP addresses for your member nodes and their corresponding port numbers. Note that IPv6 valuesmust be wrapped in double quotation marks. For example:

ClusterNodes=server1:9042,255.125.1.11:9043,"2001:DB8:0000:0000:8:800:200C:417A":9044

Note: Specifying a value for the Cluster Nodes option can be used in place of or in addition to the values ofthe Host Name (HostName) and Port Number (PortNumber) options. If values are specified all of these options,the node specified by the Host Name and Port Number are included in the list of nodes to which the driverrandomly attempts to connect.

When connection failover and load balancing are enabled, the driver randomly selects a node from the list tofirst attempt a connection. If that connection fails, the driver again randomly selects another node from this listuntil all the nodes in the list have been tried or a connection is successfully established.

See alsoCluster Nodes on page 106



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 48 characters for table names and 128 characters for column names. Quoted identifiers must beenclosed in double quotation marks ("").The characters supported in quoted identifiers depends on the versionof Cassandra being used. For details on valid characters, refer to the Cassandra documentation for yourdatabase version.

Naming conflicts can arise from restrictions imposed by third party applications, from the normalization of nativedata, or from the truncation of object names. The driver avoids naming conflicts by appending an underscoreseparator and integer (for example, _1) to identifiers with the same name. For example, if a third party applicationrestricts the naming of three columns such that each column retains the name address, the driver wouldexpose the columns in the following manner:

• address

• address_1

• address_2


Using Identifiers



6Troubleshooting

This part guides you through troubleshooting your Progress DataDirect for ODBC for Apache Cassandra driver.It provides you 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 86

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:





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.

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

See alsoEnvironment Variables on page 52Version String Information on page 34

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 Apache Cassandra provides a flexible and comprehensive logging mechanism of its Javacomponents that allows logging to be incorporated seamlessly with the logging of your application or enabledand configured independently from the application.The logging mechanism can be instrumental in investigatingand diagnosing issues. It also provides valuable insight into the type and number of operations requested bythe application from the driver and requested by the driver from the remote data source. This information canhelp you tune and 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 Apache Cassandra specific query being executed. The actual data sent orfetched is not 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 91 for details.

• Using the driver. See Using the Driver on page 92 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 Apache Cassandra connections.

• Use a different properties file for each schema map. For example, if you have two definitions (johnsmith.xxxand pattijohnson.xxx, for example), you can load one properties file for the johnsmith.xxx database andload another properties file for the pattijohnson.xxx database.

Note: By default, the name of the schema map is the user ID specified for the connection.You can specifythe name of the schema map using the SchemaMap attribute. See "Connection Option Descriptions" for detailson using LogConfigFile and other connection options.

By default, the driver looks for the file named ddlogging.properties in the current working directory toload for all Apache Cassandra connections. If the SQLEngineMode connection option is set to Server, thedriver uses the ddlogging.properties file that is specified by the SchemaMap 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 92, it looks for a properties file nameddatabase_name.logging.properties in the directory containing the embedded database for theconnection, where database_name is the name of the embedded database.

3. If the driver cannot find the file in Step 2 on page 92, 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 92, 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 demoodbc Application

DataDirect provides a simple C application, named demoodbc, that is useful for:

• Executing SELECT * FROM emp, where emp is a database table.The scripts for building the emp databasetables (one for each supported database) are in the demo subdirectory in the product installation directory.

• Testing database connections.

• Creating reproducibles.

• Persisting data to an XML data file.



The demoodbc application is installed in the /samples/demo subdirectory in the product installation directory.Refer to demoodbc.txt or demoodbc64.txt in the demo directory for an explanation of how to build anduse this application.

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 Apache Cassandra driver would look like this:

[DataDirect] [ODBC Apache Cassandra 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.


Error Messages

https://www.progress.com/support/evaluation/download-resources/download-tools

http://progresscustomersupport-survey.force.com/ConnectKB

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 Apache Cassandra database:

[DataDirect] [ODBC Apache Cassandra Driver] [Apache Cassandra] Specified length too long for CHAR column

This type of error is generated by the database system. Check your Apache Cassandra system documentationfor more information 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

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 Apache Cassandra require that you set the library path environmentfor your operating system to the directory containing your 32-bit JVM’s libjvm.so [sl | a] file, and thatdirectory’s parent 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


Troubleshooting

64-bit Drivers

• PATH on Windows

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

• LIBPATH on AIX

• The database and/or listener are not started.

• The ODBCINI environment variable is not set correctly for the ODBC drivers on UNIX and Linux.

• The ODBC driver’s connection attributes are not set correctly in the system information file on UNIX andLinux. See "Data Source Configuration on UNIX/Linux" for more information. For example, the host nameor port number are not correctly configured. See "Connection Option Descriptions" for a list of connectionstring attributes that are required for each driver to connect properly to the underlying database.

For UNIX and Linux users: See "Configuring the Product on UNIX/Linux" for more information. Seealso "The Test Loading Tool" for information about a helpful diagnostic tool.

See alsoData Source Configuration on UNIX/Linux on page 55Connection Option Descriptions on page 101Configuring the Product on UNIX/Linux on page 52The Test Loading Tool on page 88

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 23

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 89The Example Application on page 93ODBC Trace on page 85

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 189

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 FetchSize, 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.


Troubleshooting

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

See alsoFetch Size on page 112Result Memory Size on page 124JVM Arguments on page 115

Operation Timeouts

Cassandra imposes timeouts on read and write operations to prevent a given operation from negatively impactingthe performance of the cluster. If you encounter an operation timeout, you can take the following actions topromote operation success.

• Adjust the ReadConsistency connection property.You can speed up a query by reducing the number ofreplicas required to respond to a read request. Therefore, you can reduce the likelihood of a timeout bysetting ReadConsistency to a value that requires fewer replicas to respond.

• Adjust the WriteConsistency connection property.You can speed up a write operation by reducing thenumber of replicas required to acknowledge success. Therefore, you can reduce the likelihood of a timeoutby setting WriteConsistency to a value that requires fewer replicas to acknowledge the execution of thewrite operation.

• Decrease the value of the NativeFetchSize connection property. By decreasing NativeFetchSize, you reducethe amount of data that must be transmitted between the driver and the native data source. For readoperations, the smaller the chunks of data requested, the faster the cluster can assemble results fortransmission to the driver. For write operations, smaller chunks of data allow the driver to communicatemore efficiently with the native data source and thus expedite write operations.

Note: Setting NativeFetchSize too low negatively impacts performance by requiring unnecessary roundtrips across the network.

• Optimize your query by taking one or more of the following actions.

1. Limit the number of results returned.

2. Add indexes to Cassandra tables and base operations on indexes as appropriate.

3. Use Where clause filtering that can be pushed down to Cassandra, allowing operations to be evaluatedand handled quickly. Refer to the following DataStax Web pages for more information about Whereclause functionality and limitations.



• A deep look at the CQL WHERE clause

• Filtering data using WHERE

• Adjust Cassandra network timeout settings in the cassandra.yaml configuration file. These settings canbe adjusted to promote read operation success by increasing the size of the timeout window. Refer to yourApache Cassandra documentation for details.

See alsoRead Consistency on page 122Write Consistency on page 131Native Fetch Size on page 119Where Clause on page 143


Troubleshooting

http://www.datastax.com/dev/blog/a-deep-look-to-the-cql-where-clause

http://docs.datastax.com/en/cql/3.1/cql/cql_reference/select_r.html?scroll=reference_ds_d35_v2q_xj__filtering-data-using-where



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 Apache Cassandra.

Table 15: Apache Cassandra Attribute Names

DefaultAttribute (Short Name)

1 (Enabled)ApplicationUsingThreads (AUT)

4000AsciiSize (ASZ)

0 (User Id/Password)AuthenticationMethod (AM)

NoneClusterNodes (CN)



Note: The ConfigOptions connection option is notcurrently supported by the driver.

None

ConfigOptions (CO)

2 (NotExist)CreateMap (CM)

NoneDataSourceName (DSN)

38DecimalPrecision (DP)

10DecimalScale (DS)

NoneDescription (n/a)

100 (rows)FetchSize (FS)

NoneHostName (HOST)

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 setto 2 (Direct):

-Xmx256m

For all other configurations:

-Xmx1024m

JVMArgs (JVMA)

The default is an empty string, which means that thedriver automatically detects the CLASSPATHs for allODBC drivers installed on your machine and specifiesthem when launching the JVM.

JVMClasspath (JVMC)

systemKeyspaceName (KN)

NoneLogConfigFile (LCF)

15LoginTimeout (LT)

NoneLogonID (UID)

10000 (rows)NativeFetchSize (NFS)

NonePassword (PWD)

9042PortNumber (PORT)


Chapter 7: Connection Option Descriptions


4 (quorum)ReadConsistency (RC)

1 (Enabled)ReadOnly (RO)

0 (Ignore Errors)ReportCodepageConversionErrors (RCCE)

-1ResultMemorySize (RMS)

For Windows:


For UNIX/Linux:

users_home_directory/Progress/DataDirect/Cassandra_Schema/host_name.config

SchemaMap (SM)

For the 32-bit driver:

19936


19935

ServerPortNumber (SPN)

For Windows:

0 (Auto)

For UNIX/Linux:

2 (Direct)

SQLEngineMode (SEM)

0 (No Transactions)TransactionMode (TM)

4000VarcharSize (VCS)

38VarintPrecision (VP)

4 (quorum)WriteConsistency (WC)


• Application Using Threads

• Ascii Size

• Authentication Method

• Cluster Nodes

• Config Options

• Create Map

• Data Source Name

• Decimal Precision


• Decimal Scale

• Description

• Fetch Size

• Host Name

• IANAAppCodePage

• Initialization String

• JVM Arguments

• JVM Classpath

• Keyspace Name

• Log Config File

• Login Timeout

• Native Fetch Size

• Password

• Port Number

• Query Timeout

• Read Consistency

• Read Only

• Report Codepage Conversion Errors

• Result Memory Size

• Schema Map

• Server Port Number

• SQL Engine Mode

• Transaction Mode

• User Name

• Varchar Size

• Varint Precision

• Write Consistency

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 76

Ascii Size

AttributeAsciiSize (ASZ)

PurposeSpecifies the precision reported for ASCII columns in column and result-set metadata. This option allows youto set the precision for ASCII columns when using an application that does not support unbounded data types.

Valid Valuesx

where:

x

is an integer greater than 0 (zero).

Default4000


Ascii Size

Notes

• In most scenarios, an error is returned if the size of an ASCII value specified in a statement exceeds theprecision determined by this option. However, when executing a Select statement, the driver will return datacontaining values that are larger than the specified precision.

GUI TabSchema Map tab

Authentication Method

AttributeAuthenticationMethod (AM)

PurposeSpecifies the method the driver uses to authenticate the user to the server when a connection is established.If the specified authentication method is not supported by the database server, the connection fails and thedriver generates an error.

Valid Values-1 | 0

BehaviorIf set to -1 (No Authentication), the driver does not attempt to authenticate with the server.

If set to 0 (User ID/Password), the driver sends the user ID in clear text and an encrypted password to theserver for authentication.

Default0 (User ID/Password)

GUI TabSecurity tab

Cluster Nodes

AttributeClusterNodes (CN)

PurposeA comma-separated list of member nodes in your cluster to which the driver attempts to connect. Specifyinga value for this option enables connect time failover and load balancing. For details, see "Using Failover in aCluster."



Valid Valueshost_name | IP_address:port_number [, ...]

where:

host_name

is the name of a server for a member node in the replica-set cluster to which you want to connect.

IP_address

is the IP address of the server for a member node in the replica-set cluster to which you want toconnect. The IP address can be specified in IPv4 or IPv6 format. Note that IPv6 values must bewrapped in double-quotation marks. See "Using IP Addresses" for details about these formats.

port_number

is the port number of the server listener for the corresponding member node.

For example:

server1:9042,255.125.1.11:9043,"2001:DB8:0000:0000:8:800:200C:417A":9044

Notes

• When specifying a value for this option, the driver randomly selects from the list for a server node to firstattempt a connection. If that connection fails, the driver again randomly selects another server node fromthis list until all servers in the list have been tried or a connection is successfully established.

DefaultNone

GUI TabGeneral tab

See Also

• Using Failover in a Cluster on page 82

• Using IP Addresses on page 48

Config Options

AttributeConfigOptions (CO)


Config Options

Purpose

Note: The Config Options connection option is not currently supported by the driver. When configuring thedriver, you should not specify a value for this option.

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

key

is the attribute name of a supported configuration option.

value

specifies the setting for this configuration option.

DefaultNone


Create Map

AttributeCreateMap (CM)

PurposeDetermines whether the driver creates the internal files required for a relational view of the native data whenestablishing a connection.

Valid Values0 | 1 | 2



BehaviorIf set to 0 (No), the driver uses the current group of internal files specified by the Schema Map connectionoption. If the files do not exist, the connection fails.

If set to 1 (ForceNew), the driver deletes the current group of files specified by the Schema Map connectionoption and creates new files in the same location.

If set to 2 (NotExist), the driver uses the current group of files specified by the Schema Map connection option.If the files do not exist, the driver creates them.

Notes

• The internal files share the same directory as the schema map's configuration file.This directory is specifiedby the value you enter for the Schema Map connection option.

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


Data Source Name

Decimal Precision

AttributeDecimalPrecision (DP)

PurposeSpecifies the precision reported for Decimal columns in column and result-set metadata. This option allowsyou to set the precision for Decimal columns when using an application that does not support unbounded datatypes.

Valid Valuesx

where:

x


Notes

• The value specified for this option must be greater than or equal to the setting of the Decimal Scale connectionoption; otherwise, an error is returned when attempting to establish a connection.

• In most scenarios, an error is returned if the size of an Decimal value specified in a statement exceeds theprecision determined by this option. However, when executing a Select statement, the driver will return datacontaining values that are larger than the specified precision.

Default38


See also

• Decimal Scale on page 110

Decimal Scale

AttributeDecimalScale (DS)



PurposeSpecifies the maximum scale reported for Decimal columns in column and result-set metadata. This optionallows you to set the scale for Decimal columns when using an application that does not support unboundeddata types.

Valid Valuesx

where:

x


Default10

Notes

• The value specified for this option cannot exceed the setting of the Decimal Precision connection option;otherwise, an error is returned when attempting to establish a connection.

• In most scenarios, an error is returned if the scale of a Decimal value specified in a statement exceeds thescale determined by this option. However, when executing a Select statement, the driver will return datacontaining values that have a scale larger than that specified by this option.


See Also

• Decimal Precision on page 110

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.


Description

DefaultNone

GUI TabGeneral tab

Fetch Size

AttributeFetchSize (FS)

PurposeSpecifies the number of rows that the driver processes before returning data to the application when executinga Select. This value provides a suggestion to the driver as to the number of rows it should internally processbefore returning control to the application.The driver may fetch fewer rows to conserve memory when processingexceptionally wide rows.

Valid Values0 | x

where:

x

is a positive integer indicating the number of rows that should be processed.

BehaviorIf set to 0, the driver processes all the rows of the result before returning control to the application. When largedata sets are being processed, setting FetchSize to 0 can diminish performance and increase the likelihoodof out-of-memory errors.

If set to x, the driver limits the number of rows that may be processed for each fetch request before returningcontrol to the application.

Notes

• To optimize throughput and conserve memory, the driver uses an internal algorithm to determine how manyrows should be processed based on the width of rows in the result set. Therefore, the driver may processfewer rows than specified by FetchSize when the result set contains exceptionally wide rows. Alternatively,the driver processes the number of rows specified by FetchSize when the result set contains rows ofunexceptional width.

• FetchSize can be used to adjust the trade-off between throughput and response time. Smaller fetch sizescan improve the initial response time of the query. Larger fetch sizes can improve overall response timesat the cost of additional memory.

• You can use FetchSize to reduce demands on memory and decrease the likelihood of out-of-memory errors.Simply, decrease FetchSize to reduce the number of rows the driver is required to process before returningdata to the application.



• The ResultMemorySize connection property can also be used to reduce demands on memory and decreasethe likelihood of out-of-memory errors.

• FetchSize is related to, but different than, NativeFetchSize. NativeFetchSize specifies the number of rowsof raw data that the driver fetches from the native data source, while FetchSize specifies how many of theserows the driver processes before returning control to the application. Processing the data includes convertingnative data types to SQL data types used by the application. If FetchSize is greater than NativeFetchSize,the driver may make multiple round trips to the data source to get the requested number of rows beforereturning control to the application.

Default100 (rows)

GUI TabAdvanced tab

Host Name

AttributeHostName (HOST)

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

Valid Valueshost_name | IP_address

where:

host_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" for details about these formats.

DefaultNone

GUI TabGeneral tab

See AlsoUsing IP Addresses on page 48


Host Name

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 system locale.

Default4 (ISO 8559-1 Latin-1)

GUI TabNA

See Also

• Internationalization, Localization, and Unicode on page 179

• IANAAppCodePage Values on page 163



Initialization String

AttributeInitializationString (IS)

PurposeOne or multiple SQL commands to be executed by the driver after it has established the connection to thedatabase and has performed all initialization for the connection. If the execution of a SQL command fails, theconnection attempt also fails and the driver returns an error indicating which SQL command or commandsfailed.

Valid Valuesstring

where:

string

is one or multiple SQL commands.

Multiple commands must be separated by semicolons. In addition, if this option is specified in a connectionURL, the entire value must be enclosed in parentheses when multiple commands are specified.

ExampleBecause fetching metadata and generating mapping files can significantly increase the time it takes to connectto Apache Cassandara, the driver caches this information on the client the first time the driver connects onbehalf of each user. The cached metadata is used in subsequent connections made by the user instead ofre-fetching the metadata from Apache Cassandra. To force the driver to re-fetch the metadata information fora connection, use the InitializationString property to pass the REFRESH MAP CASSANDRA command in theconnection URL. For example:

DSN=Cassandra;UID={CassandraID};PWD=secret;InitializationString=(REFRESH MAP CASSANDRA)

DefaultNone

GUI TabAdvanced tab

JVM Arguments

AttributeJVMArgs (JVMA)


Initialization String

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 18

• Setting the Library Path Environment Variable (UNIX and Linux) on page 21.

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}

Default-Xmx256m

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. Thevalue specified for this option must be identical for all drivers. For example, if you are using theSalesforce and Cassandra drivers on Windows, you would specify a value of{c:\install_dir\java\lib\cassandra.jar;c:\install_dir\java\lib\sforce.jar}for both drivers. If the value for any of the affected drivers differs from that of the other drivers, thedrivers will return an error at connection that the JVM is already running.

ExampleOn Windows:

{.;c:\install_dir\java\lib\cassandra.jar}

On UNIX:

{.:/home/user1/install_dir/java/lib/cassandra.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.


Keyspace Name

AttributeKeyspaceName (KSN)

PurposeSpecifies the name of the keyspace to which you want to connect.This value is also used as the default qualifierfor unqualified table names in queries.


Keyspace Name

Valid Valueskeyspace_name

where:

keyspace_name

is the name of a valid keyspace. If the driver cannot find the specified keyspace, the connection fails;however, if you do not specify a value, the default is the keyspace defined by the system administratorfor each user.

Notes

• If KeyspaceName is not specified, Cassandra's internal keyspace name system will be used.

Defaultsystem

GUI TabGeneral 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 AlsoUsing the Driver on page 92

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.

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

Native Fetch Size

AttributeNativeFetchSize (NFS)


Login Timeout

PurposeSpecifies the number of rows of data the driver attempts to fetch from the native data source on each requestsubmitted to the server.

Valid Values0 | x

where:

x

is a positive integer that defines the number of rows.

BehaviorIf set to 0, the driver requests that the server return all rows for each request submitted to the server. Blockfetching is not used.

If set to x, the driver attempts to fetch up to a maximum of the specified number of rows on each requestsubmitted to the server.

NotesNative Fetch Size is related to, but different than, Fetch Size. Native Fetch Size specifies the number of rowsof raw data that the driver fetches from the native data source, while Fetch Size specifies how many of theserows the driver processes before returning control to the application. Processing the data includes convertingnative data types to SQL data types used by the application. If Fetch Size is greater than Native Fetch Size,the driver may make multiple round trips to the data source to get the requested number of rows before returningcontrol to the application.

Default10000 (rows)

GUI TabAdvanced tab

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:

port_number

is the port number of the server listener. Check with your database administrator for the correctnumber.

Default9042

GUI TabGeneral tab

Query Timeout

AttributeQueryTimeout (QT)


Port Number

DescriptionThe number of seconds for the default query timeout for all statements that are created by a connection. Tooverride the value set by this connection option for an individual statement, set a different value in theSQL_ATTR_QUERY_TIMEOUT statement attribute on the SQLSetStmtAttr() function.


where:

x

is a number of seconds.

BehaviorIf set to -1, the query does not time out.The driver silently ignores the SQL_ATTR_QUERY_TIMEOUT attribute.

If set to 0, the query does not time out, but the driver responds to the SQL_ATTR_QUERY_TIMEOUT attribute.

If set to x, all queries time out after the specified number of seconds unless the application overrides this valueby setting the SQL_ATTR_QUERY_TIMEOUT attribute.

Default0

GUI TabAdvanced tab

Read Consistency

AttributeReadConsistency (RC)

PurposeSpecifies how many replicas must respond to a read request before returning data to the client application.

Valid Values1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10

BehaviorIf set to 1 (one), data is returned from the closest replica. This setting provides the highest availability, butincreases the likelihood of stale data being read.

If set to 2 (two), data is returned from two of the closest replicas.

If set to 3 (three), data is returned from three of the closest replicas.

If set to 4 (quorum), data is returned after a quorum of replicas has responded from any data center.



If set to 5 (all), data is returned to the application after all replicas have responded. This setting provides thehighest consistency and lowest availability.

If set to 6 (local_quorum), data is returned after a quorum of replicas in the same data center as the coordinatornode has responded. This setting avoids latency of inter-data center communication.

(Cassandra 2.x only) If set to 7 (each_quorum), data is returned after a quorum of replicas in each data centerof the cluster has responded.

Not supported for reads

If set to 8 (serial), the data is read without proposing a new addition or update. Uncommitted transactions arecommitted as part of the read.

If set to 9 (local_serial), the data within a data center is read without proposing a new addition or update.Uncommitted transactions within the data center are committed as part of the read.

If set to 10 (local_one), data is returned from the closest replica in the local data center.

Notes

• If the server does not support the Read Consistency value specified, the connection attempt fails and thedriver returns a consistency level error.

• Refer to Apache Cassandra documentation for more information about configuring consistency levels,including usage scenarios.

Default4 (quorum)

GUI TabAdvanced 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:

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.


Read Only

Default1 (Enabled)

GUI TabAdvanced tab

Report Codepage Conversion Errors

AttributeReportCodepageConversionErrors (RCCE)

PurposeSpecifies how the driver handles code page conversion errors that occur when a character cannot be convertedfrom one character set to another.

An error message or warning can occur if an ODBC call causes a conversion error, or if an error occurs duringcode page conversions to and from the database or to and from the application.The error or warning generatedis Code page conversion error encountered. In the case of parameter data conversion errors, thedriver adds the following sentence:Error in parameter x, where x is the parameter number.The standardrules for returning specific row and column errors for bulk operations apply.


BehaviorIf set to 0 (Ignore Errors), the driver substitutes 0x1A for each character that cannot be converted and doesnot return a warning or error.

If set to 1 (Return Error), the driver returns an error instead of substituting 0x1A for unconverted characters.

If set to 2 (Return Warning), the driver substitutes 0x1A for each character that cannot be converted and returnsa warning.

Default0 (Ignore Errors)

GUI TabAdvanced tab

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.


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 untilout-of-memory errors are eliminated. As a result, the maximum size of an intermediate result set the driverholds in memory will be reduced, and some portion of the result set will be written to disk. Be aware thatwhile writing to disk reduces the risk of out-of-memory errors, it also negatively impacts performance. Foroptimal performance, 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, 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


Result Memory Size

See also

• Performance Considerations on page 76

• Fetch Size on page 112

• JVM Arguments on page 115

Schema Map

AttributeSchemaMap (SMP)

PurposeSpecifies the name and location of the configuration file used to create the relational map of native data. Thedriver looks for this file when connecting to the 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 SchemaMap is set to a value ofC:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_Schema\MyServer.config,the driver either creates or looks for the configuration file MyServer.config in the directoryC:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_Schema\.

Notes

• When connecting to a server, the driver looks for the SchemaMap configuration file. If the configuration filedoes not exist, the driver creates a SchemaMap configuration file using the name and location you haveprovided. If you do not provide a name and location for a SchemaMap configuration file, the driver createsit using default values.

• On UNIX/Linux, if no value is specified for the SchemaMap or LogonID options, the driver creates a filenamed USER.config at connection.

• The driver uses the path specified in this connection option to store additional internal files.

• You can refresh the internal files related to an existing relational view of your data by using the SQL extensionRefresh Map. Refresh Map runs a discovery against your native data and updates your internal filesaccordingly.

Default

• For Windows XP and Windows Server 2003

• user_profile\ApplicationData\Local\Progress\DataDirect\Cassandra_Schema\host_name.config

• For other Windows platforms



User data source:user_profile\AppData\Local\Progress\DataDirect\Cassandra_Schema\host_name.config

•

• System data source:C:\Users\Default\AppData\Local\Progress\DataDirect\Cassandra_Schema\host_name.config

• For UNIX/Linux

• users_home_directory/Progress/DataDirect/Cassandra_Schema/host_name.config

user_profile

is the user name of your OS profile.

host_name

is the value specified for the Host Name connection option.

users_home_directory

is the user's home directory.


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 0 (Auto) or 1 (Server).

DefaultFor the 32-bit driver:

19934


Server Port Number


19933


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.


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



Transaction Mode

AttributeTransactionMode (TM)

PurposeSpecifies how the driver handles manual transactions.

Valid Values0 | 1

BehaviorIf set to 1 (Ignore), the data source does not support transactions and the driver always operates in auto-commitmode. Calls to set the driver to manual commit mode and to commit transactions are ignored. Calls to rollbacka transaction cause the driver to return an error indicating that no transaction is started. Metadata indicatesthat the driver supports transactions and the ReadUncommitted transaction isolation level.

If set to 0 (No Transactions), the data source and the driver do not support transactions. Metadata indicatesthat the driver does not support transactions.

Default0 (No Transactions)

GUI TabAdvanced tab

User Name

AttributeLogonID (UID)

PurposeThe default user ID 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.


Transaction Mode

GUI TabSecurity tab

Varchar Size

AttributeVarcharSize (VCS)

PurposeSpecifies the precision reported for Varchar columns in column and result-set metadata. This option allowsyou to set the precision for Varchar columns when using an application that does not support unbounded datatypes.

Valid Valuesx

where:

x


Default4000

Notes

• In most scenarios, an error is returned if the size of a Varchar value specified in a statement exceeds theprecision determined by this option. However, when executing a Select statement, the driver will return datacontaining values that are larger than the specified precision.


Varint Precision

AttributeVarintPrecision (VP)

PurposeSpecifies the precision reported for Varint columns in column and result-set metadata. This option allows youto set a the precision for Varint columns when using an application that does not support unbounded datatypes.



Valid Valuesx

where:

x


Default38

Notes

• In most scenarios, an error is returned if the size of a Varint value specified in a statement exceeds theprecision determined by this option. However, when executing a Select statement, the driver returns datacontaining values that are larger than the specified precision.


Write Consistency

AttributeWriteConsistency (WC)

PurposeDetermines the number of replicas on which the write must succeed before returning an acknowledgment tothe client application.

Valid Values0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |10

BehaviorIf set to 0 (any), a write must succeed on at least one node. Even if all replica nodes for the given partition keyare down, the write can succeed after a hinted handoff has been written. This setting provides the lowestconsistency and highest availability.

If set to 1 (one), a write must succeed on at least one replica node.

If set to 2 (two), a write must succeed on at least two replica nodes.

If set to 3 (three), a write must succeed on at least three replica nodes.

If set to 4 (quorum), a write must succeed on a quorum of replica nodes.

If set to 5 (all), a write must succeed on all replica nodes in the cluster for that partition key.This setting providesthe highest consistency and lowest availability.

If set to 6 (local_quorum), a write must succeed on a quorum of replica nodes in the same data center as thecoordinator node. This setting avoids latency of inter-data center communication.


Write Consistency

If set to 7 (each_quorum), a write must succeed on a quorum of replica nodes across a data center.

(Cassandra 2.x only) If set to 8 (serial), the driver prevents unconditional updates to achieve linearizableconsistency for lightweight transactions.

(Cassandra 2.x only) If set to 9 (local_serial), the driver prevents unconditional updates to achieve linearizableconsistency for lightweight transactions within the data center.

If set to 10 (local_one), a write must succeed on at least one replica node in the local data center.

Notes

• An update operation can result in a consistency level error if the server does not support the WriteConsistencyvalue specified.

• Refer to Apache Cassandra documentation for more information about configuring consistency levels,including usage scenarios.

Default4 (quorum)

GUI TabAdvanced tab



8Supported SQL Functionality

The driver provides support for SQL statements and extensions described in this section. SQL extensions aredenoted by an (EXT) in the topic title.


• Data Definition Language (DDL)

• Delete

• Insert

• Refresh Map (EXT)

• Select

• Update

• SQL Expressions

• Subqueries

Data Definition Language (DDL)The driver supports data store-specific DDL through the Native and Refresh escape clauses. See "Native andRefresh Escape Clauses" for details.


Native and Refresh Escape Clauses

The driver supports ODBC-native-escape and ODBC-refresh-schema-escape clauses to embed datastore-specific commands in SQL-92 statements. The ODBC-native-escape clause allows you to executenative commands directly through the client application, while the ODBC-refresh-schema-escape clauseis used to incorporate any changes introduced by the ODBC-native-escape clause into the driver's relationalmap of the data.

Note: The native and refresh escape clauses are mainly intended for the execution of DDL commands, suchas ALTER, CREATE, and DROP. A returning clause for the native escape is not currently supported by thedriver. Therefore, results cannot be retrieved using the native escape clause.

The ODBC-native-escape clause is defined as follows:

ODBC-native-escape ::= ODBC-esc-initiator native (command_text)}

where:

command_text

is a data store-specific command.

The ODBC-refresh-schema-escape clause is defined as follows:

ODBC-refresh-schema-escape ::= ODBC-esc-initiator refresh ODBC-esc-terminator

The following example shows the execution of two data store-specific commands with a refresh of the driver'srelational map of the data. Note that each Native escape clause must have its own execute. The Refreshescape, however, can be used in the same execute statement as the Native escape.

SQLExecDirect( pstmt, "{native (CREATE TABLE emp (empid int primary key, title varchar))}", SQL_NTS);SQLExecDirect( pstmt, "{native (CREATE TABLE dept (deptid int primary key, city varchar))}{refresh}", SQL_NTS);

See alsoSupported SQL Functionality on page 133

Delete

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

SyntaxDELETE FROM table_name [WHERE search_condition]

where:


Chapter 8: Supported SQL Functionality

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

• Delete is supported for primitive types and non-nested complex types. See "Complex Type Normalization"for details.

• To enable Insert, Update, and Delete, set the ReadOnly connection property to false.

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

See also

• Where Clause on page 143

• Complex Type Normalization on page 38

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


Insert

In Cassandra, Inserts are in effect Upserts. When an Insert is performed on a row that already exists, the rowwill be updated.

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

• Insert is supported for primitive types and non-nested complex types. See "Complex Type Normalization"for details.

• The driver supports an insert on a child table prior to an insert on a parent table, circumventing referentialintegrity constraints associated with traditional RDBMS. To maintain integrity between parent and childtables, it is recommended that an insert first be performed on the parent table for each foreign key valueadded to the child. If such an insert is not first performed, the driver automatically inserts a row into theparent table that contains only the primary key values and NULL values for all non-primary key columns.See "Complex Type Normalization" for details.


See also

• Literals on page 151

• Select on page 137




Refresh Map (EXT)

PurposeThe REFRESH MAP statement adds newly discovered objects to your relational view of native data. It alsoincorporates any configuration changes made to your relational view by reloading the schema map configurationfile.

SyntaxREFRESH MAP

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

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.


Refresh Map (EXT)

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.

See alsoSelect Clause on page 139From Clause on page 141Where Clause on page 143Group By Clause on page 143Having Clause on page 144Union Operator on page 145Intersect Operator on page 145Except and Minus Operators on page 146Order By Clause on page 147Limit Clause on page 148



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 offset number | 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.


Select

See alsoSQL Expressions on page 150Aggregate Functions on page 140

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

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 142

Outer Join Escape Sequences

PurposeThe SQL-92 left, right, and full outer join syntax is supported.


Select

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:

• 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

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 alsoFor more information about subqueries, see Subqueries on page 158.

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 also

• SQL Expressions on page 150

• Subqueries on page 158

• Operation Timeouts on page 98

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:


Select

column_expression

is either a column name or a SQL expression. Multiple values must be separated by a comma. Ifcolumn_expression is a column name, it must match one of the column names specified in the Selectclause. Also, the Group By clause must include all non-aggregate columns specified in the Selectlist.

ExampleThe following example totals the salaries in each department:

SELECT dept_id, sum(salary) FROM emp GROUP BY dept_id

This statement returns one row for each distinct department ID. Each row contains the department ID and thesum of the salaries of the employees in the department.

See also



Having Clause

PurposeSpecifies conditions for groups of rows (for example, display only the departments that have salaries totalingmore than $200,000). This clause is valid only if you have already defined a Group By clause.

SyntaxHAVING expr1rel_operatorexpr2

where:

expr1 | expr2

can be column names, constant values, or expressions. These expressions do not have to match acolumn expression in the Select clause. See "SQL Expressions" for details regarding SQL expressions.

rel_operator

is the relational operator that links the two expressions.

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

SELECT dept_id, sum(salary) FROM emp GROUP BY dept_id HAVING sum(salary) > 200000

See also





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:


Select

DISTINCT

eliminates duplicate rows from the results.

Notes

• When using the Intersect operator, the Select lists for each Select statement must have the same numberof column expressions with the same data types and must be specified in the same order.


SELECT last_name, salary, hire_date FROM empINTERSECT [DISTINCT]SELECT name, pay, birth_date FROM person


SELECT last_name, salary FROM empINTERSECTSELECT salary, last_name FROM raises

Except and Minus Operators

PurposeReturn the rows from the left Select statement that are not included in the result of the right Select statement.

Syntax

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

where:

DISTINCT

eliminates duplicate rows from the results.

Notes

• When using one of these operators, the Select lists for each Select statement must have the same numberof column expressions with the same data types and must be specified in the same order.




SELECT last_name, salary, hire_date FROM empEXCEPTSELECT name, pay, birth_date FROM person


SELECT 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 150


Select

Limit Clause

PurposePlaces an upper bound on the number of rows returned in the result.

SyntaxLIMIT number_of_rows [OFFSET offset_number]

where:

number_of_rows

specifies a maximum number of rows in the result. A negative number indicates no upper bound.

OFFSET

specifies how many rows to skip at the beginning of the result set. offset_number is the numberof rows to skip.

Notes

• In a compound query, the Limit clause can appear only on the final Select statement. The limit is appliedto the entire query, not to the individual Select statement to which it is attached.

ExampleThe following example returns a maximum of 20 rows.

SELECT last_name, first_name FROM emp WHERE salary > 20000 ORDER BY dept_idc LIMIT20

Update

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

In Cassandra, Updates are in effect Upserts. When an Update is performed on a row that does not exist, therow will be inserted.

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

• Update is supported for primitive types, non-nested Tuple types, and non-nested user-defined types. Updateis also supported for values in non-nested Map types. The driver does not support updates on List types,Set types, or keys in Map types because the values in each are part of the primary key of their respectivechild tables and primary key columns cannot be updated. If an Update is attempted when not allowed, thedriver issues the following error message:

[DataDirect][Cassandra ODBC Driver][Cassandra]syntax error or access ruleviolation: UPDATE not permitted for column: column_name

See "Complex Type Normalization" for details.

• Update is supported for Counter columns when all the other columns in the row comprise that row’s primarykey. The Counter column itself is the only updatable field in the row. When updating a Counter column onan existing row, the Counter column is updated according to the increment (or decrement) specified in theSQL statement. When updating a Counter column for which there is no existing row, the values of thecolumns that comprise the row’s primary key are inserted into the table alongside the value of the Countercolumn.

For example, consider the following table.

CREATE TABLE page_view_counts ( counter_value counter, url_name varchar, page_name varchar, PRIMARYKEY (url_name, page_name));

The following Update can be performed on the page_view_counts table.

UPDATE page_view_counts SET counter_value=counter_value + 1 WHERE url_name = 'www.progress.com' AND page_name = 'home'


Update

This Update would provide the following output.

Note: Cassandra initially assigns a value of 0 (zero) to Counter columns. An increment or decrement canbe specified in the SQL statement.

url_name | page_name | counter_value------------------+-----------+--------------- www.progress.com | home | 1

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


See also

• Where Clause on page 143



• Native and Refresh Escape Clauses on page 134

SQL ExpressionsAn expression is a combination of one or more values, operators, and SQL functions that evaluate to a value.You can use expressions in the Where, and Having of Select statements; and in the Set clauses of Updatestatements.

Expressions enable you to use mathematical operations as well as character string manipulation operators toform complex queries.

The driver supports both unquoted and quoted identifiers. An unquoted identifier must start with an ASCII alphacharacter and can be followed by zero or more ASCII alphanumeric characters. Unquoted identifiers areconverted to uppercase before being used.

Quoted identifiers must be enclosed in double quotation marks (""). A quoted identifier can contain any Unicodecharacter including the space character. The driver recognizes the Unicode escape sequence \uxxxx as aUnicode character.You can specify a double quotation mark in a quoted identifier by escaping it with a doublequotation mark.

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

Valid expression elements are:

• Column names

• Literals

• Operators

• Functions



Column Names

The most common expression is a simple column name.You can combine a column name with other expressionelements.

Literals

Literals are fixed data values. For example, in the expression PRICE * 1.05, the value 1.05 is a constant.Literals are classified into types, including the following:

• Binary

• Character string

• Date

• Floating point

• Integer

• Numeric

• Time

• Timestamp

The following table describes the literal format for supported SQL data types.

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


SQL Expressions

ExampleLiteral SyntaxSQL Type

1.2E0 or 2.5E40 or -3.45E2or 5.67E-4

n.fEx

where:

n is the integral part

f is the fractional part

x is the exponent

DOUBLE

12 or -34 or 0n

where n is a valid integer value in the rangeof the INTEGER data type

INTEGER

'000482ff'X'hex_value'LONGVARBINARY

'This is a stringliteral'

'value'LONGVARCHAR

'2010-05-2118:33:05.025'

TIME'time'TIME

'This is a stringliteral'

'value'VARCHAR

Character String LiteralsText specifies a character string literal. A character string literal must be enclosed in single quotation marks.To represent one single quotation mark within a literal, you must enter two single quotation marks. When thedata in the fields is returned to the client, trailing blanks are stripped.

A character string literal can have a maximum length of 32 KB, that is, (32*1024) bytes.

Example

'Hello''Jim''s friend is Joe'

Numeric LiteralsUnquoted numeric values are treated as numeric literals. If the unquoted numeric value contains a decimalpoint or exponent, it is treated as a real literal; otherwise, it is treated as an integer literal.

Example+1894.1204

Binary LiteralsBinary literals are represented with single quotation marks. The valid characters in a binary literal are 0-9, a-f,and A-F.



Example'00af123d'

Date/Time LiteralsDate and time literal values are enclosed in single quotion marks ('value').

• The format for a Date literal is DATE'date'.

• The format for a Time literal is TIME'time'.

• The format for a Timestamp literal is TIMESTAMP'ts'.

Integer LiteralsInteger literals are represented by a string of numbers that are not enclosed in quotation marks and do notcontain decimal points.

Notes

• Integer constants must be whole numbers; they cannot contain decimals.

• Integer literals can start with sign characters (+/-).

Example1994 or -2

Operators

This section describes the operators that can be used in SQL expressions.

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.


SQL Expressions

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


SELECT 'Name is' || ename FROM empConcatenates character strings.||

The result of concatenating two character strings is the data type VARCHAR.

Comparison OperatorsComparison operators compare one expression to another. The result of such a comparison can be TRUE,FALSE, or UNKNOWN (if one of the operands is NULL).The driver considers the UNKNOWN result as FALSE.

The following table lists the supported comparison operators.

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

SELECT empno, ename, deptnoFROM emp e WHERE EXISTS(SELECT deptno FROM dept WHEREe.deptno = dept.deptno)

Tests for existence of rows in asubquery.

EXISTS

SELECT * FROM emp WHERE enameIS NOT NULL SELECT * FROM empWHERE ename IS NULL

Tests whether the value of thecolumn or expression is NULL.

IS [NOT] NULL

Logical OperatorsA logical operator combines the results of two component conditions to produce a single result or to invert theresult of a single condition. The following table lists the supported logical operators.


SQL Expressions

Table 21: 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 22: Operator Precedence

OperatorPrecedence

+ (Positive), - (Negative)1

*(Multiply), / (Division)2

+ (Add), - (Subtract)3

|| (Concatenate)4

=, >, <, >=, <=, <>, != (Comparison operators)5

NOT, IN, LIKE6

AND7

OR8



Example AThe query in the following example returns employee records for which the department number is 1 or 2 andthe salary is greater than $1000:

SELECT * FROM emp WHERE (deptno = 1 OR deptno = 2) AND sal > 1000

Because parenthetical expressions are forced to be evaluated first, the OR operation takes precedence overAND.

Example BIn the following example, the query returns records for all the employees in department 1, but only employeeswhose salary is greater than $1000 in department 2.

SELECT * FROM emp WHERE deptno = 1 OR deptno = 2 AND sal > 1000

The AND operator takes precedence over OR, so that the search condition in the example is equivalent to theexpression deptno = 1 OR (deptno = 2 AND sal > 1000).

Functions

The driver supports a number of functions that you can use in expressions, as listed and described in "ScalarFunctions."

See alsoScalar Functions on page 172

Conditions

A condition specifies a combination of one or more expressions and logical operators that evaluates to eitherTRUE, FALSE, or UNKNOWN.You can use a condition in the Where clause of the Delete, Select, and Updatestatements; and in the Having clauses of Select statements. The following describes supported conditions.

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


SQL Expressions

DescriptionCondition

Tests for inclusion in a range.

[NOT] BETWEEN

Range

Tests for nulls.

IS NULL, IS NOT NULL

NULL

Tests for existence of rows in a subquery.

[NOT] EXISTS

EXISTS

Specifies a test involving pattern matching.

[NOT] LIKE

LIKE

Specifies a combination of other conditions.

CONDITION [AND/OR] CONDITION

Compound

SubqueriesA query is an operation that retrieves data from one or more tables or views. In this reference, a top-level queryis called a Select statement, and a query nested within a Select statement is called a subquery.

A subquery is a query expression that appears in the body of another expression such as a Select, an Update,or a Delete statement. In the following example, the second Select statement is a subquery:

SELECT * FROM emp WHERE deptno IN (SELECT deptno FROM dept)

IN Predicate

PurposeThe In predicate specifies a set of values against which to compare a result set. If the values are being comparedagainst a subquery, only a single column result set is returned.

Syntaxvalue [NOT] IN (value1, value2,...)

OR

value [NOT] IN (subquery)

ExampleSELECT * FROM emp WHERE deptno IN

(SELECT deptno FROM dept WHERE dname <> 'Sales')



EXISTS Predicate

PurposeThe Exists predicate is true only if the cardinality of the subquery is greater than 0; otherwise, it is false.

SyntaxEXISTS (subquery)

Example

SELECT empno, ename, deptno FROM emp e WHERE EXISTS(SELECT deptno FROM dept WHERE e.deptno = dept.deptno)

UNIQUE Predicate

PurposeThe Unique predicate is used to determine whether duplicate rows exist in a virtual table (one returned froma subquery).

SyntaxUNIQUE (subquery)

Example

SELECT * FROM dept d WHERE UNIQUE (SELECT deptno FROM emp e WHERE e.deptno = d.deptno)

Correlated Subqueries

PurposeA correlated subquery is a subquery that references a column from a table referred to in the parent statement.A correlated subquery is evaluated once for each row processed by the parent statement.The parent statementcan be a Select, Update, or Delete statement.

A correlated subquery answers a multiple-part question in which the answer depends on the value in each rowprocessed by the parent statement. For example, you can use a correlated subquery to determine whichemployees earn more than the average salaries for their departments. In this case, the correlated subqueryspecifically computes the average salary for each department.

Syntax

SELECT select_list FROM table1 t_alias1 WHERE expr rel_operator (SELECT column_list FROM table2 t_alias2


Subqueries

WHERE t_alias1.columnrel_operatort_alias2.column) UPDATE table1 t_alias1 SET column = (SELECT expr FROM table2 t_alias2 WHERE t_alias1.column = t_alias2.column) DELETE FROM table1 t_alias1 WHERE column rel_operator (SELECT expr FROM table2 t_alias2 WHERE t_alias1.column = t_alias2.column)

Notes

• Correlated column names in correlated subqueries must be explicitly qualified with the table name of theparent.

Example AThe following statement returns data about employees whose salaries exceed their department average. Thisstatement assigns an alias to emp, the table containing the salary information, and then uses the alias in acorrelated subquery:

SELECT deptno, ename, sal FROM emp x WHERE sal > (SELECT AVG(sal) FROM emp WHERE x.deptno = deptno) ORDER BY deptno

Example BThis is an example of a correlated subquery that returns row values:

SELECT * FROM dept "outer" WHERE 'manager' IN (SELECT managername FROM emp WHERE "outer".deptno = emp.deptno)

Example CThis is an example of finding the department number (deptno) with multiple employees:

SELECT * FROM dept main WHERE 1 < (SELECT COUNT(*) FROM emp WHERE deptno = main.deptno)

Example DThis is an example of correlating a table with itself:

SELECT deptno, ename, sal FROM emp x WHERE sal > (SELECT AVG(sal) FROM emp WHERE x.deptno = deptno)



IReference

This part provides detailed reference information about Progress DataDirect for ODBC drivers.

Note: This part describes the behavior of multiple Progress DataDirect for ODBC drivers. The functionalitydescribed may not necessarily apply to your driver or database system.


• 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"IANAAppCodePage" 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 24: 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-93920000009398

IBM-943_P14A-200020000009438

IBM-102520000010258

IBM-439620000043968

IBM-502620000050268

IBM-503520000050358

See alsoIANAAppCodePage on page 114

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 25: 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 26: 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 33


Scalar Functions

This section lists the scalar functions that ODBC supports.Your database system may not support all thesefunctions. Refer to the documentation for your database system to find out which functions are supported. Also,depending on the driver that you are using, all the scalar functions may not be supported. To check whichscalar functions are supported by a driver, use the SQLGetInfo ODBC function.

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 27: Scalar Functions

System FunctionsTimedate FunctionsNumeric FunctionsString Functions

CURSESSIONIDCURDATEABSASCII

CURRENT_USERCURTIMEACOSBIT_LENGTH

DATABASEDATEDIFFASINCHAR

IDENTITYDAYNAMEATANCHAR_LENGTH

USERDAYOFMONTHATAN2CONCAT

DAYOFWEEKBITANDDIFFERENCE

DAYOFYEARBITORHEXTORAW

EXTRACTCEILINGINSERT

HOURCOSLCASE

MINUTECOTLEFT

MONTHDEGREESLENGTH

MONTHNAMEEXPLOCATE

NOWFLOORLOWER

QUARTERLOGLTRIM

SECONDLOG10OCTET_LENGTH

WEEKMODRAWTOHEX

YEARPIREPEAT

CURRENT_DATEPOWERREPLACE



System FunctionsTimedate FunctionsNumeric FunctionsString Functions

CURRENT_TIMERADIANSRIGHT

CURRENT_TIMESTAMP

RANDRTRIM

ROUNDSOUNDEX

ROUNDMAGICSPACE

SIGNSUBSTR

SINSUBSTRING

SQRTUCASE

TANUPPER

TRUNCATE

String FunctionsThe following table lists the string functions that ODBC supports.

The string functions listed accept the following arguments:

• string_exp can be the name of a column, a string literal, or the result of another scalar function, wherethe underlying data type is 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 28: 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]


ReturnsFunction

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)

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)



ReturnsFunction

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 29: 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)


ReturnsFunction

Base 10 log of float_exp.LOG10(float_exp)

Remainder of integer_exp1 divided by integer_exp2.MOD(integer_exp1, integer_exp2)

Constant value of pi as a floating-point number.PI()

Value of numeric_exp to the power of integer_exp.POWER(numeric_exp, integer_exp)

Number of radians converted from numeric_exp degrees.RADIANS(numeric_exp)

Random floating-point value using integer_exp as the optional seedvalue.

RAND([integer_exp])

numeric_exp rounded to integer_exp places right of the decimal (leftof the decimal if integer_exp is negative).

ROUND(numeric_exp, integer_exp)

Indicator of the sign of numeric_exp. If numeric_exp < 0, -1 is returned.If numeric_exp = 0, 0 is returned. If numeric_exp > 0, 1 is returned.

SIGN(numeric_exp)

Sine of float_exp, where float_exp is an angle in radians.SIN(float_exp)

Square root of float_exp.SQRT(float_exp)

Tangent of float_exp, where float_exp is an angle in radians.TAN(float_exp)

numeric_exp truncated to integer_exp places right of the decimal. (Ifinteger_exp is negative, truncation is to the left of the decimal.)

TRUNCATE(numeric_exp, integer_exp)

Date and Time FunctionsThe following table lists the date and time functions that 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 30: Scalar Time and Date Functions

ReturnsFunction

Current date.CURRENT_DATE()

[ODBC 3.0 only]



ReturnsFunction

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

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)


ReturnsFunction

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)

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

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.

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 platforms. Microsoft recommends using UTF-16 for new applications.

See "Unicode Support" to determine which encodings your driver supports.

See alsoUnicode Support on page 47

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 Apache Cassandra 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 186

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 182

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



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 32: 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 193

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 200

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. For Apache Cassandra systems,isolation level 0 (read uncommitted) is supported.


• 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 33: 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

Index

Aaddress, IP 48Administrator

Windows ODBC and tracing 86Administrator, Data Source

Windows 18Advanced tab 67, 71aggregate functions 140AIX, See UNIX and LinuxApache Cassandra driver

overview 25Application Using Threads connection option 104arithmetic operators 153arrays of parameter values, passing 194Ascii Size connection option 105Authentication Method connection option 106Autocommit mode 196

Bbinary

literals 152operators 153

bindingdynamic parameters 46parameter markers 46

bound columns 193

Ccaching information to improve performance 190call load, reducing 193catalog functions, using 190character encoding 181character string literals 152client code page, See code pagescluster

failover 82Cluster Nodes connection option 106code pages

IANAAppCodePage attribute 114, 163collection types 38column

names 151comparison operators 154complex types

normalization 38support 38

concatenation operator 154conditions 157

Config Options connection option 107configuring

server mode 77configuring a data source

UNIX and Linux 21using a GUI 61

configuring Java logging 91configuring security 73connecting via connection string

data source 74connection attribute

ApplicationUsingThreads 104AsciiSize 105AuthenticationMethod 106ClusterNodes 106ConfigOptions 107CreateMap 108DataSourceName 109DecimalPrecision 110DecimalScale 110Description 111FetchSize 112HostName 113IANAAppCodePage 114InitializationString 115JVMArgs 115JVMClasspath 116KeyspaceName 117LogConfigFile 118LoginTimeout 119LogonID 129NativeFetchSize 119Password 120PortNumber 121QueryTimeout 121ReadConsistency 122ReadOnly 123ReportCodepageConversionErrors 124ResultMemorySize 124SchemaMap 126ServerPortNumber 127SQLEngineMode 128TransactionMode 129VarcharSize 130VarintPrecision 130WriteConsistency 131

connection failovercluster 82

connection handles 196connection issues 95


Index

connection optionsApplication Using Threads 104Ascii Size 105Authentication Method 106Cluster Nodes 106Config Options 107Create Map 108Data Source Name 109Decimal Precision 110Decimal Scale 110Description 111Fetch Size 112Host Name 113IANAAppCodePage 114Initialization String 115JVM Arguments 115JVM Classpath 116Keyspace Name 117Log Config File 118Login Timeout 119Native Fetch Size 119overview 101Password 120Port Number 121Query Timeout 121Read Consistency 122Read Only 123Report Codepage Conversion Errors 124required 61Result Memory Size 124Schema Map 126Server Port Number 127SQL Engine Mode 128Transaction Mode 129User Name 129Varchar Size 130Varint Precision 130Write Consistency 131

connection string attributes 101connections

optimizing 196supported 50

contacting Customer Support 16correlated subqueries 159Counter data type 134, 148Create Map connection option 108cursor library, performance implications of using 195

DData Definition Language (DDL) 133–134data encryption 64data retrieval, optimizing 192data source

configuringUNIX and Linux 20, 55

data source (continued)configuring (continued)

Windows 18connecting via connection string 74connecting via logon dialog box 75

Data Source AdministratorWindows 18

Data Source Name connection option 109data types

choosing 194complex 38, 44

database connections, testing 92–93databases

supported 25date and time functions 176date/time literals 153DDL (Data Definition Language) 133–134ddlogging.properties file 92ddtestlib tool 54, 88Decimal Precision connection option 110Decimal Scale connection option 110Delete statement 134demoodbc application 92Description connection option 111determining optimal set of columns 197diagnostic tools 85dirty reads 204distributed transactions 197documentation, about 15double-byte character sets in UNIX and Linux 181driver

API and scalar functions 169code page values 163connection option descriptions 101ODBC compliance 33optimizing application performance 189supported features 47threading 211

driver requirements 26Driver to SQL Communication logger 90driver, logging for 89drivers

version string information 34dynamic parameters, binding 46

Eenabling tracing 86environment

variables 52environment variable, library path 95error messages

general 93UNIX and Linux 93Windows 93


Index

escape clausesnative 134refresh 134

example application 93Except operator 146executing SQL 93EXISTS predicate 159Extended Options 64, 67, 71, 207

FFetch Size connection option 112From clause

Outer Join Escape Sequences 141functions, ODBC

selecting for performance 194

GGeneral Tab 61Group By clause 143

Hhandles

connection 196statement 196

Having clause 144Host Name connection option 113

IIANAAppCodePage

connection option values 163IANAAppCodePage connection option 114IANAAppCodePage values 163identifiers 83improving

database performance 199index performance 199join performance 202ODBC application performance 97, 189record selection performance 200

IN predicate 158indexes

deciding which to create 201improving performance 199overview 199

indexing multiple fields 200Initialization String connection option 115Insert statement 135integer literals 153internationalization 179interoperability issues 96Intersect operator 145

IP addresses 48IPv4 48IPv6 48isolation levels

about 204read committed 204read uncommitted 204repeatable read 204serializable 204

isolation levels and data consistencycompared 204dirty reads 204non-repeatable reads 204phantom reads 204

ivtestlib tool 54, 88

JJava logging

configuring 91SQL engine logger 90

Java Logging for the SQL Engine Server 82Java Path 77join in a From clause 142JVM Arguments connection option 115JVM Classpath connection option 116

KKeyspace Name connection option 117

Llibrary path environment variable

setting on UNIX/Linux 21setting on Windows 18

Limit clause 148Linux, See UNIX and Linuxlist type 38literals

about 151binary 152character string 152date/time 153integer 153numeric 152

local tabledeleting rows 134

locale 180localization 179locking 203locking levels 46locking modes and levels 205Log Config File connection option 118


Index

logging, Javacomponents 89configuring 91SQL engine logger 90

logical operators 155Login Timeout connection option 119long data, retrieving 192

Mmanaging connections 196map type 38metadata methods 25MIBenum value 163Minus operator 146

Nnaming conflicts

identifiers 83Native escape clause 134Native Fetch Size connection option 119NativeFetchSize 98nested complex types 44non-repeatable reads 204normalization

identifiers 83numeric functions 175numeric literals 152

OODBC

API functions 169call load, reducing 193designing for performance 189functions, selecting for performance 194how the architecture works 24scalar functions 172specification 33

ODBC application performance design 97ODBC conformance 33ODBC Test 89ODBC Trace 85ODBC-native-escape 134ODBC-refresh-schema-escape 134odbc.ini (system information) file

configuring with 55odbc.ini file

controlling tracing with 87Open Database Connectivity, See ODBC specificationoperation timeouts

troubleshooting 98operators

arithmetic 153

operators (continued)comparison 154concatenation 154logical 155precedence 156

optimization, performance 189Order By clause 147out of memory errors

troubleshooting 97Outer Join Escape Sequences 141

Pparameter markers, binding 46parameter metadata 48parameter values, passing arrays of 194Password connection option 120performance 97performance considerations 76performance optimization

avoiding catalog functions 190avoiding search patterns 191commits in transactions 196managing connections 196overview 189reducing the size of retrieved data 192retrieving long data 192using a dummy query 191using bound columns 193

performance, improvingdatabase using indexes 199index 199join 202record selection 200

phantom reads 204Port Number connection option 121positioned updates and deletes 197predicate

EXISTS 159IN 158UNIQUE 159

properties file for Java loggingJVM 91

QQuery Timeout connection option 121

Rread committed 204Read Consistency connection option 122Read Only connection option 123read uncommitted 204ReadConsistency 98


Index

Refresh escape clause 134Refresh Map (EXT) 137repeatable read 204Report Codepage Conversion Errors connection option124Result Memory Size connection option 124retrieving data, optimizing 192

Sscalar functions, ODBC 172Schema Map connection option 126scrollable cursors 195search patterns, avoiding 191Security tab 73Select clause 139Select statement 137serializable isolation level 204server mode, configuring 77Server Port Number connection option 127Services 77set type 38setting library path environment variable

on UNIX/Linux 21on Windows 18

setup issues 95SQL

executing 93expressions 150supported 50

SQL engine logger 90SQL Engine Mode connection option 128SQL engine, starting

UNIX/Linux 80SQL engine, stopping

UNIX/Linux 81SQL engine, using

UNIX/Linux 80SQL escape clauses

native 134refresh 134

SQL functionality 25SQL statement support 133SQL statements

Insert 135Update 134, 148

SQLExecDirect, advantages of using 194SQLFetch, disadvantage of using 193SQLSpecialColumns, determining optimal set of columns197standards, ODBC specification compliance 33starting

SQL engine serverUNIX/Linux 80

statement handles, using to manage SQL statements196

statements supported 50static cursors 195stopping the SQL engine server

UNIX/Linx 81string functions 173subqueries

correlated 159overview 158

subquery in a From clause 142supported databases 25system functions 178system information file (.odbc.ini) 55, 87

TTechnical Support, contacting 16test connect

UNIX and Linux 22testing database connections 92–93threading, overview 211time functions 176timeouts, operation

troubleshooting 98tools

diagnostic 85other 93

trace log 85tracing

creating a trace log 85enabling with system information file 87enabling with Windows ODBC Administrator 86

tracking JDBC calls 89Transaction Mode connection option 129transactions, managing commits 196troubleshooting

operation timeouts 98tuple type 42

UUCS-2 181unary operator 153undocumented connection options 64, 67, 71Unicode

character encoding 181ODBC drivers 183support in databases 182support in ODBC 182

Unicode support 47Union operator 145UNIQUE predicate 159UNIX and Linux

configuring a data source 21configuring through the system information (odbc.ini)file 55data source configuration 20, 55


Index

UNIX and Linux (continued)double-byte character sets 181driver names 33environment

DD_INSTALLDIR 54ddtestlib tool 54introduction 52ivtestlib tool 54library search path 52ODBCINI 53ODBCINST 53system information file (.odbc.ini) 55

error messages 93system information (odbc.ini) file, configuring through55system requirements 28

Update statement 134, 148updates, optimizing 196User Name connection option 129user-defined types 42using

SQL engineUNIX/Linux 80

UTF-16 181

UTF-16 Applications 60UTF-8 181

VVarchar Size connection option 130Varint Precision connection option 130version string information 34

WWhere clause 98, 143Windows

configuring a data source using a GUI 61Data Source Administrator 18data source configuration 18driver names 28error messages 93system requirements 26

Windows ODBC Administrator and tracing 86wire protocol adapter logger 91WorkAround options for ODBC drivers 207Write Consistency connection option 131WriteConsistency 98


Index

Documents

ProgressDataDirect for ODBC forApacheCassandra Driver•Troubleshootingonpage83explainsthetoolstosolvecommonproblemsanddocumentserrormessages