プログラミング ガイドラインProgramming Guidelines

ダウンロードODBC Driver のダウンロードDownloadDownload ODBC Driver

macOS と Linux での MicrosoftMicrosoft ODBC Driver for SQL ServerSQL Server のプログラミング機能は、SQL ServerSQL Server Native Client (SQL Server Native Client (ODBC)) の ODBC に基づいています。The programming features of the MicrosoftMicrosoft ODBC Driver for SQL ServerSQL Server on macOS and Linux are based on ODBC in SQL ServerSQL Server Native Client (SQL Server Native Client (ODBC)). SQL ServerSQL Server Native Client は、Windows Data Access Components の ODBC に基づいています (ODBC プログラマー リファレンス)。Native Client is based on ODBC in Windows Data Access Components (ODBC Programmer's Reference).

ODBC アプリケーションでは、unixODBC ヘッダー (sql.hsqlext.hsqltypes.hsqlucode.h) をインクルードした後に /usr/local/include/msodbcsql.h をインクルードすることで、複数のアクティブな結果セット (MARS) やその他の SQL ServerSQL Server 固有の機能を使用できます。An ODBC application can use Multiple Active Result Sets (MARS) and other SQL ServerSQL Server specific features by including /usr/local/include/msodbcsql.h after including the unixODBC headers (sql.h, sqlext.h, sqltypes.h, and sqlucode.h). 次に、Windows ODBC アプリケーションで使用する SQL ServerSQL Server 固有の項目に、同じシンボル名を使用します。Then use the same symbolic names for SQL ServerSQL Server-specific items that you would use in your Windows ODBC applications.

利用可能な機能Available Features

SQL ServerSQL Server ODBC 用 Native Client のドキュメント (SQL Server Native Client (ODBC)) の次のセクションは、macOS と Linux で ODBC ドライバーを使用する場合に有効です。The following sections from the SQL ServerSQL Server Native Client documentation for ODBC (SQL Server Native Client (ODBC)) are valid when using the ODBC driver on macOS and Linux:

サポートされていない機能Unsupported Features

macOS および Linux 上のこのリリースの ODBC ドライバーでは、以下の機能が正しく動作することが確認されていません。The following features have not been verified to work correctly in this release of the ODBC driver on macOS and Linux:

macOS と Linux でのこのリリースの ODBC ドライバーでは、次の機能は利用できません。The following features are not available in this release of the ODBC driver on macOS and Linux:

  • 分散トランザクション (SQL_ATTR_ENLIST_IN_DTC 属性はサポートされていません)Distributed Transactions (SQL_ATTR_ENLIST_IN_DTC attribute is not supported)
  • データベース ミラーリングDatabase Mirroring
  • FILESTREAMFILESTREAM
  • SQLSetConnectAttr で説明されている ODBC ドライバー パフォーマンスのプロファイリング、および次のパフォーマンス関連接続属性:Profiling ODBC driver performance, discussed in SQLSetConnectAttr, and the following performance-related connection attributes:
    • SQL_COPT_SS_PERF_DATASQL_COPT_SS_PERF_DATA
    • SQL_COPT_SS_PERF_DATA_LOGSQL_COPT_SS_PERF_DATA_LOG
    • SQL_COPT_SS_PERF_DATA_LOG_NOWSQL_COPT_SS_PERF_DATA_LOG_NOW
    • SQL_COPT_SS_PERF_QUERYSQL_COPT_SS_PERF_QUERY
    • SQL_COPT_SS_PERF_QUERY_INTERVALSQL_COPT_SS_PERF_QUERY_INTERVAL
    • SQL_COPT_SS_PERF_QUERY_LOGSQL_COPT_SS_PERF_QUERY_LOG
  • SQLBrowseConnect (バージョン 17.2 より前)SQLBrowseConnect (before version 17.2)
  • SQL_C_INTERVAL_YEAR_TO_MONTH などの C 時間隔型 (「Data Type Identifiers and Descriptors」(データ型識別子と記述子) を参照)C interval types such as SQL_C_INTERVAL_YEAR_TO_MONTH (documented in Data Type Identifiers and Descriptors)
  • SQLSetConnectAttr 関数の SQL_ATTR_ODBC_CURSORS 属性の SQL_CUR_USE_ODBC 値。The SQL_CUR_USE_ODBC value of the SQL_ATTR_ODBC_CURSORS attribute of the SQLSetConnectAttr function.

文字セットのサポートCharacter Set Support

ODBC Driver 13 および 13.1 の場合、SQLCHAR データは UTF-8 である必要があります。For ODBC Driver 13 and 13.1, SQLCHAR data must be UTF-8. その他のエンコードはサポートされません。No other encodings are supported.

ODBC Driver 17 の場合、次のいずれかの文字セット/エンコードの SQLCHAR データがサポートされます。For ODBC Driver 17, SQLCHAR data in one of the following character sets/encodings is supported:

注意

muslglibc には iconv の違いがあるため、これらのロケールの多くは、Alpine Linux ではサポートされていません。Due to iconv differences in musl and glibc many of these locales are not supported on Alpine Linux.

詳細については、「Functional differences from glibc (glibc との機能の違い)」を参照してください。For more information, see Functional differences from glibc

名前Name 説明Description
UTF-8UTF-8 UnicodeUnicode
CP437CP437 MS-DOS ラテン アメリカMS-DOS Latin US
CP850CP850 MS-DOS ラテン 1MS-DOS Latin 1
CP874CP874 ラテン/タイ語Latin/Thai
CP932CP932 日本語、Shift-JISJapanese, Shift-JIS
CP936CP936 簡体中国語、GBKSimplified Chinese, GBK
CP949CP949 韓国語、EUC-KRKorean, EUC-KR
CP950CP950 繁体字中国語、Big5Traditional Chinese, Big5
CP1251CP1251 キリル文字Cyrillic
CP1253CP1253 ギリシャ語Greek
CP1256CP1256 アラビア語Arabic
CP1257CP1257 バルト語Baltic
CP1258CP1258 ベトナム語Vietnamese
ISO-8859-1 / CP1252ISO-8859-1 / CP1252 ラテン-1Latin-1
ISO-8859-2 / CP1250ISO-8859-2 / CP1250 ラテン-2Latin-2
ISO-8859-3ISO-8859-3 ラテン-3Latin-3
ISO-8859-4ISO-8859-4 ラテン-4Latin-4
ISO-8859-5ISO-8859-5 ラテン/キリル文字Latin/Cyrillic
ISO-8859-6ISO-8859-6 ラテン/アラビア語Latin/Arabic
ISO-8859-7ISO-8859-7 ラテン/ギリシャ語Latin/Greek
ISO-8859-8 / CP1255ISO-8859-8 / CP1255 ヘブライ語Hebrew
ISO-8859-9 / CP1254ISO-8859-9 / CP1254 トルコ語Turkish
ISO-8859-13ISO-8859-13 ラテン-7Latin-7
ISO-8859-15ISO-8859-15 ラテン-9Latin-9

接続時に、読み込まれているプロセスの現在のロケールがドライバーによって検出されます。Upon connection, the driver detects the current locale of the process it is loaded in. 上記のいずれかのエンコードを使用している場合、ドライバーでは SQLCHAR (ナロー文字) データにそのエンコードが使用されます。それ以外の場合は、既定の UTF-8 が使用されます。If it uses one of the encodings above, the driver uses that encoding for SQLCHAR (narrow-character) data; otherwise, it defaults to UTF-8. すべてのプロセスは既定で "C" ロケールで開始されます (従ってドライバーは既定で UTF-8 になります)。そのため、アプリケーションが上記のエンコードのいずれかを使用する必要がある場合は、接続前に setlocale 関数を使用してロケールを適切に設定する必要があります。そのために、目的のロケールを明示的に指定するか、setlocale(LC_ALL, "") などの空の文字列を使用して環境のロケール設定を使用します。Since all processes start in the "C" locale by default (and thus cause the driver to default to UTF-8), if an application needs to use one of the encodings above, it should use the setlocale function to set the locale appropriately before connecting; either by specifying the desired locale explicitly, or using an empty string for example setlocale(LC_ALL, "") to use the locale settings of the environment.

そのため、エンコードが UTF-8 である一般的な Linux または macOS 環境では、ODBC Driver 13 または 13.1 から 17 にアップグレードしても違いはありません。Thus, in a typical Linux or macOS environment where the encoding is UTF-8, users of ODBC Driver 17 upgrading from 13 or 13.1 will not observe any differences. ただし、setlocale() を介して上記の一覧で UTF-8 以外のエンコードを使用するアプリケーションでは、ドライバーとの間でやり取りするデータに UTF-8 ではなくそのエンコードを使用する必要があります。However, applications that use a non-UTF-8 encoding in the above list via setlocale() need to use that encoding for data to/from the driver instead of UTF-8.

SQLWCHAR データは UTF 16LE (リトル エンディアン) である必要があります。SQLWCHAR data must be UTF-16LE (Little Endian).

入力パラメーターを SQLBindParameter とバインドするときに、SQL_VARCHAR などのナロー文字の SQL 型を指定すると、ドライバーでは、指定されたデータがクライアントのエンコードから既定 (通常はコードページ 1252) の SQL ServerSQL Server エンコードに変換されます。When binding input parameters with SQLBindParameter, if a narrow character SQL type such as SQL_VARCHAR is specified, the driver converts the supplied data from the client encoding to the default (typically codepage 1252) SQL ServerSQL Server encoding. 出力パラメーターの場合、ドライバーでは、データに関連付けられている照合順序情報に指定されたエンコードからクライアントのエンコードに変換されます。For output parameters, the driver converts from the encoding specified in the collation information associated with the data to the client encoding. ただし、データの損失が発生する可能性があります。ターゲット エンコードで表現できないソース エンコードの文字は、疑問符 ('?') に変換されます。However, data loss is possible --- characters in the source encoding not representable in the target encoding will convert to a question mark ('?').

入力パラメーターをバインドするときのこのデータの損失を回避するには、SQL_NVARCHAR などの Unicode SQL 文字型を指定します。To avoid this data loss when binding input parameters, specify a Unicode SQL character type such as SQL_NVARCHAR. この場合、ドライバーでは、クライアントのエンコードから UTF-16 に変換されます。これですべての Unicode 文字を表現することができます。In this case, the driver converts from the client encoding to UTF-16, which can represent all Unicode characters. さらに、サーバー上の対象となる列またはパラメーターも、Unicode 型 (ncharnvarcharntext)、または元のソース データのすべての文字を表現できる照合順序/エンコード付きの型にする必要があります。Furthermore, the target column or parameter on the server must also be either a Unicode type (nchar, nvarchar, ntext) or one with a collation/encoding, which can represent all the characters of the original source data. 出力パラメーターを指定してデータ損失を回避するには、Unicode SQL 型と、Unicode C 型 (SQL_C_WCHAR) のいずれかを指定します。こうすると、ドライバーからデータが UTF-16 として返されるようになります。または、ナロー C 型を使用し、クライアントのエンコードがソース データのすべての文字を表現できるようにします (これは、UTF-8 であれば常に可能です)。For avoiding data loss with output parameters, specify a Unicode SQL type, and either a Unicode C type (SQL_C_WCHAR), causing the driver to return data as UTF-16; or a narrow C type, and ensure that the client encoding can represent all the characters of the source data (this is always possible with UTF-8.)

照合順序とエンコードについて詳しくは、「照合順序と Unicode のサポート」をご覧ください。For more information about collations and encodings, see Collation and Unicode Support.

Windows と、Linux および macOS 上の iconv ライブラリの一部のバージョンとの間には、エンコード変換の違いがいくつかあります。There are some encoding conversion differences between Windows and several versions of the iconv library on Linux and macOS. コードページ 1255 (ヘブライ語) のテキスト データには、Unicode への変換時に動作が異なる 1 つのコード ポイント (0xCA) があります。Text data in codepage 1255 (Hebrew) has one code point (0xCA) that behaves differently upon conversion to Unicode. Windows 上では、この文字は 0x05BA の UTF-16 コード ポイントに変換されます。On Windows, this character converts to the UTF-16 code point of 0x05BA. libiconv のバージョンが 1.15 より前の macOS および Linux 上では、0x00CA に変換されます。On macOS and Linux with libiconv versions earlier than 1.15, it converts to 0x00CA. iconv ライブラリが Big5/CP950 の 2003 リビジョン (名称は BIG5-2003) をサポートしていない Linux 上では、そのリビジョンで追加された文字が正しく変換されません。On Linux with iconv libraries that do not support the 2003 revision of Big5/CP950 (named BIG5-2003), characters added with that revision will not convert correctly. コードページ 932 (日本語、Shift-JIS) では、元のエンコード規格で定義されていない文字のデコード結果も異なります。In codepage 932 (Japanese, Shift-JIS), the result of decoding of characters not originally defined in the encoding standard also differs. たとえば、Windows 上ではバイト 0x80 は U+0080 に変換されますが、Linux および macOS 上では iconv のバージョンによっては U+30FB に変換される場合があります。For example, the byte 0x80 converts to U+0080 on Windows but may become U+30FB on Linux and macOS, depending on iconv version.

ODBC Driver 13 および 13.1 では、UTF-8 マルチバイト文字または UTF-16 サロゲートが SQLPutData バッファー間で分割されている場合、データの破損が発生します。In ODBC Driver 13 and 13.1, when UTF-8 multibyte characters or UTF-16 surrogates are split across SQLPutData buffers, it results in data corruption. 部分文字エンコーディングで終了していないストリーミング SQLPutData にバッファーを使用します。Use buffers for streaming SQLPutData that do not end in partial character encodings. この制限は、ODBC Driver 17 で削除されました。This limitation has been removed with ODBC Driver 17.

OpenSSLOpenSSL

バージョン 17.4 以降では、ドライバーによって OpenSSL が動的に読み込まれ、別のドライバー ファイルを必要とせずに、バージョン 1.0 または 1.1 のいずれかのシステムで実行できます。Starting with version 17.4, the driver loads OpenSSL dynamically, which allows it to run on systems that have either version 1.0 or 1.1 without a need for separate driver files. 複数バージョンの OpenSSL が存在する場合、ドライバーによって最新のバージョンの読み込みが試行されます。When multiple versions of OpenSSL are present, the driver will attempt to load the latest one. このドライバーは、現在、OpenSSL 1.0. x と 1.1. x をサポートしています。The driver currently supports OpenSSL 1.0.x and 1.1.x

注意

ドライバー (またはそのコンポーネントのいずれか) を使用するアプリケーションが OpenSSL の異なるバージョンにリンクされているか、異なるバージョンを動的に読み込んでいる場合、競合が発生する可能性があります。A potential conflict may occur if the application that uses the driver (or one of its components) is linked with or dynamically loads a different version of OpenSSL. システムに複数バージョンの OpenSSL が存在し、アプリケーションにそれが使用されている場合、アプリケーションとドライバーによって読み込まれたバージョンが不一致にならないように特に注意することを強くお勧めします。エラーによりメモリが破損する可能性があり、必ずしも明白なまたは一貫した方法で示されるとは限らないためです。If several versions of OpenSSL are present on the system and the application uses it, it is highly recommended that one be extra careful in making sure that the version loaded by the application and the driver do not mismatch, as the errors could corrupt memory and thus will not necessarily manifest in obvious or consistent ways.

Alpine LinuxAlpine Linux

この記事の執筆時点では、MUSL の既定のスタック サイズは 128K です。これは基本的な ODBC ドライバーの機能には十分ですが、アプリケーションの処理によっては、特に複数のスレッドからドライバーを呼び出す場合は、この制限をたやすく超えます。At the time of this writing the default stack size in MUSL is 128K, which is enough for basic ODBC driver functionality, however depending on what the application does it is not difficult to exceed this limit, especially when calling the driver from multiple threads. Alpine Linux 上で -Wl,-z,stack-size=<VALUE IN BYTES> を使用して ODBC アプリケーションをコンパイルし、スタック サイズを大きくすることをお勧めします。It is recommended that an ODBC application on Alpine Linux is compiled with -Wl,-z,stack-size=<VALUE IN BYTES> to increase the stack size. 参照の場合、ほとんどの GLIBC システムの既定のスタック サイズは 2 MB です。For reference the default stack size on most GLIBC systems is 2MB.

追加情報Additional Notes

  1. SQL ServerSQL Server 認証と host,port を使用して、専用管理者接続 (DAC) を作成できます。You can make a dedicated administrator connection (DAC) using SQL ServerSQL Server authentication and host,port. Sysadmin ロールのメンバーはまず、DAC ポートを検出する必要があります。A member of the Sysadmin role first needs to discover the DAC port. 方法については、「データベース管理者用の診断接続」を参照してください。See Diagnostic Connection for Database Administrators to discover how. たとえば、DAC ポートが 33000 である場合、次のように sqlcmd でそれに接続することができます。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 接続では、SQL ServerSQL Server 認証を使用する必要があります。DAC connections must use SQL ServerSQL Server Authentication.

  2. UnixODBC ドライバー マネージャーは、すべてのステートメント属性に対し、それらが SQLSetConnectAttr 経由で渡される場合に、「属性またはオプション識別子が無効です」を返します。The UnixODBC driver manager returns "invalid attribute/option identifier" for all statement attributes when they are passed through SQLSetConnectAttr. Windows で、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.

  3. 高度なマルチスレッド アプリケーションでドライバーを使用する場合、unixODBC のハンドル検証がパフォーマンスのボトルネックになる可能性があります。When using the driver with highly multithreaded applications, unixODBC's handle validation may become a performance bottleneck. このようなシナリオでは、--enable-fastvalidate オプションを使用して unixODBC をコンパイルすることで、大幅にパフォーマンスを向上させることができます。In such scenarios, significantly more performance may be obtained by compiling unixODBC with the --enable-fastvalidate option. ただし、これにより、アプリケーションから無効なハンドルが ODBC API に渡されると、SQL_INVALID_HANDLE エラーが返されずにクラッシュする可能性があることに注意してください。However, beware that this may cause applications which pass invalid handles to ODBC APIs to crash instead of returning SQL_INVALID_HANDLE errors.

参照See Also

よく寄せられる質問Frequently Asked Questions

このバージョンのドライバーの既知の問題Known Issues in this Version of the Driver

リリース ノートRelease Notes