Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Gebruik deze richtlijn met Microsoft ODBC Driver 17 of 18. Het beschrijft het ODBC-diagnosecontract; het definieert geen versiespecifieke native foutmappingen.
Een ODBC-functie geeft een code terug die het resultaat van die aanroep beschrijft. Diagnostische dossiers geven meer details. De applicatieprogrammeerinterface (API) kan records rapporteren van de Driver Manager, de driver, de databron of meer dan één component. Behandel de retourcode, SQLSTATE, native foutcode en bericht niet als uitwisselbaar.
Interpreteer de retourcode
Controleer de retourcode voordat je output verwerkt of beslist of je het opnieuw probeert. Voor SQL_ERROR en SQL_SUCCESS_WITH_INFO, haal diagnostische gegevens op uit de handle die door de functie wordt gebruikt. Andere retourcodes kunnen ook diagnostische records hebben wanneer het functiecontract dat toestaat.
| Retourcode | Betekenis en reactie |
|---|---|
SQL_SUCCESS |
De functie is succesvol voltooid. Controleer het uitvoercontract van de functie. |
SQL_SUCCESS_WITH_INFO |
De functie is voltooid met waarschuwingen. Haal elk diagnostisch record op en controleer of de output compleet, omgezet of afgekapt is. |
SQL_ERROR |
De functie is niet uitgevoerd. Haal elk diagnostisch record op voordat je een andere functie op hetzelfde handle aanroept. |
SQL_INVALID_HANDLE |
De functie detecteerde een nullhandle of een handle van het verkeerde type. ODBC verstrekt geen diagnostische records voor deze retourcode. Controleer de functiereferentie voor extra handlevereisten. |
SQL_NO_DATA |
Er zijn geen verdere gegevens beschikbaar voor de bewerking. Controleer de functiereferentie, want de betekenis en eventuele statusrecords hangen af van de functie. |
Voor meer informatie over het volledige retourcodecontract, zie ODBC retourcodes.
Haal elk diagnostisch record op
Bel SQLGetDiagRec voor statusrecords vanaf recordnummer 1. Ga door totdat de functie terugkeert SQL_NO_DATA, of lees het aantal records uit header record 0 door aan te roepen SQLGetDiagField met SQL_DIAG_NUMBER.
SQLGetDiagRec geeft de SQLSTATE, de native foutcode en de berichttekst van een record terug. Gebruik SQLGetDiagField wanneer je andere header- of recordvelden nodig hebt.
Stop niet na het eerste record. Een ODBC-component kan een statusrecord toevoegen met informatie over zijn eigen laag, terwijl diagnostiek van een andere component behouden blijft. De volgorde en inhoud van het record kunnen helpen om te identificeren waar een fout vandaan kwam.
Verzamel de records tijdig. Een latere ODBC-aanroep die dezelfde handle gebruikt, vervangt het diagnostisch gebied, behalve aanroepen naar SQLGetDiagRec, SQLGetDiagField en de legacy-functie SQLError. Gebruik SQLGetDiagRec en SQLGetDiagField in nieuwe code.
SQLGetDiagRec kan SQL_SUCCESS_WITH_INFO retourneren wanneer de berichtbuffer te klein is. Het record werd teruggegeven, maar de berichttekst was afgekapt. Controleer de lengte van de gerapporteerde tekst en haal het bericht op met een grotere buffer als je de volledige tekst nodig hebt. Verwar deze retourcode van SQLGetDiagRec niet met de retourcode van de originele ODBC-functie.
Voor meer informatie over het ophalen van diagnostische gegevens, zie Diagnostische records, SQLGetDiagRec en SQLGetDiagField gebruiken, en de referenties voor SQLGetDiagRec en SQLGetDiagField.
Verzamel diagnostische records in C++
Gebruik deze C++11-helper met een bestaande ODBC-handle. Het roept SQLGetDiagRecW aan om SQLSTATE, native foutcode en Unicode-berichttekst in het geheugen te verzamelen zonder de berichten te loggen.
#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
});
}
}
De helper probeert opnieuw een afgeknotte boodschap met de grootste positieve bufferlengte die SQLGetDiagRecW accepteert. Als het bericht nog steeds niet past, behoudt het de beschikbare tekst en stelt message_truncated in. Het gaat door naar het volgende record in plaats van die afkapping als het einde van de diagnostische lijst te behandelen. Er wordt een uitzondering opgeworpen als het ophalen mislukt of het recordnummer het SQLSMALLINT bereik van de API overschrijdt.
Elk bericht bevat SQLWCHAR code-eenheden zonder de null-terminator. Herinterpreteer ze niet als wchar_t, want de types kunnen verschillende breedtes hebben. Zet ze om naar de tekstcodering van je applicatie wanneer je het bericht moet verwerken of weergeven.
Roep de helper direct aan na de bewerking die een fout of waarschuwing retourneert. Dit fragment gaat ervan uit dat statement een geldige, prepared statement-handle is en dat asynchrone uitvoering is uitgeschakeld:
#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;
}
De wrapper behoudt de oorspronkelijke retourcode, inclusief SQL_SUCCESS_WITH_INFO. Pas hetzelfde patroon toe op andere ODBC-aanroepen, met het handle type en de handle die bij die operatie horen. Behandel andere retourcodes volgens het contract van die functie.
De uitvoer laat record.message bewust weg. Als je berichttekst in een log nodig hebt, maskeer deze dan volgens het databeleid van je applicatie voordat je die daarin wegschrijft. De helper schoont de berichten die in het geheugen zijn opgeslagen niet op.
Lees de diagnostische velden
De velden beantwoorden verschillende vragen:
| Veld | Wat het u vertelt |
|---|---|
| SQLSTATE | Een code van vijf tekens die een gestandaardiseerde diagnostische aandoening identificeert. De klasse bestaat uit de eerste twee karakters. |
| Systeemeigen foutcode | Een waarde die specifiek is voor de databron of ODBC-component. Het is geen universeel foutgetal, en je moet er niet van uitgaan dat het een SQL Server-foutnummer is. |
| Tekst van het bericht | Een begrijpelijke uitleg. Lees het met de SQLSTATE en native foutcode; parseer het niet als een stabiel, machineleesbaar contract. |
De Driver Manager, driver en databron kunnen elk diagnostische gegevens genereren. Een component die een record toevoegt, mag de fout of waarschuwing van een andere component niet vervangen of maskeren. Een native foutcode kan niet beschikbaar zijn of geen nuttige betekenis hebben voor een door een component gegenereerd diagnostisch bericht. Voor meer informatie over de componentregels, zie regels voor diagnostische afhandeling. Voor meer informatie over SQLSTATE-klassen en -waarden, zie SQLSTATEs.
Gebruik de records samen met de functie-returncode en operatie. Bijvoorbeeld, SQL_SUCCESS_WITH_INFO betekent dat de functie voltooid is, maar het garandeert niet dat elke uitvoerwaarde compleet is. Een afkapwaarschuwing vereist dat je de teruggegeven lengte controleert en beslist of je de resterende data wilt ophalen. Voor meer informatie, zie Datalengte, bufferlengte en afkapping.
Verzamel bewijsmateriaal veilig
Voor een supportaanvraag noteer je de functienaam, het handletype, de retourcode en elk diagnostisch record. Inclusief de driver- en Driver Manager-versies, besturingssysteem, architectuur en type databron. Maak inloggegevens, toegangstokens, geheimen in verbindingsreeksen, querytekst, parameterwaarden en persoonlijke of gereguleerde gegevens onleesbaar voordat de output wordt opgeslagen of gedeeld. Diagnostische berichten en tracelogs kunnen applicatiegegevens bevatten.
Beperk het traceren tot het kortste reproductiegeval dat je nodig hebt. Sla logs op in een map die alleen toegankelijk is voor het account waaronder de applicatie wordt uitgevoerd, en gebruik een expliciet logpad in plaats van een gedeelde of tijdelijke standaard. Stop met traceren als het reproductieproces eindigt, en verwijder het tracebestand als je het niet meer nodig hebt.
Kies de tracinglaag
Applicatiediagnostiek en tracering beantwoorden verschillende vragen:
| Laag | Wat wordt vastgelegd | Gebruik het voor |
|---|---|---|
| Applicatiediagnostiek | Retourcodes en diagnostische records van individuele ODBC-oproepen | Identificeer de functie die faalde of een waarschuwing teruggaf, en bewaar alle diagnostische velden. |
| ODBC Driver Manager-trace | ODBC API-aanroepen tussen de applicatie, Driver Manager en driver | Bekijk welke oproepen de applicatie heeft gemaakt en welke retourcodes zijn teruggekomen. Trace-argumenten kunnen gevoelige waarden blootleggen. |
| Driver-specifieke trace | Interne drivergebeurtenissen, wanneer de driver een ondersteund besturingselement documenteert | Onderzoek het gedrag van drivers dat een API-trace niet kan tonen. Ga er niet van uit dat een Driver Manager-trace deze functionaliteit inschakelt. |
Op Windows ondersteunt de ODBC Driver Manager het traceren via het tabblad Tracing in ODBC Data Source Administrator en de SQL_ATTR_TRACE en SQL_ATTR_TRACEFILE attributen. Tracering is standaard per gebruiker. Machinebrede tracering vereist lokale beheerdersrechten en kan aanroepen vastleggen van applicaties die onder andere lokale identiteiten draaien. Geef de voorkeur aan tracering per gebruiker en stop deze zodra het reproduceren van het probleem is voltooid. Voor meer informatie, zie opties voor het instellen van traceren, Tracing inschakelen en SQLSetConnectAttr.
Op Linux en macOS, zie Data access tracing met de ODBC Driver op Linux en macOS voor de unixODBC Driver Manager-configuratie.
De bestaande Linux- en macOS-programmeerrichtlijnen bevatten een historische verklaring dat ingebouwde diagnostische (BID) tracering niet werd geverifieerd vóór ODBC Driver 17.3. Die notitie beschrijft geen huidige driver-specifieke trace-controle. De unixODBC-procedure legt Driver Manager API-aanroepen vast, niet BID-gebeurtenissen.