FETCH-Anweisung [ESQL] [SP]

Mit dieser Anweisung positionieren Sie einen Cursor neu und fragen danach Daten von ihm ab.

Syntax

FETCH Cursorposition Cursorname
[ INTO { Hostvariablenliste | Variablenliste } | USING DESCRIPTOR SQLDA-Name PURGE]
[ BLOCK n ]
[ FOR UPDATE]
[ ARRAY Abrufanzahl ]
INTO Variablenliste [FOR UPDATE ]

Cursorposition :
    NEXT | PRIOR | FIRST | LAST
| { ABSOLUTE | RELATIVE } Zeilenanzahl

Zeilenanzahl : Anzahl oder Hostvariable

Cursorname : Bezeichner oder Hostvariable

Hostvariablenliste : Kann Indikatorvariablen enthalten

Variablenliste : Variable von gespeicherten Prozeduren

SQLDA-Name : Bezeichner

Abrufanzahl :  Ganzzahl oder Hostvariable

Parameter

INTO-Klausel Die INTO-Klausel ist optional. Wenn sie nicht angegeben ist, positioniert die FETCH-Anweisung nur den Cursor. Die Hostvariablenliste kann nur in Embedded SQL verwendet werden.
Cursorposition Mithilfe eines optionalen Positionsparameters kann der Cursor bewegt werden, bevor die Zeile abgerufen wird. Wenn der Abruf einen Positionierungsparameter enthält und sich die Position außerhalb der zulässigen Cursorpositionen befindet, wird die Warnung SQLE_NOTFOUND ausgegeben, und das SQLCOUNT-Feld zeigt den Ausgangspunkt von einer gültigen Position an.
Die OPEN-Anweisung positioniert den Cursor zu Beginn vor der ersten Zeile.
NEXT-Klausel Next ist die Standardpositionierung. Sie veranlasst, dass der Cursor um eine Zeile vorgerückt wird, bevor die Zeile abgerufen wird.
PRIOR-Klausel Bewirkt, dass der Cursor vor dem Abrufen eine Zeile zurückrückt
RELATIVE-Klausel RELATIVE-Positionierung wird verwendet, um den Cursor vor dem Abruf um eine angegebene Anzahl von Zeilen in die eine oder andere Richtung zu bewegen. Eine positive Zahl zeigt eine Vorwärtsbewegung, eine negative Zahl eine Rückwärtsbewegung an. Daher ist NEXT gleichwertig mit RELATIVE 1 und PRIOR gleichwertig mit RELATIVE -1. RELATIVE 0 fragt dieselbe Zeile ab wie in der letzten FETCH-Anweisung für diesen Cursor.
ABSOLUTE-Klausel Der Positionierungsparameter ABSOLUTE wird verwendet, um zu einer bestimmten Zeile zu gehen. Eine 0 gibt die Position vor der ersten Zeile an (siehe Cursor in Prozeduren und Triggern verwenden).
Eine Eins (1) gibt die erste Zeile an, usw. Negative Zahlen werden benutzt, um eine absolute Position ab dem Ende des Cursors anzugeben. Eine negative Eins (-1) gibt die letzte Zeile des Cursors an.
FIRST-Klausel Eine Kurzform für ABSOLUTE 1
LAST-Klausel Eine Kurzform für ABSOLUTE -1

Probleme mit der Cursorpositionierung

Einfügungen und einige Aktualisierungen zu DYNAMIC SCROLL-Cursorn können Probleme bei der Cursorpositionierung verursachen. Der Datenbankserver platziert eingefügte Zeilen an unvorhersehbaren Positionen innerhalb eines Cursors, falls die SELECT-Anweisung keine ORDER BY-Klausel hat. In einigen Fällen erscheint die eingefügte Zeile überhaupt nicht, bis der Cursor geschlossen und wieder geöffnet wurde.

Dies tritt auf, wenn zum Öffnen eines Cursors eine temporäre Tabelle erstellt werden musste. Eine Beschreibung finden Sie unter Arbeitstabellen in der Abfrageverarbeitung verwenden ("Alle Zeilen" als Optimierungsziel verwenden).

