Programming Guidelines

DownloadDownload ODBC Driver

The programming features of the Microsoft ODBC Driver 13 and 13.1 for SQL Server on macOS and Linux are based on ODBC in SQL Server Native Client (SQL Server Native Client (ODBC)). SQL Server Native Client is based on ODBC in Windows Data Access Components (ODBC Programmer's Reference).

An ODBC application can use Multiple Active Result Sets (MARS) and other SQL Server specific features by including /usr/local/include/msodbcsql.h after including the unixODBC headers (sql.h, sqlext.h, sqltypes.h, and sqlucode.h). Then use the same symbolic names for SQL Server-specific items that you would in your Windows ODBC applications.

Available Features

The following sections from the SQL Server Native Client documentation for ODBC (SQL Server Native Client (ODBC)) are valid when using the ODBC driver on macOS and Linux:

Unsupported Features

The following features have not been verified to work correctly in this release of the ODBC driver on macOS and Linux:

The following features are not available in this release of the ODBC driver on macOS and Linux:

  • Distributed Transactions (SQL_ATTR_ENLIST_IN_DTC attribute is not supported)
  • Database Mirroring
  • Profiling ODBC driver performance, discussed in SQLSetConnectAttr, and the following performance-related connection attributes:
  • SQLBrowseConnect
  • C interval types such as SQL_C_INTERVAL_YEAR_TO_MONTH (documented in Data Type Identifiers and Descriptors)
  • The SQL_CUR_USE_ODBC value of the SQL_ATTR_ODBC_CURSORS attribute of the SQLSetConnectAttr function.

Character Set Support

SQLCHAR data must be UTF-8. SQLWCHAR data must be UTF-16LE (Little Endian).

If SQLDescribeParameter does not specify a SQL type on the server, the driver uses the SQL type specified in the ParameterType parameter of SQLBindParameter. If a narrow character SQL type, such as SQL_VARCHAR, is specified in SQLBindParameter, the driver converts the supplied UTF-8 data to the default SQL Server code page. (The default SQL Server code page is typically 1252.) However, data loss is possible. If code page 1252 cannot represent a character, the driver converts the character to a question mark ('?'). To avoid this data loss, specify a Unicode SQL character type, such as SQL_NVARCHAR, in SQLBindParameter. In this case, the driver converts the supplied Unicode data in UTF-8 encoding to UTF-16 without loss of data.

There is a text-encoding conversion difference between Windows and several versions of the iconv library on Linux and macOS. Text data that is encoded in codepage 1255 (Hebrew) has one code point (0xCA) that behaves differently upon conversion. Converting this character to Unicode on Windows produces a UTF-16 code point of 0x05BA. Converting to Unicode on macOS and Linux with libiconv versions earlier than 1.15 produces a UTF-16 code point of 0x00CA.

When UTF-8 multibyte characters or UTF-16 surrogates are split across SQLPutData buffers, it results in data corruption. Use buffers for streaming SQLPutData that do not end in partial character encodings.

Additional Notes

  1. You can make a dedicated administrator connection (DAC) using SQL Server authentication and host,port. A member of the Sysadmin role first needs to discover the DAC port. See Diagnostic Connection for Database Administrators to discover how. For example, if the DAC port were 33000, you could connect to it with sqlcmd as follows:

    sqlcmd –U <user> -P <pwd> -S <host>,33000

    DAC connections must use SQL Server Authentication.

  2. The UnixODBC driver manager returns "invalid attribute/option identifier" for all statement attributes when they are passed through SQLSetConnectAttr. On Windows, when SQLSetConnectAttr receives a statement attribute value, it causes the driver to set that value on all active statements which are children of the connection handle.

See Also

Frequently Asked Questions

Known Issues in this Version of the Driver

Release Notes