Omnis Technical Note TNSQ0038August 2019
Updated October 2025
Using the Microsoft ODBC Driver for SQL Server on Linux and macOS
for Omnis Studio 10.0.1 or above
by Gary Ashford, Omnis Engineering
Introduction
This technote relates to the "Microsoft ODBC Driver 18 for SQL Server" available for Linux and macOS, released in 2025.
Use of this driver requires the Unix ODBC Driver Manager (libodbc.so / libodbc.dylib).
While this library may already be present on Linux operating systems, for macOS it can be extracted and installed from the download package referred to below.
Notes for macOS
Please refer to the download and installation instructions on the Microsoft ODBC Driver Installation page.
To install using Homebrew, enter the following commands from the terminal window:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18
The Homebrew script installs all files needed to make a connection using the ODBC driver, including:
/usr/local/Cellar/unixodbc/2.3.14/lib/libodbc.2.dylib | Unix ODBC Driver Manager |
/usr/local/Cellar/unixodbc/2.3.14/lib/libodbcinst.2.dylib | Unix ODBC driver installation libary |
/usr/local/Cellar/msodbcsql18/18.5.1.1/lib/msodbcsql18.dylib | Microsoft SQL Server 18 ODBC Driver |
/usr/local/Cellar/msodbcsql18/18.5.1.1/share/msodbcsql18/resources/en_US/msodbcsqlr18.rll | ODBC Driver resource file |
For a full list of files installed by a package, use the brew list command, for example:
brew list msodbcsql18 unixodbc
Configuration files
unixODBC uses two configuration files; odbcinst.ini- used to register ODBC Drivers, and odbc.ini- used to register ODBC Datasource Names (DSNs).
There can also be two odbc.ini files; one for System-wide DSNs and one for user DSNs.
By default, unixODBC looks for system DSNs in /etc/odbc.ini or /usr/local/etc/odbc.ini
And it looks for user DSNs in ~/.odbc.ini (a hidden file in the user's home folder).
You can see the default locations for these files
by executing the command:
odbcinst -j
unixODBC 2.3.12
DRIVERS............: /opt/homebrew/etc/odbcinst.ini
SYSTEM DATA SOURCES: /opt/homebrew/etc/odbc.ini
FILE DATA SOURCES..: /opt/homebrew/etc/ODBCDataSources
USER DATA SOURCES..: /Users/myuser/.odbc.ini
You can also override the default locations using environment variables, adding these to the Omnis Studio config.json file; inside the "odbcdam.ini" section
ODBCINI | Specifies the full path to the User DSN configuration file. |
ODBCSYSINI | Specifies the folder name that contians the System configuration files. |
ODBCINSTINI | Specifies the name of the System-wide driver definition file. The driver manager appends this to ODBCSYSINI to derive the actual path. |
For example:
"macOS": {
...
"odbcdam.ini": "ODBCINI=/Users/myuser/odbc.ini,ODBCSYSINI=/usr/local/etc,ODBCINSTINI=odbcinst.ini"
...
},...
Registering the ODBC Driver
If you install the Microsoft odbc Driver 18 for SQL Server using brew (as above) then the odbcinst.ini file is configured automatically, for example:
[ODBC]
Trace=NO
TraceFile=/dev/stdout
[ODBC Driver 18 for SQL Server]
Description=Microsoft ODBC Driver 18 for SQL Server
Driver=/opt/homebrew/lib/libmsodbcsql.18.lib
UsageCount=1

If the DSNs specify drivers using an explicit path, then odbcinst.ini can be ignored.
Setting up an ODBC Datasource
To register the ODBC datasource manually, use a text editor and edit the odbc.ini file directly. The DSN is registered by appending to the relevant odbc.ini file (~/.odbc.ini in this example):
[ODBC Data Sources]
ntms2019 = ODBC Driver 18 for SQL Server
[ntms2019]
Driver = ODBC Driver 18 for SQL Server
Server = 192.168.1.100
TrustServerCertificate = Yes
In the above example Driver should be either a repeat of the Driver name registered with odbcinst.ini, or the full path to the ODBC driver.
Server should be either the IP-address of the SQL Server database, or its "pingable" network domain name.
TrustServerCertificate is required in order for this version of the ODBC driver to make a connection.
Failure to include this attribute may be one cause of a "Connection not open" error otherwise.
The DSN accepts several other attributes, for example: UID, PWD & Database. However, the above represents the minimum required in order to make a connection.
Omnis Studio - Locating the Driver Manager
macOS Gatekeeper prevents codesigned applications from loading non-signed extensions- such as libodbc.dylib.
A reliable way to provision the UnixODBC Driver manager is therefore to copy/create a symbolic link to the ODBC library from the Omnis.app/Contents/Frameworks folder.
For example:
cd "Omnis Studio 11.2 40173.app/Contents/Frameworks"
ln -s /opt/homebrew/Cellar/unixodbc/2.3.12/lib/libodbc.2.dylib libodbc.dylib
Connecting from Omnis Studio 10.0.x:
Before starting Omnis, navigate to Omnis Studio 10.0.1.app->Contents/MacOS/xcomp/ini and edit your odbcdam.ini file.
If you require only User-DSNs, the ODBCINI entry should be set to your local user's odbc.ini file, e.g.
If you want to differentiate between User and System DSNs, you can additionally create an ODBCSYSINI entry, e.g.
ODBCSYSINI=/Library/ODBC
One of the entries should point to the odbc.ini file you edited in the previous step.
Connecting from Omnis Studio 10.1 and later:
Please note that in Studio 10.1 and later, separate ".ini" files have been replaced by entries in the "macOS" section
of the studio/config.json file.
Locate this section in the file, then edit the "odbcdam.ini" key with the required information, e.g.
"odbcdam.ini": "ODBCINI=/Users/myUser/Library/ODBC/odbc.ini, ODBCSYSINI=/Library/ODBC"
Tip: Avoid using ~ when specifying the path to your odbc.ini file; use an explicit path.
Using the Omnis Studio ODBC DAM, it is necessary to change the session object $mode property to kODBCModeUnix.
This should be done before logging on and tells the ODBC DAM to unload the default driver manager and load the Unix ODBC Driver manager (libodbc.dylib on macOS).
Using the SQL Browser session editor, this property can be set via the Advanced tab as shown:

The logon hostname should match the name of the ODBC DSN created above. Add your username, password and optional database details, and save the session template. You should then be able to open the ODBC session and connect to SQL Server:

Example (using notation):
Do sessionObj.$mode.$assign(kODBCModeUnix)
Do sessionObj.$database.$assign('test')
Do sessionObj.$logon('ntms2017','henry','password','session1') Returns #F
Example (using a connection string):
Note: using a self-contained connection string negates the need for odbcinst.ini and odbc.ini files.
Do sessionObj.$mode.$assign(kODBCModeUnix)
Do sessionObj.$uselogonprompt.$assign(kODBCPromptDsnLess)
Do sessionObj.$logon('Driver={/opt/homebrew/lib/msodbcsql18.dylib};Server=192.168.1.100;Database=master;UID=henry;PWD=password;TrustServerCertificate=Yes','','','session1') Returns #F
Troubleshooting
If you receive a logon error similar to "Driver manager could not be loaded", this indicates a problem locating or loading the ODBC driver manager library.
Make sure that you either copied the libodbc.2.dylib into Omnis' Frameworks folder and make sure that the symbolic link libodbc.dylib exists and points to libodbc.2.dylib.
Remember to set the ODBC DAM's $mode session property to kOdbcModeUnix in order to use the Microsoft ODBC Driver.
Error message: [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified.
Locate your Omnis writable files folder (e.g. /Users/myUser/Library/Application Support/Omnis/Omnis Studio 30204/)
and edit the Studio/config.json file. Under the "macos" section, make sure that the ODBCINI key value matches the location of your odbc.ini file.
If you defined a User DSN as opposed to the System DSN, you may need to change the location, or add an ODBCSYSINI entry to differentiate User and System DSNs, for example:
"odbcdam.ini": "ODBCINI=/Users/myUser/Library/ODBC/odbc.ini", "ODBCSYSINI": "/Library/ODBC/odbc.ini", …
Error message: [unixODBC][Driver Manager] Connection not open.
This error means that the driver manager tried to perform an action using the driver, but the connection was not open.
In other words; the ODBC DSN was not found, the DSN was found but the specified driver could not be loaded, or a connection attempt was made but failed.
One cause of this error using "ODBC Driver 18 for SQL Server" is omission of the "TrustServerCertificate" attribute or failure otherwise to provide valid SSL credentials.
In this situation, you can test an ODBC connection independently of Omnis Studio using the isql utility. For example:
isql -v ntms2019 henry password
References
Installing the Microsoft ODBC Driver for SQL Server on Linux and macOS
The unixODBC.org website