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 関数

参照

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