17.20 - Keywords for SQLDriverConnect() and SQLBrowseConnect() - ODBC Driver for Teradata

ODBC Driver for Teradata® User Guide

Product
ODBC Driver for Teradata
Release Number
17.20
Published
June 2022
Language
English (United States)
Last Update
2022-06-21
dita:mapPath
uqj1639470627591.ditamap
dita:ditavalPath
nkw1500504256726.ditaval

The keywords listed in the following table can be specified in the connect string input of SQLDriverConnect() or in the connect string input of SQLBrowseConnect() for ODBC Driver for Teradata.

Keywords are not case-sensitive. Optional keywords are designated by an *.

An attribute-key value enclosed in { } cannot have the } character.
Keyword Explanation
*ACCOUNTSTR=<Account Name>

Or

*ACCOUNT=<Account Name>

See the “AccountStr=<account>” option in the the table titled Options Configurable in the odbc.ini File in Teradata DSN Options.
*CHARACTERSET=<Character set>

Or

*CHARSET=<Character set>

Default = ASCII

See the “CharacterSet=<charset name>” option in Teradata DSN Options.

DATASOURCEDNSENTRIES=<value>

Or

DSDNSENTRIES=<value>

Default = unassigned

See Data Source DNS Entries in Teradata ODBC Driver Advanced Options.

*DATETIMEFORMAT=[A|I]AA

See the “DateTimeFormat=[A|I]AA option in Teradata DSN Options.

The recommended settings are either the AAA (default), or the IAA (optional) formats. Because the Integer data type has been deprecated for the TIME format, it is not recommended. For information, see "Integer Time" in Deprecated Features for ODBC Driver for Teradata 16.20 and Later Versions. The last character that represents TIMESTAMP is always ANSI.

*DEFAULTDATABASE=<] ]” option in database name>

Or

*DATABASE=<database name>

See the “Database=<database name>” option in Data Source Specification Section.
*DBCNAME=123.45.67.89 See the “DBCName=<IP-addr-or-alias>” option in Data Source Specification Section.

This setting is made in the Teradata Server Info section in the ODBC Driver Setup dialog box. For details, see ODBC Driver Setup Parameters.

Only one name or IP address is valid. When a name is specified, ODBC Driver for Teradata automatically detects associated COP entries. For example, if the name contains a COPx suffix. For more information, see Cop Discovery.

*DISPKANJICONVERRS=[Y | N] This DSN option is ignored. Invalid characters result in substitute characters being used.
*DOMAIN=<Domain Name> (Windows only) When the Domain Name is provided for Third Party Sign-On, you should provide the domain name along with the username and password.

If a domain name is not provided, then the local domain is assumed.

*DONTUSEHELPDATABASE=[Y | N]

Or

*DONTUSEHELPDB=[Y | N]

Default = No

See the “DontUseHelpDatabase=[Yes | No]” option in Teradata DSN Options.

*DRIVER=<ODBC Driver for Teradata> See the “Driver=<driver-path>” option in Data Source Specification Section.
DSN=<DataSourceName> See the “data-source-name=<driver>” option in ODBC Data Sources Section.
*ENABLEEXTENDEDSTMTINFO=[ Y | N ] Default = Y

See the “EnableExtendedStmtInfo=[Yes | No]” option in Teradata DSN Options.

*ENABLEREADAHEAD=[ Y | N ] Default = Y

See the “EnableReadAhead=[Yes | No]” option Teradata DSN Options.

*ENABLEREDRIVE=[Yes|No|Default] Determines whether requests on the session participate in Redrive, or not, or use the database-side default value.

Default value is "Default".

HTTPS_PORT =<port number> HTTPS Port Number

Default = 443

This option specifies the port number used for TLS connection to access the database.

See the “HTTPS_PORT=<integer>” option in Teradata DSN Options

*IGNORESEARCHPATTERN=[Y | N]

Or

*IGNORESEARCHPAT=[Y | N]

Default = No

See the “IgnoreODBCSearchPattern=[Yes | No]” option in Teradata DSN Options.

*LOGINTIMEOUT=<Time out Value> Default = 20

See Teradata DSN Options.

*MAXRESPSIZE=<Resp Buffer size> Default = 65536 (64K)

