Funzione SQLDrivers

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

Summary
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) disponibili per la restituzione 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) disponibili per la restituzione in * DriverDescription. Se il numero di caratteri disponibili per restituire è 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 di attributo del 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) disponibili per la restituzione 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) disponibili per la restituzione in * DriverAttributes. Se il numero di byte disponibili per restituire è maggiore o uguale a BufferLength2, l'elenco di coppie di valori di attributo in DriverAttributes viene troncato in * BufferLength2 meno la lunghezza del carattere di terminazione Null.

Restituisce

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 handleType di SQL_HANDLE_ENV e handle di EnvironmentHandle. La tabella seguente elenca i valori SQLSTATE in genere restituiti da SQLDrivers e spiega ognuno 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, se non diversamente specificato.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico di Gestione driver. La funzione restituisce SQL_SUCCESS_WITH_INFO.
01004 Dati stringa troncati a destra (DM) Il buffer * DriverDescription non era sufficientemente grande da restituire la descrizione completa del driver. Di conseguenza, la descrizione è stata troncata. La lunghezza della descrizione completa del driver viene restituita in * DescriptionLengthPtr. La funzione restituisce SQL_SUCCESS_WITH_INFO.

(DM) Il buffer * DriverAttributes non era sufficientemente grande da restituire l'elenco completo di coppie di valori di attributo. Pertanto, l'elenco è stato troncato. La lunghezza dell'elenco nontruncato di coppie di valori di attributo viene restituita in *AttributesLengthPtr. La funzione restituisce SQL_SUCCESS_WITH_INFO.
HY000 Errore generale: Si è verificato un errore per il quale non è stato definito un SQLSTATE specifico e per il quale non è stato definito ALCUN VALORE SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer * MessageText descrive l'errore e la relativa causa.
HY001 Errore di allocazione della memoria (DM) Gestione driver non è stato in grado di allocare la memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY010 Errore della sequenza di funzioni (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e ha restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi.
HY013 Errore di gestione della memoria Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY090 Lunghezza della stringa o del buffer non valida (DM) Il valore specificato per l'argomento BufferLength1 è minore di 0.

(DM) Il valore specificato per l'argomento BufferLength2 è minore di 0 o uguale a 1.
HY103 Codice di recupero non valido (DM) Il valore specificato per l'argomento Direction non è uguale a SQL_FETCH_FIRST o SQL_FETCH_NEXT.
HY117 La connessione è stata sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo funzioni di disconnessione e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.

Commenti

SQLDrivers restituisce la descrizione del driver nel buffer * DriverDescription. Restituisce informazioni aggiuntive sul driver nel buffer * DriverAttributes come elenco di coppie parola 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 usato per richiedere la creazione di origini dati e pertanto è facoltativo. 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 degli attributi del driver vengono aggiunte dalle informazioni di sistema quando viene installato il driver. Per altre informazioni, vedere Installazione di componenti ODBC.

Un'applicazione può chiamare SQLDrivers più volte 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 la SQL_NO_DATA, restituisce la prima descrizione del driver. Per informazioni sul modo in cui 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à agli standard di un determinato driver.

Per informazioni su Vedere
Individuazione ed elenco dei valori necessari per connettersi a un'origine dati Funzione SQLBrowseConnect
Connessione a un'origine dati Funzione SQLConnect
Restituzione di nomi di origini dati Funzione SQLDataSources
Connessione a un'origine dati tramite una stringa di connessione o una finestra di dialogo Funzione SQLDriverConnect

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC