SQLFetch-Funktion
Konformität
Version eingeführt: ODBC 1.0-Normenkonformität: ISO 92
Zusammenfassung
SQLFetch ruft das nächste Rowset der Daten aus dem Resultset ab und gibt Daten für alle gebundenen Spalten zurück.
Syntax
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
Argumente
StatementHandle
[Eingabe] Anweisungshandle.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLFetch entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem die SQLGetDiagRec-Funktion 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 in der Regel von SQLFetch 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.) |
| 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. (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 (im Gegensatz zum Bruch) der Zahl 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 war 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 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. |
| 24.000 | Ungültiger Cursorstatus | StatementHandle befand sich in einem ausgeführten Zustand, aber kein Resultset war dem StatementHandle zugeordnet. |
| 40001 | Serialisierungsfehler | Die Transaktion, in der der Abruf ausgeführt wurde, wurde beendet, um einen Deadlock zu verhindern. |
| 40003 | Anweisungsabschluss unbekannt | Bei der zugehörigen Verbindung ist während der Ausführung dieser Funktion ein Fehler aufgetreten, 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 kein implementierungsspezifischer SQLSTATE-Wert 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 arbeitsspeicher nicht 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 SQLFetch-Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle auf der StatementHandle aufgerufen. Anschließend wurde die SQLFetch-Funktion erneut für die AnweisungHandle aufgerufen. Oder die SQLFetch-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 SQLFetch-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) 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, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| 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 des IRD verfügbar und kann durch Aufrufen von SQLDescribeCol, SQLColAttribute oder SQLGetDescField abgerufen werden.) |
| 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. |
| 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 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 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. |
| IM017 | Die Abfrage ist im asynchronen Benachrichtigungsmodus deaktiviert. | Wenn das Benachrichtigungsmodell verwendet wird, ist 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
SQLFetch gibt das nächste Rowset im Resultset zurück. Sie kann nur aufgerufen werden, wenn ein Resultset vorhanden ist, d. h. nach einem Aufruf, der ein Resultset erstellt, und bevor der Cursor über dieses 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 SQLFetch auch diese Informationen zurück. Aufrufe von SQLFetch können mit Aufrufen von SQLFetchScroll gemischt werden, können aber nicht mit Aufrufen von SQLExtendedFetch gemischt werden. Weitere Informationen finden Sie unter Abrufen einer Datenzeile.
Wenn eine ODBC 3*.x*-Anwendung mit einem ODBC 2*.x*-Treiber funktioniert, ordnet der Treiber-Manager SQLFetch-AufrufeSQLExtendedFetch für einen ODBC 2*.x*-Treiber zu, der SQLExtendedFetch unterstützt. Wenn der ODBC 2*.x*-Treiber SQLExtendedFetch nicht unterstützt, ordnet der Treiber-Manager SQLFetch-Aufrufe sqlFetch im ODBC 2*.x*-Treiber zu, der nur eine einzelne Zeile abrufen kann.
Weitere Informationen finden Sie unter BlockCurs, Scrollable Cursors und Abwärtskompatibilität in Anhang G: Treiberrichtlinien für Abwärtskompatibilität.
Positionieren des Cursors
Wenn das Resultset erstellt wird, wird der Cursor vor dem Beginn des Resultsets positioniert. SQLFetch ruft das nächste Rowset ab. Es entspricht dem Aufrufen von SQLFetchScroll , wobei FetchOrientation auf SQL_FETCH_NEXT festgelegt ist. Weitere Informationen zu Cursorn finden Sie unter Cursor undBlockcursors.
Das SQL_ATTR_ROW_ARRAY_SIZE-Anweisungsattribut gibt die Anzahl der Zeilen im Rowset an. Wenn das von SQLFetch abgerufene Rowset das Ende des Resultsets überschneidet, gibt SQLFetch 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 SQLFetch zurückgegeben wurde, ist die aktuelle Zeile die erste Zeile des Rowsets.
Die in der folgenden Tabelle aufgeführten Regeln beschreiben die Cursorpositionierung nach einem Aufruf von SQLFetch basierend auf den Bedingungen, die in der zweiten Tabelle in diesem Abschnitt aufgeführt sind.
| Bedingung | Erste Zeile des neuen Rowsets |
|---|---|
| Vor dem Start | 1 |
| CurrRowsetStart< = LastResultRow – RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow – RowsetSize[1] | Nach Dem Ende |
| Nach Dem Ende | Nach Dem Ende |
[1] Wenn die Rowsetgröße zwischen Abrufen geändert wird, ist dies die Rowsetgröße, die beim vorherigen Abruf verwendet wurde.
[2] Wenn die Rowsetgröße zwischen Abrufen geändert wird, ist dies die Rowsetgröße, die beim neuen Abruf verwendet wurde.
| 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 SQLFetch 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 SQLFetch 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. |
Angenommen, ein Resultset hat 100 Zeilen und die Rowsetgröße ist 5. Die folgende Tabelle zeigt das Rowset und den von SQLFetch zurückgegebenen Code für verschiedene Startpositionen.
| Aktuelles Rowset | Rückgabecode | Neues Rowset | Anzahl der abgerufenen Zeilen |
|---|---|---|---|
| Vor dem Start | SQL_SUCCESS | 1 bis 5 | 5 |
| 1 bis 5 | SQL_SUCCESS | 6 bis 10 | 5 |
| 52 bis 56 | SQL_SUCCESS | 57 bis 61 | 5 |
| 91 bis 95 | SQL_SUCCESS | 96 bis 100 | 5 |
| 93 bis 97 | SQL_SUCCESS | 98 bis 100. Die Zeilen 4 und 5 des Zeilenstatusarrays sind auf SQL_ROW_NOROW festgelegt. | 3 |
| 96 bis 100 | SQL_NO_DATA | Keine. | 0 |
| 99 bis 100 | SQL_NO_DATA | Keine. | 0 |
| Nach Dem Ende | SQL_NO_DATA | Keine. | 0 |
Zurückgeben von Daten in gebundenen Spalten
Wenn SQLFetch jede Zeile zurückgibt, werden die Daten für jede gebundene Spalte im Puffer platziert, der an diese Spalte gebunden ist. Wenn keine Spalten gebunden sind, gibt SQLFetch keine Daten zurück, bewegt den Blockcursor jedoch vorwärts. Die Daten können weiterhin mithilfe von SQLGetData abgerufen werden. Wenn der Cursor ein Mehrzeilencursor ist (d. h. der SQL_ATTR_ROW_ARRAY_SIZE größer als 1), kann SQLGetData nur aufgerufen werden, wenn SQL_GD_BLOCK zurückgegeben wird, wenn SQLGetInfo mit einem InfoType von SQL_GETDATA_EXTENSIONS aufgerufen wird. (Weitere Informationen finden Sie unter SQLGetData.)
Für jede gebundene Spalte in einer Zeile führt SQLFetch folgendes aus:
Legt den Längen-/Indikatorpuffer auf SQL_NULL_DATA fest und fährt mit der nächsten Spalte fort, wenn die Daten NULL sind. Wenn die Daten NULL sind und kein Längen-/Indikatorpuffer gebunden wurde, gibt SQLFetch SQLSTATE 22002 (Indikatorvariable erforderlich, aber nicht angegeben) für die Zeile zurück und fährt mit der nächsten Zeile fort. Informationen zum Bestimmen der Adresse des Längen-/Indikatorpuffers finden Sie unter "Pufferadressen" in SQLBindCol.
Wenn die Daten für die Spalte nicht NULL sind, fährt SQLFetch mit Schritt 2 fort.
Wenn das SQL_ATTR_MAX_LENGTH-Anweisungsattribut auf einen Wert ungleich null festgelegt ist und die Spalte Zeichen- oder Binärdaten enthält, werden die Daten auf SQL_ATTR_MAX_LENGTH Bytes abgeschnitten.
Hinweis
Das SQL_ATTR_MAX_LENGTH-Anweisungsattribut dient zur Verringerung des Netzwerkdatenverkehrs. Sie wird im Allgemeinen von der Datenquelle implementiert, wodurch die Daten abgeschnitten werden, bevor sie über das Netzwerk zurückgegeben werden. Treiber und Datenquellen sind für die Unterstützung nicht erforderlich. Um sicherzustellen, dass Daten auf eine bestimmte Größe gekürzt werden, sollte eine Anwendung daher einen Puffer dieser Größe zuordnen und die Größe im Argument cbValueMax in SQLBindCol angeben.
Konvertiert die Daten in den Typ, der von TargetType in SQLBindCol angegeben wird.
Wenn die Daten in einen Datentyp mit variabler Länge konvertiert wurden, z. B. zeichen oder binär, überprüft SQLFetch , ob die Länge der Daten die Länge des Datenpuffers überschreitet. Wenn die Länge der Zeichendaten (einschließlich des NULL-Terminierungszeichens) die Länge des Datenpuffers überschreitet, schneidet SQLFetch die Daten auf die Länge des Datenpuffers ab, abzüglich der Länge eines NULL-Terminierungszeichens. Anschließend werden die Daten mit NULL beendet. Wenn die Länge der Binärdaten die Länge des Datenpuffers überschreitet, schneidet SQLFetch sie auf die Länge des Datenpuffers ab. Die Länge des Datenpuffers wird mit BufferLength in SQLBindCol angegeben.
SQLFetch schneidet niemals Daten ab, die in Datentypen mit fester Länge konvertiert werden. Dabei wird immer davon ausgegangen, dass die Länge des Datenpuffers der Größe des Datentyps entspricht.
Fügt die konvertierten (und möglicherweise abgeschnittenen) Daten in den Datenpuffer ein. Informationen zum Ermitteln der Adresse des Datenpuffers finden Sie unter "Pufferadressen" in SQLBindCol.
Fügt die Länge der Daten in den Längen-/Indikatorpuffer ein. Wenn der Indikatorzeiger und der Längenzeiger beide auf denselben Puffer festgelegt wurden (wie bei einem Aufruf von SQLBindCol ), wird die Länge in den Puffer für gültige Daten geschrieben, und SQL_NULL_DATA wird in den Puffer für NULL-Daten geschrieben. Wenn kein Längen-/Indikatorpuffer gebunden wurde, gibt SQLFetch die Länge nicht zurück.
Bei Zeichen- oder Binärdaten ist dies die Länge der Daten nach der Konvertierung und vor dem Abschneiden, da der Datenpuffer zu klein ist. Wenn der Treiber die Länge der Daten nach der Konvertierung nicht bestimmen kann, wie dies manchmal bei langen Daten der Fall ist, legt er die Länge auf SQL_NO_TOTAL fest. Wenn Daten aufgrund des SQL_ATTR_MAX_LENGTH-Anweisungsattributs abgeschnitten wurden, wird der Wert dieses Attributs in den Längen-/Indikatorpuffer anstelle der tatsächlichen Länge eingefügt. Dies liegt daran, dass dieses Attribut so konzipiert ist, dass Daten auf dem Server vor der Konvertierung abgeschnitten werden, sodass der Treiber keine Möglichkeit hat, die tatsächliche Länge zu ermitteln.
Bei allen anderen Datentypen ist dies die Länge der Daten nach der Konvertierung. Das heißt, es ist die Größe des Typs, in den die Daten konvertiert wurden.
Informationen zum Bestimmen der Adresse des Längen-/Indikatorpuffers finden Sie unter "Pufferadressen" in SQLBindCol.
Wenn die Daten während der Konvertierung abgeschnitten werden, ohne dass signifikante Ziffern verloren gehen (z. B. wird die reelle Zahl 1.234 bei der Konvertierung auf die ganze Zahl 1 abgeschnitten), gibt SQLFetch SQLSTATE 01S07 (Bruchkürzung) und SQL_SUCCESS_WITH_INFO zurück. Wenn die Daten abgeschnitten werden, weil die Länge des Datenpuffers zu klein ist (z. B. wird die Zeichenfolge "abcdef" in einen 4-Byte-Puffer eingefügt), gibt SQLFetch SQLSTATE 01004 (Daten abgeschnitten) und SQL_SUCCESS_WITH_INFO zurück. Wenn Daten aufgrund des SQL_ATTR_MAX_LENGTH-Anweisungsattributs abgeschnitten werden, gibt SQLFetch SQL_SUCCESS zurück und gibt sqlstate 01S07 (Bruchkürzung) oder SQLSTATE 01004 (Datenkürzung) nicht zurück. Wenn Daten während der Konvertierung abgeschnitten werden und signifikante Ziffern verloren gehen (z. B. wenn ein SQL_INTEGER Wert größer als 100.000 in eine SQL_C_TINYINT konvertiert wurde), gibt SQLFetch SQLSTATE 22003 (Numerischer Wert außerhalb des Bereichs) und SQL_ERROR zurück (wenn die Rowsetgröße 1 ist) oder SQL_SUCCESS_WITH_INFO (wenn die Rowsetgröße größer als 1 ist).
Der Inhalt des gebundenen Datenpuffers und des Längen-/Indikatorpuffers sind nicht definiert, wenn SQLFetch oder SQLFetchScroll nicht SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO zurückgibt.
Zeilenstatusarray
Das Zeilenstatusarray wird verwendet, um den Status jeder Zeile im Rowset zurückzugeben. Die Adresse dieses Arrays wird mit dem SQL_ATTR_ROW_STATUS_PTR-Anweisungsattribut angegeben. Das Array wird von der Anwendung zugeordnet und muss über so viele Elemente verfügen, wie im SQL_ATTR_ROW_ARRAY_SIZE-Anweisungsattribut angegeben sind. Die Werte werden von SQLFetch, SQLFetchScroll und SQLBulkOperations oder SQLSetPos festgelegt (außer wenn sie aufgerufen wurden, nachdem der Cursor von SQLExtendedFetch positioniert wurde). Wenn der Wert des SQL_ATTR_ROW_STATUS_PTR-Anweisungsattributs ein NULL-Zeiger ist, geben diese Funktionen den Zeilenstatus nicht zurück.
Der Inhalt des Zeilenstatusarraypuffers ist nicht definiert, wenn SQLFetch oder SQLFetchScroll nicht SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO zurückgibt.
Die folgenden Werte werden im Zeilenstatusarray zurückgegeben.
| Zeilenstatusarraywert | BESCHREIBUNG |
|---|---|
| SQL_ROW_SUCCESS | Die Zeile wurde erfolgreich abgerufen und hat sich seit dem letzten Abruf aus diesem Resultset nicht geändert. |
| SQL_ROW_SUCCESS_WITH_INFO | Die Zeile wurde erfolgreich abgerufen und hat sich seit dem letzten Abruf aus diesem Resultset nicht geändert. Es wurde jedoch eine Warnung für die Zeile zurückgegeben. |
| SQL_ROW_ERROR | Fehler beim Abrufen der Zeile. |
| SQL_ROW_UPDATED[1], [2] und [3] | Die Zeile wurde erfolgreich abgerufen und hat sich geändert, seit sie zuletzt aus diesem Resultset abgerufen wurde. Wenn die Zeile erneut aus diesem Resultset abgerufen oder von SQLSetPos aktualisiert wird, wird der Status in den neuen Status der Zeile geändert. |
| SQL_ROW_DELETED[3] | Die Zeile wurde gelöscht, seit sie zuletzt aus diesem Resultset abgerufen wurde. |
| SQL_ROW_ADDED[4] | Die Zeile wurde von SQLBulkOperations eingefügt. Wenn die Zeile erneut aus diesem Resultset abgerufen oder von SQLSetPos aktualisiert wird, lautet ihr Status SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | Das Rowset überlappt das Ende des Resultsets, und es wurde keine Zeile zurückgegeben, die diesem Element des Zeilenstatusarrays entsprach. |
[1] Bei Keyset-, gemischten und dynamischen Cursorn gilt die Datenzeile als gelöscht und eine neue Zeile hinzugefügt, wenn ein Schlüsselwert aktualisiert wird.
[2] Einige Treiber können Datenaktualisierungen nicht erkennen und können daher diesen Wert nicht zurückgeben. Um zu bestimmen, ob ein Treiber Updates für zurückgeforderte Zeilen erkennen kann, ruft eine Anwendung SQLGetInfo mit der Option SQL_ROW_UPDATES auf.
[3] SQLFetch kann diesen Wert nur zurückgeben, wenn er mit Aufrufen von SQLFetchScroll gemischt wird. Dies liegt daran , dass SQLFetch sich durch das Resultset vorwärts bewegt und bei ausschließlicher Verwendung keine Zeilen refetcht. Da keine Zeilen refetched werden, erkennt SQLFetch keine Änderungen, die an zuvor abgerufenen Zeilen vorgenommen wurden. Wenn SQLFetchScroll den Cursor jedoch vor allen zuvor abgerufenen Zeilen positioniert und SQLFetch zum Abrufen dieser Zeilen verwendet wird, kann SQLFetch alle Änderungen an diesen Zeilen erkennen.
[4] Nur von SQLBulkOperations zurückgegeben. Nicht durch SQLFetch oder SQLFetchScroll festgelegt.
Abgerufener Zeilenpuffer
Der abgerufene Zeilenpuffer wird verwendet, um die Anzahl der abgerufenen Zeilen zurückzugeben, einschließlich der Zeilen, für die keine Daten zurückgegeben wurden, weil beim Abrufen ein Fehler aufgetreten ist. Mit anderen Worten, es ist die Anzahl der Zeilen, für die der Wert im Zeilenstatusarray nicht SQL_ROW_NOROW ist. Die Adresse dieses Puffers wird mit dem Attribut SQL_ATTR_ROWS_FETCHED_PTR-Anweisung angegeben. Der Puffer wird von der Anwendung zugewiesen. Sie wird von SQLFetch und SQLFetchScroll festgelegt. Wenn der Wert des SQL_ATTR_ROWS_FETCHED_PTR-Anweisungsattributs ein NULL-Zeiger ist, geben diese Funktionen nicht die Anzahl der abgerufenen Zeilen zurück. Um die Anzahl der aktuellen Zeile im Resultset zu bestimmen, kann eine Anwendung SQLGetStmtAttr mit dem attribut SQL_ATTR_ROW_NUMBER aufrufen.
Der Inhalt des abgerufenen Zeilenpuffers ist nicht definiert, wenn SQLFetch oder SQLFetchScroll SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO nicht zurückgibt, außer wenn SQL_NO_DATA zurückgegeben wird. In diesem Fall wird der Wert in den abgerufenen Zeilen auf 0 festgelegt.
Fehlerbehandlung
Fehler und Warnungen können für einzelne Zeilen oder für die gesamte Funktion gelten. Weitere Informationen zu Diagnosedatensätzen finden Sie unter Diagnose und SQLGetDiagField.
Fehler und Warnungen für die gesamte Funktion
Wenn ein Fehler für die gesamte Funktion gilt, z. B. SQLSTATE HYT00 (Timeout abgelaufen) oder SQLSTATE 24000 (Ungültiger Cursorzustand), gibt SQLFetch SQL_ERROR und den entsprechenden SQLSTATE zurück. Der Inhalt der Rowsetpuffer ist nicht definiert, und die Cursorposition bleibt unverändert.
Wenn eine Warnung für die gesamte Funktion gilt, gibt SQLFetch SQL_SUCCESS_WITH_INFO und den entsprechenden SQLSTATE zurück. Die Statusdatensätze für Warnungen, die für die gesamte Funktion gelten, werden vor den Statusdatensätzen zurückgegeben, die für einzelne Zeilen gelten.
Fehler und Warnungen in einzelnen Zeilen
Wenn ein Fehler (z. B. SQLSTATE 22012 (Division by zero)) oder eine Warnung (z. B. SQLSTATE 01004 (Data truncated)) auf eine einzelne Zeile zutrifft, führt SQLFetchfolgendes aus:
Legt das entsprechende Element des Zeilenstatusarrays auf SQL_ROW_ERROR für Fehler oder SQL_ROW_SUCCESS_WITH_INFO für Warnungen fest.
Fügt null oder mehr Statusdatensätze hinzu, die SQLSTATEs für den Fehler oder die Warnung enthalten.
Legt die Felder Zeilen- und Spaltennummer in den Statusdatensätzen fest. Wenn SQLFetch keine Zeilen- oder Spaltennummer ermitteln kann, wird diese Zahl auf SQL_ROW_NUMBER_UNKNOWN bzw. SQL_COLUMN_NUMBER_UNKNOWN festgelegt. Wenn der Statusdatensatz nicht für eine bestimmte Spalte gilt, legt SQLFetch die Spaltennummer auf SQL_NO_COLUMN_NUMBER fest.
SQLFetch setzt das Abrufen von Zeilen fort, bis alle Zeilen im Rowset abgerufen wurden. Es wird SQL_SUCCESS_WITH_INFO zurückgegeben, es sei denn, in jeder Zeile des Rowsets tritt ein Fehler auf (ohne Zeilen mit dem Status SQL_ROW_NOROW), in diesem Fall wird SQL_ERROR zurückgegeben. Insbesondere wenn die Rowsetgröße 1 ist und in dieser Zeile ein Fehler auftritt, gibt SQLFetch SQL_ERROR zurück.
SQLFetch gibt die Statusdatensätze in Zeilennummernreihenfolge zurück. Das heißt, es gibt alle Statusdatensätze für unbekannte Zeilen (falls vorhanden) zurück. als Nächstes werden alle Statusdatensätze für die erste Zeile (falls vorhanden) und dann alle Statusdatensätze für die zweite Zeile (falls vorhanden) zurückgegeben usw. Die Statusdatensätze für jede Zeile werden gemäß den normalen Regeln für die Reihenfolge von Statusdatensätzen sortiert; Weitere Informationen finden Sie unter "Sequenz von Statusdatensätzen" in SQLGetDiagField.
Deskriptoren und SQLFetch
In den folgenden Abschnitten wird beschrieben, wie SQLFetch mit Deskriptoren interagiert.
Argumentzuordnungen
Der Treiber legt keine Deskriptorfelder basierend auf den Argumenten von SQLFetch fest.
Andere Deskriptorfelder
Die folgenden Deskriptorfelder werden von SQLFetch verwendet.
| Deskriptorfeld | Desc. | Feld in | Festlegen durch |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | header | SQL_ATTR_ROW_ARRAY_SIZE-Anweisungsattribut |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | header | SQL_ATTR_ROW_STATUS_PTR-Anweisungsattribut |
| SQL_DESC_BIND_OFFSET_PTR | ARD | header | SQL_ATTR_ROW_BIND_OFFSET_PTR-Anweisungsattribut |
| SQL_DESC_BIND_TYPE | ARD | header | SQL_ATTR_ROW_BIND_TYPE-Anweisungsattribut |
| SQL_DESC_COUNT | ARD | header | ColumnNumber-Argument von SQLBindCol |
| SQL_DESC_DATA_PTR | ARD | records | TargetValuePtr-Argument von SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | records | StrLen_or_IndPtr Argument in SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | records | BufferLength-Argument in SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | records | StrLen_or_IndPtr Argument in SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | header | SQL_ATTR_ROWS_FETCHED_PTR-Anweisungsattribut |
| SQL_DESC_TYPE | ARD | records | TargetType-Argument in SQLBindCol |
Alle Deskriptorfelder können auch über SQLSetDescField festgelegt werden.
Separate Längen- und Indikatorpuffer
Anwendungen können einen einzelnen Puffer oder zwei separate Puffer binden, die zum Halten von Längen- und Indikatorwerten verwendet werden können. Wenn eine Anwendung SQLBindCol aufruft, legt der Treiber die SQL_DESC_OCTET_LENGTH_PTR- und SQL_DESC_INDICATOR_PTR Felder der ARD auf dieselbe Adresse fest, die im argument StrLen_or_IndPtr übergeben wird. Wenn eine Anwendung SQLSetDescField oder SQLSetDescRec aufruft, kann sie diese beiden Felder auf unterschiedliche Adressen festlegen.
SQLFetch bestimmt, ob die Anwendung separate Längen- und Indikatorpuffer angegeben hat. Wenn die Daten in diesem Fall nicht NULL sind, legt SQLFetch den Indikatorpuffer auf 0 fest und gibt die Länge im Längenpuffer zurück. Wenn die Daten NULL sind, legt SQLFetch den Indikatorpuffer auf SQL_NULL_DATA fest und ändert den Längenpuffer nicht.
Codebeispiel
Siehe SQLBindCol, SQLColumns, SQLGetData und SQLProcedures.
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Binden eines Puffers an eine Spalte in einem Resultset | SQLBindCol-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 eines Datenblocks oder Scrollen durch ein Resultset | SQLFetchScroll-Funktion |
| Schließen des Cursors für die -Anweisung | SQLFreeStmt-Funktion |
| Abrufen eines Teils oder des Gesamten einer Datenspalte | SQLGetData-Funktion |
| Zurückgeben der Anzahl von Resultsetspalten | SQLNumResultCols-Funktion |
| Vorbereiten einer Anweisung für die Ausführung | SQLPrepare-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