SQLGetDiagField-Funktion

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

Zusammenfassung
SQLGetDiagField den aktuellen Wert eines Felds eines Datensatzes der Diagnosedatenstruktur (zugeordnet mit einem angegebenen Handle) zurück, der Fehler-, Warnungs- und Statusinformationen enthält.

Syntax

SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

Argumente

HandleType-
[Eingabe] Ein Handletypbezeichner, der den Typ des Handles beschreibt, für den Diagnosen erforderlich sind. Muss eine 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 einem ODBC-Treiber-.

behandeln
[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. Wenn das argument DiagIdentifier ein beliebiges Feld des Diagnoseheaders angibt, wird RecNumber- ignoriert. Wenn nicht, sollte es mehr als 0 sein.

DiagIdentifier-
[Eingabe] Gibt das Feld der Diagnose an, dessen Wert zurückgegeben werden soll. Weitere Informationen finden Sie im Abschnitt "DiagIdentifier Argument" in "Kommentare".

DiagInfoPtr-
[Ausgabe] Zeigen Sie auf einen Puffer, in dem die Diagnoseinformationen zurückgegeben werden sollen. Der Datentyp hängt vom Wert DiagIdentifierab. Wenn DiagInfoPtr ein ganzzahliger Typ ist, sollten Anwendungen einen Puffer von SQLULEN verwenden und den Wert vor dem Aufrufen dieser Funktion auf 0 initialisieren, da einige Treiber möglicherweise nur die untere 32-Bit- oder 16-Bit-Version eines Puffers schreiben und das Bit der höheren Reihenfolge unverändert lassen.

Wenn DiagInfoPtr- NULL ist, gibt StringLengthPtr- weiterhin die Gesamtanzahl der Bytes zurück (ohne das Nullendpunktzeichen für Zeichendaten), das für die Rückgabe im Puffer verfügbar ist, auf DiagInfoPtrverweist.

BufferLength-
[Eingabe] Wenn DiagIdentifier eine ODBC-definierte Diagnose ist und DiagInfoPtr auf eine Zeichenzeichenfolge oder einen Binären Puffer zeigt, sollte dieses Argument die Länge von *DiagInfoPtrsein. Wenn DiagIdentifier- ein ODBC-definiertes Feld ist und *DiagInfoPtr eine ganze Zahl ist, wird BufferLength- ignoriert. Wenn der Wert in *DiagInfoPtr eine Unicode-Zeichenfolge ist (beim Aufrufen SQLGetDiagFieldW), muss das argument BufferLength eine gerade Zahl sein.

Wenn DiagIdentifier ein treiberdefiniertes Feld ist, gibt die Anwendung die Art des Felds an den Treiber-Manager an, indem sie das argument BufferLength festlegen. BufferLength- können die folgenden Werte aufweisen:

• Wenn DiagInfoPtr- ein Zeiger auf eine Zeichenfolge ist, ist BufferLength- die Länge der Zeichenfolge oder SQL_NTS.

• Wenn DiagInfoPtr- ein Zeiger auf einen Binärpuffer ist, platziert die Anwendung das Ergebnis des SQL_LEN_BINARY_ATTR(Länge) Makros in BufferLength-. Dadurch wird ein negativer Wert in BufferLength-platziert.

• Wenn DiagInfoPtr- ein Zeiger auf einen anderen Wert als eine Zeichenfolge oder binäre Zeichenfolge ist, sollte BufferLength- den Wert SQL_IS_POINTER aufweisen.

• Wenn *DiagInfoPtr einen Datentyp mit fester Länge enthält, ist BufferLength- nach Bedarf SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT oder SQL_IS_USMALLINT.

StringLengthPtr-
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtanzahl der Bytes zurückgegeben werden soll (mit Ausnahme der Anzahl der Bytes, die für das Nullendpunktzeichen erforderlich sind), die für die Rückgabe in *DiagInfoPtrfür Zeichendaten verfügbar sind. Wenn die Anzahl der zurückzugebenden Bytes größer oder gleich BufferLength-ist, wird der Text in *DiagInfoPtr abgeschnitten, um BufferLength minus der Länge eines NULL-Beendigungszeichens abgeschnitten.

Ertrag

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_NO_DATA.

Diagnostik

SQLGetDiagField keine Diagnosedatensätze für sich selbst bereitstellen. 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: *DiagInfoPtr war zu klein, um das angeforderte Diagnosefeld zu halten. Daher wurden die Daten im Diagnosefeld abgeschnitten. Um festzustellen, dass eine Abkürzung erfolgt ist, muss die Anwendung BufferLength- mit der tatsächlichen Anzahl der verfügbaren Bytes vergleichen, die in *StringLengthPtrgeschrieben wird.

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

• SQL_ERROR: Eine der folgenden Aktionen ist aufgetreten:

  • Das Argument "DiagIdentifier" war keiner der gültigen Werte.

  • Das Argument DiagIdentifier war SQL_DIAG_CURSOR_ROW_COUNT, SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE oder SQL_DIAG_ROW_COUNT, aber Handle war kein Anweisungshandle. (Der Treiber-Manager gibt diese Diagnose zurück.)

  • Das Argument RecNumber war negativ oder 0, wenn DiagIdentifier ein Feld aus einem Diagnosedatensatz anzeigte. RecNumber- wird für Kopfzeilenfelder ignoriert.

  • Der angeforderte Wert war eine Zeichenfolge, und BufferLength- kleiner als Null war.

  • 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 in der Regel SQLGetDiagField- auf, um eines von drei Zielen zu erreichen:

1. So erhalten Sie bestimmte Fehler- oder Warnungsinformationen, wenn ein Funktionsaufruf SQL_ERROR oder SQL_SUCCESS_WITH_INFO (oder SQL_NEED_DATA für die SQLBrowseConnect-funktion zurückgegeben hat).

2. Um die Anzahl der Zeilen in der Datenquelle zu ermitteln, die beim Einfügen, Löschen oder Aktualisieren von Vorgängen betroffen waren, mit einem Aufruf von SQLExecute, SQLExecDirect, SQLBulkOperationsoder SQLSetPos (aus dem Feld SQL_DIAG_ROW_COUNT Kopfzeile) oder um die Anzahl der Zeilen zu bestimmen, die im aktuellen geöffneten Cursor vorhanden sind, wenn der Treiber diese Informationen bereitstellen kann (aus dem SQL_DIAG_CURSOR_ROW_COUNT Kopfzeilenfeld).

3. Um zu bestimmen, welche Funktion durch einen Aufruf von SQLExecDirect oder SQLExecute- ausgeführt wurde (aus den Feldern SQL_DIAG_DYNAMIC_FUNCTION und SQL_DIAG_DYNAMIC_FUNCTION_CODE Header).

Jede ODBC-Funktion kann jedes Mal, wenn sie aufgerufen wird, null oder mehr Diagnosedatensätze bereitstellen, sodass eine Anwendung SQLGetDiagField- nach jedem ODBC-Funktionsaufruf aufrufen kann. Es gibt keine Beschränkung auf die Anzahl der Diagnosedatensätze, die jederzeit gespeichert werden können. SQLGetDiagField ruft nur die Diagnoseinformationen ab, die zuletzt der im Argument Handle angegebenen Diagnosedatenstruktur zugeordnet sind. Wenn die Anwendung eine andere ODBC-Funktion als SQLGetDiagField oder SQLGetDiagRecaufruft, gehen alle Diagnoseinformationen aus einem vorherigen Aufruf mit demselben Handle verloren.

Eine Anwendung kann alle Diagnosedatensätze scannen, indem RecNumber-erhöht wird, solange SQLGetDiagField SQL_SUCCESS zurückgibt. Die Anzahl der Statusdatensätze wird im kopfzeilenfeld SQL_DIAG_NUMBER angegeben. Aufrufe von SQLGetDiagField- sind nicht destruktiv für die Kopfzeilen- und Datensatzfelder. Die Anwendung kann SQLGetDiagField- später erneut aufrufen, um ein Feld aus einem Datensatz abzurufen, solange eine andere Funktion als die Diagnosefunktionen nicht in der Zwischenzeit aufgerufen wurde, was Datensätze auf demselben Handle posten würde.

Eine Anwendung kann SQLGetDiagField- aufrufen, um jedes Diagnosefeld jederzeit zurückzugeben, mit Ausnahme von SQL_DIAG_CURSOR_ROW_COUNT oder SQL_DIAG_ROW_COUNT, was SQL_ERROR zurückgibt, wenn Handle kein Anweisungshandle ist. Wenn ein anderes Diagnosefeld nicht definiert ist, gibt der Aufruf von SQLGetDiagField- SQL_SUCCESS zurück (sofern keine andere Diagnose erkannt wird), und für das Feld wird ein nicht definierter Wert zurückgegeben.

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 argument HandleType gibt den Handletyp Handlean.

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

Wenn HandleType- SQL_HANDLE_ENV ist, kann Handle entweder ein freigegebenes oder nicht freigegebenes Umgebungshandle sein.

Es sollten keine treiberspezifischen Headerdiagnosefelder einem Umgebungshandle zugeordnet werden.

Die einzigen Diagnoseheaderfelder, die für ein Deskriptorhandle definiert sind, sind SQL_DIAG_NUMBER und SQL_DIAG_RETURNCODE.

DiagIdentifier-Argument

Dieses Argument gibt den Bezeichner des Felds an, das aus der Diagnosedatenstruktur erforderlich ist. Wenn RecNumber- größer oder gleich 1 ist, werden in den Daten im Feld die von einer Funktion zurückgegebenen Diagnoseinformationen beschrieben. Wenn RecNumber 0 ist, befindet sich das Feld in der Kopfzeile der Diagnosedatenstruktur und enthält daher Daten im Zusammenhang mit dem Funktionsaufruf, der die Diagnoseinformationen zurückgegeben hat, nicht zu den spezifischen Informationen.

Treiber können treiberspezifische Kopfzeilen- und Datensatzfelder in der Diagnosedatenstruktur definieren.

Eine ODBC 3*.x*-Anwendung, die mit einem ODBC 2*.x*-Treiber arbeitet, kann SQLGetDiagField- nur mit einem DiagIdentifier--Argument von SQL_DIAG_CLASS_ORIGIN, SQL_DIAG_CLASS_SUBCLASS_ORIGIN, SQL_DIAG_CONNECTION_NAME, SQL_DIAG_MESSAGE_TEXT, SQL_DIAG_NATIVE, SQL_DIAG_NUMBER, SQL_DIAG_RETURNCODE, SQL_DIAG_SERVER_NAME, aufrufen. oder SQL_DIAG_SQLSTATE. Alle anderen Diagnosefelder geben SQL_ERROR zurück.

Kopfzeilenfelder

Die in der folgenden Tabelle aufgeführten Kopfzeilenfelder können im argument DiagIdentifier enthalten sein.

Datensatzfelder

Die in der folgenden Tabelle aufgeführten Datensatzfelder können in das argument DiagIdentifier eingeschlossen werden.

Werte der Dynamischen Funktionsfelder

In der folgenden Tabelle werden die Werte von SQL_DIAG_DYNAMIC_FUNCTION und SQL_DIAG_DYNAMIC_FUNCTION_CODE beschrieben, die für jeden SQL-Anweisungstyp gelten, der durch einen Aufruf von SQLExecute oder SQLExecDirect-ausgeführt wird. Der Treiber kann den aufgelisteten Werten treiberdefinierte Werte hinzufügen.

Sequenz von Statusdatensätzen

Statusdatensätze werden basierend auf der Zeilennummer und dem Typ der Diagnose in einer Sequenz positioniert. Der Treiber-Manager bestimmt die endgültige Reihenfolge, in der Statusdatensätze zurückgegeben werden, die generiert werden. Der Treiber bestimmt die endgültige Reihenfolge, in der Statusdatensätze zurückgegeben werden, die generiert werden.

Wenn Diagnosedatensätze sowohl vom Treiber-Manager als auch vom Treiber bereitgestellt werden, ist der Treiber-Manager für die Bestellung verantwortlich.

Wenn zwei oder mehr Statusdatensätze vorhanden sind, wird die Abfolge der Datensätze zuerst anhand der Zeilennummer bestimmt. Die folgenden Regeln gelten für die Ermittlung der Abfolge von Diagnosedatensätzen nach Zeile:

• Datensätze, die keiner Zeile entsprechen, werden vor Datensätzen angezeigt, die einer bestimmten Zeile entsprechen, da SQL_NO_ROW_NUMBER als -1 definiert ist.

• Datensätze, für die die Zeilennummer unbekannt ist, werden vor allen anderen Datensätzen angezeigt, da SQL_ROW_NUMBER_UNKNOWN als -2 definiert ist.

• Für alle Datensätze, die sich auf bestimmte Zeilen beziehen, werden Datensätze nach dem Wert im feld SQL_DIAG_ROW_NUMBER sortiert. Alle Fehler und Warnungen der ersten betroffenen Zeile werden aufgelistet, und dann alle Fehler und Warnungen der nächsten betroffenen Zeile usw.

Innerhalb jeder Zeile oder für alle Datensätze, die keiner Zeile entsprechen oder für die die Zeilennummer unbekannt ist, oder für alle diese Datensätze mit einer Zeilennummer, die SQL_NO_ROW_NUMBER entspricht, wird der erste aufgelistete Datensatz mithilfe einer Reihe von Sortierregeln bestimmt. Nach dem ersten Datensatz ist die Reihenfolge der anderen Datensätze, die sich auf eine Zeile auswirken, nicht definiert. Eine Anwendung kann nicht davon ausgehen, dass Vorwarnungen nach dem ersten Datensatz auftreten. Anwendungen sollten die vollständige Diagnosedatenstruktur überprüfen, um vollständige Informationen zu einem erfolglosen Aufruf einer Funktion zu erhalten.

Die folgenden Regeln werden verwendet, um den ersten Datensatz in einer Zeile zu bestimmen. Der Datensatz mit dem höchsten Rang ist der erste Datensatz. Die Quelle eines Datensatzes (Treiber-Manager, Treiber, Gateway usw.) wird beim Bewerten von Datensätzen nicht berücksichtigt.

• Fehler Statusdatensätze, die Fehler beschreiben, haben die höchste Rangfolge. Die folgenden Regeln werden auf Sortierfehler angewendet:

  • Datensätze, die auf einen Transaktionsfehler oder einen möglichen Transaktionsfehler hinweisen, haben alle anderen Datensätze überlagert.

  • Wenn zwei oder mehr Datensätze dieselbe Fehlerbedingung beschreiben, haben SQLSTATEs, die von der Open Group CLI-Spezifikation (Klassen 03 bis HZ) definiert sind, ODBC- und treiberdefinierte SQLSTATEs ausrangiert.

• Implementierungsdefinierte No Data Values Statusdatensätze, die treiberdefinierte Keine Datenwerte (Klasse 02) beschreiben, haben die zweithöchste Rangfolge.

• Warnungen Statusdatensätze, die Warnungen (Klasse 01) beschreiben, haben die niedrigste Rangfolge. Wenn zwei oder mehr Datensätze dieselbe Warnungsbedingung beschreiben, werden SQLSTATEs, die durch die Open Group CLI-Spezifikation definiert sind, ODBC-definierte und treiberdefinierte SQLSTATEs überschrieben.

Verwandte Funktionen

Siehe auch

ODBC-API-Referenz
ODBC-Headerdateien