CLI の手引きおよび解説書

SQLGetConnectAttr - 現行属性設定を入手する

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLGetConnectAttr() は、接続属性の現在の設定を返します。

構文

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

関数引き数

表 90. SQLGetConnectAttr 引き数
データ・タイプ 引き数 使用法 説明
SQLHDBC ConnectionHandle 入力 接続ハンドル。
SQLINTEGER 属性 入力 取り出す属性
SQLPOINTER ValuePtr 出力 属性 によって指定されている属性の現行値を返すメモリーを指すポインター。
SQLINTEGER BufferLength 入力
  • ValuePtr が文字ストリングを指す場合、この引き数の長さは *ValuePtr になります。
  • ValuePtr がポインターであるが、ストリングではない場合、BufferLength の値は SQL_IS_POINTER になります。
  • ValuePtr がポインターではない場合、 BufferLength の値は SQL_IS_NOT_POINTER になります。
  • *ValuePtr の値が Unicode ストリングである場合、 BufferLength 引き数は偶数でなければなりません。

SQLINTEGER *StringLengthPtr 出力 *ValuePtr 内に戻すために使用できる総バイト数 (ヌル終了文字を除く) を戻すバッファーを指すポインター。 ValuePtr がヌル・ポインターである場合、長さは戻されません。属性値が文字ストリングであり、返すことが可能なバイトの数が BufferLength からヌル終了文字の長さを引いたものより大きい場合、 *ValuePtr の値は、 BufferLength からヌル終了文字の長さを引いたものに切り捨てられ、これは DB2 CLI によってヌル終了になります。

使用法

設定可能な属性のリストについては、SQLSetConnectAttr - 接続属性を設定するを参照してください。 属性 がストリングを返す属性を指定する場合、ValuePtr は、そのストリングのバッファーを指すポインターでなければなりません。ヌル終了文字を含むストリングの最大長は、BufferLength バイトになります。

属性によっては、SQLGetConnectAttr() を呼び出す前に接続を構築する必要のないアプリケーションがあります。しかし、SQLGetConnectAttr() が呼び出され、指定した属性に省略時値がなく、 SQLSetConnectAttr() より前の呼び出しによって設定されていない場合は、 SQLGetConnectAttr() は SQL_NO_DATA を返します。

属性が SQL_ATTR_TRACE であるか、または SQL_ATTR_TRACEFILE である場合、 ConnectionHandle は有効である必要はなく、 ConnectionHandle が無効である場合、 SQLGetConnectAttr() は SQL_ERROR を返すことはありません。これらの属性は、すべての接続に適用されます。別の引き数が無効である場合、SQLGetConnectAttr() は SQL_ERROR を返します。

アプリケーションが SQLSetConnectAttr() を使用してステートメント属性を設定できるときに、アプリケーションはステートメント属性値を取り出すために SQLGetConnectAttr() を使用することはできません。ステートメント属性の設定を取り出すには、SQLGetStmtAttr() を呼び出さなければなりません。

SQL_ATTR_AUTO_IPD 接続属性は、SQLGetConnectAttr() の呼び出しによって返されますが、 SQLSetConnectAttr() の呼び出しによって設定することはできません。

戻りコード

診断

表 91. SQLGetConnectAttr SQLSTATE
SQLSTATE 説明 解説
01000 警告。 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
01004 データが切り捨てられました。 *ValuePtr に戻されるデータは、 BufferLength からヌル終了文字の長さを引いた長さに切り捨てられます。 *StringLengthPtr には、切り捨て前のストリング値の長さが戻されます。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
08003 接続がクローズされています。 オープン接続が必要な Attribute 値を指定しました。
HY000 一般的なエラーです。 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。
HY010 関数の順序エラーです。 ConnectionHandleSQLBrowseConnect() が呼び出され、 SQL_NEED_DATA が戻されました。この関数は、SQLBrowseConnect() が SQL_SUCCESS_WITH_INFO または SQL_SUCCESS を戻す前に呼び出されました。
HY090 ストリングまたはバッファー長が無効です。 引き数 BufferLength に指定された値は、0 より小さい値でした。
HY092 オプション・タイプが範囲外です。 引き数 Attribute に指定された値は、無効でした。
HYC00 ドライバーが機能していません。 引き数 Attribute に指定された値は、このバージョンの DB2 CLI ドライバーには有効な接続またはステートメント属性でしたが、データ・ソースによりサポートされていませんでした。

制約

なし。

CLI サンプル dbinfo.c

(ここで完全サンプル dbinfo.c を使用することもできます 。)

/* From the CLI sample DBINFO.C */
/* ... */
    sqlrc = SQLGetConnectAttr( hdbc, SQL_AUTOCOMMIT, &autocommit, 0, NULL ) ;
    HANDLE_CHECK( SQL_HANDLE_DBC, hdbc, sqlrc, &henv, &hdbc ) ;
    printf("\n    A connection attribute...\n");
    printf( "        Autocommit is: " ) ;
    if ( autocommit == SQL_AUTOCOMMIT_ON ) printf( "ON\n" ) ;
    else printf( "OFF\n" ) ;
 
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]