SQLFetchScroll-Funktion
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.
Verwandte Funktionen
| 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 |