SQLSetEnvAttr() - 環境属性を設定する
SQLSetEnvAttr() は、環境内の全接続に影響する属性を設定します。
SQLSetEnvAttr() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| なし | あり | あり |
構文
SQLRETURN SQLSetEnvAttr (SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHENV | EnvironmentHandle | 入力 | 環境ハンドル。 |
| SQLINTEGER | 属性 | 入力 | 設定する環境属性。 属性とその説明のリストについては 表 3 を 参照してください。 |
| SQLPOINTER | ValuePtr | 入力 | Attribute の値。 |
| SQLINTEGER | StringLength | 入力 | 属性値が文字ストリングの場合、ValuePtr の長さ (バイト単位)。Attribute が ストリングでない場合、Db2® ODBC は StringLength を無視します。 |
使用法
設定されると、属性値はこの環境内のすべての接続に影響します。
アプリケーションは、SQLGetEnvAttr() を呼び出して、現行の属性値を取得することができます。
表 3 は、SQLSetEnvAttr() の Attribute 値をリストしています。 太字で示されている値は、デフォルト値です。
Attribute 値は、ODBC 3.0 で名前変更されました。 ODBC 3.0 で名前変更された Attributes の要約については、『SQLSetEnvAttr() 属性の変更』を参照してください。
| 属性 | 内容 |
|---|---|
| SQL_ATTR_ODBC_VERSION | ある機能が ODBC 2.0 の動作であるかまたは ODBC 3.0 の動作であるかを
決定する、32 ビットの整数。
この値は、なんらかの接続ハンドルが割り当てられている間は変更することができません。
この属性の値を設定するには、次の値を使用します。
|
| SQL_ATTR_OUTPUT_NTS | 出力引数での NUL 終了の使用を制御する 32 ビット整数値。 可能な値には、以下のものがあります。
この属性は、この環境ハンドルのもとで接続ハンドルが割り振り割られていない場合のみ、 設定することができます。 |
| SQL_ATTR_CONNECTTYPE1 | このアプリケーションを整合して動く分散環境で実行するか、または協調せずに動く分散環境で
実行するかを指定する 32 ビット整数値。 可能な値には、以下のものがあります。
この属性は、接続ハンドルを割り当てる前に設定する必要があります。 そのようにしないと、SQLSetEnvAttr() 呼び出しはリジェクトされます。 アプリケーション内のすべての接続には、 SQL_ATTR_CONNECTTYPE および SQL_ATTR_SYNC_POINT 値が同じである必要があります。また、この属性は、SQLSetConnectAttr() 関数を使用して設定することもできます。 IBM® 固有: この属性は、IBM が規定した拡張機能です。 推奨事項: アプリケーションは、SQL_ATTR_CONNECTTYPE 属性を接続ごと設定せず、 環境レベルで設定するようにしてください。 整合して動く複数の Db2 トランザクションを利用するように作成された ODBC アプリケーション は、SQLSetEnvAttr() が ODBC でサポートされていない ため、SQLSetConnectAttr() を使用して、それぞれ の接続ごとに接続レベルでこれらの属性を設定する必要があります。 |
| SQL_ATTR_MAXCONN2 | アプリケーションがセットアップを希望する最大同時接続数に対応する 32 ビット整数値。
デフォルト値は 0 で、これは最大値がないことを
意味します。アプリケーションはシステム・リソースで許される
個数の接続を設定することができます。整数値は 0 または正数でなければなりません。
これは、アプリケーション単位の最大接続数の管理プログラムとして 使用することができます。 最初の接続が確立される時点で有効な値が、使用される値になります。 最初の接続が確立されると、この値を変更しようとするとリジェクトされます。 IBM 固有: この属性は、IBM が規定した拡張機能です。 推奨事項: アプリケーションは、SQL_ATTR_MAXCONN 属性を接続ごとに設定せず、 環境レベルで設定するようにしてください。ODBC ではこの属性がサポートされて いないため、ODBC アプリケーションは接続レベルでこの属性を設定する必要があります。 |
| 注:
|
|
戻りコード
- SQL_SUCCESS
- SQL_INVALID_HANDLE
- SQL_ERROR
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| HY009 | NULL ポインターの使用は無効です。 | ValuePtr に NULL ポインターが渡され、*ValuePtr の値はストリング値でした。 |
| HY011 | この時点では操作は無効です。 | 環境ハンドルに対して複数の接続ハンドルが割り当てられてい る間は、アプリケーションは環境属性を設定できません。 |
| HY024 | 属性値が無効です。 | 指定された Attribute 値について、無効な値が *ValuePtr に指定されました。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | StringLength 引数は 0 より小さい値ですが、SQL_NTS ではありません。 |
| HY092 | オプションのタイプが範囲外です。 | 引数 Attribute に指定された値は、Db2 ODBC のこのバージョンでは無効です。 |
| HYC00 | ドライバーは使用できません。 | 指定された Attribute は、Db2 ODBC でサポートされていません。指定された Attribute 値の場合、 引数 ValuePtr に指定された値はサポートされません。 |
例
SQLINTEGER output_nts,autocommit;
rc = SQLSetEnvAttr( henv,
SQL_ATTR_OUTPUT_NTS,
( SQLPOINTER ) output_nts,
0
) ;
CHECK_HANDLE( SQL_HANDLE_ENV, henv, rc );