SQLSetStmtAttr() - ステートメント属性を設定する
SQLSetStmtAttr() は、ステートメントに関連した属性を設定します。 アプリケーションは、特定の接続に関連したすべてのステートメントの属性を 設定するために、SQLSetConnectAttr() を呼び出すことができます。
SQLSetStmtAttr() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 3.0 | あり | あり |
構文
SQLRETURN SQLSetStmtAttr (SQLHSTMT StatementHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
| SQLINTEGER | 属性 | 入力 | 設定するステートメント属性。属性の完全なリストについては 表 3 を参照してください。 |
| SQLPOINTER | ValuePtr | 入力 | Attribute に関連付けられる値を指すポインター。ValuePtr は 、Attribute の値によって異なり、32 ビットの符号なし整数値または NUL 終了文字ストリングを指します。Attribute 引数がドライバー固有値の場合は 、ValuePtr の値は符号付き整数になる場合があります。 |
| SQLINTEGER | StringLength | 入力 | *ValuePtr 引数についての情報。
|
使用法
ステートメントのステートメント属性は、別の 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 値を示しています。太字で示されている値は、デフォルト値です。
| 属性 | 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 ビット整数値。
CCSID は C シンボリック・データ・タイプが SQL_C_CHAR および SQL データ・タイプが以下のタイプのいずれかであるデータに適用されます。
|
| SQL_CCSID_GRAPHIC | 以下の CCSID を指定する 32 ビット整数値。
CCSID は C シンボリック・データ・タイプが SQL_C_DBCHAR および SQL データ・タイプが以下のタイプのいずれかであるデータに適用されます。
|
| SQL_ATTR_CLOSE_BEHAVIOR | 基礎となる CLOSE CURSOR 操作の際に強制的にロックを解放する 32 ビット整数値。可能な値には、以下のものがあります。
|
| SQL_ATTR_CONCURRENCY | カーソルの並行性を指定する 32 ビット整数値。
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 は別の並行性と置き換えて、警告を戻します。置換順序は、カーソルのタイプによります。
サポートされない属性値: ODBC アーキテクチャーでは以下の値を定義して
いますが、Db2 ODBC ではサポートされていません。
|
| SQL_ATTR_CURSOR_HOLD1 | このステートメント・ハンドルに関連したカーソルが COMMIT 操作以前と同じ位置に保存
されているかどうか、さらにアプリケーションがそのステートメントを
再実行せずにフェッチ可能かどうかを指定する 32 ビット整数。
ステートメント・ハンドルが最初に割り当てられたときのデフォルト値は SQL_CURSOR_HOLD_ON です。 このステートメント・ハンドルに関連してオープン・カーソルがある場合は、 この属性は指定できません。 |
| SQL_ATTR_CURSOR_SCROLLABLE | アプリケーションが必要とするサポートのレベルを指定する 32 ビット整数。この属性を設定すると、SQLExecDirect() および SQLExecute() に続いて起こる呼び出しに影響を与えます。サポートされる値は、以下のとおりです。 |
| SQL_ATTR_CURSOR_SENSITIVITY | 別のカーソルで行われた変更をステートメント・ハンドル上のカーソルに表示されるようにするかどうかを指定する 32 ビット整数。
この属性を設定すると、SQLExecDirect() および SQLExecute() に続いて起こる呼び出しに影響を与えます。サポートされる値は、以下のとおりです。
|
| SQL_ATTR_CURSOR_TYPE | カーソル・タイプを指定する 32 ビット整数値。 サポートされる値は、以下のとおりです。
指定したカーソル・タイプがデータ・ソースでサポートされない場合、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 ビット整数。
このステートメント・ハンドルに関連してオープン・カーソルがある場合は、 この属性は指定できません。 この属性は、次のようなアプリケーションによって、関数 SQLSetColAttributes() と一緒に使用されます。 すなわち、戻される結果セットの正確な特性をそのアプリケーションがあらかじめ分かっており、クライアント側の処理を提供するために Db2 ODBC が必要とする記述子情報に関連した余分のネットワーク・トラフィックを発生させたくない場合です。 IBM 固有: この属性は、IBM が規定した拡張機能です。 |
| SQL_ATTR_NOSCAN | Db2 ODBC が SQL ストリングをスキャンしてエスケープ文節を探すかどうかを指定する 32 ビット整数値。次の 2 つの有効値があります。
|
| SQL_ATTR_PARAMOPT_ATOMIC | 複数行の挿入操作の下層処理にアプリケーションがアトミック SQL または非アトミック SQL のどちらを使用するかを決定する 32 ビット整数値。属性値は、SQLSetStmtAttr を使用して SQL INSERT ステートメントのパラメーター・マーカーに対して複数値を指定した後で、有効になります。可能な値は、以下のとおりです。
|
| 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_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 ドライバーが可変長ブックマークを提供することを示します。 |
| 注:
|
|
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_INVALID_HANDLE
- SQL_ERROR
診断
次の表は、この関数が生成する各 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 ドライバーのバージョンに対して有効な接続かステートメント属性ですが、データ・ソースでサポートされていません。 |
例
rc = SQLSetStmtAttr( hstmt,
SQL_ATTR_CURSOR_HOLD,
( void * ) SQL_CURSOR_HOLD_OFF,
0 ) ;
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;
SQL_ATTR_ROWS_FETCHED_PTR