Die UPDATE-Anweisung kann bewirken, dass sich eine Zeile im Cursor verschiebt. Das geschieht, wenn der Cursor eine ORDER BY-Klausel besitzt, die einen vorhandenen Index verwendet (es wird keine temporäre Tabelle erstellt).
BLOCK-Klausel Eine Clientanwendung kann mehr als eine Zeile gleichzeitig abrufen. Dies wird Blockabruf, Prefetch-Vorgang oder Mehrzeilenabruf genannt. Der erste Abruf bewirkt, dass mehrere Zeilen vom Datenbankserver zurückgesendet werden. Der Client puffert diese Zeilen, und nachfolgende Abrufe werden ohne erneute Anforderung an den Datenbankserver aus diesen Puffern abgerufen.
Die BLOCK-Klausel kann nur in Embedded SQL verwendet werden. Sie gibt Client und Server einen Hinweis, wie viele Zeilen von der Anwendung abgerufen werden können. Der Spezialwert 0 bedeutet, dass die Anforderung an den Datenbankserver geschickt und eine einzelne Zeile zurückgegeben wird (keine Zeilenblockierung). Die BLOCK-Klausel verringert die Anzahl der Zeilen, die ins nächste Prefetch an den BLOCK-Wert aufgenommen werden. Um die Anzahl der Prefetch-Zeilen zu erhöhen, verwenden Sie den PrefetchRows-Verbindungsparameter.

Wenn Sie keine BLOCK-Klausel angeben, wird der für OPEN angegebene Wert verwendet. Weitere Hinweise finden Sie unter OPEN-Anweisung [ESQL] [SP].

FETCH RELATIVE 0 ruft die Zeile immer erneut ab.

Wenn Prefetch für den Cursor deaktiviert ist, wird die BLOCK-Klausel ignoriert und die Zeilen werden einzeln eingelesen. Wenn auch ARRAY angegeben ist, wird die durch ARRAY angegebene Anzahl von Zeilen eingelesen.
PURGE-Klausel Die PURGE-Klausel kann nur in Embedded SQL verwendet werden. Sie bewirkt, dass der Client seine Puffer für alle Zeilen leert und dann die Abrufanforderung an den Datenbankserver sendet. Beachten Sie, dass diese Abrufanforderung einen Zeilenblock zurückgeben kann.
FOR UPDATE-Klausel Die FOR UPDATE-Klausel gibt an, dass die abgerufene Zeile anschließend mit einer UPDATE WHERE CURRENT OF CURSOR-Anweisung aktualisiert wird. Diese Klausel bewirkt, dass der Datenbankserver eine Absichtssperre auf die Zeile setzt. Die Sperre wird bis zum Ende der aktuellen Transaktion aufrechterhalten. Weitere Hinweise hierzu finden Sie unter Funktionsweise von Sperren und in der Beschreibung der FOR UPDATE-Klausel der SELECT-Anweisung.
ARRAY-Klausel Die ARRAY-Klausel kann nur in Embedded SQL verwendet werden. Sie ermöglicht sogenannte weite Abrufe, die mehr als eine Zeile gleichzeitig abrufen und so die Performance verbessern können.
Um weite Abrufe in Embedded SQL zu verwenden, fügen Sie die Abrufanweisung wie folgt in Ihren Code ein:
EXEC SQL FETCH ... ARRAY nnn
Dabei ist ARRAY nnn das letzte Element der FETCH-Anweisung. Die Abrufanzahl nnn kann eine Hostvariable sein. SQLDA muss nnn * (Spalten pro Zeile)-Variablen enthalten. Die erste Zeile wird in die SQLDA-Variablen von 0 bis (Spalten pro Zeile)-1 geschrieben, usw.

Ein ausführliches Beispiel zur Verwendung von weiten Abrufen finden Sie unter Mehr als eine Zeile auf einmal abrufen.

Bemerkungen

Die FETCH-Anweisung ruft eine Zeile aus dem benannten Cursor ab. Der Cursor muss zuvor geöffnet worden sein.

Embedded SQL verwenden Eine DECLARE CURSOR-Anweisung muss vor der FETCH-Anweisung im C-Quellcode erscheinen, und die OPEN-Anweisung muss vor der FETCH-Anweisung ausgeführt werden. Wenn eine Hostvariable für einen Cursornamen verwendet wird, erzeugt die DECLARE-Anweisung Code und muss vor der FETCH-Anweisung ausgeführt werden.

Der Server gibt in SQLCOUNT die Anzahl der abgerufenen Datensätze zurück, wobei SQLCOUNT immer größer als 0 ist, es sei denn, es liegt ein Fehler oder eine Warnung vor.

Wenn die Warnung SQLSTATE_NOTFOUND für den Abruf zurückgegeben wird, enthält das Feld sqlerrd[2] des SQLCA (SQLCOUNT) die Anzahl der Zeilen, um die der Abrufversuch die zulässige Cursorposition überschritten hat. Der Wert ist 0 (Null), falls die Zeile nicht gefunden wurde, die Position aber gültig ist, z.B., wenn FETCH RELATIVE 1 ausgeführt wird, und die Position auf der letzten Zeile eines Cursors ist. Der Wert ist positiv, falls das Abrufen jenseits des Cursors versucht wurde, und negativ, falls das Abrufen vor dem Anfang des Cursors versucht wurde. Der Cursor wird auf die letzte Zeile positioniert, falls das Abrufen jenseits des Cursors versucht wurde, und auf die erste Zeile, falls das Abrufen vor dem Anfang des Cursors versucht wurde.

Nach der erfolgreichen Ausführung der FETCH-Anweisung, wird das Feld sqlerrd[1] des SQLCA (SQLIOCOUNT) um die Anzahl der Ein-/Ausgabevorgänge erhöht, die erforderlich sind, um den Abruf auszuführen. Dieses Feld erhöht sich bei jeder Datenbankanweisung.

Einzeiliges Abrufen Eine Zeile aus dem Ergebnis der SELECT-Anweisung wird in den Variablen der Variablenliste abgelegt. Die Entsprechung von Auswahlliste zu Hostvariablenliste ist eins zu eins.

Mehrzeiliges Abrufen Eine oder mehr Zeilen aus dem Ergebnis der SELECT-Anweisung werden entweder in den Variablen in der Variablenliste oder in den von SQLDA-Name beschriebenen Programmdatenbereichen abgelegt. In beiden Fällen entspricht die Auswahlliste eins zu eins der Hostvariablenliste oder dem SQLDA-Name-Deskriptorfeld.

Berechtigungen

Der Cursor muss geöffnet sein, und der Benutzer muss SELECT-Berechtigung für Tabellen haben, die in der Deklaration des Cursors referenziert werden.

Nebenwirkungen

Keine.

Siehe auch

Standards und Kompatibilität

SQL/2003 Kernfunktion. Bei Verwendung in Prozeduren ist es eine Persistent-Stored-Module-Funktion.

Beispiel

Im Folgenden finden Sie ein Beispiel für Embedded SQL:

EXEC SQL DECLARE cur_employee CURSOR FOR
SELECT EmployeeID, Surname FROM Employees;
EXEC SQL OPEN cur_employee;
EXEC SQL FETCH cur_employee
INTO :emp_number, :emp_name:indicator;

Es folgt ein Beispiel für eine Prozedur:

BEGIN
   DECLARE cur_employee CURSOR FOR
      SELECT Surname
      FROM Employees;
   DECLARE name CHAR(40);
   OPEN cur_employee;
   lp: LOOP
      FETCH NEXT cur_employee into name;
      IF SQLCODE <> 0 THEN LEAVE lp END IF;
       ...
   END LOOP;
   CLOSE cur_employee;
END

Kommentieren Sie diese Seite in DocCommentXchange.
Senden Sie uns Feedback über diese Seite via E-Mail.