CLI の手引きおよび解説書

SQLGetStmtAttr - ステートメント属性の現行設定値を入手する

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLGetStmtAttr() は、ステートメント属性の現行設定値を戻します。

構文

SQLRETURN   SQLGetStmtAttr   (SQLHSTMT          StatementHandle,
                              SQLINTEGER        Attribute,
                              SQLPOINTER        ValuePtr,
                              SQLINTEGER        BufferLength,
                              SQLINTEGER        *StringLengthPtr);

関数引き数

表 118. SQLGetStmtAttr 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLINTEGER Attribute 入力 取り出す属性。
SQLPOINTER ValuePtr 出力 Attribute に指定されている属性値を戻すバッファーを指すポインター。
SQLINTEGER BufferLength 入力 Attribute が ODBC 定義の属性で、 ValuePtr が文字ストリングか 2 進バッファーを指している場合、この引き数の長さは *ValuePtr の長さにする必要があります。 Attribute が ODBC 定義の属性で、 *ValuePtr が整数の場合、 BufferLength は無視されます。

Attribute が DB2 CLI 属性の場合、アプリケーションは BufferLength 引き数を設定して、その属性の性質を示します。 BufferLength には次の値が有効です。

  • *ValuePtr が文字ストリングを指すポインターの場合、 BufferLength はストリングまたは SQL_NTS の長さです。
  • *ValuePtr が 2 進バッファーを指すポインターの場合、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を BufferLength に入れます。 BufferLength には負の値が入れられます。
  • *ValuePtr が文字ストリングまたは 2 進ストリング以外の値を指すポインターの場合、 BufferLength の値は SQL_IS_POINTER でなければなりません。
  • *ValuePtr に固定長のデータ・タイプが入っている場合、 BufferLength は SQL_IS_INTEGER か SQL_IS_UINTEGER (どちらか適切な方) になります。
SQLSMALLINT *StringLengthPtr 出力 *ValuePtr に戻すために使用できる総バイト数 (ヌル終了文字を除く) を戻すバッファーを指すポインター。このポインターがヌル・ポインターの場合、長さは戻されません。属性値が文字ストリングで、戻りに使用できるバイト数が BufferLength 以上の場合、 *ValuePtrBufferLength からヌル終了文字の長さを引いた長さまで切り捨てられ、 DB2 CLI がヌル文字で終了させます。

使用法

SQLGetStmtAttr() を呼び出すと *ValuePtr に、 Attribute に指定されているステートメント属性の値が戻されます。この値は、32 ビット値またはヌル文字で終了する文字ストリングのどちらかです。この値がヌル文字で終了するストリングの場合、アプリケーションは BufferLength 引き数にそのストリングの最大長を指定し、 DB2 CLI は *StringLengthPtrPtr バッファーにそのストリングの長さを戻します。この値が 32 ビット値である場合、 BufferLength 引き数と StringLengthPtr 引き数は使用されません。

SQLGetStmtAttr() を呼び出す DB2 CLI バージョン 5.2 アプリケーションを DB2 CLI バージョン 2 と一緒に使用して作業できるようにするため、 SQLGetStmtAttr() への呼び出しが SQLGetStmtOption() にマップされます。

次の引き数属性は読み取り専用なので、 SQLGetStmtAttr() で取り出しできますが、 SQLSetStmtAttr() で設定はできません。設定および検索できる属性のリストについては、 SQLSetStmtAttr - ステートメントに関連したオプションの設定を参照してください。

戻りコード

診断

表 119. SQLGetStmtAttr SQLSTATE
SQLSTATE 説明 解説
01000 警告。 通知メッセージです。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
01004 データが切り捨てられました。 *ValuePtr に戻されるデータは、 BufferLength からヌル終了文字の長さを引いた長さに切り捨てられます。 *StringLengthPtr には、切り捨て前のストリング値の長さが戻されます。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
24000 カーソル状態が無効です。 引き数 Attribute が SQL_ATTR_ROW_NUMBER で、カーソルがオープンされていたか、カーソルが結果セットの開始点の前または終了点の後ろに配置されていました。
HY000 一般的なエラーです。 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。
HY010 関数の順序エラーです。 StatementHandle の非同期実行関数が呼び出され、この関数が呼び出された時点でまだ実行中でした。

StatementHandle のために SQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。
HY090 ストリングまたはバッファー長が無効です。 BufferLength に指定された値は、0 より小さい値でした。
HY092 オプション・タイプが範囲外です。 引き数 Attribute に指定された値は、このバージョンの DB2 CLI では無効でした。
HY109 カーソル位置が無効です。 Attribute 引き数は SQL_ATTR_ROW_NUMBER で、行は削除されたか、フェッチできませんでした。
HYC00 ドライバーが機能していません。 引き数 Attribute で指定された値はこのバージョンの DB2 CLI の有効な DB2 CLI 属性でしたが、データ・ソースでサポートされていませんでした。

制約

なし。

CLI サンプル dbinfo.c

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

/* From the CLI sample DBINFO.C */
/* ... */
    sqlrc = SQLGetStmtAttr( hstmt, SQL_CURSOR_HOLD, &cursor_hold, 0, NULL ) ;
    HANDLE_CHECK( SQL_HANDLE_STMT, hstmt, sqlrc, &henv, &hdbc ) ;
    printf("    A statement attribute...\n");
    printf( "        Cursor With Hold is: " ) ;
    if ( cursor_hold == SQL_CURSOR_HOLD_ON ) printf( "ON\n" ) ;
    else printf( "OFF\n" ) ;
 
 

参照


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