SQLFetch-Funktion
Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92
Zusammenfassung
SQLFetch ruft das nächste Rowset von 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.
Diagnostik
Wenn SQLFetch entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen der SQLGetDiagRec-Funktion mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLFetch 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 ermitteln, auf 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 (mit Ausnahme von 01xxx SQLSTATEs) zurückgeben können, wird SQL_SUCCESS_WITH_INFO zurückgegeben, wenn ein Fehler für einen oder mehrere, jedoch nicht alle Zeilen eines Mehrzeilenvorgangs auftritt, und SQL_ERROR zurückgegeben wird, wenn ein Fehler bei einem Einzelzeilenvorgang auftritt.
| 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. |
| 01S01 | Fehler in Zeile | Fehler beim Abrufen einer oder mehrerer Zeilen. (Wenn dieser SQLSTATE-Wert 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. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 07006 | Verletzung des Eingeschränkten Datentyp-Attributs | Der Datenwert einer Spalte im Resultset konnte nicht in den durch TargetType in SQLBindCol angegebenen Datentyp konvertiert werden. Spalte 0 wurde mit einem Datentyp von SQL_C_BOOKMARK gebunden, und das attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung wurde auf SQL_UB_VARIABLE festgelegt. Spalte 0 wurde 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 wurde 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. |
| 22001 | Zeichenfolgendaten, rechts abgeschnitten | Eine Textmarke mit variabler Länge, die für eine Spalte zurückgegeben wird, wurde abgeschnitten. |
| 22002 | Indikatorvariable erforderlich, aber nicht angegeben | NULL-Daten wurden in eine Spalte abgerufen, deren StrLen_or_IndPtr von SQLBindCol (oder SQL_DESC_INDICATOR_PTR von SQLSetDescField oder SQLSetDescRec festgelegt) ein Nullzeiger war. |
| 22003 | Numerischer Wert außerhalb des Bereichs | Wenn Sie den numerischen Wert als numerische oder Zeichenfolge für eine oder mehrere gebundene Spalten zurückgeben, würde der gesamte Teil (im Gegensatz zu Bruchzahlen) der Zahl abgeschnitten werden. 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 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. |
| 22012 | Division durch Null | Ein Wert aus einem arithmetischen Ausdruck wurde zurückgegeben, was zu Einer Division durch Null führte. |
| 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. |
| 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 keine Darstellung im Zeichensatz des Puffers vorhanden war. 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. |
| 24.000 | Ungültiger Cursorstatus | Die Anweisungshandle wurde in einem ausgeführten Zustand ausgeführt, aber dem StatementHandle wurde kein Resultset zugeordnet. |
| 40001 | Serialisierungsfehler | Die Transaktion, in der der Abruf ausgeführt wurde, wurde beendet, um deadlock zu verhindern. |
| 40003 | Abschluss der Anweisung unbekannt | Fehler bei der zugehörigen Verbindung während der Ausführung dieser Funktion, 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 dessen Ursache. |
| HY001 | Speicherzuweisungsfehler | Der Treiber konnte arbeitsspeicher nicht zuordnen, der zur Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist. |
| HY008 | Vorgang abgebrochen | Die asynchrone Verarbeitung wurde für " StatementHandle" aktiviert. Die SQLFetch-Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für die Anweisungshandle aufgerufen. Anschließend wurde die SQLFetch-Funktion erneut für " StatementHandle" aufgerufen. Oder die SQLFetch-Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle für das StatementHandle von einem anderen Thread in einer Multithread-Anwendung 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 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) 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) SQLFetch wurde für " StatementHandle " aufgerufen, nachdem SQLExtendedFetch aufgerufen wurde und 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. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | Das Attribut der SQL_ATTR_USE_BOOKMARK-Anweisung wurde auf SQL_UB_VARIABLE festgelegt, und Spalte 0 wurde an einen Puffer gebunden, dessen Länge nicht der maximalen Länge für die Textmarke für diesen Resultset entspricht. (Diese Länge ist im Feld SQL_DESC_OCTET_LENGTH des IRD verfügbar und kann durch Aufrufen abgerufen werden.SQLDescribeCol, SQLColAttribute oder SQLGetDescField.) |
| HY107 | Zeilenwert außerhalb des Bereichs | Der mit dem attribut der SQL_ATTR_CURSOR_TYPE-Anweisung angegebene Wert wurde SQL_CURSOR_KEYSET_DRIVEN, der mit dem attribut SQL_ATTR_KEYSET_SIZE-Anweisung angegebene Wert war jedoch größer als 0 und kleiner als der wert, der mit dem attribut SQL_ATTR_ROW_ARRAY_SIZE-Anweisung angegeben wurde. |
| 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 | 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. |
| HYT00 | Timeout überschritten | Der Abfragetimeoutzeitraum ist abgelaufen, bevor die Datenquelle das angeforderte Resultset zurückgegeben hat. Der Timeoutzeitraum wird über SQLSetStmtAttr SQL_ATTR_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. |
| IM017 | Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert. | Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung 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 Nachbearbeitung 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 diesen 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-Aufrufe sqlExtendedFetch 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 Blockcursor, scrollfähige Cursor 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 Start des Resultsets positioniert. SQLFetch ruft das nächste Rowset ab. Es entspricht dem Aufrufen von SQLFetchScroll mit FetchOrientation-Set auf SQL_FETCH_NEXT. Weitere Informationen zu Cursorn finden Sie unter Cursor und Blockcursor.
Das attribut SQL_ATTR_ROW_ARRAY_SIZE-Anweisung gibt die Anzahl der Zeilen im Rowset an. Wenn das von SQLFetch abgerufene Rowset das Ende des Resultsets überlappt, gibt SQLFetch ein partielles Rowset zurück. Wenn S + R - 1 größer als L ist, wobei S die Startzeile des abzurufenden Rowsets ist, ist R die Rowsetgröße und L die letzte Zeile im Resultset, dann sind nur die ersten L - S + 1 Zeilen des Rowsets gültig. Die verbleibenden Zeilen sind leer und weisen einen Status von SQL_ROW_NOROW auf.
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 Beginn | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | Nach Ende |
| Nach Ende | Nach Ende |
[1] Wenn die Zeilensatzgröße zwischen Abrufen geändert wird, ist dies die Zeilensatzgröße, die mit dem vorherigen Abruf verwendet wurde.
[2] Wenn die Zeilensatzgröße zwischen Abrufen geändert wird, ist dies die Zeilensatzgröße, die mit dem neuen Abruf verwendet wurde.
| Notation | Bedeutung |
|---|---|
| Vor Beginn | Der Blockcursor wird vor dem Start des Resultsets positioniert. Wenn die erste Zeile des neuen Rowsets vor dem Start des Resultsets liegt, gibt SQLFetch SQL_NO_DATA zurück. |
| Nach 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 gibt code zurück, der von SQLFetch für unterschiedliche Startpositionen zurückgegeben wird.
| Aktuelles Rowset | Rückgabecode | Neues Rowset | Anzahl der abgerufenen Zeilen |
|---|---|---|---|
| Vor Beginn | 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 werden auf SQL_ROW_NOROW festgelegt. | 3 |
| 96 bis 100 | SQL_NO_DATA | Keine. | 0 |
| 99 bis 100 | SQL_NO_DATA | Keine. | 0 |
| Nach 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 An diese Spalte gebundenen Puffer platziert. 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 Mehrzeiliger ist (d. h. die SQL_ATTR_ROW_ARRAY_SIZE größer als 1 ist), 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 die folgenden Aktionen 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 Ermitteln 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 attribut der SQL_ATTR_MAX_LENGTH-Anweisung 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 Attribut der SQL_ATTR_MAX_LENGTH-Anweisung soll den Netzwerkdatenverkehr reduzieren. Sie wird in der Regel von der Datenquelle implementiert, wodurch die Daten abgeschnitten werden, bevor sie über das Netzwerk zurückgegeben werden. Treiber und Datenquellen sind nicht erforderlich, um sie zu unterstützen. Um sicherzustellen, dass Daten auf eine bestimmte Größe abgeschnitten werden, sollte eine Anwendung einen Puffer dieser Größe zuweisen und die Größe im cbValueMax-Argument in SQLBindCol angeben.
Konvertiert die Daten in den durch TargetType in SQLBindCol angegebenen Typ.
Wenn die Daten in einen Datentyp mit variabler Länge konvertiert wurden, z. B. Zeichen oder Binärdaten, überprüft SQLFetch, ob die Länge der Daten die Länge des Datenpuffers überschreitet. Wenn die Länge von Zeichendaten (einschließlich des Null-Beendigungszeichens) die Länge des Datenpuffers überschreitet, schneidet SQLFetch die Daten auf die Länge des Datenpuffers ab, weniger die Länge eines Null-Beendigungszeichens. Anschließend wird die Daten 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 daten, die in Datentypen mit fester Länge konvertiert wurden, nie ab. Es wird immer davon ausgegangen, dass die Länge des Datenpuffers die Größe des Datentyps ist.
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 auf denselben Puffer (wie ein Aufruf von SQLBindCol ) festgelegt wurden, wird die Länge in den Puffer für gültige Daten geschrieben und SQL_NULL_DATA in den Puffer für NULL-Daten geschrieben. Wenn kein Längen-/Indikatorpuffer gebunden war, 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 ermitteln kann, wie es bei langen Daten der Fall ist, wird die Länge auf SQL_NO_TOTAL festgelegt. Wenn Daten aufgrund des attributs SQL_ATTR_MAX_LENGTH Anweisung abgeschnitten wurden, wird der Wert dieses Attributs im Längen-/Indikatorpuffer anstelle der tatsächlichen Länge platziert. Dies liegt daran, dass dieses Attribut zum Abschneiden von Daten auf dem Server vor der Konvertierung konzipiert ist, sodass der Treiber keine Möglichkeit hat, herauszufinden, was die tatsächliche Länge ist.
Bei allen anderen Datentypen ist dies die Länge der Daten nach der Konvertierung; d. h. die Größe des Typs, in den die Daten konvertiert wurden.
Informationen zum Ermitteln 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 beim Konvertieren auf die ganze Zahl 1 abgeschnitten), gibt SQLFetch SQLSTATE 01S07 (Bruchbruch) und SQL_SUCCESS_WITH_INFO zurück. Wenn die Daten abgeschnitten werden, da die Länge des Datenpuffers zu klein ist (z. B. wird die Zeichenfolge "abcdef" in einen 4-Byte-Puffer gesetzt), gibt SQLFetch SQLSTATE 01004 (Daten abgeschnitten) und SQL_SUCCESS_WITH_INFO zurück. Wenn Daten aufgrund des attributs SQL_ATTR_MAX_LENGTH Anweisung abgeschnitten werden, gibt SQLFetch SQL_SUCCESS zurück und gibt sqlSTATE 01S07 (Bruchbruch) oder SQLSTATE 01004 (Daten abgeschnitten) nicht zurück. Wenn Daten während der Konvertierung mit einem Verlust signifikanter Ziffern abgeschnitten werden (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 (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 der Längen-/Indikatorpuffer 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 attribut der SQL_ATTR_ROW_STATUS_PTR-Anweisung angegeben. Das Array wird von der Anwendung zugewiesen und muss so viele Elemente aufweisen, wie durch das Attribut SQL_ATTR_ROW_ARRAY_SIZE-Anweisung angegeben. 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 attributs der SQL_ATTR_ROW_STATUS_PTR-Anweisung ein Nullzeiger ist, geben diese Funktionen nicht den Zeilenstatus zurück.
Der Inhalt des Zeilenstatusarraypuffers ist nicht definiert, wenn SQLFetch oder SQLFetchScroll SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO nicht 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 Abrufen aus diesem Resultset nicht geändert. |
| SQL_ROW_SUCCESS_WITH_INFO | Die Zeile wurde erfolgreich abgerufen und hat sich seit dem letzten Abrufen aus diesem Resultset nicht geändert. Es wurde jedoch eine Warnung zu der 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 seit dem letzten Abrufen aus diesem Resultset geändert. 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 seit dem letzten Abruf aus diesem Resultset gelöscht. |
| SQL_ROW_ADDED[4] | Die Zeile wurde von SQLBulkOperations eingefügt. Wenn die Zeile erneut aus diesem Resultset abgerufen oder von SQLSetPos aktualisiert wird, wird der 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 entspricht. |
[1] Bei Keyset-, gemischten und dynamischen Cursorn gilt, wenn ein Schlüsselwert aktualisiert wird, die Datenzeile als gelöscht und eine neue Zeile hinzugefügt wurde.
[2] Einige Treiber können Keine Aktualisierungen von Daten erkennen und können daher diesen Wert nicht zurückgeben. Um zu ermitteln, ob ein Treiber Updates für zurückgerufene 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 intermixt wird. Dies liegt daran, dass SQLFetch durch das Resultset vorwärts bewegt wird und wenn es exklusiv verwendet wird, keine Zeilen zurückgibt. Da keine Zeilen erneut zurückgegeben werden, erkennt SQLFetch keine Änderungen, die an zuvor abgerufenen Zeilen vorgenommen wurden. Wenn SQLFetchScroll den Cursor jedoch vor zuvor abgerufenen Zeilen positioniert und SQLFetch zum Abrufen dieser Zeilen verwendet wird, kann SQLFetch alle Änderungen an diesen Zeilen erkennen.
[4] Wird nur von SQLBulkOperations zurückgegeben. Wird nicht von 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, da beim Abrufen ein Fehler aufgetreten ist. Anders ausgedrückt: 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 Attributs der SQL_ATTR_ROWS_FETCHED_PTR-Anweisung ein Nullzeiger ist, geben diese Funktionen nicht die Anzahl der abgerufenen Zeilen zurück. Um die Nummer der aktuellen Zeile im Resultset zu ermitteln, kann eine Anwendung SQLGetStmtAttr mit dem attribut SQL_ATTR_ROW_NUMBER aufrufen.
Der Inhalt des abgerufenen Zeilenpuffers ist nicht definiert, wenn SQLFetch oder SQLFetchScroll nicht SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO zurückgibt, außer wenn SQL_NO_DATA zurückgegeben wird. In diesem Fall wird der Wert im abgerufenen Zeilenpuffer auf 0 festgelegt.
Fehlerbehandlung
Fehler und Warnungen können auf einzelne Zeilen oder auf die gesamte Funktion angewendet werden. Weitere Informationen zu Diagnosedatensätzen finden Sie unter Diagnostics und SQLGetDiagField.
Fehler und Warnungen für die gesamte Funktion
Wenn ein Fehler auf die gesamte Funktion angewendet wird, z. B. SQLSTATE HYT00 (Timeout abgelaufen) oder SQLSTATE 24000 (Ungültiger Cursorstatus), gibt SQLFetch SQL_ERROR und den entsprechenden SQLSTATE-Wert zurück. Der Inhalt der Rowsetpuffer ist nicht definiert, und die Cursorposition bleibt unverändert.
Wenn eine Warnung auf die gesamte Funktion angewendet wird, gibt SQLFetch SQL_SUCCESS_WITH_INFO und den entsprechenden SQLSTATE-Wert zurück. Die Statuseinträge 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 (Daten abgeschnitten)) für eine einzelne Zeile gilt, führt SQLFetchdie folgenden Aktionen aus:
Legt das entsprechende Element des Zeilenstatusarrays für Fehler oder SQL_ROW_SUCCESS_WITH_INFO für Warnungen auf SQL_ROW_ERROR fest.
Fügt null oder mehr Statuseinträge hinzu, die SQLSTATEs für den Fehler oder die Warnung enthalten.
Legt die Zeilen- und Spaltennummernfelder in den Statusdatensätzen fest. Wenn SQLFetch keine Zeilen- oder Spaltennummer bestimmen kann, wird diese Zahl auf SQL_ROW_NUMBER_UNKNOWN oder SQL_COLUMN_NUMBER_UNKNOWN festgelegt. Wenn der Statusdatensatz nicht auf eine bestimmte Spalte angewendet wird, legt SQLFetch die Spaltennummer auf SQL_NO_COLUMN_NUMBER fest.
SQLFetch ruft Zeilen weiter ab, bis alle Zeilen im Rowset abgerufen wurden. Es wird SQL_SUCCESS_WITH_INFO zurückgegeben, es sei denn, in jeder Zeile des Rowsets (nicht einschließlich Zeilen mit Status SQL_ROW_NOROW), in diesem Fall wird SQL_ERROR zurückgegeben. 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 Statuseinträge für die erste Zeile (falls vorhanden) zurückgegeben, und dann werden alle Statusdatensätze für die zweite Zeile (falls vorhanden) usw. zurückgegeben. Die Statusdatensätze für jede Zeile werden gemäß den normalen Regeln für die Sortierung von Statusdatensätzen sortiert; weitere Informationen finden Sie unter "Sequence of Status Records" 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.
Weitere Beschreibungsfelder
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 | attribut "SQL_ATTR_ROW_STATUS_PTR-Anweisung" |
| 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 | Einträge | TargetValuePtr-Argument von SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | Einträge | StrLen_or_IndPtr Argument in SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | Einträge | BufferLength-Argument in SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | Einträge | StrLen_or_IndPtr Argument in SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | header | SQL_ATTR_ROWS_FETCHED_PTR-Anweisungsattribut |
| SQL_DESC_TYPE | ARD | Einträge | 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 Speichern von Längen- und Indikatorwerten verwendet werden können. Wenn eine Anwendung SQLBindCol aufruft, legt der Treiber die felder SQL_DESC_OCTET_LENGTH_PTR und SQL_DESC_INDICATOR_PTR 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 nicht NULL sind, legt SQLFetch in diesem Fall 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
| Weitere Informationen zu | Siehe |
|---|---|
| Binden eines Puffers an eine Spalte in einem Resultset | SQLBindCol-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 |
| Abrufen eines Datenblocks oder Scrollen durch ein Resultset | SQLFetchScroll-Funktion |
| Schließen des Cursors auf der Anweisung | SQLFreeStmt-Funktion |
| Abrufen eines Teils oder aller Datenspalten | SQLGetData-Funktion |
| Zurückgeben der Anzahl von Resultsetspalten | SQLNumResultCols-Funktion |
| Vorbereiten einer Anweisung für die Ausführung | SQLPrepare-Funktion |