CLI の手引きおよび解説書

SQLSetEnvAttr - 環境属性を設定する

目的
仕様: DB2 CLI 2.1   ISO CLI

SQLSetEnvAttr() は、現行環境の環境属性を設定します。

構文

SQLRETURN   SQLSetEnvAttr    (SQLHENV           EnvironmentHandle, /* henv */
                              SQLINTEGER        Attribute,
                              SQLPOINTER        ValuePtr,          /* Value */
                              SQLINTEGER        StringLength);

関数引き数


表 164. SQLSetEnvAttr 引き数
データ・タイプ 引き数 使用法 説明
SQLHENV EnviornmentHandle 入力 環境ハンドル
SQLINTEGER Attribute 入力 設定する環境属性。属性とその説明のリストについては、『環境属性』を参照してください。
SQLPOINTER ValuePtr 入力 指定したい Attribute の値。
SQLINTEGER StringLength 入力 属性値が文字ストリングの場合は、バイト単位の ValuePtr の長さ。 Attribute にストリングを指示しないと、DB2 CLI は StringLength を無視します。

使用法

いったん設定されると、属性の値はこの環境でのすべての接続に影響します。

アプリケーションは、SQLGetEnvAttr() を呼び出すことで、現行の属性値を取得することができます。

環境属性

SQL_ATTR_CONNECTION_POOLING
環境レベルでの接続のプール処理を使用可能または使用不能にする 32 ビット整数値。使用される値は次のとおりです。

接続のプール処理は、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() を呼び出しているので、接続のプール処理が使用可能になり、アプリケーションの共用環境が選択された後には、この属性をリセットすることはできません。接続のプール処理が共用環境ですでに使用可能になっていて、この属性が設定されている場合、この属性の影響を受けるのはこの後に割り当てられる共用環境だけです。

SQL_ATTR_CONNECTTYPE

このアプリケーションを整合分散環境で実行するか、または非整合分散環境で実行するかを指定する 32 ビット整数値。処理を調整する必要がある場合、SQL_ATTR_SYNC_POINT 接続オプションとの組み合わせにおいて、このオプションを考慮に入れる必要があります。有効値は以下のとおりです。

この属性は、接続ハンドルを割り振る前に設定する必要があります。そうでなければ、SQLSetEnvAttr() 呼び出しは拒否されます。

アプリケーション内のすべての接続の SQL_ATTR_CONNECTTYPE 値と SQL_ATTR_SYNC_POINT 値は、同じ値でなければなりません。この属性は、SQLSetConnectAttr 関数を使用して設定することもできます。アプリケーションが SQL_ATTR_CONNECTTYPE 属性を設定するときに、接続レベルではなく、環境レベルで設定することをお勧めします。調整 DB2 トランザクションを利用するために書かれた ODBC アプリケーションは、 SQLSetEnvAttr() が ODBC でサポートされていないので、 SQLSetConnectAttr() を使用して各接続の接続レベルでこれらの属性を設定する必要があります。

注:これは、IBM 定義の拡張機能です。

SQL_ATTR_CP_MATCH
接続を接続プールから選択する方法を決定する 32 ビット値。 SQLConnect() または SQLDriverConnect() が呼び出されると、 DB2 CLI (または使用している場合はドライバー・マネージャー) はどの接続をプールから再利用するか決定します。 DB2 CLI (またはドライバー・マネージャー) は、呼び出しの接続オプション、アプリケーションがキーワードに設定した接続属性、およびプールにある接続の接続属性の突き合わせを試行します。この属性値で、突き合わせ基準の精度レベルが判別されます。

次の値を使用して、この属性値を設定します。

SQL_ATTR_MAXCONN
アプリケーションがセットアップしたい最大並行接続数に対応する 32 ビット整数値。省略時値は 0 で、これは最大値がないことを意味します。アプリケーションはシステム資源で許可される個数の接続を設定することができます。整数値は 0 または正の数でなければなりません。

これは、アプリケーション・ベースでの接続の最大数のための管理プログラムとして使用できます。

OS/2 で NetBIOS プロトコルが使用中の場合に、この値は、アプリケーションで並行してセットアップされる接続 (NetBIOS セッション) の数に対応します。 OS/2 NetBIOS の値の範囲は、1 から 254 です。 0 (省略時値) を指定すると、5 つの予約済み 接続が行われます。他のアプリケーションは、予約済み NetBIOS セッションを使用できません。このパラメーターで指定された接続数は、 DB2 NetBIOS プロトコルがリモート・サーバーに接続するのに使用するアダプターに適用されます (アダプター番号は NetBIOS ノードのノード・ディレクトリーで指定します)。

最初の接続が確立される時点で有効な値は、使用しようとしている値です。最初の接続がすでに確立されていると、この値を変更しようとしても拒否されます。アプリケーションが SQL_ATTR_MAXCONN を設定するときに、接続レベルではなく環境レベルで設定することをお勧めしてきました。 ODBC アプリケーションは、SQLSetEnvAttr() がサポートされていないので、接続レベルでこの属性を設定する必要があります。

注:これは、IBM 定義の拡張機能です。

SQL_ATTR_ODBC_VERSION
特定の機能性に ODBC 2.x (DB2 CLI v2) または ODBC 3.0 (DB2 CLI v5) の動作を示すかどうかを決定する 32 ビット整数。

すべての DB2 CLI アプリケーションでこの環境属性を設定するようお勧めします。 ODBC アプリケーションでは、SQLHENV 引き数が指定されている関数を呼び出す前に、この環境属性を設定しないと、呼び出しは SQLSTATE HY010 (関数の順序エラーです。) を戻します。

次の値を使用して、この属性値を設定します。

SQL_ATTR_OUTPUT_NTS
出力引き数におけるヌル終了の使用を制御する 32 ビット整数値。有効値は以下のとおりです。

この属性の影響を受ける CLI 関数は、文字ストリング・パラメーターのある環境 (およびその環境で割り振られている接続とステートメント) について呼び出されたすべての関数です。

この属性は、この環境に接続ハンドルが割り振られていないときにのみ、設定することができます。

SQL_ATTR_PROCESSCTRL
プロセスのすべての環境と接続に影響を与える、プロセス・レベル属性を設定する 32 ビット・マスク。この属性は、環境ハンドルが割り当てられる前に設定する必要があります。

SQLSetEntAttr() の呼び出しでは、 EnvironmentHandle 引き数を SQL_NULL_HANDLE に設定する必要があります。この設定は、プロセスの存続期間中はずっと有効です。一般に、この属性が使用されるのは、大量の CLI 呼び出しが行われる、パフォーマンスの影響を受けやすいアプリケーションについてだけです。以下のビットのいずれかを設定する前に、アプリケーションとアプリケーションが呼び出すその他のライブラリーが、列挙されている制約事項に従っていることを確認してください。

以下の値を組み合わせてビット・マスクを形成することができます。

SQL_ATTR_SYNC_POINT

アプリケーションが 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 をサポートする必要はありません。

SQL_ATTR_USE_2BYTES_OCTET_LENGTH
SQL_DESC_OCTET_LENGTH_PTR 記述子フィールド (APD または ARD のどちらかとして使用される) が、 2 バイト値と 4 バイト値 (省略時値) のどちらを指すポインターであるかを指定する、4 バイト整数値。有効値は以下のとおりです。

記述子フィールドの詳細については、SQLSetDescField - 記述子レコードの単一フィールドを設定するを参照してください。

この属性はいつでも設定することができ、記述子関数が次に呼び出されるときに有効となります。この属性は、SQLGetData() 呼び出しの StrLen_or_IndPtr 値には影響を与えません。
注:これは、IBM 定義の拡張機能です。

SQL_ATTR_USE_LIGHT_OUTPUT_SQLDA

列名がネットワークを介して送信されて、SQLDescribeCol()SQLColAttribute()、および SQLGetDescField() への呼び出しに対して戻されるかどうかを指定する 32 ビット整数値。有効値は以下のとおりです。

注:これは、IBM 定義の拡張機能です。

SQL_CONNECTTYPE
この Attribute は、 SQL_ATTR_CONNECTTYPE に置き換えられました。

SQL_MAXCONN
この Attribute は、 SQL_ATTR_MAXCONN に置き換えられました。

SQL_SYNC_POINT
この Attribute は、 SQL_ATTR_SYNC_POINT に置き換えられました。

戻りコード

診断


表 165. SQLSetEnvAttr SQLSTATE
SQLSTATE 説明 解説
HY009 引き数値が無効です。 fOption 値が与えられているので、引き数 vParam に指定されたのは無効な値でした。
HY011 この段階で操作は無効です。 環境ハンドルに関する接続ハンドルが割り振られている間は、アプリケーションは環境属性を設定できません。
HY024 無効な属性値。 指定済みの Attribute 値が与えられているので、 *ValuePtr に指定されたのは無効な値でした。
HY090 無効なストリングまたはバッファー長。 StringLength 引き数は 0 より小さい値でしたが、SQL_NTS ではありませんでした。
HY092 オプション・タイプが範囲外です。 無効な Attribute 値を指定しました。
HYC00 ドライバーが機能していません。 指定した Attribute は、DB2 CLI ではサポートされません。

指定済みの Attribute 値が与えられているので、引き数 ValuePtr に指定した値はサポートされません。

制約

なし。

CLI サンプル pcall.c

(ここで完全サンプル 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
                      ) ;
    
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]