Win32 API 日本語リファレンス
ホーム › System.Search › SQLSetConnectAttr

SQLSetConnectAttr

関数
接続属性に値を設定する。
DLLODBC32.dll文字セットANSI (-A)呼出規約winapi

シグネチャ

// ODBC32.dll  (ANSI / -A)
#include <windows.h>

SHORT SQLSetConnectAttr(
    void* ConnectionHandle,
    INT Attribute,
    void* Value,   // optional
    INT StringLength
);

パラメーター

名前型方向説明
ConnectionHandlevoid*inout[入力] 接続ハンドル。
AttributeINTin[入力] 設定する属性。「解説」に一覧を示します。
Valuevoid*inoptional設定する属性値。整数または文字列バッファへのポインタ。
StringLengthINTin

[入力] Attribute が ODBC で定義された属性で、ValuePtr が文字列またはバイナリバッファーを指している場合、この引数には *ValuePtr の長さを指定します。文字列データの場合、この引数にはその文字列のバイト数を指定します。

Attribute が ODBC で定義された属性で、ValuePtr が整数の場合、StringLength は無視されます。

Attribute がドライバー定義の属性の場合、アプリケーションは StringLength 引数を設定することで、その属性の性質をドライバーマネージャーに伝えます。StringLength には次の値を指定できます。

  • ValuePtr が文字列へのポインターの場合、StringLength はその文字列の長さまたは SQL_NTS です。

  • ValuePtr がバイナリバッファーへのポインターの場合、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を StringLength に設定します。これにより、StringLength には負の値が設定されます。

  • ValuePtr が文字列でもバイナリ文字列でもない値へのポインターの場合、StringLength には SQL_IS_POINTER を指定します。

  • ValuePtr に固定長の値が含まれる場合、StringLength には適宜 SQL_IS_INTEGER または SQL_IS_UINTEGER のいずれかを指定します。

戻り値の型: SHORT

公式ドキュメント

SQLSetConnectAttr は、接続のさまざまな動作を制御する属性を設定します。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE、または SQL_STILL_EXECUTING。

解説(Remarks)

接続属性に関する一般的な情報については、Connection Attributes を参照してください。

現在定義されている属性と、それらが導入された ODBC のバージョンを、このセクションの後半の表に示します。さまざまなデータソースを活用するために、今後さらに属性が定義されることが想定されています。一定範囲の属性は ODBC によって予約されています。ドライバー開発者は、自身のドライバー固有の用途に使用する値を Open Group から予約する必要があります。

メモ

SQLSetConnectAttr を呼び出して接続レベルでステートメント属性を設定する機能は、ODBC 3*.x* では非推奨になりました。ODBC 3*.x* アプリケーションでは、接続レベルでステートメント属性を設定しないでください。ODBC 3*.x* のステートメント属性は接続レベルでは設定できません。ただし、SQL_ATTR_METADATA_ID 属性と SQL_ATTR_ASYNC_ENABLE 属性は例外です。これらは接続属性であると同時にステートメント属性でもあり、接続レベルとステートメントレベルのいずれでも設定できます。

ODBC 3*.x* ドライバーは、接続レベルで ODBC 2*.x* のステートメントオプションを設定する ODBC 2*.x* アプリケーションと連携する必要がある場合にのみ、この機能をサポートすれば十分です。詳細については、「Appendix G: Driver Guidelines for Backward Compatibility」の SQLSetConnectOption Mapping を参照してください。

アプリケーションは、接続が割り当てられてから解放されるまでの間であれば、いつでも SQLSetConnectAttr を呼び出すことができます。アプリケーションがその接続に対して正常に設定したすべての接続属性およびステートメント属性は、その接続に対して SQLFreeHandle が呼び出されるまで保持されます。たとえば、アプリケーションがデータソースへの接続前に SQLSetConnectAttr を呼び出した場合、データソースへの接続時にドライバー内で SQLSetConnectAttr が失敗しても、その属性は保持されます。また、アプリケーションがドライバー固有の属性を設定した場合、その接続で別のドライバーに接続しても、その属性は保持されます。

接続属性には、接続の確立前にしか設定できないものと、接続の確立後にしか設定できないものがあります。次の表は、接続の確立前と確立後のどちらで設定しなければならないかを示しています。どちらでも は、その属性を接続の前後どちらでも設定できることを示します。

属性 接続の前と後のどちらで設定するか
SQL_ATTR_ACCESS_MODE どちらでも[1]
SQL_ATTR_ASYNC_DBC_EVENT どちらでも
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE どちらでも[4]
SQL_ATTR_ASYNC_DBC_PCALLBACK どちらでも
SQL_ATTR_ASYNC_DBC_PCONTEXT どちらでも
SQL_ATTR_ASYNC_ENABLE どちらでも[2]
SQL_ATTR_AUTO_IPD どちらでも
SQL_ATTR_AUTOCOMMIT どちらでも[5]
SQL_ATTR_CONNECTION_DEAD 接続後
SQL_ATTR_CONNECTION_TIMEOUT どちらでも
SQL_ATTR_CURRENT_CATALOG どちらでも[1]
SQL_ATTR_DBC_INFO_TOKEN 接続後
SQL_ATTR_ENLIST_IN_DTC 接続後
SQL_ATTR_LOGIN_TIMEOUT 接続前
SQL_ATTR_METADATA_ID どちらでも
SQL_ATTR_ODBC_CURSORS 接続前
SQL_ATTR_PACKET_SIZE 接続前
SQL_ATTR_QUIET_MODE どちらでも
SQL_ATTR_TRACE どちらでも
SQL_ATTR_TRACEFILE どちらでも
SQL_ATTR_TRANSLATE_LIB 接続後
SQL_ATTR_TRANSLATE_OPTION 接続後
SQL_ATTR_TXN_ISOLATION どちらでも[3]

[1] SQL_ATTR_ACCESS_MODE と SQL_ATTR_CURRENT_CATALOG は、ドライバーによって接続の前後どちらでも設定できます。ただし、接続後の変更をサポートしないドライバーもあるため、相互運用性を重視するアプリケーションでは接続前に設定します。

[2] SQL_ATTR_ASYNC_ENABLE は、アクティブなステートメントが存在するようになる前に設定する必要があります。

[3] SQL_ATTR_TXN_ISOLATION は、その接続上に開いているトランザクションがない場合にのみ設定できます。一部の接続属性は、*ValuePtr で指定された値をデータソースがサポートしていない場合に、類似する値への置き換えをサポートします。その場合、ドライバーは SQL_SUCCESS_WITH_INFO と SQLSTATE 01S02 (Option value changed) を返します。たとえば、Attribute が SQL_ATTR_PACKET_SIZE で、*ValuePtr が最大パケットサイズを超えている場合、ドライバーは最大サイズに置き換えます。置き換えられた値を確認するには、アプリケーションは SQLGetConnectAttr を呼び出します。

[4] SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE が接続を開く前に設定された場合、ドライバーマネージャーは、SQLBrowseConnect、SQLConnect、または SQLDriverConnect の呼び出し中にドライバーが読み込まれた時点で、そのドライバーの属性を設定します。SQLBrowseConnect、SQLConnect、または SQLDriverConnect の呼び出し前は、ドライバーマネージャーはどのドライバーに接続するのかを把握しておらず、そのドライバーが非同期の接続操作をサポートしているかどうかも分かりません。そのため、ドライバーマネージャーは常に SQL_SUCCESS を返します。ただし、ドライバーが非同期の接続操作をサポートしていない場合は、SQLBrowseConnect、SQLConnect、または SQLDriverConnect の呼び出しが失敗します。

[5] SQL_ATTR_AUTOCOMMIT が FALSE に設定されている場合、トランザクションの整合性を確保するため、いずれかの API が SQL_ERROR を返したときにはアプリケーションで SQLEndTran(SQL_ROLLBACK) を呼び出す必要があります。

*ValuePtr バッファーに設定する情報の形式は、指定した Attribute によって異なります。SQLSetConnectAttr は、属性の情報を 2 つの形式のいずれかで受け取ります。null で終わる文字列、または整数値です。それぞれの形式は各属性の説明に記載されています。SQLSetConnectAttr の ValuePtr 引数が指す文字列の長さは StringLength バイトです。

ODBC 2*.x* 以前で導入されたすべての属性のように長さが属性によって決まっている場合、StringLength 引数は無視されます。

Attribute ValuePtr の内容
SQL_ATTR_ACCESS_MODE (ODBC 1.0) SQLUINTEGER 値。SQL_MODE_READ_ONLY は、更新を発生させる SQL ステートメントを接続がサポートする必要がないことを示すインジケーターとして、ドライバーまたはデータソースが使用します。このモードは、ロック方式やトランザクション管理など、ドライバーまたはデータソースにとって適切な領域の最適化に利用できます。ドライバーは、そのようなステートメントがデータソースに送信されるのを防ぐ必要はありません。読み取り専用の接続中に読み取り専用ではない SQL ステートメントの処理を要求された場合のドライバーおよびデータソースの動作は、実装依存です。既定値は SQL_MODE_READ_WRITE です。
SQL_ATTR_ASYNC_DBC_EVENT (ODBC 3.8) イベントハンドルである SQLPOINTER 値。

非同期関数の完了通知は、SQL_ATTR_ASYNC_STMT_EVENT 属性を指定して SQLSetConnectAttr を呼び出し、イベントハンドルを指定することで有効になります。注: この通知方式はカーソルライブラリではサポートされていません。通知方式が有効になっている状態で SQLSetConnectAttr によってカーソルライブラリを有効にしようとすると、アプリケーションはエラーメッセージを受け取ります。
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE (ODBC 3.8) 接続ハンドルに対する特定の関数の非同期実行を有効または無効にする SQLUINTEGER 値。詳細については、Asynchronous Execution (Polling Method) を参照してください。

SQL_ASYNC_DBC_ENABLE_ON = 指定した接続関連の関数について非同期操作を有効にします。

SQL_ASYNC_DBC_ENABLE_OFF = (既定値) 指定した接続関連の関数について非同期操作を無効にします。

SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE の設定は常に同期的です (つまり、SQL_STILL_EXECUTING を返すことはありません)。

ステートメント操作の非同期実行は SQL_ATTR_ASYNC_ENABLE で有効にします。
SQL_ATTR_ASYNC_DBC_PCALLBACK (ODBC 3.8) コンテキスト構造体を指す SQLPOINTER 値。

この属性を指定してドライバーの SQLSetStmtAttr 関数を呼び出せるのは、ドライバーマネージャーだけです。
SQL_ATTR_ASYNC_DBC_PCONTEXT (ODBC 3.8) コンテキスト構造体を指す SQLPOINTER 値。

この属性を指定してドライバーの SQLSetStmtAttr 関数を呼び出せるのは、ドライバーマネージャーだけです。
SQL_ATTR_ASYNC_ENABLE (ODBC 3.0) 指定した接続上のステートメントで呼び出された関数を非同期に実行するかどうかを指定する SQLULEN 値:

SQL_ASYNC_ENABLE_OFF = ステートメント操作に対する接続レベルの非同期実行サポートを無効にします (既定値)。

SQL_ASYNC_ENABLE_ON = ステートメント操作に対する接続レベルの非同期実行サポートを有効にします。

この属性は、SQL_ASYNC_MODE 情報型を指定した SQLGetInfo が SQL_AM_CONNECTION と SQL_AM_STATEMENT のどちらを返す場合でも設定できます。
SQL_ATTR_AUTO_IPD (ODBC 3.0) SQLPrepare の呼び出し後の IPD の自動設定がサポートされているかどうかを示す、読み取り専用の SQLUINTEGER 値:

SQL_TRUE = SQLPrepare の呼び出し後の IPD の自動設定がドライバーでサポートされています。

SQL_FALSE = SQLPrepare の呼び出し後の IPD の自動設定がドライバーでサポートされていません。準備済みステートメントをサポートしないサーバーでは、IPD を自動的に設定できません。

SQL_ATTR_AUTO_IPD 接続属性に対して SQL_TRUE が返された場合、ステートメント属性 SQL_ATTR_ENABLE_AUTO_IPD を設定して、IPD の自動設定のオンとオフを切り替えることができます。SQL_ATTR_AUTO_IPD が SQL_FALSE の場合、SQL_ATTR_ENABLE_AUTO_IPD を SQL_TRUE に設定することはできません。SQL_ATTR_ENABLE_AUTO_IPD の既定値は SQL_ATTR_AUTO_IPD の値と同じです。

この接続属性は SQLGetConnectAttr で取得できますが、SQLSetConnectAttr で設定することはできません。
SQL_ATTR_AUTOCOMMIT (ODBC 1.0) 自動コミットモードと手動コミットモードのどちらを使用するかを指定する SQLUINTEGER 値:

SQL_AUTOCOMMIT_OFF = ドライバーは手動コミットモードを使用します。アプリケーションは SQLEndTran でトランザクションを明示的にコミットまたはロールバックする必要があります。

SQL_AUTOCOMMIT_ON = ドライバーは自動コミットモードを使用します。各ステートメントは実行された直後にコミットされます。これが既定値です。手動コミットモードから自動コミットモードに変更するために SQL_ATTR_AUTOCOMMIT を SQL_AUTOCOMMIT_ON に設定すると、その接続上で開いているトランザクションはすべてコミットされます。

詳細については、Commit Mode を参照してください。重要: データソースによっては、ステートメントがコミットされるたびに、その接続上のすべてのステートメントのアクセスプランを削除し、カーソルを閉じるものがあります。自動コミットモードでは、非クエリステートメントが実行されるたび、またはクエリのカーソルが閉じられたときに、これが発生する可能性があります。詳細については、SQLGetInfo の SQL_CURSOR_COMMIT_BEHAVIOR および SQL_CURSOR_ROLLBACK_BEHAVIOR 情報型と、Effect of Transactions on Cursors and Prepared Statements を参照してください。

自動コミットモードでバッチを実行する場合、2 つの動作が考えられます。バッチ全体を 1 つの自動コミット単位として扱う場合と、バッチ内の各ステートメントを自動コミット単位として扱う場合です。データソースによっては、この両方の動作をサポートし、どちらかを選択する手段を提供することもあります。バッチを 1 つの自動コミット単位として扱うか、バッチ内の個々のステートメントを自動コミット単位として扱うかは、ドライバーによって定義されます。
SQL_ATTR_CONNECTION_DEAD

(ODBC 3.5)
接続の状態を示す、読み取り専用の SQLUINTEGER 値。SQL_CD_TRUE の場合、接続は失われています。SQL_CD_FALSE の場合、接続はまだ有効です。
SQL_ATTR_CONNECTION_TIMEOUT (ODBC 3.0) 接続上の要求が完了してアプリケーションに制御が戻るまでの待機秒数に対応する SQLUINTEGER 値。ドライバーは、クエリの実行やログインに関連しない状況でタイムアウトが発生し得る場合には常に、SQLSTATE HYT00 (Timeout expired) を返す必要があります。

ValuePtr が 0 (既定値) の場合、タイムアウトはありません。
SQL_ATTR_CURRENT_CATALOG (ODBC 2.0) データソースが使用するカタログの名前を格納する文字列。たとえば SQL Server では、カタログはデータベースであるため、ドライバーはデータソースに USE database ステートメントを送信します。ここで database は *ValuePtr で指定されたデータベースです。単層ドライバーの場合、カタログはディレクトリであることがあり、その場合ドライバーは現在のディレクトリを *ValuePtr で指定されたディレクトリに変更します。
SQL_ATTR_DBC_INFO_TOKEN (ODBC 3.8 SQLRateConnection の (*pRating) パラメーターが 100 以外の場合に、接続情報トークンを DBC ハンドルに設定し直すために使用する SQLPOINTER 値。

SQL_ATTR_DBC_INFO_TOKEN は設定専用です。SQLGetConnectAttr や SQLGetConnectOption を使用してこの値を取得することはできません。アプリケーションがこの属性を設定するべきではないため、ドライバーマネージャーの SQLSetConnectAttr は SQL_ATTR_DBC_INFO_TOKEN を受け付けません。

SQL_ATTR_DBC_INFO_TOKEN の設定後にドライバーが SQL_ERROR を返した場合、プールから取得したばかりの接続は解放されます。その後、ドライバーマネージャーはプールから別の接続を取得しようとします。詳細については、Developing Connection-Pool Awareness in an ODBC Driver を参照してください。
SQL_ATTR_ENLIST_IN_DTC (ODBC 3.0) Microsoft Component Services によって調整される分散トランザクションで ODBC ドライバーを使用するかどうかを指定する SQLPOINTER 値。

SQL Server にエクスポートするトランザクションを指定する DTC OLE トランザクションオブジェクトを渡すか、接続の DTC への関連付けを終了するには SQL_DTC_DONE を渡します。

クライアントは、Microsoft Distributed Transaction Coordinator (MS DTC) の OLE ITransactionDispenser::BeginTransaction メソッドを呼び出して MS DTC トランザクションを開始し、そのトランザクションを表す MS DTC トランザクションオブジェクトを作成します。次に、アプリケーションは SQL_ATTR_ENLIST_IN_DTC オプションを指定して SQLSetConnectAttr を呼び出し、トランザクションオブジェクトを ODBC 接続に関連付けます。関連するデータベース操作はすべて、MS DTC トランザクションの保護下で実行されます。接続の DTC への関連付けを終了するには、アプリケーションは SQL_DTC_DONE を指定して SQLSetConnectAttr を呼び出します。詳細については、MS DTC のドキュメントを参照してください。
SQL_ATTR_LOGIN_TIMEOUT (ODBC 1.0) ログイン要求が完了してアプリケーションに制御が戻るまでの待機秒数に対応する SQLUINTEGER 値。既定値はドライバーに依存します。ValuePtr が 0 の場合、タイムアウトは無効になり、接続の試行は無期限に待機します。

指定したタイムアウトがデータソースの最大ログインタイムアウトを超える場合、ドライバーはその値に置き換え、SQLSTATE 01S02 (Option value changed) を返します。
SQL_ATTR_METADATA_ID (ODBC 3.0) カタログ関数の文字列引数をどのように扱うかを決定する SQLUINTEGER 値。

SQL_TRUE の場合、カタログ関数の文字列引数は識別子として扱われます。大文字と小文字は区別されません。区切り記号で囲まれていない文字列の場合、ドライバーは末尾の空白を削除し、文字列を大文字に変換します。区切り記号で囲まれた文字列の場合、ドライバーは先頭と末尾の空白を削除し、区切り記号の間にある内容をそのまま解釈します。これらの引数のいずれかに null ポインターを設定した場合、関数は SQL_ERROR と SQLSTATE HY009 (Invalid use of null pointer) を返します。

SQL_FALSE の場合、カタログ関数の文字列引数は識別子として扱われません。大文字と小文字は区別されます。引数によっては、文字列検索パターンを含む場合と含まない場合があります。

既定値は SQL_FALSE です。

値のリストを受け取る SQLTables の TableType 引数は、この属性の影響を受けません。

SQL_ATTR_METADATA_ID はステートメントレベルでも設定できます (ステートメント属性でもある唯一の接続属性です)。

詳細については、Arguments in Catalog Functions を参照してください。
SQL_ATTR_ODBC_CURSORS (ODBC 2.0) ドライバーマネージャーが ODBC カーソルライブラリをどのように使用するかを指定する SQLULEN 値:

SQL_CUR_USE_IF_NEEDED = ドライバーマネージャーは、必要な場合にのみ ODBC カーソルライブラリを使用します。ドライバーが SQLFetchScroll の SQL_FETCH_PRIOR オプションをサポートしている場合、ドライバーマネージャーはそのドライバーのスクロール機能を使用します。そうでない場合は、ODBC カーソルライブラリを使用します。

SQL_CUR_USE_ODBC = ドライバーマネージャーは ODBC カーソルライブラリを使用します。

SQL_CUR_USE_DRIVER = ドライバーマネージャーはドライバーのスクロール機能を使用します。これが既定の設定です。

ODBC カーソルライブラリの詳細については、Appendix F: ODBC Cursor Library を参照してください。警告: カーソルライブラリは、将来のバージョンの Windows で削除されます。新規の開発ではこの機能の使用を避け、現在この機能を使用しているアプリケーションについては変更を計画してください。Microsoft は、ドライバーのカーソル機能を使用することを推奨します。
SQL_ATTR_PACKET_SIZE (ODBC 2.0) ネットワークパケットサイズをバイト単位で指定する SQLUINTEGER 値。注: 多くのデータソースは、このオプションをサポートしていないか、ネットワークパケットサイズの取得のみが可能で設定はできません。

指定したサイズが最大パケットサイズを超える場合、または最小パケットサイズより小さい場合、ドライバーはその値に置き換え、SQLSTATE 01S02 (Option value changed) を返します。

接続が既に確立された後にアプリケーションがパケットサイズを設定した場合、ドライバーは SQLSTATE HY011 (Attribute cannot be set now) を返します。
SQL_ATTR_QUIET_MODE (ODBC 2.0) ウィンドウハンドル (HWND)。

ウィンドウハンドルが null ポインターの場合、ドライバーはダイアログボックスを表示しません。

ウィンドウハンドルが null ポインターでない場合、それはアプリケーションの親ウィンドウのハンドルである必要があります。これが既定値です。ドライバーはこのハンドルを使用してダイアログボックスを表示します。注: SQL_ATTR_QUIET_MODE 接続属性は、SQLDriverConnect が表示するダイアログボックスには適用されません。
SQL_ATTR_TRACE (ODBC 1.0) ドライバーマネージャーがトレースを実行するかどうかを指示する SQLUINTEGER 値:

SQL_OPT_TRACE_OFF = トレースをオフにします (既定値)

SQL_OPT_TRACE_ON = トレースをオンにします

トレースがオンの場合、ドライバーマネージャーは ODBC 関数の各呼び出しをトレースファイルに書き込みます。注: トレースがオンの場合、ドライバーマネージャーは任意の関数から SQLSTATE IM013 (Trace file error) を返すことがあります。

アプリケーションは SQL_ATTR_TRACEFILE オプションでトレースファイルを指定します。ファイルが既に存在する場合、ドライバーマネージャーはそのファイルに追記します。存在しない場合は、ファイルを作成します。トレースがオンでトレースファイルが指定されていない場合、ドライバーマネージャーはルートディレクトリの SQL.LOG ファイルに書き込みます。

アプリケーションは、変数 ODBCSharedTraceFlag を設定してトレースを動的に有効にできます。その場合、現在実行中のすべての ODBC アプリケーションでトレースが有効になります。アプリケーションがトレースをオフにした場合、オフになるのはそのアプリケーションだけです。

システム情報の Trace キーワードが 1 に設定されている状態で、アプリケーションが HandleType に SQL_HANDLE_ENV を指定して SQLAllocHandle を呼び出すと、すべてのハンドルでトレースが有効になります。有効になるのは SQLAllocHandle を呼び出したアプリケーションのみです。

Attribute に SQL_ATTR_TRACE を指定して SQLSetConnectAttr を呼び出す場合、ConnectionHandle 引数が有効である必要はなく、ConnectionHandle が NULL であっても SQL_ERROR は返されません。この属性はすべての接続に適用されます。
SQL_ATTR_TRACEFILE (ODBC 1.0) トレースファイルの名前を格納する、null で終わる文字列。

SQL_ATTR_TRACEFILE 属性の既定値は、システム情報の TraceFile キーワードで指定します。詳細については、ODBC Subkey を参照してください。

Attribute に SQL_ATTR_TRACEFILE を指定して SQLSetConnectAttr を呼び出す場合、ConnectionHandle 引数が有効である必要はなく、ConnectionHandle が無効であっても SQL_ERROR は返されません。この属性はすべての接続に適用されます。
SQL_ATTR_TRANSLATE_LIB (ODBC 1.0) 文字セットの変換などの処理を実行するためにドライバーがアクセスする、SQLDriverToDataSource および SQLDataSourceToDriver 関数を含むライブラリの名前を格納する、null で終わる文字列。このオプションは、ドライバーがデータソースに接続している場合にのみ指定できます。この属性の設定は、接続をまたいで保持されます。データの変換の詳細については、Translation DLLs および Translation DLL Function Reference を参照してください。
SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) 変換 DLL に渡される 32 ビットのフラグ値。この属性は、ドライバーがデータソースに接続している場合にのみ指定できます。データの変換については、Translation DLLs を参照してください。
SQL_ATTR_TXN_ISOLATION (ODBC 1.0) 現在の接続のトランザクション分離レベルを設定する 32 ビットのビットマスク。このオプションを指定して SQLSetConnectAttr を呼び出す前に、アプリケーションは SQLEndTran を呼び出して、接続上で開いているすべてのトランザクションをコミットまたはロールバックする必要があります。

ValuePtr に指定できる値は、InfoType に SQL_TXN_ISOLATION_OPTIONS を指定して SQLGetInfo を呼び出すことで判別できます。

トランザクション分離レベルの説明については、SQLGetInfo の SQL_DEFAULT_TXN_ISOLATION 情報型の説明と、Transaction Isolation Levels を参照してください。

[1] これらの関数を非同期に呼び出せるのは、記述子がアプリケーション記述子ではなく実装記述子である場合のみです。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp)

各言語での呼び出し定義

// ODBC32.dll  (ANSI / -A)
#include <windows.h>

SHORT SQLSetConnectAttr(
    void* ConnectionHandle,
    INT Attribute,
    void* Value,   // optional
    INT StringLength
);
[DllImport("ODBC32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern short SQLSetConnectAttr(
    IntPtr ConnectionHandle,   // void* in/out
    int Attribute,   // INT
    IntPtr Value,   // void* optional
    int StringLength   // INT
);
<DllImport("ODBC32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function SQLSetConnectAttr(
    ConnectionHandle As IntPtr,   ' void* in/out
    Attribute As Integer,   ' INT
    Value As IntPtr,   ' void* optional
    StringLength As Integer   ' INT
) As Short
End Function
' ConnectionHandle : void* in/out
' Attribute : INT
' Value : void* optional
' StringLength : INT
Declare PtrSafe Function SQLSetConnectAttr Lib "odbc32" ( _
    ByVal ConnectionHandle As LongPtr, _
    ByVal Attribute As Long, _
    ByVal Value As LongPtr, _
    ByVal StringLength As Long) As Integer
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

SQLSetConnectAttr = ctypes.windll.odbc32.SQLSetConnectAttr
SQLSetConnectAttr.restype = ctypes.c_short
SQLSetConnectAttr.argtypes = [
    ctypes.POINTER(None),  # ConnectionHandle : void* in/out
    ctypes.c_int,  # Attribute : INT
    ctypes.POINTER(None),  # Value : void* optional
    ctypes.c_int,  # StringLength : INT
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ODBC32.dll')
SQLSetConnectAttr = Fiddle::Function.new(
  lib['SQLSetConnectAttr'],
  [
    Fiddle::TYPE_VOIDP,  # ConnectionHandle : void* in/out
    Fiddle::TYPE_INT,  # Attribute : INT
    Fiddle::TYPE_VOIDP,  # Value : void* optional
    Fiddle::TYPE_INT,  # StringLength : INT
  ],
  Fiddle::TYPE_SHORT)
#[link(name = "odbc32")]
extern "system" {
    fn SQLSetConnectAttr(
        ConnectionHandle: *mut (),  // void* in/out
        Attribute: i32,  // INT
        Value: *mut (),  // void* optional
        StringLength: i32  // INT
    ) -> i16;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("ODBC32.dll", CharSet = CharSet.Ansi)]
public static extern short SQLSetConnectAttr(IntPtr ConnectionHandle, int Attribute, IntPtr Value, int StringLength);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ODBC32_SQLSetConnectAttr' -Namespace Win32 -PassThru
# $api::SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength)
#uselib "ODBC32.dll"
#func global SQLSetConnectAttr "SQLSetConnectAttr" sptr, sptr, sptr, sptr
; SQLSetConnectAttr ConnectionHandle, Attribute, Value, StringLength   ; 戻り値は stat
; ConnectionHandle : void* in/out -> "sptr"
; Attribute : INT -> "sptr"
; Value : void* optional -> "sptr"
; StringLength : INT -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "ODBC32.dll"
#cfunc global SQLSetConnectAttr "SQLSetConnectAttr" sptr, int, sptr, int
; res = SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength)
; ConnectionHandle : void* in/out -> "sptr"
; Attribute : INT -> "int"
; Value : void* optional -> "sptr"
; StringLength : INT -> "int"
; SHORT SQLSetConnectAttr(void* ConnectionHandle, INT Attribute, void* Value, INT StringLength)
#uselib "ODBC32.dll"
#cfunc global SQLSetConnectAttr "SQLSetConnectAttr" intptr, int, intptr, int
; res = SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength)
; ConnectionHandle : void* in/out -> "intptr"
; Attribute : INT -> "int"
; Value : void* optional -> "intptr"
; StringLength : INT -> "int"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	odbc32 = windows.NewLazySystemDLL("ODBC32.dll")
	procSQLSetConnectAttr = odbc32.NewProc("SQLSetConnectAttr")
)

// ConnectionHandle (void* in/out), Attribute (INT), Value (void* optional), StringLength (INT)
r1, _, err := procSQLSetConnectAttr.Call(
	uintptr(ConnectionHandle),
	uintptr(Attribute),
	uintptr(Value),
	uintptr(StringLength),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // SHORT
function SQLSetConnectAttr(
  ConnectionHandle: Pointer;   // void* in/out
  Attribute: Integer;   // INT
  Value: Pointer;   // void* optional
  StringLength: Integer   // INT
): Smallint; stdcall;
  external 'ODBC32.dll' name 'SQLSetConnectAttr';
result := DllCall("ODBC32\SQLSetConnectAttr"
    , "Ptr", ConnectionHandle   ; void* in/out
    , "Int", Attribute   ; INT
    , "Ptr", Value   ; void* optional
    , "Int", StringLength   ; INT
    , "Short")   ; return: SHORT
●SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength) = DLL("ODBC32.dll", "int SQLSetConnectAttr(void*, int, void*, int)")
# 呼び出し: SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength)
# ConnectionHandle : void* in/out -> "void*"
# Attribute : INT -> "int"
# Value : void* optional -> "void*"
# StringLength : INT -> "int"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "odbc32" fn SQLSetConnectAttr(
    ConnectionHandle: ?*anyopaque, // void* in/out
    Attribute: i32, // INT
    Value: ?*anyopaque, // void* optional
    StringLength: i32 // INT
) callconv(std.os.windows.WINAPI) i16;
proc SQLSetConnectAttr(
    ConnectionHandle: pointer,  # void* in/out
    Attribute: int32,  # INT
    Value: pointer,  # void* optional
    StringLength: int32  # INT
): int16 {.importc: "SQLSetConnectAttr", stdcall, dynlib: "ODBC32.dll".}
pragma(lib, "odbc32");
extern(Windows)
short SQLSetConnectAttr(
    void* ConnectionHandle,   // void* in/out
    int Attribute,   // INT
    void* Value,   // void* optional
    int StringLength   // INT
);
ccall((:SQLSetConnectAttr, "ODBC32.dll"), stdcall, Int16,
      (Ptr{Cvoid}, Int32, Ptr{Cvoid}, Int32),
      ConnectionHandle, Attribute, Value, StringLength)
# ConnectionHandle : void* in/out -> Ptr{Cvoid}
# Attribute : INT -> Int32
# Value : void* optional -> Ptr{Cvoid}
# StringLength : INT -> Int32
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int16_t SQLSetConnectAttr(
    void* ConnectionHandle,
    int32_t Attribute,
    void* Value,
    int32_t StringLength);
]]
local odbc32 = ffi.load("odbc32")
-- odbc32.SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength)
-- ConnectionHandle : void* in/out
-- Attribute : INT
-- Value : void* optional
-- StringLength : INT
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('ODBC32.dll');
const SQLSetConnectAttr = lib.func('__stdcall', 'SQLSetConnectAttr', 'int16_t', ['void *', 'int32_t', 'void *', 'int32_t']);
// SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength)
// ConnectionHandle : void* in/out -> 'void *'
// Attribute : INT -> 'int32_t'
// Value : void* optional -> 'void *'
// StringLength : INT -> 'int32_t'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("ODBC32.dll", {
  SQLSetConnectAttr: { parameters: ["pointer", "i32", "pointer", "i32"], result: "i16" },
});
// lib.symbols.SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength)
// ConnectionHandle : void* in/out -> "pointer"
// Attribute : INT -> "i32"
// Value : void* optional -> "pointer"
// StringLength : INT -> "i32"
// 文字列は "buffer"。ANSI(-A) は new TextEncoder() で UTF-8/ANSI バイト列(末尾に \x00)を渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int16_t SQLSetConnectAttr(
    void* ConnectionHandle,
    int32_t Attribute,
    void* Value,
    int32_t StringLength);
C, "ODBC32.dll");
// $ffi->SQLSetConnectAttr(ConnectionHandle, Attribute, Value, StringLength);
// ConnectionHandle : void* in/out
// Attribute : INT
// Value : void* optional
// StringLength : INT
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Odbc32 extends StdCallLibrary {
    Odbc32 INSTANCE = Native.load("odbc32", Odbc32.class, W32APIOptions.ASCII_OPTIONS);
    short SQLSetConnectAttr(
        Pointer ConnectionHandle,   // void* in/out
        int Attribute,   // INT
        Pointer Value,   // void* optional
        int StringLength   // INT
    );
}
@[Link("odbc32")]
lib LibODBC32
  fun SQLSetConnectAttr = SQLSetConnectAttr(
    ConnectionHandle : Void*,   # void* in/out
    Attribute : Int32,   # INT
    Value : Void*,   # void* optional
    StringLength : Int32   # INT
  ) : Int16
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef SQLSetConnectAttrNative = Int16 Function(Pointer<Void>, Int32, Pointer<Void>, Int32);
typedef SQLSetConnectAttrDart = int Function(Pointer<Void>, int, Pointer<Void>, int);
final SQLSetConnectAttr = DynamicLibrary.open('ODBC32.dll')
    .lookupFunction<SQLSetConnectAttrNative, SQLSetConnectAttrDart>('SQLSetConnectAttr');
// ConnectionHandle : void* in/out -> Pointer<Void>
// Attribute : INT -> Int32
// Value : void* optional -> Pointer<Void>
// StringLength : INT -> Int32
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function SQLSetConnectAttr(
  ConnectionHandle: Pointer;   // void* in/out
  Attribute: Integer;   // INT
  Value: Pointer;   // void* optional
  StringLength: Integer   // INT
): Smallint; stdcall;
  external 'ODBC32.dll' name 'SQLSetConnectAttr';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "SQLSetConnectAttr"
  c_SQLSetConnectAttr :: Ptr () -> Int32 -> Ptr () -> Int32 -> IO Int16
-- ConnectionHandle : void* in/out -> Ptr ()
-- Attribute : INT -> Int32
-- Value : void* optional -> Ptr ()
-- StringLength : INT -> Int32
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let sqlsetconnectattr =
  foreign "SQLSetConnectAttr"
    ((ptr void) @-> int32_t @-> (ptr void) @-> int32_t @-> returning int16_t)
(* ConnectionHandle : void* in/out -> (ptr void) *)
(* Attribute : INT -> int32_t *)
(* Value : void* optional -> (ptr void) *)
(* StringLength : INT -> int32_t *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library odbc32 (t "ODBC32.dll"))
(cffi:use-foreign-library odbc32)

(cffi:defcfun ("SQLSetConnectAttr" sqlset-connect-attr :convention :stdcall) :int16
  (connection-handle :pointer)   ; void* in/out
  (attribute :int32)   ; INT
  (value :pointer)   ; void* optional
  (string-length :int32))   ; INT
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $SQLSetConnectAttr = Win32::API::More->new('ODBC32',
    'short SQLSetConnectAttr(LPVOID ConnectionHandle, int Attribute, LPVOID Value, int StringLength)');
# my $ret = $SQLSetConnectAttr->Call($ConnectionHandle, $Attribute, $Value, $StringLength);
# ConnectionHandle : void* in/out -> LPVOID
# Attribute : INT -> int
# Value : void* optional -> LPVOID
# StringLength : INT -> int
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

文字セット違い