Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Verwenden Sie diese Anleitung mit Microsoft ODBC Driver 17 oder 18. Er beschreibt den ODBC-Diagnosekontrakt; er definiert keine versionsspezifischen nativen Fehlerzuordnungen.
Eine ODBC-Funktion gibt einen Code zurück, der das Ergebnis dieses Aufrufs beschreibt. Diagnoseberichte liefern mehr Details. Die Application Programming Interface (API) kann Datensätze vom Driver Manager, dem Treiber, der Datenquelle oder mehr als einer Komponente melden. Behandle den Rückgabecode, SQLSTATE, den nativen Fehlercode und die Nachricht nicht als austauschbar.
Interpretiere den Rückgabecode
Überprüfen Sie den Rückgabecode, bevor Sie die Ausgabe verarbeiten oder entscheiden, ob Sie es erneut versuchen möchten. Für SQL_ERROR und SQL_SUCCESS_WITH_INFO, hole Diagnostiken aus dem von der Funktion verwendeten Handle ab. Andere Rückgabecodes können ebenfalls Diagnosedatensätze enthalten, wenn die Funktionsspezifikation dies erlaubt.
| Rückgabecode | Bedeutung und Antwort |
|---|---|
SQL_SUCCESS |
Die Funktion wurde erfolgreich abgeschlossen. Überprüfen Sie den Ausgabekontrakt der Funktion. |
SQL_SUCCESS_WITH_INFO |
Die Funktion wurde mit Warnhinweisen abgeschlossen. Rufen Sie jeden Diagnosedatensatz ab und prüfen Sie, ob die Ausgabe vollständig, konvertiert oder abgeschnitten ist. |
SQL_ERROR |
Die Funktion ist fehlgeschlagen. Rufen Sie jeden Diagnosedatensatz ab, bevor Sie eine weitere Funktion auf demselben Handle aufrufen. |
SQL_INVALID_HANDLE |
Die Funktion erkannte ein Null-Handle oder ein Handle des falschen Typs. ODBC stellt für diesen Rückgabecode keine Diagnosedaten bereit. Überprüfen Sie die Funktionsreferenz auf zusätzliche Handle-Anforderungen. |
SQL_NO_DATA |
Für die Operation liegen keine weiteren Daten vor. Überprüfen Sie die Funktionsreferenz, da die Bedeutung und eventuelle Statusdatensätze von der Funktion abhängen. |
Weitere Informationen zum vollständigen Vertrag für Rückgabecodes finden Sie unter ODBC-Rückgabecodes.
Rufen Sie jeden Diagnosedatensatz ab
Rufen Sie SQLGetDiagRec für Statusdatensätze ab Eintrag Nummer 1 auf. Fahren Sie fort, bis die Funktion SQL_NO_DATA zurückgibt, oder lesen Sie die Datensatzanzahl aus dem Header-Datensatz 0, indem Sie SQL_DIAG_NUMBER mit SQLGetDiagField aufrufen.
SQLGetDiagRec gibt den SQLSTATE eines Datensatzes, den nativen Fehlercode und den Nachrichtentext zurück. Verwenden SQLGetDiagField Sie, wenn Sie andere Header- oder Datensatzfelder benötigen.
Hör nicht nach dem ersten Datensatz auf. Eine ODBC-Komponente kann einen Statusdatensatz mit Informationen über ihre eigene Schicht hinzufügen, wobei die Diagnoseinformationen einer anderen Komponente erhalten bleiben. Die Reihenfolge der Datensätze und der Inhalt können helfen, den Ursprung eines Fehlers zu erkennen.
Sammle die Unterlagen umgehend. Ein späterer ODBC-Aufruf, der denselben Handle verwendet, ersetzt seinen Diagnosebereich, mit Ausnahme von Aufrufen zu SQLGetDiagRec, SQLGetDiagField, und der Legacy-Funktion SQLError . Verwenden Sie SQLGetDiagRec und SQLGetDiagField in neuem Code.
SQLGetDiagRec kann SQL_SUCCESS_WITH_INFO zurückgeben, wenn sein Nachrichtenpuffer zu klein ist. Der Datensatz wurde zurückgegeben, aber der Nachrichtentext wurde abgeschnitten. Überprüfen Sie die gemeldete Textlänge und rufen Sie die Nachricht mit einem größeren Puffer ab, falls Sie den vollständigen Text benötigen. Verwechsle diesen Rückgabecode von SQLGetDiagRec nicht mit dem Rückgabecode der ursprünglichen ODBC-Funktion.
Für weitere Informationen zum Abrufen von Diagnoseinformationen siehe Diagnostische Datensätze, Verwendung von SQLGetDiagRec und SQLGetDiagField sowie die SQLGetDiagRec- und SQLGetDiagField-Referenzen.
Diagnostische Datensätze in C++ sammeln
Verwenden Sie diesen C++11-Helfer mit einem bestehenden ODBC-Handle. Es ruft SQLGetDiagRecW auf, um SQLSTATE, nativen Fehlercode und Unicode-Nachrichtentext im Speicher zu sammeln, ohne die Nachrichten zu protokollieren.
#ifdef _WIN32
#include <windows.h>
#endif
#include <sql.h>
#include <sqlext.h>
#include <algorithm>
#include <limits>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
struct DiagnosticRecord {
std::string sqlstate;
SQLINTEGER native_error;
std::vector<SQLWCHAR> message;
bool message_truncated;
};
std::vector<DiagnosticRecord> ReadDiagnostics(SQLSMALLINT type, SQLHANDLE handle) {
const SQLSMALLINT limit = (std::numeric_limits<SQLSMALLINT>::max)();
std::vector<DiagnosticRecord> records;
for (SQLINTEGER number = 1; ; ++number) {
if (number > limit) {
throw std::runtime_error("Diagnostic record number exceeds SQLSMALLINT.");
}
SQLWCHAR state[6] = {};
SQLINTEGER native = 0;
std::vector<SQLWCHAR> message(256);
auto read = [&]() {
return SQLGetDiagRecW(type, handle, static_cast<SQLSMALLINT>(number),
state, &native, message.data(),
static_cast<SQLSMALLINT>(message.size()), nullptr);
};
SQLRETURN result = read();
if (result == SQL_NO_DATA) {
return records;
}
if (result == SQL_SUCCESS_WITH_INFO) {
message.resize(limit);
result = read(); // Retrieve the same record, not the next one.
}
if (result != SQL_SUCCESS && result != SQL_SUCCESS_WITH_INFO) {
throw std::runtime_error("SQLGetDiagRecW couldn't retrieve a diagnostic record.");
}
message.erase(std::find(message.begin(), message.end(), SQLWCHAR{0}), message.end());
records.push_back({
std::string(state, state + 5),
native,
std::move(message),
result == SQL_SUCCESS_WITH_INFO
});
}
}
Der Helfer versucht erneut eine abgeschnittene Nachricht mit der größten positiven Pufferlänge, die SQLGetDiagRecW akzeptiert. Wenn die Nachricht immer noch nicht passt, behält sie den verfügbaren Text und setzt message_truncated. Es geht weiter zum nächsten Datensatz, anstatt diese Abschneidung als Ende der Diagnoseliste zu behandeln. Es löst eine Ausnahme aus, wenn der Abruf fehlschlägt oder die Datensatznummer den SQLSMALLINT Bereich der API überschreitet.
Jede Nachricht enthält SQLWCHAR Codeeinheiten ohne den Nullterminator. Interpretiere sie nicht als wchar_t, da die Typen unterschiedlich breit sein können. Konvertiere sie in die Textcodierung deiner Anwendung, wenn du die Nachricht verarbeiten oder anzeigen musst.
Ruf den Helfer sofort nach dem Vorgang an, der einen Fehler oder eine Warnung zurückgibt. Dieses Fragment setzt voraus, dass statement ein gültiges, vorbereitetes Statement-Handle ist und dass die asynchrone Ausführung deaktiviert ist:
#include <iostream>
SQLRETURN ExecuteWithDiagnostics(SQLHSTMT statement) {
SQLRETURN result = SQLExecute(statement);
if (result == SQL_ERROR || result == SQL_SUCCESS_WITH_INFO) {
const auto records = ReadDiagnostics(SQL_HANDLE_STMT, statement);
for (const auto& record : records) {
std::cerr << "SQLExecute: SQLSTATE=" << record.sqlstate
<< " native_error=" << record.native_error
<< " message_truncated=" << record.message_truncated << '\n';
}
} else if (result == SQL_INVALID_HANDLE) {
throw std::runtime_error("SQLExecute returned SQL_INVALID_HANDLE.");
}
return result;
}
Der Wrapper bewahrt den ursprünglichen Rückgabecode, einschließlich SQL_SUCCESS_WITH_INFO. Wenden Sie dasselbe Muster auf andere ODBC-Aufrufe an und verwenden Sie dabei den Handle-Typ und den Handle, die dieser Operation zugeordnet sind. Behandle andere Rückgabecodes gemäß der Spezifikation dieser Funktion.
Die Ausgabe lässt record.message absichtlich aus. Wenn Sie Nachrichtentext in einem Logbuch benötigen, schwärzen Sie ihn gemäß der Datenrichtlinie Ihrer Anwendung, bevor Sie ihn in das Protokoll schreiben. Der Helfer bereinigt die im Speicher gespeicherten Nachrichten nicht.
Lesen Sie die Diagnosefelder
Die Felder beantworten verschiedene Fragen:
| Feld | Was es Ihnen sagt |
|---|---|
| SQLSTATE | Ein Code mit fünf Zeichen, der eine standardisierte diagnostische Bedingung identifiziert. Die Klasse besteht aus den ersten beiden Zeichen. |
| Nativer Fehlercode | Ein Wert, der spezifisch für die Datenquelle oder ODBC-Komponente ist. Es ist keine universelle Fehlernummer, und du solltest nicht annehmen, dass es eine SQL Server-Fehlernummer ist. |
| Text der Nachricht | Eine für Menschen lesbare Erklärung. Lies es mit dem SQLSTATE und dem nativen Fehlercode; werte es nicht als stabilen, maschinenlesbaren Schnittstellenvertrag aus. |
Der Treiber-Manager, der Treiber und die Datenquelle können jeweils Diagnosen generieren. Eine Komponente, die einen Datensatz hinzufügt, darf den Fehler oder die Warnung einer anderen Komponente nicht ersetzen oder verbergen. Ein nativer Fehlercode könnte nicht verfügbar sein oder keine sinnvolle Bedeutung für eine komponentengenerierte Diagnose haben. Weitere Informationen zu Komponentenregeln finden Sie unter Diagnosebehandlungsregeln. Weitere Informationen zu SQLSTATE-Klassen und -Werten finden Sie unter SQLSTATEs.
Verwenden Sie die Datensätze zusammen mit dem Funktions-Rückgabecode und der Operation. Zum Beispiel bedeutet SQL_SUCCESS_WITH_INFO, dass die Funktion abgeschlossen wurde, dies garantiert jedoch nicht, dass jeder Ausgabewert vollständig ist. Eine Warnung vor Abschneidung erfordert, dass Sie die zurückgegebene Länge überprüfen und entscheiden, ob Sie die verbleibenden Daten abrufen möchten. Weitere Informationen finden Sie unter Datenlänge, Pufferlänge und Abschneiden.
Sichere Beweise sammeln
Für einen Support-Fall notieren Sie den Funktionsnamen, den Handle-Typ, den Rückgabecode und jeden Diagnoseeintrag. Geben Sie die Treiber- und Treibermanager-Versionen, das Betriebssystem, die Architektur und den Datenquellentyp an. Schwärzen Sie Zugangsdaten, Zugriffstoken, Verbindungsstring-Geheimnisse, Anfragetext, Parameterwerte sowie persönliche oder regulierte Daten vor dem Speichern oder Teilen der Ausgabe. Diagnosemeldungen und Trace-Logs können Anwendungsdaten enthalten.
Beschränken Sie die Ablaufverfolgung auf die kürzeste erforderliche Reproduktion. Speichern Sie Protokolle in einem Verzeichnis, das nur für das Konto zugänglich ist, das die Anwendung ausführt, und verwenden Sie einen expliziten Protokollpfad anstelle eines gemeinsam genutzten oder temporären Standardpfads. Beende die Ablaufverfolgung, wenn die Reproduktion endet, und entferne die Trace-Datei, wenn du sie nicht mehr brauchst.
Auswahl der Ablaufverfolgungsebene
Anwendungsdiagnostik und Nachverfolgung beantworten verschiedene Fragen:
| Ebene | Was er erfasst | Verwenden Sie es für |
|---|---|---|
| Anwendungsdiagnose | Rückgabecodes und Diagnoseaufzeichnungen von einzelnen ODBC-Anrufen | Identifizieren Sie die Funktion, die fehlschlug oder eine Warnung zurückgab, und bewahren Sie alle Diagnosefelder bei. |
| ODBC Driver Manager Trace | ODBC-API-Aufrufe zwischen der Anwendung, dem Driver Manager und dem Treiber | Sehen Sie, welche Aufrufe die Anwendung gemacht hat und welche Rückgabecodes zurückkamen. Trace-Argumente können sensible Werte offenlegen. |
| Treiberspezifische Ablaufverfolgung | Interne Treiberereignisse, wenn der Treiber ein unterstütztes Steuerelement dokumentiert | Untersuche das Treiberverhalten, das ein API-Trace nicht anzeigen kann. Gehen Sie nicht davon aus, dass eine Driver Manager-Ablaufverfolgung diese Funktion aktiviert. |
Unter Windows unterstützt der ODBC Driver Manager die Nachverfolgung über die Registerkarte Tracing im ODBC Data Source Administrator sowie die Attribute SQL_ATTR_TRACE und SQL_ATTR_TRACEFILE. Die Nachverfolgung erfolgt standardmäßig pro Benutzer. Maschinenweite Nachverfolgung erfordert lokale Administratorrechte und kann Aufrufe von Anwendungen erfassen, die unter anderen lokalen Identitäten laufen. Bevorzugen Sie eine benutzerspezifische Ablaufverfolgung und stoppen Sie diese, sobald die Reproduktion endet. Weitere Informationen finden Sie unter Einstellen der Nachverfolgungsoptionen, Aktivieren der Nachverfolgung und SQLSetConnectAttr.
Unter Linux und macOS siehe Datenzugriffsverfolgung mit dem ODBC-Treiber unter Linux und macOS für die unixODBC Driver Manager-Konfiguration.
Die bestehenden Linux- und macOS Programmierungsrichtlinien enthalten noch den historischen Hinweis, dass die eingebaute Diagnostik (BID)-Ablaufverfolgung vor ODBC Driver 17.3 nicht verifiziert wurde. Diese Notiz beschreibt keine aktuelle, treiberspezifische Trace-Steuerung. Das unixODBC-Verfahren erfasst Driver Manager API-Aufrufe, nicht BID-Ereignisse.