SQLDrivers-Funktion

Konformität
Version eingeführt: ODBC 2.0-Standardscompliance: ODBC

Summary
SQLDrivers listet Treiberbeschreibungen und Schlüsselwörter für Treiberattribute. Diese Funktion wird nur vom Driver Manager implementiert.

Syntax

  
SQLRETURN SQLDrivers(  
     SQLHENV         EnvironmentHandle,  
     SQLUSMALLINT    Direction,  
     SQLCHAR *       DriverDescription,  
     SQLSMALLINT     BufferLength1,  
     SQLSMALLINT *   DescriptionLengthPtr,  
     SQLCHAR *       DriverAttributes,  
     SQLSMALLINT     BufferLength2,  
     SQLSMALLINT *   AttributesLengthPtr);  

Argumente

EnvironmentHandle
[Eingabe] Umwelt-Kontrolle.

Direction
[Eingabe] Bestimmt, ob der Driver Manager die nächste Treiberbeschreibung in der Liste (SQL_FETCH_NEXT) abruft oder ob die Suche von Anfang an beginnt (SQL_FETCH_FIRST).

DriverDescription
[Ausgabe] Zeiger auf einen Puffer, um die Treiberbeschreibung zurückzugeben.

Wenn DriverDescription NULL ist, gibt DescriptionLengthPtr weiterhin die Gesamtzahl der Zeichen zurück (ohne das Null-Terminationszeichen für Zeichendaten), die im von DriverDescription gezeigten Puffer zurückgegeben werden können.

BufferLength1
[Eingabe] Länge des *DriverDescription-Puffers , in Zeichen.

BeschreibungLängePtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (ohne das Null-Terminationszeichen) zurückgegeben werden kann, die in *DriverDescription. Wenn die Anzahl der zurückgegebenen Zeichen größer oder gleich BufferLength1 ist, wird die Treiberbeschreibung in *DriverDescription auf BufferLength1 minus die Länge eines Null-Terminationszeichens abgekürzt.

Fahrerattribute
[Ausgabe] Zeiger auf einen Puffer, in dem die Liste der Treiberattributwertpaare zurückgegeben wird (siehe "Kommentare").

Wenn DriverAttributes NULL ist, gibt AttributesLengthPtr weiterhin die Gesamtzahl der Bytes zurück (ohne das Null-Terminationszeichen für Zeichendaten), die im von DriverAttributes gezeigten Puffer zurückgegeben werden können.

BufferLength2
[Eingabe] Länge des *DriverAttributs-Puffers , in Zeichen. Wenn der Wert *DriverDescription eine Unicode-Zeichenkette ist (beim Aufruf von SQLDriversW), muss das BufferLength-Argument eine gerade Zahl sein.

AttributeLängePtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Bytes (ohne das Null-Terminierungsbyte) zurückgegeben werden kann, die in *DriverAttributes zurückgegeben werden können. Wenn die Anzahl der verfügbaren Bytes größer oder gleich BufferLength2 ist, wird die Liste der Attributwertpaare in *DriverAttributes auf BufferLength2 minus die Länge des Null-Terminationszeichens abgeschnitten.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostics

Wenn SQLDrivers entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugehöriger SQLSTATE-Wert erhalten werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_ENV und einem Handle von EnvironmentHandle aufgerufen wird. Die folgende Tabelle listet die SQL-State-Werte auf, die typischerweise von SQLDrivers zurückgegeben werden, und erklärt jeden einzelnen im Kontext dieser Funktion; die Notation "(DM)" geht den vom Treibermanager zurückgegebenen SQLSTATE-Beschreibungen voraus. 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. Er liefert zusätzliche Informationen über den Treiber im *DriverAttributs-Puffer als Liste von Schlüsselwort-Wert-Paaren. 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 zur Erstellung von Datenquellen verwendet wird und daher optional ist. Jedes Paar wird mit einem Nullbyte beendet, und die vollständige Liste mit einem Nullbyte (das heißt, zwei Nullbytes markieren das Ende der Liste). Zum Beispiel könnte ein dateibasierter Treiber mit C-Syntax folgende Liste von Attributen zurückgeben ("\0" steht für ein Nullzeichen):

FileUsage=1\0FileExtns=*.dbf\0\0  

Wenn *DriverAttributes nicht groß genug ist, um die gesamte Liste zu halten, wird die Liste abgeschnitten, SQLDrivers gibt SQLSTATE 01004 zurück (Daten abgeschnitten), und die Länge der Liste (ohne das letzte Null-Terminierungsbyte) wird in *AttributesLengthPtr zurückgegeben.

Treiberattribut-Schlüsselwörter werden aus den Systeminformationen hinzugefügt, wenn der Treiber installiert wird. Weitere Informationen finden Sie unter Installation von ODBC-Komponenten.

Eine Anwendung kann SQLDrivers mehrfach aufrufen , um alle Treiberbeschreibungen abzurufen. Der Driver Manager holt diese Informationen aus den Systeminformationen ab. Wenn es keine weiteren Treiberbeschreibungen gibt, gibt SQLDrivers SQL_NO_DATA zurück. Wenn SQLDrivers mit SQL_FETCH_NEXT sofort nach der Rückgabe SQL_NO_DATA aufgerufen wird, gibt es die erste Treiberbeschreibung zurück. Für Informationen darüber, wie eine Anwendung die von SQLDrivers zurückgegebenen Informationen verwendet, siehe Wahl einer Datenquelle oder eines Treibers.

Wenn SQL_FETCH_NEXT beim allerersten Aufruf an SQLDrivers übermittelt wird, gibt SQLDrivers den ersten Namen der Datenquelle zurück.

Da SQLDrivers im Driver Manager implementiert ist, wird es für alle Treiber unabhängig von der Einhaltung der Standards eines bestimmten Treibers unterstützt.

Verwandte Funktionen

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien