Anhang B: ODBC-Statusübergangstabellen
Die Tabellen in diesem Anhang zeigen, wie ODBC-Funktionen Übergänge der Umgebungs-, Verbindungs-, Anweisungs- und Deskriptorzustände verursachen. Der Zustand der Umgebung, Verbindung, Anweisung oder Deskriptor gibt in der Regel vor, wann Funktionen aufgerufen werden können, die den entsprechenden Handle-Typ (Umgebung, Verbindung, Anweisung oder Deskriptor) verwenden. Die Umgebungs-, Verbindungs-, Anweisungs- und Deskriptorzustände überlappen sich ungefähr, wie in den folgenden Abbildungen gezeigt. Beispielsweise ist die genaue Überlappung der Verbindungszustände C5 und C6 sowie der Anweisungszustände S1 bis S12 datenquellenabhängig, da Transaktionen zu unterschiedlichen Zeitpunkten auf verschiedenen Datenquellen beginnen, und der Deskriptorzustand D1i (implizit zugeordneter Deskriptor) vom Zustand der Anweisung abhängt, der der Deskriptor zugeordnet ist, während Zustand D1e (explizit zugeordneter Deskriptor) vom Zustand einer beliebigen Anweisung unabhängig ist. Eine Beschreibung der einzelnen Zustände finden Sie weiter unten in diesem Anhang unter Umgebungsübergänge, Verbindungsübergänge, Anweisungsübergänge und Deskriptorübergänge.
Die Umgebungs- und Verbindungszustände überschneiden sich wie folgt:
Die Verbindungs- und Anweisungszustände überschneiden sich wie folgt:
Die Anweisung und die Deskriptorzustände überschneiden sich wie folgt:
Die Verbindungs- und Deskriptorzustände überlappen sich wie folgt:
Jeder Eintrag in einer Übergangstabelle kann einer der folgenden Werte sein:
-- –Der Zustand bleibt unverändert, nachdem die Funktion ausgeführt wurde.
E
n , C_n_, S_n_ oder D_n_ : Der Umgebungs-, Verbindungs-, Anweisungs- oder Deskriptorzustand wird in den angegebenen Zustand verschoben.
(IH) – Ein ungültiges Handle wurde an die Funktion übergeben. Wenn das Handle ein NULL-Handle war oder ein gültiges Handle des falschen Typs war ( z. B. wurde ein Verbindungshandle übergeben, wenn ein Anweisungshandle erforderlich war ), gibt die Funktion SQL_INVALID_HANDLE zurück. andernfalls ist das Verhalten undefiniert und wahrscheinlich fatal. Dieser Fehler wird nur angezeigt, wenn es sich um das einzige mögliche Ergebnis des Aufrufs der Funktion im angegebenen Zustand handelt. Dieser Fehler ändert den Zustand nicht und wird immer vom Treiber-Manager erkannt, wie in den Klammern angegeben.
NS : Nächster Zustand. Der -Anweisungsübergang ist identisch, als hätte die -Anweisung die asynchronen Zustände nicht durchlaufen. Angenommen, eine Anweisung, die ein Resultset erstellt, wechselt in den Zustand S11, da SQLExecDirect SQL_STILL_EXECUTING zurückgegeben hat. Die NS-Notation im Zustand S11 bedeutet, dass die Übergänge für die Anweisung mit denen für eine Anweisung im Zustand S1 identisch sind, die ein Resultset erstellt. Wenn SQLExecDirect einen Fehler zurückgibt, bleibt die Anweisung im Zustand S1; wenn sie erfolgreich ist, wird die Anweisung in den Zustand S5 verschoben. wenn Daten benötigt werden, wird die Anweisung in den Zustand S8 verschoben. und wenn es weiterhin ausgeführt wird, bleibt es im Zustand S11.
XXXXX oder (XXXXX): Ein SQLSTATE-Objekt, das mit der Übergangstabelle verknüpft ist; SQLSTATEs, die vom Treiber-Manager erkannt werden, sind in Klammern eingeschlossen. Die Funktion hat SQL_ERROR und den angegebenen SQLSTATE zurückgegeben, aber der Zustand ändert sich nicht. Wenn SQLExecute beispielsweise vor SQLPrepare aufgerufen wird, wird SQLSTATE HY010 (Funktionssequenzfehler) zurückgegeben.
Hinweis
Die Tabellen zeigen keine Fehler an, die nicht mit den Übergangstabellen zusammenhängen, die den Zustand nicht ändern. Wenn SQLAllocHandle beispielsweise im Umgebungszustand E1 aufgerufen wird und SQLSTATE HY001 (Speicherzuordnungsfehler) zurückgibt, bleibt die Umgebung im Zustand E1; dies wird in der Umgebungsübergangstabelle für SQLAllocHandle nicht angezeigt.
Wenn die Umgebung, Verbindung, Anweisung oder Deskriptor in mehr als einen Zustand verschoben werden kann, wird jeder mögliche Zustand angezeigt, und eine oder mehrere Fußnoten erklären die Bedingungen, unter denen jeder Übergang stattfindet. Die folgenden Fußnoten können in jeder Tabelle angezeigt werden.
| Fußnote | Bedeutung |
|---|---|
| b | Vorher oder nachher. Der Cursor wurde vor dem Beginn des Resultsets oder nach dem Ende des Resultsets positioniert. |
| c | Aktuelle Funktion. Die aktuelle Funktion wurde asynchron ausgeführt. |
| d | Daten benötigen. Die funktion wurde SQL_NEED_DATA zurückgegeben. |
| e | Fehler. Die Funktion wurde SQL_ERROR zurückgegeben. |
| i | Ungültige Zeile. Der Cursor wurde in einer Zeile im Resultset positioniert, und entweder wurde die Zeile gelöscht oder ein Fehler bei einem Vorgang für die Zeile aufgetreten. Wenn das Zeilenstatusarray vorhanden war, wurde der Wert im Zeilenstatusarray für die Zeile SQL_ROW_DELETED oder SQL_ROW_ERROR. (Auf das Zeilenstatusarray wird vom Attribut SQL_ATTR_ROW_STATUS_PTR-Anweisung verwiesen.) |
| nf | Nicht gefunden: Die funktion wurde SQL_NO_DATA zurückgegeben. Dies gilt nicht, wenn SQLExecDirect, SQLExecute oder SQLParamData nach dem Ausführen einer durchsuchten Update- oder Delete-Anweisung SQL_NO_DATA zurückgibt. |
| np | Nicht vorbereitet. Die Anweisung wurde nicht vorbereitet. |
| nr | Keine Ergebnisse. Die Anweisung hat kein Resultset erstellt oder erstellt. |
| o | Andere Funktion. Eine andere Funktion wurde asynchron ausgeführt. |
| p | Vorbereitet. Die Anweisung wurde vorbereitet. |
| r | Ergebnisse. Die -Anweisung erstellt oder erstellt ein (möglicherweise leeres) Resultset. |
| s | Erfolg. Die Funktion wurde SQL_SUCCESS_WITH_INFO oder SQL_SUCCESS zurückgegeben. |
| v | Gültige Zeile. Der Cursor wurde in einer Zeile im Resultset positioniert, und die Zeile wurde erfolgreich eingefügt, erfolgreich aktualisiert oder ein anderer Vorgang für die Zeile erfolgreich abgeschlossen. Wenn das Zeilenstatusarray vorhanden war, wurde der Wert im Zeilenstatusarray für die Zeile SQL_ROW_ADDED, SQL_ROW_SUCCESS oder SQL_ROW_UPDATED. (Auf das Zeilenstatusarray wird vom Attribut SQL_ATTR_ROW_STATUS_PTR-Anweisung verwiesen.) |
| w | Ausführen. Die Funktion wurde SQL_STILL_EXECUTING zurückgegeben. |
SQLFreeHandle
In diesem Beispiel lautet die Zeile in der Übergangstabelle für den Umgebungszustand für SQLFreeHandle wie folgt, wenn HandleType SQL_HANDLE_ENV ist.
| E0 Nicht zugeordnet |
E1 Zugeordnet |
E2 Verbindung |
|---|---|---|
| (IH) | E0 | (HY010) |
Wenn SQLFreeHandle im Umgebungszustand E0 aufgerufen wird und HandleType auf SQL_HANDLE_ENV festgelegt ist, gibt der Treiber-Manager SQL_INVALID_HANDLE zurück. Wenn sie im Zustand E1 aufgerufen wird, wobei HandleType auf SQL_HANDLE_ENV festgelegt ist, wechselt die Umgebung in den Zustand E0, wenn die Funktion erfolgreich ist, und verbleibt im Zustand E1, wenn die Funktion ausfällt. Wenn er im Zustand E2 aufgerufen wird, wobei HandleType auf SQL_HANDLE_ENV festgelegt ist, gibt der Treiber-Manager immer SQL_ERROR und SQLSTATE HY010 (Funktionssequenzfehler) zurück, und die Umgebung verbleibt im Zustand E2.
Um die Zustandsübergangstabellen zu verstehen, müssen Sie verstehen, auf welches Element (Umgebung, Verbindung, Anweisung oder Deskriptor) sie sich beziehen. Angenommen, eine Funktion akzeptiert das Handle eines Elements vom Typ X. Die X-Zustandsübergangstabelle für diese Funktion beschreibt, wie sich das Aufrufen der Funktion mit dem Handle eines Elements vom Typ X auf dieses Element auswirkt. SqlDisconnect akzeptiert beispielsweise ein Verbindungshandle. In der Verbindungszustandsübergangstabelle für SQLDisconnect wird beschrieben, wie sich SQLDisconnect auf den Zustand der Verbindung auswirkt, für die sie aufgerufen wird.
Angenommen, eine Funktion akzeptiert das Handle eines Elements vom Typ Y, wobei Y nicht gleich X ist. Die X-Zustandsübergangstabelle für diese Funktion beschreibt, wie sich das Aufrufen der Funktion mit einem Handle vom Typ X, das dem Element des Typs Y zugeordnet ist, auf das Element vom Typ Y auswirkt. Beispielsweise beschreibt die Anweisungszustandsübergangstabelle für SQLDisconnect , wie SQLDisconnect den Zustand einer Anweisung beeinflusst, wenn es mit dem Handle der Verbindung aufgerufen wird, der die Anweisung zugeordnet ist.
Dieser Anhang enthält die folgenden Themen.