README
     Progress(R) DataDirect(R)
     Progress(R) DataDirect(R) for ODBC for Apache Cassandra(TM)

     UNIX and Linux Platforms(32- and 64-bit) 

     Release 8.0.0 
     March 1, 2019


***********************************************************************
Copyright (C) 2019 Progress Software Corporation and/or its 
subsidiaries or affiliates. All Rights Reserved. 
***********************************************************************

This README file contains information for Progress(R) DataDirect(R)  
for ODBC for Apache Cassandra(TM) Driver. 

This README file contains information not included in the PROGRESS
DATADIRECT(R) FOR ODBC FOR APACHE CASSANDRA DRIVER USER'S GUIDE AND REFERENCE.


CONTENTS

Driver Requirements
Installation Directory
Changes Since 8.0.0 Release
Release 8.0.0 Features
Required Operating System Patches
Configuring Data Sources
Notes, Known Problems, and Restrictions
Driver WorkAround Options
Documentation 
Installed Files for 32-bit Drivers
Installed Files for 64-bit Drivers


	Driver Requirements

The driver requires a Java Virtual Machine (JVM): Java SE 6 or higher. Also,
you must set the library path environment variable of your operating system
to the directory containing your JVM's libjvm.so [sl | a] file and that
directory's parent directory. 

	   
    Installation Directory 
	   
* The default installation directory for the 32-bit driver is:

  /opt/Progress/DataDirect/ODBC_80

* The default installation directory for the 64-bit driver is:

  /opt/Progress/DataDirect/ODBC_80_64bit
   
   
    Changes Since 8.0.0 Release 
	
Certifications
--------------
* Certified with OpenJDK 11
  Driver version 08.00.0101 (B0377, U0256) 

* Certified with OpenJDK 8 on Linux platforms 
  Driver version 08.00.0101 (B0377, U0256)

* Certified with Red Hat Enterprise 7.3 (driver version 
  08.00.0074 (B0238, U0156))
  
Data Consistency Level Enhancement
----------------------------------
* The driver has been enhanced to support all the data consistency levels for 
  read and write operations that are supported by Apache Cassandra data stores. 
  Data consistency levels are configured using the Read Consistency and Write 
  Consistency connection options. Refer to the user's guide and reference for
  descriptions of these options.   
   
   
    Release 8.0.0 Features  

The Progress DataDirect for ODBC for Apache Cassandra driver supports standard
SQL query language to select data from Apache Cassandra databases. In addition,
some insert, update, and delete capabilities are supported. The driver
translates the SQL statements provided by an application into native Cassandra
Query Language(CQL) statements, enabling you to leverage your knowledge 
of SQL.

Features:

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

* Certified against DataStax Enterprise 4.7, 4.8, 5.0
  
* Supports SQL read-write access to Apache Cassandra data sources.   

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

* Supports user id and password authentication. 

* Generates a relational view of Cassandra data. Tuple and user-defined types 
  are flattened into a relational parent table, while collection types are 
  mapped as relational child tables.
  
* Supports Native and Refresh escape sequences to embed CQL commands in 
  SQL-92 statements.

* Supports Cassandra's tunable consistency functionality with ReadConsistency
  and WriteConsistency connection options. 

* Supports the handling of large result sets through the FetchSize, 
  NativeFetchSize and ResultMemorySize connection options.

* Supports applications that do not support unbounded data types through
  the ASCIISize, DecimalPrecision, DecimalScale, VarintPrecision, and 
  VarcharSize connection options. 

* The driver supports the following data types:
  - ASCII	maps to SQL_VARCHAR
  - Bigint	maps to SQL_BIGINT
  - Blob	maps to SQL_LONGVARBINARY
  - Boolean	maps to SQL_BIT
  - Counter     maps to SQL_BIGINT
  - Date        maps to SQL_TYPE_DATE 
  - Decimal     maps to SQL_DECIMAL
  - Double	maps to SQL_DOUBLE
  - Float       maps to SQL_REAL
  - Inet        maps to SQL_VARCHAR
  - Int 	maps to SQL_INTEGER
  - List        maps to SQL_WLONGVARCHAR
  - Map         maps to SQL_WLONGVARCHAR
  - Set         maps to SQL_WLONGVARCHAR
  - Smallint    maps to SQL_SMALLINT
  - Time        maps to SQL_TYPE_TIME
  - Timestamp   maps to SQL_TYPE_TIMESTAMP
  - TimeUUID	maps to SQL_CHAR
  - TINYINT     maps to SQL_TINYINT
  - TUPLE       maps to SQL_WLONGVARCHAR
  - USERTYPE    maps to SQL_WLONGVARCHAR
  - UUID        maps to SQL_CHAR
  - Varchar     maps to SQL_WVARCHAR
  - Varint      maps to SQL_DECIMAL
  
 
    Required Operating System Patches

For HP-UX 11 aCC Users Only
---------------------------
The ODBC drivers for HP-UX 11 aCC are supported on HP-UX 11.0
when running with HP-UX applications built using the HP aCC 
compiler version 3.05 or higher.

The ODBC drivers require certain runtime library patches. HP-UX 
patches are publicly available from the HP Web site (www.hp.com). The 
required patch is:

PHSS_14577

HP updates the patch database regularly; therefore, the patch 
numbers in this file may be superseded by newer versions. If you 
search for any of the specified patches on an HP site and receive 
a message that a patch has been superseded, download and install 
the replacement patch.

 
 Configuring Data Sources

Data sources are stored in the system information file (typically, 
odbc.ini). For details on configuring this file, see the PROGRESS DATADIRECT
FOR ODBC FOR APACHE CASSANDRA DRIVER USER'S GUIDE AND REFERENCE.
 
 
	Notes, Known Problems, and Restrictions 

The following are notes, known problems, and restrictions for the 
8.0 release of the driver:

SQLColAttributes for Columns in Prepared Statements
---------------------------------------------------
SQLColAttributes currently returns the incorrect data types and searchability
for columns in prepared statements.

Row Counts for Semicolon Delimited Statement Batches
----------------------------------------------------
Contrary to the driver metadata returned, row counts for semicolon delimited 
statement batches are rolled up into a single value rather than being returned
for each explicit statement.

CURRENT OF Syntax Error 
-----------------------
Attempting to update data using a named cursor with the CURRENT OF cursor 
syntax currently returns an error.

Updates on Counter Columns
--------------------------
Update is supported for Counter columns only when all the other columns in the
row comprise that row's primary key. When updating a Counter column on an
existing row, the Counter column is updated according to the increment (or
decrement) specified in the SQL statement. When updating a Counter column for
which there is no existing row, the values of the columns that comprise the 
row's primary key are inserted into the table alongside the value of the 
Counter column. Note that Update is only supported using the native syntax. 

Out-of-memory Errors
--------------------
The driver has been designed to handle large result sets that result. However,
out-of-memory errors can occur. The following items outline how to reduce the
likelihood of out-of-memory errors for your environment.

* Reduce FetchSize to reduce demands on memory. By lowering the maximum number
  of rows as specified by FetchSize, you lower the number of rows the driver is
  required to process before returning data to the application. Thus, you 
  reduce demands on memory and decrease the likelihood of out-of-memory errors.

* Decrease ResultMemorySize until results are successfully returned. Intermediate
  results larger than the value specified will be written to disk as opposed to
  held in memory. When configured correctly, 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 impacts performance. For optimal performance, decrease this value
  only to a size necessary to avoid errors. By default, ResultMemorySize is set
  to -1, which sets the maximum size of intermediate results held in memory to 
  a percentage of the max Java heap size. If you received errors using the 
  default configuration, use the max Java heap size divided by 4 as a starting
  point when tuning this option.

* Increase the JVM heap size. By increasing the max Java heap size, you increase
  the amount of data the driver can accumulate in memory and avoid 
  out-of-memory errors.

system.indexes collection
-------------------------
The driver hides the system.indexes collection, and tables containing the "$"
character are hidden to prevent naming conflicts.

oplog.rs system table
---------------------
The driver hides the oplog.rs system table.

ODBC Development on UNIX and Linux Platforms
--------------------------------------------
All of the Release 8.0 Core Components (header files, etc.) needed for 
development of ODBC applications on UNIX and Linux are installed into 
the /include directory created by the product installer.

Please read the notices.txt file in the installation directory for 
licensing information regarding the ODBC Core Components. Contact your 
Progress DataDirect representative if you have any questions.

Developers using programming languages other than C++:
The DataDirect ODBC Driver Manager is a C++ shared library. The ODBC 
Driver Manager can be used with any language that supports loading a 
C++ shared library; however, if you are using a programming language 
other than C++, you must take additional steps to ensure that the C++ 
libraries are initialized properly when loaded. If you are not using 
C++, consult your compiler documentation for instructions on using C++ 
shared libraries with your application.
  
LANG Environment Setting on UNIX and Linux Platforms
----------------------------------------------------
A default installation of the product on UNIX and Linux assumes that 
the value of the LANG environment setting is en_US. If your locale is 
not set to en_US, the drivers may not return error messages properly. 
In this case, you must create a symbolic link in the 
<Install_Dir>/locale directory that has the same value as the LANG 
environment setting. This link must point to the 
<Install_Dir>/locale/en_US directory.
 
SQLColAttribute(s)
------------------
The column attributes 1001 and 1002, which were assigned as DataDirect- 
specific attributes, were inadvertently used as system attributes by
the Microsoft 3.0 ODBC implementation. Applications using those 
attributes must now use 1901 and 1902, respectively.
 
SQLDriverConnect
----------------
SQLDriverConnect using options other than SQL_DRIVER_NOPROMPT is 
supported only on systems that include the Motif libraries 
libivmback.so or libddmback.so and vscnctdlg.so.
 
SQL_C_NUMERIC
-------------
Because of inconsistencies in the ODBC specification, users attempting 
to use SQL_C_NUMERIC parameters must set the precision and scale values 
of the corresponding structure and the descriptor fields in the 
Application Parameter Descriptor.

For AIX Users
------------------------------
Some IBM AIX C compilers, such as xlc 3.1.4, do not support the use 
of C++ build binaries. C developers on AIX should consult their 
compiler documentation and verify that their AIX C compiler supports 
the use of C++ shared libraries or the application could be unstable.
 

    Driver WorkAround Options

Progress DataDirect has included non-standard connection options
(workarounds) for the Apache Cassandra driver that enable you to
take full advantage of packaged ODBC-enabled applications 
requiring non-standard or extendedbehavior.
Refer to the chapter "WorkAround Options" in THE PROGRESS DATADIRECT
FOR ODBC APACHE CASSANDRA DRIVER USER'S GUIDE AND REFERENCE for a 
description of these options.

      
     Documentation

THE PROGRESS DATADIRECT FOR ODBC FOR APACHE CASSANDRA DRIVER 
USER'S GUIDE AND REFERENCE
------------------------------------------------------------	 
The User's Guide and Reference is provided in PDF and HTML versions. Both 
versions are installed in the CassandraHelp subdirectory of your product 
installation directory. You can access the HTML help by opening the index.html
file. The PDF version, which you can view using Adobe Reader, can be viewed by 
opening the cassandraodbcuser.pdf file.

NOTE: To download Adobe Reader, visit the Adobe Web site at 
http://www.adobe.com.

  
    Installed Files for the 32-bit Driver
	 
This file list assumes a full installation of the 32-bit driver and 
documentation. 

The installer copies the following files and subdirectories to the 
product installation directory, by default:

/opt/Progress/DataDirect/ODBC_80:


odbc.csh              Setup script for C shell
odbc.ini              Sample odbc.ini file
odbcinst.ini          Sample odbcinst.ini file
odbc.sh               Setup script for Bourne shell
IVODBC.LIC            DataDirect license file
fixes.txt             List of fixes since last release
license.txt           End User License Agreement

/bin:
ivtestlib            Test application to check that required libraries
                     are present and loadable

/help: 
cassandra_connect.txt    Help text for the driver 
                         SQLDriverConnect dialog 

/help/CassandraHelp:
index.html               HTML help system entry file
cassandraodbcuser.pdf    PDF copy of the User's Guide and Reference
*.*                      Support folders for the HTML help system

/include:
odbcinst.h            Include files
qesqlext.h
sql.h
sqlext.h
sqltypes.h
sqlucode.h
sqlunx.h

/java/lib:
cassandra.jar         Java components of the driver

/lib:
The following library files all have the extension .so, except when 
installed on HP-UX PA-RISC, in which case the extension is .sl.

ivcsndr28.so          DataDirect Driver for Apache Cassandra 
ivtrc28.so            Progress DataDirect trace library
libivcurl28.so        Library used for HTTP connections  [.a on AIX]
libivicu28.so         Unicode conversion tables  [.a on AIX]
libivmbackw.so        SQLDriverConnect Motif library 
libodbc.so            ODBC Driver Manager [.a on AIX]
libodbcinst.so        ODBC Installer [.a on AIX]
odbc.so               ODBC Driver Manager (dynamically loadable) 
                      [AIX only]
odbccurs.so           ODBC Cursor library 
odbcinst.so           ODBC Installer (dynamically loadable) 
                      [AIX only]
vscnctdlg.so          ODBC library for Motif operations

/locale/en_US/LC_MESSAGES:
ivmbackw.mo           Motif library message file
ivmbackw.po           Motif library message source
ivcsndr28.mo          Apache Cassandra driver message file
ivcsndr28.po          Apache Cassandra driver message file source
odbc.m                ODBC Driver Manager message file
odbc.po               ODBC Driver Manager message source

/NOTICES:
ODBC for Apache Cassandra 
v8.0 notices.txt             Third-party vendor license agreements	

/READMES:
ODBC for Apache Cassandra 
v8.0 readme.txt	             This file

/samples:
/bulk/bulk                  Bulk application
/bulk/bulk.c                Bulk example source
/bulk/bulk.mak              Bulk example make file
/bulk/bulk.txt              Bulk example description
/bulk/ddlogging.properties  Log configuration file for the Cassandra driver

/bulkstrm/bulk.cpp          Bulk streaming example source
/bulkstrm/bulk.hpp          Bulk streaming example header
/bulkstrm/bulkstrm          Bulk streaming example application
/bulkstrm/bulkstrm.txt      Bulk streaming example description
/bulkstrm/main.cpp          Bulk streaming example source
/bulkstrm/msgprintf.hpp     Bulk streaming example header
/bulkstrm/streambulk.mak    Bulk streaming example make file
/bulkstrm/ddlogging.properties    Log configuration file for the 
                                  Cassandra driver

/example/example                 Example application
/example/example.c               Example source
/example/example.h               Example header
/example/example.mak             Example make file
/example/example.txt             Example description
/example/ddlogging.properties    Log configuration file for the 
                                 Cassandra driver
/tools:
ddextu                    License Extender utility
ddprocinfo                Processor Information utility

/uninstall/*.*           Files used to uninstall the product
							

    Installed Files for the 64-bit Driver
	 
This file list assumes a full installation of the 64-bit driver and 
documentation. 

The installer copies the following files and subdirectories to the 
product installation directory, by default:

/opt/Progress/DataDirect/ODBC_80:

odbc.csh              Setup script for C shell
odbc.ini              Sample odbc.ini file
odbcinst.ini          Sample odbcinst.ini file
odbc.sh               Setup script for Bourne shell
DDODBC.LIC            DataDirect license file
fixes.txt             List of fixes since last release
license.txt           End User License Agreement

/bin:
ddtestlib            Test application to check that required libraries
                     are present and loadable
/help: 
cassandra_connect.txt    Help text for the driver 
                     SQLDriverConnect dialog 
/help/CassandraHelp:
index.html           HTML help system entry file
cassandraodbcuser.pdf PDF copy of the User's Guide and Reference
*.*                  Support folders for the HTML help system

/include:
odbcinst.h            Include files
qesqlext.h
sql.h
sqlext.h
sqltypes.h
sqlucode.h
sqlunx.h

/java/lib:
cassandra.jar         Java components of the driver



/lib:
The following library files all have the extension .so, except when 
installed on HP-UX PA-RISC, in which case the extension is .sl.

ddcsndr28.so          DataDirect Driver for Apache Cassandra 
ddtrc28.so            Progress DataDirect trace library
libddcurl28.so        Library used for HTTP connections  [.a on AIX]
libddicu28.so         Unicode conversion tables  [.a on AIX]
libddmbackw.so        SQLDriverConnect Motif library 
libodbc.so            ODBC Driver Manager [.a on AIX]
libodbcinst.so        ODBC Installer [.a on AIX]
odbc.so               ODBC Driver Manager (dynamically loadable) 
                      [AIX only]
odbccurs.so           ODBC Cursor library 
odbcinst.so           ODBC Installer (dynamically loadable) 
                      [AIX only]
vscnctdlg.so          ODBC library for Motif operations

/locale/en_US/LC_MESSAGES:
ddmbackw.mo           Motif library message file
ddmbackw.po           Motif library message source
ddcsndr28.mo          Apache Cassandra driver message file
ddcsndr28.po          Apache Cassandra driver message file source
odbc.m                ODBC Driver Manager message file
odbc.po               ODBC Driver Manager message source

/NOTICES:
ODBC for Apache Cassandra 
v8.0 notices.txt             Third-party vendor license agreements	

/READMES:
ODBC for Apache Cassandra 
v8.0 readme.txt	             This file

/samples:
/bulk/bulk                  Bulk application
/bulk/bulk.c                Bulk example source
/bulk/bulk.mak              Bulk example make file
/bulk/bulk.txt              Bulk example description
/bulk/ddlogging.properties  Log configuration file for the Cassandra driver

/bulkstrm/bulk.cpp          Bulk streaming example source
/bulkstrm/bulk.hpp          Bulk streaming example header
/bulkstrm/bulkstrm          Bulk streaming example application
/bulkstrm/bulkstrm.txt      Bulk streaming example description
/bulkstrm/main.cpp          Bulk streaming example source
/bulkstrm/msgprintf.hpp     Bulk streaming example header
/bulkstrm/streambulk.mak    Bulk streaming example make file
/bulkstrm/ddlogging.properties    Log configuration file for the 
                                  Cassandra driver

/example/example                 Example application
/example/example.c               Example source
/example/example.h               Example header
/example/example.mak             Example make file
/example/example.txt             Example description
/example/ddlogging.properties    Log configuration file for the 
                                 Cassandra driver
/tools:
ddextu                    License Extender utility
ddprocinfo                Processor Information utility

/uninstall/*.*           Files used to uninstall the product



~~~~~~~~~~~~~~
March 1, 2019
End of README.TXT