Freigeben über

SQLFetchScroll-Funktion

  • Artikel

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

Zusammenfassung
SQLFetchScroll ruft das angegebene Rowset von Daten aus dem Resultset ab und gibt Daten für alle gebundenen Spalten zurück. Rowsets können an einer absoluten oder relativen Position oder durch Textmarke angegeben werden.

Beim Arbeiten mit einem ODBC 2.x-Treiber ordnet der Treiber-Manager diese Funktion SQLExtendedFetch zu. Weitere Informationen finden Sie unter Zuordnen von Ersetzungsfunktionen für die Abwärtskompatibilität von Anwendungen.

Syntax

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

FetchOrientation
[Eingabe]

Typ des Abrufs:

SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARK

Weitere Informationen finden Sie unter "Positionieren des Cursors" im Abschnitt "Kommentare".

FetchOffset
[Eingabe]

Die Nummer der abzurufenden Zeile. Die Interpretation dieses Arguments hängt vom Wert des FetchOrientation-Arguments ab . Weitere Informationen finden Sie unter "Positionieren des Cursors" im Abschnitt "Kommentare".

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLFetchScroll entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLFetchScroll zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben. Wenn in einer einzelnen Spalte ein Fehler auftritt, kann SQLGetDiagField mit einem DiagIdentifier von SQL_DIAG_COLUMN_NUMBER aufgerufen werden, um die Spalte zu ermitteln, für die der Fehler aufgetreten ist. SqlGetDiagField kann mit einem DiagIdentifier von SQL_DIAG_ROW_NUMBER aufgerufen werden, um die Zeile zu bestimmen, die diese Spalte enthält.

Für alle SQLSTATEs, die SQL_SUCCESS_WITH_INFO oder SQL_ERROR (mit Ausnahme von 01xxx SQLSTATEs) zurückgeben können, wird SQL_SUCCESS_WITH_INFO zurückgegeben, wenn ein Fehler für einen oder mehrere, jedoch nicht alle Zeilen eines Mehrzeilenvorgangs auftritt, und SQL_ERROR zurückgegeben wird, wenn ein Fehler bei einem Einzelzeilenvorgang auftritt.

SQLSTATE Error Beschreibung
01000 Allgemeiner Warnhinweis Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01004 Zeichenfolgendaten, rechts abgeschnitten Zeichenfolgen- oder Binärdaten, die für eine Spalte zurückgegeben werden, führten zum Abschneiden von nicht leeren Zeichen- oder Nicht-NULL-Binärdaten. Wenn es sich um einen Zeichenfolgenwert handelte, wurde er mit der rechten Abkürzung versehen.
01S01 Fehler in Zeile Fehler beim Abrufen einer oder mehrerer Zeilen.

(Wenn dieser SQLSTATE-Wert zurückgegeben wird, wenn eine ODBC 3*.x*-Anwendung mit einem ODBC 2*.x*-Treiber arbeitet, kann sie ignoriert werden.)
01S06 Versuch, abzurufen, bevor das Resultset das erste Rowset zurückgegeben hat Das angeforderte Rowset überlappt den Anfang des Resultsets, als FetchOrientation SQL_FETCH_PRIOR wurde, die aktuelle Position lag über der ersten Zeile und die Anzahl der aktuellen Zeile ist kleiner oder gleich der Rowsetgröße.

Das angeforderte Rowset überlappt den Anfang des Resultsets, als FetchOrientation SQL_FETCH_PRIOR wurde, die aktuelle Position lag über dem Ende des Resultsets, und die Rowsetgröße war größer als die Ergebnissatzgröße.

Das angeforderte Rowset überlappt den Start des Resultsets, als FetchOrientation SQL_FETCH_RELATIVE wurde, FetchOffset negativ war und der absolute Wert von FetchOffset kleiner oder gleich der Rowset-Größe war.

Das angeforderte Rowset überlappt den Anfang des Resultsets, als FetchOrientation SQL_FETCH_ABSOLUTE war, FetchOffset negativ war und der absolute Wert von FetchOffset größer als die Resultsetgröße, aber kleiner oder gleich der Rowsetgröße war.

(Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01S07 Bruchabkürzung Die für eine Spalte zurückgegebenen Daten wurden abgeschnitten. Bei numerischen Datentypen wurde der Bruchteil der Zahl abgeschnitten. Für Zeit-, Zeitstempel- und Intervalldatentypen, die eine Zeitkomponente enthalten, wurde der Bruchteil der Zeit abgeschnitten.

(Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
07006 Verletzung des Eingeschränkten Datentyp-Attributs Der Datenwert einer Spalte im Resultset konnte nicht in den durch TargetType in SQLBindCol angegebenen Datentyp konvertiert werden.

Spalte 0 wurde mit einem Datentyp von SQL_C_BOOKMARK gebunden, und das attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung wurde auf SQL_UB_VARIABLE festgelegt.

Spalte 0 wurde an einen Datentyp von SQL_C_VARBOOKMARK gebunden, und das attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung wurde nicht auf SQL_UB_VARIABLE festgelegt.
07009 Ungültiger Deskriptorindex Der Treiber war ein ODBC 2*.x*-Treiber, der SQLExtendedFetch nicht unterstützt, und eine in der Bindung für eine Spalte angegebene Spaltennummer war 0.

Spalte 0 wurde gebunden, und das attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung wurde auf SQL_UB_OFF festgelegt.
08S01 Kommunikationslinkfehler Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde.
22001 Zeichenfolgendaten, rechts abgeschnitten Eine Textmarke mit variabler Länge, die für eine Spalte zurückgegeben wird, wurde abgeschnitten.
22002 Indikatorvariable erforderlich, aber nicht angegeben NULL-Daten wurden in eine Spalte abgerufen, deren StrLen_or_IndPtr von SQLBindCol (oder SQL_DESC_INDICATOR_PTR von SQLSetDescField oder SQLSetDescRec festgelegt) ein Nullzeiger war.
22003 Numerischer Wert außerhalb des Bereichs Das Zurückgeben des numerischen Werts (als numerische oder Zeichenfolge) für eine oder mehrere gebundene Spalten hätte dazu geführt, dass der gesamte Teil (im Gegensatz zu Bruchzahlen) der Zahl abgeschnitten wird.

Weitere Informationen finden Sie unter Konvertieren von Daten aus SQL in C-Datentypen in Anhang D: Datentypen.
22007 Ungültiges Datetime-Format Eine Zeichenspalte im Resultset wurde an eine Datums-, Uhrzeit- oder Zeitstempel-C-Struktur gebunden, und ein Wert in der Spalte war jeweils ein ungültiges Datum, eine Uhrzeit oder ein Zeitstempel.
22012 Division durch Null Ein Wert aus einem arithmetischen Ausdruck wurde zurückgegeben, was zu Einer Division durch Null führte.
22015 Intervallfeldüberlauf Das Zuweisen eines genauen numerischen oder Intervall-SQL-Typs zu einem Intervall-C-Typ hat zu einem Verlust signifikanter Ziffern im führenden Feld geführt.

Beim Abrufen von Daten in einen Intervall-C-Typ gab es keine Darstellung des Werts des SQL-Typs im Intervall C-Typ.
22018 Ungültiger Zeichenwert für die Umwandlungsspezifikation Eine Zeichenspalte im Resultset wurde an einen Zeichen C-Puffer gebunden, und die Spalte enthielt ein Zeichen, für das keine Darstellung im Zeichensatz des Puffers vorhanden war.

Der Typ C war eine genaue oder ungefähre Zahl, ein Datum/Uhrzeit oder ein Intervall-Datentyp; Der SQL-Typ der Spalte war ein Zeichendatentyp; und der Wert in der Spalte war kein gültiges Literal des gebundenen C-Typs.
24.000 Ungültiger Cursorstatus Die Anweisungshandle wurde in einem ausgeführten Zustand ausgeführt, aber dem StatementHandle wurde kein Resultset zugeordnet.
40001 Serialisierungsfehler Die Transaktion, in der der Abruf ausgeführt wurde, wurde beendet, um deadlock zu verhindern.
40003 Abschluss der Anweisung unbekannt Fehler bei der zugehörigen Verbindung während der Ausführung dieser Funktion, und der Status der Transaktion kann nicht bestimmt werden.
HY000 Allgemeiner Fehler Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und dessen Ursache.
HY001 Speicherzuweisungsfehler Der Treiber konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen.
HY008 Vorgang abgebrochen Die asynchrone Verarbeitung wurde für " StatementHandle" aktiviert. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für die Anweisungshandle aufgerufen. Anschließend wurde die Funktion erneut für " StatementHandle" aufgerufen.

Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle von einem anderen Thread in einer Multithreadanwendung aufgerufen.
HY010 Funktionssequenzfehler (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungshandle aufgerufen, der dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die SQLFetchScroll-Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für " StatementHandle " aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden.

(DM) Das angegebene StatementHandle war nicht in einem ausgeführten Zustand. Die Funktion wurde aufgerufen, ohne zuerst SQLExecDirect, SQLExecute oder eine Katalogfunktion aufzurufen.

(DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das StatementHandle aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für " StatementHandle " aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden.

(DM) SQLFetch wurde für " StatementHandle " aufgerufen, nachdem SQLExtendedFetch aufgerufen wurde und bevor SQLFreeStmt mit der option SQL_CLOSE aufgerufen wurde.
HY013 Speicherverwaltungsfehler Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen.
HY090 Ungültige Zeichenfolgen- oder Pufferlänge Das Attribut der SQL_ATTR_USE_BOOKMARK-Anweisung wurde auf SQL_UB_VARIABLE festgelegt, und Spalte 0 wurde an einen Puffer gebunden, dessen Länge nicht der maximalen Länge für die Textmarke für diesen Resultset entspricht. (Diese Länge ist im Feld SQL_DESC_OCTET_LENGTH des IRD verfügbar und kann durch Aufrufen abgerufen werden.SQLDescribeCol, SQLColAttribute oder SQLGetDescField.)
HY106 Abrufen des Bereichstyps DM) Der für das Argument FetchOrientation angegebene Wert war ungültig.

(DM) Das Argument FetchOrientation wurde SQL_FETCH_BOOKMARK, und das attribut der SQL_ATTR_USE_BOOKMARKS Anweisung wurde auf SQL_UB_OFF festgelegt.

Der Wert des attributs der SQL_ATTR_CURSOR_TYPE-Anweisung wurde SQL_CURSOR_FORWARD_ONLY, und der Wert des Arguments FetchOrientation wurde nicht SQL_FETCH_NEXT.

Der Wert des attributs SQL_ATTR_CURSOR_SCROLLABLE-Anweisung wurde SQL_NONSCROLLABLE, und der Wert des Arguments FetchOrientation wurde nicht SQL_FETCH_NEXT.
HY107 Zeilenwert außerhalb des Bereichs Der mit dem attribut der SQL_ATTR_CURSOR_TYPE-Anweisung angegebene Wert wurde SQL_CURSOR_KEYSET_DRIVEN, der mit dem attribut SQL_ATTR_KEYSET_SIZE-Anweisung angegebene Wert war jedoch größer als 0 und kleiner als der wert, der mit dem attribut SQL_ATTR_ROW_ARRAY_SIZE-Anweisung angegeben wurde.
HY111 Ungültiger Textmarkenwert Das Argument FetchOrientation wurde SQL_FETCH_BOOKMARK, und die Textmarke, auf die durch den Wert im attribut der SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisung verwiesen wurde, war ungültig oder war ein NULL-Zeiger.
HY117 Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function.
HYC00 Optionales Feature wurde nicht implementiert Der Treiber oder die Datenquelle unterstützt die durch die Kombination von TargetType in SQLBindCol und dem SQL-Datentyp der entsprechenden Spalte angegebene Konvertierung nicht.
HYT00 Timeout überschritten Der Abfragetimeoutzeitraum ist abgelaufen, bevor die Datenquelle das angeforderte Resultset zurückgegeben hat. Der Timeoutzeitraum wird über SQLSetStmtAttr SQL_ATTR_QUERY_TIMEOUT festgelegt.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt.
IM001 Dieser Treiber unterstützt diese Funktion nicht. (DM) Der dem StatementHandle zugeordnete Treiber unterstützt die Funktion nicht.
IM017 Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert. Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung deaktiviert.
IM018 SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen. Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachbearbeitung durchzuführen und den Vorgang abzuschließen.

Kommentare

SQLFetchScroll gibt ein angegebenes Rowset aus dem Resultset zurück. Rowsets können durch absolute oder relative Position oder durch Textmarke angegeben werden. SQLFetchScroll kann nur aufgerufen werden, wenn ein Resultset vorhanden ist , d. h. nach einem Aufruf, der ein Resultset erstellt, und bevor der Cursor über diesen Resultset geschlossen wird. Wenn Spalten gebunden sind, werden die Daten in diesen Spalten zurückgegeben. Wenn die Anwendung einen Zeiger auf ein Zeilenstatusarray oder einen Puffer angegeben hat, in dem die Anzahl der abgerufenen Zeilen zurückgegeben werden soll, gibt SQLFetchScroll diese Informationen ebenfalls zurück. Aufrufe an SQLFetchScroll können mit Aufrufen von SQLFetch gemischt werden, können aber nicht mit Aufrufen von SQLExtendedFetch gemischt werden.

Weitere Informationen finden Sie unter Verwenden von Blockcursorn und Verwenden von Bildlaufcursorn.

Positionieren des Cursors

Wenn das Resultset erstellt wird, wird der Cursor vor dem Start des Resultsets positioniert. SQLFetchScroll positioniert den Blockcursor basierend auf den Werten der Argumente FetchOrientation und FetchOffset , wie in der folgenden Tabelle dargestellt. Die genauen Regeln zum Bestimmen des Anfangs des neuen Rowsets werden im nächsten Abschnitt angezeigt.

FetchOrientation Bedeutung
SQL_FETCH_NEXT Gibt das nächste Rowset zurück. Dies entspricht dem Aufrufen von SQLFetch.

SQLFetchScroll ignoriert den Wert von FetchOffset.
SQL_FETCH_PRIOR Gibt das vorherige Rowset zurück.

SQLFetchScroll ignoriert den Wert von FetchOffset.
SQL_FETCH_RELATIVE Gibt das Rowset FetchOffset vom Anfang des aktuellen Rowsets zurück.
SQL_FETCH_ABSOLUTE Gibt das Rowset ab Zeile FetchOffset zurück.
SQL_FETCH_FIRST Gibt das erste Rowset im Resultset zurück.

SQLFetchScroll ignoriert den Wert von FetchOffset.
SQL_FETCH_LAST Gibt das letzte vollständige Rowset im Resultset zurück.

SQLFetchScroll ignoriert den Wert von FetchOffset.
SQL_FETCH_BOOKMARK Gibt die Rowset FetchOffset-Zeilen aus der Textmarke zurück, die durch das Attribut der SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisung angegeben wurde.

Treiber sind nicht erforderlich, um alle Abrufausrichtungen zu unterstützen; eine Anwendung ruft SQLGetInfo mit einem Informationstyp von SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 oder SQL_STATIC_CURSOR_ATTRIBUTES1 (abhängig vom Cursortyp) auf, um zu bestimmen, welche Abrufausrichtung vom Treiber unterstützt werden. Die Anwendung sollte sich die SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE und WQL_CA1_BOOKMARK Bitmasken in diesen Informationstypen ansehen. Wenn der Cursor vorwärts ist und FetchOrientation nicht SQL_FETCH_NEXT ist, gibt SQLFetchScroll SQLSTATE HY106 (Fetch-Typ außerhalb des Bereichs) zurück.

Das attribut SQL_ATTR_ROW_ARRAY_SIZE-Anweisung gibt die Anzahl der Zeilen im Rowset an. Wenn das von SQLFetchScroll abgerufene Rowset das Ende des Resultsets überlappt, gibt SQLFetchScroll ein partielles Rowset zurück. Wenn S + R - 1 größer als L ist, wobei S die Startzeile des abzurufenden Rowsets ist, ist R die Rowsetgröße und L die letzte Zeile im Resultset, dann sind nur die ersten L - S + 1 Zeilen des Rowsets gültig. Die verbleibenden Zeilen sind leer und weisen einen Status von SQL_ROW_NOROW auf.

Nachdem SQLFetchScroll zurückgegeben wurde, ist die aktuelle Zeile die erste Zeile des Rowsets.

Cursorpositionierungsregeln

In den folgenden Abschnitten werden die genauen Regeln für jeden Wert von FetchOrientation beschrieben. Diese Regeln verwenden die folgende Schreibweise.

Notation Bedeutung
Vor Beginn Der Blockcursor wird vor dem Start des Resultsets positioniert. Wenn die erste Zeile des neuen Rowsets vor dem Start des Resultsets liegt, gibt SQLFetchScroll SQL_NO_DATA zurück.
Nach Ende Der Blockcursor wird nach dem Ende des Resultsets positioniert. Wenn die erste Zeile des neuen Rowsets nach dem Ende des Resultsets liegt, gibt SQLFetchScroll SQL_NO_DATA zurück.
CurrRowsetStart Die Nummer der ersten Zeile im aktuellen Rowset.
LastResultRow Die Nummer der letzten Zeile im Resultset.
RowsetSize Die Rowsetgröße.
FetchOffset Der Wert des FetchOffset-Arguments .
BookmarkRow Die Zeile, die der textmarke entspricht, die durch das Attribut der SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisung angegeben wird.

SQL_FETCH_NEXT

Die folgenden Regeln gelten.

Bedingung Erste Zeile des neuen Rowsets
Vor Beginn 1
CurrRowsetStart + RowsetSize[1] <= LastResultRow CurrRowsetStart + RowsetSize[1]
CurrRowsetStart + RowsetSize[1]> LastResultRow Nach Ende
Nach Ende Nach Ende

[1] Wenn die Zeilensatzgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die Zeilensatzgröße, die mit dem vorherigen Aufruf verwendet wurde.

SQL_FETCH_PRIOR

Die folgenden Regeln gelten.

Bedingung Erste Zeile des neuen Rowsets
Vor Beginn Vor Beginn
CurrRowsetStart = 1 Vor Beginn
1 < CurrRowsetStart <= RowsetSize [2] 1 [1]
CurrRowsetStart > RowsetSize [2] CurrRowsetStart - RowsetSize [2]
After end AND LastResultRow RowsetSize < [2] 1 [1]
After end AND LastResultRow >= RowsetSize [2] LastResultRow - RowsetSize + 1 [2]

[1] SQLFetchScroll gibt SQLSTATE 01S06 (Versuch, abzurufen, bevor das Resultset das erste Rowset zurückgegeben hat) und SQL_SUCCESS_WITH_INFO zurück.

[2] Wenn die Zeilensatzgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die neue Rowsetgröße.

SQL_FETCH_RELATIVE

Die folgenden Regeln gelten.

Bedingung Erste Zeile des neuen Rowsets
(Before start AND FetchOffset > 0) OR (After end AND FetchOffset < 0) --[1]
BeforeStart AND FetchOffset <= 0 Vor Beginn
CurrRowsetStart = 1 AND FetchOffset < 0 Vor Beginn
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize [3] Vor Beginn
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize [3] 1 [2]
1 <= CurrRowsetStart + FetchOffset <= LastResultRow CurrRowsetStart + FetchOffset
CurrRowsetStart + FetchOffset > LastResultRow Nach Ende
Nach Ende UND FetchOffset >= 0 Nach Ende

[1] SQLFetchScroll gibt dasselbe Rowset zurück, als ob es mit FetchOrientation aufgerufen wurde, das auf SQL_FETCH_ABSOLUTE festgelegt wurde. Weitere Informationen finden Sie im Abschnitt "SQL_FETCH_ABSOLUTE".

[2] SQLFetchScroll gibt SQLSTATE 01S06 (Versuch, abzurufen, bevor das Resultset das erste Rowset zurückgegeben hat) und SQL_SUCCESS_WITH_INFO zurück.

[3] Wenn die Zeilensatzgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die neue Rowsetgröße.

SQL_FETCH_ABSOLUTE

Die folgenden Regeln gelten.

Bedingung Erste Zeile des neuen Rowsets
FetchOffset < 0 UND | FetchOffset | <= LastResultRow LastResultRow + FetchOffset + 1
FetchOffset < 0 UND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize [2] Vor Beginn
FetchOffset < 0 UND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize [2] 1 [1]
FetchOffset = 0 Vor Beginn
1 <= FetchOffset <= LastResultRow FetchOffset
FetchOffset > LastResultRow Nach Ende

[1] SQLFetchScroll gibt SQLSTATE 01S06 (Versuch, abzurufen, bevor das Resultset das erste Rowset zurückgegeben hat) und SQL_SUCCESS_WITH_INFO zurück.

[2] Wenn die Zeilensatzgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die neue Rowsetgröße.

Ein absoluter Abruf, der für einen dynamischen Cursor ausgeführt wird, kann das erforderliche Ergebnis nicht bereitstellen, da Zeilenpositionen in einem dynamischen Cursor nicht bestimmt sind. Ein solcher Vorgang entspricht einem Abruf, gefolgt von einem Abruf relativ; es ist keine atomische Operation, wie ein absoluter Abruf auf einem statischen Cursor.

SQL_FETCH_FIRST

Die folgenden Regeln gelten.

Bedingung Erste Zeile des neuen Rowsets
Beliebige 1

SQL_FETCH_LAST

Die folgenden Regeln gelten.

Bedingung Erste Zeile des neuen Rowsets
RowsetSize [1]<= LastResultRow LastResultRow - RowsetSize + 1 [1]
RowsetSize [1]> LastResultRow 1

[1] Wenn die Zeilensatzgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die neue Rowsetgröße.

SQL_FETCH_BOOKMARK

Die folgenden Regeln gelten.

Bedingung Erste Zeile des neuen Rowsets
BookmarkRow + FetchOffset < 1 Vor Beginn
1 <= BookmarkRow + FetchOffset <= LastResultRow BookmarkRow + FetchOffset
BookmarkRow + FetchOffset > LastResultRow Nach Ende

Informationen zu Textmarken finden Sie unter Bookmarks (ODBC).

Auswirkung von gelöschten, hinzugefügten und Fehlerzeilen auf Cursorbewegungen

Statische und keysetgesteuerte Cursor erkennen manchmal Zeilen, die dem Resultset hinzugefügt wurden, und entfernen Zeilen, die aus dem Resultset gelöscht wurden. Durch Aufrufen von SQLGetInfo mit den Optionen SQL_STATIC_CURSOR_ATTRIBUTES2 und SQL_KEYSET_CURSOR_ATTRIBUTES2 und betrachten Sie die SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS und SQL_CA2_SENSITIVITY_UPDATES Bitmasken, bestimmt eine Anwendung, ob die von einem bestimmten Treiber implementierten Cursor dies tun. Bei Treibern, die gelöschte Zeilen erkennen und entfernen können, beschreiben die folgenden Absätze die Auswirkungen dieses Verhaltens. Bei Treibern, die gelöschte Zeilen erkennen, aber nicht entfernen können, wirken sich Löschvorgänge nicht auf Cursorbewegungen aus, und die folgenden Absätze gelten nicht.

Wenn der Cursor Zeilen erkennt, die dem Resultset hinzugefügt wurden, oder entfernt Zeilen, die aus dem Resultset gelöscht wurden, wird es so angezeigt, als ob diese Änderungen nur erkannt werden, wenn daten abgerufen werden. Dies schließt den Fall ein, wenn SQLFetchScroll aufgerufen wird, wobei FetchOrientation auf SQL_FETCH_RELATIVE festgelegt ist und FetchOffset auf 0 festgelegt ist, um dasselbe Rowset zurückzustellen, schließt jedoch nicht den Fall ein, wenn SQLSetPos aufgerufen wird, wobei "fOption" auf SQL_REFRESH festgelegt ist. Im letzteren Fall werden die Daten in den Rowsetpuffern aktualisiert, jedoch nicht zurückgerufen, und gelöschte Zeilen werden nicht aus dem Resultset entfernt. Wenn also eine Zeile aus dem aktuellen Rowset gelöscht oder in das aktuelle Rowset eingefügt wird, ändert der Cursor die Rowsetpuffer nicht. Stattdessen erkennt sie die Änderung, wenn sie alle Rowset abruft, die zuvor die gelöschte Zeile enthalten oder jetzt die eingefügte Zeile enthält.

Zum Beispiel:

// Fetch the next rowset.  
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);  
// Delete third row of the rowset. Does not modify the rowset buffers.  
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);  
// The third row has a status of SQL_ROW_DELETED after this call.  
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);  
// Refetch the same rowset. The third row is removed, replaced by what  
// was previously the fourth row.  
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);

Wenn SQLFetchScroll ein neues Rowset zurückgibt, das eine Position relativ zum aktuellen Rowset hat , d. h. FetchOrientation ist SQL_FETCH_NEXT, SQL_FETCH_PRIOR oder SQL_FETCH_RELATIVE - enthält es keine Änderungen am aktuellen Rowset beim Berechnen der Anfangsposition des neuen Rowsets. Es enthält jedoch Änderungen außerhalb des aktuellen Rowsets, wenn es in der Lage ist, sie zu erkennen. Wenn SQLFetchScroll ein neues Rowset zurückgibt, das eine Position unabhängig vom aktuellen Rowset hat , d. h. FetchOrientation ist SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE oder SQL_FETCH_BOOKMARK - enthält es alle Änderungen, die er erkennen kann, auch wenn sie sich im aktuellen Rowset befinden.

Beim Bestimmen, ob sich neu hinzugefügte Zeilen innerhalb oder außerhalb des aktuellen Rowsets befinden, wird ein partielles Rowset als Enden an der letzten gültigen Zeile betrachtet. d. h. die letzte Zeile, für die der Zeilenstatus nicht SQL_ROW_NOROW ist. Angenommen, der Cursor kann neu hinzugefügte Zeilen erkennen, das aktuelle Rowset ist ein partielles Rowset, die Anwendung fügt neue Zeilen hinzu, und der Cursor fügt diese Zeilen am Ende des Resultsets hinzu. Wenn die Anwendung SQLFetchScroll mit FetchOrientation-Set auf SQL_FETCH_NEXT aufruft, gibt SQLFetchScroll das Rowset beginnend mit der ersten neu hinzugefügten Zeile zurück.

