s--- title: "Programming Guidelines | Microsoft Docs" ms.custom: "" ms.date: "01/19/2017" ms.prod: "sql-non-specified" ms.reviewer: "" ms.suite: "" ms.technology:

  • "drivers" ms.tgt_pltfrm: "" ms.topic: "article" ms.assetid: 0cc8686c-e27b-4963-b674-dc420fcbd3d2 caps.latest.revision: 39 author: "MightyPen" ms.author: "genemi"

manager: "jhubbard"

Programming Guidelines

DownloadDownload ODBC Driver

The programming features of the Microsoft ODBC Driver 11 for SQL Server on 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).


These instructions refer to msodbcsql-11.0.2270.0.tar.gz, which is the installation file for Red Hat Linux. If you are installing the CTP for SUSE Linux, the file name is msodbcsql-11.0.2260.0.tar.gz.

An ODBC application can use Multiple Active Result Sets (MARS) and other SQL Server specific features by including /opt/microsoft/msodbcsql/11.0.2270.0/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 in from the SQL Server Native Client documentation for ODBC (SQL Server Native Client (ODBC)) are valid when using the ODBC driver on Linux:

Features That Are Not Available

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

  • bulk copy functions (bcp_batch, for example)
  • distributed transactions (SQL_ATTR_ENLIST_IN_DTC attribute is not supported)
  • database mirroring
  • profiling ODBC driver performance, discussed in SQLSetConnectAttr, the following performance-related connection attributes:
  • SQLBrowseConnect
  • table-valued parameters (TVPs)
  • C interval types such as SQL_C_INTERVAL_YEAR_TO_MONTH (documented in Data Type Identifiers and Descriptors) are not currently supported.
  • Not supported: the SQL_CUR_USE_ODBC value of the SQL_ATTR_ODBC_CURSORS attribute of the SQLSetConnectAttr function.

Character 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 precision.

There is a text-encoding conversion difference between Windows and the iconv library on Linux. Text data that is encoded in codepage 1255 (Hebrew) has one code point (0xCA) that behaves differently on the two platforms. Converting to Unicode on Windows produces a UTF-16 code point of 0x05BA. Converting to Unicode on Linux produces a UTF-16 code point of 0x00CA. Code point 0xCA in codepage 1255 is not defined to be a character. An application should not include logic that uses the (undefined) code point 0xCA.

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.

Other Issues

  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. 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  
  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 that are children of the connection handle.


    DAC connections must use SQL Server Authentication.

See Also

Microsoft ODBC Driver for SQL Server on Linux