See Teradata DSN Options.

*MECHANISMKEY=<Value>

Or

*AUTHENTICATIONPARAMETER=<Value>

Value=string

A string of characters opaque to the driver, and regarded as a parameter to the authentication mechanism. Passed to the Teradata authentication software called to set the authentication mechanism.

For instructions on configuring this parameter, see the MechanismKey=<Value> description in Teradata DSN Options.

For more information, see TDGSS Support for UTF16.

You can use a Teradata Wallet reference string as the value for this keyword (or part of the value) by specifying the$tdwallet() token. For example:

AUTHENTICATIONPARAMETER=$tdwallet(WalletRefString);

For more information, see Teradata Wallet.

*MECHANISMNAME=<MechanismName>

Or

*AUTHENTICATION=<MechanismName>

Identifies the authentication mechanism used for connections to the data source.

The default is determined by a configuration option set in an XML file by the TeraGSS program, tdgssconfigure.

For instructions on configuring the authentication mechanism, see the MechanismName=<MechanismName> description in Teradata DSN Options.

For more information, see Authentication Mechanisms.

*MSACCESSINTEROPMODE=[Y | N]

Or

*USEDATEDATAFORTIMESTAMPPARAMS=[Y | N]

Default = No

(Windows Only)

*NOSCAN=[Y | N] Default = No

See the “NoScan=[Yes | No]” option in Teradata DSN Options.

*NTERRLOG=[Y | N] Default = No

(Windows only) When Yes is selected, this option enables the user to log errors returned by ODBC Driver for Teradata in the Event Log.

When No is selected, no errors are logged in the Event Log.

*PASSWORD=<value>

Or

*PWD=<value>

See the “Password=<password>” option in Data Source Specification Section.

You can use a Teradata Wallet reference string as the value for this keyword (or part of the value) by specifying the $tdwallet() token. For example:

PWD=$tdwallet(WalletRefString);

For more information, see Teradata Wallet.

*PRINTOPTION= [P | N] Default = No

See the “PrintOption=[O | P]” option in Teradata DSN Options.

*PWD2=<value> A secondary password used with the default username when logging onto a Teradata server. (See the option in Data Source Specification Section.)

When SQLDriverConnect or SQLBrowseConnect is called and PWD has expired, connect keywords recognized for ConnectStringInput are extended by PWD2=new_password_value.

When an attempt is made to establish a database session, a logon request is issued using PWD. If a restricted logon is returned because the password has expired, a MODIFY is issued using PWD2. The ConnectStringOutput is then updated to reflect the password used to establish the session. Applications are responsible for checking the password used for the login and using it in their own login processes.
  • An expired password error will return when calling SQLConnect, because PWD2 does not support the ConnectStringInput string.
  • PWD2 might not work in applications that normally cache connection information.
  • PWD2 does not work for passwords stored in the Registry.
For PWD2 to work, an application must be aware of how password expiration is handled by the database session connection process and must use that knowledge when sending connection requests. Off-the-shelf ODBC applications or third-party tools cannot use PWD2 because their connection code does not know how to use the secondary password. PWD2 only works in applications that have been customized to use it.
*RECONNECTCOUNT=<value> Default is 20

The maximum number of times the driver should attempt to reconnect to the database (0-99).

*RECONNECTINTERVAL=<value> Default is 30

The number of seconds (1-300) between reconnect attempts.

*RETRYONEINTR=[Y | N] Default = Y

This option allows the user to control whether ODBC Driver for Teradata should retry the socket system calls on an EINTR or return an SQL_ERROR.

The socket system calls affected are:
  • connect()
  • select()
  • recv()
  • send()

See the “RETRYONEINTR=[Y | N]” option in Teradata DSN Options.

*RETURNGENERATEDKEYS=<value> Default = N

See the RETURNGENERATEDKEYS=<value> description in Teradata DSN Options.

*SESSIONMODE=[ANSI|Teradata] The default value is determined by the database based on the option used in the CREATE or MODIFY USER statement.

See the “SessionMode=[TeradataANSI]” option in Teradata DSN Options. For Windows configuration, see the Session Mode menu description in Teradata ODBC Driver Options.

*SESSIONS=<value> There is no default

See the "Sessions=<value>" option in Teradata DSN Options.

*SPLOPTION=[Y | N] Default = No

See the “SplOption=[Y | N]” option in Teradata DSN Options.

SSLCA=<path> SSL CA Path

This option specifies the full path of the directory containing the root certificates for trusted CAs. If SSL Mode is not set to Verify-CA or Verify-Full, SSL CA File Name or SSL CA Path will be ignored.

SSLCAPath=<path> SSL CA File Name

The default is the default of the operating environment.

This option specifies the full path and name of a .pem file containing one or more certificates for trusted Root and Intermediate CAs. If SSL Mode is not set to Verify-CA or Verify-Full, SSL CA File Name or SSL CA Path will be ignored.

To use this option, use “c_rehash” tool to create symbolic links for certificate files that are used by OpenSSL.

For more details, refer to OpenSSL documentation: https://www.openssl.org/docs/man1.1.1/man1/c_rehash.html

SSLMode=[Allow|Disable|Prefer|Require|Verify-CA|Verify-Full] Default="Prefer"

This option specifies which TLS mode ODBC Driver for Teradata operates in.

Valid values:

Prefer

Driver prioritizes connecting with HTTPS port.

If that connection fails, then the driver falls back to connect with TDMST port.

When Teradata Gateway TLS settings set to “enable” with TLS certificate being correctly setup, ODBC driver for Teradata only attempts connection using HTTPS port. If the connection fails, then a corresponding error message is returned.

For more details, refer to Deterministic Behavior of Prefer/Allow SSLMode.

Allow

Driver prioritizes connecting with TDMST port.

If that connection fails, then the driver falls back to connect with HTTPS port.

When Teradata Gateway TLS setting is set to “enable” with TLS certificate being correctly setup, ODBC driver for Teradata only attempts connection using TDMST port. If the connection fails, then a corresponding error message is returned.

For more details, refer to Deterministic Behavior of Prefer/Allow SSLMode.

Disable

Driver only connects on TDMST port.

Require

Driver only connects on the HTTPS port.

Verify-CA

Same as “Require” mode with additional verification of the server Certificate Authority (CA) certificate against the configured CA certificates.

Verify-Full

Same as “Verify-CA” mode with additional host name identity validation.

SSLProtocol=[TLSv1.2] SSL Protocol

Currently only TLSv1.2 is supported.

*TABLEQUALIFIER=[Y | N] Default = No

When this option is Yes, NULL values are passed for the Table Qualifier parameters in the Catalog API functions.

When this option is No, NULL values are not passed for the Table Qualifier parameters in the Catalog API functions.

*TCPNODELAY=[Y | N] Default = Yes

See the “TCPNoDelay=[Yes | No]” option in Teradata DSN Options.

*TDMSTPORTNUMBER=<port number> Default = 1025

See the “TDMSTPortNumber=<integer>” option in Teradata DSN Options.

*TYPE=[Default|FastExport] Default = Default

See the "Type=[Default|FastExport]" option in Teradata DSN Options.

*USECOLUMNNAMES=[Y | N]

Or

*DONTUSETITLES=[Y | N]

Default = Yes

See the “DontUseTitles=[Yes | No]” option in Teradata DSN Options.

USEDATAENCRYPTION=[Y |N]

Or

DATAENCRYPTION=[Y |N]

Default = No

When DATAENCRYPTION is Yes, ODBC Driver for Teradata encrypts data, and thus the Teradata gateway and ODBC Driver for Teradata communicate with each other in an encrypted manner.

When DATAENCRYPTION is No, ODBC Driver for Teradata does not encrypt data, except for logon information.

USEREGIONALSETTINGS=[Y | N]

Or

REGIONALDECIMALSYMBOL=[Y | N]

Default = Yes

[Windows and Apple macOS] See the “Use Regional Settings for Decimal Symbol” option in Teradata ODBC Driver Options.

*USERNAME=<value>

Or

*UID=<value>

See the “Username=<name>” option in Data Source Specification Section.
*USEXVIEWS=[Y | N] Default = No

See the “UseXViews=[Yes|No]” option in Teradata DSN Options.