SQLDrivers-Funktion
Konformität
Eingeführte Version: ODBC 2.0-Standardkonformität: ODBC
Zusammenfassung
SQLDrivers listet Treiberbeschreibungen und Schlüsselwörter für Treiberattribute auf. Diese Funktion wird nur vom Treiber-Manager implementiert.
Syntax
SQLRETURN SQLDrivers(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * DriverDescription,
SQLSMALLINT BufferLength1,
SQLSMALLINT * DescriptionLengthPtr,
SQLCHAR * DriverAttributes,
SQLSMALLINT BufferLength2,
SQLSMALLINT * AttributesLengthPtr);
Argumente
EnvironmentHandle
[Eingabe] Umgebungshandle.
Richtung
[Eingabe] Bestimmt, ob der Treiber-Manager die nächste Treiberbeschreibung in der Liste abruft (SQL_FETCH_NEXT) oder ob die Suche am Anfang der Liste beginnt (SQL_FETCH_FIRST).
DriverDescription
[Ausgabe] Zeiger auf einen Puffer, in dem die Treiberbeschreibung zurückgegeben werden soll.
Wenn DriverDescription NULL ist, gibt DescriptionLengthPtr 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 driverDescription verweist.
BufferLength1
[Eingabe] Länge des *DriverDescription-Puffers in Zeichen.
BeschreibungLengthPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens) zurückgegeben werden soll, die in *DriverDescription zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Zeichen größer oder gleich BufferLength1 ist, wird die Treiberbeschreibung in *DriverDescription auf BufferLength1 abzüglich der Länge eines NULL-Terminierungszeichens abgeschnitten.
DriverAttributes
[Ausgabe] Zeiger auf einen Puffer, in dem die Liste der Treiber-Attributwertpaare zurückgegeben werden soll (siehe "Kommentare").
Wenn DriverAttributes NULL ist, gibt AttributesLengthPtr weiterhin die Gesamtanzahl der Bytes (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den DriverAttributes verweist.
BufferLength2
[Eingabe] Länge des *DriverAttributes-Puffers in Zeichen. Wenn der Wert *DriverDescription eine Unicode-Zeichenfolge ist (beim Aufrufen von SQLDriversW), muss das BufferLength-Argument eine gerade Zahl sein.
AttributesLengthPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Bytes (mit Ausnahme des Bytes zur NULL-Beendigung) zurückgegeben werden soll, die in *DriverAttributes zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Bytes größer oder gleich BufferLength2 ist, wird die Liste der Attributwertpaare in *DriverAttributes in BufferLength2 abzüglich der Länge des NULL-Terminierungszeichens abgeschnitten.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLDrivers 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 in der Regel von SQLDrivers zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, 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. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01004 | Zeichenfolgendaten, rechts abgeschnitten | (DM) Der Puffer *DriverDescription war nicht groß genug, um die vollständige Treiberbeschreibung zurückzugeben. Daher wurde die Beschreibung abgeschnitten. Die Länge der vollständigen Treiberbeschreibung wird in *DescriptionLengthPtr zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) (DM) Der Puffer *DriverAttributes war nicht groß genug, um die vollständige Liste der Attributwertpaare zurückzugeben. Daher wurde die Liste abgeschnitten. Die Länge der nicht wahrgewordenen Liste von Attributwertpaaren wird in *AttributesLengthPtr zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE 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 keinen Arbeitsspeicher zuordnen, der zur Unterstützung der Ausführung oder Fertigstellung 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, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen. |
| 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 oder gleich 1. |
| HY103 | Ungültiger Abrufcode | (DM) Der für das Argument Direction angegebene Wert war nicht gleich SQL_FETCH_FIRST oder SQL_FETCH_NEXT. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
Kommentare
SQLDrivers gibt die Treiberbeschreibung im *DriverDescription-Puffer zurück. Sie gibt zusätzliche Informationen zum Treiber im *DriverAttributes-Puffer als Liste von Schlüsselwort-Wert-Paaren zurück. Alle Schlüsselwörter, die in den Systeminformationen für Treiber aufgeführt sind, werden für alle Treiber zurückgegeben, mit Ausnahme von CreateDSN, das zum Erstellen von Datenquellen verwendet wird und daher optional ist. Jedes Paar wird mit einem NULL-Byte beendet, und die vollständige Liste wird mit einem NULL-Byte beendet (das Heißt, zwei NULL-Bytes markieren das Ende der Liste). Beispielsweise kann ein dateibasierter Treiber mit C-Syntax die folgende Liste von Attributen zurückgeben ("\0" stellt ein NULL-Zeichen dar):
FileUsage=1\0FileExtns=*.dbf\0\0
Wenn *DriverAttributes nicht groß genug ist, um die gesamte Liste zu enthalten, wird die Liste abgeschnitten, SQLDrivers gibt SQLSTATE 01004 (Daten abgeschnitten) zurück, und die Länge der Liste (mit Ausnahme des endgültigen Bytes mit NULL-Terminierung) wird in *AttributesLengthPtr zurückgegeben.
Schlüsselwörter für Treiberattribute werden aus den Systeminformationen hinzugefügt, wenn der Treiber installiert wird. Weitere Informationen finden Sie unter Installieren von ODBC-Komponenten.
Eine Anwendung kann SQLDriver mehrmals aufrufen, um alle Treiberbeschreibungen abzurufen. Der Treiber-Manager ruft diese Informationen aus den Systeminformationen ab. Wenn keine Treiberbeschreibungen mehr vorhanden sind, gibt SQLDrivers SQL_NO_DATA zurück. Wenn SQLDrivers unmittelbar nach der Rückgabe SQL_NO_DATA mit SQL_FETCH_NEXT aufgerufen wird, wird die erste Treiberbeschreibung zurückgegeben. Informationen dazu, wie eine Anwendung die von SQLDriver zurückgegebenen Informationen verwendet, finden Sie unter Auswählen einer Datenquelle oder eines Treibers.
Wenn SQL_FETCH_NEXT beim ersten Aufruf an SQLDrivers übergeben wird, gibt SQLDrivers den ersten Datenquellennamen zurück.
Da SQLDrivers im Treiber-Manager implementiert ist, wird es für alle Treiber unterstützt, unabhängig von der Konformität mit den Standards eines bestimmten Treibers.
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 |
| Zurückgeben von Datenquellennamen | SQLDataSources-Funktion |
| Herstellen einer Verbindung mit einer Datenquelle mithilfe einer Verbindungszeichenfolge oder eines Dialogfelds | SQLDriverConnect-Funktion |