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.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| 01000 | Avviso generale | (DM) 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. Pertanto, 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 per restituire l'elenco completo delle coppie di valori dell'attributo. Pertanto, l'elenco è stato troncato. La lunghezza dell'elenco non modificato di coppie valore attributo viene restituita in *AttributesLengthPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| HY000 | Errore generale: | Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun 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 è riuscito ad allocare 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 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 viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse 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 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
| Per informazioni su | Vedere |
|---|---|
| Individuazione ed elenco dei valori necessari per la connessione a un'origine dati | Funzione SQLBrowseConnect |
| Connessione a un'origine dati | Funzione SQLConnect |
| Restituzione dei nomi delle origini dati | Funzione SQLDataSources |
| Connessione a un'origine dati tramite una stringa di connessione o una finestra di dialogo | Funzione SQLDriverConnect |