README
     Progress (R) DataDirect (R)
	 
     Progress(R) DataDirect(R) for ODBC for MongoDB(TM) Driver

     Windows Platforms (32- and 64-bit)
     8.0.1 Release   
     December 19, 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  
for ODBC for MongoDB(TM) Driver. 

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

IMPORTANT: You must have the Microsoft Data Access Components (MDAC) 
installed to use this product.
 
* For 32-bit Windows systems, version 2.6 or higher is required.
* For 64-bit Windows systems, version 2.8 or higher is required.

Depending on the version of your Windows operating system, these 
components may already be installed. You can download a utility that 
determines whether MDAC is installed and its version from the following 
Microsoft site:

http://msdn.microsoft.com/en-us/data/aa937730.aspx

You can also download MDAC from the same site. 

CONTENTS

Driver Requirements
Installation Directory
Changes Since 8.0.1 GA
Changes for 8.0.1 GA 
Release 8.0.0 Features 
The Progress DataDirect for ODBC for MongoDB Driver 
Driver WorkAround Options
Notes, Known Problems, and Restrictions
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.

 
	Installation Directory

* The default installation directory for the 32-bit driver on a 64-bit 
  system is:

  C:\Program Files (86)\Progress\DataDirect\ODBC_80

* The default installation directory for all other installations is:

  C:\Program Files\Progress\DataDirect\ODBC_80
  

    Changes Since 8.0.1 GA   
  
Certifications
--------------
* Certified with MongoDB 4.0 
  (driver version 08.01.0222 (B0481, U0331, J000420))
* Certified with OpenJDK 11
  (driver version 08.01.0194 (B0366, U0249)) 
* Certified with OpenJDK 8
  (driver version 08.01.0194 (B0366, U0249))
* Certified with MongoDB 3.4 (driver version 08.01.0156 
  (B0251, U0167, J000272))
* Certified with Windows Server 2016 (driver version 08.01.0152 (B0226, U0145))
* Certified with MongoDB 3.2 (driver version 08.01.0102  (B0131, U0094, 
  J000198))
  
Enhancements  
------------
* The CAST_TO_NATIVE function escape has been introduced to select or insert a
  value of a specific native type. This can be particularly useful when MongoDB
  has inconsistent native types for a given field. Currently, CAST_TO_NATIVE 
  can only be used with the ObjectID type in SELECT statement filters and 
  literal INSERT values.

Changed Behavior 
----------------
* Java SE 7 has reached the end of its product life cycle and will no longer 
  receive generally available security updates. As a result, the drivers will 
  no longer support JVMs that are version Java SE 7 or earlier. Support for 
  distributed versions of Java SE 7 and earlier will also end, including
  IBM SDK (Java Edition).  
  
* The following Windows platforms have reached the end of their product 
  lifecycle and are no longer supported 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)

Refer to the fixes.txt file in the product installation directory for a list of
changes by build number. 


    Changes for 8.0.1 GA

New Operating System Support
---------------------------- 	
* Certified with Windows 10. 

Name Conflict Resolution
------------------------
The driver has been enhanced to resolve naming conflicts that can occur when
exposing native objects using unquoted, uppercase identifiers (the default
behavior). To avoid conflicts, the driver appends an underscore separator 
and integer (for example, _1) to identifiers that differ only by case. 

DefaultVarcharSize, MaxVarcharSize, and MinVarcharSize Config Options  
---------------------------------------------------------------------
The DefaultVarcharSize config option has been enhanced to generate dynamic 
default lengths for VARCHAR columns when specifying a multiplier value (for
example, 2x) for the option. When specifying a multiplier value, the default
length for a VARCHAR column is determined by multiplying the value specified
by the size of the largest value detected in that column. This results in 
a default length that is proportionate to the size of the data within 
the column, which can improve the memory efficiency within the driver and 
application. The default value for this option has been updated to 1.5x.

In addition, you can further define the default length for VARCHAR columns by 
tuning the new MaxVarcharSize and MinVarcharSize config options. These options 
allow you to specify maximum and minimum size limits for the default length 
generated by the DefaultVarcharSize config option. When tuned for your data,
MaxVarcharSize and MinVarcharSize can provide additional memory efficiency 
and avoid undesired truncation of VARCHAR values.

KeywordConflictSuffix Config Option
-----------------------------------
The new KeywordConflictSuffix config option allows you to specify the suffix 
that is appended to object and field names that conflict with SQL engine 
keywords.
  
Tableau Data Source File  
------------------------
The driver includes a new Tableau data source file that provides improved
functionality when accessing your MongoDB data with Tableau. 
  
MongoDB Aggregation Framework
-----------------------------
The driver uses the MongoDB aggregation framework to improve performance in the
execution of SQL queries using LIMIT, ORDER BY, or TOP clauses.

New SQL Extensions
------------------
The RELOAD MAP and REFRESH MAP commands have been added to the driver.

* RELOAD MAP reloads the schema definition and associated files. RELOAD MAP
  updates your relational view of native data while the driver is connected to
  the data store. RELOAD MAP does not discover changes made to the native 
  data store. 

* REFRESH MAP discovers native objects that have been added to the native data
  store since connection or since the last refresh. REFRESH MAP incorporates
  newly discovered objects into your relational view of native data. It also 
  incorporates any configuration changes made to your relational view by 
  reloading the schema definition and associated files. REFRESH MAP is an 
  expensive query since it involves the discovery of native data. 
  
Dynamic Fetch Enhancement
-------------------------
The driver has been enhanced to improve the handling of large result sets and
reduce the likelihood of out-of-memory errors through the modification of the
Fetch Size connection option and the introduction of the Result Memory Size
connection option. See "Notes, Known Problems, and Restrictions" for details.
  
  
    Release 8.0.0 Features   

Certifications
--------------
* Certified with MongoDB 3.0 

Automatic Schema Definition Creation
------------------------------------
When first connecting to a MongoDB server, the driver automatically creates a
normalized schema of the data and generates a Schema Definition for housing and
sharing the normalized schema.

Full Normalization of Native Objects 
------------------------------------
Native MongoDB data is fully normalized during the normalization process, 
regardless of the depth of nested arrays, documents, and objects.

MongoDB Aggregation Framework
-----------------------------
The driver uses the MongoDB aggregation framework to improve performance in 
the execution of SQL queries using aggregates, GROUP BY clauses, or HAVING clauses.

Schema Tool Enhancements 
------------------------
* The new Restart Wizard feature allows you to reset the relational view of 
  your data from the Table Wizard menu.
* The new Update Schema feature allows you to map all new native objects to 
  your schema definition with a single click.
* Support for selecting multiple objects in the Table Wizard for improved 
  object management when customizing your schema. 

Min Long Varchar Connection Option 
----------------------------------
The new Min Long Varchar Size connection option allows you to fetch
SQL_LONGVARCHAR columns whose size is smaller than the minimum
imposed by some third-party applications. 

Varchar Threshold Connection Option 
-----------------------------------
The new Varchar Threshold connection option allows you to fetch columns
that would otherwise exceed the upper limit of the SQL_VARCHAR type for some
third-party applications. 

SQL Engine Mode Auto Setting
---------------------------- 
The SQL Engine Mode connection option now supports Auto mode. When this setting 
is enabled, the driver automatically determines whether the SQL engine runs in
server or direct mode based on availability. 


For more information about these features, refer to THE PROGRESS DATADIRECT FOR
ODBC FOR MONGODB DRIVER USER'S GUIDE AND REFERENCE.  


    The Progress DataDirect for ODBC for MongoDB Driver 

The Progress DataDirect for ODBC for MongoDB Driver supports standard SQL query
language to select data from MongoDB databases. In addition, some insert, 
update, and delete capabilities are supported. The driver translates the 
SQL statements provided by an application into native MongoDB-BSON statements,
enabling you to leverage your knowledge of SQL. The driver also includes
the DataDirect Schema Tool, which guides you through the process of mapping 
the MongoDB dynamic schema data model to a customized relational data model.  

Features:
---------
	
* The driver has been certified against the following MongoDB databases:
  * MongoDB version 3.0 
  * MongoDB version 2.2, 2.4, 2.6

* The driver supports all ODBC Core functions. 

* The driver supports the core SQL 92 grammar.

* The driver supports advanced security features, including SSL data 
  encryption.

* The driver supports the following data types:
  - Array		maps to SQL_LONGVARCHAR
  - Bigint		maps to SQL_BIGINT
  - BinData		maps to SQL_VARBINARY
  - Boolean		maps to SQL_BIT
  - Date		maps to SQL_TIMESTAMP
  - Double		maps to SQL_DOUBLE
  - Integer		maps to SQL_INTEGER
  - Object		maps to SQL_WLONGVARCHAR
  - ObjectID		maps to SQL_WVARCHAR
  - String		maps to SQL_WVARCHAR
  
