SQLDataSources 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92
まとめ
SQLDataSources は、 データ ソースに関する情報を返します。 この関数は、ドライバー マネージャーによってのみ実装されます。
構文
SQLRETURN SQLDataSources(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT * NameLength1Ptr,
SQLCHAR * Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT * NameLength2Ptr);
引数
EnvironmentHandle
[入力]環境ハンドル。
方向
[入力]ドライバー マネージャーが情報を返すデータ ソースを決定します。 次の値をとります。
SQL_FETCH_NEXT (リスト内の次のデータ ソース名をフェッチする)、SQL_FETCH_FIRST (リストの先頭からフェッチする場合)、SQL_FETCH_FIRST_USER (最初のユーザー DSN をフェッチする場合)、またはSQL_FETCH_FIRST_SYSTEM (最初のシステム DSN をフェッチする場合) をSQL_FETCH_FIRST_USERします。
Direction が SQL_FETCH_FIRST に設定されている場合、Direction が SQL_FETCH_NEXT に設定されたSQLDataSources の後続の呼び出しでは、ユーザー DSN とシステム DSN の両方が返されます。 Direction が SQL_FETCH_FIRST_USER に設定されている場合、Direction が に設定されている SQLDataSources の後続のすべての呼び出しでは、ユーザー DSN のみが返SQL_FETCH_NEXT。 Direction が SQL_FETCH_FIRST_SYSTEM に設定されている場合、Direction が に設定されている SQLDataSources に対する後続のすべての呼び出しでは、システム DSN のみが返SQL_FETCH_NEXT。
ServerName
[出力]データ ソース名を返すバッファーへのポインター。
ServerName が NULL の場合、NameLength1Ptr は引き続き、ServerName が指すバッファーで返すために使用できる文字数 (文字データの null 終端文字を除く) を返します。
BufferLength1
[入力]*ServerName バッファーの長さ (文字数)。これは、SQL_MAX_DSN_LENGTHに null 終端文字を加えたものより長くする必要はありません。
NameLength1Ptr
[出力]*ServerName で返すために使用できる文字数 (null 終了文字を除く) を返すバッファーへのポインター。 返される文字数が BufferLength1 以上の場合、*ServerName のデータ ソース名は BufferLength1 から null 終端文字の長さを引いた値に切り捨てられます。
説明
[出力]データ ソースに関連付けられているドライバーの説明を返すバッファーへのポインター。 たとえば、dBASE や SQL Serverなどです。
Description が NULL の場合、NameLength2Ptr は引き続き Description が指すバッファーで返すために使用できる文字数 (文字データの null 終端文字を除く) を返します。
BufferLength2
[入力]*Description バッファーの文字数。
NameLength2Ptr
[出力]*Description で返すために使用できる文字数 (null 終了文字を除く) を返すバッファーへのポインター。 返される文字数が BufferLength2 以上の場合、*Description のドライバーの説明は BufferLength2 から null 終端文字の長さを引いた値に切り捨てられます。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLDataSources が SQL_ERROR または SQL_SUCCESS_WITH_INFO を返す場合は、関連付けられている SQLSTATE 値を取得するには、HandleType が SQL_HANDLE_ENV で、Handle of EnvironmentHandle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLDataSources によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | (DM) ドライバー マネージャー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | (DM) バッファー *ServerName は、完全なデータ ソース名を返すには十分な大きさではありません。 そのため、名前は切り捨てられました。 データ ソース名全体の長さは、*NameLength1Ptr で返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 (DM) バッファー *Description が、ドライバーの完全な説明 を返すには十分な大きさではなかった。 したがって、説明は切り捨てられました。 *NameLength2Ptr では、未入力のデータ ソースの説明の長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| HY000 | 一般的なエラー | (DM) 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | (DM) ドライバー マネージャーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) 引数 BufferLength1 に指定された値が 0 未満でした。 (DM) 引数 BufferLength2 に指定された値が 0 未満でした。 |
| HY103 | 無効な取得コード | (DM) 引数 Direction に指定された値が、SQL_FETCH_FIRST、SQL_FETCH_FIRST_USER、SQL_FETCH_FIRST_SYSTEM、またはSQL_FETCH_NEXTと等しくありません。 |
| HY117 | トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
説明
SQLDataSources はドライバー マネージャーに実装されているため、特定のドライバーの標準準拠に関係なく、すべてのドライバーでサポートされます。
アプリケーションは SQLDataSources を複数回呼び出して、すべてのデータ ソース名を取得できます。 ドライバー マネージャーは、システム情報からこの情報を取得します。 これ以上データ ソース名がない場合、ドライバー マネージャーはSQL_NO_DATAを返します。 sqlDataSources が SQL_NO_DATA を返した直後に SQL_FETCH_NEXT で呼び出されると、最初のデータ ソース名が返されます。 アプリケーションで SQLDataSources によって返される情報の使用方法については、「データ ソースまたはドライバーの選択」を参照してください。
SQL_FETCH_NEXTが初めて呼び出されるときに SQLDataSources に渡された場合、最初のデータ ソース名が返されます。
ドライバーは、データ ソース名を実際のデータ ソースにマップする方法を決定します。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| データ ソースへの接続に必要な値の検出と一覧表示 | SQLBrowseConnect 関数 |
| データ ソースに接続する | SQLConnect 関数 |
| 接続文字列またはダイアログ ボックスを使用してデータ ソースに接続する | SQLDriverConnect 関数 |
| ドライバーの説明と属性を返す | SQLDrivers 関数 |