Angenommen, das aktuelle Rowset besteht aus Den Zeilen 21 bis 30, die Zeilengröße ist 10, der Cursor entfernt zeilen, die aus dem Resultset gelöscht wurden, und der Cursor erkennt Zeilen, die dem Resultset hinzugefügt wurden. Die folgende Tabelle zeigt die Zeilen SQLFetchScroll in verschiedenen Situationen zurück.

Change Fetch-Typ FetchOffset Neues Rowset[1]
Zeile 21 löschen NEXT 0 31 bis 40
Zeile 31 löschen NEXT 0 32 bis 41
Einfügen einer Zeile zwischen den Zeilen 21 und 22 NEXT 0 31 bis 40
Einfügen einer Zeile zwischen den Zeilen 30 und 31 NEXT 0 Eingefügte Zeile, 31 bis 39
Zeile 21 löschen PRIOR 0 11 bis 20
Zeile 20 löschen PRIOR 0 10 bis 19
Einfügen einer Zeile zwischen den Zeilen 21 und 22 PRIOR 0 11 bis 20
Einfügen einer Zeile zwischen den Zeilen 20 und 21 PRIOR 0 12 bis 20, eingefügte Zeile
Zeile 21 löschen RELATIVE 0 22 bis 31[2]
Zeile 21 löschen RELATIVE 1 22 bis 31
Einfügen einer Zeile zwischen den Zeilen 21 und 22 RELATIVE 0 21, eingefügte Zeile, 22 bis 29
Einfügen einer Zeile zwischen den Zeilen 21 und 22 RELATIVE 1 22 bis 31
Zeile 21 löschen ABSOLUTE 21 22 bis 31[2]
Zeile 22 löschen ABSOLUTE 21 21, 23 bis 31
Einfügen einer Zeile zwischen den Zeilen 21 und 22 ABSOLUTE 22 Eingefügte Zeile, 22 bis 29

[1] Diese Spalte verwendet die Zeilennummern, bevor Zeilen eingefügt oder gelöscht wurden.

[2] In diesem Fall versucht der Cursor, Zeilen ab Zeile 21 zurückzugeben. Da Zeile 21 gelöscht wurde, ist die zurückgegebene erste Zeile Zeile 22.

Fehlerzeilen (d. h. Zeilen mit einem Status von SQL_ROW_ERROR) wirken sich nicht auf die Cursorbewegung aus. Wenn beispielsweise das aktuelle Rowset mit Zeile 11 beginnt und der Status von Zeile 11 SQL_ROW_ERROR ist, wird sqlFetchScroll mit FetchOrientation auf SQL_FETCH_RELATIVE festgelegt, und FetchOffset auf 5 wird das Rowset beginnend mit Zeile 16 zurückgegeben, genau wie der Status für Zeile 11 wurde SQL_SUCCESS.

Zurückgeben von Daten in gebundenen Spalten

SQLFetchScroll gibt Daten in gebundenen Spalten auf die gleiche Weise wie SQLFetch zurück. Weitere Informationen finden Sie unter "Zurückgeben von Daten in gebundenen Spalten" in der SQLFetch-Funktion.

Wenn keine Spalten gebunden sind, gibt SQLFetchScroll keine Daten zurück, den Blockcursor jedoch an die angegebene Position. Ob Daten aus ungebundenen Spalten eines Blockcursors mit SQLGetData abgerufen werden können, hängt vom Treiber ab. Diese Funktion wird unterstützt, wenn ein Aufruf von SQLGetInfo das SQL_GD_BLOCK Bit für den SQL_GETDATA_EXTENSIONS Informationstyp zurückgibt.

