SQLDataSources-Funktion
Konformität
Version eingeführt: ODBC 1.0-Normenkonformität: ISO 92
Zusammenfassung
SQLDataSources gibt Informationen zu einer Datenquelle zurück. Diese Funktion wird nur vom Treiber-Manager implementiert.
Syntax
SQLRETURN SQLDataSources(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT * NameLength1Ptr,
SQLCHAR * Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT * NameLength2Ptr);
Argumente
EnvironmentHandle
[Eingabe] Umgebungshandle.
Richtung
[Eingabe] Bestimmt, zu welcher Datenquelle der Treiber-Manager Informationen zurückgibt. Mögliche Werte sind:
SQL_FETCH_NEXT (zum Abrufen des nächsten Datenquellennamens in der Liste), SQL_FETCH_FIRST (zum Abrufen vom Anfang der Liste), SQL_FETCH_FIRST_USER (zum Abrufen des ersten Benutzer-DSN) oder SQL_FETCH_FIRST_SYSTEM (zum Abrufen des ersten System-DSN).
Wenn Richtung auf SQL_FETCH_FIRST festgelegt ist, geben nachfolgende Aufrufe von SQLDataSources mit "Direction" auf SQL_FETCH_NEXT sowohl Benutzer- als auch System-DSNs zurück. Wenn Direction auf SQL_FETCH_FIRST_USER festgelegt ist, geben alle nachfolgenden Aufrufe von SQLDataSources mit festgelegterRichtung auf SQL_FETCH_NEXT nur Benutzer-DSNs zurück. Wenn Direction auf SQL_FETCH_FIRST_SYSTEM festgelegt ist, geben alle nachfolgenden Aufrufe von SQLDataSources mit "Richtung" auf SQL_FETCH_NEXT nur System-DSNs zurück.
ServerName
[Ausgabe] Zeiger auf einen Puffer, in dem der Datenquellenname zurückgegeben werden soll.
Wenn ServerName NULL ist, gibt NameLength1Ptr weiterhin die Gesamtanzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den serverName verweist.
BufferLength1
[Eingabe] Länge des *ServerName-Puffers in Zeichen; dies muss nicht länger als SQL_MAX_DSN_LENGTH plus null-Terminierungszeichen sein.
NameLength1Ptr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens) zurückgegeben werden soll, die in *ServerName zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Zeichen größer oder gleich BufferLength1 ist, wird der Datenquellenname in *ServerName in BufferLength1 abgeschnitten, abzüglich der Länge eines NULL-Terminierungszeichens.
Beschreibung
[Ausgabe] Zeiger auf einen Puffer, in dem die Beschreibung des Treibers zurückgegeben werden soll, der der Datenquelle zugeordnet ist. Beispielsweise dBASE oder SQL Server.
Wenn Description NULL ist, gibt NameLength2Ptr weiterhin die Gesamtzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den die Beschreibung verweist.
BufferLength2
[Eingabe] Länge in Zeichen des *Description-Puffers .
NameLength2Ptr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens) zurückgegeben werden soll, die in *Description zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Zeichen größer oder gleich BufferLength2 ist, wird die Treiberbeschreibung in *Description in BufferLength2 abgeschnitten, abzüglich der Länge eines NULL-Beendigungszeichens.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLDataSources entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_ENV und einem Handle of EnvironmentHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die normalerweise von SQLDataSources zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
| SQLSTATE | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | (DM) Treiber-Manager-spezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01004 | Zeichenfolgendaten, rechts abgeschnitten | (DM) Der Puffer *ServerName war nicht groß genug, um den vollständigen Datenquellennamen zurückzugeben. Daher wurde der Name abgeschnitten. Die Länge des gesamten Datenquellennamens wird in *NameLength1Ptr zurückgegeben. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) (DM) Der Puffer *Description war nicht groß genug, um die vollständige Treiberbeschreibung zurückzugeben. Daher wurde die Beschreibung abgeschnitten. Die Länge der nicht erkannten Datenquellenbeschreibung wird in *NameLength2Ptr zurückgegeben. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| HY000 | Allgemeiner Fehler | (DM) Ein Fehler, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | (DM) Der Treiber-Manager konnte arbeitsspeicher nicht zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist. |
| HY010 | Funktionssequenzfehler | (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für statementHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | (DM) Der für das Argument BufferLength1 angegebene Wert war kleiner als 0. (DM) Der für das Argument BufferLength2 angegebene Wert war kleiner als 0. |
| HY103 | Ungültiger Abrufcode | (DM) Der für das Argument Direction angegebene Wert war nicht gleich SQL_FETCH_FIRST, SQL_FETCH_FIRST_USER, SQL_FETCH_FIRST_SYSTEM oder SQL_FETCH_NEXT. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum Angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
Kommentare
Da SQLDataSources im Treiber-Manager implementiert ist, wird es unabhängig von der Einhaltung der Standards eines bestimmten Treibers für alle Treiber unterstützt.
Eine Anwendung kann SQLDataSources mehrmals aufrufen, um alle Datenquellennamen abzurufen. Der Treiber-Manager ruft diese Informationen aus den Systeminformationen ab. Wenn keine weiteren Datenquellennamen vorhanden sind, gibt der Treiber-Manager SQL_NO_DATA zurück. Wenn SQLDataSources mit SQL_FETCH_NEXT sofort aufgerufen wird, nachdem SQL_NO_DATA zurückgegeben wurde, wird der erste Datenquellenname zurückgegeben. Informationen dazu, wie eine Anwendung die von SQLDataSources zurückgegebenen Informationen verwendet, finden Sie unter Auswählen einer Datenquelle oder eines Treibers.
Wenn SQL_FETCH_NEXT beim ersten Aufruf an SQLDataSources übergeben wird, wird der erste Datenquellenname zurückgegeben.
Der Treiber bestimmt, wie Datenquellennamen tatsächlichen Datenquellen zugeordnet werden.
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Ermitteln und Auflisten von Werten, die zum Herstellen einer Verbindung mit einer Datenquelle erforderlich sind | SQLBrowseConnect-Funktion |
| Aufbauen der Verbindung zu einer Datenquelle | SQLConnect-Funktion |
| Herstellen einer Verbindung mit einer Datenquelle mithilfe einer Verbindungszeichenfolge oder eines Dialogfelds | SQLDriverConnect-Funktion |
| Zurückgeben von Treiberbeschreibungen und Attributen | SQLDrivers-Funktion |