Menu
Simba Technologies
Simba Technologies

SimbaEngine X SDK 10.1.15
SimbaClient/Server Developer Guide

SimbaClient for ODBC Configuration Properties

All configuration properties are type String. See SimbaClient for ODBC on Windows for the location of these properties in the Windows registry, or SimbaClient for ODBC on Linux, Unix, and macOS for the location of these properties in the configuration files.

The following table summarizes the configuration properties. Detailed descriptions are provided in subsequent tables.

Property Type Description

ConnectionDialog

DSN, Driver, or SimbaSettingReader

The location of the connection dialog file.

Description

DSN

A brief, human-readable description of the DSN.

Driver

DSN or
Driver

In the driver configuration location, Driver should contain the path to the driver binary. In the DSN configuration location, Driver could contain the path to the driver binary, or it could contain the driver entry in the registry.

Locale

DSN

The connection locale.

ServerList

DSN

A list of all servers (IP address and port number) to connect to.

TransactionsSupported SimbaSetting
Reader
Overrides the value of DSI_DRIVER_TRANSACTION_CAPABILITY_KNOWN property to specify whether or not the server is connecting to a data store that supports transactions.
Timeout properties

IdleTimeout

DSN

The time to wait for a response from the server.

LoginTimeout

DSN

The timeout, in seconds, to wait for a response from the server when attempting to log in.

QueryTimeout

DSN

Sets the value of SQL_ATTR_QUERY_TIMEOUT, which is passed to the server.

Logging properties

LogLevel

SimbaSetting
Reader

Controls the granularity of the messages and events that are logged.

LogPath

SimbaSetting
Reader

Specifies the directory where the log files are created.

LogFileSize

SimbaSetting
Reader

The size of each log file. When the maximum size of the file is reached, a new file is created.

LogFileCount

SimbaSetting
Reader

The number of log files to create.

Integrated security (single sign-on) properties

ServicePrincipalName

DSN

The service principal name for the server with integrated security.

UseIntegratedSecurity

DSN

Indicates whether integrated security (Kerberos) should be used.

Secure socket layer (SSL) properties

AllowExpiredCert

DSN

Specifies whether the client will accept an expired SSL certificate from the server.

AllowHostMismatch

DSN

Specifies whether the client will accept a hostname from the server that differs from the one in the server's SSL certificate.

AllowSelfSignedCert

DSN

Specifies whether the client accepts SSL certificates from the server which are self-signed.

SSLCACertfile

DSN

Location of the SSL certificate authority certification file.

UseSsl

DSN

Enable SSL encryption for the connection between SimbaClient and SimbaServer.

General configuration properties

ConnectionDialog

The location of the connection dialog file.

Required

Required only if the connection dialog is required.

Allowed values

Allowed characters for file path names. May differ by platform.

Default value

[INSTALL_DIR]\ConnectionDialog.dll

Example

ConnectionDialog=C:\Simba Technologies\InstallDir\ConnectionDialog.dll

Comment

You can use the ConnectionDialog.dll for a staged login when you need to have the client and server have a short conversation before connecting. The Client looks in ODBC.INI first, then ODBCINST.INI, then under Simba Settings.

Description

A brief, human-readable description of the DSN.

Required

No

Allowed
values

Any alphanumeric characters.

Default value

Sample SimbaODBCClient DSN

Example

Description=Time system database – read-only.

Comment

This describes the DSN to users who are deciding which DSN to use. Applications will usually display the description of the DSN to help the user choose the correct one.

Driver

The location of the driver file.

Required

No (but recommended)

Allowed
values

Allowed characters for file path names. May differ by platform.

Default value

None

Example

Driver= C:\Simba Technologies\InstallDir\SimbaClient.dll

Comment

The Driver keyword points to the location of the ODBC driver itself. This is not always required as the location can be inferred, but we recommend you include it.

Locale

The connection locale.

Required

No

Allowed Values

Values are composed of a 2-letter language code (in lower case), and an optional 2-letter country code (in upper case). If the country code is specified, it must be separated from the language code by a hyphen (-).

The language codes conform to the ISO639-2 specification: http://www.loc.gov/standards/iso639-2/php/code_list.php

The country codes conform to the ISO3166-1 specification: http://www.iso.org/iso/country_codes/iso-3166-1_decoding_table.htm

Default value

0

Example

Locale=fr-CA

Comment

If this value is set, it overrides the driver-wide locale. For example, the driver-wide locale could be en-US. If the client would prefer fr-CA, it can set the connection locale to fr-CA.

ServerList

A listing of all servers to connect to, including IP address and port number.

Required

Yes

Range

  • IP addresses: Any valid IP address.
  • Ports: 0 - 65535

Default value

127.0.0.1 1543 (loopback with default port)

Example

ServerList=127.0.0.1 1543,192.168.0.1 1543

Comment

SimbaClient must be able to find SimbaServer on the network. This property enables server discovery. SimbaClient will try to make a network connection to the servers in the order specified until a connection is made.

The format is: <ip> <port>,<ip> <port>,…

TransactionsSupported

Overrides the value of DSI_DRIVER_TRANSACTION_CAPABILITY_KNOWN to specify whether or not the server supports transactions.

Required

No

Allowed values
  • 0 or FALSE: the server does not support transactions
  • 1 or TRUE: the server supports transactions

Default value

0 or FALSE: the server does not support transactions

Example

TransactionsSupported=TRUE

Comment

This property overrides the server property DSI_DRIVER_TRANSACTION_CAPABILITY_KNOWN, which specifies whether the DSII's IConnection implementation knows whether or not transactions are supported, before the connection is established.

For more information on DSI_DRIVER_TRANSACTION_CAPABILITY_KNOWN, see DSIDriverProperties.h

Timeout properties

The value of LoginTimeout is used by the ODBC client. The values of IdleTimeout and QueryTimeout are passed to the server, and you must implement any desired timeout behavior in your server's DSII. For more information on timeout behavior, see How does timeout work?

IdleTimeout

Sets the value of SQL_ATTR_CONNECTION_TIMEOUT, which is passed to the server.

Required

No

Range

0 – UINT_MAX seconds

Default value

0 (no timeout)

Example

IdleTimeout=60000

Comment

You must implement any required idle timeout in your server DSII. Typically, this covers any situation that requires a timeout and is not associated with query execution or login. For more information on SQL_ATTR_CONNECTION_TIMEOUT, see https://msdn.microsoft.com/en-us/library/ms713605(v=vs.85).aspx.

Note:

The ODBC client IdleTimeout property and the server IdleTimeout property have the same name, but are different properties.

LoginTimeout

The time, in seconds, to wait for a response from the server after a login request is made by the client.

Required

No

Range

0 – UINT_MAX seconds

Default value

60

Example

LoginTimeout=10

Comment

A value of 0 means no timeout.

The value of this property is used to set the value of SQL_ATTR_LOGIN_TIMEOUT.

Note:

  • A log in timeout may occur earlier than the time specified by this value. For example, if a DNS lookup failure occurs, the log in attempt times out immediately.
  • If additional servers are specified in ServerList, the client attempts to log in to the other servers before timing out.

QueryTimeout

Sets the value of SQL_ATTR_QUERY_TIMEOUT, which is passed to the server.

Required

No

Range

0 – UINT_MAX seconds

Default value

60

Example

QueryTimeout=10

Comment

You must implement any required query timeout in your server DSII. Typically, this means throwing an error if statements such as PREPARE, EXECUTE, or EXECUTEDIRECT take longer than specified by SQL_ATTR_QUERY_TIMEOUT.

Logging properties

For more information on logging, see Setting Properties to Control Logging.

LogLevel

Controls the granularity of the messages and events that are logged.

 

Required

No

Allowed
values

See Comment.

Default value

LOG_OFF

Example

LogLevel=LOG_ERROR

Comment

With this keyword, you can control the amount of log output by controlling the kinds of events that are logged.

