SQLGetConnectAttr() - 現行の属性設定値を取得する

SQLGetConnectAttr() は、接続属性の現行設定値を戻します。ユーザーはこれらの設定値を設定できます。

SQLGetConnectAttr() の ODBC 仕様

表 1. SQLGetConnectAttr() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
3.0 あり あり

構文

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

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLGetConnectAttr() の引数
データ・タイプ 引数 使用法 説明
SQLHDBC ConnectionHandle 入力 そこから属性値を取り出す接続ハンドルを指定します。
SQLINTEGER 属性 入力 取り出す接続属性を指定します。 属性の完全なリストについては SQLSetConnectAttr() を参照してください。
SQLPOINTER ValuePtr 入力 引数 Attribute が示す属性現行値の戻し先メモリーに対するポインターを指定します。

*ValuePtr は、32 ビットの符号なしの整数値、または NUL 終了文字ストリング です。Attribute 引数がドライバー固有値の場合は、*ValuePtr の値は 符号付き整数になる場合があります。

SQLINTEGER BufferLength 入力 引数 *ValuePtr が指すバッファーの サイズ (バイト) を指定します。この引数は、以下の属性のタイプによって、 動きが異なります。
  • ODBC が定義した属性の場合
    • ValuePtr が文字ストリングを指す場合、 この引数は *ValuePtr の長さにする必要があります。
    • ValuePtr が整数を指す場合、BufferLength は無視されます。
  • ドライバーが定義する属性 (IBM® 拡張) の場合
    • ValuePtr が文字ストリングを指す場合、 この引数は *ValuePtr または SQL_NTS の長さ (バイト) にする必要があり ます。SQL_NTS の場合、ドライバーは *ValuePtr の 長さが SQL_MAX_OPTIONS_STRING_LENGTH バイト (NUL 終止符を除く) であると想定します。
    • ValuePtr が整数を指す場合、BufferLength は無視されます。
SQLINTEGER * StringLengthPtr 出力 引数 ValuePtr が必要とする合計バイト数 (NUL 終了文字を除く) を戻す先の バッファーを指すポインターを指定します。以下の条件が、引数 StringLengthPtr に 適用されます。
  • ValuePtr が NULL ポインターの場合、長さは戻されません。
  • 属性値が文字ストリングであり、さらに戻すのに使用可能なバイト数が引数 BufferLength で 指定された値以上の場合は、ValuePtr のデータは指定された値から NUL 終止文字を引いた長さに 切り捨てられます。Db2® ODBC は、切り捨てたデータを NUL 終了します。
  • 引数 Attribute が、あるストリングを示していない場合、Db2 ODBC は、 引数 BufferLength を無視し、引数 StringLengthPtr が指している バッファーに値を戻しません。

使用法

SQLGetConnectAttr() を使用して、接続ハンドルで設定された接続属性の値を取り出します。

SQLSetConnectAttr() を使用してステートメント・ハンドルの属性値を設定することができますが、SQLGetConnectAttr() を使用してステートメント・ハンドルの現行の属性値を取り出すことはできません。ステートメントの属性値を取り出すには、SQLGetStmtAttr() を呼び出してください。

戻りコード

SQLGetConnectAttr() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_NO_DATA
  • SQL_INVALID_HANDLE
  • SQL_ERROR

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLGetConnectAttr() の 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" ) ;