Diagnosedatensätze und -felder

Gilt für:SQL ServerAzure SQL-DatenbankAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics 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 den Feldern ODBC SQLSTATE, systemeigene Fehlernummer und Diagnosemeldung ab. Diese Funktionalität ähnelt odbc 2. xSQLError-Funktion . Die einfachste Fehlerbehandlungsfunktion in ODBC 3. x ruft SQLGetDiagRec wiederholt auf, beginnend mit dem Auf 1 gesetzten Parameter RecNumber und erhöht RecNumber um 1, bis SQLGetDiagRec SQL_NO_DATA zurückgibt. Dies entspricht einer ODBC 2-Version. x-Anwendung , die SQLError aufruft, bis SQL_NO_DATA_FOUND zurückgegeben wird.

ODBC 3. x unterstützt viel mehr Diagnoseinformationen als ODBC 2. x. Diese Informationen werden in zusätzlichen Feldern in Diagnosedatensätzen gespeichert, die mithilfe von SQLGetDiagField abgerufen werden.

Der SQL Server Native Client ODBC-Treibers 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, Schweregrad, Servername, Prozedurname und 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 aufruft , wobei DiagIdentifier auf SQL_DIAG_DYNAMIC_FUNCTION_CODE festgelegt ist.

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, um treiberspezifische Diagnosefelder abzurufen, bevor eine erfolgreiche Verbindung hergestellt 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 Diagnosefelder erst aufrufen, nachdem Sie nach der Verbindungsfunktion einen weiteren ODBC-Funktionsaufruf durchgefü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 zu verwenden, um mindestens die SQL_DIAG_SS_MSGSTATE und SQL_DIAG_SS_SEVERITY treiberspezifischen Felder abzurufen. Wenn an mehreren Stellen im SQL Server Code ein bestimmter Fehler ausgelöst werden kann, gibt SQL_DIAG_SS_MSGSTATE einem Microsoft-Supporttechniker an, wo ein Fehler ausgelöst wurde, was manchmal bei der Diagnose eines Problems hilfreich ist.

Weitere Informationen

Behandlung von Fehlern und Meldungen