OpenText Analytics Database 26.2.x – ODBC client driver

Connecting-To: Installing the ODBC client driver

Mon, 01 Jan 0001 00:00:00 +0000

To install ODBC, follow the instructions according to your platform. For a list of supported platforms, see Client drivers support.

This page covers a non-FIPS installation. To install ODBC on a FIPS-compliant system, see Installing the FIPS client driver for ODBC and vsql.

Installing OpenText™ Analytics Database on Linux

Installing OpenText™ Analytics Database from the RPM automatically installs the ODBC client driver, so you do not need to install them again on the machine running the database. To use the ODBC client driver, create a DSN.

To install the ODBC client driver manually on other machines:

Log in to the client system as root.
Verify that your system has a supported ODBC driver manager.
Download the ODBC client driver for Linux in the format appropriate for your distribution.
Install or extract the driver:
- If you downloaded the .rpm, install the driver:
  
  Note
  If the client driver is already installed on your system (either from a manual installation or from automatic installation from the OpenText™ Analytics Database RPM) and you attempt to reinstall them manually, you will receive error messages. To bypass these errors and overwrite the existing driver installations, use the --force flag.
```
$ rpm -Uvh driver_name.rpm
```
- If you downloaded the .tar, create the /opt/vertica/ directory if it does not already exist, copy the .tar to it, navigate to it, and extract the .tar:
```
$ mkdir -p /opt/vertica/
$ cp driver_name.tar.gz /opt/vertica/
$ tar vzxf driver_name.tar.gz
```
  This creates two directories:
  - /opt/vertica/include: Contains the header file.
  - /opt/vertica/lib64/ (64-bit) or /opt/vertica/lib/ (32-bit): Contains library files.
Set the following ODBC driver settings in vertica.ini. For details on each, see ODBC driver settings:
- ErrorMessagesPath: Required, the path of the directory containing the ODBC driver's error message files.
- ODBCInstLib: The path to the ODBC installer library. This is only required if the driver manager's installation library is not in the environment variables LD_LIBRARY_PATH or LIB_PATH.
- DriverManagerEncoding: The UTF encoding standard used by the driver manager. This is only required if your driver manager does not use UTF-8.
The following is an example configuration in vertica.ini:
- Use encoding for the 64-bit UNIXODBC driver manager.
- Use the error messages defined in the standard Vertica 64-bit ODBC driver installation directory.
- Log all warnings and more severe messages to log files in /tmp/
```
[Driver]
DriverManagerEncoding=UTF-16
ODBCInstLib=/usr/lib64/libodbcinst.so
ErrorMessagesPath=/opt/vertica
LogLevel=4
LogPath=/tmp
```
Create a DSN.

Installing on macOS

Note

You can only have one installation per version of the ODBC driver on a macOS system. This is because each installation is identified by a package ID and version number, and package ID does not change between versions of the driver.

To install the ODBC client driver on macOS:

Verify that your system has a compatible driver manager. The driver is designed to be used with the standard iODBC Driver Manager that ships with macOS. You can also use unixODBC.
Download the ODBC client driver.
If you installed a previous version of the ODBC driver, your system might already have a registered driver named "Vertica". You must remove or rename this older version of the driver before installing a new version from the .pkg installer. Renaming the older version allows you to retain the old version after you install the new one.
Run the installer.
Create a DSN.

Installing silently

Log into the client macOS in one of two ways:
- As an administrator account if you are installing the driver for system-wide use.
- As the user who needs to use the database ODBC driver.
Open a terminal.

Install the .pkg file containing the ODBC driver using the command:

sudo installer -pkg path/to/client/driver/vertica-odbc-xx.x.x-x.pkg -target /

Installing on Windows

To install the ODBC client driver on Windows:

Download the client driver installer for Windows.
Run the installer.
Create a DSN.

Installing silently

Open a terminal as an Administrator.
Run the following command to silently install the drivers to C:\Program Files\Vertica Systems:
```
VerticaSetup.exe -q -install InstallFolder="C:\Program Files\Vertica Systems"
```

Connecting-To: Upgrading and downgrading ODBC

Mon, 01 Jan 0001 00:00:00 +0000

Linux

To upgrade ODBC:

Uninstall the current version of the driver.
Install the new version of the driver.

macOS

To upgrade or downgrade ODBC:

Upgrade: Newly installed versions of the OpenText™ Analytics Database ODBC driver for macOS automatically upgrade the relevant driver system settings. Any DSNs associated with a previous version of the driver are not affected, except that they begin using the newer version of the driver.
Downgrade: Run the uninstall script to remove the current version of the database ODBC driver for macOS. Complete this step before installing an older driver version.

Windows

Download the Windows client driver installer.
Run the installer and follow the prompts to upgrade the driver. The installer upgrades existing drivers in place.
Reboot your system.

Connecting-To: Uninstalling ODBC

Mon, 01 Jan 0001 00:00:00 +0000

Linux

If you installed ODBC with the .rpm:

$ rpm -e package_name

If you installed ODBC with the .tar, delete the directory manually.

macOS

Uninstalling the macOS ODBC Client-Driver does not remove any existing DSNs associated with the driver.

To uninstall:

Open a terminal window.

Run the command:

sudo /Library/Vertica/ODBC/bin/Uninstall

Windows

Open the Add or Remove Programs menu.
EIther uninstall the Vertica Client Installer to remove all client drivers from the system or, to only uninstall ODBC, uninstall the following applications:
- Vertica ODBC Driver (32 Bit)
- Vertica ODBC Driver (64 Bit)

Connecting-To: Creating an ODBC data source name (DSN)

Mon, 01 Jan 0001 00:00:00 +0000

A Data Source Name (DSN) is the logical name that is used by Open Database Connectivity (ODBC) to refer to the driver and other information that is required to access data from a data source. Whether you are developing your own ODBC client code or you are using a third-party tool that needs to access OpenText™ Analytics Database using ODBC, you need to configure and test a DSN. The method you use depends upon the client operating system you are using.

Refer to the following sections for information specific to your client operating system.

Connecting-To: ODBC driver settings

Mon, 01 Jan 0001 00:00:00 +0000

Note

While required settings are required for all platforms, these settings automatically set by the Windows and macOS installers, so all directives to change these settings are for Linux users.

DriverManagerEncoding: The UTF encoding standard used by the driver manager. This can be one of the following:

UTF-8
UTF-16
UTF-32

The ODBC driver encoding must match that of your driver manager. The following table lists default encodings for various platforms that take effect if you do not set this parameter. If the defaults do not match the encoding used by your driver manager, you must set it manually. Consult your driver manager's documentation for details on its encoding.

Note

While both UTF-16 and UTF-8 are valid settings for the DataDirect driver manager, UTF-16 is recommended.

Client Platform	Default Encoding
Linux 32-bit	UTF-32
Linux 64-bit	UTF-32
Linux Itanium 64-bit	UTF-32
OS X	UTF-32
Windows 32-bit	UTF-16
Windows 64-bit	UTF-16

ErrorMessagesPath: Required, the path of the directory containing the ODBC driver's error message files. These files (ODBCMessages.xml and VerticaMessages.xml) are stored in the same directory as the OpenText™ Analytics Database ODBC driver files (for example, opt/vertica/en-US in the downloaded .tar).
ODBCInstLib: The path to the ODBC installer library. This setting is only required if the directory containing the library is not set in the LD_LIBRARY_PATH or LIB_PATH environment variables. The library files for the major driver managers are:
UnixODBC: libodbcinst.so
iODBC: libiodbcinst.so (libiodbcinst.2.dylib on macOS)
DataDirect: libodbcinst.so

You can also control client-server message logging for both ODBC and ADO.NET. For details, see Configuring ODBC logs.

Linux and macOS

To set these parameters on Linux or macOS:

Create a file vertica.ini anywhere on the client system. Common locations are in /etc/ for a shared configuration, or the home directory for a per-user configuration.
Verify that users of the ODBC driver have read privileges on the file.
Set the VERTICAINI environment variable to the path of vertica.ini. For example:

$ export VERTICAINI=/etc/vertica.ini

Create a section called [Driver] in vertica.ini:

[Driver]

Under [Driver], set parameters with the following format. Each parameter must have its own line:

[Driver]
DriverManagerEncoding=UTF-16
ODBCInstLib=/usr/lib64/libodbcinst.so

Windows

The Windows client driver installer automatically configures all necessary settings for the ODBC driver. Settings are stored in the registry in HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\ODBC\Driver.

If you want to configure ODBC further, use the ODBC Data Sources program.

Connecting-To: Configuring ODBC logs

Mon, 01 Jan 0001 00:00:00 +0000

The following parameters control whether and how the ODBC client driver logs messages between the client and server.

The way you set these parameters differs between operating systems:

On Linux and macOS, edit vertica.ini you created during the installation. For example, to log all warnings and more severe messages to log files in /tmp/:
```
[Driver]
LogLevel=4
LogPath=/tmp
```
On Windows, edit the keys in the Windows Registry under HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\ODBC\Driver.

Parameters

