SQLFetchScroll (Cursorbibliothek)

Wichtig

Dieses Feature wird in einer zukünftigen Version von Windows entfernt. Vermeiden Sie die Verwendung dieses Features in neuen Entwicklungsvorgängen, und planen Sie das Ändern von Anwendungen, die dieses Feature derzeit verwenden. Microsoft empfiehlt die Verwendung der Cursorfunktion des Treibers.

In diesem Thema wird die Verwendung der FUNKTION SQLFetchScroll in der Cursorbibliothek erläutert. Allgemeine Informationen zu SQLFetchScroll finden Sie unter SQLFetchScroll-Funktion.

Die Cursorbibliothek implementiert SQLFetchScroll durch wiederholtes Aufrufen von SQLFetch im Treiber. Die abgerufenen Daten vom Treiber werden an die von der Anwendung bereitgestellten Rowsetpuffer übertragen. Außerdem werden die Daten im Arbeitsspeicher und in Datenträgerdateien zwischengespeichert. Wenn eine Anwendung ein neues Rowset anfordert, ruft die Cursorbibliothek es nach Bedarf aus dem Treiber (sofern es zuvor nicht abgerufen wurde) oder aus dem Cache (sofern es zuvor abgerufen wurde) ab. Schließlich verwaltet die Cursorbibliothek den Status der zwischengespeicherten Daten und gibt diese Informationen an die Anwendung im Zeilenstatusarray zurück.

Wenn die Cursorbibliothek verwendet wird, können Aufrufe von SQLFetchScroll nicht mit Aufrufen von SQLFetch oder SQLExtendedFetch gemischt werden.

Wenn die Cursorbibliothek verwendet wird, werden Aufrufe von SQLFetchScroll für ODBC 2 unterstützt. x und für ODBC 3. x-Treiber .

Rowsetpuffer

Die Cursorbibliothek optimiert die Übertragung von Daten vom Treiber in den von der Anwendung bereitgestellten Rowsetpuffer, wenn:

• Die Anwendung verwendet zeilenweise Bindung.

• Es gibt keine nicht verwendeten Bytes zwischen Feldern in der Struktur, die die Anwendung deklariert, um eine Datenzeile zu enthalten.

• Die Felder, in denen SQLFetch oder SQLFetchScroll die Länge/den Indikator für eine Spalte zurückgibt, folgen dem Puffer für diese Spalte und gehen dem Puffer für die nächste Spalte voran. Diese Felder sind optional.

Wenn die Anwendung ein neues Rowset anfordert, ruft die Cursorbibliothek bei Bedarf Daten aus dem Cache und aus dem Treiber ab. Wenn sich die neuen und alten Rowsets überschneiden, kann die Cursorbibliothek ihre Leistung optimieren, indem sie die Daten aus den überlappenden Abschnitten der Rowsetpuffer wiederverwendet. Daher gehen nicht gespeicherte Änderungen an den Rowsetpuffern verloren, es sei denn, die neuen und alten Rowsets überlappen sich und die Änderungen befinden sich in den überlappenden Abschnitten der Rowsetpuffer. Um die Änderungen zu speichern, übermittelt eine Anwendung eine positionierte Update-Anweisung.

Beachten Sie, dass die Cursorbibliothek die Rowsetpuffer immer mit Daten aus dem Cache aktualisiert, wenn eine Anwendung SQLFetchScroll aufruft, wobei das FetchOrientation-Argument auf SQL_FETCH_RELATIVE und das FetchOffset-Argument auf 0 festgelegt ist.

Die Cursorbibliothek unterstützt das Aufrufen von SQLSetStmtAttr mit einem Attribut von SQL_ATTR_ROW_ARRAY_SIZE, um die Rowsetgröße zu ändern, während ein Cursor geöffnet ist. Die neue Rowsetgröße wird beim nächsten Aufruf von SQLFetchScroll wirksam.

Mitgliedschaft im Resultset

Die Cursorbibliothek ruft Daten nur dann vom Treiber ab, wenn die Anwendung dies anfordert. Abhängig von der Datenquelle und der Einstellung des SQL_CONCURRENCY-Anweisungsattributs hat dies die folgenden Folgen:

• Die von der Cursorbibliothek abgerufenen Daten unterscheiden sich möglicherweise von den Daten, die zum Zeitpunkt der Ausführung der Anweisung verfügbar waren. Nach dem Öffnen des Cursors können beispielsweise Zeilen, die an einem Punkt außerhalb der aktuellen Cursorposition eingefügt wurden, von einigen Treibern abgerufen werden.

