SQLSetStmtAttr() - ステートメント属性を設定する

SQLSetStmtAttr() は、ステートメントに関連した属性を設定します。 アプリケーションは、特定の接続に関連したすべてのステートメントの属性を 設定するために、SQLSetConnectAttr() を呼び出すことができます。

SQLSetStmtAttr() の ODBC 仕様

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

構文

SQLRETURN  SQLSetStmtAttr (SQLHSTMT          StatementHandle,
                           SQLINTEGER        Attribute,
                           SQLPOINTER        ValuePtr,
                           SQLINTEGER        StringLength);

関数の引数

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

表 2. SQLSetStmtAttr() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLINTEGER 属性 入力 設定するステートメント属性。属性の完全なリストについては 表 3 を参照してください。
SQLPOINTER ValuePtr 入力 Attribute に関連付けられる値を指すポインター。ValuePtr は 、Attribute の値によって異なり、32 ビットの符号なし整数値または NUL 終了文字ストリングを指します。Attribute 引数がドライバー固有値の場合は 、ValuePtr の値は符号付き整数になる場合があります。
SQLINTEGER StringLength 入力 *ValuePtr 引数についての情報。
  • ODBC が定義した属性の場合
    • ValuePtr が文字ストリングを指す場合、 この引数は *ValuePtr の長さにする必要があります。
    • ValuePtr が整数を指す場合、BufferLength は無視されます。
  • ドライバーが定義する属性 (IBM® 拡張) の場合
    • ValuePtr が文字ストリングを指す場合、この引数は *ValuePtr の長さまたは、 NUL 終了ストリングの場合は SQL_NTS の長さにする必要があります。
    • ValuePtr が整数を指す場合、BufferLength は無視されます。

使用法

ステートメントのステートメント属性は、別の SQLSetStmtAttr() を呼び出して ステートメント属性を変更するか、または SQLFreeHandle() を呼び出して ステートメントをドロップするまで、有効なままになってい ます。 SQL_CLOSE、SQL_UNBIND、または SQL_RESET_PARAMS 属性を用いて SQLFreeStmt() を呼び出しても、ステートメント属性はリセットされません。

いくつかのステートメント属性は 、*ValuePtr に指定された値をデータ・ソースがサポートしない場合に、 類似の値で置き換えることをサポートします。 このような場合、Db2® ODBC は、SQL_SUCCESS_WITH_INFO および SQLSTATE 01S02 (属性値が変更された) を戻します。置き換えられた値を判別するには、 アプリケーションで SQLGetStmtAttr() を呼び出します。

ValuePtr を使用して設定する情報の形式は、Attribute の指定により異なり ます。SQLSetStmtAttr() は、NUL 終了文字ストリングまたは 32 ビット整数値の形式で属性情報を受け入れます。 それぞれの ValuePtr 値の形式は、表 3 の属性の説明に示されています。 この形式は、SQLGetStmtAttr() のそれぞれの属性について戻される情報に適用され ます。 SQLSetStmtAttr() の引数 ValuePtr が指す文字ストリングには、StringLength の 長さが入ります。

Db2 ODBC は、ODBC 3.0 で名前変更されたすべての ODBC 2.0 の Attribute 値を サポートします。ODBC 3.0 で名前変更された Attribute 値の要約については、『SQLSetStmtAttr() 属性の変更』を参照してください。

DSNHDECP からの Db2 CCSID のオーバーライド: SQLSetStmtAttr() への Db2 ODBC 拡張機能によって、アプリケーションは、Db2 サブシステムのユニコード、EBCDIC、または ASCII CCSID の設定値を、ステートメント属性 SQL_CCSID_CHAR および SQL_CCSID_GRAPHIC を使用して、現在接続されているものにオーバーライドできます。この拡張は、Db2 DSNHDECP のデフォルト設定値とは異なる CCSID の Db2 との間で、 データを送受信しようとするアプリケーションを対象としたものです。

