Diagnosedatensätze und -felder
Gilt für:
SQL Server Azure SQL-Datenbank Azure SQL verwaltete Instanz Azure Synapse Analytics Analytics Platform System (PDW)
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 einen einzelnen Diagnosedatensatz zusammen mit seinen ODBC SQLSTATE-, systemeigenen Fehlernummer- und Diagnosenachrichtenfeldern ab. Diese Funktionalität ähnelt dem ODBC 2.xSQLError-Funktion . Die einfachste Fehlerbehandlungsfunktion in ODBC 3.x dient zum wiederholten Aufrufen von SQLGetDiagRec beginnend mit dem RecNumber-Parameter, der auf 1 festgelegt ist, und das Inkrementieren von RecNumber um 1, bis SQLGetDiagRec SQL_NO_DATA zurückgibt. Dies entspricht einem ODBC 2.x-Anwendung, die SQLError aufruft, bis sie SQL_NO_DATA_FOUND zurückgibt.
ODBC 3.x unterstützt wesentlich mehr Diagnoseinformationen als ODBC 2.x. Diese Informationen werden in zusätzlichen Feldern in Diagnosedatensätzen gespeichert, die mithilfe von SQLGetDiagField abgerufen werden.
Der ODBC-Treiber des nativen SQL Server-Clients verfügt über treiberspezifische Diagnosefelder, die mit SQLGetDiagField abgerufen werden können. Bezeichnungen für diese treiberspezifischen Felder werden in sqlncli.h definiert. Verwenden Sie diese Bezeichnungen, um den SQL Server-Zustand, den Schweregrad, den Servernamen, den Prozedurnamen und die Zeilennummer abzurufen, die jedem Diagnosedatensatz zugeordnet sind. Außerdem enthält sqlncli.h Definitionen der Codes, die der Treiber verwendet, um Transact-SQL-Anweisungen zu identifizieren, wenn eine Anwendung SQLGetDiagField mit DiagIdentifier auf SQL_DIAG_DYNAMIC_FUNCTION_CODE aufruft.
SQLGetDiagField wird vom ODBC-Treiber-Manager mithilfe von Fehlerinformationen verarbeitet, die vom zugrunde liegenden Treiber zwischengespeichert werden. Der ODBC-Treiber-Manager speichert treiberspezifische Diagnosefelder erst zwischen, nachdem eine erfolgreiche Verbindung hergestellt wurde. SQLGetDiagField gibt SQL_ERROR zurück, wenn es aufgerufen wird, treiberspezifische Diagnosefelder abzurufen, bevor eine erfolgreiche Verbindung abgeschlossen 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 mit dem Aufrufen von SQLGetDiagField für treiberspezifische Diagnosefelder erst beginnen, nachdem Sie nach der Verbindungsfunktion einen weiteren ODBC-Funktionsaufruf ausgeführt haben.
Die meisten Fehler, die vom SQL Server Native Client ODBC-Treiber gemeldet werden, können effektiv mithilfe der von SQLGetDiagRec zurückgegebenen Informationen 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 mit dem SQL Server Native Client ODBC-Treiber empfiehlt es sich, auch SQLGetDiagField zum Abrufen der SQL_DIAG_SS_MSGSTATE und SQL_DIAG_SS_SEVERITY treiberspezifischen Felder zu verwenden. Wenn ein bestimmter Fehler an mehreren Stellen im SQL Server-Code ausgelöst werden kann, gibt SQL_DIAG_SS_MSGSTATE an, dass ein Microsoft-Supporttechniker speziell dort angibt, wo ein Fehler ausgelöst wurde, was manchmal bei der Diagnose eines Problems hilft.