OpenText Analytics Database 26.2.x – Creating an ODBC data source name (DSN)

Connecting-To: Creating an ODBC DSN for Linux

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

You define DSN on Linux and other UNIX-like platforms in a text file. Your client's driver manager reads this file to determine how to connect to your OpenText™ Analytics Database. The driver manager usually looks for the DSN definitions in two places:

/etc/odbc.ini
~/.odbc.ini (a file named .odbc.ini in the user's home directory)

Users must be able to read the odbc.ini file in order to use it to connect to the database. If you use a global odbc.ini file, consider creating a UNIX group with read access to the file. Then, add the users who need to use the DSN to this group.

The structure of these files is the same—only their location differs. If both files are present, the ~/.odbc.ini file usually overrides the system-wide /etc/odbc.ini file.

Note

See your ODBC driver manager's documentation for details on where these files should be located and any other requirements.

odbc.ini file structure

The odbc.ini is a text file that contains two types of lines:

Section definitions, which are text strings enclosed in square brackets.
Parameter definitions, which contain a parameter name, an equals sign (=), and then the parameter's value.

Caution

The unixODBC driver manager supports parameter values of up to 1000 characters in odbc.ini. If your parameter value is greater than 1000 characters (for example, OAuthAccessToken), you must pass it through a connection string rather than specifying it in odbc.ini.

The first section of the file is always named [ODBC Data Sources], and contains a list of all the DSNs that the odbc.ini file defines. The parameters in this section are the names of the DSNs, which appear as section definitions later in the file. The value is a text description of the DSN and has no function. For example, an odbc.ini file that defines a single DSN named Vertica DSN could have this ODBC Data Sources section:

[ODBC Data Sources]
VerticaDSN = "vmartdb"

Appearing after the ODBC data sources section are sections that define each DSN. The name of a DSN section must match one of the names defined in the ODBC Data Sources section.

Configuring the odbc.ini file:

To create or edit the DSN definition file:

Using the text editor of your choice, open odbc.ini or ~/.odbc.ini.
Create an ODBC Data Sources section and define a parameter:
- Whose name is the name of the DSN you want to create
- Whose value is a description of the DSN
For example, to create a DSN named VMart, you would enter:
```
[ODBC Data Sources]
VMart = "VMart database on OpenText&trade; Analytics Database"
```
Create a section whose name matches the DSN name you defined in step 2. In this section, you add parameters that define the DSN's settings. The most commonly-defined parameters are:
- Description – Additional information about the data source.
- Driver – The location and designation of the ODBC driver, or the name of a driver defined in the odbcinst.ini file (see below). For future compatibility, use the name of the symbolic link in the library directory, rather than the library file:
  - ( /opt/vertica/lib, on 32-bit clients
  - /opt/vertica/lib64, on 64-bit clients
  For example, the symbolic link for the 64-bit ODBC driver library is:
```
/opt/vertica/lib64/libverticaodbc.so
```
  The symbolic link always points to the most up-to-date version of the database client ODBC library. Use this link so that you do not need to update all of your DSNs when you update your client drivers.
- Database – The name of the database running on the server. This example uses vmartdb for the vmartdb.
- ServerName — The name of the server where the database is installed. Use localhost if the database is installed on the same machine.
  
  You can provide an IPv4 address, IPv6 address, or host name.
  
  In mixed IPv4/IPv6 networks, the DNS server configuration determines which IP version address is sent first. Use the PreferredAddressFamily option to force the connection to use either IPv4 or IPv6.
- UID — Either the database superuser (same name as database administrator account) or a user that the superuser has created and granted privileges. This example uses the user name dbadmin.
- PWD —The password for the specified user name. This example leaves the password field blank.
- Port — The port number on which the database listens for ODBC connections. For example, 5433.
- ConnSettings — Can contain SQL commands separated by a semicolon. These commands can be run immediately after connecting to the server.
- SSLKeyFile — The file path and name of the client's private key. This file can reside anywhere on the system.
- SSLCertFile —The file path and name of the client's public certificate. This file can reside anywhere on the system.
- Locale — The default locale used for the session. By default, the locale for the database is: en_US@collation=binary (English as in the United States of America). Specify the locale as an ICU Locale. See the ICU User Guide (http://userguide.icu-project.org/locale) for a complete list of parameters that can be used to specify a locale.
- PreferredAddressFamily:
  
  The IP version to use if the client and server have both IPv4 and IPv6 addresses and you have provided a host name, one of the following:
  - ipv4: Connect to the server using IPv4.
  - ipv6: Connect to the server using IPv6.
  - none: Use the IP address provided by the DNS server.

For example:

[VMart]
Description = Vmart Database
Driver = /opt/vertica/lib64/libverticaodbc.so
Database = vmartdb
Servername = host01
UID = dbadmin
PWD =
Port = 5433
ConnSettings =
AutoCommit = 0
SSLKeyFile = /home/dbadmin/client.key
SSLCertFile = /home/dbadmin/client.crt
Locale = en_US@collation=binary

See ODBC DSN connection properties for a complete list of parameters including database-specific ones.

Using an odbcinst.ini file

Instead of giving the path of the ODBC driver library in your DSN definitions, you can use the name of a driver defined in the odbcinst.ini file. This method is useful method if you have many DSNs and often need to update them to point to new driver libraries. It also allows you to set some additional ODBC parameters, such as the threading model.

Just as in the odbc.ini file, odbcinst.ini has sections. Each section defines an ODBC driver that can be referenced in the odbc.ini files.

In a section, you can define the following parameters:

Description— Additional information about the data source.
Driver— The location and designation of the ODBC driver, such as /opt/vertica/lib64/libverticaodbc.so

For example:

[Vertica]
Description = ODBC Driver
Driver = /opt/vertica/lib64/libverticaodbc.so

Then, in your odbc.ini file, use the name of the section you created in the odbcinst.ini file that describes the driver you want to use. For example:

[VMart]
Description = Vmart database
Driver = Vertica

If you are using the unixODBC driver manager, you should also add an ODBC section to override its standard threading settings. By default, unixODBC serializes all SQL calls through ODBC, which prevents multiple parallel loads. To change this default behavior, add the following to your odbcinst.ini file:

[ODBC]
Threading = 1

Configuring additional ODBC settings

On Linux and UNIX systems, you need to configure some additional driver settings before you can use your DSN. See ODBC driver settings for details.

Connecting-To: Creating an ODBC DSN for windows clients

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

To create a DSN for Microsoft Windows clients, you must perform the following tasks:

Connecting-To: Creating an ODBC DSN for macOS clients

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

You can use the OpenText™ Analytics Database ODBC Driver to set up an ODBC DSN. This procedure assumes that the driver is already installed, as described in Installing the ODBC client driver.

Setting up a DSN

Using your web browser, download and install the Apple ODBC Administrator Tool.
Locate and open the ODBC Administrator Tool after installation:
1. Navigate to Finder > Applications > Utilities.
2. Open the ODBC Administrator Tool.
Click the Drivers tab, and verify that the database driver is installed.
Specify if you want all users on your client system to be able to access the DSN for the database:
- If you want all users to have access, then click the System DSN tab.
- Otherwise, click the User DSN tab to create a DSN that is only usable by your Macintosh user account.
Click Add... to create a new DSN to connect to the database.
Scroll through the list of drivers in the Choose A Driver dialog box to locate the database driver. Select the driver and click OK. A dialog box opens that requests DSN parameter information.
In the dialog box, enter the Data Source Name (DSN) and an optional Description. To do so, click Add to insert keywords (parameters) and values that define the settings needed to connect to your database, including database name, server host, database user name (such as dbadamin), database password, and port. Then, click OK.
In the ODBC Administrator dialog box, click Apply.

See ODBC DSN connection properties for a complete list of parameters including those specific to the database.

After configuring the ODBC Administrator Tool, you may need to configure additional driver settings before you can use your DSN, depending on your environment. See Additional ODBC Driver Configuration Settings for details.

Note

To test your connection, use the iodbctest utility. For details, see Testing an ODBC DSN using iodbctest.

Connecting-To: ODBC DSN connection properties

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

The following tables list the connection properties you can set in the DSNs for use with OpenText™ Analytics Database's ODBC driver. To set these parameters, see Setting DSN connection properties.

Required connection properties

These connection properties are the minimum required to create a functioning DSN.

Note

If you use a host name (Servername) whose DNS entry resolves to multiple IP addresses, the client attempts to connect to the first IP address returned by the DNS. If a connection cannot be made to the first address, the client attempts to connect to the second, then the third, continuing until it either connects successfully or runs out of addresses.

Property	Description
Driver	The file path and name of the driver used.
Database	The name of the database running on the server.
Servername	The host name or IP address of any active node in a database cluster. You can provide an IPv4 address, IPv6 address, or host name. In mixed IPv4/IPv6 networks, the DNS server configuration determines which IP version address is sent first. Use the `PreferredAddressFamily` option to force the connection to use either IPv4 or IPv6. You can also use the aliases "server" and "host" for this property.
UID	The database username.

Optional properties

Property Description

Port

Property	Description
Port	The port number on which the database listens for ODBC connections. Default: 5433
PWD	The password for the specified user name. You may insert an empty string to leave this property blank. Default: None, login only succeeds if the user does not have a password set.
PreferredAddressFamily	The IP version to use if the client and server have both IPv4 and IPv6 addresses and you have provided a host name, one of the following: `ipv4`: Connect to the server using IPv4. `ipv6`: Connect to the server using IPv6. `none`: Use the IP address provided by the DNS server. Default: none

The port number on which the database listens for ODBC connections.

Default: 5433

PWD

The password for the specified user name. You may insert an empty string to leave this property blank.

Default: None, login only succeeds if the user does not have a password set.

PreferredAddressFamily

The IP version to use if the client and server have both IPv4 and IPv6 addresses and you have provided a host name, one of the following:

ipv4: Connect to the server using IPv4.
ipv6: Connect to the server using IPv6.
none: Use the IP address provided by the DNS server.

Default: none

Advanced settings

Property	Description
AutoCommit	A Boolean value that controls whether the driver automatically commits transactions after executing a DML statement. Default: true
BackupServerNode	A string containing the host name or IP address that client libraries can try to connect to if the host specified in ServerName is unreachable. Connection attempts continue until successful or until the list of server nodes is exhausted. Valid values: Comma-separated list of servers optionally followed by a colon and port number.
ConnectionLoadBalance	A Boolean value that indicates whether the connection can be redirected to a host in the database other than the ServerNode. This affects the connection only if the load balancing. is set to something other than "none". When the node differs from the node the client is connected to, the client disconnects and reconnects to the targeted node. See About Native Connection Load Balancing in the Administration Guide. Default: false
ConnSettings	A string containing SQL commands that the driver should execute immediately after connecting to the server. You can use this property to configure the connection, such as setting a schema search path. Reserved symbol: In the connection string semicolon (`;`) is a reserved symbol. To set multiple properties as part of ConnSettings properties, use `%3B` as the comma delimiter, and `+` (plus) for spaces.
ConnectionTimeout	The number of seconds to wait for a request to complete before returning to the client application. This is equivalent to the SQL_ATTR_CONNECTION_TIMEOUT parameter in the ODBC API. Default: 0 (no timeout)
ConvertSquareBracketIdentifiers	Controls whether square-bracket query identifiers are converted to a double quote identifier for compatibility when making queries to a database. Default: false
DirectBatchInsert	Deprecated, always set to true.
DriverStringConversions	Controls whether the ODBC driver performs type conversions on strings sent between the ODBC driver and the database. Possible values are: NONE: No conversion in either direction. This results in the highest performance. INPUT: Strings sent from the client to the server are converted, but strings sent from the server to the client are not. OUTPUT: Strings sent by the server to the client are converted, but strings sent from the client to the server are not. BOTH: Strings are converted in both directions. Default: OUTPUT
Locale	The locale used for the session. Specify the locale as an ICU Locale. See the ICU User Guide for a complete list of properties that can be used to specify a locale. Default: `en_US@collation=binary`
PromptOnNoPassword	[Windows only] Controls whether users are prompted to enter a password, if none is supplied by the connection string or DSN used to connect to the database. See Prompting windows users for passwords. Default: false
ReadOnly	A true or false value that controls whether the connection can read data only from the database. Default: false
ResultBufferSize	Size of memory buffer for the large result sets in streaming mode. A value of 0 means ResultBufferSize is turned off. Default: 131072 (128KB)
TransactionIsolation	Sets the transaction isolation for the connection, one of the following: Read Committed Serializable Server Default See Changing Transaction Isolation Levels for an explanation of transaction isolation. Default: Server Default
Workload	The name of the workload for the session. For details, see Workload routing. Default: None (no workload)

Identification

Property	Description	Standard/ Vertica
Description	Description for the DSN entry. Required? No Insert an empty string to leave the description empty.	Standard
Label / SessionLabel	Sets a label for the connection on the server. This value appears in the client_label column of the V_MONITOR.SESSIONS system table. Label and SessionLabel are synonyms and can be used interchangeably.	Vertica

Property

Description

Standard/ Vertica

Description

Description for the DSN entry.

Required? No

Insert an empty string to leave the description empty.

Standard

Label / SessionLabel

Sets a label for the connection on the server. This value appears in the client_label column of the V_MONITOR.SESSIONS system table.

Label and SessionLabel are synonyms and can be used interchangeably.

Vertica

OAuth connection properties

The following connection properties pertain to OAuth in ODBC.

Caution

Property	Description
AccessToken	Required if OAuthRefreshToken is unspecified, an OAuth token that authorizes a user to the database. Either OAuthAccessToken or OAuthRefreshToken must be set (programmatically or manually) to authenticate to OpenText™ Analytics Database with OAuth authentication. You can omit both OAuthAccessToken and OAuthRefreshToken only if you authenticate to your identity provider directly with single sign-on through the client driver, which requires the machine running the ODBC driver to have access to a web browser. For details on the different methods for retrieving access tokens, see Retrieving access tokens.
RefreshToken	Deprecated Use OAuthAccessToken instead. Token refresh should be handled by the client application separately. Required if OAuthAccessToken is unspecified, a token that used to obtain a new access token when their old one expires. Either OAuthAccessToken or OAuthRefreshToken must be set (programmatically or manually) to authenticate to OpenText™ Analytics Database with OAuth authentication. You can omit both OAuthAccessToken and OAuthRefreshToken only if you authenticate to your identity provider directly with single sign-on through the client driver, which requires the machine running the ODBC driver to have access to a web browser. For details on the different methods for retrieving access tokens, see Retrieving access tokens. If you set this parameter, you must also set the OAuthClientSecret connection property. In cases where introspection fails (e.g. when the access token expires), OpenText™ Analytics Database responds to the request with an error. If introspection fails and OAuthRefreshToken is specified, the driver attempts to refresh and silently retrieve a new access token. Otherwise, the driver passes error to the client application.
OAuth Redirect Port	Optional. Sets the desired OAuth redirect port for OAuth web browser login.
Client ID	Required. The ID of the confidential client application registered in the identity provider. The database uses this ID to call the introspection API to retrieve user grants.
ClientSecret	Deprecated Use OAuthAccessToken instead. Token refresh should be handled by the client application separately. The secret provided by your identity provider for your client. This parameter is required for confidential clients.
Token URL	Required for single-sign on (SSO). This is the token endpoint provided by your identity provider.
Discovery URL	The database uses this endpoint to retrieve information about the identity provider's configuration and other endpoints (Keycloak only).
Scope	Optional. The requested OAuth scopes define the extent of access for OAuth web browser login.

Multi factor authentication

Property	Description
Totp	Specify the current Time-based One-time Password (Totp) value. The Totp is sent to the server in the connection string for validation. If MFA is enforced and you do not provide a Totp, a dialog is displayed. You need to enter the Totp before proceeding with authentication. Totp values are generated at 30-second intervals. A Totp code remains valid for up to 90 seconds.

Encryption

Property Description Standard/ Vertica

SSLMode

Property	Description	Standard/ Vertica
SSLMode	Controls whether the connection to the database uses SSL encryption, one of the following. For information on using these parameters to configure TLS, see Configuring TLS for ODBC Clients: `require`: Requires that the server use TLS. If the TLS connection attempt fails, the client rejects the connection. `prefer`: Prefers that the server use TLS. The client first attempts to connect using TLS. If that attempt fails, the client attempts to connect again in plaintext. Note On Windows, the supported options are `require` and `prefer`. * `verify-ca`: The client verifies that the server's certificate was issued by a trusted certificate authority (CA). * `verify-full`: The client verifies that the following conditions are met: - The server's certificate was issued by a trusted CA. - One of the following: - The server's hostname matches the common name specified in the server's certificate. - The server's hostname or IP address appears in the Subject Alternative Name (SAN) field of the server's certificate. `disable`: Never connect to the server using TLS. This setting is typically used for troubleshooting. Default: prefer	Vertica
SSLCertFile	The absolute path of the client's public certificate file. This file can reside anywhere on the system.	Vertica
SSLKeyFile	The absolute path to the client's private key file. This file can reside anywhere on the system.	Vertica

Controls whether the connection to the database uses SSL encryption, one of the following. For information on using these parameters to configure TLS, see Configuring TLS for ODBC Clients:

require: Requires that the server use TLS. If the TLS connection attempt fails, the client rejects the connection.
prefer: Prefers that the server use TLS. The client first attempts to connect using TLS. If that attempt fails, the client attempts to connect again in plaintext.

Note

On Windows, the supported options are require and prefer.

* `verify-ca`: The client verifies that the server's certificate was issued by a trusted certificate authority (CA). * `verify-full`: The client verifies that the following conditions are met: - The server's certificate was issued by a trusted CA. - One of the following: - The server's hostname matches the common name specified in the server's certificate. - The server's hostname or IP address appears in the Subject Alternative Name (SAN) field of the server's certificate.

disable: Never connect to the server using TLS. This setting is typically used for troubleshooting.

Default: prefer

Vertica

SSLCertFile The absolute path of the client's public certificate file. This file can reside anywhere on the system. Vertica

SSLKeyFile The absolute path to the client's private key file. This file can reside anywhere on the system. Vertica

Third-party compatibility

Property Description Default Standard/ Vertica

Property	Description	Default	Standard/ Vertica
ColumnsAsChar	Specifies how character column types are reported when the driver is in Unicode mode. When set to false, the ODBC driver reports the data type of character columns as WCHAR. If you set ColumnsAsChar to true, the driver identifies character column as CHAR. You typically use this setting for compatibility with some third-party clients. Default: false	`false`	Vertica
ThreePartNaming	A Boolean value that controls how catalog names are interpreted by the driver. When this value is false, the driver reports that catalog names are not supported. When catalog names are not supported, they cannot be used as a filter in database metadata API calls. In this case, the driver returns NULL as the catalog name in all driver metadata results. When this value is true, catalog names can be used as a filter in database metadata API calls. In this case, the driver returns the database name as the catalog name in metadata results. Some third-party applications assume a certain catalog behavior and do not work properly with the default values. Enable this option if your client software expects to get the catalog name from the database metadata and use it as part of a three-part name reference. Default: false for UNIX, true for Windows	`false` (UNIX) `true` (Window)	Vertica
EnforceBatchInsertNullConstraints	Prevents NULL values from being loaded into columns with a NOT NULL constraint during batch inserts. When this value is set to true, batch inserts roll back when NULL values are inserted in to columns with NOT NULL constraints. When this value is set to false, batch insert behavior is unchanged. OpenText recommends using this property only with SAP Data Services as it could negatively impact database performance.	`false`	Vertica

ColumnsAsChar

Specifies how character column types are reported when the driver is in Unicode mode. When set to false, the ODBC driver reports the data type of character columns as WCHAR. If you set ColumnsAsChar to true, the driver identifies character column as CHAR.

You typically use this setting for compatibility with some third-party clients.

Default: false

false

Vertica

ThreePartNaming

A Boolean value that controls how catalog names are interpreted by the driver. When this value is false, the driver reports that catalog names are not supported. When catalog names are not supported, they cannot be used as a filter in database metadata API calls. In this case, the driver returns NULL as the catalog name in all driver metadata results.

When this value is true, catalog names can be used as a filter in database metadata API calls. In this case, the driver returns the database name as the catalog name in metadata results. Some third-party applications assume a certain catalog behavior and do not work properly with the default values. Enable this option if your client software expects to get the catalog name from the database metadata and use it as part of a three-part name reference.

Default: false for UNIX, true for Windows

false (UNIX)

true (Window)

Vertica

EnforceBatchInsertNullConstraints

Prevents NULL values from being loaded into columns with a NOT NULL constraint during batch inserts. When this value is set to true, batch inserts roll back when NULL values are inserted in to columns with NOT NULL constraints. When this value is set to false, batch insert behavior is unchanged.

OpenText recommends using this property only with SAP Data Services as it could negatively impact database performance.

false

Vertica

Kerberos connection properties

Use the following properties for client authentication using Kerberos.

Property Description Standard/ Vertica

KerberosServiceName

Property	Description	Standard/ Vertica
KerberosServiceName	Provides the service name portion of the database Kerberos principal; for example: `vertichost@EXAMPLE.COM` Default: vertica	Vertica
KerberosHostname	Provides the instance or host name portion of the database Kerberos principal; for example: `verticaosEXAMPLE.COM` Default: Value specified in the servername connection string property	Vertica

Provides the service name portion of the database Kerberos principal; for example: vertichost@EXAMPLE.COM

Default: vertica

Vertica

KerberosHostname

Provides the instance or host name portion of the database Kerberos principal; for example: verticaosEXAMPLE.COM

Default: Value specified in the servername connection string property

Vertica

Connecting-To: Setting DSN connection properties

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

The properties in the following tables are common for all user and system DSN entries. The examples provided are for Windows clients.

To edit DSN properties:

On UNIX and Linux client platforms, you can edit the odbc.ini file. The location of this file is specific to the driver manager. See Creating an ODBC DSN for Linux.
On Windows client platforms, you can edit some DSN properties using the OpenText™ Analytics Database ODBC client driver interface. See Creating an ODBC DSN for windows clients.
You can also edit the DSN properties directly by opening the DSN entry in the Windows registry (for example, at HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\DSNname). Directly editing the registry can be risky, so you should only use this method for properties that cannot be set through the ODBC driver's user interface, or via your client code.

You can set properties in the connection string when opening a connection using the SQLDriverConnect() function:

sqlRet = SQLDriverConnect(sql_hDBC, 0, (SQLCHAR*)"DSN=DSNName;Locale=en_GB@collation=binary", SQL_NTS, szDNS, 1024,&nSize, SQL_DRIVER_NOPROMPT);

Note

In the connection string ';' is a reserved symbol. If you need to set multiple properties as part of the ConnSettings property use '%3B' in place of ';'. Also use '+' instead of spaces.

For example:

sqlRet = SQLDriverConnect(sql_hDBC, 0, (SQLCHAR*)"DSN=Vertica SQL;ConnSettings=set+search_path+to+a,b,c%3Bset+locale=ch;SSLMode=prefer", SQL_NTS,
szDNS, 1024,&nSize, SQL_DRIVER_NOPROMPT);

Your client code can retrieve DSN property values after a connection has been made to the database using the SQLGetConnectAttr() and SQLGetStmtAttr() API calls. Some properties can be set and using SQLSetConnectAttr() and SQLSetStmtAttr().

For details of the list of properties specific to the database, see ODBC Header Files specific to OpenText™ Analytics Database.

OpenText Analytics Database 26.2.x – Creating an ODBC data source name (DSN)

Connecting-To: Creating an ODBC DSN for Linux

Note

odbc.ini file structure

Caution

Configuring the odbc.ini file:

Using an odbcinst.ini file

Configuring additional ODBC settings

Connecting-To: Creating an ODBC DSN for windows clients

Connecting-To: Creating an ODBC DSN for macOS clients

Setting up a DSN

Note

Connecting-To: ODBC DSN connection properties

Required connection properties

Note

Optional properties

Advanced settings

Identification

OAuth connection properties

Caution

Deprecated

Deprecated

Multi factor authentication

Encryption

Note

Third-party compatibility

Kerberos connection properties

See also

Connecting-To: Setting DSN connection properties

Note