SQLSetEnvAttr 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 3.0 Standards Compliance: 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 で、Handle of EnvironmentHandle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLSetEnvAttr によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 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_VERSION が SQLSetEnvAttr で設定されておらず、 属性 が SQL_ATTR_ODBC_VERSION と等しくありません。 SQLAllocHandleStd を使用している場合は、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 つの異なる形式のいずれかで属性情報を受け入れます。 それぞれの形式は、属性の説明に記載されています。

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

接続属性は、 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 引数を SQL_HANDLE_ENV に設定して SQLAllocHandle を呼び出して、暗黙的な共有環境を割り当てます。

接続プールが有効になり、アプリケーションに対して共有環境が選択されると、この属性を設定するときに 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 コードを返し、予期します。
- SQLError、SQLGetDiagField、または SQLGetDiagRec が呼び出されると、ドライバーは ODBC 3.xSQLSTATE コードを返します。
- SQLTables の呼び出しの CatalogName 引数は、検索パターンを受け入れます。
- ドライバー マネージャーでは、C データ型の拡張性がサポートされています。 C データ型の拡張性の詳細については、「 ODBC の C データ型」を参照してください。

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

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

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

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

- ドライバーは、日付、時刻、およびタイムスタンプの ODBC 2.x コードを返し、予期します。
- SQLError、SQLGetDiagField、または SQLGetDiagRec が呼び出されると、ドライバーは ODBC 2.xSQLSTATE コードを返します。
- 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_SUCCESSを返SQL_TRUEに設定します。 SQLSetEnvAttr を呼び出してそれを SQL_FALSE に設定すると、SQL_ERRORと SQLSTATE HYC00 が返されます (省略可能な機能は実装されていません)。
対象 解決方法については、
ハンドルの割り当て SQLAllocHandle 関数
環境属性の設定を返す SQLGetEnvAttr 関数

参照

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