仕様: | DB2 CLI 2.1 | ISO CLI |
SQLSetEnvAttr() は、現行環境の環境属性を設定します。
構文
SQLRETURN SQLSetEnvAttr (SQLHENV EnvironmentHandle, /* henv */ SQLINTEGER Attribute, SQLPOINTER ValuePtr, /* Value */ SQLINTEGER StringLength);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHENV | EnviornmentHandle | 入力 | 環境ハンドル |
SQLINTEGER | Attribute | 入力 | 設定する環境属性。属性とその説明のリストについては、『環境属性』を参照してください。 |
SQLPOINTER | ValuePtr | 入力 | 指定したい Attribute の値。 |
SQLINTEGER | StringLength | 入力 | 属性値が文字ストリングの場合は、バイト単位の ValuePtr の長さ。 Attribute にストリングを指示しないと、DB2 CLI は StringLength を無視します。 |
使用法
いったん設定されると、属性の値はこの環境でのすべての接続に影響します。
アプリケーションは、SQLGetEnvAttr() を呼び出すことで、現行の属性値を取得することができます。
接続のプール処理は、SQLSetEnvAttr() を呼び出して、 SQL_ATTR_CONNECTION_POOLING 属性を SQL_CP_ONE_PER_DRIVER または SQL_CP_ONE_PER_HENV に設定することによって使用可能になります。この呼び出しは、接続のプール処理が使用可能になっている共用環境をアプリケーションが割り振る前に呼び出してください。 SQLSetEnvAttr() への呼び出しの環境ハンドルがヌルに設定されているので、 SQL_ATTR_CONNECTION_POOLING が処理レベルの属性になります。接続のプール処理が使用可能になると、アプリケーションは、 InputHandle 引き数を SQL_HANDLE_ENV に設定して SQLAllocHandle() を呼び出すことにより、暗黙的に共用環境を割り当てます。
環境の SQL_ATTR_CONNECTION_POOLING 属性を設定するときにヌルの環境ハンドルを指定して SQLSetEnvAttr() を呼び出しているので、接続のプール処理が使用可能になり、アプリケーションの共用環境が選択された後には、この属性をリセットすることはできません。接続のプール処理が共用環境ですでに使用可能になっていて、この属性が設定されている場合、この属性の影響を受けるのはこの後に割り当てられる共用環境だけです。
このアプリケーションを整合分散環境で実行するか、または非整合分散環境で実行するかを指定する 32 ビット整数値。処理を調整する必要がある場合、SQL_ATTR_SYNC_POINT 接続オプションとの組み合わせにおいて、このオプションを考慮に入れる必要があります。有効値は以下のとおりです。
SQL_ATTR_SYNC_POINT 属性の現行設定は無視されます。
これが省略時値です。
この属性は、接続ハンドルを割り振る前に設定する必要があります。そうでなければ、SQLSetEnvAttr() 呼び出しは拒否されます。
アプリケーション内のすべての接続の SQL_ATTR_CONNECTTYPE 値と SQL_ATTR_SYNC_POINT 値は、同じ値でなければなりません。この属性は、SQLSetConnectAttr 関数を使用して設定することもできます。アプリケーションが SQL_ATTR_CONNECTTYPE 属性を設定するときに、接続レベルではなく、環境レベルで設定することをお勧めします。調整 DB2 トランザクションを利用するために書かれた ODBC アプリケーションは、 SQLSetEnvAttr() が ODBC でサポートされていないので、 SQLSetConnectAttr() を使用して各接続の接続レベルでこれらの属性を設定する必要があります。
注: | これは、IBM 定義の拡張機能です。 |
次の値を使用して、この属性値を設定します。
これは、アプリケーション・ベースでの接続の最大数のための管理プログラムとして使用できます。
OS/2 で NetBIOS プロトコルが使用中の場合に、この値は、アプリケーションで並行してセットアップされる接続 (NetBIOS セッション) の数に対応します。 OS/2 NetBIOS の値の範囲は、1 から 254 です。 0 (省略時値) を指定すると、5 つの予約済み 接続が行われます。他のアプリケーションは、予約済み NetBIOS セッションを使用できません。このパラメーターで指定された接続数は、 DB2 NetBIOS プロトコルがリモート・サーバーに接続するのに使用するアダプターに適用されます (アダプター番号は NetBIOS ノードのノード・ディレクトリーで指定します)。
最初の接続が確立される時点で有効な値は、使用しようとしている値です。最初の接続がすでに確立されていると、この値を変更しようとしても拒否されます。アプリケーションが SQL_ATTR_MAXCONN を設定するときに、接続レベルではなく環境レベルで設定することをお勧めしてきました。 ODBC アプリケーションは、SQLSetEnvAttr() がサポートされていないので、接続レベルでこの属性を設定する必要があります。
注: | これは、IBM 定義の拡張機能です。 |
すべての DB2 CLI アプリケーションでこの環境属性を設定するようお勧めします。 ODBC アプリケーションでは、SQLHENV 引き数が指定されている関数を呼び出す前に、この環境属性を設定しないと、呼び出しは SQLSTATE HY010 (関数の順序エラーです。) を戻します。
次の値を使用して、この属性値を設定します。
これが省略時値です。
この属性の影響を受ける CLI 関数は、文字ストリング・パラメーターのある環境 (およびその環境で割り振られている接続とステートメント) について呼び出されたすべての関数です。
この属性は、この環境に接続ハンドルが割り振られていないときにのみ、設定することができます。
SQLSetEntAttr() の呼び出しでは、 EnvironmentHandle 引き数を SQL_NULL_HANDLE に設定する必要があります。この設定は、プロセスの存続期間中はずっと有効です。一般に、この属性が使用されるのは、大量の CLI 呼び出しが行われる、パフォーマンスの影響を受けやすいアプリケーションについてだけです。以下のビットのいずれかを設定する前に、アプリケーションとアプリケーションが呼び出すその他のライブラリーが、列挙されている制約事項に従っていることを確認してください。
以下の値を組み合わせてビット・マスクを形成することができます。
アプリケーションが 1 フェーズ調整トランザクションと 2 フェーズ調整トランザクションの間で選択できるようにする 32 ビット整数値。有効値は以下のとおりです。
分散作業単位 (トランザクション) の詳細については、SQL 解説書 を参照してください。
アプリケーション内のすべての接続の SQL_ATTR_CONNECTTYPE 値と SQL_ATTR_SYNC_POINT 値は、同じ値でなければなりません。この属性も、SQLSetConnectAttr() 関数を使用して設定できます。アプリケーションがこれら 2 つの属性を設定するときに、接続レベルによってではなく、環境レベルで設定することをお勧めします。調整 DB2 トランザクションを利用するために書かれた ODBC アプリケーションは、 SQLSetEnvAttr() が ODBC でサポートされていないので、 SQLSetConnectAttr() を使用して各接続の接続レベルでこれらの属性を設定する必要があります。
注: | これは、IBM 拡張機能です。組み込み SQL では、SYNCPOINT NONE という追加の同期点設定があります。 SYNCPOINT NONE は、同じデータベースへの複数の接続を許可していないので、 SQL_ATTR_CONNECTTYPE 属性の SQL_CONCURRENT_TRANS 設定よりも限定された設定です。結果的に、DB2 CLI は SYNCPOINT NONE をサポートする必要はありません。 |
記述子フィールドの詳細については、SQLSetDescField - 記述子レコードの単一フィールドを設定するを参照してください。
この属性はいつでも設定することができ、記述子関数が次に呼び出されるときに有効となります。この属性は、SQLGetData() 呼び出しの StrLen_or_IndPtr 値には影響を与えません。
注: | これは、IBM 定義の拡張機能です。 |
列名がネットワークを介して送信されて、SQLDescribeCol()、SQLColAttribute()、および SQLGetDescField() への呼び出しに対して戻されるかどうかを指定する 32 ビット整数値。有効値は以下のとおりです。
注: | これは、IBM 定義の拡張機能です。 |
戻りコード
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
HY009 | 引き数値が無効です。 | fOption 値が与えられているので、引き数 vParam に指定されたのは無効な値でした。 |
HY011 | この段階で操作は無効です。 | 環境ハンドルに関する接続ハンドルが割り振られている間は、アプリケーションは環境属性を設定できません。 |
HY024 | 無効な属性値。 | 指定済みの Attribute 値が与えられているので、 *ValuePtr に指定されたのは無効な値でした。 |
HY090 | 無効なストリングまたはバッファー長。 | StringLength 引き数は 0 より小さい値でしたが、SQL_NTS ではありませんでした。 |
HY092 | オプション・タイプが範囲外です。 | 無効な Attribute 値を指定しました。 |
HYC00 | ドライバーが機能していません。 | 指定した Attribute は、DB2 CLI ではサポートされません。
指定済みの Attribute 値が与えられているので、引き数 ValuePtr に指定した値はサポートされません。 |
制約
なし。
(ここで完全サンプル pcall.c を使用することもできます 。)
/* From the CLI sample PCALL.C */ /* ... */ /* enable sending column names over the network */ sqlrc = SQLSetEnvAttr( henv, SQL_ATTR_USE_LIGHT_OUTPUT_SQLDA, ( SQLPOINTER ) SQL_FALSE, SQL_FALSE ) ;
参照