SQLSetEnvAttr 関数

適合 性
導入されたバージョン: ODBC 3.0 標準準拠: ISO 92

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

構文

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

引数

EnvironmentHandle
[入力]環境ハンドル。

属性
[入力]設定する属性。"コメント" に一覧表示されます。

ValuePtr
[入力]Attribute に関連付けられる値への ポインター。 Attribute の値に応じてValuePtr は 32 ビット整数値になるか、null で終る文字列を指します。

StringLength
[入力] ValuePtr が 文字列またはバイナリ バッファーをポイントする場合、この引数は *ValuePtr の長さである必要があります。 文字列データの場合、この引数には文字列内のバイト数が含まれている必要があります。

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

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、または SQL_INVALID_HANDLE。

診断

SQLSetEnvAttr が SQL_ERROR または SQL_SUCCESS_WITH_INFO を返す場合、関連付けられた SQLSTATE 値は、handleType が SQL_HANDLE_ENV で、ハンドルEnvironmentHandle である SQLGetDiagRec を呼び出すことによって取得できます。 次の表は、 通常 SQLSetEnvAttr によって返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前には、"(DM)" という表記が付きます。 特に指定しない限り、各 SQLSTATE 値に関連SQL_ERROR戻りコードは返されます。 ドライバーが環境属性をサポートしていない場合、エラーは接続時にのみ返されます。

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

(DM) Attribute 引数がSQL_ATTR_OUTPUT_NTSされ、 ValuePtr がSQL_FALSE

コメント

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

ValuePtr によって設定される 情報の形式は 、指定した属性によって異 なりますSQLSetEnvAttr は、null で終わりの文字列または 32 ビット整数値の 2 つの異なる形式の 1 つで属性情報を受け取ります。 各 の形式は、属性の説明に記載されています。

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

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

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

SQL_CP_OFF = 接続プールがオフになっている。 これは既定値です。

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

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

SQL_CP_DRIVER_AWARE = 使用可能な場合は、ドライバーの接続プール認識機能を使用します。 ドライバーが接続プールの認識をサポートしていない場合、SQL_CP_DRIVER_AWAREは無視されSQL_CP_ONE_PER_HENV使用されます。 詳細については、「ドライバー対応 接続プール」を参照してください。 一部のドライバーがサポートし、一部のドライバーが接続プール認識をサポートしていない環境では、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属性が生成されます。 接続プールが有効になると、アプリケーションは InputHandle 引数をに設定して SQLAllocHandle を呼び出すことによって、暗黙的な共有環境を割り当SQL_HANDLE_ENV。

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

また、環境で接続プールを有効にできます。 環境接続プールについては、次の点に注意してください。

- 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 コードを受け取る必要があります。
- SQLErrorSQLGetDiagField、または SQLGetDiagRec が呼び出された場合、ドライバーは ODBC 3.x SQLSTATE コードを返します。
- SQLTables の呼 び出しの CatalogName 引数 、検索パターンを受け入れる。
- ドライバー マネージャーでは、C データ型の機能拡張がサポートされています。 C データ型の機能拡張の詳細については、「 ODBC の C データ型」を参照してください

詳細については、「 ODBC 3.8 の新機能」を参照してください

SQL_OV_ODBC3 = ドライバー マネージャーとドライバーは、次の ODBC 3.x の動作を示 します。

- ドライバーは を返し、日付、時刻、およびタイムスタンプに対して ODBC 3.x コードを受け取る必要があります。
- SQLErrorSQLGetDiagField、または SQLGetDiagRec が呼び出された場合、ドライバーは ODBC 3.x SQLSTATE コードを返します。
- SQLTables の呼 び出しの CatalogName 引数 、検索パターンを受け入れる。
- ドライバー マネージャーでは、C データ型の機能拡張はサポートされていません。

SQL_OV_ODBC2 = ドライバー マネージャーとドライバーは、次の ODBC 2.x の動作を示 します。 これは、ODBC 3.x ドライバーを操作する ODBC 2.x アプリケーションで特 に便利 です。

- ドライバーは を返し、日付、時刻、およびタイムスタンプに対して ODBC 2.x コードを受け取る必要があります。
- SQLErrorSQLGetDiagField、または SQLGetDiagRec が呼び出された場合、ドライバーは ODBC 2.x SQLSTATE コードを返します。
- SQLTables の呼び出しの CatalogName 引数は、検索パターンを受け入れ "できません"。
- ドライバー マネージャーでは、C データ型の機能拡張はサポートされていません。

アプリケーションは、SQLHENV 引数を持つ関数を呼び出す前に、この環境属性を設定する必要があります。そうすると、SQLSTATE HY010 (関数シーケンス エラー) が返されます。 これらの環境フラグに対して追加の動作が存在するかどうかは、ドライバー固有です。

- 詳細については、「アプリケーションの ODBC バージョンと動作変更 の宣言」 を参照してください
SQL_ATTR_OUTPUT_NTS (ODBC 3.0) ドライバーが文字列データを返す方法を決定する 32 ビット整数。 このSQL_TRUE、ドライバーは null で終えた文字列データを返します。 このSQL_FALSE、ドライバーは null で終えた文字列データを返します。

この属性の既定値は SQL_TRUE。 SQLSetEnvAttr の呼び出しを呼び出して、SQL_TRUEを返SQL_SUCCESS。 SQLSetEnvAttr を呼び出して SQL_FALSE に設定すると、SQL_ERROR と SQLSTATE HYC00 が返されます (省略可能な機能は実装されていません)。
対象 解決方法については、
ハンドルの割り当て SQLAllocHandle 関数
環境属性の設定を返す SQLGetEnvAttr 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル
ODBC 3.8 の新機能