Pufferadressen

SQLFetchScroll verwendet dieselbe Formel, um die Adresse von Daten und Längen-/Indikatorpuffern wie SQLFetch zu bestimmen. Weitere Informationen finden Sie unter "Pufferadressen" in der SQLBindCol-Funktion.

Zeilenstatusarray

SQLFetchScroll legt Werte im Zeilenstatusarray auf die gleiche Weise wie SQLFetch fest. Weitere Informationen finden Sie unter "Row Status Array" in SQLFetch Function.

Abgerufener Zeilenpuffer

SQLFetchScroll gibt die Anzahl der zeilen zurück, die in dem abgerufenen Zeilenpuffer auf die gleiche Weise wie SQLFetch abgerufen wurden. Weitere Informationen finden Sie unter "Rows Fetched Buffer" in SQLFetch Function.

Fehlerbehandlung

Wenn eine Anwendung SQLFetchScroll in einem ODBC 3.x-Treiber aufruft, ruft der Treiber-Manager SQLFetchScroll im Treiber auf. Wenn eine Anwendung SQLFetchScroll in einem ODBC 2.x-Treiber aufruft, ruft der Treiber-Manager SQLExtendedFetch im Treiber auf. Da SQLFetchScroll und SQLExtendedFetch Fehler auf etwas andere Weise behandeln, sieht die Anwendung beim Aufrufen von SQLFetchScroll in ODBC 2.x- und ODBC 3.x-Treibern etwas anderes Fehlerverhalten.

SQLFetchScroll gibt Fehler und Warnungen auf die gleiche Weise wie SQLFetch zurück. Weitere Informationen finden Sie unter "Fehlerbehandlung" in SQLFetch. SQLExtendedFetch gibt Fehler auf die gleiche Weise wie SQLFetch zurück, mit den folgenden Ausnahmen:

Wenn eine Warnung auftritt, die für eine bestimmte Zeile im Rowset gilt, legt SQLExtendedFetch den entsprechenden Eintrag im Zeilenstatusarray auf SQL_ROW_SUCCESS fest, nicht auf SQL_ROW_SUCCESS_WITH_INFO.

Wenn in jeder Zeile im Rowset Fehler auftreten, gibt SQLExtendedFetch SQL_SUCCESS_WITH_INFO zurück, nicht SQL_ERROR.

In jeder Gruppe von Statusdatensätzen, die für eine einzelne Zeile gelten, muss der erste von SQLExtendedFetch zurückgegebene Statusdatensatz SQLSTATE 01S01 (Fehler in Zeile) enthalten. SQLFetchScroll gibt diesen SQLSTATE-Wert nicht zurück. Wenn SQLExtendedFetch keine zusätzlichen SQLSTATEs zurückgeben kann, muss sie diesen SQLSTATE-Wert weiterhin zurückgeben.