* The DataDirect Schema Tool:
  - Enables you to flatten, normalize, or customize your view of 
    MongoDB data across a sharded or non-sharded environment.
  - Enables you to specify a primary key to ensure data integrity in a 
    sharded or non-sharded environment. 
  - Allows you to decide which MongoDB objects are extracted into 
    relational views.  
  - Provides information and statistics about your data. 
  - Exposes tabular relationships among your MongoDB collections.
  - Enables you to define your column data types.
  - Allows schema definitions to be shared across servers.
  - Supports advanced security features, including SSL data encryption. 

 
    Notes, Known Problems, and Restrictions 

Out-of-Memory Errors
--------------------
When processing large sets of data, out-of-memory errors can occur when the size
of an intermediate result exceeds the available memory allocated to the JVM. If
you are encountering these errors, you can tune Fetch Size or Result Memory 
Size to fit your environment.

* Reduce Fetch Size to reduce demands on the driver's internal memory. By
  lowering the maximum number of rows as specified by Fetch Size, you lower the
  number of rows the driver is required to process before returning data to the
  application. Thus, you reduce demands on the driver's internal memory, and, 
  in turn, decrease the likelihood of out-of-memory errors.
  
* To tune Result Memory Size, decrease the value specified until results are 
  successfully returned. Intermediate results larger than the specified setting
  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, Result Memory Size 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.   
  
Performance Issues When Executing Queries
-----------------------------------------
The 8.0 driver pushes down SQL queries to MongoDB whenever possible. Queries 
that cannot be pushed down to MongoDB in the 8.0 driver may be slower than 
comparable queries made with previous versions of the driver because data may 
be paged to disk while completing an operation. If you experience slow 
performance, please contact Technical Support: 
https://www.progress.com/support-and-services. Our team will quickly address 
any performance issues you may encounter.

In-Memory Tables
----------------
The driver no longer supports in-memory, or local, tables. As a result, alters,
creates, and drops are no longer supported. 	

SQL Engine Upgrade
------------------
The driver's SQL engine was upgraded for Release 8.0. Therefore, there 
are some differences in how the 8.0 driver handles SQL queries compared to 
previous versions of the driver. For more information, visit:
https://www.progress.com/datadirect-connect/features/progress-datadirect-sql
-engine-upgrade	

Support for 7.1.x Schema Definitions
------------------------------------
The 8.0.x version of the driver and Schema Tool do not support schema 
definitions created with previous versions of the product. Therefore, you
should reproduce your  7.1.x schema definitions with the 8.0.x driver or 
Schema Tool. 
	
Primary Keys in a Sharded Environment
-------------------------------------	
_id is assumed to be the primary key and row identifier for all tables
exposed via the driver. This assumption is typically valid; however, if
you are working with a sharded MongoDB collection, _id is not guaranteed
to be unique unless _id has been defined as the shard key for that 
collection. If the _id is not unique, write and join operations could
produce unpredictable and undesired results. 
  
To avoid undesired results, verify that the values of _id are unique 
before disabling the Read Only connection option. If needed, you can also 
designate the shard key as your primary key using the DataDirect
Schema Tool. For more information on designating the primary key, refer
to the "Using the Driver" chapter of the USER'S GUIDE AND REFERENCE.   
	
VARCHAR Truncation
------------------
For columns mapped to VARCHAR, the driver truncates values that exceed the
column size defined for the column when constructing the relational map of your
data. Refer to "About Column Information and Statistics" in the USER'S
GUIDE AND REFERENCE for details.

During the initial discovery and normalization process, you can use the
defaultVarcharSize configuration option to specify the default length of fields
that are discovered and mapped as Varchar by the driver. Refer to "Starting
the Schema Tool" in the USER'S GUIDE AND REFERENCE for details.

After the initial discovery and normalization process, you can define the
column size of individual columns from the main display of the Schema Tool.
Refer to "Defining Columns" in the USER'S GUIDE AND REFERENCE for details.

You can find the column size defined for a column either by selecting a table
from the main display of the Schema Tool or by calling or by executing the 
SQLColumns function.

VARBINARY Truncation
--------------------
For columns mapped to Varbinary, the driver truncates values that exceed the
column size defined for the column when constructing the relational map of your
data. Refer to "About Column Information and Statistics" in the 
USER'S GUIDE AND REFERENCE for details.

After the initial discovery and normalization process, you can define the
column size of individual columns from the main display of the Schema Tool.
Refer to "Defining Columns" in the USER'S GUIDE AND REFERENCE for details.

You can find the column size defined for a column either by selecting a table
from the main display of the Schema Tool or by executing the SQLColumns 
function.

Write Operations When Connected to a Replica Set
------------------------------------------------	
When connected to a replica set, you can execute Select, Insert, and Delete
against the primary node. However, you can only execute Select against
secondary members (follower servers).

Mapped Columns with Numeric Names
---------------------------------
When accessing data from a mapped column with a numeric name, you must 
enclose the column name in double quotes in the SQL statement. For example,
to select data from a column named 3, you submit the following statement:

SELECT "3" FROM 

Although numeric column names can be created a number of ways, they are 
typically the result of normalizing a collection that contains array fields. 

system.indexes Collection and Tables
------------------------------------
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.

  
    Documentation	 	 

THE PROGRESS DATADIRECT FOR ODBC FOR MONGODB DRIVER USER'S GUIDE AND REFERENCE
------------------------------------------------------------------------------
The guide is provided in PDF and HTML versions. 

The PDF version is available on the Progress DataDirect Web site, which you can
view using Adobe Reader. 

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

The HTML version of the book is installed in the MongoDBHelp subdirectory of
your product installation directory. You can access the help by opening the 
index.html file or by clicking the Help button on the driver setup dialog.

A separate Schema Tool help system is packaged with the driver. This help
system is installed in the SchemaToolHelp subdirectory of your product 
installation directory. The content of the Schema Tool help is also 
included in the User's Guide and Reference. 


	Installed Files the 32-bit Driver

This file list assumes a full installation of the driver and 
documentation.

The installer copies the following file to the Windows system 
directory:

ivtrc28.dll           DataDirect trace library

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

For 32-bit drivers on 64-bit machines:
  C:\Program Files (x86)\Progress\DataDirect\ODBC_80\:

For all other installations:
  C:\Program Files\Progress\DataDirect\ODBC_80\:

fixes.txt           List of fixes since last release
license.txt         Progress DataDirect license agreement

\drivers:
ivcurl28.dll            Library used for HTTP connections 
ivicu28.dll		Unicode conversion tables
ivmongo28.dll		MongoDB driver
ivmongo28r.dll		MongoDB driver
			resource file
ivmongo28s.dll		Progress DataDirect MongoDB driver
			setup library 
IVODBC.LIC		DataDirect License File
ivssl28.dll		SSL support file 
ivtrc28.dll             DataDirect trace library
qesqlext.h		Header file for DataDirect-specific ODBC Definitions


\help\MongoDBHelp: 
index.html          HTML help system entry file
\*.*                Support folders for the HTML help system

\help\SchemaToolHELP: 
index.html          HTML help system entry file for the Schema Tool
\*.*                Support folders for the HTML help system

\java\lib:
mongodb.jar	    Java components for the MongoDB Driver

\jre
*.*		    Files associated with the installer program

\NOTICES:
ODBC for MongoDB v8.0 notices.txt	Third-party vendor license agreements		

\READMES:
ODBC for MongoDB v8.0 readme.txt	This file

\samples:
\bulk\bulk.c        		  Bulk example source
\bulk\bulk.exe      		  Bulk application
\bulk\bulk.mak      		  Bulk example make file
\bulk\bulk.sln      		  Bulk example solution file
\bulk\bulk.vcproj   		  Bulk example project file
\bulk\ddlogging.properties        Log configuration file for the MongoDB driver
                       
\bulkstrm\bulk.cpp                Bulk streaming example source
\bulkstrm\bulk.hpp                Bulk streaming example header
\bulkstrm\bulk.rc                 Bulk streaming example resource file
\bulkstrm\bulkstreaming.sln       Bulk streaming example solution file
\bulkstrm\bulkstreaming.vcproj    Bulk streaming example project file
\bulkstrm\bulkstrm.exe            Bulk streaming example application
\bulkstrm\bulkstrm.txt   	  Bulk streaming description
\bulkstrm\ddlogging.properties    Log configuration file for the MongoDB driver
\bulkstrm\msgprintf.hpp           Bulk streaming example header file
\bulkstrm\ProgressDataDirect.bmp
\bulkstrm\ProgressDataDirect.ico
\bulkstrm\winmain.cpp             Bulk streaming example source file

