SQLGetDiagRec-Funktion

Konformität
Version eingeführt: ODBC 3.0 Standards Compliance: ISO 92

Zusammenfassung
SQLGetDiagRec gibt die aktuellen Werte mehrerer Felder eines Diagnosedatensatzes zurück, der Fehler-, Warnungs- und Statusinformationen enthält. Im Gegensatz zu SQLGetDiagField, das ein Diagnosefeld pro Aufruf zurückgibt, gibt SQLGetDiagRec mehrere häufig verwendete Felder eines Diagnosedatensatzes zurück, einschließlich SQLSTATE, des systemeigenen Fehlercodes und des Diagnosemeldungstexts.

Syntax

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

Argumente

HandleType
[Eingabe] Ein Handle-Typbezeichner, der den Typ des Handles beschreibt, für den Diagnosen erforderlich sind. Dies muss eine der folgenden Ressourcen 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 Handle-Typ nicht verwenden. Weitere Informationen zu SQL_HANDLE_DBC_INFO_TOKEN finden Sie unter Developing Connection-Pool Awareness in an ODBC Driver.For more information about SQL_HANDLE_DBC_INFO_TOKEN, see Developing Connection-Pool Awareness in an ODBC Driver.

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

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

SQLState
[Ausgabe] Zeiger auf einen Puffer, in dem ein fünfstelliger SQLSTATE-Code (und das Beenden von NULL) für den Diagnosedatensatz RecNumber zurückgegeben werden soll. Die ersten beiden Zeichen geben die Klasse an; die nächsten drei geben die Unterklasse an. Diese Informationen sind im Feld SQL_DIAG_SQLSTATE Diagnose enthalten. Weitere Informationen finden Sie unter SQLSTATEs.

NativeErrorPtr
[Ausgabe] Zeiger auf einen Puffer, in dem der systemeigene Fehlercode zurückgegeben werden soll, spezifisch für die Datenquelle. Diese Informationen sind im Feld SQL_DIAG_NATIVE Diagnose enthalten.

MessageText
[Ausgabe] Zeiger auf einen Puffer, in dem die Textzeichenfolge der Diagnosemeldung zurückgegeben werden soll. Diese Informationen sind im Feld SQL_DIAG_MESSAGE_TEXT Diagnose enthalten. Das Format der Zeichenfolge finden Sie unter Diagnosemeldungen.

Wenn MessageText NULL ist, gibt TextLengthPtr weiterhin die Gesamtanzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den MessageText verweist.

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

TextLengthPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (mit Ausnahme der für das NULL-Terminierungszeichen erforderlichen Zeichen) zurückgegeben werden soll, die in *MessageText zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Zeichen größer als BufferLength ist, wird der Text der Diagnosemeldung in *MessageText in BufferLength abzüglich der Länge eines NULL-Terminierungszeichens abgeschnitten.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA oder SQL_INVALID_HANDLE.

Diagnose

SQLGetDiagRec stellt keine Diagnosedatensätze für sich selbst bereit. Es verwendet die folgenden Rückgabewerte, um das Ergebnis seiner eigenen Ausführung zu melden:

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

• SQL_SUCCESS_WITH_INFO: Der *MessageText-Puffer war zu klein, um die angeforderte Diagnosenachricht zu speichern. Es wurden keine Diagnosedatensätze generiert. Um festzustellen, ob ein Abschneiden aufgetreten ist, muss die Anwendung BufferLength mit der tatsächlichen Anzahl der verfügbaren Bytes vergleichen, die in *TextLengthPtr geschrieben wird.

• SQL_INVALID_HANDLE: Das durch HandleType und Handle angegebene Handle war kein gültiges Handle.

• SQL_ERROR: Eine der folgenden Aktionen ist aufgetreten:

  • RecNumber war negativ oder 0.

  • BufferLength war kleiner als 0 (null).

  • Bei Verwendung asynchroner Benachrichtigungen 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 das in Handle angegebene Handle vorhanden waren . Die Funktion gibt auch SQL_NO_DATA für alle positiven RecNumber-Werte zurück, wenn keine Diagnosedatensätze für Handle vorhanden sind.

Kommentare

Eine Anwendung ruft in der Regel 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 0 oder mehr Diagnosedatensätze veröffentlichen kann, kann eine Anwendung SQLGetDiagRec nach jedem ODBC-Funktionsaufruf aufrufen. Eine Anwendung kann SQLGetDiagRec mehrmals aufrufen, um einige oder alle Datensätze in der Diagnosedatenstruktur zurückzugeben. ODBC erzwingt keine Beschränkung für die Anzahl von Diagnosedatensätzen, die gleichzeitig gespeichert werden können.

SQLGetDiagRec kann nicht verwendet werden, um Felder aus dem Header der Diagnosedatenstruktur zurückzugeben. (Das RecNumber-Argument muss größer als 0 sein.) Die Anwendung sollte zu diesem Zweck SQLGetDiagField aufrufen.

SQLGetDiagRec ruft nur die Diagnoseinformationen ab, die zuletzt dem im Handle-Argument angegebenen Handle zugeordnet sind. Wenn die Anwendung eine andere ODBC-Funktion mit Ausnahme von SQLGetDiagRec, SQLGetDiagField oder SQLError aufruft, gehen alle Diagnoseinformationen aus den vorherigen Aufrufen desselben Handles verloren.

Eine Anwendung kann alle Diagnosedatensätze überprüfen, indem eine Schleife ausgeführt wird und RecNumber erhöht wird, solange SQLGetDiagRec SQL_SUCCESS zurückgibt. Aufrufe von SQLGetDiagRec sind für die Header- und Datensatzfelder nicht destruktiv. Die Anwendung kann SQLGetDiagRec zu einem späteren Zeitpunkt erneut aufrufen, um ein Feld aus einem Datensatz abzurufen, solange keine andere Funktion außer SQLGetDiagRec, SQLGetDiagField oder SQLError in der Zwischenzeit aufgerufen wurde. Die Anwendung kann auch die Anzahl der verfügbaren Diagnosedatensätze abrufen, indem SQLGetDiagField aufgerufen wird, um den Wert des felds SQL_DIAG_NUMBER abzurufen, und dann SQLGetDiagRec so oft aufgerufen wird.

Eine Beschreibung der Felder der Diagnosedatenstruktur finden Sie unter SQLGetDiagField. Weitere Informationen finden Sie unter Verwenden von SQLGetDiagRec und SQLGetDiagField und Implementieren von SQLGetDiagRec und 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

Jedem Handletyp können Diagnoseinformationen zugeordnet sein. Das HandleType-Argument gibt den Handle-Typ des Handle-Arguments an.

Einige Header- und Datensatzfelder können für Umgebungs-, Verbindungs-, Anweisungs- und Deskriptorhandles nicht zurückgegeben werden. Die Handles, für die kein Feld gilt, werden in den Abschnitten "Headerfelder" und "Datensatzfelder" in SQLGetDiagField angegeben.

Ein Aufruf von SQLGetDiagRec gibt SQL_INVALID_HANDLE zurück, wenn HandleType SQL_HANDLE_SENV ist, was ein Freigegebenes Umgebungshandle angibt. Wenn HandleType jedoch SQL_HANDLE_ENV ist, kann Handle entweder ein freigegebenes oder ein nicht freigegebenes Umgebungshandle sein.

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien
ODBC-Beispielprogramm