Campi e record di diagnostica
I record di diagnostica sono associati a handle descrittore, di istruzione, di connessione o di ambiente ODBC. Quando una funzione ODBC genera un codice restituito diverso da SQL_SUCCESS o SQL_INVALID_HANDLE, l'handle chiamato dalla funzione presenta record di diagnostica associati che contengono messaggi informativi o di errore. Questi record vengono mantenuti fino a quando non vengono eliminati per effetto di una chiamata a un'altra funzione utilizzando l'handle specifico. Non esiste un limite nel numero di record di diagnostica che possono essere associati a un handle.
Sono disponibili due tipi di record di diagnostica, ovvero di intestazione e di stato. Il record di intestazione è il record 0, mentre gli eventuali record di stato vengono numerati a partire da 1. I record di diagnostica contengono campi diversi per il record di intestazione e i record di stato. Per i componenti ODBC possono anche essere definiti campi dei record di diagnostica specifici.
I campi del record di intestazione contengono informazioni generali sull'esecuzione di una funzione, inclusi il codice restituito, il conteggio delle righe, il numero di record di stato e il tipo di istruzione eseguita. Il record di intestazione viene creato sempre, a meno che una funzione ODBC non restituisca SQL_INVALID_HANDLE. Per un elenco completo dei campi del record di intestazione, vedere SQLGetDiagField.
I campi dei record di stato contengono informazioni su errori o avvisi specifici restituiti da Gestione driver ODBC, dal driver o dall'origine dati, quali SQLSTATE, il numero dell'errore nativo, il messaggio di diagnostica, il numero di colonna e il numero di riga. I record di stato vengono creati solo se la funzione restituisce SQL_ERROR, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_NEED_DATA o SQL_STILL_EXECUTING. Per un elenco completo dei campi dei record di stato, vedere SQLGetDiagField.
SQLGetDiagRec recupera un solo record di diagnostica insieme ai relativi campi del messaggio di diagnostica, del numero dell'errore nativo e SQLSTATE ODBC. Questa funzionalità è simile a SQLError di ODBC 2.x. La funzione di gestione degli errori più semplice in ODBC 3.x consiste nel chiamare ripetutamente SQLGetDiagRec impostando inizialmente il parametro RecNumber su 1 per poi incrementarlo fino a quando SQLGetDiagRec non restituisce SQL_NO_DATA. Ciò equivale alla chiamata da parte di un'applicazione ODBC 2.x alla funzione SQLError fino a quando non restituisce SQL_NO_DATA_FOUND.
ODBC 3.x supporta una quantità di informazioni di diagnostica maggiore rispetto a ODBC 2.x. Tali informazioni vengono archiviate nei campi aggiuntivi dei record di diagnostica recuperati tramite SQLGetDiagField.
Il driver ODBC di SQL Server Native Client presenta campi di diagnostica specifici del driver che possono essere recuperati con SQLGetDiagField. Le etichette di questi campi specifici del driver sono definite in sqlncli.h. Utilizzarle per recuperare lo stato, il livello di gravità, il nome del server, il nome della procedura e il numero di riga di SQL Server associati a ogni record di diagnostica. sqlncli.h contiene inoltre le definizioni dei codici utilizzati dal driver per identificare le istruzioni Transact-SQL se un'applicazione chiama SQLGetDiagField con DiagIdentifier impostato su SQL_DIAG_DYNAMIC_FUNCTION_CODE.
SQLGetDiagField viene elaborato da Gestione driver ODBC utilizzando le informazioni sugli errori che memorizza nella cache dal driver sottostante. Gestione driver ODBC memorizza nella cache i campi di diagnostica specifici del driver solo una volta stabilita una connessione. SQLGetDiagField restituisce SQL_ERROR se viene chiamato per ottenere i campi di diagnostica specifici del driver prima che sia stata completata una connessione. Se una funzione di connessione ODBC restituisce SQL_SUCCESS_WITH_INFO, i campi di diagnostica specifici del driver della funzione non sono ancora disponibili. È possibile iniziare a chiamare SQLGetDiagField per i campi di diagnostica specifici del driver solo in seguito a un'altra chiamata alla funzione ODBC dopo la funzione di connessione.
La maggior parte degli errori segnalati dal driver ODBC di SQL Server Native Client può essere diagnosticata in modo efficace utilizzando solo le informazioni restituite da SQLGetDiagRec. In alcuni casi, tuttavia, le informazioni restituite dai campi di diagnostica specifici del driver sono importanti per la diagnosi di un errore. Quando si codifica un gestore degli errori ODBC per applicazioni che utilizzano il driver ODBC di SQL Server Native Client, è consigliabile utilizzare anche SQLGetDiagField per recuperare almeno i campi specifici del driver SQL_DIAG_SS_MSGSTATE e SQL_DIAG_SS_SEVERITY. Se un determinato errore può essere generato in diverse posizioni nel codice SQL Server, SQL_DIAG_SS_MSGSTATE indica esattamente al supporto tecnico Microsoft il punto in cui è stato generato, fornendo in tal modo un'informazione che in alcuni casi facilita la diagnosi di un problema.