SQLExtendedFetch-Funktion
Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: veraltet
Zusammenfassung
SQLExtendedFetch 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.
Hinweis
In ODBC 3*.x* wurde SQLExtendedFetch durch SQLFetchScroll ersetzt. ODBC 3*.x*-Anwendungen sollten SQLExtendedFetch nicht aufrufen. stattdessen sollten sie SQLFetchScroll aufrufen. Der Treiber-Manager ordnet SQLFetchScrollsqlExtendedFetch zu, wenn sie mit einem ODBC 2*.x*-Treiber arbeiten. ODBC 3*.x*-Treiber sollten SQLExtendedFetch unterstützen, wenn sie mit ODBC 2*.x*-Anwendungen arbeiten möchten, die sie aufrufen. Weitere Informationen finden Sie unter "Kommentare" und Blockcursors, Scrollbare Cursor und Abwärtskompatibilität in Anhang G: Treiberrichtlinien für Abwärtskompatibilität.
Syntax
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Argumente
StatementHandle
[Eingabe] Anweisungshandle.
FetchOrientation
[Eingabe] Art des Abrufs. Dies ist identisch mit FetchOrientation in SQLFetchScroll.
FetchOffset
[Eingabe] Nummer der abzurufenden Zeile. Dies ist mit einer Ausnahme identisch mit FetchOffset in SQLFetchScroll. Wenn FetchOrientation SQL_FETCH_BOOKMARK ist, ist FetchOffset ein Lesezeichen mit fester Länge, kein Offset eines Lesezeichens. Anders ausgedrückt: SQLExtendedFetch ruft das Lesezeichen aus diesem Argument ab, nicht das attribut SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisung. Es unterstützt keine Lesezeichen mit variabler Länge und nicht das Abrufen eines Rowsets an einem Offset (außer 0) aus einem Lesezeichen.
RowCountPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Anzahl der tatsächlich abgerufenen Zeilen zurückgegeben werden soll. Dieser Puffer wird auf die gleiche Weise wie der Puffer verwendet, der durch das attribut SQL_ATTR_ROWS_FETCHED_PTR-Anweisung angegeben wird. Dieser Puffer wird nur von SQLExtendedFetch verwendet. Es wird nicht von SQLFetch oder SQLFetchScroll verwendet.
RowStatusArray
[Ausgabe] Zeiger auf ein Array, in dem der Status jeder Zeile zurückgegeben werden soll. Dieses Array wird auf die gleiche Weise wie das array verwendet, das durch das Attribut SQL_ATTR_ROW_STATUS_PTR-Anweisung angegeben wird.
Die Adresse dieses Arrays wird jedoch nicht im Feld SQL_DESC_STATUS_ARRAY_PTR im IRD gespeichert. Darüber hinaus wird dieses Array nur von SQLExtendedFetch und von SQLBulkOperations mit einem Vorgang von SQL_ADD oder SQLSetPos verwendet, wenn es nach SQLExtendedFetch aufgerufen wird. Es wird nicht von SQLFetch oder SQLFetchScroll verwendet, und es wird nicht von SQLBulkOperations oder SQLSetPos verwendet, wenn sie nach SQLFetch oder SQLFetchScroll aufgerufen werden. Es wird auch nicht verwendet, wenn SQLBulkOperations mit einem Vorgang von SQL_ADD aufgerufen wird, bevor eine Abruffunktion aufgerufen wird. Mit anderen Worten, es wird nur im Anweisungszustand S7 verwendet. Es wird nicht in den Anweisungszuständen S5 oder S6 verwendet. Weitere Informationen finden Sie unter Anweisungsübergänge in Anhang B: ODBC-Zustandsübergangstabellen.
Anwendungen sollten einen gültigen Zeiger im Argument RowStatusArray bereitstellen. andernfalls sind das Verhalten von SQLExtendedFetch und das Verhalten von Aufrufen von SQLBulkOperations oder SQLSetPos , nachdem ein Cursor von SQLExtendedFetch positioniert wurde, nicht definiert.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLExtendedFetch entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLError aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLExtendedFetch 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.
| 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. Wenn es sich um einen numerischen Wert handelte, wurde der Bruchteil der Zahl abgeschnitten. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S01 | Fehler in Zeile | Beim Abrufen einer oder mehrerer Zeilen ist ein Fehler aufgetreten. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S06 | Versuchen sie zu abrufen, bevor das Resultset das erste Rowset zurückgegeben hat. | Das angeforderte Rowset überlappt den Anfang des Resultsets, wenn die aktuelle Position über der ersten Zeile lag, und entweder FetchOrientation wurde SQL_PRIOR oder FetchOrientation wurde mit einem negativen FetchOffset SQL_RELATIVE, dessen absoluter Wert kleiner oder gleich dem aktuellen SQL_ROWSET_SIZE 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 | Ein Datenwert konnte nicht in den von TargetType in SQLBindCol angegebenen C-Datentyp konvertiert werden. |
| 07009 | Ungültiger Deskriptorindex | Spalte 0 war an SQLBindCol 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. |
| 22002 | Indikatorvariable erforderlich, aber nicht angegeben | NULL-Daten wurden in eine Spalte abgerufen, deren StrLen_or_IndPtr von SQLBindCol als NULL-Zeiger festgelegt wurde. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 22003 | Numerischer Wert außerhalb des Bereichs | Das Zurückgeben des numerischen Werts (als numerisch oder Zeichenfolge) für eine oder mehrere Spalten hätte dazu geführt, dass der gesamte Teil (im Gegensatz zum Bruch) der Zahl abgeschnitten wurde. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) Weitere Informationen finden Sie unter Richtlinien für Intervall- und numerische 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. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 22012 | Division by Zero | Ein Wert aus einem arithmetischen Ausdruck wurde zurückgegeben, was zu einer Division durch 0 führte. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 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. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 22018 | Ungültiger Zeichenwert für die Umwandlungsspezifikation | Der C-Typ war ein exakter 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. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 24.000 | Ungültiger Cursorstatus | StatementHandle befand sich in einem ausgeführten Zustand, aber kein Resultset war dem StatementHandle zugeordnet. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLError 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 Vervollständigung der Funktion erforderlich ist. |
| HY008 | Vorgang abgebrochen | Für statementHandle wurde die asynchrone Verarbeitung aktiviert. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle aufgerufen, und dann wurde die Funktion für die StatementHandle erneut aufgerufen. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle auf der StatementHandle von 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 SQLExtendedFetch-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) Die angegebene AnweisungHandle befand sich 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 Funktion) wurde für das StatementHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für die StatementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführung gesendet wurden. (DM) SQLExtendedFetch wurde für die StatementHandle aufgerufen, nachdem SQLFetch oder SQLFetchScroll aufgerufen wurde und bevor SQLFreeStmt mit der option SQL_CLOSE aufgerufen wurde. (DM) SQLBulkOperations wurde für eine Anweisung aufgerufen, bevor SQLFetch, SQLFetchScroll oder SQLExtendedFetch aufgerufen wurde, und dann sqlExtendedFetch wurde aufgerufen, bevor SQLFreeStmt mit der Option SQL_CLOSE aufgerufen wurde. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY106 | Abrufen des Typs aus dem Bereich | (DM) Der für das Argument FetchOrientation angegebene Wert war ungültig. (Siehe "Kommentare".) Das Argument FetchOrientation wurde SQL_FETCH_BOOKMARK, und das Attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung wurde auf SQL_UB_OFF festgelegt. Der Wert der SQL_CURSOR_TYPE-Anweisungsoption wurde SQL_CURSOR_FORWARD_ONLY, und der Wert des Arguments FetchOrientation wurde nicht SQL_FETCH_NEXT. Das Argument FetchOrientation wurde SQL_FETCH_RESUME. |
| HY107 | Zeilenwert außerhalb des Bereichs | Der mit der SQL_CURSOR_TYPE-Anweisungsoption angegebene Wert wurde SQL_CURSOR_KEYSET_DRIVEN, aber der mit dem SQL_KEYSET_SIZE-Anweisungsattribut angegebene Wert war größer als 0 und kleiner als der mit dem SQL_ROWSET_SIZE-Anweisungsattribut angegebene Wert. |
| HY111 | Ungültiger Lesezeichenwert | Das Argument FetchOrientation wurde SQL_FETCH_BOOKMARK, und das im FetchOffset-Argument angegebene Lesezeichen war ungültig. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum Angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYC00 | Optionale Funktion nicht implementiert | Der Treiber oder die Datenquelle unterstützt den angegebenen Abruftyp nicht. 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. Dieser Fehler gilt nur, wenn der SQL-Datentyp der Spalte einem treiberspezifischen SQL-Datentyp zugeordnet wurde. |
| HYT00 | Timeout abgelaufen | Der Abfragetimeoutzeitraum ist abgelaufen, bevor die Datenquelle das Resultset zurückgibt. Der Timeoutzeitraum wird über SQLSetStmtOption festgelegt, SQL_QUERY_TIMEOUT. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitraum für das Verbindungstimeout wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Der Treiber unterstützt diese Funktion nicht. | (DM) Der der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
Kommentare
Das Verhalten von SQLExtendedFetch ist mit den folgenden Ausnahmen mit dem verhalten von SQLFetchScroll identisch:
SQLExtendedFetch und SQLFetchScroll verwenden verschiedene Methoden, um die Anzahl der abgerufenen Zeilen zurückzugeben. SQLExtendedFetch gibt die Anzahl der in *RowCountPtr abgerufenen Zeilen zurück. SQLFetchScroll gibt die Anzahl der Zeilen zurück, die direkt an den Puffer abgerufen werden, auf den SQL_ATTR_ROWS_FETCHED_PTR verweist. Weitere Informationen finden Sie im RowCountPtr-Argument .
SQLExtendedFetch und SQLFetchScroll geben den Status jeder Zeile in verschiedenen Arrays zurück. Weitere Informationen finden Sie im RowStatusArray-Argument .
SQLExtendedFetch und SQLFetchScroll verwenden verschiedene Methoden, um das Lesezeichen abzurufen, wenn FetchOrientation SQL_FETCH_BOOKMARK ist. SQLExtendedFetch unterstützt keine Lesezeichen mit variabler Länge oder das Abrufen von Rowsets an einem anderen Offset als 0 aus einem Lesezeichen. Weitere Informationen finden Sie im FetchOffset-Argument .
SQLExtendedFetch und SQLFetchScroll verwenden unterschiedliche Rowsetgrößen. SQLExtendedFetch verwendet den Wert des attributs SQL_ROWSET_SIZE-Anweisung, und SQLFetchScroll verwendet den Wert des attributs SQL_ATTR_ROW_ARRAY_SIZE anweisung.
SQLExtendedFetch weist etwas andere Fehlerbehandlungssemantik auf als SQLFetchScroll. Weitere Informationen finden Sie unter "Fehlerbehandlung" im Abschnitt "Kommentare" von SQLFetchScroll.
SQLExtendedFetch unterstützt keine Bindungsoffsets (das Attribut der SQL_ATTR_ROW_BIND_OFFSET_PTR-Anweisung).
Aufrufe von SQLExtendedFetch können nicht mit Aufrufen von SQLFetch oder SQLFetchScroll gemischt werden. Wenn SQLBulkOperations aufgerufen wird, bevor eine Abruffunktion aufgerufen wird, kann SQLExtendedFetch erst aufgerufen werden, wenn der Cursor geschlossen und erneut geöffnet wird. Das heißt, SQLExtendedFetch kann nur im Anweisungszustand S7 aufgerufen werden. Weitere Informationen finden Sie unter Anweisungsübergänge in Anhang B: ODBC-Zustandsübergangstabellen.
Wenn eine Anwendung SQLFetchScroll aufruft, während sie einen ODBC 2*.x*-Treiber verwendet, ordnet der Treiber-Manager diesen Aufruf SQLExtendedFetch zu. Weitere Informationen finden Sie unter "SQLFetchScroll und ODBC 2*.x* Drivers" in SQLFetchScroll.
In ODBC 2*.x* wurde SQLExtendedFetch aufgerufen, um mehrere Zeilen abzurufen, und SQLFetch wurde aufgerufen, um eine einzelne Zeile abzurufen. In ODBC 3*.x* kann dagegen SQLFetch aufgerufen werden, um mehrere Zeilen abzurufen.
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 |
| 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-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für