Funzione SQLDrivers

Conformità
Versione introdotta: Conformità agli standard ODBC 2.0: ODBC

Riepilogo
SQLDrivers elenca le descrizioni dei driver e le parole chiave degli attributi del driver. Questa funzione viene implementata solo da Gestione driver.

Sintassi

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

Argomenti

EnvironmentHandle
[Input] Handle dell'ambiente.

Direzione
[Input] Determina se Gestione driver recupera la descrizione del driver successiva nell'elenco (SQL_FETCH_NEXT) o se la ricerca inizia dall'inizio dell'elenco (SQL_FETCH_FIRST).

DriverDescription
[Output] Puntatore a un buffer in cui restituire la descrizione del driver.

Se DriverDescription è NULL, DescriptionLengthPtr restituirà comunque il numero totale di caratteri (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta DriverDescription.

BufferLength1
[Input] Lunghezza del buffer *DriverDescription , in caratteri.

DescriptionLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero totale di caratteri (escluso il carattere di terminazione Null) disponibile per la restituzione in *DriverDescription. Se il numero di caratteri disponibili per la restituzione è maggiore o uguale a BufferLength1, la descrizione del driver in *DriverDescription viene troncata a BufferLength1 meno la lunghezza di un carattere di terminazione Null.

DriverAttributes
[Output] Puntatore a un buffer in cui restituire l'elenco di coppie di valori dell'attributo driver (vedere "Commenti").

Se DriverAttributes è NULL, AttributesLengthPtr restituirà comunque il numero totale di byte (escluso il carattere di terminazione null per i dati di tipo carattere) da restituire nel buffer a cui punta DriverAttributes.

BufferLength2
[Input] Lunghezza del buffer *DriverAttributes , in caratteri. Se il valore *DriverDescription è una stringa Unicode (quando si chiama SQLDriversW), l'argomento BufferLength deve essere un numero pari.

AttributesLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero totale di byte (escluso il byte di terminazione Null) disponibile per la restituzione in *DriverAttributes. Se il numero di byte disponibili per la restituzione è maggiore o uguale a BufferLength2, l'elenco di coppie di valori di attributo in *DriverAttributes viene troncato a BufferLength2 meno la lunghezza del carattere di terminazione Null.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLDrivers restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_ENV e handle di EnvironmentHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLDrivers e spiega ognuno di essi nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Commenti

SQLDrivers restituisce la descrizione del driver nel buffer *DriverDescription . Restituisce informazioni aggiuntive sul driver nel buffer *DriverAttributes come elenco di coppie chiave-valore. Tutte le parole chiave elencate nelle informazioni di sistema per i driver verranno restituite per tutti i driver, ad eccezione di CreateDSN, che viene usata per richiedere la creazione di origini dati e pertanto è facoltativa. Ogni coppia viene terminata con un byte Null e l'elenco completo viene terminato con un byte Null, ovvero due byte Null contrassegnano la fine dell'elenco. Ad esempio, un driver basato su file che usa la sintassi C potrebbe restituire l'elenco di attributi seguente ("\0" rappresenta un carattere Null):

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

Se *DriverAttributes non è sufficientemente grande da contenere l'intero elenco, l'elenco viene troncato, SQLDrivers restituisce SQLSTATE 01004 (dati troncati) e la lunghezza dell'elenco (escluso il byte finale di terminazione Null) viene restituita in *AttributesLengthPtr.

Le parole chiave dell'attributo driver vengono aggiunte dalle informazioni di sistema quando viene installato il driver. Per altre informazioni, vedere Installazione di componenti ODBC.

Un'applicazione può chiamare più volte SQLDrivers per recuperare tutte le descrizioni dei driver. Gestione driver recupera queste informazioni dalle informazioni di sistema. Quando non sono presenti altre descrizioni dei driver, SQLDrivers restituisce SQL_NO_DATA. Se SQLDrivers viene chiamato con SQL_FETCH_NEXT immediatamente dopo che restituisce SQL_NO_DATA, restituisce la prima descrizione del driver. Per informazioni su come un'applicazione usa le informazioni restituite da SQLDrivers, vedere Scelta di un'origine dati o di un driver.

Se SQL_FETCH_NEXT viene passato a SQLDrivers la prima volta che viene chiamato, SQLDrivers restituisce il primo nome dell'origine dati.

Poiché SQLDrivers viene implementato in Gestione driver, è supportato per tutti i driver indipendentemente dalla conformità degli standard di un determinato driver.

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC