Diagnosedatensätze und -felder
Diagnosedatensätze sind ODBC-Umgebungs-, Verbindungs-, Anweisungs- oder Deskriptorhandles zugeordnet. Wenn eine ODBC-Funktion einen anderen Rückgabecode als SQL_SUCCESS oder SQL_INVALID_HANDLE auslöst, verfügt das von der Funktion aufgerufene Handle über zugeordnete Diagnosedatensätze mit Informations- oder Fehlermeldungen. Diese Datensätze werden so lange beibehalten, bis eine andere Funktion mit diesem Handle aufgerufen wird. Anschließend werden sie verworfen. Die Zahl der Diagnosedatensätze, die einem Handle zugeordnet sein können, ist unbegrenzt.
Es gibt zwei Arten von Diagnosedatensätzen: Header und Status. Der Headerdatensatz ist Datensatz 0; wenn es Statusdatensätze gibt, sind dies die Datensätze 1 und höher. Diagnosedatensätze enthalten andere Felder für den Headerdatensatz und die Statusdatensätze. ODBC-Komponenten können auch eigene Diagnosedatensatzfelder definieren.
Felder im Headerdatensatz enthalten allgemeine Informationen über die Ausführung einer Funktion, einschließlich Rückgabecode, Zeilenanzahl, Anzahl der Statusdatensätze und Typ der ausgeführten Anweisung. Der Headerdatensatz wird immer erstellt, es sei denn, eine ODBC-Funktion gibt SQL_INVALID_HANDLE zurück. Eine vollständige Liste der Felder im Headerdatensatz finden Sie unter SQLGetDiagField.
Felder in den Statusdatensätzen enthalten Informationen über bestimmte Fehler oder Warnungen, die vom ODBC-Treiber-Manager, vom Treiber oder von der Datenquelle zurückgegeben werden, einschließlich SQLSTATE, systemeigener Fehlernummer, Diagnosemeldung, Spaltennummer und Zeilennummer. Statusdatensätze werden nur erstellt, wenn die Funktion SQL_ERROR, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_NEED_DATA oder SQL_STILL_EXECUTING zurückgibt. Eine vollständige Liste der Felder in den Statusdatensätzen finden Sie unter SQLGetDiagField.
SQLGetDiagRec ruft mit ODBC SQLSTATE, systemeigener Fehlernummer und Diagnosemeldungsfeldern einen einzelnen Diagnosedatensatz ab. Diese Funktionalität ist mit der ODBC 2.xSQLError-Funktion vergleichbar. Die einfachste Fehlerbehandlungsfunktion in ODBC 3.x besteht im wiederholten Aufrufen von SQLGetDiagRec, wobei der RecNumber-Parameter anfangs auf 1 festgelegt ist und RecNumber schrittweise um 1 erhöht wird, bis SQLGetDiagRec SQL_NO_DATA zurückgibt. Dies ist vergleichbar mit einer ODBC 2.x-Anwendung, die SQLError aufruft, bis SQL_NO_DATA_FOUND zurückgegeben wird.
ODBC 3.x unterstützt weitaus mehr Diagnoseinformationen als ODBC 2.x. Diese Informationen werden in zusätzlichen Feldern in Diagnosedatensätzen gespeichert, die mit SQLGetDiagField abgerufen werden.
Der SQL Server-Native Client-ODBC-Treiber verfügt über treiberspezifische Diagnosefelder, die mit SQLGetDiagField abgerufen werden können. Bezeichnungen für diese treiberspezifischen Felder werden in sqlncli.h definiert. Mit diesen Bezeichnungen rufen Sie den SQL Server-Status, den Schweregrad, den Servernamen, den Prozedurnamen und die jedem Diagnosedatensatz zugeordnete Zeilennummer ab. Außerdem enthält sqlncli.h Definitionen der Codes, mit denen der Treiber Transact-SQL-Anweisungen identifiziert, wenn eine Anwendung SQLGetDiagField aufruft und DiagIdentifier auf SQL_DIAG_DYNAMIC_FUNCTION_CODE festgelegt ist.
SQLGetDiagField wird vom ODBC-Treiber-Manager mit Fehlerinformationen verarbeitet, die der ODBC-Treiber-Manager vom zugrunde liegenden Treiber zwischenspeichert. Der ODBC-Treiber-Manager speichert treiberspezifische Diagnosefelder erst zwischen, wenn eine erfolgreiche Verbindung hergestellt wurde. SQLGetDiagField gibt SQL_ERROR zurück, wenn der Aufruf zum Abrufen von treiberspezifischen Diagnosefeldern erfolgt, bevor eine Verbindung herstellt wurde. Wenn eine ODBC-Verbindungsfunktion SQL_SUCCESS_WITH_INFO zurückgibt, sind noch keine treiberspezifischen Diagnosefelder für die Verbindungsfunktion verfügbar. Sie können SQLGetDiagField für treiberspezifische Felder erst aufrufen, nachdem Sie einen weiteren ODBC-Funktionsaufruf nach der Verbindungsfunktion durchgeführt haben.
Die meisten vom SQL Server Native Client ODBC-Treiber gemeldeten Fehler können einzig anhand der von SQLGetDiagRec zurückgegebenen Informationen effektiv diagnostiziert werden. In einigen Fällen sind jedoch die von den treiberspezifischen Diagnosefeldern zurückgegebenen Informationen für die Fehlerdiagnose wichtig. Beim Codieren eines ODBC-Fehlerhandlers für Anwendungen, die den SQL Server Native Client ODBC-Treiber verwenden, empfiehlt es sich, mit SQLGetDiagField zumindest die treiberspezifischen Felder SQL_DIAG_SS_MSGSTATE und SQL_DIAG_SS_SEVERITY abzurufen. Wenn ein bestimmter Fehler an mehreren Orten im SQL Server-Code ausgelöst werden kann, erkennt der Microsoft Software Service anhand von SQL_DIAG_SS_MSGSTATE, wo genau ein Fehler ausgelöst wurde, was mitunter für die Problemdiagnose hilfreich ist.