SQLFetchScroll-Funktion
Konformität
Version eingeführt: ODBC 3.0-Normenkonformität: ISO 92
Zusammenfassung
SQLFetchScroll ruft das angegebene Rowset der 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 Lesezeichen angegeben werden.
Wenn Sie mit einem ODBC 2.x-Treiber arbeiten, ordnet der Treiber-Manager diese Funktion SQLExtendedFetch zu. Weitere Informationen finden Sie unter Zuordnen von Ersatzfunktionen für die Abwärtskompatibilität von Anwendungen.
Syntax
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
Argumente
StatementHandle
[Eingabe] Anweisungshandle.
FetchOrientation
[Eingabe]
Art 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]
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.
Diagnose
Wenn SQLFetchScroll entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLFetchScroll zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben. Wenn ein Fehler für eine einzelne Spalte auftritt, kann SQLGetDiagField mit einem DiagIdentifier von SQL_DIAG_COLUMN_NUMBER aufgerufen werden, um die Spalte zu bestimmen, in der der Fehler aufgetreten ist. und 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 zurückgeben können (außer 01xxx SQLSTATEs), wird SQL_SUCCESS_WITH_INFO zurückgegeben, wenn ein Fehler für eine oder mehrere Zeilen eines Mehrzeilenvorgangs auftritt, und SQL_ERROR zurückgegeben wird, wenn ein Fehler bei einem Einzeilenvorgang auftritt.
| SQLSTATE | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01004 | Zeichenfolgendaten, rechts abgeschnitten | Zeichenfolgen- oder Binärdaten, die für eine Spalte zurückgegeben wurden, führten zum Abschneiden von Nichtblankzeichen- oder Nicht-NULL-Binärdaten. Wenn es sich um einen Zeichenfolgenwert handelte, wurde er rechts abgeschnitten. |
| 01S01 | Fehler in Zeile | Beim Abrufen einer oder mehrerer Zeilen ist ein Fehler aufgetreten. (Wenn dieser SQLSTATE zurückgegeben wird, wenn eine ODBC 3*.x*-Anwendung mit einem ODBC 2*.x*-Treiber arbeitet, kann sie ignoriert werden.) |
| 01S06 | Versuchen sie zu abrufen, bevor das Resultset das erste Rowset zurückgegeben hat. | Das angeforderte Rowset überlappt den Anfang des Resultsets, wenn FetchOrientation SQL_FETCH_PRIOR wurde, die aktuelle Position außerhalb der ersten Zeile lag und die Anzahl der aktuellen Zeile kleiner oder gleich der Rowsetgröße ist. Das angeforderte Rowset überlappt den Anfang des Resultsets, wenn FetchOrientation SQL_FETCH_PRIOR wurde, die aktuelle Position über das Ende des Resultsets hinaus lag und die Rowsetgröße größer als die Resultsetgröße war. Das angeforderte Rowset überlappt den Start des Resultsets, als FetchOrientation SQL_FETCH_RELATIVE, FetchOffset negativ war und der absolute Wert von FetchOffset kleiner oder gleich der Rowsetgröße war. Das angeforderte Rowset überlappt den Start des Resultsets, wenn FetchOrientation SQL_FETCH_ABSOLUTE, FetchOffset negativ war und der absolute Wert von FetchOffset größer als die Resultsetgröße, aber kleiner oder gleich der Rowsetgröße war. (Die 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. Bei Zeit-, Zeitstempel- und Intervalldatentypen, die eine Zeitkomponente enthielten, wurde der Bruchteil der Zeit abgeschnitten. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 07006 | Verletzung eines eingeschränkten Datentypattributes | Der Datenwert einer Spalte im Resultset konnte nicht in den von TargetType in SQLBindCol angegebenen Datentyp konvertiert werden. Spalte 0 war an einen Datentyp von SQL_C_BOOKMARK gebunden, und das Attribut SQL_ATTR_USE_BOOKMARKS-Anweisung wurde auf SQL_UB_VARIABLE festgelegt. Spalte 0 war 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 war gebunden, und das Attribut 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 war, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde. |
| 22001 | Zeichenfolgendaten, rechts abgeschnitten | Ein Für eine Spalte zurückgegebenes Lesezeichen mit variabler Länge wurde abgeschnitten. |
| 22002 | Indikatorvariable erforderlich, aber nicht angegeben | NULL-Daten wurden in eine Spalte abgerufen, deren StrLen_or_IndPtr durch SQLBindCol (oder SQL_DESC_INDICATOR_PTR festgelegt durch SQLSetDescField oder SQLSetDescRec) ein NULL-Zeiger war. |
| 22003 | Numerischer Wert außerhalb des Bereichs | Das Zurückgeben des numerischen Werts (als numerisch oder Zeichenfolge) für eine oder mehrere gebundene Spalten hätte dazu geführt, dass der gesamte Teil der Zahl (im Gegensatz zur Bruchzahl) abgeschnitten wurde. 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 war an eine Datums-, Uhrzeit- oder Zeitstempel-C-Struktur gebunden, und ein Wert in der Spalte war jeweils ein ungültiges Datum, eine ungültige Uhrzeit oder ein ungültiger Zeitstempel. |
| 22012 | Division by Zero | Ein Wert aus einem arithmetischen Ausdruck wurde zurückgegeben, was zu einer Division durch 0 führte. |
| 22015 | Intervallfeldüberlauf | Das Zuweisen eines genauen numerischen oder Intervall-SQL-Typs zu einem Intervall-C-Typ führte zu einem Verlust signifikanter Ziffern im führenden Feld. Beim Abrufen von Daten in einen Intervall-C-Typ gab es keine Darstellung des Werts des SQL-Typs im Intervalltyp C. |
| 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 im Zeichensatz des Puffers keine Darstellung vorhanden war. Der C-Typ war ein genauer oder ungefährer numerischer Datentyp, ein datetime- oder ein Intervalldatentyp. 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 StatementHandle-Instanz befand sich in einem ausgeführten Zustand, aber es wurde kein Resultset dem StatementHandle zugeordnet. |
| 40001 | Serialisierungsfehler | Die Transaktion, in der der Abruf ausgeführt wurde, wurde beendet, um einen Deadlock zu verhindern. |
| 40003 | Anweisungsabschluss unbekannt | Die zugeordnete Verbindung ist während der Ausführung dieser Funktion fehlgeschlagen, 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 seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist. |
| HY008 | Vorgang abgebrochen | Die asynchrone Verarbeitung wurde für statementHandle aktiviert. Die Funktion wurde aufgerufen, und vor Abschluss der Ausführung wurde SQLCancel oder SQLCancelHandle für statementHandle aufgerufen. Anschließend wurde die Funktion für die AnweisungHandle erneut aufgerufen. Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle für die StatementHandle aus einem anderen Thread in einer Multithreadanwendung aufgerufen. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die FUNKTION SQLFetchScroll 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) Der angegebene StatementHandle befand sich nicht im Ausführungszustand. 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 der Ausführungsparameter 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 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | Das SQL_ATTR_USE_BOOKMARK-Anweisungsattribut wurde auf SQL_UB_VARIABLE festgelegt, und Spalte 0 wurde an einen Puffer gebunden, dessen Länge nicht der maximalen Länge für das Lesezeichen für dieses Resultset entsprach. (Diese Länge ist im Feld SQL_DESC_OCTET_LENGTH der IRD verfügbar und kann durch Aufrufen von SQLDescribeCol, SQLColAttribute oder SQLGetDescField abgerufen werden.) |
| HY106 | Abrufen des Typs außerhalb des Bereichs | 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 SQL_ATTR_CURSOR_TYPE-Anweisungsattributs wurde SQL_CURSOR_FORWARD_ONLY, und der Wert des Arguments FetchOrientation wurde nicht SQL_FETCH_NEXT. Der Wert des SQL_ATTR_CURSOR_SCROLLABLE-Anweisungsattributs wurde SQL_NONSCROLLABLE, und der Wert des Arguments FetchOrientation wurde nicht SQL_FETCH_NEXT. |
| HY107 | Zeilenwert außerhalb des Bereichs | Der mit dem SQL_ATTR_CURSOR_TYPE-Anweisungsattribut angegebene Wert wurde SQL_CURSOR_KEYSET_DRIVEN, aber der mit dem SQL_ATTR_KEYSET_SIZE-Anweisungsattribut angegebene Wert war größer als 0 und kleiner als der mit dem SQL_ATTR_ROW_ARRAY_SIZE-Anweisungsattribut angegebene Wert. |
| HY111 | Ungültiger Lesezeichenwert | Das Argument FetchOrientation wurde SQL_FETCH_BOOKMARK, und das Lesezeichen, auf das der Wert im SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisungsattribut verweist, war ungültig oder ein NULL-Zeiger. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYC00 | Optionales Feature nicht implementiert | Der Treiber oder die Datenquelle unterstützt nicht die Konvertierung, die durch die Kombination von TargetType in SQLBindCol und dem SQL-Datentyp der entsprechenden Spalte angegeben wird. |
| HYT00 | Timeout abgelaufen | Der Abfragetimeoutzeitraum ist abgelaufen, bevor die Datenquelle das angeforderte Resultset zurückgegeben hat. Der Timeoutzeitraum wird über SQLSetStmtAttr festgelegt, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Treiber unterstützt diese Funktion nicht. | (DM) Der Der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM017 | Abruf ist im asynchronen Benachrichtigungsmodus deaktiviert. | Wenn das Benachrichtigungsmodell verwendet wird, wird die Abfrage 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 Nachverarbeitung 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 Lesezeichen angegeben werden. SQLFetchScroll kann nur aufgerufen werden, solange ein Resultset vorhanden ist, d. h. nach einem Aufruf, der ein Resultset erstellt, und bevor der Cursor über diesem 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 auch diese Informationen zurück. Aufrufe von SQLFetchScroll können mit Aufrufen von SQLFetch gemischt, aber nicht mit Aufrufen von SQLExtendedFetch gemischt werden.
Weitere Informationen finden Sie unter Verwenden von Blockcursors und Verwenden von scrollbaren Cursorn.
Positionieren des Cursors
Wenn das Resultset erstellt wird, wird der Cursor vor dem Anfang des Resultsets positioniert. SQLFetchScroll positioniert den Blockcursor basierend auf den Werten der Argumente FetchOrientation und FetchOffset , wie in der folgenden Tabelle gezeigt. Die genauen Regeln zum Bestimmen des Anfangs des neuen Rowsets werden im nächsten Abschnitt gezeigt.
| 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-Zeilen FetchOffset aus dem Lesezeichen zurück, das durch das SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisungsattribut angegeben ist. |
Treiber sind nicht erforderlich, um alle Abrufausrichtungen zu unterstützen. eine Anwendung ruft SQLGetInfo mit dem Informationstyp SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 oder SQL_STATIC_CURSOR_ATTRIBUTES1 (abhängig vom Typ des Cursors) auf, um zu bestimmen, welche Abrufausrichtungen vom Treiber unterstützt werden. Die Anwendung sollte sich die bitmasken SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE und WQL_CA1_BOOKMARK in diesen Informationstypen ansehen. Wenn der Cursor nur vorwärts ist und FetchOrientation nicht SQL_FETCH_NEXT ist, gibt SQLFetchScroll SQLSTATE HY106 (Fetch-Typ außerhalb des Bereichs) zurück.
Das SQL_ATTR_ROW_ARRAY_SIZE-Anweisungsattribut gibt die Anzahl der Zeilen im Rowset an. Wenn das von SQLFetchScroll abgerufene Rowset das Ende des Resultsets überschneidet, gibt SQLFetchScroll ein partielles Rowset zurück. Das heißt, wenn S + R - 1 größer als L ist, wobei S die Anfangszeile des abgerufenen Rowsets, R die Rowsetgröße und L die letzte Zeile im Resultset ist, sind nur die ersten L - S + 1 Zeilen des Rowsets gültig. Die restlichen Zeilen sind leer und haben den Status SQL_ROW_NOROW.
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 Notation.
| Notation | Bedeutung |
|---|---|
| Vor dem Start | Der Blockcursor wird vor dem Start des Resultsets positioniert. Wenn sich die erste Zeile des neuen Rowsets vor dem Start des Resultsets befindet, gibt SQLFetchScroll SQL_NO_DATA zurück. |
| Nach Dem 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 dem Lesezeichen entspricht, das durch das Attribut SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisung angegeben wird. |
SQL_FETCH_NEXT
Es gelten die folgenden Regeln.
| Bedingung | Erste Zeile des neuen Rowsets |
|---|---|
| Vor dem Start | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | Nach Dem Ende |
| Nach Dem Ende | Nach Dem Ende |
[1] Wenn die Rowsetgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die Rowsetgröße, die beim vorherigen Aufruf verwendet wurde.
SQL_FETCH_PRIOR
Es gelten die folgenden Regeln.
| Bedingung | Erste Zeile des neuen Rowsets |
|---|---|
| Vor dem Start | Vor dem Start |
| CurrRowsetStart = 1 | Vor dem Start |
| 1 < CurrRowsetStart <= RowsetSize[2] | 1[1] |
| CurrRowsetStart > RowsetSize[2] | CurrRowsetStart – RowsetSize[2] |
| Nach Ende UND LastResultRow < RowsetSize[2] | 1[1] |
| After end AND LastResultRow >= RowsetSize[2] | LastResultRow – RowsetSize + 1[2] |
[1] SQLFetchScroll gibt SQLSTATE 01S06 (Versucht zu abrufen, bevor das Resultset das erste Rowset zurückgegeben hat) und SQL_SUCCESS_WITH_INFO zurück.
[2] Wenn die Rowsetgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die neue Rowsetgröße.
SQL_FETCH_RELATIVE
Es gelten die folgenden Regeln.
| Bedingung | Erste Zeile des neuen Rowsets |
|---|---|
| (Vor Start UND FetchOffset > 0) ODER (Nach Ende UND FetchOffset < 0) | --[1] |
| BeforeStart AND FetchOffset <= 0 | Vor dem Start |
| CurrRowsetStart = 1 UND FetchOffset < 0 | Vor dem Start |
| CurrRowsetStart > 1 UND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize[3] | Vor dem Start |
| CurrRowsetStart > 1 UND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize[3] | 1[2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | Nach Dem Ende |
| Nach Ende UND FetchOffset >= 0 | Nach Dem Ende |
[1] SQLFetchScroll gibt dasselbe Rowset zurück, als wäre es aufgerufen, wenn FetchOrientation auf SQL_FETCH_ABSOLUTE festgelegt wurde. Weitere Informationen finden Sie im Abschnitt "SQL_FETCH_ABSOLUTE".
[2] SQLFetchScroll gibt SQLSTATE 01S06 (Versucht, abzurufen, bevor das Resultset das erste Rowset zurückgegeben hat) und SQL_SUCCESS_WITH_INFO zurück.
[3] Wenn die Rowsetgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die neue Rowsetgröße.
SQL_FETCH_ABSOLUTE
Es gelten die folgenden Regeln.
| Bedingung | Erste Zeile des neuen Rowsets |
|---|---|
| FetchOffset < 0 AND | FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize[2] | Vor dem Start |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize[2] | 1[1] |
| FetchOffset = 0 | Vor dem Start |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | Nach Dem Ende |
[1] SQLFetchScroll gibt SQLSTATE 01S06 (Versucht, abzurufen, bevor das Resultset das erste Rowset zurückgegeben hat) und SQL_SUCCESS_WITH_INFO zurück.
[2] Wenn die Rowsetgröß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 liefern, da Zeilenpositionen in einem dynamischen Cursor unbestimmt sind. Ein solcher Vorgang entspricht einem Fetch zuerst, gefolgt von einem Fetch-Relativen. es handelt sich nicht um eine atomische Operation, da es sich um einen absoluten Abruf auf einem statischen Cursor handelt.
SQL_FETCH_FIRST
Es gelten die folgenden Regeln.
| Bedingung | Erste Zeile des neuen Rowsets |
|---|---|
| Alle | 1 |
SQL_FETCH_LAST
Es gelten die folgenden Regeln.
| Bedingung | Erste Zeile des neuen Rowsets |
|---|---|
| RowsetSize[1]<= LastResultRow | LastResultRow – RowsetSize + 1[1] |
| RowsetSize[1]> LastResultRow | 1 |
[1] Wenn die Rowsetgröße seit dem vorherigen Aufruf zum Abrufen von Zeilen geändert wurde, ist dies die neue Rowsetgröße.
SQL_FETCH_BOOKMARK
Es gelten die folgenden Regeln.
| Bedingung | Erste Zeile des neuen Rowsets |
|---|---|
| BookmarkRow + FetchOffset < 1 | Vor dem Start |
| 1 <= BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | Nach Dem Ende |
Informationen zu Lesezeichen finden Sie unter Lesezeichen (ODBC).
Auswirkung von gelöschten, hinzugefügten und Fehlerzeilen auf die Cursorbewegung
Statische Cursor und Keyset-gesteuerte 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 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. Für Treiber, die gelöschte Zeilen erkennen und entfernen können, beschreiben die folgenden Absätze die Auswirkungen dieses Verhaltens. Für Treiber, die gelöschte Zeilen erkennen, aber nicht entfernen können, haben Löschungen keine Auswirkungen auf Cursorbewegungen, und die folgenden Absätze gelten nicht.
Wenn der Cursor Zeilen erkennt, die dem Resultset hinzugefügt wurden, oder die aus dem Resultset gelöschten Zeilen entfernt, scheint es, als ob er diese Änderungen nur erkennt, wenn er Daten abruft. Dies schließt den Fall ein, wenn SQLFetchScroll aufgerufen wird, wobei FetchOrientation auf SQL_FETCH_RELATIVE und FetchOffset auf 0 festgelegt ist, um das gleiche Rowset zu refetchen, aber nicht den Fall, wenn SQLSetPos aufgerufen wird, wobei fOption auf SQL_REFRESH festgelegt ist. Im letzteren Fall werden die Daten in den Rowsetpuffern aktualisiert, aber nicht refetched, 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 wird die Änderung erkannt, wenn ein Rowset abgerufen wird, das zuvor die gelöschte Zeile enthält oder jetzt die eingefügte Zeile enthält.
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 ), werden beim Berechnen der Startposition des neuen Rowsets keine Änderungen am aktuellen Rowset eingeschlossen. Es enthält jedoch Änderungen außerhalb des aktuellen Rowsets, wenn sie erkannt werden können. Wenn SQLFetchScroll außerdem ein neues Rowset zurückgibt, das unabhängig vom aktuellen Rowset eine Position hat – d. h. FetchOrientation ist SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE oder SQL_FETCH_BOOKMARK – enthält es alle Änderungen, die es erkennen kann, auch wenn sie sich im aktuellen Rowset befinden.
Bei der Bestimmung, ob sich neu hinzugefügte Zeilen innerhalb oder außerhalb des aktuellen Rowsets befinden, wird davon ausgegangen, dass ein Teilrowset bei der letzten gültigen Zeile endet. 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 Teilrowset, die Anwendung fügt neue Zeilen hinzu, und der Cursor fügt diese Zeilen am Ende des Resultsets hinzu. Wenn die Anwendung SQLFetchScroll aufruft, wobei FetchOrientation auf SQL_FETCH_NEXT festgelegt ist, gibt SQLFetchScroll das Rowset ab der ersten neu hinzugefügten Zeile zurück.
Angenommen, das aktuelle Rowset umfasst die Zeilen 21 bis 30, die Rowsetgröße beträgt 10, der Cursor entfernt die aus dem Resultset gelöschten Zeilen, und der Cursor erkennt Zeilen, die dem Resultset hinzugefügt wurden. Die folgende Tabelle zeigt die Zeilen, die SQLFetchScroll in verschiedenen Situationen zurückgibt.
| 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 |
| Zeile zwischen Zeilen 21 und 22 einfügen | NEXT | 0 | 31 bis 40 |
| Zeile zwischen Zeilen 30 und 31 einfügen | 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 |
| Zeile zwischen Zeilen 21 und 22 einfügen | PRIOR | 0 | 11 bis 20 |
| Zeile zwischen Zeilen 20 und 21 einfügen | PRIOR | 0 | 12 bis 20, Zeile eingefügt |
| Zeile 21 löschen | RELATIVE | 0 | 22 bis 31[2] |
| Zeile 21 löschen | RELATIVE | 1 | 22 bis 31 |
| Zeilen zwischen Zeilen 21 und 22 einfügen | RELATIVE | 0 | 21, Zeile eingefügt, 22 bis 29 |
| Zeilen zwischen Zeilen 21 und 22 einfügen | 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 |
| Zeilen zwischen Zeilen 21 und 22 einfügen | ABSOLUTE | 22 | Zeile eingefügt, 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 erste Zeile, die sie zurückgibt, Zeile 22.
Fehlerzeilen (d. h. Zeilen mit dem Status SQL_ROW_ERROR) wirken sich nicht auf die Cursorbewegung aus. Wenn das aktuelle Rowset beispielsweise mit Zeile 11 beginnt und der Status von Zeile 11 SQL_ROW_ERROR ist, gibt der Aufruf von SQLFetchScroll mit FetchOrientation auf SQL_FETCH_RELATIVE und FetchOffset auf 5 das Rowset ab Zeile 16 zurück, genau wie bei SQL_SUCCESS der Status für Zeile 11.
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, aber der Blockcursor wird an die angegebene Position verschoben. 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 "Zeilenstatusarray" in der SQLFetch-Funktion.
Abgerufener Zeilenpuffer
SQLFetchScroll gibt die Anzahl der Zeilen zurück, die im abgerufenen Zeilenpuffer abgerufen wurden, auf die gleiche Weise wie SQLFetch. Weitere Informationen finden Sie unter "Zeilen abgerufener Puffer" in der SQLFetch-Funktion.
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 etwas anders behandeln, sieht die Anwendung ein etwas anderes Fehlerverhalten, wenn sqlFetchScroll in ODBC 2.x- und ODBC 3.x-Treibern aufgerufen wird.
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 und nicht auf SQL_ROW_SUCCESS_WITH_INFO fest.
Wenn in jeder Zeile im Rowset Fehler auftreten, gibt SQLExtendedFetch SQL_SUCCESS_WITH_INFO und nicht SQL_ERROR zurück.
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 diese SQLSTATE trotzdem zurückgegeben werden.
SQLFetchScroll und Optimistische Parallelität
Wenn ein Cursor eine optimistische Parallelität verwendet , d. h. das Attribut der SQL_ATTR_CONCURRENCY-Anweisung hat den Wert SQL_CONCUR_VALUES oder SQL_CONCUR_ROWVER, aktualisiert SQLFetchScroll die optimistischen Parallelitätswerte, die von der Datenquelle verwendet werden, um zu erkennen, ob sich eine Zeile geändert hat. Dies geschieht immer dann, wenn SQLFetchScroll ein neues Rowset abruft, einschließlich des Refetches 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. Es ü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 verwendet, der an der adresse gespeichert wird, die durch das SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisungsattribut angegeben wird. |
| RowCountPtr | Die Adresse, die durch das Attribut SQL_ATTR_ROWS_FETCHED_PTR-Anweisung angegeben wird. |
| RowStatusArray | Die Adresse, die durch das Attribut SQL_ATTR_ROW_STATUS_PTR-Anweisung angegeben wird. |
Weitere Informationen finden Sie unter BlockCurs, Scrollable Cursors und Abwärtskompatibilität in Anhang G: Treiberrichtlinien für Abwärtskompatibilität.
Deskriptoren und SQLFetchScroll
SQLFetchScroll interagiert mit Deskriptoren auf die gleiche Weise wie SQLFetch. Weitere Informationen finden Sie im Abschnitt "Deskriptoren und SQLFetchScroll" in der SQLFetch-Funktion.
Codebeispiel
Weitere Informationen finden Sie unter Column-Wise Binding, Row-Wise Binding, Positioned Update and Delete-Anweisungen und Aktualisieren von Zeilen im Rowset mit SQLSetPos.
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| 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 Anweisungsverarbeitung | 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 einer vorwärtsgerichteten Richtung | SQLFetch-Funktion |
| Schließen des Cursors für die -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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für