SQLSetConnectAttr 関数
準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: 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 値は、HandleType SQL_HANDLE_DBC の HandleType とConnectionHandle 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) 開いている接続を必要とする Attribute 値が指定されましたが、 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 関数が呼び出され、SQLSetConnectAttr 関数が ConnectionHandle で再度呼び出されました。 または、 SQLSetConnectAttr 関数が呼び出され、実行が完了する前に、 SQLCancelHandle がマルチスレッド アプリケーションの別のスレッドから ConnectionHandle で呼び出されました。 |
| HY009 | null ポインターの使用が無効です | Attribute引数は文字列値を必要とする接続属性を識別し、ValuePtr 引数は null ポインターでした。 |
| HY010 | 関数シーケンス エラー | (DM) 非同期実行関数が、ConnectionHandle に関連付けられた StatementHandle に対して呼び出され、SQLSetConnectAttr が呼び出されたときにまだ実行されていました。 (DM) 非同期実行関数 (この関数ではない) が ConnectionHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) SQLExecute、 SQLExecDirect、または SQLMoreResults ConnectionHandle に関連付けられているステートメント ハンドルの 1 つに対して呼び出され、SQL_PARAM_DATA_AVAILABLEが返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 (DM) SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos ConnectionHandle に関連付けられた StatementHandle が呼び出され、SQL_NEED_DATAが返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) SQLBrowseConnect が ConnectionHandle に対して呼び出され、SQL_NEED_DATA返されました。 この関数は、 SQLBrowseConnect SQL_SUCCESS_WITH_INFOまたはSQL_SUCCESSを返す前に呼び出されました。 |
| HY011 | 現在、属性を設定できません | Attribute引数がSQL_ATTR_TXN_ISOLATIONされ、トランザクションが開かれていました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY024 | 属性値が無効です | 指定した Attribute 値を指定すると、 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 | カーソル ライブラリとドライバー対応プールを同時に有効にすることはできません | 詳細については、「ドライバー対応接続プール」に関するページを参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | 引数 Attribute に指定された値は、ドライバーでサポートされている ODBC のバージョンの有効な ODBC 接続またはステートメント属性でしたが、ドライバーではサポートされていませんでした。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr によって設定されます。 |
| 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 を返すことができます。
Comments
接続属性の一般的な情報については、「 Connection 属性」を参照してください。
現在定義されている属性と、その属性が導入された ODBC のバージョンを、このセクションの後半の表に示します。さまざまなデータ ソースを利用するために、より多くの属性が定義されることが予想されます。 属性の範囲は ODBC によって予約されています。ドライバー開発者は、オープン グループから独自のドライバー固有の使用のために値を予約する必要があります。
Note
ODBC 3*.x* では、 SQLSetConnectAttr を呼び出してステートメント属性を接続レベルで設定する機能が非推奨になりました。 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 がドライバーで失敗しても属性は保持されます。アプリケーションがドライバー固有の属性を設定した場合、アプリケーションが接続上の別のドライバーに接続した場合でも、属性は保持されます。
一部の接続属性は、接続が確立される前にのみ設定できます。他のユーザーは、接続が確立された後にのみ設定できます。 次の表は、接続が確立される前または後に設定する必要がある接続属性を示しています。 いずれか は、接続の前または後に属性を設定できることを示します。
| Attribute | 接続前または接続後に設定しますか? |
|---|---|
| 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 を返します (オプション値が変更されました)。 たとえば、 Attribute がSQL_ATTR_PACKET_SIZEされ、*ValuePtr が最大パケット サイズを超えている場合、ドライバーは最大サイズに置き換えられます。 置換された値を特定するために、アプリケーションは SQLGetConnectAttr を呼び出します。
接続が開く前にSQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLEが設定されている場合、ドライバー マネージャーは、 SQLBrowseConnect、 SQLConnect、または SQLDriverConnect の呼び出し中にドライバーが読み込まれるときにドライバーの属性を設定します。 SQLBrowseConnect、SQLConnect、または SQLDriverConnect を呼び出す前に、ドライバー マネージャーは接続先のドライバーを認識せず、ドライバーが非同期接続操作をサポートしているかどうかはわかりません。 したがって、ドライバー マネージャーは常にSQL_SUCCESSを返します。 ただし、ドライバーが非同期接続操作をサポートしていない場合、 SQLBrowseConnect、 SQLConnect、または SQLDriverConnect の呼び出しは失敗します。
[5] SQL_ATTR_AUTOCOMMITが FALSE に設定されている場合、アプリケーションは SQLEndTran(SQL_ROLLBACK) を呼び出す必要があります(トランザクションの一貫性を確保するために API がSQL_ERRORを返す場合)。
*ValuePtr バッファーに設定された情報の形式は、指定した Attributeによって異なります。 SQLSetConnectAttr は、null で終わる文字列または整数値という 2 つの異なる形式のいずれかで属性情報を受け入れます。 それぞれの形式は属性の説明に記載されています。 SQLSetConnectAttr の ValuePtr 引数が指す文字列の長さはStringLength バイトです。
ODBC 2*.x* 以前で導入されたすべての属性の場合と同様に、属性によって長さが定義されている場合、 StringLength 引数は無視されます。
| 属性 | 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に設定され、手動コミット モードから自動コミット モードに変更されると、接続で開いているトランザクションはすべてコミットされます。 詳細については、「 コミット モード」を参照してください。 重要: 一部のデータ ソースでは、ステートメントがコミットされるたびにアクセス プランを削除し、接続上のすべてのステートメントのカーソルを閉じます。自動コミット モードでは、各非クエリ ステートメントが実行された後、またはクエリに対してカーソルが閉じられたときに、これが発生する可能性があります。 詳細については、 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 ステートメントを送信します。ここで、 database は *ValuePtr で指定されたデータベースです。 単一層ドライバーの場合、カタログはディレクトリである可能性があるため、ドライバーは現在のディレクトリを *ValuePtr で指定されたディレクトリに変更します。 |
| SQL_ATTR_DBC_INFO_TOKEN (ODBC 3.8) | SQL_ATTR_DBC_INFO_TOKENはセット専用です。 SQL_ATTR_DBC_INFO_TOKEN設定後にドライバーからSQL_ERRORが返された場合、プールから取得した接続は解放されます。 ドライバー マネージャーは、プールから別の接続を取得しようとします。 詳細については、「 ODBC ドライバーでの接続プール認識のデベロピング を参照してください。 |
| 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 トランザクションで保護されます。 アプリケーションは、接続の DTC 関連付けを終了するために、SQL_DTC_DONEで SQLSetConnectAttr を呼び出します。 詳細については、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 カーソル ライブラリの詳細については、「 Appendix 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 に書き込みます。ルート ディレクトリにログインします。 アプリケーションは、変数 ODBCSharedTraceFlag を設定して、トレースを動的に有効にすることができます。 その後、現在実行中のすべての ODBC アプリケーションに対してトレースが有効になります。 アプリケーションがトレースをオフにした場合、そのアプリケーションに対してのみ無効になります。 アプリケーションが SQL_HANDLE_ENV の HandleType で SQLAllocHandle を呼び出したときに、システム情報の Trace キーワードが 1 に設定されている場合、トレースはすべてのハンドルに対して有効になります。 これは、 SQLAllocHandle を呼び出したアプリケーションに対してのみ有効になります。 SQL_ATTR_TRACEの Attribute でSQLSetConnectAttrを呼び出す場合、ConnectionHandle 引数が有効である必要はありません。また、ConnectionHandle が NULL の場合はSQL_ERRORを返しません。 この属性は、すべての接続に適用されます。 |
| SQL_ATTR_TRACEFILE (ODBC 1.0) | トレース ファイルの名前を含む null で終わる文字列。 SQL_ATTR_TRACEFILE属性の既定値は、システム情報の TraceFile キーワードで指定されます。 詳細については、 ODBC サブキーを参照してください。 SQL_ATTR_TRACEFILEの Attribute でSQLSetConnectAttrを呼び出す場合、ConnectionHandle 引数は有効である必要はありません。また、ConnectionHandle が無効な場合はSQL_ERRORを返しません。 この属性は、すべての接続に適用されます。 |
| SQL_ATTR_TRANSLATE_LIB (ODBC 1.0) | ドライバーが文字セット変換などのタスクを実行するためにアクセスする関数 SQLDriverToDataSource および SQLDataSourceToDriver を含むライブラリの名前を含む null で終わる文字列。 このオプションは、ドライバーがデータ ソースに接続されている場合にのみ指定できます。 この属性の設定は、接続間で保持されます。 データの変換の詳細については、「 Translation DLL および Translation DLL 関数リファレンスを参照してください。 |
| SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) | 変換 DLL に渡される 32 ビット フラグ値。 この属性は、ドライバーがデータ ソースに接続している場合にのみ指定できます。 データの変換の詳細については、「 変換 DLLを参照してください。 |
| SQL_ATTR_TXN_ISOLATION (ODBC 1.0) | 現在の接続のトランザクション分離レベルを設定する 32 ビット ビットマスク。 アプリケーションは、 SQLEndTran を呼び出して、接続で開いているすべてのトランザクションをコミットまたはロールバックしてから、このオプションで SQLSetConnectAttr を呼び出す必要があります。 ValuePtr の有効な値は、SQLGetInfo InfoType SQL_TXN_ISOLATION_OPTIONS を呼び出すことによって決定できます。 トランザクション分離レベルの説明については、「 SQLGetInfo および Transaction 分離レベルのSQL_DEFAULT_TXN_ISOLATION情報の種類の説明を参照してください。 |
[1] これらの関数は、記述子が実装記述子であり、アプリケーション記述子ではない場合にのみ非同期的に呼び出すことができます。
コード例
「 SQLConnect」を参照してください。
関連する関数
| 情報 | 参照トピック |
|---|---|
| ハンドルの割り当て | SQLAllocHandle 関数 |
| 接続属性の設定を返す | SQLGetConnectAttr 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示