SQLSetEnvAttr() - 環境属性を設定する

SQLSetEnvAttr() は、環境内の全接続に影響する属性を設定します。

SQLSetEnvAttr() の ODBC 仕様

表 1. SQLSetEnvAttr() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
なし あり あり

構文

SQLRETURN  SQLSetEnvAttr (SQLHENV           EnvironmentHandle,
                          SQLINTEGER        Attribute,
                          SQLPOINTER        ValuePtr,
                          SQLINTEGER        StringLength);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLSetEnvAttr() の引数
データ・タイプ 引数 使用法 説明
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() 属性の変更』を参照してください。

表 3. 環境属性
属性 内容
SQL_ATTR_ODBC_VERSION ある機能が ODBC 2.0 の動作であるかまたは ODBC 3.0 の動作であるかを 決定する、32 ビットの整数。 この値は、なんらかの接続ハンドルが割り当てられている間は変更することができません。
この属性の値を設定するには、次の値を使用します。
  • SQL_OV_ODBC3 では、以下の ODBC 3.0 の動作となります。
    • Db2 ODBC は、日付、時刻、およびタイム・スタンプについて、ODBC 3.0 の データ・タイプ・コードを戻し、このタイプであるものと見なします。
    • Db2 ODBC は、SQLGetDiagRec() が呼び出されたときに、ODBC 3.0 SQLSTATE コードを戻します。
    • SQLTables() への呼び出しで、引数 CatalogName は、検索パターンを受け入れます。
  • SQL_OV_ODBC2 では、以下の ODBC 2.x の動作となります。
    • Db2 ODBC は、日付、時刻、およびタイム・スタンプについて、ODBC 2.x の データ・タイプ・コードを戻し、このタイプであるものとみなします。
    • Db2 ODBC は、SQLGetDiagRec() または SQLError() が呼び出されたときに、ODBC 2.0 SQLSTATE コードを戻します。
    • SQLTables() への呼び出しで、引数 CatalogName は、検索パターンを受け入れません。
SQL_ATTR_OUTPUT_NTS 出力引数での NUL 終了の使用を制御する 32 ビット整数値。 可能な値には、以下のものがあります。
  • SQL_TRUE: Db2 ODBC は、NUL 終了を使用して出力文字ストリングの長さを指示します。

    これはデフォルトです。

  • SQL_FALSE: Db2 ODBC は、出力文字ストリングで NUL 終了文字を使用しません。
この属性の影響を受ける CLI 関数は、文字ストリング・パラメーターのある 環境 (およびその環境で割り当てられている接続とステートメント) について呼び出されたすべての関数です。

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

SQL_ATTR_CONNECTTYPE1 このアプリケーションを整合して動く分散環境で実行するか、または協調せずに動く分散環境で 実行するかを指定する 32 ビット整数値。 可能な値には、以下のものがあります。
  • SQL_CONCURRENT_TRANS: それぞれの接続には、それ自体の コミット範囲があります。 トランザクションを協調することが強制的に行われることはありません。 あるアプリケーションが SQLEndTran() で環境ハンドルを使用して コミットを出し、一部の接続コミットが成功しなかった場合は、 そのアプリケーションがリカバリーを行う必要があります。 これは、『ODBC 接続モデルでの Db2 ODBC の制約事項』に記載されている制約事項に従属する CONNECT (タイプ 1) の意味構造に対応しています。

    これはデフォルトです。

  • SQL_COORDINATED_TRANS: アプリケーションは、複数のデータベース接続間で調整されたコミットとロールバックが行われるよう求めます。 上記の SQL_CONCURRENT_TRANS 設定とは対照的に、 アプリケーションは 1 つのデータベースにつき 1 つのオープン接続のみを許可されます。

この属性は、接続ハンドルを割り当てる前に設定する必要があります。 そのようにしないと、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 アプリケーションは接続レベルでこの属性を設定する必要があります。

注:
  1. ODBC 初期化ファイルの CONNECTTYPE キーワードを用いて、この属性のデフォルト値を 変更することができます。
  2. ODBC 初期化ファイルの MAXCONN キーワードを用いて、この属性のデフォルト値を 変更することができます。

戻りコード

SQLSetEnvAttr() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_INVALID_HANDLE
  • SQL_ERROR

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 4. SQLSetEnvAttr() の 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 に指定された値はサポートされません。

例

次の例では、SQLSetEnvAttr() を使用して、環境属性を設定します。 また、トピック『分散作業単位接続を確立するための関数』を参照してください。
SQLINTEGER output_nts,autocommit;
rc = SQLSetEnvAttr( henv,
                   SQL_ATTR_OUTPUT_NTS,
                   ( SQLPOINTER ) output_nts,
                   0
                  ) ;
CHECK_HANDLE( SQL_HANDLE_ENV, henv, rc );