SQLDrivers-funktion

Överensstämmelse
Version introducerad: ODBC 2.0 Standardsefterlevnad: ODBC

Summary
SQLDrivers listar drivrutinsbeskrivningar och nyckelord för drivrutinsattribut. Denna funktion implementeras endast av Driver Manager.

Syntax

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

Arguments

EnvironmentHandle
[Input] Miljöhantering.

Riktning
[Input] Avgör om Driver Manager hämtar nästa drivrutinsbeskrivning i listan (SQL_FETCH_NEXT) eller om sökningen börjar från början av listan (SQL_FETCH_FIRST).

DriverDescription
[Utdata] Peka på en buffert där drivrutinsbeskrivningen ska returneras.

Om DriverDescription är NULL kommer DescriptionLengthPtr ändå att returnera det totala antalet tecken (exklusive null-termineringstecknet för teckendata) som finns tillgängliga att returnera i bufferten som DriverDescription pekar på.

BufferLength1
[Input] Längd på *DriverDescription-bufferten , i tecken.

BeskrivningLängdPtr
[Utdata] Pekare till en buffert där det totala antalet tecken (exklusive null-termineringstecknet) kan returneras i *DriverDescription. Om antalet tecken som kan returneras är större än eller lika med BufferLength1, trunkeras drivrutinsbeskrivningen i *DriverDescription till BufferLength1 minus längden på ett null-termineringstecken.

Föraregenskaper
[Utdata] Pekare till en buffert där listan över attributvärdspar för drivrutiner returneras (se "Kommentarer").

Om DriverAttributes är NULL kommer AttributesLengthPtr ändå att returnera det totala antalet bytes (exklusive null-termineringstecknet för teckendata) som finns tillgängliga att returnera i bufferten som DriverAttributes pekar på.

BufferLength2
[Input] Längden på *DriverAttributs-bufferten , i tecken. Om *DriverDescription-värdet är en Unicode-sträng (vid anrop av SQLDriversW) måste argumentet BufferLength vara ett jämnt tal.

AttributLengthPtr
[Utdata] Pekare till en buffert där man returnerar det totala antalet bytes (exklusive nulltermineringsbytet) som finns tillgängligt att returnera i *DriverAttributes. Om antalet byte som kan returneras är större än eller lika med BufferLength2, förkortas listan över attributvärdspar i *DriverAttributes till BufferLength2 minus längden på null-termineringstecknet.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostics

När SQLDrivers returnerar antingen SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med HandleType SQL_HANDLE_ENV och Handle EnvironmentHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLDrivers och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

Comments

SQLDrivers returnerar drivrutinsbeskrivningen i *DriverDescription-bufferten . Den returnerar ytterligare information om drivrutinen i *DriverAttributs-bufferten som en lista över nyckelord-värdepar. Alla nyckelord som anges i systeminformationen för drivrutiner kommer att returneras för alla drivrutiner, förutom CreateDSN, som används för att be om skapande av datakällor och därför är valfritt. Varje par avslutas med en nullbyte, och den kompletta listan avslutas med en nullbyte (det vill säga, två nullbyte markerar slutet). Till exempel kan en filbaserad drivrutin som använder C-syntax returnera följande lista med attribut ("\0" representerar ett nolltecken):

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

Om *DriverAttributes inte är tillräckligt stort för att rymma hela listan, trunkeras listan, SQLDrivers returnerar SQLSTATE 01004 (Data trunkerad), och längden på listan (exklusive den sista nulltermineringsbytet) returneras i *AttributesLengthPtr.

Drivrutinsattributnyckelord läggs till från systeminformationen när drivrutinen installeras. För mer information, se Installation av ODBC-komponenter.

En applikation kan anropa SQLDrivers flera gånger för att hämta alla drivrutinsbeskrivningar. Driver Manager hämtar denna information från systeminformationen. När det inte finns några drivrutinsbeskrivningar kvar, returnerar SQLDrivers SQL_NO_DATA. Om SQLDrivers anropas med SQL_FETCH_NEXT omedelbart efter att den returnerat SQL_NO_DATA, returnerar den den första drivrutinsbeskrivningen. För information om hur en applikation använder informationen som returneras av SQLDrivers, se Välj en datakälla eller drivrutin.

Om SQL_FETCH_NEXT skickas till SQLDrivers första gången den anropas, returnerar SQLDrivers det första namnet på datakällan.

Eftersom SQLDrivers är implementerat i Driver Manager stöds det för alla drivrutiner oavsett om en viss drivrutin uppfyller standarderna.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler