SQLSetConnectAttr 関数
準拠
導入されたバージョン: ODBC 3.0 Standards Compliance: ISO 92
まとめ
SQLSetConnectAttr は、接続の側面を制御する属性を設定します。
Note
ODBC 3*.x* アプリケーションが ODBC 2*.x* ドライバーを操作している場合にドライバー マネージャーによってこの関数がマップされる内容の詳細については、「 アプリケーションの下位互換性のための置換関数のマッピング」を参照してください。
構文
SQLRETURN SQLSetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
引数
ConnectionHandle
[入力] 接続ハンドル。
属性
[入力]設定する属性。"コメント" に一覧表示されます。
ValuePtr
[入力] Attribute に関連付ける値へのポインター。 Attribute の値に応じて、ValuePtr は符号なし整数値であるか、null で終わる文字列を指します。 Attribute 引数の整数型は固定長ではない可能性があることに注意してください。詳細については、「コメント」セクションを参照してください。
StringLength
[入力] 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のいずれかになります。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE、またはSQL_STILL_EXECUTING。
診断
SQLSetConnectAttr がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_DBCの HandleType と ConnectionHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLSetConnectAttr によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。
ドライバーは、オプションの設定結果に関する情報を提供するSQL_SUCCESS_WITH_INFOを返すことができます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01S02 | オプション値の変更 | ドライバーは 、ValuePtr で指定された値をサポートしておらず、同様の値を置き換えました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 08002 | 使用中の接続名 | Attribute 引数がSQL_ATTR_ODBC_CURSORSされ、ドライバーは既にデータ ソースに接続されています。 |
| 08003 | 接続が開かない | (DM) 開いている接続を必要とする 属性値 が指定されましたが、 ConnectionHandle が接続状態ではありません。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 24000 | カーソル状態が無効 | Attribute 引数がSQL_ATTR_CURRENT_CATALOGされ、結果セットが保留中でした。 |
| 25000 | ローカル トランザクションでの操作が無効です | 接続属性をSQL_ATTR_ENLIST_IN_DTC設定して分散トランザクション接続 (DTC) に参加しようとしたときに、接続がローカル トランザクションにありました。 接続は既に DTC に参加しています。 分散トランザクション接続に接続が登録され、SQL_ATTR_AUTOCOMMITを SQL_AUTOCOMMIT_OFF に設定してローカル トランザクションが開始されました。 |
| 3D000 | カタログ名が無効です | Attribute 引数がSQL_CURRENT_CATALOGされ、指定されたカタログ名が無効です。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY008 | 操作が取り消されました | ConnectionHandle に対して非同期処理が有効にされました。 SQLSetConnectAttr 関数が呼び出され、実行が完了する前に、ConnectionHandle で SQLCancelHandle 関数が呼び出され、ConnectionHandle で SQLSetConnectAttr 関数が再度呼び出されました。 または、SQLSetConnectAttr 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーション内の別のスレッドから ConnectionHandle で SQLCancelHandle が呼び出されました。 |
| HY009 | null ポインターの使用が無効です | Attribute 引数は文字列値を必要とする接続属性を識別し、ValuePtr 引数は null ポインターでした。 |
| HY010 | 関数シーケンス エラー | (DM) ConnectionHandle に関連付けられた StatementHandle に対して非同期実行関数が呼び出され、SQLSetConnectAttr が呼び出されたときにはまだ実行されていました。 (DM) 非同期実行関数 (この関数ではなく) が ConnectionHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) ConnectionHandle に関連付けられているステートメント ハンドルの 1 つに対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。 (DM) ConnectionHandle に関連付けられた StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATAが返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) ConnectionHandle に対して SQLBrowseConnect が呼び出され、SQL_NEED_DATAが返されました。 この関数は、 SQLBrowseConnect がSQL_SUCCESS_WITH_INFOまたはSQL_SUCCESSを返す前に呼び出されました。 |
| HY011 | 属性を今すぐ設定できない | Attribute 引数がSQL_ATTR_TXN_ISOLATIONされ、トランザクションが開かれていました。 |
| HY013 | メモリ管理エラー | メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY024 | 属性値が無効です | 指定した 属性値 を指定すると、 ValuePtr で無効な値が指定されました。 (ドライバー マネージャーは、SQL_ATTR_ACCESS_MODEやSQL_ATTR_ASYNC_ENABLEなどの個別の値のセットを受け入れる接続属性とステートメント属性に対してのみ、この SQLSTATE を返します。他のすべての接続属性とステートメント属性の場合、ドライバーは ValuePtr で指定された値を確認する必要があります)。 Attribute 引数がSQL_ATTR_TRACEFILEまたはSQL_ATTR_TRANSLATE_LIBで、ValuePtr が空の文字列でした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) *ValuePtr は文字列であり、 StringLength 引数は 0 未満でしたが、SQL_NTSされませんでした。 |
| HY092 | 無効な属性/オプション識別子 | (DM) 引数 Attribute に指定された値が、ドライバーでサポートされている ODBC のバージョンに対して無効でした。 (DM) 引数 Attribute に指定された値が読み取り専用属性でした。 |
| HY114 | ドライバーは、接続レベルの非同期関数の実行をサポートしていません | (DM) 非同期接続操作をサポートしていないドライバーに対して、SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLEを使用して非同期関数の実行を有効にしようとしました。 |
| HY117 | 不明なトランザクション状態が原因で接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HY121 | カーソル ライブラリとDriver-Awareプールを同時に有効にすることはできません | 詳細については、「 ドライバー対応接続プール」を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | 引数 Attribute に指定された値は、ドライバーでサポートされているバージョンの ODBC の有効な ODBC 接続またはステートメント属性でしたが、ドライバーではサポートされていませんでした。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) ConnectionHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
| IM009 | 翻訳 DLL を読み込むことができません | ドライバーは、接続に指定された変換 DLL を読み込めませんでした。 このエラーは、 Attribute がSQL_ATTR_TRANSLATE_LIBされている場合にのみ返されます。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルを使用するたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する以前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。 |
| S1118 | ドライバーは非同期通知をサポートしていません | SQL_ATTR_ASYNC_DBC_EVENTは (接続が確立された後に) 設定されましたが、非同期通知はドライバーでサポートされていません。 |
Attribute がステートメント属性の場合、SQLSetConnectAttr は SQLSetStmtAttr によって返されるすべての SQLSTATEs を返すことができます。
説明
接続属性の一般的な情報については、「 接続属性」を参照してください。
現在定義されている属性と、その属性が導入された ODBC のバージョンを、このセクションの後半の表に示します。さまざまなデータ ソースを利用するために、より多くの属性が定義されることが予想されます。 属性の範囲は ODBC によって予約されています。ドライバー開発者は、オープン グループから独自のドライバー固有の使用のために値を予約する必要があります。
Note
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* アプリケーションで動作する必要がある場合にのみ、この機能をサポートする必要があります。 詳細については、「付録 G: 下位互換性のためのドライバー ガイドライン」の 「SQLSetConnectOption マッピング 」を参照してください。
アプリケーションは、接続が割り当てられ解放される間、いつでも SQLSetConnectAttr を呼び出すことができます。 接続に対してアプリケーションによって正常に設定されたすべての接続属性とステートメント属性は、接続で SQLFreeHandle が呼び出されるまで保持されます。 たとえば、アプリケーションがデータ ソースに接続する前に SQLSetConnectAttr を呼び出した場合、アプリケーションがデータ ソースに接続するときに SQLSetConnectAttr がドライバーで失敗した場合でも、 属性は保持されます。アプリケーションがドライバー固有の属性を設定した場合、アプリケーションが接続上の別のドライバーに接続した場合でも、 属性は保持されます。
一部の接続属性は、接続が確立される前にのみ設定できます。他のユーザーは、接続が確立された後にのみ設定できます。 次の表は、接続が確立される前または後に設定する必要がある接続属性を示しています。 どちらの場合も 、接続前または接続後に属性を設定できることを示します。
| 属性 | 接続前または接続後に設定しますか? |
|---|---|
| SQL_ATTR_ACCESS_MODE | Either[1] |
| SQL_ATTR_ASYNC_DBC_EVENT | 接続前/接続後 |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE | Either[4] |
| SQL_ATTR_ASYNC_DBC_PCALLBACK | 接続前/接続後 |
| SQL_ATTR_ASYNC_DBC_PCONTEXT | 接続前/接続後 |
| SQL_ATTR_ASYNC_ENABLE | Either[2] |
| SQL_ATTR_AUTO_IPD | 接続前/接続後 |
| SQL_ATTR_AUTOCOMMIT | Either[5] |
| SQL_ATTR_CONNECTION_DEAD | クリック後 |
| SQL_ATTR_CONNECTION_TIMEOUT | 接続前/接続後 |
| SQL_ATTR_CURRENT_CATALOG | Either[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 | Either[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 を返します (オプション値が変更されました)。 たとえば、 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 バッファーに設定される情報の形式は、指定された 属性によって異なります。 SQLSetConnectAttr は、null で終わる文字列または整数値という 2 つの異なる形式の属性情報を受け入れます。 それぞれの形式は、属性の説明に記載されています。 SQLSetConnectAttr の ValuePtr 引数が指す文字列の長さは StringLength バイトです。
長さが属性によって定義されている場合、引数 StringLength は無視されます。ODBC 2*.x* 以前で導入されたすべての属性の場合と同様です。
| 属性 | 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 値。 詳細については、「 非同期実行 (ポーリング メソッド)」を参照してください。 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に設定されている場合にコミットされます。 詳細については、「 コミット モード」を参照してください。 大事な： 一部のデータ ソースは、アクセス プランを削除し、ステートメントがコミットされるたびに接続上のすべてのステートメントのカーソルを閉じます。autocommit モードを使用すると、クエリ以外の各ステートメントが実行された後、またはクエリのカーソルが閉じられたときに、このエラーが発生する可能性があります。 詳細については、「 SQLGetInfo 」のSQL_CURSOR_COMMIT_BEHAVIORおよびSQL_CURSOR_ROLLBACK_BEHAVIOR情報の種類と、 カーソルおよび準備されたステートメントに対するトランザクションの影響に関するページを参照してください。 バッチが自動コミット モードで実行される場合は、2 つのことが可能です。 バッチ全体を自動コミット可能な単位として扱うか、バッチ内の各ステートメントを自動コミット可能な単位として扱うことができます。 特定のデータ ソースでは、これらの両方の動作をサポートでき、どちらか一方を選択する方法が提供される場合があります。 これは、バッチが自動コミット可能な単位として扱われるかどうか、またはバッチ内の個々のステートメントが自動コミット可能かどうかに関係なく、ドライバーによって定義されます。 |
| SQL_ATTR_CONNECTION_DEAD (ODBC 3.5) |
接続の状態を示す読み取り専用 SQLUINTEGER 値。 SQL_CD_TRUE場合、接続は失われました。 SQL_CD_FALSE場合、接続は引き続きアクティブです。 |
| SQL_ATTR_CONNECTION_TIMEOUT (ODBC 3.0) | アプリケーションに戻る前に、接続の要求が完了するまで待機する秒数に対応する SQLUINTEGER 値。 ドライバーは、クエリの実行またはログインに関連付けられていない状況でタイムアウトになる可能性がある場合は、いつでも SQLSTATE HYT00 (タイムアウトの期限切れ) を返す必要があります。 ValuePtr が 0 (既定値) に等しい場合、タイムアウトはありません。 |
| SQL_ATTR_CURRENT_CATALOG (ODBC 2.0) | データ ソースで使用されるカタログの名前を含む文字列。 たとえば、SQL Serverでは、カタログはデータベースであるため、ドライバーは USEデータベース ステートメントをデータ ソースに送信します。ここで、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を返した場合、プールから取得した接続は解放されます。 ドライバー マネージャーは、プールから別の接続を取得しようとします。 詳細については、「 ODBC ドライバーでのConnection-Pool認識の開発 」を参照してください。 |
| SQL_ATTR_ENLIST_IN_DTC (ODBC 3.0) | Microsoft Component Services によって調整された分散トランザクションで ODBC ドライバーを使用するかどうかを指定する SQLPOINTER 値。 SQL Serverにエクスポートするトランザクションを指定する DTC OLE トランザクション オブジェクトを渡すか、接続の DTC 関連付けを終了するためにSQL_DTC_DONEします。 クライアントは、Microsoft 分散トランザクション コーディネーター (MS DTC) OLE ITransactionDispenser::BeginTransaction メソッドを呼び出して、MS DTC トランザクションを開始し、トランザクションを表す MS DTC トランザクション オブジェクトを作成します。 その後、アプリケーションは SQLSetConnectAttr を SQL_ATTR_ENLIST_IN_DTC オプションと共に呼び出して、トランザクション オブジェクトを ODBC 接続に関連付けます。 関連のあるすべてのデータベース操作は、MS DTC トランザクションで保護されます。 アプリケーションでは、SQL_DTC_DONE 値を指定して SQLSetConnectAttr を呼び出し、接続と DTC の関連付けを完了します。 詳細については、MS DTC のドキュメントを参照してください。 |
| SQL_ATTR_LOGIN_TIMEOUT (ODBC 1.0) | ログイン要求が完了するまでアプリケーションに戻るまでの秒数に対応する SQLUINTEGER 値。 既定値はドライバーに依存します。 ValuePtr が 0 の場合、タイムアウトは無効になり、接続試行は無期限に待機します。 指定したタイムアウトがデータ ソースの最大ログイン タイムアウトを超えた場合、ドライバーはその値を置き換え、SQLSTATE 01S02 を返します (オプション値が変更されました)。 |
| SQL_ATTR_METADATA_ID (ODBC 3.0) | カタログ関数の文字列引数の処理方法を決定する SQLUINTEGER 値。 SQL_TRUE場合、カタログ関数の文字列引数は識別子として扱われます。 このケースは重要ではありません。 削除されていない文字列の場合、ドライバーは末尾のスペースを削除し、文字列は大文字に折りたたまれます。 区切られた文字列の場合、ドライバーは先頭または末尾のスペースを削除し、区切り記号の間にあるものはすべてリテラルで受け取ります。 これらの引数のいずれかが null ポインターに設定されている場合、関数は SQL_ERROR と SQLSTATE HY009 を返します (null ポインターの使用が無効です)。 SQL_FALSE場合、カタログ関数の文字列引数は識別子として扱われません。 このケースは重要です。 引数に応じて、文字列検索パターンを含めることができます。 既定値は SQL_FALSE です。 値のリストを受け取る SQLTables の TableType 引数は、この属性の影響を受けられません。 SQL_ATTR_METADATA_IDは、ステートメント レベルで設定することもできます。 (ステートメント属性でもある唯一の接続属性です)。 詳細については、「 カタログ関数の引数」を参照してください。 |
| 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 カーソル ライブラリの詳細については、「 付録 F: ODBC カーソル ライブラリ」を参照してください。 警告： カーソル ライブラリは、今後のバージョンの Windows で削除される予定です。 新しい開発作業ではこの機能を使用しないでください。また、現在この機能を使用しているアプリケーションの変更を計画してください。 Microsoft では、ドライバーのカーソル機能を使用することをお勧めします。 |
| SQL_ATTR_PACKET_SIZE (ODBC 2.0) | ネットワーク パケット サイズをバイト単位で指定する SQLUINTEGER 値。 メモ： 多くのデータ ソースでは、このオプションがサポートされていないか、ネットワーク パケット サイズのみを返すことができますが、設定できません。 指定したサイズが最大パケット サイズを超えているか、最小パケット サイズより小さい場合、ドライバーはその値を置き換え、SQLSTATE 01S02 を返します (オプション値が変更されました)。 接続が既に行われた後にアプリケーションでパケット サイズが設定されている場合、ドライバーは SQLSTATE HY011 を返します (属性は現在設定できません)。 |
| 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 (トレース ファイル エラー) を返すことができます。 アプリケーションは、SQL_ATTR_TRACEFILE オプションを使用してトレース ファイルを指定します。 ファイルが既に存在する場合は、ドライバー マネージャーによってファイルが追加されます。 それ以外の場合は、ファイルが作成されます。 トレースがオンで、トレース ファイルが指定されていない場合、ドライバー マネージャーは SQL ファイルに書き込みます。ルート ディレクトリの LOG。 アプリケーションでは、変数 ODBCSharedTraceFlag を設定して、トレースを動的に有効にすることができます。 その後、現在実行中のすべての ODBC アプリケーションに対してトレースが有効になります。 アプリケーションがトレースをオフにすると、そのアプリケーションに対してのみオフになります。 アプリケーションで HandleType がSQL_HANDLE_ENVの SQLAllocHandle を呼び出すときに、システム情報の Trace キーワードが 1 に設定されている場合、トレースはすべてのハンドルに対して有効になります。 SQLAllocHandle を呼び出したアプリケーションに対してのみ有効になります。 属性が SQL_ATTR_TRACE の SQLSetConnectAttr を呼び出しても、ConnectionHandle 引数が有効である必要はありません。ConnectionHandle が NULL の場合、SQL_ERRORは返されません。 この属性は、すべての接続に適用されます。 |
| SQL_ATTR_TRACEFILE (ODBC 1.0) | トレース ファイルの名前を含む null で終わる文字列。 SQL_ATTR_TRACEFILE属性の既定値は、システム情報の TraceFile キーワードで指定されます。 詳細については、「 ODBC サブキー」を参照してください。 属性が SQL_ATTR_TRACEFILE の SQLSetConnectAttr を呼び出しても、ConnectionHandle 引数が有効である必要はありません。ConnectionHandle が無効な場合、SQL_ERRORは返されません。 この属性は、すべての接続に適用されます。 |
| SQL_ATTR_TRANSLATE_LIB (ODBC 1.0) | ドライバーが文字セット変換などのタスクを実行するためにアクセスする 関数 SQLDriverToDataSource および SQLDataSourceToDriver を含むライブラリの名前を含む null で終わる文字列。 このオプションは、ドライバーがデータ ソースに接続している場合にのみ指定できます。 この属性の設定は、接続間で保持されます。 データの変換の詳細については、「 翻訳 DLL」および「TranslationDLL 関数リファレンス」を参照してください。 |
| SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) | 変換 DLL に渡される 32 ビット フラグ値。 この属性は、ドライバーがデータ ソースに接続している場合にのみ指定できます。 データの変換の詳細については、「 翻訳 DLL」を参照してください。 |
| SQL_ATTR_TXN_ISOLATION (ODBC 1.0) | 現在の接続のトランザクション分離レベルを設定する 32 ビットビットマスク。 このオプションを使用して SQLSetConnectAttr を呼び出す前に、アプリケーションで SQLEndTran を呼び出して、接続で開いているすべてのトランザクションをコミットまたはロールバックする必要があります。 ValuePtr の有効な値は、InfoType が SQL_TXN_ISOLATION_OPTIONS と等しい SQLGetInfo を呼び出すことによって決定できます。 トランザクション分離レベルの説明については、「 SQLGetInfo 」および「 トランザクション分離レベル」のSQL_DEFAULT_TXN_ISOLATION情報の種類の説明を参照してください。 |
[1] これらの関数は、記述子が実装記述子であり、アプリケーション記述子ではない場合にのみ非同期的に呼び出すことができます。
コード例
「SQLConnect」を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| ハンドルの割り当て | SQLAllocHandle 関数 |
| 接続属性の設定を返す | SQLGetConnectAttr 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示