仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLSetStmtAttr() は、ステートメントに関連したオプションを設定します。特定の接続に関連したすべてのステートメントのオプションを設定するために、アプリケーションは、SQLSetConnectAttr() を呼び出すことができます。
構文
SQLRETURN SQLSetStmtAttr (SQLHSTMT StatementHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLINTEGER | Attribute | 入力 | 設定オプション。 『ステートメント属性』にリストされる。 |
SQLHSTMT | *ValuePtr | 入力 | Attribute が ODBC 定義の属性で、
ValuePtr が文字ストリングか 2 進バッファーを指している場合、この引き数の長さは *ValuePtr の長さにする必要があります。
Attribute が ODBC 定義の属性で、
ValuePtr が整数の場合、StringLength は無視されます。
Attribute が DB2 CLI 属性の場合、アプリケーションは、 StringLength 引き数の設定により、属性の性質を示します。 StringLength には以下の値が入ります。
|
SQLINTEGER | StringLength | 入力 | ValuePtr が文字ストリングまたは 2 進数バッファーへのポインターの場合、この引き数の長さは *ValuePtr になります。 ValuePtr が文字ストリングまたは 2 進数バッファー以外へのポインターの場合、 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 (オプション値が変更された) を戻します。たとえば、Attribute が SQL_ATTR_CONCURRENCY、 *ValuePtr が SQL_CONCUR_ROWVER で、データ・ソースがこれをサポートしない場合、 DB2 CLI は SQL_CONCUR_VALUES を代用し、SQL_SUCCESS_WITH_INFO を戻します。アプリケーションは SQLGetStmtAttr() を呼び出して、代用された値を判別します。
ValuePtr によって設定した情報の形式は、Attribute の指定により異なります。 SQLSetStmtAttr() が受け入れる属性情報の形式は、ヌルで終了する文字ストリングまたは 32 ビット整数値のいずれかです。それぞれの形式の注記は、その属性の説明にあります。この形式は、SQLGetStmtAttr() のそれぞれの属性ごとに戻される情報に適用されます。 SQLSetStmtAttr() の ValuePtr 引き数が指し示す文字ストリングの長さは、 StringLength です。
記述子の設定によってステートメント属性を設定する
多くのステートメント属性は、1 つまたは複数の記述子のヘッダー・フィールドにも対応しています。このような属性は、SQLSetStmtAttr() の呼び出しだけでなく、 SQLSetDescField() の呼び出しによっても設定可能です。 SQLSetDescField() ではなく SQLSetStmtAttr() を呼び出すことによってこれらのオプションを設定した方が、記述子ハンドルを取り出す必要がないので便利です。
注: | 1 つのステートメントに SQLSetStmtAttr() 呼び出しを行うと、他のステートメントにも影響します。それが生じるのは、ステートメントに関連した APD または ARD が明示的に割り当てられ、それらが他のステートメントにも関連しているような場合です。 SQLSetStmtAttr() は APD や ARD を変更するので、そのような変更は、この記述子が関連しているすべてのステートメントに適用されます。このような適用が不要な場合、アプリケーションでこの記述子と他のステートメントとの関連付けをなくして (SQLSetStmtAttr() を呼び出して、 SQL_ATTR_APP_ROW_DESC または SQL_ATTR_APP_PARAM_DESC フィールドを別の記述子ハンドルに設定して) から、再度 SQLSetStmtAttr() を呼び出します。 |
記述子フィールドでもあるステートメント属性が、 SQLSetStmtAttr() の呼び出しによって設定される場合、ステートメントに関連した記述子の対応フィールドも設定されます。設定されるフィールドは、 StatementHandle 引き数により識別されるステートメントに現に関連付けられている記述子だけに該当し、属性を設定しても、将来そのステートメントに関連付けられる記述子に影響が及ぶことはありません。ステートメント属性でもある記述子フィールドが、SQLSetDescField() によって設定される場合、対応するステートメント属性も設定されます。
ステートメント属性は、ステートメント・ハンドルがどの記述子に関連付けられているのかを判別します。ステートメントが割り当てられている場合 (SQLAllocHandle() を参照)、 4 つの記述子ハンドルが自動的に割り当てられ、そのステートメントに関連付けられます。明示的に割り当てられた記述子ハンドルは、ステートメントに関連付けることができます。これを行うには、 SQL_HANDLE_DESC の fHandleType で SQLAllocHandle() を呼び出して記述子ハンドルを割り当ててから、 SQLSetStmtAttr() を呼び出して記述子ハンドルをステートメントに関連付けます。
以下のステートメント属性は、記述子のヘッダー・フィールドに対応しています。
ステートメント属性 | ヘッダー・フィールド | 説明 |
---|---|---|
SQL_ATTR_PARAM_BIND_OFFSET_PTR | SQL_DESC_BIND_OFFSET_PTR | APD |
SQL_ATTR_PARAM_BIND_TYPE | SQL_DESC_BIND_TYPE | APD |
SQL_ATTR_PARAM_OPERATION_PTR | SQL_DESC_ARRAY_STATUS_PTR | APD |
SQL_ATTR_PARAM_STATUS_PTR | SQL_DESC_ARRAY_STATUS_PTR | IPD |
SQL_ATTR_PARAMS_PROCESSED_PTR | SQL_DESC_ROWS_PROCESSED_PTR | IPD |
SQL_ATTR_PARAMSET_SIZE | SQL_DESC_ARRAY_SIZE | APD |
SQL_ATTR_ROW_ARRAY_SIZE | SQL_DESC_ARRAY_SIZE | APD |
SQL_ATTR_ROW_BIND_OFFSET_PTR | SQL_DESC_BIND_OFFSET_PTR | ARD |
SQL_ATTR_ROW_BIND_TYPE | SQL_DESC_BIND_TYPE | ARD |
SQL_ATTR_ROW_OPERATION_PTR | SQL_DESC_ARRAY_STATUS_PTR | APD |
SQL_ATTR_ROW_STATUS_PTR | SQL_DESC_ARRAY_STATUS_PTR | IRD |
SQL_ATTR_ROWS_FETCHED_PTR | SQL_DESC_ROWS_PROCESSED_PTR | IRD |
現在定義されている属性とそれらが導入されている DB2 CLI のバージョンは、下記のとおりです。別のデータ・ソースも利用できるように、さらに多くが今後定義されるものと予想されます。
注: | DB2 CLI バージョン 2 のステートメント属性は、すべて名前変更されています。バージョン 2 では SQL_ で始まっていましたが、現在は SQL_ATTR_ になっています。 |
ステートメント・ハンドルで後続の SQLExecute() および SQLExecDirect() 呼び出しを行うための APD へのハンドル。この属性の初期値は、ステートメントの初期割り当て時に暗黙的に割り当てられる記述子です。この属性の値が SQL_NULL_DESC に設定されていると、明示的に割り当てられた APD ハンドルは、今まで関連付けられていたステートメント・ハンドルとの関連付けを断たれ、ステートメント・ハンドルは、暗黙的に割り当てられる APD ハンドルに戻ります。
この属性は、別のステートメントに暗黙的に割り当てられた記述子ハンドル、または同じステートメントで暗黙的に設定された別の記述子ハンドルには設定することができません。つまり、暗黙的に割り当てられた記述子ハンドルは、 1 つのステートメントまたは 1 つの記述子ハンドルにしか関連付けできないということです。
この属性は、接続レベルでは設定できません。
ステートメント・ハンドルでの以後の取り出しを行うための ARD へのハンドル。この属性の初期値は、ステートメントの初期割り当て時に暗黙的に割り当てられる記述子です。この属性の値が SQL_NULL_DESC に設定されていると、明示的に割り当てられた ARD ハンドルは、今まで関連付けられていたステートメント・ハンドルとの関連付けを断たれ、ステートメント・ハンドルは、暗黙的に割り当てられる ARD ハンドルに戻ります。
この属性は、別のステートメントに暗黙的に割り当てられた記述子ハンドル、または同じステートメントで暗黙的に設定された別の記述子ハンドルには設定することができません。つまり、暗黙的に割り当てられた記述子ハンドルは、 1 つのステートメントまたは 1 つの記述子ハンドルにしか関連付けできないということです。
この属性は、接続レベルでは設定できません。
指定のステートメントでの関数コールを非同期で実行するかどうかを指定する 32 ビット整数値。
関数が非同期で呼び出されると、元の関数が SQL_STILL_EXECUTING 以外のコードを戻すまでは、元の関数 SQLAllocHandle()、SQLCancel()、SQLSetStmtAttr()、 SQLGetDiagField()、SQLGetDiagRec()、または SQLGetFunctions() だけがそのステートメントで、またはそのステートメントに関連した接続で呼び出すことができます。そのステートメントで、またはそのステートメントに関連した接続で呼び出されるその他の関数は、 HY010 の SQLSTATE を伴う SQL_ERROR を戻します (関数順序エラー)。関数は、他のステートメントで呼び出せます。
DB2 CLI はステートメント・レベル非同期実行をサポートしているため、ステートメント属性 SQL_ATTR_ASYNC_ENABLE を設定できます。その初期値は、ステートメント・ハンドル割り当て時と同じ名前を持つ接続レベル属性値と同じです。
一般に、アプリケーションは、シングル・スレッドのオペレーティング・システム上で、非同期で関数を実行する必要があります。マルチ・スレッドのオペレーティング・システムの場合は、同じスレッドで非同期に実行するのではなく、別々のスレッドでアプリケーションを実行すべきです。マルチスレッドのオペレーティング・システムだけで動作する DB2 CLI アプリケーションは、非同期実行のサポートが必要ありません。詳しくは、マルチスレッドのアプリケーション作成、および CLI の非同期実行を参照してください。
以下の関数は、非同期で実行できます。
SQLColAttribute() SQLGetTypeInfo() SQLColumnPrivileges() SQLMoreResults() SQLColumns() SQLNumParams() SQLCopyDesc() SQLNumResultCols() SQLDescribeCol() SQLParamData() SQLDescribeParam() SQLPrepare() SQLExecDirect() SQLPrimaryKeys() SQLExecute() SQLProcedureColumns() SQLFetch() SQLProcedures() SQLFetchScroll() SQLPutData() SQLForeignKeys() SQLSetPos() SQLGetData() SQLSpecialColumns() SQLGetDescField() 1* SQLStatistics() SQLGetDescRec() 1* SQLTablePrivileges() SQLGetDiagField() SQLTables() SQLGetDiagRec() 1* これらの関数は、記述子がインプリメンテーション記述子であり、 アプリケーション記述子でない場合にのみ、非同期で呼び出せます。
非同期実行は、 ASYNCENABLE DB2 CLI/ODBC 構成キーワードを使用しても設定可能です。詳しくは、db2cli.ini の構成を参照してください。
このステートメント・ハンドルを指定して SQLExtendedFetch() を呼び出すときに使用するバインド方向を設定するための 32 ビット整数値。引き数 vParam に値 SQL_BIND_BY_COLUMN を指定すると、 列ごとのバインド が選択されます。構造体の長さまたは列のバインド先となるバッファーのインスタンスを指定する vParam に値を指定すると、 行ごとのバインド が選択されます。
行ごとのバインドで、vParam に指定される長さには、バインドされる列のすべてに対するスペースと、構造体やバッファーの埋め込みが入っていなければなりません。これは、バインドされる列のアドレスが指定の長さで増分された際に、必ず結果が次の行の同じ列の先頭を指すようにするためです。 (ANSI C の構造体または共用体で sizeof 演算子を使用する場合、この動作は保証されます。)
列ごとのバインドは、このオプションの省略時値です。
カーソルのクローズとオープンにかかる時間を短くするために、同じハンドルを使用して 2 番目のカーソルがオープンされると、 DB2 はオープンされているカーソルを自動的にクローズします。このように、クローズ要求がオープン要求と連結され、 2 つのステートメントが結合されて (2 つではなく) 1 つのネットワーク要求になると、ネットワーク・フローは少なくなります。
以前の CLI アプリケーションでは、カーソルが明示的にクローズされるように設計されているので、この省略時値は役立ちません。しかし、新しいアプリケーションでは、カーソルを明示的にクローズするのではなく、後続のオープン要求時に CLI にカーソルをクローズさせることによって、この動作を利用することができます。
カーソルの並行性を指定する 32 ビット整数値。
静的な転送専用カーソルについては、SQL_ATTR_CONCURRENCY の省略時値は、SQL_CONCUR_READ_ONLY です。キー・セット・カーソルの省略時値は、SQL_CONCUR_VALUES です。
この属性は SQLSetScrollOptions() の Concurrency 引き数を使用して設定することもできます。この属性は、オープン・カーソルには指定できません。
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() を呼び出すと、 SQLSTATE 01S02 (オプション値が変更された) が出されます。
指定した並行性がデータ・ソースにサポートされていないと、DB2 CLI は別の並行性を代用し、 SQLSTATE 01S02 (オプション値が変更された) を戻します。代用の順序は、以下のようにカーソルのタイプによって異なります。
注: | 以下の値も ODBC で定義されていますが、DB2 CLI ではサポートされません。
|
この StatementHandle に関連したカーソルを COMMIT 操作前と同じ位置に保存するかどうか、また、アプリケーションがステートメントを再実行しなくても取り出せるようにするかどうかを指定する 32 ビット整数値。
StatementHandle が最初に割り当てられるときの省略時値は、SQL_CURSOR_HOLD_ON です。
このオプションは、この StatementHandle に関連したオープン・カーソルがある場合には設定できません。
CURSORHOLD DB2 CLI/ODBC 構成キーワードを使用することによっても、カーソル保留を設定することができます。詳しくは、db2cli.ini の構成を参照してください。
注: | このオプションは、IBM 拡張機能です。 |
カーソル・タイプを指定する 32 ビット整数値。以下の値がサポートされています。
このオプションは、オープン・カーソルには指定できません。
指定したカーソル・タイプが、データ・ソースでサポートされていないと、 CLI は別のカーソル・タイプを代用し、SQLSTATE 01S02 (オプション値が変更された) を戻します。混合または動的カーソルについては、CLI は、キー・セットによって操作されるカーソルまたは静的カーソルをこの順で代用します。
注: | 以下の値も ODBC で定義されていますが、DB2 CLI ではサポートされません。
この値が使用されると、DB2 CLI は、ステートメント属性を SQL_CURSOR_STATIC SQL_CURSOR_FORWARD_ONLY に設定し、 SQLSTATE 01S02 (オプション値が変更された) を戻します。この場合、アプリケーションは SQLGetStmtAttr() を呼び出して、実際の値を照会する必要があります。 |
対応する実行要求が発行されるまで、PREPARE 要求を据え置きにするかどうかを指定します。
ターゲットの DB2 データベースまたは DDCS ゲートウェイが据え置き準備をサポートしていない場合、クライアントは、その接続の据え置き準備を使用不能にします。
省略時設定の動作は DB2 バージョン 2 から変更されました。現在は据え置き準備が省略時値になっており、必要なら明示的にオフにする必要があります。
注: | 据え置き準備を使用可能にすると、通常は SQLCA の PREPARE ステートメントの SQLERRD(3) と SQLERRD(4) に戻される行およびコスト見積もりがゼロになる可能性があります。このことは、これらの値を使用して SQL ステートメントを継続するかどうかを決めているユーザーにとって重要となります。 |
このオプションは、 CLI/ODBC オプション DB2ESTIMATE がゼロ以外の値に設定されていれば、オフになります。
DEFERREDPREPARE DB2 CLI/ODBC 構成キーワードを使用することによっても、据え置き準備を設定することができます。詳しくは、db2cli.ini の構成を参照してください。
注: | これは、IBM 定義の拡張機能です。 |
最後のレコードがクライアントに送られた際に、クライアントのカーソルをクローズせずにサーバーの一時カーソルを自動的にクローズできるようにするかどうかを指定します。
これによって、CLI/ODBC ドライバーは、カーソルがクローズしたことを認識できるため、明示的にクローズするためのステートメントを発行しなくても済み、ネットワーク要求を省略できるようになります。
このオプションをオンにすると、小さい結果セットをたくさん使用するアプリケーションの処理速度が向上します。
次の場合は、EARLYCLOSE 機能を使用しません。
EARLYCLOSE DB2 CLI/ODBC 構成キーワードを使用することによっても、優先クローズ機能を設定することができます。詳しくは、db2cli.ini の構成を参照してください。
注: | これは、IBM 定義の拡張機能です。 |
IPD の自動移植を実行するかどうかを指定する 32 ビット整数値。
ステートメント属性 SQL_ATTR_ENABLE_AUTO_IPD の省略時値は、 SQL_ATTR_AUTO_IPD 接続属性値と同じです。
接続属性 SQL_ATTR_ AUTO_IPD が SQL_FALSE の場合、ステートメント属性 SQL_ATTR_ENABLE_AUTO_IPD は SQL_TRUE に設定できません。
2 進数ブックマーク値を指すポインター。 SQL_FETCH_BOOKMARK に等しい fFetchOrientation で SQLFetchScroll() を呼び出すと、 DB2 CLI はこのフィールドからブックマークをピックアップします。このフィールドは、省略時で NULL ポインターになります。
IPD へのハンドル。この属性の値は、ステートメントの初期割り当て時に割り当てられる記述子です。アプリケーションではこの属性を設定できません。
この属性の検索は、SQLGetStmtAttr() の呼び出しで行えますが、 SQLSetStmtAttr() を呼び出して設定することはできません。
IRD へのハンドル。この属性の値は、ステートメントの初期割り当て時に割り当てられる記述子です。アプリケーションではこの属性を設定できません。
この属性の検索は、SQLGetStmtAttr() の呼び出しで行えますが、 SQLSetStmtAttr() を呼び出して設定することはできません。
DB2 CLI は純キー・セット・カーソルをサポートしているので、 SQL_KEYSET_SIZE ステートメントは無視されます。キー・セットのサイズを制限するには、アプリケーションは、 SQL_ATTR_MAX_ROWS 属性を 0 以外の値に設定することによって、結果セットのサイズを制限する必要があります。
単一文字または 2 進列から取り出せるデータの最大量に対応する 32 ビット整数値。 SQL_MAX_LENGTH に指定した値が使用可能なデータ量よりも小さいためにデータが切り捨てられる場合、 SQLGetData() の呼び出しまたは取り出しは SQL_SUCCESS_WITH_INFO および SQLSTATE 01004 (データ切り捨て) ではなく、 SQL_SUCCESS を戻します。 vParam の省略時値は 0 です。 0 の場合は、DB2 CLI が文字または 2 進形式のすべての使用可能データを戻そうとします。
照会からアプリケーションに戻す最大行数に対応する 32 ビット整数値。 vParam の省略時値は 0 です。 0 の場合は、すべてのデータが戻されます。
カタログ関数のストリング引き数をどのように扱うかを判別する 32 ビット整数値。
これが省略時値です。
リストの値を取る SQLTables() の TableType 引き数は、この属性に影響されません。
このステートメント属性は、DB2 CLI バージョン 5 以降では不要です。現在では、DB2 CLI は省略時で据え置き準備を使用するため、 SQLSetColAttributes() の機能性を必要としません。詳しくは、デフォルトでの据え置き準備を参照してください。
DB2 CLI が、結果セットの列属性を自動的に記述するか、SQLSetColAttributes() によってアプリケーションから通知されるまで待たなければならないかを指定する 32 ビット整数。
注: | これは、IBM 定義の拡張機能です。 |
DB2 CLI が SQL を走査してエスケープ文節のストリングを探すかどうかを指定する 32 ビット整数値。次の 2 つの有効値があります。
このアプリケーションは、送信する SQL ストリング内にベンダー・エスケープ・シーケンスを使用することがない場合に走査をオフにすることを選択できます。この選択を行うと、走査に関連したオーバーヘッド処理の一部が除かれます。
32 ビット整数値。 n を 0 より大きい整数に設定すると、 "OPTIMIZE FOR n ROWS" 文節がすべての選択ステートメントに付加されます。 n を 0 (省略時値) に設定すると、この文節は追加されません。
OPTIMIZE FOR n ROWS ステートメントの影響に関する詳細については、 管理の手引き を参照してください。
この値は、 OPTIMIZEFORNROWS DB2 CLI/ODBC 構成キーワードを使用して設定することもできます。詳しくは、db2cli.ini の構成を参照してください。
32 ビット整数。
呼び出しが最適化されると、 SQLColumns() からの COLUMN_DEF 情報 (列の省略時ストリングが入っている) は戻されず、 AS/400 NUMERIC 列のデータ・タイプが SQL_DECIMAL として戻されます。
この値は、 OPTIMIZESQLCOLUMNS DB2 CLI/ODBC 構成キーワードを使用して設定することもできます。詳しくは、db2cli.ini の構成を参照してください。
動的パラメーターのバインドを変更するためにポインターに追加されるオフセットを示す 32 ビット整数 * 値。このフィールドが非ヌルの場合、DB2 CLI はポインターを据え置きし、据え置き値を記述子レコード (SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、および SQL_DESC_OCTET_LENGTH_PTR) の各据え置きフィールドに追加し、バインド時に新しいポインター値を使用します。これは省略時でヌルに設定されます。
バインド・オフセットは、常に SQL_DESC_DATA_PTR、 SQL_DESC_INDICATOR_PTR、および SQL_DESC_OCTET_LENGTH_PTR フィールドに直接追加されます。オフセットを別の値に変更しても、新しい値が記述子フィールドの値に直接追加されます。新しいオフセットは、以前のオフセットを加えたフィールド値に追加されることはありません。
このステートメント属性を設定すると、 APD ヘッダーに SQL_DESC_BIND_OFFSET_PTR フィールドが設定されます。
バインド方向を動的パラメーターに使用することを示す 32 ビット整数値。
このフィールドを SQL_PARAMETER_BIND_BY_COLUMN (省略時値) に設定して、列ごとのバインドを選択します。
行ごとのバインドを選択するには、このフィールドを構造体の長さか、または、動的パラメーターのセットにバインドされるバッファーのインスタンス長に設定します。この長さには、バインドされるパラメーターのすべてに対するスペースと、構造体やバッファーの埋め込みが入っていなければなりません。これは、バインドされるパラメーターのアドレスを指定の長さで増分した際に、必ず結果が次のパラメーター・セットの同じパラメーターの先頭を指し示すようにするためです。 ANSI C の sizeof 演算子を使用する場合、この動作は保証されます。
このステートメント属性を設定すると、 APD ヘッダーに SQL_DESC_ BIND_TYPE フィールドが設定されます。
SQL ステートメントの実行時にパラメーターを無視するために使用される 16 ビット無符号整数値の配列を示す 16 ビット無符号整数 * 値。それぞれの値は、SQL_PARAM_PROCEED (パラメーターを実行する) か、または SQL_PARAM_IGNORE (パラメーターを無視する) に設定します。
APD の SQL_DESC_ARRAY_STATUS_PTR が指し示す配列の状況値を SQL_PARAM_IGNORE に設定することによって、処理中にパラメーターのセットを無視することができます。状況値が SQL_PARAM_PROCEED に設定されているか、配列のどの要素も設定されていなければ、パラメーターのセットが処理されます。
このステートメント属性は NULL ポインターに設定可能です。その場合、DB2 CLI はパラメーター状況値を戻しません。この属性はいつでも設定可能ですが、設定した値は、次に SQLExecDirect() または SQLExecute() を呼び出すまで使用されません。
このステートメント属性を設定すると、 APD に SQL_DESC_ARRAY_STATUS_PTR フィールドが設定されます。
SQLExecute() または SQLExecDirect() の呼び出し後、パラメーター値の各行ごとの状況に関する情報の入った UWORD 値の配列を示す 16 ビット無符号整数 * 値。このフィールドは、PARAMSET_SIZE が 1 より大きい場合にのみ必要です。
状況値には以下の値が入ります。
このステートメント属性は NULL ポインターに設定可能です。その場合、DB2 CLI はパラメーター状況値を戻しません。この属性はいつでも設定可能ですが、設定した値は、次に SQLFetch()、 SQLFetchScroll()、または SQLSetPos() を呼び出すまで使用されません。
このステートメント属性を設定すると、 IPD ヘッダーに SQL_DESC_ARRAY_STATUS_PTR フィールドが設定されます。
SQLParamOptions() を使用してパラメーター・マーカーの複数値を指定した場合に、基礎処理の実行を ATOMIC と NOT-ATOMIC 複合 SQL のどちらを介して行うかを判別する 32 ビット整数値。有効値は以下のとおりです。
ATOMIC 複合 SQL は、以下のものでは使用することができません。バージョン 2.1 以前の共通サーバー用の DB2 または DRDA サーバー。上記のサーバーの 1 つに接続されるときに SQL_ATOMIC_YES を指定すると、エラーになります。 (SQLSTATE は S1C00 です。)
現在行の番号を戻すべきバッファーを示す 32 ビット無符号整数 * レコード・フィールド。パラメーターの各行が処理されていく際に、これはその行番号に設定されます。これがヌル・ポインターであれば、行番号は返されません。
このステートメント属性を設定すると、 IPD ヘッダーに SQL_DESC_ROWS_PROCESSED_PTR フィールドが設定されます。
各パラメーターごとの値の数を指定する 32 ビット無符号整数値。 SQL_ATTR_PARAMSET_SIZE が 1 より大きい場合、APD の SQL_DESC_DATA_PTR、 SQL_DESC_INDICATOR_PTR、および SQL_DESC_OCTET_LENGTH_PTR は配列を示します。各配列のカーディナリティーは、このフィールドの値と同等です。
このステートメント属性を設定すると、APD ヘッダーに SQL_DESC_ARRAY_SIZE フィールドが設定されます。
サーバーが、現行ブロックの送信直後にデータの次のブロックを事前取り出しするかどうか (サーバーがサポートしている場合) を決める 32 ビット値。この値を指定すると、アプリケーションが現行ブロックを受信している間に、サーバーはデータの次のブロックを入手するようになります。
結果セット全体がデータの最初のブロックに収まる場合、またはカーソルが非ブロック・カーソル (たとえば、FOR UPDATE カーソルである場合、または結果に LOB データが入っている場合) である場合は、この設定は無効になります。
有効値は以下のとおりです。
SQLPrepare()、SQLExtendedPrepare()、または SQLExecDirect() の次の呼び出しで照会最適化レベルが使用されるように設定する 32 ビット整数値。
使用されている現行値は、0、1、2、3、5、7、および 9 です。照会最適化レベルの詳細については、 SQL 解説書 の SET CURRENT QUERY OPTIMIZATION コマンドを参照してください。
アプリケーションに戻る前に、 SQL ステートメントが実行されるまで待機する秒数を示す 32 ビット整数値。 Windows 3.1 以外では、DB2 CLI は 0 しかサポートしません。 0 はタイムアウトがないという意味です。
注: | Windows 3.1 上では、このオプションを設定して、長時間の照会を終了させることができます。このオプションを指定すると、基礎となる Windows 3.1 接続コードはダイアログ・ボックスを表示して、指定秒数が経過したことを知らせ、照会の続行または中断のいずれかを指定するようプロンプトが出されます。
このオプションは Windows 3.1 以外のプラットフォームでは無効であり、 S1C00 が戻されます。 |
32 ビット整数値。
SQL_RETRIEVE_DATA を SQL_RD_OFF に設定することにより、アプリケーションは行が存在するかどうかを検査したり、あるいは検索行のオーバーヘッドを損なわずにブックマークを検索して行を探すことができます。
行セット内の行数を指定する 32 ビット整数値。これは、 SQLFetch() または SQLFetchScroll() への呼び出しのたびに戻される行数です。省略時値は 1 です。
指定した行セット・サイズが、データ・ソースでサポートされる最大行セット・サイズを超えると、 DB2 CLI はその値を代用し、SQLSTATE 01S02 (オプション値が変更された) を戻します。
このオプションはオープン・カーソルに指定でき、 SQLSetScrollOptions() の RowsetSize 引き数を使用して設定することもできます。
このステートメント属性を設定すると、 ARD ヘッダーに SQL_DESC_ARRAY_SIZE フィールドが設定されます。
列データのバインドを変更するためにポインターに追加されるオフセットを示す 32 ビット整数 * 値。このフィールドが非ヌルの場合、DB2 CLI はポインターを据え置きし、据え置き値を記述子レコード (SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、および SQL_DESC_OCTET_LENGTH_PTR) の各据え置きフィールドに追加し、バインド時に新しいポインター値を使用します。これは省略時でヌルに設定されます。
このステートメント属性を設定すると、 ARD ヘッダーに SQL_DESC_BIND_OFFSET_PTR フィールドが設定されます。
関連ステートメントで SQLFetch() または SQLFetchScroll() を呼び出すときに使用するバインド方向を設定するための 32 ビット整数値。引き数 *ValuePtr に定義済み定数 SQL_BIND_BY_COLUMN を指定すると、列ごとのバインドが選択されます。構造体の長さまたは列のバインド先となるバッファーのインスタンスを指定する *ValuePtr に値を指定すると、行ごとのバインドが選択されます。
*ValuePtr に指定される長さには、バインドされる列のすべてに対するスペースと、構造体やバッファーの埋め込みが入っていなければなりません。これは、バインドされる列のアドレスを指定の長さで増分した際に、必ず結果が次の行の同じ列の先頭を示すようにするためです。 ANSI C の構造体または共用体で sizeof 演算子を使用する場合、この動作は保証されます。
列ごとのバインドは、 SQLFetch() および SQLFetchScroll() の省略時のバインド方向です。
このステートメント属性を設定すると、 ARD ヘッダーに SQL_DESC_BIND_TYPE フィールドが設定されます。
結果セット全体の現在行の番号を示す 32 ビット整数値。現在行の番号を判別できないか、現在行がない場合、DB2 CLI は 0 を戻します。
この属性の検索は、SQLGetStmtAttr() の呼び出しで行えますが、 SQLSetStmtAttr() を呼び出して設定することはできません。
SQLSetPos() を使用するバルク操作時に行を無視するための UDWORD 値の配列を示す 16 ビット無符号整数 * 値。それぞれの値は、 SQL_ROW_PROCEED (バルク操作時に行を含める) または SQL_ROW_IGNORE (バルク操作時に行を除外する) に設定されます。
このステートメント属性は NULL ポインターに設定可能です。その場合、DB2 CLI は行状況値を戻しません。この属性はいつでも設定可能ですが、設定した値は、次に SQLFetch()、SQLFetchScroll()、または SQLSetPos() を呼び出すまで使用されません。
このステートメント属性を設定すると、 ARD に SQL_DESC_ARRAY_STATUS_PTR フィールドが設定されます。
SQLFetch() または SQLFetchScroll() の呼び出し後、行状況値の入った UWORD 値の配列を示す 16 ビット無符号整数 * 値。この配列の要素の数は、行セット内にある行の数と同じです。
このステートメント属性は NULL ポインターに設定可能です。その場合、DB2 CLI は行状況値を戻しません。この属性はいつでも設定可能ですが、設定した値は、次に SQLFetch()、SQLFetchScroll()、または SQLSetPos() を呼び出すまで使用されません。
このステートメント属性を設定すると、 IRD ヘッダーに SQL_DESC_ARRAY_STATUS_PTR フィールドが設定されます。
これは、 SQLFetch() または SQLFetchScroll() への呼び出し後、取り出した行数を戻すべきバッファーを示す 32 ビット無符号整数 * 値。
このステートメント属性を設定すると、 IRD ヘッダーに SQL_DESC_ROWS_PROCESSED_PTR フィールドが設定されます。
SQLExtendedFetch() の呼び出し時、この属性は DB2 CLI により RowCountPtr 配列にマップされます。
現在、DB2 CLI アプリケーションは、 SQLExtendedFetch() ではなく SQLFetchScroll() を使用すべきです。また、アプリケーションでは行セットに行数を設定するために、ステートメント属性として SQL_ATTR_ROW_ARRAY_SIZE を使用してください。詳しくは 結果セットから返される行セットの指定を参照してください。
行セット内の行数を指定する 32 ビット整数値。行セットは、SQLExtendedFetch() の呼び出しのたびに戻される行の配列です。省略時値は 1 であり、これは単一の SQLFetch() を行うことと同等です。このオプションは、カーソルがオープンであるときでも指定することができ、次の SQLExtendedFetch() 呼び出しで有効になります。
このステートメント属性は、DB2 CLI ではサポートされませんが、 ODBC により定義されています。
シミュレートされた定位置の更新および削除ステートメントの影響を、単一行だけにとどめるかどうかを指定する 32 ビット整数値。
現行の StatementHandle にトランザクション分離レベルを設定する 32 ビット整数値。
このオプションは、このステートメント・ハンドルに関するオープン・カーソルがある場合には設定できません (SQLSTATE 24000)。
値 SQL_ATTR_STMTTXN_ISOLATION は、SQL_ATTR_TXN_ISOLATION と同義です。ただし、ODBC ドライバー・マネージャーは、ステートメント・オプションとしての SQL_ATTR_TXN_ISOLATION の設定を拒否するので、各ステートメントごとにトランザクション分離レベルを設定しなければならない ODBC アプリケーションでは、 SQLSetStmtAttr() 呼び出しで、代わりに明示定数 SQL_ATTR_STMTTXN_ISOLATION を使用する必要があります。
トランザクション分離レベルは、 TXNISOLATION DB2 CLI/ODBC 構成キーワードを使用して設定することもできます。詳しくは、db2cli.ini の構成を参照してください。
この属性 (または対応するキーワード) を使用できるのは、省略時の分離レベルが使用される場合だけです。アプリケーションが分離レベルを設定する場合は、この属性を設定しても効果はありません。
注: | IBM 拡張機能により、このオプションをステートメント・レベルに設定することができます。 |
アプリケーションがカーソルでブックマークを使用するかどうかを指定する 32 ビット整数値。
カーソルでブックマークを使用するには、アプリケーションは、カーソルのオープン前にこのオプションで SQL_UB_VARIABLE 値を指定する必要があります。
戻りコード
診断
表 171. SQLSetStmtAttr SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
01S02 | オプション値が変更されました。 | DB2 CLI は *ValuePtr の指定値をサポートしていないか、または *ValuePtr の指定値が SQL の制約および要件にかなっていないため、 DB2 CLI が同等の値を代用しました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
08S01 | 通信リンクに障害が起きました。 | 関数が処理を完了する前に、DB2 CLI とその接続先データ・ソースとの間の通信リンクが失敗しました。 |
24000 | カーソル状態が無効です。 | Attribute が、SQL_ATTR_CONCURRENCY、SQL_ATTR_CURSOR_TYPE、 SQL_ATTR_SIMULATE_CURSOR、または SQL_ATTR_USE_BOOKMARKS であり、カーソルがオープンしていました。 |
HY000 | 一般的なエラーです。 | 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。 |
HY009 | 引き数値が無効です。 | ValuePtr に NULL ポインターが渡され、*ValuePtr の値がストリング属性でした。 |
HY010 | 関数の順序エラーです。 | StatementHandle の非同期実行関数が呼び出され、この関数が呼び出された時点でまだ実行中でした。
StatementHandle のために SQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。 |
HY011 | この段階で操作は無効です。 | Attribute が、SQL_ATTR_CONCURRENCY、SQL_ATTR_CURSOR_TYPE、 SQL_ATTR_SIMULATE_CURSOR、または SQL_ATTR_USE_BOOKMARKS であり、ステートメントが準備済みでした。 |
HY017 | 自動割り振りの記述子ハンドルについて無効な使用です。 | Attribute 引き数が SQL_ATTR_IMP_ROW_DESC または SQL_ATTR_IMP_PARAM_DESC でした。 Attribute 引き数が SQL_ATTR_APP_ROW_DESC または SQL_ATTR_APP_PARAM_DESC であり、 *ValuePtr の値が、暗黙的に割り当てられた記述子ハンドルでした。 |
HY024 | 属性値が無効です。 | 指定済みの Attribute 値が与えられているので、 *ValuePtr に指定されたのは無効な値でした。 (DB2 CLI がこの SQLSTATE を戻すのは、 SQL_ATTR_ACCESS_MODE や SQL_ATTR_ASYNC_ENABLE などの離散的な値セットを受け入れる接続およびステートメント属性に対してのみです。その他すべての接続およびステートメント属性に対しては、ドライバーで *ValuePtr の指定値を検査する必要があります。) |
HY090 | ストリングまたはバッファー長が無効です。 | StringLength 引き数は 0 より小さい値でしたが、SQL_NTS ではありませんでした。 |
HY092 | オプション・タイプが範囲外です。 | DB2 CLI のこのバージョンでは、引き数 Attribute の指定値が無効です。 |
HYC00 | ドライバーが機能していません。 | 引き数 Attribute に指定された値は、このバージョンの DB2 CLI ドライバーには有効な接続またはステートメント属性でしたが、データ・ソースによりサポートされていませんでした。 |
制約
なし。
例
SQLFetchScroll() を参照してください。
参照