SQLGetEnvAttr 関数
準拠
導入されたバージョン: ODBC 3.0 Standards Compliance: ISO 92
まとめ
SQLGetEnvAttr は 、環境属性の現在の設定を返します。
構文
SQLRETURN SQLGetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
引数
EnvironmentHandle
[入力]環境ハンドル。
属性
[入力]取得する属性。
ValuePtr
[出力] Attribute で指定された属性の現在の値を返すバッファーへのポインター。
ValuePtr が NULL の場合でも、StringLengthPtr は ValuePtr が指すバッファーで返すことができる合計バイト数 (文字データの null 終端文字を除く) を返します。
BufferLength
[入力] ValuePtr が 文字列を指す場合、この引数は *ValuePtr の長さである必要があります。 *ValuePtr が整数の場合、 BufferLength は無視されます。 *ValuePtr が Unicode 文字列の場合 (SQLGetEnvAttrW を呼び出すとき)、BufferLength 引数は偶数である必要があります。 属性値が文字列でない場合、 BufferLength は使用されません。
StringLengthPtr
[出力] *ValuePtr で返すことができる合計バイト数 (null 終端文字を除く) を返すバッファーへのポインター。 属性値が文字列で、返すことができるバイト数が BufferLength 以上の場合、*ValuePtr のデータは BufferLength から null 終端文字の長さを引いた値に切り捨てられ、ドライバーによって null で終了されます。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLGetEnvAttr がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_ENVの HandleType と EnvironmentHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLGetEnvAttr によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | *ValuePtr で返されたデータは、 BufferLength から null 終端文字を引いた値に切り捨てられました。 *StringLengthPtr では、文字列値の長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY010 | 関数シーケンス エラー | (DM) SQL_ATTR_ODBC_VERSION は 、SQLSetEnvAttr を使用してまだ設定されていません。 SQLAllocHandleStd を使用している場合は、SQL_ATTR_ODBC_VERSIONを明示的に設定する必要はありません。 |
| HY013 | メモリ管理エラー | メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY092 | 無効な属性/オプション識別子 | 引数 Attribute に指定された値が、ドライバーでサポートされている ODBC のバージョンでは無効でした。 |
| HY117 | 不明なトランザクション状態が原因で接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | 引数 Attribute に指定された値は、ドライバーでサポートされている ODBC のバージョンに対して有効な ODBC 環境属性でしたが、ドライバーではサポートされていませんでした。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) EnvironmentHandle に対応するドライバーは、 関数をサポートしていません。 |
説明
属性の一覧については、「 SQLSetEnvAttr」を参照してください。 ドライバー固有の環境属性はありません。 Attribute が文字列を返す属性を指定する場合、ValuePtr は文字列を返すバッファーへのポインターである必要があります。 null 終端バイトを含む文字列の最大長は BufferLength バイトになります。
SQLGetEnvAttr は、割り当てと環境ハンドルの解放の間にいつでも呼び出すことができます。 環境のアプリケーションによって正常に設定されたすべての環境属性は、HandleType が SQL_HANDLE_ENV の EnvironmentHandle で SQLFreeHandle が呼び出されるまで保持されます。 ODBC 3*.x* では、複数の環境ハンドルを同時に割り当てることができます。 ある環境の環境属性は、別の環境が割り当てられている場合には影響を受けません。
Note
SQL_ATTR_OUTPUT_NTS環境属性は、標準準拠のアプリケーションでサポートされています。 SQLGetEnvAttr が呼び出されると、ODBC 3*.x* ドライバー マネージャーは常に、この属性のSQL_TRUEを返します。 SQL_ATTR_OUTPUT_NTSは、 SQLSetEnvAttr の呼び出しによってのみSQL_TRUEに設定できます。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 接続属性の設定を返す | SQLGetConnectAttr 関数 |
| ステートメント属性の設定を返す | SQLGetStmtAttr 関数 |
| 接続属性の設定 | SQLSetConnectAttr 関数 |
| 環境属性の設定 | SQLSetEnvAttr 関数 |
| ステートメント属性の設定 | SQLSetStmtAttr 関数 |