LogLevel: The severity of messages that are logged between the client and the server. The valid values are:
- 0: No logging
- 1: Fatal errors
- 2: Errors
- 3: Warnings
- 4: Info
- 5: Debug
- 6: Trace (all messages)
The value you specify for this setting sets the minimum severity for a message to be logged. For example, setting LogLevel to 3 means that the client driver logs all warnings, errors, and fatal errors.
LogPath: The absolute path of a directory to store log files. For example: /var/log/verticaodbc

Diverting log entires to ETW (windows)

On Windows clients, ODBC log entries can be sent to Event Tracing for Windows (ETW) so they appear in the Windows Event Viewer:

Register the driver as a Windows Event Log provider and enable the logs.
Activate ETW by adding a string value LogType with data ETW to your Windows Registry.
Understand how OpenText™ Analytics Database compresses log levels for the Windows Event Viewer.
Know where to find the logs within Event Viewer.
Understand the meaning of the Event IDs in your log entries.

Registering the ODBC driver as a windows event log provider

To use ETW logging, you must register the ODBC driver as a Windows Event Log provider. You can choose to register either the 32-bit or 64-bit driver. After you have registered the driver, you must enable the logs.

Important

If you do not both register the driver and enable the logs, output is directed to stdout.

Open a command prompt window as Administrator, or launch the command prompt with the Run as Administrator option.

Important
You must have administrator privileges to successfully complete the next step.

Run the command wevtutil im to register either the 32-bit or 64-bit version of the driver.

For the 64-bit ODBC driver, run:

wevtutil im "c:\Program Files\Vertica Systems\ODBC64\lib\VerticaODBC64.man"
/resourceFilePath:"c:\Program Files\Vertica Systems\ODBC64\lib\vertica_9.1_odbc_3.5.dll"
/messageFilePath:"c:\Program Files\Vertica Systems\ODBC64\lib\vertica_9.1_odbc_3.5.dll"

For the 32-bit ODBC driver, run:

wevtutil im "c:\Program Files (x86)\Vertica Systems\ODBC32\lib\VerticaODBC32.man"
/resourceFilePath:"c:\Program Files (x86)\Vertica Systems\ODBC32\lib\vertica_9.1_odbc_3.5.dll"
/messageFilePath:"c:\Program Files (x86)\Vertica Systems\ODBC32\lib\vertica_9.1_odbc_3.5.dll"

Run the command wevtutil sl to enable the logs.
- For 64-bit ODBC driver logs, run:
```
wevtutil sl VerticaODBC64/e:true
```
- For the 32-bit ODBC driver logs, run:
```
wevtutil sl VerticaODBC32/e:true
```
Note
Should you want to later disable the logs, you can use the same wevtutil sl command, substituting /e:false in place of /e:true when you issue the statement. Alternatively, you can enable or disable logs within the Windows Event Viewer itself.

Add the string value LogType

By default, the database does not send ODBC log entries to ETW. To activate ETW, add the string LogType to your Windows registry, and set its value to ETW.

Start the registry editor by typing regedit.exe in the Windows Run command box.
Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\ODBC\Driver in the registry.
Right-click in the right pane of the Registry Editor window.
Select New, then select String Value.
Change the name of the string value from New Value #1 to LogType.
Double-click the new LogType entry. When prompted for a new value, enter ETW.
Exit the registry editor.

ETW is disabled by default. When ETW is enabled, you can disable it by clearing the value ETW from the LogType string.

LogLevel in the windows event viewer

While LogLevel ranges from 0 through 6, this range is compressed for the Windows Event Viewer to a range of 0 through 3.

Vertica LogLevel Setting	Vertica LogLevel Description	Log level sent to the Windows Event Viewer	Log level displayed by the Windows Event Viewer
0	(No logging)	0	(No logging)
1	Fatal Errors	1	Critical
2	Errors	2	Error
3	Warnings	3	Warning
4	Info	4	Information
5	Debug	4
6	Trace (all messages)	4

The following examples show how LogLevel is converted when displayed in the Windows Event Viewer.

A LogLevel of 5 sends fatal errors, errors, warnings, info and debug log level entries to Event Viewer as Level 4 (Information).
A LogLevel of 6 sends fatal errors, errors, warnings, debug and trace log level entries to Event Viewer as Level 4.

Finding logs in the event viewer

Launch the Windows Event Viewer.
From Event Viewer (Local), expand Applications and Services Logs.
Expand the folder that contains the log you want to review (for example, VerticaODBC64).
Select the database ODBC log under the folder. Entries appear in the right pane.
Note the value in the Event ID field. Each Event Log entry includes one of four Event IDs:
- 0: Informational (debug, info, and trace events)
- 1: Error
- 2: Fatal event
- 3: Warning