SQLSetStmtAttr - ステートメントに関するオプションの設定

目的

仕様:

DB2 CLI 2.1

ODBC 1.0

ISO CLI

SQLSetStmtAttr() はステートメントに関するオプションを設定します。

構文

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

関数の引き数

表 82. SQLSetStmtAttr の引き数

データ・タイプ	引き数	用途	説明
SQLHSTMT	`StatementHandle`	入力	ステートメント・ハンドル。
SQLINTEGER	`Attribute`	入力	セットするオプション。
SQLPOINTER	`ValuePtr`	入力	`Attribute` が ODBC 定義の属性であり、`ValuePtr` が文字ストリングまたはバイナリー・バッファーを指している場合は、この引き数は、`*ValuePtr` の長さでなければならない。 `Attribute` が ODBC 定義の属性であり、ValuePtr が整数であれば、`StringLength` は無視される。 `Attribute` が DB2 CLI 属性であれば、アプリケーションは属性の性質を `StringLength` 引き数を設定することによって示す。 `StringLength` には、以下の値を設定可能。 `ValuePtr` が文字ストリングを指すポインターであれば、 `StringLength` はストリングの長さまたは SQL_NTS である。 `ValuePtr` がバイナリー・バッファーを指すポインターであれば、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を `StringLength` に入れる。これにより、負の値が `StringLength` に入る。 `ValuePtr` が文字ストリングあるいはバイナリー・ストリング以外の値を指すポインターであれば、`StringLength` の値は SQL_IS_POINTER でなければならない。 `ValuePtr` に固定長の値が含まれている場合は、 `StringLength` は、SQL_IS_INTEGER または SQL_IS_UINTEGER となる。
SQLINTEGER	`StringLength`	入力	`ValuePtr` が文字ストリングまたはバイナリー・バッファーを指している場合は、この引き数は `ValuePtr` の長さでなければならない。 `ValuePtr` がポインターであるがストリングまたはバイナリー・バッファーを指していない場合は、`StringLength` の値は SQL_IS_POINTER でなければならない。 `ValuePtr` がポインターでない場合は、 `StringLength` の値は SQL_IS_NOT_POINTER でなければならない。

使用法

ステートメントのステートメント属性は、別の SQLSetStmtAttr() 呼び出しで変更されるか、SQLFreeHandle() の呼び出しでそのステートメントが除去されるまでは有効です。SQL_CLOSE、SQL_UNBIND、または SQL_RESET_PARAMS オプションを指定して SQLFreeStmt() を呼び出しても、ステートメント属性はリセットされません。

ステートメント属性によっては、データ・ソースが ValuePtr で指定されている値をサポートしない場合、似たような値での置き換えをサポートするものがあります。そのような場合、 DB2 CLI は SQL_SUCCESS_WITH_INFO および SQLSTATE 01S02 (オプション値が変更された) を戻します。例えば、属性が SQL_ATTR_CONCURRENCY で、 ValuePtr が SQL_CONCUR_ROWVER であり、データ・ソースがそれをサポートしない場合、DB2 CLI は SQL_CONCUR_VALUES を置き換えて SQL_SUCCESS_WITH_INFO を戻します。置き換えられた値を判別するには、アプリケーションで SQLGetStmtAttr() を呼び出します。 ValuePtr に設定する情報の形式は、指定された属性によって変わります。

SQLSetStmtAttr() は、属性情報を次の 2 つ (ヌル終了文字ストリングまたは 32 ビット整数値) の形式のいずれかで受け入れます。それぞれの形式は、属性の説明のところで述べられています。この形式は、SQLGetStmtAttr() でそれぞれの属性ごとに戻される情報に適用されます。 SQLSetStmtAttr() の ValuePtr 引き数が指す文字ストリングの長さは StringLength です。

ダーティー・ビット

