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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien