SQLExtendedFetch-Funktion
Konformität
Version eingeführt: ODBC 1.0-Standardscompliance: Veraltet
Zusammenfassung
SQLExtendedFetch 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.
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 SQLFetchScroll sqlExtendedFetch 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 "Blockcursor", bildlauffähige 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] Typ des Abrufs. Dies ist identisch mit FetchOrientation in SQLFetchScroll.
FetchOffset
[Eingabe] Die Nummer der abzurufenden Zeile. Dies ist identisch mit FetchOffset in SQLFetchScroll, mit einer Ausnahme. Wenn FetchOrientation SQL_FETCH_BOOKMARK ist, ist FetchOffset eine Textmarke mit fester Länge und kein Offset von einer Textmarke. Mit anderen Worten, SQLExtendedFetch ruft die Textmarke aus diesem Argument ab, nicht das attribut der SQL_ATTR_FETCH_BOOKMARK_PTR-Anweisung. Es unterstützt keine Textmarken mit variabler Länge und unterstützt nicht das Abrufen eines Rowsets bei einem Offset (außer 0) aus einer Textmarke.
RowCountPtr
[Ausgabe] Zeigen Sie 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 durch das attribut der SQL_ATTR_ROWS_FETCHED_PTR-Anweisung angegebene Puffer verwendet. Dieser Puffer wird nur von SQLExtendedFetch verwendet. Sie wird nicht von SQLFetch oder SQLFetchScroll verwendet.
RowStatusArray
[Ausgabe] Zeigen Sie 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 der 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 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 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, sie wird nur im Anweisungszustand S7 verwendet. Es wird nicht in Anweisungszuständen S5 oder S6 verwendet. Weitere Informationen finden Sie unter "Anweisungsübergänge" in Anhang B: ODBC-Statusübergangstabellen .
Anwendungen sollten einen gültigen Zeiger im RowStatusArray-Argument bereitstellen. Andernfalls sind das Verhalten von SQLExtendedFetch und das Verhalten von Aufrufen von SQLBulkOperations oder SQLSetPos nach der Position eines Cursors durch SQLExtendedFetch nicht definiert.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnostik
Wenn SQLExtendedFetch entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLError abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLExtendedFetch 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 bestimmen, für die 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 | 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. Wenn es sich um einen numerischen Wert handelte, wurde der Bruchteil der Zahl abgeschnitten. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S01 | Fehler in Zeile | Fehler beim Abrufen einer oder mehrerer Zeilen. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01S06 | Versuch, abzurufen, bevor das Resultset das erste Rowset zurückgegeben hat | Das angeforderte Rowset überlappt den Anfang des Resultsets, wenn die aktuelle Position über die erste Zeile hinausging, und entweder "FetchOrientation " SQL_PRIOR oder "FetchOrientation " wurde mit einem negativen FetchOffset SQL_RELATIVE, dessen absoluter Wert kleiner oder gleich dem aktuellen SQL_ROWSET_SIZE 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 | Ein Datenwert konnte nicht in den von TargetType in SQLBindCol angegebenen C-Datentyp konvertiert werden. |
| 07009 | Ungültiger Deskriptorindex | Spalte 0 wurde mit SQLBindCol 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. |
| 22002 | Indikatorvariable erforderlich, aber nicht angegeben | NULL-Daten wurden in eine Spalte abgerufen, deren StrLen_or_IndPtr von SQLBindCol als Nullzeiger festgelegt wurde. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 22003 | Numerischer Wert außerhalb des Bereichs | Das Zurückgeben des numerischen Werts (als numerische oder Zeichenfolge) für eine oder mehrere Spalten hätte dazu geführt, dass der gesamte Teil (im Gegensatz zu Bruchzahlen) der Zahl abgeschnitten wird. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) Weitere Informationen finden Sie in den Richtlinien für Intervall- und numerische 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. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 22012 | Division durch Null | Ein Wert aus einem arithmetischen Ausdruck wurde zurückgegeben, was zu Einer Division durch Null führte. (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 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. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 22018 | Ungültiger Zeichenwert für die Umwandlungsspezifikation | 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. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 24.000 | Ungültiger Cursorstatus | The StatementHandle was in an executed state, but no result set was associated with the StatementHandle. |
| 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 SQLError im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine 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 das StatementHandle aufgerufen, und dann 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 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) 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) SQLExtendedFetch wurde für " 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 sqlExtendedFetch wurde aufgerufen, 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. |
| HY106 | Abrufen des Bereichstyps | (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 Option SQL_CURSOR_TYPE-Anweisung 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, der mit dem attribut SQL_KEYSET_SIZE-Anweisung angegebene Wert war jedoch größer als 0 und kleiner als der wert, der mit dem attribut SQL_ROWSET_SIZE-Anweisung angegeben wurde. |
| HY111 | Ungültiger Textmarkenwert | Das Argument FetchOrientation wurde SQL_FETCH_BOOKMARK, und die im FetchOffset-Argument angegebene Textmarke war ungültig. |
| 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 | Treiber oder Datenquelle unterstützt den angegebenen Abruftyp nicht. 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. Dieser Fehler gilt nur, wenn der SQL-Datentyp der Spalte einem treiberspezifischen SQL-Datentyp zugeordnet wurde. |
| HYT00 | Timeout überschritten | Der Abfragetimeoutzeitraum ist abgelaufen, bevor die Datenquelle das Resultset zurückgibt. Der Timeoutzeitraum wird über SQLSetStmtOption SQL_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. |
Kommentare
Das Verhalten von SQLExtendedFetch ist identisch mit dem von SQLFetchScroll, mit den folgenden Ausnahmen:
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 wurden, 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 die Textmarke abzurufen, wenn FetchOrientation SQL_FETCH_BOOKMARK ist. SQLExtendedFetch unterstützt keine Textmarken mit variabler Länge oder das Abrufen von Rowsets an einem anderen Offset als 0 aus einer Textmarke. 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 der SQL_ATTR_ROW_ARRAY_SIZE-Anweisung.
SQLExtendedFetch weist etwas andere Fehlerbehandlungssemantik als SQLFetchScroll auf. 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, und 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-Statusübergangstabellen .
Wenn eine Anwendung SQLFetchScroll während der Verwendung eines ODBC 2*.x*-Treibers aufruft, 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 sqlFetch dagegen aufgerufen werden, um mehrere Zeilen abzurufen.
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 |
| 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 |