SQLGetConnectAttr 関数
準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92
まとめ
SQLGetConnectAttr は 、接続属性の現在の設定を返します。
Note
ODBC 3*.x* アプリケーションが ODBC 2*.x* ドライバーを操作している場合にドライバー マネージャーによってこの関数がマップされる内容の詳細については、「 アプリケーションの下位互換性のための置換関数のマッピング」を参照してください。
構文
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
引数
ConnectionHandle
[入力] 接続ハンドル。
属性
[入力]取得する属性。
ValuePtr
[出力] Attribute で指定された属性の現在の値を返すメモリへのポインター。 整数型の属性の場合、一部のドライバーでは、バッファーの下位 32 ビットまたは 16 ビットのみを書き込み、上位ビットを変更しない場合があります。 そのため、アプリケーションでは SQLULEN のバッファーを使用し、この関数を呼び出す前に値を 0 に初期化する必要があります。
ValuePtr が NULL の場合でも、StringLengthPtr は、ValuePtr が指すバッファーで返すために使用できるバイトの合計数 (文字データの null 終端文字を除く) を返します。
BufferLength
[入力] Attribute が ODBC 定義の属性で 、ValuePtr が文字列またはバイナリ バッファーを指している場合、この引数は *ValuePtr の長さである必要があります。 Attribute が ODBC 定義の属性で、*ValuePtr が整数の場合、BufferLength は無視されます。 *ValuePtr の値が Unicode 文字列の場合 (SQLGetConnectAttrW を呼び出すとき)、BufferLength 引数は偶数である必要があります。
Attribute がドライバー定義の属性の場合、アプリケーションは BufferLength 引数を設定して、ドライバー マネージャーに属性の性質を示します。 BufferLength には、次の値を指定できます。
*ValuePtr が文字列へのポインターである場合、BufferLength は文字列の長さです。
*ValuePtr がバイナリ バッファーへのポインターである場合、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を BufferLength に配置します。 これにより 、BufferLength に負の値が配置されます。
*ValuePtr が文字列またはバイナリ文字列以外の値へのポインターである場合、BufferLength の値はSQL_IS_POINTER。
*ValuePtr に固定長データ型が含まれている場合、BufferLength は必要に応じてSQL_IS_INTEGERまたはSQL_IS_UINTEGERのいずれかになります。
StringLengthPtr
[出力]*ValuePtr で返すために使用できるバイトの合計数 (null 終了文字を除く) を返すバッファーへのポインター。 属性値が文字列で、返されるバイト数が BufferLength から null 終端文字の長さを差し引いた値より大きい場合、 *ValuePtr のデータは BufferLength から null 終端文字の長さを引いた値に切り捨てられ、ドライバーによって null で終了されます。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLGetConnectAttr がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値は、SQL_HANDLE_DBC の Handle とConnectionHandle の Handle を使用して SQLGetDiagRec を呼び出すことによって、診断データ構造から取得できます。 次の表に、 SQLGetConnectAttr によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | *ValuePtr で返されたデータは、 BufferLength から null 終端文字の長さを差し引いた値に切り捨てられました。 * StringLengthPtr では、文字列値の長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 08003 | 接続が開かない | (DM) 開いている接続を必要とする 属性値 が指定されました。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されているデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 SQLGetDiagField の引数 MessageText によって診断データ構造から返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY010 | 関数シーケンス エラー | (DM) ConnectionHandle に対して SQLBrowseConnect が呼び出され、SQL_NEED_DATAが返されました。 この関数は、 SQLBrowseConnect がSQL_SUCCESS_WITH_INFOまたはSQL_SUCCESSを返す前に呼び出されました。 (DM) ConnectionHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) *ValuePtr は文字列であり、BufferLength は 0 未満ですが、SQL_NTSと等しくありません。 |
| HY092 | 属性/オプション識別子が無効です | 引数 Attribute に指定された値が、ドライバーでサポートされている ODBC のバージョンでは無効でした。 |
| HY114 | ドライバーは、接続レベルの非同期関数の実行をサポートしていません | (DM) 非同期接続操作をサポートしていないドライバーに対して、SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLEを使用して非同期関数の実行を有効にしようとしたアプリケーション。 |
| HY117 | トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | 引数 Attribute に指定された値は、ドライバーでサポートされている ODBC のバージョンに対して有効な ODBC 接続属性でしたが、ドライバーではサポートされていませんでした。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) ConnectionHandle に対応するドライバーは、 関数をサポートしていません。 |
説明
接続属性の一般的な情報については、「 接続属性」を参照してください。
設定できる属性の一覧については、「 SQLSetConnectAttr」を参照してください。 Attribute が文字列を返す属性を指定する場合、ValuePtr は文字列のバッファーへのポインターである必要があることに注意してください。 null 終端文字を含む、返される文字列の最大長は BufferLength バイトになります。
属性によっては、 SQLGetConnectAttr を呼び出す前にアプリケーションで接続を確立する必要はありません。 ただし、 SQLGetConnectAttr が呼び出され、指定された属性に既定値が設定されておらず、 SQLSetConnectAttr の以前の呼び出しによって設定されていない場合、 SQLGetConnectAttr はSQL_NO_DATAを返します。
属性が TRACE または TRACEFILE SQL_ATTR_SQL_ATTR_場合、ConnectionHandle は有効である必要はありません。ConnectionHandle が無効な場合、SQLGetConnectAttr はSQL_ERRORまたはSQL_INVALID_HANDLEを返しません。 これらの属性は、すべての接続に適用されます。 SQLGetConnectAttr は、別の引数が無効な場合、SQL_ERRORまたはSQL_INVALID_HANDLEを返します。
アプリケーションでは SQLSetConnectAttr を使用してステートメント属性を設定できますが、 SQLGetConnectAttr を使用してステートメント属性値を取得することはできません。ステートメント属性の設定を取得するには、 SQLGetStmtAttr を呼び出す必要があります。
SQL_ATTR_AUTO_IPDとSQL_ATTR_CONNECTION_DEADの両方の接続属性は 、SQLGetConnectAttr の呼び出しによって返されますが、 SQLSetConnectAttr の呼び出しでは設定できません。
Note
SQLGetConnectAttr の非同期サポートはありません。 SQLGetConnectAttr を実装する場合、ドライバーは、情報がサーバーから送信または要求される回数を最小限に抑えることによって、パフォーマンスを向上させることができます。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| ステートメント属性の設定を返す | SQLGetStmtAttr 関数 |
| 接続属性の設定 | SQLSetConnectAttr 関数 |
| 環境属性の設定 | SQLSetEnvAttr 関数 |
| ステートメント属性の設定 | SQLSetStmtAttr 関数 |