SQLGetStmtAttr() - ステートメント属性の現行設定値を取得する

SQLGetStmtAttr() は、ステートメント属性の現行の設定値を戻します。これらのステートメント属性を設定するには、SQLSetStmtAttr() を使用します。

SQLGetStmtAttr() の ODBC 仕様

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

構文

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

関数の引数

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

表 2. SQLGetStmtAttr() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT StatementHandle 入力 接続ハンドルを指定します。
SQLINTEGER 属性 入力 取り出すステートメント属性を指定します。 これらの属性の全リストについては、関数 SQLSetStmtAttr() を参照してください。
SQLPOINTER ValuePtr 出力 引数 Attribute で指定した属性の現行値を戻す先の バッファーを指します。 このバッファーに戻される値は、32 ビットの符号なし整数値、または NUL 終了文字ストリングです。 この引数 Attribute にドライバー固有値が指定された場合は、符号付き整数が 戻されることがあります。
SQLINTEGER BufferLength 入力 この引数に指定する値は、以下のいずれの属性タイプを 照会するかによって異なります。
  • ODBC が定義した属性の場合
    • 引数 ValuePtr が文字ストリングを指している場合は、引数 BufferLength は、 引数 ValuePtr が指すバッファーの長さ (バイト) を指定します。
    • 引数 ValuePtr が整数を指している場合は、引数 BufferLength は 無視されます。
  • ドライバーが定義する属性 (IBM® 拡張) の場合
    • 引数 ValuePtr が文字ストリングを指している場合、引数 BufferLength には、 引数 ValuePtr が指すバッファーの長さ (バイト) を指定するか、あるいは NUL 終了ストリング に対応する SQL_NTS を指定します。SQL_NTS が指定された場合は、ドライバーは、引数 ValuePtr が指すバッファーの長さが SQL_MAX_OPTIONS_STRING_LENGTH であるものと想定します (NUL 終止符を除く)。
    • 引数 ValuePtr が整数を指している場合は、引数 BufferLength は 無視されます。
SQLINTEGER * StringLengthPtr 出力 引数 ValuePtr が指すバッファーに戻すのに使用可能な 合計バイト数 (NUL 終了文字用に戻されるバイト数を除く) を戻す先のバッファーを指します。
  • 引数 ValuePtr が NULL ポインターを指定する場合、長さは戻されません。
  • ValuePtr が指す属性値が文字ストリングであり、戻すのに使用可能なバイト数が BufferLength 以上 の場合、ValuePtr のデータは BufferLength から NUL 終了文字を引いた 長さに切り捨てられ、Db2® ODBC によって NUL 終了になります。
  • 引数 Attribute がストリングを示していない場合、Db2 ODBC は、 引数 BufferLength を無視し、引数 StringLengthPtr が指している バッファーに値を戻しません。

使用法

SQLGetStmtAttr() は、ステートメント属性の現行の設定値を戻します。これらの属性は、SQLSetStmtAttr() 関数を使用して設定します。

戻りコード

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

診断

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

表 3. SQLGetStmtAttr() の SQLSTATE
SQLSTATE 説明 説明
01000 警告。 通知メッセージ。(SQLGetStmtAttr() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
01004 データが切り捨てられました。 引数 ValuePtr が指すバッファーに戻されるデータは、 引数 BufferLength が指定する値の長さ (バイト) から NUL 終止符を引いた長さに 切り捨てられます。 切り捨てられなかったストリング値の長さ (バイト) は、引数 StringLengthPtr が指しているバッファーに戻されます。(SQLGetStmtAttr() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
HY000 一般エラー。 具体的な SQLSTATE が存在しないエラーが起こりました。SQLGetDiagRec() が戻すエラー・メッセージには、特定のエラーとそのエラーの原因が記述されています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要な メモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。 ステートメント・ハンドルで SQLExecute() または SQLExecDirect() が 呼び出され、SQL_NEED_DATA が戻されました。この関数は、すべての実行時データ・パラメーターまたは列にデータが送られる前に 呼び出されます。 実行時データ条件を取り消すには、SQLCancel() を呼び出してください。
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要な メモリーにアクセスすることができません。
HY090 ストリングまたはバッファーの長さが無効です。 引数 BufferLength に指定された値は 0 より小さい値です。
HY092 オプションのタイプが範囲外です。 引数 Attribute に指定された値は、Db2 ODBC の このバージョンには有効ではありません。
HYC00 ドライバーは使用できません。 引数 Attribute に指定された値は 、Db2 ODBC ドライバーのこのバージョンの接続属性またはステートメント属性として有効なものですが、 このデータ・ソースではサポートされていません。

例

次の例では、SQLGetStmtAttr() を使用してステートメント属性の現行値を取り出します。
SQLINTEGER cursor_hold;
rc = SQLGetStmtAttr( hstmt, SQL_ATTR_CURSOR_HOLD,
                                                        &cursor_hold, 0, NULL ) ;
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;
printf( "¥nCursor With Hold is: " ) ;
if ( cursor_hold == SQL_CURSOR_HOLD_ON )
  printf( "ON¥n" ) ;
else
  printf( "OFF¥n" ) ;