適合 性
導入バージョン:ODBC 3.0 規格準拠:ISO 92
Summary
SQLGetConnectAttr は接続属性の現在の設定を返します。
Note
ODBC 3*.x*アプリケーションがODBC 2*.x*ドライバで動作する際に、ドライバーマネージャーがこの関数を何にマッピングするかの詳細については、「 アプリケーションの後方互換性のための置換機能マッピング」を参照してください。
構文
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
引数
ConnectionHandle
[入力] 接続ハンドル。
属性
[入力]取得する属性。
ValuePtr
[出力]属性 によって指定された属性の現在値を返すためのメモリへのポインタです。 整数型属性の場合、一部のドライバーはバッファの下位32ビットまたは16ビットのみを書き込み、高位ビットは変更しないことがあります。 したがって、アプリケーションはSQLulenのバッファを使用し、この関数を呼び出す前に値を0に初期化する必要があります。
ValuePtr が NULL の場合、StringLengthPtr は ValuePtr が指すバッファ内で返せる合計バイト数(文字データの null 終端文字を除く)を返します。
BufferLength
[入力] Attribute が ODBC で定義された属性で、 ValuePtr が文字列またはバイナリ バッファーを指している場合、この引数の長さは *ValuePtr にする必要があります。
AttributeがODBCで定義された属性で、*ValuePtr が整数の場合、BufferLengthは無視されます。
*ValuePtr の値が Unicode 文字列(SQLGetConnectAttrW 呼び出し時)の場合、BufferLength 引数は偶数でなければなりません。
Attributeがドライバー定義属性の場合、アプリケーションはBufferLength引数を設定してDriver Managerに属性の性質を示します。 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。
Diagnostics
SQLGetConnectAttrがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返すと、診断データ構造からSQLGetDiagRecを呼び出し、HandleTypeをSQL_HANDLE_DBC、HandleをConnectionHandleで呼び出すことで関連するSQLSTATE値を取得できます。 以下の表は 、通常SQLGetConnectAttr が返すSQLSTATE値を一覧にし、この関数の文脈でそれぞれを説明します。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。
| SQLSTATE | エラー | Description |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | *ValuePtr で返されるデータは、 BufferLength からヌル終端文字の長さを引いたものに短縮されていました。 切り詰められていない文字列の値の長さは *StringLengthPtrで返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 08003 | 接続が開かない | (DM) オープン接続を必要とする 属性 値が指定されました。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 診断データ構造からSQLGetDiagFieldのMessageText引数で返されるエラーメッセージは、エラーとその原因を記述します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。 |
| HY010 | 関数シーケンス エラー | (DM) SQLBrowseConnect が ConnectionHandle を呼び出し、返SQL_NEED_DATA。 この関数は SQLBrowseConnect がSQL_SUCCESS_WITH_INFOまたはSQL_SUCCESSを返す前に呼び出されました。 (DM) SQLExecute、 SQLExecDirect、または SQLMoreResults が ConnectionHandle に対して呼び出され、返SQL_PARAM_DATA_AVAILABLE。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) *ValuePtr は文字文字列であり、BufferLength はゼロ未満でしたが SQL_NTS に等しくはありませんでした。 |
| HY092 | 無効な属性/オプション識別子 | Attributeという引数に指定された値は、ドライバがサポートするODBCのバージョンでは有効ではありませんでした。 |
| HY114 | ドライバは接続レベルの非同期関数実行をサポートしていません | (DM) 非同期接続操作をサポートしないドライバに対して、アプリケーションが非同期関数実行をSQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLEで可能にしようと試みました。 |
| HY117 | 不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | Attribute引数に指定された値は、ドライバがサポートしているバージョンの有効なODBC接続属性でしたが、ドライバではサポートされていませんでした。 |
| HYT01 | 接続がタイムアウトしました | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) ConnectionHandle に対応するドライバーは、関数をサポートしていません。 |
Comments
接続属性に関する一般的な情報については、 Connection Attributesをご覧ください。
設定可能な属性のリストについては、 SQLSetConnectAttrを参照してください。 Attributeが文字列を返す属性を指定する場合、ValuePtrはその文字列のバッファへのポインタでなければなりません。 返される文字列の最大長(null終端文字を含む)は BufferLength バイトとなります。
属性によっては、アプリケーションは SQLGetConnectAttrを呼び出す前に接続を確立する必要はありません。 しかし、 SQLGetConnectAttr が呼び出され、指定された属性にデフォルトがなく、かつ SQLSetConnectAttrへの事前呼び出しで設定されていない場合、 SQLGetConnectAttr はSQL_NO_DATAを返します。
AttributeがTRACEまたはSQL_ATTR_TRACEFILE 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 関数 |