\example\ddlogging.properties     Log configuration file for the MongoDB driver
\example\example.c         	  Example source
\example\Example.exe       	  Example application
\example\example.h         	  Example header
\example\Example.mak       	  Example make file
\example\Example.sln       	  Example solution file
\example\example.txt       	  Example description
\example\Example.vcproj    	  Example project file

\Tableau:
DataDirect MongoDB.tdc          Tableau data source file 

\tools:
ivextwin.exe			License Extender utility
ddprocinfo.exe			Processor Information utility
DSNConverterSIL.exe		Data Source Converter utility
mongodbserver32.exe		The MongoDB SQL Server Engine
schematool.jar			The Progress DataDirect Schema Tool
XMLP.exe			A GUI demo tool that persists a result set to 
                                an XML data file
						
\uninstall\*.*			Files used to uninstall the product

            
	Installed Files for 64-bit Drivers

This file list assumes a full installation of all drivers and 
documentation. 

The installer copies the following file to the Windows system 
directory:

ddtrc28.dll           DataDirect trace library

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

   C:\Program Files\Progress\DataDirect\ODBC_80\:

fixes.txt           List of fixes since last release
license.txt         Progress DataDirect license agreement

\drivers:
ddcurl28.dll            Library used for HTTP connections 
ddicu28.dll		Unicode conversion tables
ddmongo28.dll		MongoDB driver
ddmongo28r.dll		MongoDB driver
			resource file
ddmongo28s.dll		MongoDB driver
			setup library 
DDODBC.LIC		DataDirect License File
ddssl28.dll		SSL support file
ddtrc28.dll		DataDirect trace library
qesqlext.h		Header file for DataDirect-specific ODBC Definitions

\help\MongoDBHelp: 
index.html              HTML help system entry file
\*.*                    Support folders for the HTML help system

\help\SchemaToolHelp:
index.html HTML help system entry file for the Schema Tool
\*.* Support folders for the HTML help system

\java\lib:
mongodb.jar		Java components for the MongoDB Driver

\jre
*.*			Files associated with the installer program

\NOTICES:
ODBC for MongoDB v8.0 notices.txt	Third-party vendor license agreements

\READMES:
ODBC for MongoDB v8.0 readme.txt	This file

\samples:
\bulk\bulk.c        		  Bulk example source
\bulk\bulk.exe      		  Bulk application
\bulk\bulk.mak      		  Bulk example make file
\bulk\bulk.sln      		  Bulk example solution file
\bulk\bulk.vcproj   		  Bulk example project file
\bulk\ddlogging.properties        Log configuration file for the MongoDB driver
                       
\bulkstrm\bulk.cpp                Bulk streaming example source
\bulkstrm\bulk.hpp                Bulk streaming example header
\bulkstrm\bulk.rc                 Bulk streaming example resource file
\bulkstrm\bulkstreaming.sln       Bulk streaming example solution file
\bulkstrm\bulkstreaming.vcproj    Bulk streaming example project file
\bulkstrm\bulkstrm.exe            Bulk streaming example application
\bulkstrm\bulkstrm.txt 		  Bulk streaming description
\bulkstrm\ddlogging.properties    Log configuration file for the MongoDB driver
\bulkstrm\msgprintf.hpp           Bulk streaming example header file
\bulkstrm\ProgressDataDirect.bmp
\bulkstrm\ProgressDataDirect.ico
\bulkstrm\winmain.cpp             Bulk streaming example source file

\example\ddlogging.properties     Log configuration file for the MongoDB driver
\example\example.c         	  Example source
\example\Example.exe       	  Example application
\example\example.h         	  Example header
\example\Example.mak       	  Example make file
\example\Example.sln       	  Example solution file
\example\Example.vcproj    	  Example project file
\example\example.txt       	  Example description

\Tableau:
DataDirect MongoDB.tdc          Tableau data source file 

\TOOLS:
ddextwin.exe			License Extender utility
ddprocinfo.exe			Processor Information utility
DSNCOnverterSil.exe		Data Source Converter utility
mongodbserver64.exe		The MongoDB SQL Server Engine
schematool.jar			The Progress DataDirect Schema Tool
XMLP.exe			A GUI demo tool that persists a result set to 
                                an XML data file
						
\uninstall\*.*			Files used to uninstall the product


   
~~~~~~~~~~~~~~~
December 19, 2019
End of README.TXT