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.

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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien