ODBC Connection Parameters

An OAuth access token (used instead of username and password). For example, you could replace UID=myUsername;PWD=myPassword; in the connection string with:

 "ACCESSTOKEN=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3M;"

The access token string in this example has been truncated for brevity. If a AccessToken is specified, then no username or password are used as these are mutually exclusive.

Defines the security method to be used. Valid values are:

• 0 = Password — authenticate with standard username and password.

• 1 = Kerberos — authenticate with Kerberos. This option also requires settings for Security Level and Service Principal Name.

  • Connection Security Level — Select Kerberos, Kerberos with Packet Integrity, or Kerberos with Encryption, as appropriate (see the Client/Server section of About Kerberos and the Access Modes).

  • Service Principal Name — Specify the name of the server to be used as a Kerberos principal.

• 2 = Password with SSL/TLS — authenticate using an SSL/TLS protected connection. Security Level must be set to 10 if this option is selected.

For detailed information on these options, see Authentication Guide.

See Creating a DSN with the ODBC Data Source AdministratorOpens in a new tab (Windows) and Structure of the ODBC Initialization File (UNIX) for detailed information and examples.

Provides user-defined information about the DSN or initialization file.

If set to 1, causes the ODBC client driver to ignore the value of the Query Timeout setting. This is useful in cases where an ODBC application has a hard-coded Query Timeout value that is too short for your purposes.

This setting is implemented in different ways depending on your operating system:

• In Windows, specifies the name of the InterSystems ODBC driver (where the name is the key to a Windows registry entry). For example: "Driver={InterSystems ODBC}" or "Driver={InterSystems IRIS ODBC35}".

• In UNIX, specifies the full path to the InterSystems ODBC client driver file. For example: "Driver = /usr/irissys/bin/libirisodbc.so"

A pre-configured Data Source Name (DSN) in the ODBC Data Source Administrator.

The path to a file containing the same information as a DSN. For example "FILEDSN = C:\\ODBC_Samples.dsn". See Structure of the ODBC Initialization File and Using File DSNs and DSN-less Connections for more information and examples.

The hostname or IP address of the InterSystems IRIS server (for example, localhost or 127.0.0.1).

When set to LOG=1, the InterSystems ODBC client driver creates a log file (default name IRISODBC.log in a specific system directory) that records its activities.

This log is for troubleshooting; you should not turn logging on during normal operation as it will dramatically slow down ODBC performance. See ODBC Logging in Windows for more information.

Specifies the location of a log file. For example, "LOGFILE=d:/work/filelog.log". If a log file has already been specified, this will close the old file and redirect logging to the new one.

The InterSystems IRIS Namespace to connect to (for example, USER or SAMPLES).

The Superserver port for the InterSystems IRIS instance. The default is 1972 (see “DefaultPort” in the Configuration Parameter File Reference.

Specifies the protocol for connecting to the DSN. For InterSystems, this is always TCP.

Specifies the password for the account specified by the UID parameter. For default username _SYSTEM, the password is SYS. Unlike the UID, the password is case-sensitive.

Specifies the number of seconds a client should wait for a specific operation to finish. If an operation does not finish within the specified time, it is automatically cancelled. If you are using an ODBC application that has a hard-coded timeout value, Query Timeout can be disabled by setting Disable Query Timeout.

Specifies the type of connection when you use Kerberos for authentication. The allowed values are as follows:

• 1 = Kerberos

• 2 = Kerberos with packet integrity

• 3 = Kerberos with encryption

• 10 = This parameter must be set to 10 if Authentication Method is 2.

For more information on Kerberos, see Kerberos Authentication.

Specifies the name of the server to be used as a Kerberos principal when using Kerberos for authentication. This should be the name of the service principal that represents InterSystems. For example, "Service Principal Name = iris/localhost.domain.com"

Defines the SQL dialect used when preparing and executing dynamic SQL statements. It allows InterSystems IRIS to process SQL source code intended for other database systems by overriding its default SQL behavior.

Valid values are IRIS, MSSQLSERVER, MSSQL, and SYBASE. The default is IRIS. Support for MSSQLSERVER and SYBASE dialects is limited to a subset of the TSQL grammar supported by the InterSystems IRIS TSQL language mode.

This setting is crucial for compatibility when migrating applications from other databases or when using the SQL Gateway to connect to external data sources that use different SQL dialects.

Can be set:

• within the DSN configuration using the Windows ODBC Data Source AdministratorOpens in a new tab tool.

• programmatically in ObjectScript using the %SYSTEM.TSQL.SetDialect() method or by setting the %Dialect property of a %SQL.Statement instance.

• via the InterSystems Management PortalOpens in a new tab in the TSQL Compatibility settings. 

When set to 1, enables the InterSystems ODBC client driver’s static cursor support. If 0, then the cursor support provided by the ODBC Cursor Library will be used. In general, this flag should be off (set to 0) unless you have a specific reason for not using the ODBC Cursor Library.

Sets the stream prefetch size. All streams smaller than or equal to the prefetch size will be fetched in entirety as part of the original result set, thus eliminating the need for additional server round trips. Any streams larger than prefetch size will not be prefetched. Stream prefetch is off by default. If it is on, setting the size to 0 will turn it off again.

Stream prefetching is only advantageous with short streams. Values up to 100k are accepted. Smaller values such as 10k or 30k are advised. Values outside of the permitted range will not be accepted and the stream prefetch size will remain whatever it was before.

Stream prefetch may only be used with non-lob data retrieval methods (getAsciiStream, getBinaryStream and getCharacterStream). An attempt to access prefetched data with lob methods (getBlob and getClob) will result in an exception.

Specifies whether the driver manager performs logging ("Trace = on") or not ("Trace = off") By default, logging is off (see “ODBC Logging on UNIX®” for more information).

If logging is enabled by the Trace option, this specifies the location of the driver manager log file. For example

"TraceFile = iodbctrace.log"

Specifies the username for logging in to the DSN. The InterSystems default value is _SYSTEM (not case-sensitive).

If set to 1, this option turns on reporting of a Unicode SQL type (SQL_WVARCHAR (-9) SQLType) for string data.

This functionality is only relevant when working with a multibyte character set. It allows some Microsoft applications to allocate the properly sized buffers to hold multibyte data. If an application encounters a “SQL data type out of range” error from the Microsoft Driver Manager using SQLBindParameter, it can be caused by having selected this option.