Connection Cloud ODBC Driver for Windows platforms
Release 1.4.1
Software
The software is distributed as a zip file, containing at minimum:
- this file (ODBC_README.docx)
- CCODBCInstaller.exe
- CCODBCPackage.msi in the 32-bit version
- CCODBC64Package.msi in the 64-bit version
Unzip the file to any folder.
Supported OS/Application versions
The software has been tested under Windows XP, Windows Vista 32-bit and Windows 7
32-bit / 64-bit.
Functionality
The driver presents the data from a server as read-only. Data insert/update/delete are not
supported.
The current release does not support asynchronous operations.
Before Installation
Obtain the following information from the Connection Cloud administrator:
- QueryService URL
- User name
- Password
If you are planning to install the 64-bit driver on a system that already has a 32-bit
version installed, you may need to consider removing all the data sources created for the
32-bit version and uninstalling the 32-bit version because Microsoft ODBC manager does
not distinguish between DSNs created for use with 32-bit and 64-bit drivers. The
Connection Cloud DSN created previously for use with the 32-bit version will not work
with the 64-bit driver.
The same recommendation applies to installing the 32-bit version on a system that
already has the 64-bit driver installed.
Installation
Bring up the folder containing the unzipped contents. Double-click on the file
CCODBCInstaller.exe. Follow the installation steps. Once the installation is completed,
the Connection Configurator dialog will appear allowing the setup of a Connection Cloud
Data Source. See the section Add/Edit ODBC DSN for more information on this utility.
After connection setup is completed, the ODBC driver is ready for use.
By default the software is installed under the Connection Cloud ODBC Driver directory
under Program Files\Elastic Intelligence. Under Windows Vista 64-bit and Windows 7
64-bit, the 32-bit software is installed under the Program Files (x86)\ Elastic
Intelligence directory path. The name of the subdirectory is Connection Cloud ODBC
Driver for the 32-bit version, and Connection Cloud ODBC Driver 64-bit for the 64-bit
version. The installation process also creates the Start Menu program group named
Elastic Intelligence. Shortcuts to the Connection Configurator and the Windows Office
README file are created under this folder.
NOTE: Users running systems with Norton Antivirus may see the installation process
freeze, and then a warning about CCODBCInstaller.exe being a suspicious application.
It’s because the Norton SONAR application considers the Connection Cloud installation
program “unsafe” for attempting to call up the Microsoft Software Installer during the
installation process. In that situation, please temporarily disable SONAR. As other
antivirus functionality is still active, this should not affect the safety of the system.
NOTE 2: Users can also install by double-clicking on the CCODBCPackage.msi file.
However installing this way will not allow user to add the first Connection Cloud data
source right after installation.
Upgrade from Beta Releases
We recommend that any previously installed beta version of this software is to be
uninstalled before this version is installed.
Add/Edit ODBC DSN
Users may add or edit the ODBC DSN by either bring up the Connection Configurator
from the Elastic Intelligence ODBC menu, or by running the ODBC Data Sources editor.
To run the Connection Configurator, bring up the Windows Start menu, and locate the
menu entry Connection Configurator under the Elastic Intelligence -> ODBC driver
menu.
To run the ODBC Data Sources editor, find it at:
Windows XP:
Control Panel -> Performance and Maintenance -> Administrative Tools
Windows Vista 32-bit:
Control Panel -> System and Maintenance -> Administrative Tools
Windows 7 32-bit with 32-bit driver and Windows 7 64-bit with 64-bit driver:
Control Panel -> System and Security -> Administrative Tools
Windows 7 64-bit with 32-bit driver:
Run the program odbcad32.exe under the directory SysWOW64 under the
Windows directory.
Before creating a new Data Source
Obtain the following information from the Connection Cloud administrator:
- QueryService URL
- User name
- Password
Create/Edit Data Source using the Connection Configurator
The configurator runs after installation. The user can also run it from the Elastic
Intelligence -> ODBC Driver menu. The configurator allows user to create or edit a
Connection Cloud Data Source named ‘Connection Cloud’. The user can rename the
data source to a name other than ‘Connection Cloud’, but to edit a data source with name
other than the default, the user must use the ODBC Data Source Administrator (see
below.)
The configurator shows the following dialog (shown here with a user name and a
password already filled in):
Put the name you like in the Name field. That will be the name of the DSN.
The URL information can have either form:
- http://server_path
- https://server_path
For backward compatibility, the following forms are still supported, but deprecated:
- http://server_path/QueryService/QueryService
- https://server_path/QueryService/QueryService
Fill the rest of the fields with the information you have obtained earlier.
Click on the Test button to verify that ODBC can open a connection to the server using
the input values. If you did not fill all the required information, a dialog will prompt you
to do so.
You can also set the advanced behavior of the driver. To do so click on the Advanced
button. The following dialog will appear:
See the Advanced Settings section for more information about the advanced fields.
For most of the situations, the default settings are perfectly fine.
Click OK to save the DSN.
Create Data Source using the ODBC Data Source Administrator
The following dialog comes up when adding a DSN:
Select the Connection Cloud Driver entry, and click Finish. The Connection
Configurator dialog will come up (see above.)
Edit an existing DSN
Editing an existing DSN is very similar to adding one. Run the ODBC Data Source
Administrator. Instead of clicking on Add, select a DSN, and then click on Configure.
Make the necessary changes in the Connection Configurator dialog, and then click OK to
save the new settings.
Advanced Settings
The advanced options affect the behavior of the function SQLTables, and related
functions (SQLColumns, etc.)
Maximum bind row memory
Use this value as a workaround for some products such as Microsoft Query that does not
handle queries that have a large number (hundreds) of columns in the results. Because
Connection Cloud returns most of its character data columns as text type, the memory
required can be too much. Microsoft Query would silently not execute the query in such
cases (there is no error; the Wizart dialog is displayed again as if the execution has not
started.) Enter a value less than 24000 into this textbox (you may need to adjust the value
if the query still does not run.) When the value is defined, the ODBC driver scales the
text column size accordingly. While this may result in data truncation, the displayed
results may be useful as a form of data preview. Please do not define this value if data
integrity is of highest priority. Try to reduce the number of columns instead.
Note: other products don’t need this value set.
Character(s) to use in place of embedded period characters in column names
Use this value to map the period character embedded in some column names, as the
presence of these characters may cause operational problems with products such as
Microsoft Access and Microsoft Excel. By default the period is mapped to two
underscore characters. Use the period character if you do not want to map the character.
This field does not accept empty string value.
Maximum number of characters in a catalog/schema/table name
Some products such as Microsoft Query (used by Microsoft Excel) may have a limit on
the number of characters being used in a catalog/schema/table name. Any attempt to
retrieve a list of database tables would result in failure if there were some names
exceeding this limit. This textbox tells the ODBC driver to filter out any names that are
longer than the limit. The entries longer than such limit will not appear as part of the list.
In the case of MS Query the limit is 64 characters. Enter the number 64 in the textbox if
you are using the DSN in Excel.
Query timeout
If set, this value controls the number of seconds every query execution can take before
timing out (aborted.) By default, there is no timeout; the ODBC query operation will run
until being terminated by the server, or being interrupted by the calling program.
Fetch row buffer
If set, this value controls the maximum number of rows the ODBC attempts to retrieve
from the server in single query data request. Larger values may mean better performance
for queries with large result sets, while the smaller values mean the ODBC driver
requiring less memory to run (the memory size required very much dependent on the
average size per data row.) The default value is the maximum currently supported by the
Connection Cloud client and server: 1000.
Trace mode
Define this value to obtain application traces, which are used for technical support
purpose. Please do not define this value unless recommended by technical support.
Windows Registry
The driver manages a driver registry named Connection Cloud Driver under
ODBCINST.INI, and one entry for each DSN tied to the driver under ODBC.INI, named
after the driver. You must not modify registry entries because that may result in serious
problems.
Event Logging
The ODBC driver can be setup to log events to the Application event log. In the release
1.x, the driver logs only driver starting/stopping and error events. To view the events
logged by the driver, run the Event Viewer under Administrative Tools, and open the
Application log. The driver’s events are listed with Source value Connection Cloud.
There are three types of events: Information, Warning, and Error. The logged errors
are not necessarily the same as the errors the driver returns to the calling application.
They are errors, but might be non-fatal.
To log more event types, set the Trace Mode value in the DSN configuration dialog to
value 63. Caution is advised as this mode will fill the application event log with a lot of
events. A large application event log may negatively affect the performance of some
systems.
You can save the logged events by right-clicking on the Application log, and select Save
Log File As. The file can then be sent to Connection Cloud for inspection.
Troubleshooting
If you are running into error code 193 while using either the ODBC Data Source
Administrator or the Connection Cloud Connection Configurator (DSNManager), it’s
likely that your Data Source was defined for use for the wrong driver. If you have
installed both the 32-bit and 64-bit of the Connection Cloud driver, try using the other
ODBC Data Source Administrator. Error code 193 indicates that the execution code is in
the wrong binary format, conflicting with the administrator being used.
Known Issues
Timestamp values in searches
While the ODBC driver returns timestamp values as in local time. For accurate search
results, timestamp string values used in query predicate may need to be defined with a
time zone offset. The time zone offset is of the format –hh:mm or +hh:mm. The
Universal Time Clock (Greenwich Mean Time) has offset +00:00. The US East Coast
has either time zone offset of -04:00 when Daylight Savings Time applied or -05:00.
There are a few exceptions where the time zone offset is not necessary:
- When the user’s time zone is the same as the Connection Cloud server’s time
zone (Central time, offset -05:00 or -06:00).
- When the user’s time zone is the same as the Saleforce user account’s for
operations using the Salesforce Liberator.
Periods in column names are changed
By default the driver converts the periods appearing in column names to three
consecutive underscore characters as workaround for some applications generating
incorrect queries because they do not expect periods in column names. Therefore the
names of the columns that are replaced look different than the names at the original data
sources. This is expected, not an error.
Connection Cloud queries with declared parameters not shown in
table catalogs
Because queries with declared parameters cannot be treated as tables/views, they are not
listed as part of table catalog. Using these queries as tables in SQL statements without
passing the necessary parameter inputs will result in error SQLCODE 07002 – COUNT
field incorrect.
Question marks not yet supported in calls to queries with declared
parameters
While applications can execute queries with declared parameters through the ODBC API,
syntax using question marks (?) as parameter placeholders is currently not supported.
Attempts to do so result in runtime errors. Instead of writing a statement with question
marks to use in place of values that will be later bound/set with SQLBindParameter or
SQLPutData, rewrite the statement using Connection Cloud declared parameter syntax or
using the value literals directly.
For example, instead of using this statement:
SELECT * FROM Sales.CustomerOrderQuery(? AS “companyName”)
Rewrite it using declared parameter syntax:
DECLARE company TEXT;
SELECT * FROM Sales.CustomerOrderQuery(company AS “companyName”)
And use SQLBindParameter to bind the input value.
Or rewrite the original statement by embedding the value literals:
SELECT * FROM Sales.CustomerOrderQuery(‘ABC Corp.’ AS “companyName”)
In this case, there is no need to call SQLBindParameter.
Please note that this limitation does not apply to statements using standard SQL syntax.
It only applies to Connection Cloud’s specific syntax.
User Defined Types and Arrays are not supported
This version of the driver does not support User Defined Types and Arrays. Columns
with such attributes are not included in the column list represented by * or supported in
the queries. If a query statement lists such columns, the columns will not appear in the
result set.
Microsoft Query does not execute queries with large number of
columns
A query defined with a large number of columns (hundreds of columns) will not run with
Microsoft Query. MSQUERY Query Wizart either reports that there is a column limit, or
quietly terminates the execution of the query. Either reduce the number of columns for
the query, or if really necessary, define the Maximum bind row memory value as
described in the Advanced Settings.
Microsoft Query executes the same query twice before inserting data
into the spreadsheet
When importing data into the spreadsheet, Microsoft Query executes the same query
twice. For queries taking a while to run, this behavior incurs some additional running
time. To work around the problem, with this version, the ODBC driver has been
designed to “remember” the query for 2 minutes. If the user clicks OK on the placement
dialog within this amount of time, the driver re-uses the query results instead of starting
another execution. The driver will re-execute the query if the time is exceeded.
Uninstalling the Software
To uninstall the software:
Windows XP: Click on
Control Panel -> Add or Remove Programs
And select the Connection Cloud ODBC Driver in the list.
Windows Vista/7: Click on
Control Panel -> Programs -> Programs and Features -> Uninstall a Program
And select the Connection Cloud ODBC Driver in the list.