SQLSetEnvAttr 関数

適合 性
導入バージョン:ODBC 3.0 規格準拠:ISO 92

Summary
SQLSetEnvAttr は環境の側面を制御する属性を設定します。

構文

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

引数

EnvironmentHandle
[入力]環境の取り扱い。

属性
[入力]「コメント」に記載されたセットへの帰属。

ValuePtr
[入力]属性 に関連付けられる値を指し示します。 Attributeの値によって、ValuePtr は32ビット整数値になるか、null終端文字文字列を指すことがあります。

StringLength
[入力] ValuePtr が文字文字列やバイナリバッファを指す場合、この引数は *ValuePtr の長さであるべきです。 文字文字列データの場合、この引数は文字列内のバイト数を含ませるべきです。

ValuePtrが整数の場合、StringLengthは無視されます。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

Diagnostics

SQLSetEnvAttrがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返すと、SQLGetDiagRecを呼び出し、HandleTypeをHandle(SQL_HANDLE_ENV)、Handle(environmentHandle)を付けて関連するSQLSTATE値を取得できます。 以下の表は 、SQLSetEnvAttr が通常返すSQLSTATE値を示し、それぞれをこの関数の文脈で説明しています。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。 ドライバが環境属性をサポートしていない場合、エラーは接続時にのみ返されます。

SQLSTATE エラー Description
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S02 オプション値の変更 ドライバーは ValuePtr で指定された値をサポートせず、類似の値を置き換えました。 (関数はSQL_SUCCESS_WITH_INFOを返します。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージには、エラーとその原因が記述されています。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。
HY009 null ポインターの使用が無効です Attribute引数は文字列値を必要とする環境属性を特定し、 ValuePtr 引数はnullポインタでした。
HY010 関数シーケンス エラー (DM) EnvironmentHandleに接続ハンドルが割り当てられました。

(DM) SQL_ATTR_ODBC_VERSION は SQLSetEnvAttr で設定されておらず、 属性 は SQL_ATTR_ODBC_VERSIONと等しくありません。 SQLAllocHandleStdを使っているなら、明示的にSQL_ATTR_ODBC_VERSIONを設定する必要はありません。
HY013 メモリ管理エラー メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY024 属性値が無効です 指定した Attribute 値を指定すると、 ValuePtr で無効な値が指定されました。
HY090 文字列またはバッファーの長さが無効です StringLengthの引数は0未満でしたが、SQL_NTSではありませんでした。
HY092 無効な属性/オプション識別子 (DM) 引数 Attribute に指定された値が、ドライバーでサポートされている ODBC のバージョンに対して無効でした。
HY117 不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 (DM) 中断状態の詳細については、「 SQLEndTran 関数を参照してください。
HYC00 省略可能な機能が実装されていません Attributeという引数に指定された値は、ドライバがサポートしているバージョンの有効なODBC環境属性でしたが、ドライバではサポートされていませんでした。

(DM) 属性 の議論はSQL_ATTR_OUTPUT_NTSし、 ValuePtr はSQL_FALSEでした。

Comments

アプリケーションは、環境に接続ハンドルが割り当てられていない場合のみ SQLSetEnvAttr を呼び出せます。 アプリケーションが環境のために正しく設定したすべての環境属性は、 SQLFreeHandle が環境上で呼び出されるまで持続します。 ODBC 3.xでは複数の環境ハンドルを同時に割り当てることができます。

ValuePtrによる情報セットの形式は、指定された属性に依存します。 SQLSetEnvAttr は、null終端文字文字列または32ビット整数値のいずれかの異なる形式で属性情報を受け入れます。 それぞれの形式は属性の説明に記載されています。

ドライバー固有の環境属性はありません。

接続属性は SQLSetEnvAttrの呼び出しで設定できません。 これを試みるとSQLSTATE HY092(無効な属性/オプション識別子)が返されます。

属性 ValuePtr コンテンツ
SQL_ATTR_CONNECTION_POOLING(ODBC 3.8) 環境レベルで接続プーリングを有効または無効にする32ビットのSQLUINTEGER値。 次の値が使用されます。

SQL_CP_OFF = 接続プーリングはオフです。 これが既定値です。

SQL_CP_ONE_PER_DRIVER = 各ドライバーごとに単一の接続プールがサポートされています。 プール内のすべての接続は1人のドライバーに関連付けられています。

SQL_CP_ONE_PER_HENV = 各環境ごとに単一の接続プールがサポートされています。 プール内のすべての接続は1つの環境に関連付けられています。

SQL_CP_DRIVER_AWARE = ドライバーの接続プール認識機能が利用可能であれば利用してください。 ドライバーが接続プール認識をサポートしていない場合、SQL_CP_DRIVER_AWAREは無視されSQL_CP_ONE_PER_HENVが使われます。 詳細については、Driver-Aware Connection Pooling を参照してください。 一部のドライバが対応し、一部がコネクションプール認識をサポートしない環境では、SQL_CP_DRIVER_AWAREはサポートドライバでコネクションプール認識機能を有効にすることができますが、これは接続プール認識機能をサポートしていないドライバーに対してSQL_CP_ONE_PER_HENV設定するのと同等です。

接続プーリングは 、SQLSetEnvAttr を呼び出してSQL_ATTR_CONNECTION_POOLING属性をSQL_CP_ONE_PER_DRIVERまたはSQL_CP_ONE_PER_HENVに設定することで有効になります。 この呼び出しは、アプリケーションが接続プールを有効にする共有環境を割り当てる前に行う必要があります。 SQLSetEnvAttrの呼び出しにおける環境ハンドルはnullに設定されており、SQL_ATTR_CONNECTION_POOLINGプロセスレベルの属性となります。 接続プーリングが有効化された後、アプリケーションは SQLAllocHandle を呼び出し、 InputHandle 引数をSQL_HANDLE_ENVに設定して暗黙の共有環境を割り当てます。

接続プーリングが有効化され、アプリケーション用の共有環境が選択された後、その環境SQL_ATTR_CONNECTION_POOLINGリセットできません。なぜなら、この属性を設定する際に SQLSetEnvAttr がヌル環境ハンドルで呼び出されるためです。 この属性が共有環境で既に接続プーリングが有効になっている状態で設定された場合、この属性はその後に割り当てられる共有環境にのみ影響します。

また、環境上で接続プーリングを有効にすることも可能です。 環境接続プーリングについて以下の点に注目してください:

- NULLハンドルでの接続プーリングの有効化はプロセスレベルの属性です。 その後割り当てられた環境は共有環境となり、プロセスレベルの接続プーリング設定を引き継ぎます。
- 環境が割り当てられた後も、アプリケーションは接続プールの設定を変更できます。
- 環境接続プーリングが有効で、接続のドライバーがドライバープーリングを使用している場合、環境プーリングが優先されます。

SQL_ATTR_CONNECTION_POOLINGはドライバーマネージャー内で実装されています。 ドライバーは必ずしもSQL_ATTR_CONNECTION_POOLINGを実装する必要はありません。 ODBC 2.0および3.0アプリケーションではこの環境属性を設定できます。

詳細については、「 ODBC Connection Pooling (ODBC 接続プール)」を参照してください。
SQL_ATTR_CP_MATCH(ODBC 3.0) 接続プールから接続を選択する方法を決定する32ビットのSQLUINTEGER値です。 SQLConnectまたはSQLDriverConnectが呼び出されると、ドライバーマネージャーはプールから再利用する接続を特定します。 ドライバーマネージャーは、呼び出し内の接続オプションとアプリケーションが設定した接続属性を、プール内の接続のキーワードや接続属性に照合しようとします。 この属性の値は、マッチング基準の精度レベルを決定します。

この属性の値を設定するために、以下の値が使用されます:

SQL_CP_STRICT_MATCH = 呼び出しの接続オプションとアプリケーションが設定した接続属性に正確に一致する接続のみを再利用します。 これが既定値です。

SQL_CP_RELAXED_MATCH = 接続文字列キーワードが一致する接続が使われることがあります。 キーワードは一致しなければなりませんが、すべての接続属性が一致している必要はありません。

ドライバマネージャーがプール接続に接続する際のマッチングの方法については、 SQLConnectを参照してください。 接続プールの詳細については、「 ODBC 接続プール」を参照してください。
SQL_ATTR_ODBC_VERSION(ODBC 3.0) 特定の機能がODBC 2.x の挙動を示すかODBC 3.x の挙動を示すかを決定する32ビット整数です。 この属性の値を設定するために、以下の値が使用されます:

SQL_OV_ODBC3_80 = ドライバーマネージャーとドライバーは以下のODBC 3.8の挙動を示します:

- 運転手が戻り、日付、時刻、タイムスタンプのODBC 3.x コードを期待します。
- SQLError、SQLGetDiagField、またはSQLGetDiagRecが呼び出されると、ドライバはODBC 3.x SQLSTATEコードを返します。
- SQLTablesへの呼び出しにおけるCatalogName引数は検索パターンを受け入れます。
- ドライバーマネージャーはCのデータ型拡張性をサポートしています。 Cのデータ型拡張性についての詳細は、 ODBCにおけるCデータ型を参照してください。

詳細については「 ODBC 3.8の最新情報」をご覧ください。

SQL_OV_ODBC3 = ドライバーマネージャーとドライバーは以下のODBC 3.x の挙動を示します:

- 運転手が戻り、日付、時刻、タイムスタンプのODBC 3.x コードを期待します。
- SQLError、SQLGetDiagField、またはSQLGetDiagRecが呼び出されると、ドライバはODBC 3.x SQLSTATEコードを返します。
- SQLTablesへの呼び出しにおけるCatalogName引数は検索パターンを受け入れます。
- ドライバーマネージャーはCのデータ型拡張性をサポートしていません。

SQL_OV_ODBC2 = ドライバーマネージャーとドライバーは以下のODBC 2.x の動作を示します。 これは特にODBC 3.xドライバーを扱うODBC 2.xアプリケーションに有用です。

- 運転手が戻ってきて、日付、時刻、タイムスタンプのODBC 2.x コードを期待します。
- SQLError、SQLGetDiagField、またはSQLGetDiagRecが呼び出されると、ドライバーはODBC 2.x SQLSTATEコードを返します。
- SQLTablesの呼び出しにおけるCatalogName引数は検索パターンを受け入れません。
- ドライバーマネージャーはCのデータ型拡張性をサポートしていません。

アプリケーションはSQLHENV引数を持つ関数を呼び出す前にこの環境属性を設定しなければならず、そうしないとSQLSTATE HY010(関数シーケンスエラー)を返します。 これらの環境フラグに追加の挙動が存在するかどうかはドライバーによって異なります。

- 詳細については、「 アプリケーションのODBCバージョン および 動作変更の宣言」を参照してください。
SQL_ATTR_OUTPUT_NTS(ODBC 3.0) 32ビット整数で、ドライバーが文字列データを返す方法を決めます。 SQL_TRUEした場合、ドライバはヌル終端の文字列データを返します。 SQL_FALSEの場合、ドライバは文字列データをヌル終端で返しません。

この属性はデフォルトでSQL_TRUEとなります。 SQLSetEnvAttrに呼び出してSQL_TRUEに設定するとSQL_SUCCESS返されます。 SQLSetEnvAttrに呼び出してSQL_FALSEに設定するとSQL_ERRORとSQLSTATE HYC00(オプション機能未実装)が返されます。
～についての情報 参照先
ハンドルの割り当て SQLAllocHandle 関数
環境属性の設定を返す SQLGetEnvAttr 関数

関連するコンテンツ

  • Last updated on