DB2 Everyplace はダーティー・ビットを使用してレコードに対して行われた変更を追跡します。ダーティー・ビットの動作は SQL_ATTR_DELETE_MODE、 SQL_ATTR_READ_MODE、SQL_ATTR_DIRTYBIT_SET_MODE ステートメント属性の影響を受けます。次の表は、あるレコードに対して特定のデータベース操作が行われた後のダーティー・ビットの状態を示しています。この表では、SQL_ATTR_DIRTYBIT_SET_MODE パラメーターが、システムによって保守されるダーティー・ビットを持つ SQL_DIRTYBIT_SET_BY_SYSTEM に設定されていると想定しています。

表 83. DB2 Everyplace ダーティー・ビットの状態

レコードに対するアクション	ダーティー・ビットの状態
状態をクリーン (0) にして INSERT	INSERT
状態をクリーン (0) にして DELETE	DELETE
状態をクリーン (0) にして UPDATE	UPDATE
DELETE して INSERT	UPDATE
DELETE して DELETE	該当せず
DELETE して UPDATE	該当せず
INSERT して INSERT	該当せず
INSERT して DELETE	レコードの物理的な削除
INSERT して UPDATE	INSERT
UPDATE して INSERT	該当せず
UPDATE して DELETE	DELETE
UPDATE して UPDATE	UPDATE

ダーティー・ビットの値は、表の $dirty 列を照会して入手します。例えば、以下のステートメントはダーティー・ビットと PHONEBOOK 表の NAME 列を戻します。

SELECT $dirty, NAME from PHONEBOOK

ダーティー・ビットの値は以下のようになります。

表 84. DB2 Everyplace ダーティー・ビット値

説明	ダーティー・ビット値
未変更レコード (CLEAN)	0
削除済みレコード (DELETE)	1
挿入済みレコード (INSERT)	2
更新済みレコード (UPDATE)	3

ステートメント属性

現在定義されている属性は以下のとおりです。

SQL_ATTR_CURSOR_SCROLLABLE (DB2 CLI)

アプリケーションが求めるサポート・レベルを指定する 32 ビット整数。この属性の設定は、後続の SQLExecDirect() および SQLExecute() への呼び出しに影響します。サポートされる値は次のとおりです。

SQL_NONSCROLLABLE

ステートメント・ハンドルは両方向スクロール・カーソルを必要としません。アプリケーションがこのハンドルで SQLFetchScroll() を呼び出した場合、 FetchOrientation() の唯一の有効な値は SQL_FETCH_NEXT です。これはデフォルトです。
SQL_SCROLLABLE

ステートメント・ハンドルは両方向スクロール・カーソルを必要とします。 SQLFetchScroll() を呼び出す場合、カーソルを順次モード以外のモードで配置することができるように、アプリケーションは FetchOrientation の有効な値を指定します。

SQL_ATTR_CURSOR_SENSITIVITY (DB2 CLI)

カーソルが別のカーソルの書き込みアクティビティーを認識するかどうかを指定する 32 ビット整数値。サポートされる値は次のとおりです。

SQL_UNSPECIFIED

他のカーソルの書き込みアクティビティーにより、現行のカーソルが未定義の影響を受けます。これはデフォルトです。
SQL_INSENSITIVE

他のカーソルの書き込みアクティビティーによる、現行のカーソルへの影響はありません。
注:
この属性値はパフォーマンスに影響するため、慎重に使用してください。

SQL_ATTR_CURSOR_TYPE (DB2 CLI)

カーソル・タイプを指定する 32 ビット整数値。サポートされる値は次のとおりです。

SQL_CURSOR_FORWARD_ONLY = カーソルは前方にのみスクロール。これはデフォルトです。
SQL_CURSOR_STATIC = 結果セット内のデータは静的です。

このオプションをオープン・カーソルに指定することはできません。

SQL_ATTR_ROW_ARRAY_SIZE (DB2 CLI)

行セット内の行数を指定する 32 ビット整数値。これは、SQLFetch() または SQLFetchScroll() に対する各呼び出しで戻される行数です。デフォルト値は 1 です。指定した行セットのサイズが、データ・ソースがサポートする最大行セット・サイズを超える場合、 DB2 CLI はその値を置き換え、SQLSTATE 01S02 (オプション値が変更された) を戻します。このオプションはオープン・カーソルに対して指定できます。

SQL_ATTR_ROW_BIND_TYPE (DB2 CLI)

SQLFetch() または SQLFetchScroll() が関連したステートメントで呼び出されるときに使用する、バインディング方向を設定する 32 ビットの整数値。列方向バインディングは、定義済み定数の SQL_BIND_BY_COLUMN を ValuePtr に設定することで選択します。 ValuePtr に指定する長さに、バインドされた列用のスペースと、構造体あるいはバッファーの埋め込み用のスペースをすべて含めることによって、バインドされた列のアドレスが指定された長さの分だけ増分しても、結果が次の行の同じ列の先頭を指すようにする必要があります。sizeof 演算子を ANSI C の共用体または構造体で使用すれば、この動作は保証されます。列方向バインディングは、SQLFetchScroll() の場合のデフォルトのバインディング方向です。

SQL_ATTR_ROW_NUMBER (DB2 CLI)

結果セット全体の中の現在行の番号を示す 32 ビット整数値。現在行の番号が判別できない場合、あるいは現在行がない場合、DB2 CLI は 0 を戻します。この属性は SQLGetStmtAttr() を呼び出すことによって取り出すことができますが、 SQLSetStmtAttr() を呼び出すことによって設定することはできません。

SQL_ATTR_ROW_STATUS_PTR (DB2 CLI)

SQLFetch() または SQLFetchScroll() の呼び出しの後、行状況値が入った UWORD 値の配列を指す、16 ビットの符号なし整数値。この配列には、行セットの行数分のエレメントがあります。このステートメント属性をヌル・ポインターとしてセットできますが、その場合は、DB2 CLI は行状況値を戻しません。この属性はいつでもセットできますが、新規の値は次に SQLFetch() または SQLFetchScroll() が呼び出されるまでは使用されません。

SQL_ATTR_ROWS_FETCHED_PTR (DB2 CLI)

SQLFetch() または SQLFetchScroll() の呼び出しの後、取り出された行数が戻るバッファーを指す、32 ビットの符号なしの整数値。

SQL_ATTR_DELETE_MODE (DB2 Everyplace)

サポートされる値は次のとおりです。

SQL_DELETE_MARK_ONLY

これはシステム・デフォルトです。削除 SQL ステートメントが実行されると、レコードは「delete」とだけマークされます。そのレコード内容は、SQL_READ_INCLUDE_MARKED_DELETE が設定されている場合、引き続き読み取ることができます。
SQL_DELETE_PHYSICAL_REMOVE

SQL の DELETE ステートメントは、レコードのダーティー・ビットとは無関係に、WHERE 文節の条件を満たすレコードを物理的に削除します。

例えば、ダーティー・ビットの状況を無視してレコードを物理的に除去するには、以下の構文を使用します。

SQLSetStmtAttr (stmt, SQL_ATTR_DELETE_MODE, SQL_DELETE_PHYSICAL_REMOVE, 0)

次に、以下の SQL ステートメントを実行して、X が 0 に等しくないすべてのレコードを表から削除します。

DELETE T WHERE X<>0

SQL_ATTR_DIRTYBIT_SET_MODE (DB2 Everyplace)

カーソル・タイプを指定する 32 ビット整数値。サポートされる値は次のとおりです。

SQL_DIRTYBIT_SET_BY_SYSTEM

これはシステム・デフォルトです。挿入、更新、または削除されたレコードは、それぞれ、INSERT、UPDATE、または DELETE に設定されたダーティー・ビットを持ちます。 SQL_DIRTYBIT_SET_BY_SYSTEM が設定されている場合、 $dirty 列の UPDATE は許可されていません。
SQL_DIRTYBIT_SET_BY_APPLICATION

レコードの挿入、更新、または削除の際のダーティー・ビットの設定は、アプリケーションが行います。各操作の意味は以下のとおりです。
UPDATE
システムは、アプリケーションが指定したとおりのダーティー・ビットを設定します。例えば、アプリケーションが以下のステートメントを実行した場合、表内のすべてのレコードは 0 (CLEAN) にリセットされます。
```
UPDATE T SET $dirty=0 WHERE $dirty>0
```
INSERT
新しく挿入されたレコードのダーティー・ビットが CLEAN に設定されます。
DELETE
SQL_DELETE_PHYSICAL_REMOVE を設定すると、DELETE はデータベースからレコードを物理的に削除します。それ以外の場合は、$dirty 列の値が DELETE に設定され、レコードはデータベース内に残ります。

例えば、レコードのダーティー・ビットをクリーンにするには、以下のステートメントを使用します。

SQLSetStmtAttr (stmt, SQL_ATTR_DIRTYBIT_SET_MODE, 
                SQL_DIRTYBIT_SET_BY_APPLICATION, 0)

次に、以下の SQL ステートメントを実行します。

UPDATE T SET $DIRTY=0 WHERE $DIRTY>0

一般的に、エンド・ユーザーによるデータベース更新のトラッキングにダーティー・ビットが必要とされないときは、アプリケーションで SQL_DIRTYBIT_SET_BY_APPLICATION を設定できます。

SQL_ATTR_READ_MODE (DB2 Everyplace)

カーソル・タイプを指定する 32 ビット整数値。サポートされる値は次のとおりです。

SQL_READ_EXCLUDE_MARKED_DELETE

これはシステム・デフォルトです。ダーティー・ビットが「delete」に設定されているすべてのレコードが SQL から隠されます。
SQL_READ_INCLUDE_MARKED_DELETE

これを設定すると、ダーティー・ビットが DELETE に設定されたレコードが、SQL の SELECT ステートメントから可視の状態になります。アプリケーションは、レコードのダーティー・ビットを調べることによって、アプリケーションの削除済みレコードとその他のレコードを区別することができます。

例えば、ダーティー・ビットが DELETE とマークされたレコードを含め、ダーティー・ビットが設定されているすべてのレコードを読み取るには、以下のステートメントを使用します。

SQLSetStmtAttr (stmt, SQL_ATTR_READ_MODE, SQL_READ_INCLUDE_MARKED_DELETE, 0)

次に、以下の SQL ステートメントを実行して、すべてのレコードを検索します。

SELECT * FROM T WHERE $dirty<>0

SQL_ATTR_REORG_MODE (DB2 Everyplace)

ユーザーが作成した表でのデータベースの自動再編成を実行するかどうか、および明示的な REORG SQL ステートメントを許可するかどうかを指定する 32 ビット整数値。サポートされる値は次のとおりです。

SQL_REORG_ENABLED - これはシステム・デフォルトです。データベースの再編成は、 DB2 Everyplace が実行することも、ユーザーが REORG SQL ステートメントを使用することによって明示的に実行することもできます。
SQL_REORG_DISABLED - REORG SQL ステートメントには制限があり、ユーザーが作成した表の自動データベース再編成は行われません。

このオプションをオープン・カーソルに指定することはできません。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

診断

表 85. SQLSetStmtAttr SQLSTATE

SQLSTATE	説明	解説
24000	カーソル状態が無効。	カーソルがすでにこのステートメント・ハンドルでオープンされている。
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数の実行または完了のサポートに必要なメモリーを割り当てることができない。
HY010	関数のシーケンス・エラー。	実行時データ (`SQLPrepare()` または `SQLExecDirect()`) の操作中に、関数が呼び出された。 BEGIN COMPOUND および END COMPOUND SQL 操作中に、関数が呼び出された。
HY014	ハンドル数の限界に到達済み。	内部リソースが原因で、DB2 CLI がハンドルを割り当てることができない。
HY090	無効なストリング長またはバッファー長。	名前の長さ引き数のいずれかの値が、ゼロより小であるが、SQL_NTS と等しくない。

制約事項

なし。

関連した解説