CCSID のオーバーライドは、SQLBindParameter() または SQLBindFileToParam() によってパラメーター・マーカーにバインドされた入力データ、あるいは、SQLBindCol() または SQLBindFileToCol() によって列にバインドされた出力データ、および SQLGetData() によって取り出される出力データのみに適用されます。

CCSID のオーバーライドはステートメント・レベルにのみ適用されます。Db2 は、ステートメントが ドロップされた後、または SQL_CCSID_DEFAULT が指定された場合 は、Db2 DSNHDECP のデフォルトの CCSID 設定値を引き続き使用します。

SQLGetStmtAttr() を使用して、現行ステートメント・ハンドルの CCSID オーバーライドの設定値を照会することができます。

次の表は、SQLSetStmtAttr() が設定できる それぞれの Attribute 値を示しています。太字で示されている値は、デフォルト値です。

表 3. ステートメント属性
属性 ValuePtr の内容
SQL_ATTR_BIND_TYPE または SQL_ATTR_ROW_BIND_TYPE このステートメント・ハンドルを指定して、SQLExtendedFetch() を 呼び出すときに使用するバインド方向を設定する 32 ビットの整数値。 引数 vParam に値 SQL_BIND_BY_COLUMN を 指定すると、列方向バインド が選択されます。vParam の値として、構造体の 長さ (バイト) を指定するか、結果列を バインドするバッファーのインスタンスを指定すると、行方向バインド が選択されます。

行方向バインドの場合、vParam で指定する長さ (バイト) には、 バインドされたすべての列のスペースおよび構造体またはバッファーの 埋め込みを含めるようにして、バインドされた列のアドレスが指定された長さだけ増えた場合に、 その結果が次の行の同じ列の先頭を指すようにする必要があります。(ANSI C の構造体または共用体を 用いて sizeof 演算子を使用する場合は、この動作は保証されます)

SQL_CCSID_CHAR 以下の CCSID を指定する 32 ビット整数値。
  • SQLBindParameter() または SQLBindFileToParam() でパラメーター・マーカーにバインドされるデータ
  • SQLBindCol() または SQLBindFileToCol() で結果セットの列にバインドされるデータ
  • SQLGetData() で取り出されるデータ
CCSID は C シンボリック・データ・タイプが SQL_C_CHAR および SQL データ・タイプが以下のタイプのいずれかであるデータに適用されます。
  • SQL_CHAR
  • SQL_VARCHAR
  • SQL_LONGVARCHAR
  • SQL_CLOB
  • SQL_TYPE_DATE
  • SQL_TYPE_TIME
  • SQL_TYPE_TIMESTAMP
SQL_CCSID_GRAPHIC 以下の CCSID を指定する 32 ビット整数値。
  • SQLBindParameter() または SQLBindFileToParam() でパラメーター・マーカーにバインドされるデータ
  • SQLBindCol() または SQLBindFileToCol() で結果セットの列にバインドされるデータ
  • SQLGetData() で取り出されるデータ
CCSID は C シンボリック・データ・タイプが SQL_C_DBCHAR および SQL データ・タイプが以下のタイプのいずれかであるデータに適用されます。
  • SQL_GRAPHIC
  • SQL_VARGRAPHIC
  • SQL_LONGVARGRAPHIC
  • SQL_DBCLOB
  • SQL_TYPE_DATE
  • SQL_TYPE_TIME
  • SQL_TYPE_TIMESTAMP
SQL_ATTR_CLOSE_BEHAVIOR 基礎となる CLOSE CURSOR 操作の際に強制的にロックを解放する 32 ビット整数値。可能な値には、以下のものがあります。
  • SQL_CC_NO_RELEASE: このステートメント・ ハンドルに関連したカーソルのクローズ時に、ロックは解放されません。
  • SQL_CC_RELEASE: このステートメント・ハンドルに関連したカーソルの クローズ時に、ロックが解放されます。
一般的に、SQL_CLOSE を設定した引数 fOption を指定して SQLFreeStmt() を呼び出すか、 または SQLCloseCursor() を呼び出すと、カーソルは明示的にクローズされます。さらに、(コミットまたはロールバックを出したときに) トランザクションの終了によっても、 カーソルをクローズすることができます (現在使用中の WITH HOLD 属性によって異なります)。
SQL_ATTR_CONCURRENCY
カーソルの並行性を指定する 32 ビット整数値。
  • SQL_CONCUR_READ_ONLY - カーソルは読み取り専用。更新はできません。前方スクロール・カーソルと静的カーソルでサポートされます。
  • SQL_CONCUR_LOCK - カーソルは、行を確実に更新するのに十分な最低レベルのロッキングを使用します。 前方スクロール・カーソルと動的カーソルでサポートされます。

SQL_ATTR_CONCURRENCY のデフォルト値は、静的で前方スクロール・カーソルは SQL_CONCUR_READ_ONLY です。動的カーソルのデフォルトは SQL_CONCUR_LOCK です。

SQL_ATTR_CURSOR_TYPE 属性が SQL_ATTR_CONCURRENCY の現行値をサポートしないタイプに変更された場合、SQL_ATTR_CONCURRENCY の値が実行時に変更されて、SQLExecDirect() または SQLPrepare() が呼び出されると警告が出されます。

SQL_ATTR_CONCURRENCY の値が SQL_CONCUR_READ_ONLY に設定されて、SELECT FOR UPDATE ステートメントが実行されると、エラーが戻ります。

SQL_ATTR_CONCURRENCY の値が、SQL_ATTR_CURSOR_TYPE の一部の値をサポートするが、SQL_ATTR_CURSOR_TYPE の現行値はサポートしない値に変更された場合は、SQL_ATTR_CURSOR_TYPE の値は実行時に変更されて、SQLExecDirect() または SQLPrepare() が呼び出されると警告が出されます。

指定した並行性がデータ・ソースでサポートされない場合、Db2 ODBC は別の並行性と置き換えて、警告を戻します。置換順序は、カーソルのタイプによります。
  • 前方スクロール: SQL_CONCUR_LOCK が、SQL_CONCUR_ROWVER または SQL_CONCUR_VALUES に対して置き換わります。
  • 静的: SQL_CONCUR_READ_ONLY が SQL_CONCUR_ROWVER または SQL_CONCUR_VALUES に対して置き換わります。
  • 動的: SQL_CONCUR_LOCK が、SQL_CONCUR_ROWVER または SQL_CONCUR_VALUES に対して置き換わります。
サポートされない属性値: ODBC アーキテクチャーでは以下の値を定義して いますが、Db2 ODBC ではサポートされていません。
  • SQL_CONCUR_VALUES - カーソルは、複数の値を比較して、オプティミスティック並行性制御を使用します。
  • SQL_CONCUR_ROWVER - カーソルはオプティミスティック並行性制御を使用します。
これらの値のいずれかが使用されると、SQL_SUCCESS_WITH_INFO (SQLSTATE 01S02) が戻され、オプション値が変更されます。
SQL_ATTR_CURSOR_HOLD1 このステートメント・ハンドルに関連したカーソルが COMMIT 操作以前と同じ位置に保存 されているかどうか、さらにアプリケーションがそのステートメントを 再実行せずにフェッチ可能かどうかを指定する 32 ビット整数。
  • SQL_CURSOR_HOLD_ON
  • SQL_CURSOR_HOLD_OFF

ステートメント・ハンドルが最初に割り当てられたときのデフォルト値は SQL_CURSOR_HOLD_ON です。

このステートメント・ハンドルに関連してオープン・カーソルがある場合は、 この属性は指定できません。

SQL_ATTR_CURSOR_SCROLLABLE アプリケーションが必要とするサポートのレベルを指定する 32 ビット整数。この属性を設定すると、SQLExecDirect() および SQLExecute() に続いて起こる呼び出しに影響を与えます。サポートされる値は、以下のとおりです。
  • SQL_NONSCROLLABLE - 両方向スクロール・カーソルは、ステートメント・ハンドルでは必要ではありません。アプリケーションが SQLFetchScroll() をこのハンドルで呼び出す場合、FetchOrientation の有効な値は SQL_FETCH_NEXT のみです。
  • SQL_SCROLLABLE - 両方向スクロール・カーソルが、ステートメント・ハンドルで必要です。 アプリケーションが SQLFetchScroll() を呼び出す場合、順次モード以外のモードでカーソル位置に対し、FetchOrientation の有効な値を指定できます。
SQL_ATTR_CURSOR_SENSITIVITY 別のカーソルで行われた変更をステートメント・ハンドル上のカーソルに表示されるようにするかどうかを指定する 32 ビット整数。 この属性を設定すると、SQLExecDirect() および SQLExecute() に続いて起こる呼び出しに影響を与えます。サポートされる値は、以下のとおりです。
  • SQL_UNSPECIFIED - カーソル・タイプ、および他のカーソルで行われた変更をステートメント・ハンドル上のカーソルに表示されるかどうかは、指定されません。ステートメント・ハンドル上のカーソルは、このような変更を全然表示しない場合も、一部を表示する場合も、あるいはすべてを表示する場合もあります。
  • SQL_INSENSITIVE - ステートメント・ハンドル上のすべてのカーソルは、他のカーソルによって行われた変更を反映することなく結果セットを表示します。 インセンシティブ・カーソルは読み取り専用です。この属性は、読み取り専用の並行性を持つ静的カーソルに対応します。
  • SQL_SENSITIVE - 読み取り専用の並行性を持つ静的カーソルに対応します。
SQL_ATTR_CURSOR_TYPE
カーソル・タイプを指定する 32 ビット整数値。 サポートされる値は、以下のとおりです。
  • SQL_CURSOR_FORWARD_ONLY : カーソルは、 前方のみのスクロール・カーソルとして動作します。
  • SQL_CURSOR_STATIC : 結果セット内のデータは、静的です。
  • SQL_CURSOR_DYNAMIC - カーソルは、結果セット内のすべての変更を検出します。
これらのオプションは、関連ステートメント・ハンドルにオープン・カーソルがある場合は設定できません。

指定したカーソル・タイプがデータ・ソースでサポートされない場合、Db2 ODBC は別のカーソル・タイプと置き換えて、警告を戻します。動的カーソルの場合は、Db2 ODBC は以下の順序で別のカーソル・タイプを置き換えます (静的カーソルまたは前方スクロール・カーソル)。

サポートされない属性値: ODBC アーキテクチャーでは、Db2 ODBC でサポートされない SQL_CURSOR_KEYSET_DRIVEN 値を定義します。この値が指定された場合、Db2 ODBC はステートメント属性を SQL_CURSOR_STATIC または SQL_CURSOR_FORWARD_ONLY に設定し、SQLSTATE 01S02 (変更されたオプション値) を戻します。この場合、アプリケーションは、SQLGetStmtAttr() を呼び出して、設定されている値を照会する必要があります。

SQL_ATTR_MAX_LENGTH 単一文字列またはバイナリー列から取り出せるデータの最大量に対応する 32 ビット 整数値。SQL_ATTR_MAX_LENGTH に指定した値が使用可能なデータ量よりも小さいためにデータが 切り捨てられる場合、SQLGetData() 呼び出しまたはフェッチは、SQL_SUCCESS_WITH_INFO およ び SQLSTATE 01004 (データの切り捨て) を戻すのでなく、SQL_SUCCESS を 戻します。vParam のデフォルト値は 0 です。 0 の場合、Db2 ODBC が文字またはバイナリー・タイプのすべての使用可能なデータを戻そうとします。
SQL_ATTR_MAX_ROWS 照会からアプリケーションに戻す最大行数に対応する 32 ビット整数値。vParam の デフォルト値は 0 です。0 の場合、すべての行が戻されます。
SQL_ATTR_NODESCRIBE
Db2 ODBC が、自動的に結果セットの列属性を記述するか、あるいは SQLSetColAttributes() を 使用してアプリケーションから通知されるまで待つかを指定する 32 ビット整数。
  • SQL_NODESCRIBE_OFF
  • SQL_NODESCRIBE_ON

このステートメント・ハンドルに関連してオープン・カーソルがある場合は、 この属性は指定できません。

この属性は、次のようなアプリケーションによって、関数 SQLSetColAttributes() と一緒に使用されます。 すなわち、戻される結果セットの正確な特性をそのアプリケーションがあらかじめ分かっており、クライアント側の処理を提供するために Db2 ODBC が必要とする記述子情報に関連した余分のネットワーク・トラフィックを発生させたくない場合です。

IBM 固有: この属性は、IBM が規定した拡張機能です。

SQL_ATTR_NOSCAN Db2 ODBC が SQL ストリングをスキャンしてエスケープ文節を探すかどうかを指定する 32 ビット整数値。次の 2 つの有効値があります。
  • SQL_NOSCAN_OFF : SQL ストリングをスキャンして、 エスケープ文節シーケンスを探します。
  • SQL_NOSCAN_ON : エスケープ文節を探すために SQL ストリングをスキャンしません。すべてサーバーに直接送信され処理されます。
このアプリケーションは、送信する SQL ストリング内にベンダー・エスケープ・ シーケンスを使用することがない場合に走査をオフにすることを選択できます。 この選択を行うと、スキャンに関連したオーバーヘッド処理の一部が除かれます。
SQL_ATTR_PARAMOPT_ATOMIC 複数行の挿入操作の下層処理にアプリケーションがアトミック SQL または非アトミック SQL のどちらを使用するかを決定する 32 ビット整数値。属性値は、SQLSetStmtAttr を使用して SQL INSERT ステートメントのパラメーター・マーカーに対して複数値を指定した後で、有効になります。可能な値は、以下のとおりです。
SQL_ATOMIC_YES
アプリケーションは、複数行の挿入操作の下層処理にアトミック SQL を使用します。これはデフォルトです。

複数行の挿入をサポートしないサーバーへの接続に対して SQL_ATOMIC_YES を指定すると、SQLSTATE 01S02 (オプション値変更) になります。 属性値は SQL_ATOMIC_NO に設定されます。

SQL_ATOMIC_NO
アプリケーションは、複数行の挿入操作の下層処理に非アトミック SQL を使用します。
SQL_ATTR_PARAMSET_SIZE 各パラメーターの値の数を指定する 32 ビットの符号なし整数値。 SQL_ATTR_PARAMSET_SIZE が 1 より大きい場合、 SQLBindParameter() の引数 rgbValue は、 パラメーター値が入った配列を指し、 引数 pcbValue は、長さが入った配列を指します。各配列のカーディナリティーは、 このフィールドの値と値と等しくなります。
SQL_ATTR_PARAMS_PROCESSED_PTR

現在行の番号が返されるバッファーを指す、 32 ビットの符号なし整数 * フィールド。パラメーターの行が処理されるたびに、 その行の番号に設定されます。 NULL ポインターの場合、行番号は返されません。

この属性の指すバッファーに値を設定する SQLExecDirect() または SQLExecute() を呼び出した場合に、 SQL_SUCCESS または SQL_SUCCESS_WITH_INFO のいずれも返されなければ、 そのバッファーの内容は未定義です。

SQL_ATTR_RETRIEVE_DATA Db2 ODBC が、SQLFetchScroll() または SQLExtendedFetch() を呼び出す時にデータをデータベースから取り出すかどうかを示す 32 ビット整数値。可能な値には、以下のものがあります。
  • SQL_RD_ON: SQLFetchScroll() または SQLExtendedFetch() によって、カーソルを指定した場所に置いた後に、データを取り出します。
  • SQL_RD_OFF: SQLFetchScroll() または SQLExtendedFetch() によって、カーソルを置いた後に、データを取り出しません。SQL_RETRIEVE_DATA を SQL_RD_OFF に設定することにより、取り出す行のオーバーヘッドに陥ることなく、アプリケーションで行があるかどうか、または行のブックマークを取り出すかどうかを検査できます。

この属性は、カーソルがオープンしている場合は、設定できません。

SQL_ATTR_ROW_ARRAY_SIZE 行セットの行数を指定する 32 ビット整数値。 これは、SQLFetchScroll() の各呼び出しによって戻される行数です。 デフォルト値は 1 です。

指定した行セット・サイズが、データ・ソースでサポートされる最大行セット・サイズを超えた場合、Db2 ODBC は、最大サポート値を置き換えて、SQLSTATE 01S02 (変更されたオプション値) を戻します。

SQL_ATTR_ROW_NUMBER 結果セット全体にある現在行の番号の 32 ビット整数値。現在行の番号を判別できない場合、または現在行がない場合、Db2 ODBC は 0 を戻します。この属性は、SQLGetStmtAttr() の呼び出しによって取り出すことができますが、SQLSetStmtAttr() の呼び出しによって設定できません。
SQL_ATTR_ROW_OPERATION_POINTER SQLSetPos() が使用されて一括操作が実行される際に、行を無視するのに使用される UDWORD 値の配列を指す 16 ビット符号なし整数 * 値。各値が SQL_ROW_PROCEED (一括操作で行を含む場合) または SQL_ROW_IGNORE (一括操作から行を除外する場合) に設定されます。SQLBulkOperations() の呼び出し中に、この配列を使用して行を無視することはできません。

SQL_ATTR_ROW_OPERATION_POINTER が NULL ポインターに設定されている場合、Db2 ODBC は行の状況値を戻しません。この属性はいつでも設定できますが、新しい値は次に SQLFetchScroll() または SQLSetPos() が呼び出されるまで使用されません。

SQL_ATTR_ROW_STATUS_PTR SQLFetch() または SQLFetchScroll() の呼び出し後、行の状況値を含む UWORD 値を指す 16 ビット符号なし整数 * 値。 配列には、行セット内の行と同じ数のエレメントがあります。

SQL_ATTR_ROW_STATUS_PTR が NULL ポインターに設定されている場合、Db2 ODBC は行の状況値を戻しません。この属性はいつでも設定できますが、新しい値は次に SQLFetch()、SQLFetchScroll()、または SQLSetPos() が呼び出されるまで使用されません。

変更の始まりSQL_ATTR_ROWS_FETCHED_PTR変更の終わり 変更の始まりSQLFetch() または SQLFetchScroll() の呼び出し後、フェッチされた行数を含むバッファーを指す 32 ビット符号なし整数 * 値。 配列には、行セット内の行と同じ数のエレメントがあります。

Db2 ODBC は、SQLExtendedFetch() で、SQL_ATTR_ROWS_FETCHED_PTR を RowCountPtr 配列にマップします。

変更の終わり
SQL_ATTR_ROWSET_SIZE 行セットの行数を指定する 32 ビット整数値。 行セットは、SQLExtendedFetch() の各呼び出しで戻される行の配列です。デフォルト値は 1 であり、これは単一の SQLFetch() 呼び出しを行うことに相当します。 この属性は、カーソルがオープンしていても指定でき、次の SQLExtendedFetch() 呼び出しで実効になります。

推奨: SQLExtendedFetch() ではなく、SQLFetchScroll() をご使用ください。ステートメント属性 SQL_ATTR_ROWSET_SIZE ではなく SQL_ATTR_ROW_ARRAY_SIZE を使用して行セット内の行数を設定します。

SQL_ATTR_STMTTXN_ISOLATION または SQL_ATTR_TXN_ISOLATION2 現行のステートメント・ハンドルでのトランザクション分離レベルを設定する 32 ビット整数値。 これは、接続レベルで設定されたデフォルト値をオーバーライドするものです。許可される値については、関数 SQLSetConnectOption() を参照してください。