• Die Daten im Resultset werden möglicherweise von der Datenquelle für die Cursorbibliothek gesperrt und sind daher für andere Benutzer nicht verfügbar.

Nachdem die Cursorbibliothek eine Datenzeile zwischengespeichert hat, kann sie keine Änderungen an dieser Zeile in der zugrunde liegenden Datenquelle erkennen (mit Ausnahme von positionierten Updates und Löschungen, die im Cache desselben Cursors ausgeführt werden). Dies liegt daran, dass die Cursorbibliothek für Aufrufe von SQLFetchScroll niemals Daten aus der Datenquelle zurückgibt. Stattdessen werden Daten aus dem Cache zurückgegeben.

Scrollen

Die Cursorbibliothek unterstützt die folgenden Abruftypen in SQLFetchScroll.

Cursortyp	Abrufen von Typen
Vorwärtscursor	SQL_FETCH_NEXT
statischen	SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_RELATIVE SQL_FETCH_ABSOLUTE SQL_FETCH_BOOKMARK

Errors

Wenn SQLFetchScroll aufgerufen wird und einer der Aufrufe von SQLFetch SQL_ERROR zurückgibt, wird die Cursorbibliothek wie folgt fortgesetzt. Nachdem diese Schritte ausgeführt wurden, setzt die Cursorbibliothek die Verarbeitung fort.

1. Ruft SQLGetDiagRec auf, um Fehlerinformationen vom Treiber abzurufen, und stellt diese als Diagnosedatensatz im Treiber-Manager bereit.

2. Legt das feld SQL_DIAG_ROW_NUMBER im Diagnosedatensatz auf den entsprechenden Wert fest.

3. Legt das feld SQL_DIAG_COLUMN_NUMBER im Diagnosedatensatz ggf. auf den entsprechenden Wert fest; Andernfalls wird der Wert auf 0 festgelegt.

4. Legt den Wert für die Zeile in error im Zeilenstatusarray auf SQL_ROW_ERROR fest.

Nachdem die Cursorbibliothek SQLFetch in ihrer Implementierung von SQLFetchScroll mehrmals aufgerufen hat, befinden sich alle von einem der SQLFetch-Aufrufe zurückgegebenen Fehler oder Warnungen in einem Diagnosedatensatz und können durch einen Aufruf von SQLGetDiagRec abgerufen werden. Wenn die Daten beim Abrufen abgeschnitten wurden, befinden sich die abgeschnittenen Daten nun im Cache der Cursorbibliothek. Nachfolgende Aufrufe von SQLFetchScroll zum Scrollen zu einer Zeile mit abgeschnittenen Daten geben die abgeschnittenen Daten zurück, und es wird keine Warnung ausgelöst, da die Daten aus dem Cache der Cursorbibliothek abgerufen werden. Um die Länge der zurückgegebenen Daten nachzuverfolgen, damit ermittelt werden kann, ob die in einem Puffer zurückgegebenen Daten abgeschnitten wurden, sollte eine Anwendung den Längen-/Indikatorpuffer binden.

Lesezeichenvorgänge

Die Cursorbibliothek unterstützt das Aufrufen von SQLFetchScroll mit einer FetchOrientation von SQL_FETCH_BOOKMARK. Außerdem wird das Angeben eines Offsets im FetchOffset-Argument unterstützt, das im Lesezeichenvorgang verwendet werden kann. Dies ist der einzige Lesezeichenvorgang, den die Cursorbibliothek unterstützt. Das Aufrufen von SQLBulkOperations wird von der Cursorbibliothek nicht unterstützt.

Wenn die Anwendung das SQL_ATTR_USE_BOOKMARKS-Anweisungsattribut festgelegt und an die Lesezeichenspalte gebunden ist, generiert die Cursorbibliothek ein Lesezeichen mit fester Länge und gibt es an die Anwendung zurück. Die Cursorbibliothek erstellt und verwaltet die lesezeichen, die sie verwendet. Es werden keine Lesezeichen verwendet, die in der Datenquelle verwaltet werden. Wenn SQLFetchScroll aufgerufen wird, um einen Datenblock abzurufen, der bereits aus der Datenquelle abgerufen wurde, werden die Daten aus dem Cursorbibliothekscache abgerufen. Daher muss das Lesezeichen, das in einem Aufruf von SQLFetchScroll mit einer FetchOrientation von SQL_FETCH_BOOKMARK verwendet wird, von der Cursorbibliothek erstellt und verwaltet werden.

Interaktion mit anderen Funktionen

Eine Anwendung muss SQLFetch oder SQLFetchScroll aufrufen, bevor sie positionierte Update- oder Löschanweisungen vorbereitet oder ausführt.