SQLGetDiagRec-Funktion

Konformität
Eingeführte Version: ODBC 3.0 Normenkonformität: ISO 92

Summary
SQLGetDiagRec gibt die aktuellen Werte mehrerer Felder eines Diagnosedatensatzes zurück, die Fehler-, Warn- und Statusinformationen enthalten. Im Gegensatz zu SQLGetDiagField, das pro Aufruf ein Diagnosefeld zurückgibt, liefert SQLGetDiagRec mehrere häufig verwendete Felder eines Diagnosedatensatzes, darunter den SQLSTATE, den nativen Fehlercode und den Diagnosetext.

Syntax

  
SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);  

Argumente

HandleType-
[Eingabe] Ein Handletypbezeichner, der den Typ des Handles beschreibt, für den Diagnosen erforderlich sind. Muss einer der folgenden Werte sein:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN Handle wird nur vom Treiber-Manager und Treiber verwendet. Anwendungen sollten diesen Handletyp nicht verwenden. Weitere Informationen zu SQL_HANDLE_DBC_INFO_TOKEN finden Sie unter Developing Connection-Pool Awareness in an ODBC Driver.

Griff
[Eingabe] Ein Handle für die Diagnosedatenstruktur des Typs, der durch HandleTypeangegeben ist. Wenn HandleType- SQL_HANDLE_ENV ist, kann Handle entweder ein freigegebenes oder nicht freigegebenes Umgebungshandle sein.

RecNumber
[Eingabe] Gibt den Statusdatensatz an, aus dem die Anwendung Informationen angibt. Statusdatensätze werden von 1 nummeriert.

Sqlstate
[Ausgabe] Zeiger auf einen Puffer, in dem ein fünfstelliger SQLSTATE-Code (und terminierender NULL) für den Diagnosedatensatz RecNumber zurückgegeben werden kann. Die ersten beiden Zeichen geben die Klasse an; die nächsten drei zeigen die Unterklasse an. Diese Informationen sind im Bereich der SQL_DIAG_SQLSTATE Diagnostik enthalten. Weitere Informationen finden Sie unter SQLSTATEs.

NativeErrorPtr
[Ausgabe] Zeiger auf einen Puffer, in dem der native Fehlercode zurückgegeben werden kann, der spezifisch für die Datenquelle ist. Diese Informationen sind im SQL_DIAG_NATIVE Diagnosefeld enthalten.

MessageText
[Ausgabe] Zeiger auf einen Puffer, in dem die Diagnose-Nachrichtentext-Zeichenkette zurückgegeben werden kann. Diese Informationen sind im SQL_DIAG_MESSAGE_TEXT Diagnosefeld enthalten. Für das Format der Zeichenkette siehe Diagnostische Nachrichten.

Wenn MessageText NULL ist, gibt TextLengthPtr weiterhin die Gesamtzahl der Zeichen zurück (ohne das Null-Terminationszeichen für Zeichendaten), die im von MessageText gezeigten Puffer zurückgegeben werden können.

BufferLength
[Eingabe] Länge des *MessageText-Puffers in Zeichen. Es gibt keine maximale Länge des Diagnosetextes.

TextLengthPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (ohne die für das Null-Endzeichen) benötigte Anzahl der Zeichen zurückgegeben werden kann, die in *MessageText zurückgegeben werden können. Wenn die Anzahl der verfügbaren Zeichen größer als BufferLength ist, wird der diagnostische Nachrichtentext in *MessageText auf BufferLength minus die Länge eines Null-Terminationszeichens abgeschnitten.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA oder SQL_INVALID_HANDLE.

Diagnostics

SQLGetDiagRec veröffentlicht keine diagnostischen Datensätze für sich selbst. Es verwendet die folgenden Rückgabewerte, um das Ergebnis der eigenen Ausführung zu melden:

• SQL_SUCCESS: Die Funktion hat diagnoseinformationen erfolgreich zurückgegeben.

• SQL_SUCCESS_WITH_INFO: Der *MessageText-Puffer war zu klein, um die angeforderte Diagnosemeldung zu speichern. Es wurden keine Diagnosedaten erstellt. Um festzustellen, dass eine Abschneidung stattgefunden hat, muss die Anwendung BufferLength mit der tatsächlichen Anzahl der verfügbaren Bytes vergleichen, die in *TextLengthPTR geschrieben wird.

• SQL_INVALID_HANDLE: Der von HandleType angegebene Handle und Handle war kein gültiger Handle.

• SQL_ERROR: Eine der folgenden Aktionen ist aufgetreten:

  • RecNumber war negativ oder 0.

  • BufferLength war weniger als null.

  • Bei Verwendung asynchroner Benachrichtigung war der asynchrone Vorgang für das Handle nicht abgeschlossen.

• SQL_NO_DATA: RecNumber- war größer als die Anzahl der Diagnosedatensätze, die für den in Handle angegebenen Handle vorhanden waren. Die Funktion gibt auch SQL_NO_DATA für alle positiven RecNumber- zurück, wenn keine Diagnosedatensätze für Handlevorhanden sind.

Kommentare

Eine Anwendung ruft typischerweise SQLGetDiagRec auf, wenn ein vorheriger Aufruf einer ODBC-Funktion SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgegeben hat. Da jedoch jede ODBC-Funktion bei jedem Aufruf null oder mehr diagnostische Datensätze posten kann, kann eine Anwendung nach jedem ODBC-Funktionsaufruf SQLGetDiagRec aufrufen. Eine Anwendung kann SQLGetDiagRec mehrfach aufrufen, um einige oder alle Datensätze in der diagnostischen Datenstruktur zurückzugeben. ODBC setzt keine Begrenzung für die Anzahl der diagnostischen Datensätze, die zu einem bestimmten Zeitpunkt gespeichert werden können.

SQLGetDiagRec kann nicht verwendet werden, um Felder aus dem Header der diagnostischen Datenstruktur zurückzugeben. ( Das RecNumber-Argument muss größer als 0 sein.) Für diesen Zweck sollte die Anwendung SQLGetDiagField aufrufen.

SQLGetDiagRec ruft nur die diagnostischen Informationen ab, die zuletzt mit dem im Handle-Argument angegebenen Handle verknüpft sind. Wenn die Anwendung eine andere ODBC-Funktion aufruft, außer SQLGetDiagRec, SQLGetDiagField oder SQLError, gehen alle diagnostischen Informationen der vorherigen Aufrufe desselben Handles verloren.

Eine Anwendung kann alle diagnostischen Datensätze durch Schleifen scannen und RecNumber erhöhen, solange SQLGetDiagRec SQL_SUCCESS zurückgibt. Aufrufe zu SQLGetDiagRec sind für die Header- und Datensatzfelder nicht zerstörerisch. Die Anwendung kann SQLGetDiagRec zu einem späteren Zeitpunkt erneut aufrufen, um ein Feld aus einem Datensatz abzurufen, solange in der Zwischenzeit keine andere Funktion außer SQLGetDiagRec, SQLGetDiagField oder SQLError aufgerufen wurde. Die Anwendung kann außerdem die Gesamtzahl der verfügbaren Diagnosedatensätze abrufen, indem sie SQLGetDiagField aufruft, um den Wert des SQL_DIAG_NUMBER Feldes abzurufen, und dann SQLGetDiagRec mehrfach aufruft.

Für eine Beschreibung der Felder der diagnostischen Datenstruktur siehe SQLGetDiagField. Weitere Informationen finden Sie unter Using SQLGetDiagRec and SQLGetDiagField and Implementing SQLGetDiagRec and SQLGetDiagField.

Wenn Sie eine andere API als die api aufrufen, die asynchron ausgeführt wird, wird HY010 "Funktionssequenzfehler" generiert. Der Fehlerdatensatz kann jedoch nicht abgerufen werden, bevor der asynchrone Vorgang abgeschlossen ist.

HandleType-Argument

Jeder Handletyp kann diagnoseinformationen zugeordnet sein. Das Handle Type-Argument bezeichnet den Handle-Typ des Handle-Arguments.

Einige Header- und Datensatzfelder können nicht für Umgebungs-, Verbindungs-, Anweisungs- und Deskriptorhandles zurückgegeben werden. Die Handles, für die ein Feld nicht anwendbar ist, sind in den Abschnitten "Header Fields" und "Record Fields" in SQLGetDiagField angegeben.

Ein Aufruf zu SQLGetDiagRec gibt SQL_INVALID_HANDLE zurück, wenn HandleType SQL_HANDLE_SENV ist, was einen Shared Environment Handle bezeichnet. Wenn HandleType jedoch SQL_HANDLE_ENV ist, kann Handle entweder ein gemeinsamer oder ein ungeteilter Umgebungshandle sein.

Verwandte Funktionen

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien
• Beispiel-ODBC-Programm