この属性は、このステートメント・ハンドルでオープン・カーソルがある場合は 設定できません (SQLSTATE 24000)。

IBM 固有: 値 SQL_ATTR_STMTTXN_ISOLATION は、SQL_ATTR_TXN_ISOLATION と 同じ意味です。 SQL_ATTR_STMTTXN_ISOLATION は、この属性をステートメント・レベルで 設定できるようにする IBM 拡張機能です。

この属性の設定について詳しくは、『最大並行性およびデータ整合性の分離レベル』を参照してください。

SQL_ATTR_USE_BOOKMARKS アプリケーションがカーソルでブックマークを使用するかどうかを指定する 32 ビット整数値。サポートされる属性値は SQL_UB_OFF のみです。これは、アプリケーションがカーソルでブックマークを使用しないことを示します。

サポートされない属性値: ODBC アーキテクチャーでは、Db2 ODBC でサポートされない SQL_UB_VARIABLE 値を定義します。 SQL_UB_VARIABLE は、アプリケーションがカーソルでブックマークを使用し、サポートされていれば、ODBC ドライバーが可変長ブックマークを提供することを示します。

注:
  1. ODBC 初期化ファイルの CURSORHOLD キーワードを用いて、この属性のデフォルト値を 変更することができます。
  2. ODBC 初期化ファイルの TXNISOLATION キーワードを用いて、この属性のデフォルト値を 変更することができます。

戻りコード

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

診断

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

表 4. SQLSetStmtAttr() の SQLSTATE
SQLSTATE 説明 説明
01000 警告。 通知メッセージ。(SQLSetStmtAttr() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
01S02 オプション値が変更されました。 Db2 が *ValuePtr に指定された値をサポートしていないか、または *ValuePtr に 指定された値が SQL 制約または要件により無効です。 したがって、Db2 ODBC は類似の値で置き換えを行いました。(SQLSetStmtAttr() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
08S01 データ・ソースに接続できません。 アプリケーションとデータ・ソースとの間の通信リンクに、 関数が完了する前に障害が発生しました。
24000 カーソル状態が無効です。 Attribute は SQL_ATTR_CONCURRENCY であり、カーソルはオープンしています。
HY000 一般エラー。 具体的な SQLSTATE が存在しないエラーが起こりました。SQLGetDiagRec() が *MessageText バッファー に戻したエラー・メッセージに、エラーとその原因が記述されています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は指定されたハンドルにメモリーを割り振ることができません。
HY009 NULL ポインターの使用は無効です。 ValuePtr に NULL ポインターが渡され、*ValuePtr の値はストリング値でした。
HY010 関数シーケンス・エラーが発生しました。 ステートメント・ハンドルで SQLExecute() または SQLExecDirect() が 呼び出され、SQL_NEED_DATA が戻されました。この関数は、すべての実行時データ・パラメーターまたは列にデータが送られる前に 呼び出されます。 実行時データ条件を取り消すには、SQLCancel() を呼び出してください。
HY011 この時点では操作は無効です。 Attribute は SQL_ATTR_CONCURRENCY であり、ステートメントは準備済みです。
HY024 属性値が無効です。 指定された Attribute 値について、無効な値が *ValuePtr に指定されました。
HY090 ストリングまたはバッファーの長さが無効です。 StringLength 引数は 0 より小さい値ですが、SQL_NTS ではありません。
HY092 オプションのタイプが範囲外です。 引数 Attribute に指定された値は、Db2 ODBC のこのバージョンでは無効です。
HYC00 ドライバーは使用できません。 引数 Attribute に指定された値は、Db2 ODBC ドライバーのバージョンに対して有効な接続かステートメント属性ですが、データ・ソースでサポートされていません。

例

次の例では、SQLSetStmtAttr() を使用してステートメント属性を設定します。
rc = SQLSetStmtAttr( hstmt,
                     SQL_ATTR_CURSOR_HOLD,
                     ( void * ) SQL_CURSOR_HOLD_OFF,
                     0 ) ;
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;