Possible values (case sensitive):

  • 0 or LOG_OFF: no logging occurs
  • 1 or LOG_FATAL: only log fatal errors
  • 2 or LOG_ERROR: log all errors
  • 3 or LOG_WARNING: log all errors and warnings
  • 4 or LOG_INFO: log all errors, warnings, and informational messages
  • 5 or LOG_DEBUG: log method entry and exit points and parameter values for debugging
  • 6 or LOG_TRACE: log all method entry points

LogPath

Specifies where the log file is created.

Required

No

Allowed values

Valid directory path, or unspecified.

Default value

Unspecified

Example

LogPath=C:\Simba Technologies\Temp

Comment

If this value is not set, the log files are written to the current working directory of the SimbaClient.

LogFileSize

Specifies the size, in bytes, of each log file.

Required

No

Allowed
values

The SimbaEngine X SDK will accept any positive integer. The maximum size of a file depends on the host machine's specifications.

Default value

20971520 bytes

Example

LogFileSize="30000000"

Comment

When the maximum size of the log file is reached, another log file will be created.

LogFileCount

Specifies the number of log files to create.

Required

No

Allowed
values

The SimbaEngine X SDK will accept any positive integer. The maximum number of files depends on the host machine's specifications.

Default value

50

Example

LogFileCount=100

Comment

When the maximum number of log files has been created, the oldest file will be deleted and a new one created.

Integrated security (single sign-on) properties

For more information on configuring Kerberos, see Overview.

ServicePrincipalName

The service principal name for the server with integrated security.

Required

Yes if UseIntegratedSecurity is True.

Allowed
values

Any valid service principal name.

Default
value

no default

Example

ServicePrincipalName=<SPN of the server>

UseIntegratedSecurity

Indicates whether integrated security (single sign-on), should be used when the client establishes a connection to the server. Kerberos authentication is used for integrated security.

Note:

You must configure UseIntegratedSecurity on both the SimbaServer and the SimbaClient in order to use integrated security.

Required

No

Allowed values

Disabled, Enabled, Required

Default value

Disabled

Example

UseIntegratedSecurity=Required

Comment

If enabled on the client and the server, integrated security will be used during connection.

For a summary of the connection types that will be established based on the different client and server settings, see Configuration Properties for Integrated Security.

Secure socket layer (SSL) properties

For more information, see Overview.

AllowExpiredCert

Specifies whether the client will accept an expired SSL certificate from the server.

Required

No

Range

Yes or No (also accepts 1 or 0)

Default value

No

Example

AllowExpiredCert=Yes

Comment

When enabled, the client will accept an expired SSL certificate from the server.

AllowHostMismatch

Specifies whether the client will accept a hostname from the server that differs from the one in the server's SSL certificate.

Required

No

Allowed values

Yes or No (also accepts 1 or 0)

Default value

No

Example

AllowHostMismatch=Yes

Comment

When enabled, the client will accept a different hostname from the server than the one specified in the server’s SSL certificate.

AllowSelfSignedCert

Specifies whether the client accepts SSL certificates from the server which are self-signed.

Required

No

Allowed values

Yes or No (also accepts 1 or 0)

Default value

No

Example

AllowSelfSignedCert=Yes

Comment

When enabled, the client accepts SSL certificates from the server which are self-signed (as opposed to being signed by a certificate authority).

SSLCACertfile

Location of the SSL certificate authority certification file for SimbaClient to use when encrypting SSL communication with SimbaServer.

Required

Yes if UseSsl is enabled.

Allowed
values

Disabled, Enabled, Required

Default
value

Disabled

Example

SSLCACertFile=C:\Simba Technologies\SimbaEngineSDK\10.1
\Documentation\SSLCertificates\
SampleCACertificate.pem

UseSsl

This setting allows the connection between the SimbaClients and SimbaServer to use Secure Sockets Layer (SSL) encryption.

Note:

You must configure SSL on both the SimbaServer and the SimbaClient in order to establish a secure connection. See Configuration Properties for SSL.

Required

Yes, if UseSsl is enabled on the Server.

Allowed values

Disabled, Enabled, Required

Default value

Disabled

Example

UseSsl=Enabled