SQLGetConnectAttr() - 現行の属性設定値を取得する
SQLGetConnectAttr() は、接続属性の現行設定値を戻します。ユーザーはこれらの設定値を設定できます。
SQLGetConnectAttr() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 3.0 | あり | あり |
構文
SQLRETURN SQLGetConnectAttr (SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER *StringLengthPtr);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHDBC | ConnectionHandle | 入力 | そこから属性値を取り出す接続ハンドルを指定します。 |
| SQLINTEGER | 属性 | 入力 | 取り出す接続属性を指定します。 属性の完全なリストについては SQLSetConnectAttr() を参照してください。 |
| SQLPOINTER | ValuePtr | 入力 | 引数 Attribute が示す属性現行値の戻し先メモリーに対するポインターを指定します。
*ValuePtr は、32 ビットの符号なしの整数値、または NUL 終了文字ストリング です。Attribute 引数がドライバー固有値の場合は、*ValuePtr の値は 符号付き整数になる場合があります。 |
| SQLINTEGER | BufferLength | 入力 | 引数 *ValuePtr が指すバッファーの
サイズ (バイト) を指定します。この引数は、以下の属性のタイプによって、
動きが異なります。
|
| SQLINTEGER * | StringLengthPtr | 出力 | 引数 ValuePtr が必要とする合計バイト数 (NUL 終了文字を除く) を戻す先の
バッファーを指すポインターを指定します。以下の条件が、引数 StringLengthPtr に
適用されます。
|
使用法
SQLGetConnectAttr() を使用して、接続ハンドルで設定された接続属性の値を取り出します。
SQLSetConnectAttr() を使用してステートメント・ハンドルの属性値を設定することができますが、SQLGetConnectAttr() を使用してステートメント・ハンドルの現行の属性値を取り出すことはできません。ステートメントの属性値を取り出すには、SQLGetStmtAttr() を呼び出してください。
戻りコード
SQLGetConnectAttr() は、呼び出された後、次のいずれかの値を戻します。
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_NO_DATA
- SQL_INVALID_HANDLE
- SQL_ERROR
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01000 | 警告。 | 通知メッセージ。 (SQLGetConnectAttr() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 01004 | データが切り捨てられました。 | バッファー (引数 ValuePtr で指定) に戻されたデータは 、切り捨てられます。 データが切り捨てられる長さは、引数 BufferLength に指定された長さから、 NUL 終了文字の長さを引いた値に等しくなります。 引数 StringLengthPtr は、切り捨てられなかったストリング・サイズを受け取る バッファーを指定します。(SQLGetConnectAttr() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 08003 | 接続はクローズされています。 | 引数 Attribute は、オープン接続を必要とする値を 指定していますが、接続ハンドルは接続された状態にありませんでした。 |
| HY000 | 一般エラー。 | 具体的な SQLSTATE が存在しないエラーが起こりました。引数 MessageText が指定するバッファーに SQLGetDiagRec() が戻す エラー・メッセージに、このエラーとその原因が記述されています。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要な メモリーを割り振ることができません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 引数 BufferLength に指定された値は 0 より小さい値です。 |
| HY092 | オプションのタイプが範囲外です。 | 引数 Attribute に指定された値は、Db2 ODBC の このバージョンには有効ではありません。 |
| HYC00 | ドライバーは使用できません。 | 引数 Attribute に指定された値は 、Db2 ODBC のこのバージョンの接続属性またはステートメント属性として有効なものですが、 データ・ソースではサポートされていません。 |
例
次の例では、接続属性の現行設定値を印刷し
ます。SQLGetConnectAttr() は、SQL_ATTR_AUTOCOMMIT ステートメント属性の現行値を取り出します。
SQLINTEGER output_nts,autocommit;
rc = SQLGetConnectAttr( hdbc, SQL_AUTOCOMMIT,
&autocommit, 0, NULL ) ;
CHECK_HANDLE( SQL_HANDLE_DBC, hdbc, rc ) ;
printf( "¥nAutocommit is: " ) ;
if ( autocommit == SQL_AUTOCOMMIT_ON )
printf( "ON¥n" ) ;
else
printf( "OFF¥n" ) ;