SQLFetchScroll und optimistische Parallelität

Wenn ein Cursor optimistische Parallelität verwendet ( d. h. das attribut der SQL_ATTR_CONCURRENCY-Anweisung hat einen Wert von SQL_CONCUR_VALUES oder SQL_CONCUR_ROWVER - sqlFetchScroll aktualisiert die optimistischen Parallelitätswerte, die von der Datenquelle verwendet werden, um zu ermitteln, ob eine Zeile geändert wurde. Dies geschieht, wenn SQLFetchScroll ein neues Rowset abruft, einschließlich der Zurückweisung des aktuellen Rowsets. (Es wird aufgerufen, wobei FetchOrientation auf SQL_FETCH_RELATIVE und FetchOffset auf 0 festgelegt ist.)

SQLFetchScroll- und ODBC 2.x-Treiber

Wenn eine Anwendung SQLFetchScroll in einem ODBC 2.x-Treiber aufruft, ordnet der Treiber-Manager diesen Aufruf SQLExtendedFetch zu. Sie übergibt die folgenden Werte für die Argumente von SQLExtendedFetch.

SQLExtendedFetch-Argument Wert
StatementHandle StatementHandle in SQLFetchScroll.
FetchOrientation FetchOrientation in SQLFetchScroll.
FetchOffset Wenn FetchOrientation nicht SQL_FETCH_BOOKMARK ist, wird der Wert des FetchOffset-Arguments in SQLFetchScroll verwendet.

Wenn FetchOrientation SQL_FETCH_BOOKMARK ist, wird der wert, der an der adresse gespeichert ist, die durch das attribut SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisung angegeben wird.
RowCountPtr Die durch das attribut der SQL_ATTR_ROWS_FETCHED_PTR-Anweisung angegebene Adresse.
RowStatusArray Die durch das attribut der SQL_ATTR_ROW_STATUS_PTR-Anweisung angegebene Adresse.

Weitere Informationen finden Sie unter Blockcursor, scrollfähige Cursor und Abwärtskompatibilität in Anhang G: Treiberrichtlinien für Abwärtskompatibilität.

Deskriptoren und SQLFetchScroll

SQLFetchScroll interagiert auf die gleiche Weise mit Deskriptoren wie SQLFetch. Weitere Informationen finden Sie im Abschnitt "Descriptors and SQLFetchScroll" in SQLFetch Function.

Codebeispiel

Siehe Column-Wise Binding, Row-Wise Binding, Positioned Update and Delete Statements, and Updating Rows in the Rowset with SQLSetPos.

Weitere Informationen zu Siehe
Binden eines Puffers an eine Spalte in einem Resultset SQLBindCol-Funktion
Ausführen von Masseneinfügungs-, Aktualisierungs- oder Löschvorgängen SQLBulkOperations-Funktion
Abbrechen der Verarbeitung von Anweisungen SQLCancel-Funktion
Zurückgeben von Informationen zu einer Spalte in einem Resultset SQLDescribeCol-Funktion
Ausführen einer SQL-Anweisung SQLExecDirect-Funktion
Ausführen einer vorbereiteten SQL-Anweisung SQLExecute-Funktion
Abrufen einer einzelnen Zeile oder eines Datenblocks in eine vorwärtsgerichtete Richtung SQLFetch-Funktion
Schließen des Cursors auf der Anweisung SQLFreeStmt-Funktion
Zurückgeben der Anzahl von Resultsetspalten SQLNumResultCols-Funktion
Positionieren des Cursors, Aktualisieren von Daten im Rowset oder Aktualisieren oder Löschen von Daten im Resultset SQLSetPos-Funktion
Festlegen eines Anweisungsattributs SQLSetStmtAttr-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien