SQLGetConnectAttr -- 接続属性の現行設定の取得

目的

仕様:

DB2 CLI 5.0

ODBC 3.0

ISO CLI

SQLGetConnectAttr() は接続属性の現行の設定を戻します。

構文

SQLRETURN   SQLGetConnectAttr(SQLHDBC           ConnectionHandle,
                              SQLINTEGER        Attribute,
                              SQLPOINTER        ValuePtr,
                              SQLINTEGER        BufferLength,
                              SQLINTEGER        *StringLengthPtr);

関数の引き数

表 87. SQLGetConnectAttr の引き数

データ・タイプ	引き数	用途	説明
SQLHDBC	`ConnectionHandle`	入力	接続ハンドル。
SQLINTEGER	`Attribute`	入力	取り出す属性。
SQLPOINTER	`ValuePtr`	出力	`Attribute` に指定された属性の現在値を戻すメモリーへのポインター。
SQLINTEGER	`BufferLength`	入力	`ValuePtr` が文字ストリングを指している場合は、この引き数は `ValuePtr` の長さでなければならない。 `ValuePtr` はポインターであるが、ストリングを指していない場合は、`BufferLength` の値は `SQL_IS_POINTER` でなければならない。 `ValuePtr` の値がユニコード・ストリングである場合は、`BufferLength` 引き数は偶数でなければならない。
SQLINTEGER *	`StringLengthPtr`	出力	`ValuePtr` に戻す際に使用できる合計バイト数 (ヌル終了文字を除く) を戻すバッファーを指すポインター。 `ValuePtr` がヌル・ポインターである場合、長さは戻されない。属性値が文字ストリングであり、かつ、戻り時に使用できるバイト数が `BufferLength` からヌル終了文字の長さを引いた値より大きい場合、 `ValuePtr` 内のデータは `BufferLength` からヌル終了文字の長さを引いた値に切り捨てられ、DB2 CLI によってヌル終了される。

使用法

SQLGetConnectAttr() の呼び出しでは、Attribute に指定した接続属性の値が *ValuePtr に戻されます。DB2 Everyplace ではこの値は 32 ビット値になり、BufferLength および StringLengthPtr 引き数は使用されません。

SQLGetConnectAttr() によって、以下の接続属性を検索することができます。これらの属性については、『SQLSetConnectAttr -- 接続に関するオプションの設定』を参照してください。

SQL_ATTR_AUTOCOMMIT (DB2 CLI/ODBC)
SQL_ATTR_CONNECTION_DEAD (DB2 CLI/ODBC)
SQL_ATTR_LOGIN_TIMEOUT (DB2 CLI/ODBC)
SQL_ATTR_FILENAME_FORMAT (DB2 Everyplace)

属性によっては、SQLGetConnectAttr() の呼び出し前にアプリケーションで接続を確立する必要がないことがあります。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_ERROR
SQL_INVALID_HANDLE

診断

表 88. SQLGetConnectAttr SQLSTATEs

SQLSTATE	説明	解説
01000	警告。	通知メッセージ。(関数は、SQL_SUCCESS_WITH_INFO を戻す。)
01004	データが切り捨てられた。	`ValuePtr` に戻されたデータは、`BufferLength` からヌル終了文字を引いた値になるように切り捨てられた。切り捨てられていないストリング値の長さが `StringLengthPtr` に戻される。(関数は、SQL_SUCCESS_WITH_INFO を戻す。)
08003	接続がクローズしている。	オープン接続を必要とする `Attribute` 値が指定された。
HY000	一般エラー。	特定の SQLSTATE が何も存在しないエラーが発生した。`SQLGetDiagRec`() が `*MessageText` バッファーに戻したエラー・メッセージが、そのエラーと原因を示す。
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数を実行または完了させるのに必要なメモリーを割り当てることができない。アプリケーション・プロセスのプロセス・レベル・メモリーが使い尽くされた可能性がある。オペレーティング・システムの構成を調べて、プロセス・レベル・メモリーの制限に関する情報を入手すること。
HY090	無効なストリング長またはバッファー長。	引き数 `BufferLength` に指定した値が 0 より小さい。
HY092	オプション・タイプが範囲外。	引き数 `Attribute` に指定した値が無効である。
HYC00	ドライバーが使用不可である。	引き数 Attribute に指定した値は、DB2 CLI ドライバーのバージョンに対しては有効な接続属性かステートメント属性であるが、データ・ソースでサポートされていない。

制約事項

なし。

関連した解説

SQLSetConnectAttr -- 接続に関するオプションの設定