次の方法で共有

SQLDrivers 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 2.0 Standards Compliance: ODBC

まとめ
SQLDrivers には、 ドライバーの説明とドライバー属性のキーワードが一覧表示されます。 この関数は、ドライバー マネージャーによってのみ実装されます。

構文

  
SQLRETURN SQLDrivers(  
     SQLHENV         EnvironmentHandle,  
     SQLUSMALLINT    Direction,  
     SQLCHAR *       DriverDescription,  
     SQLSMALLINT     BufferLength1,  
     SQLSMALLINT *   DescriptionLengthPtr,  
     SQLCHAR *       DriverAttributes,  
     SQLSMALLINT     BufferLength2,  
     SQLSMALLINT *   AttributesLengthPtr);

引数

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

方向
[入力]ドライバー マネージャーが一覧の次のドライバーの説明をフェッチするかどうか (SQL_FETCH_NEXT) または検索が一覧の先頭から開始されるかどうかを判断します (SQL_FETCH_FIRST)。

DriverDescription
[出力]ドライバーの説明を返すバッファーへのポインター。

DriverDescription が NULL の場合でも、DescriptionLengthPtr は、DriverDescription が指すバッファーで返すことができる文字数の合計 (文字データの null 終端文字を除く) を返します。

BufferLength1
[入力]*DriverDescription バッファーの長さ (文字数)。

DescriptionLengthPtr
[出力]*DriverDescription で返すことができる合計文字数 (null 終端文字を除く) を返すバッファーへのポインター。 返すことができる文字数が BufferLength1 以上の場合、*DriverDescription のドライバーの説明は BufferLength1 から null 終端文字の長さを引いた値に切り捨てられます。

DriverAttributes
[出力]ドライバー属性値ペアの一覧を返すバッファーへのポインター (「コメント」を参照)。

DriverAttributes が NULL の場合でも、AttributesLengthPtr は、DriverAttributes が指すバッファーで返すことができる合計バイト数 (文字データの null 終端文字を除く) を返します。

BufferLength2
[入力]*DriverAttributes バッファーの 長さ (文字数)。 *DriverDescription 値が Unicode 文字列の場合 (SQLDriversW を呼び出すとき)、BufferLength 引数は偶数である必要があります。

AttributesLengthPtr
[出力]*DriverAttributes で返すことができる合計バイト数 (null 終端バイトを除く) を返すバッファーへのポインター。 返すことができるバイト数が BufferLength2 以上の場合、*DriverAttributes 内の属性値ペアのリストは BufferLength2 から null 終端文字の長さを引いた値に切り捨てられます。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

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

SQLSTATE エラー 説明
01000 一般的な警告 (DM) ドライバー マネージャー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01004 文字列データ、右切り捨て (DM) バッファー *DriverDescription が、ドライバーの完全な説明を返すには十分な大きさではなかった。 したがって、説明は切り捨てられました。 ドライバーの完全な説明の長さは、*DescriptionLengthPtr で返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。

(DM) バッファー *DriverAttributes が属性値ペアの完全な一覧を返すには十分な大きさではなかった。 したがって、リストは切り捨てられました。 属性と値のペアの未入力リストの長さは、*AttributesLengthPtr で返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。
HY001 メモリ割り当てエラー (DM) ドライバー マネージャーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。
HY010 関数シーケンス エラー (DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。
HY013 メモリ管理エラー メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY090 文字列またはバッファーの長さが無効です (DM) 引数 BufferLength1 に指定された値が 0 未満でした。

(DM) 引数 BufferLength2 に指定された値が 0 より小さいか、1 以上でした。
HY103 無効な取得コード (DM) 引数 Direction に指定された値が、SQL_FETCH_FIRSTまたはSQL_FETCH_NEXTと等しくありません。
HY117 不明なトランザクション状態が原因で接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。

説明

SQLDrivers は 、*DriverDescription バッファーでドライバーの説明を返します。 キーワードと値のペアの一覧として、*DriverAttributes バッファー内のドライバーに関する追加情報を返します。 ドライバーのシステム情報に記載されているすべてのキーワードは、データ ソースの作成を求めるために使用される CreateDSN を除き、すべてのドライバーに対して返されます。そのため、省略可能です。 各ペアは null バイトで終了し、完全なリストは null バイトで終了します (つまり、2 つの null バイトがリストの末尾を示します)。 たとえば、C 構文を使用するファイル ベースのドライバーは、次の属性の一覧を返す場合があります ("\0" は null 文字を表します)。

FileUsage=1\0FileExtns=*.dbf\0\0

*DriverAttributes がリスト全体を保持するのに十分な大きさでない場合、リストは切り捨てられ、 SQLDrivers は SQLSTATE 01004 (データの切り捨て) を返し、リストの長さ (最後の null 終了バイトを除く) は *AttributesLengthPtr で返されます。

ドライバー属性キーワードは、ドライバーのインストール時にシステム情報から追加されます。 詳細については、「 ODBC コンポーネントのインストール」を参照してください。

アプリケーションは SQLDrivers を複数回呼び出して、すべてのドライバーの説明を取得できます。 ドライバー マネージャーは、システム情報からこの情報を取得します。 ドライバーの説明がなくなった場合、 SQLDrivers はSQL_NO_DATAを返します。 sqlDrivers がSQL_NO_DATAを返した直後に SQL_FETCH_NEXT で呼び出されると、最初のドライバーの説明が返されます。 アプリケーションが SQLDrivers によって返される情報をどのように使用するかについては、「データ ソースまたはドライバーの選択」を参照してください。

SQL_FETCH_NEXTが初めて呼び出されるときに SQLDrivers に渡された場合、 SQLDrivers は最初のデータ ソース名を返します。

SQLDrivers はドライバー マネージャーに実装されているため、特定のドライバーの標準準拠に関係なく、すべてのドライバーでサポートされます。

対象 解決方法については、
データ ソースへの接続に必要な値の検出と一覧表示 SQLBrowseConnect 関数
データ ソースに接続する SQLConnect 関数
データ ソース名を返す SQLDataSources 関数
接続文字列またはダイアログ ボックスを使用したデータ ソースへの接続 SQLDriverConnect 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル