SQLMoreResults-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ODBC

Zusammenfassung
SQLMoreResults bestimmt, ob weitere Ergebnisse für eine Anweisung verfügbar sind, die SELECT-, UPDATE-, INSERT- oder DELETE-Anweisungen enthält und wenn ja, die Verarbeitung für diese Ergebnisse initialisiert.

Syntax

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);  

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_PARAM_DATA_AVAILABLE.

Diagnose

Wenn SQLMoreResults SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec 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 häufig von SQLMoreResults zurückgegeben werden und die einzelnen werte im Kontext dieser Funktion erläutert werden; 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.

SQLSTATE Fehler Beschreibung
01000 Allgemeine Warnung Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01S02 Optionswert wurde geändert Der Wert eines Anweisungsattributes wurde geändert, da der Batch verarbeitet wurde. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
08S01 Kommunikationslinkfehler Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, konnte nicht ausgeführt werden, bevor die Verarbeitung der Funktion abgeschlossen wurde.
40001 Serialisierungsfehler Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt.
40003 Abschluss der Anweisung unbekannt Die zugeordnete Verbindung ist während der Ausführung dieser Funktion fehlgeschlagen, und der Status der Transaktion kann nicht bestimmt werden.
HY000 Allgemeiner Fehler Fehler, für den keine spezifische SQLSTATE vorhanden war und für die keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache.
HY001 Fehler bei der Speicherzuweisung Der Treiber konnte den 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 das StatementHandle aktiviert. Die SQLMoreResults-Funktion wurde aufgerufen, und, bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle aufgerufen. Anschließend wurde die SQLMoreResults-Funktion erneut im StatementHandle aufgerufen.

Die SQLMoreResults-Funktion wurde aufgerufen und, bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandlevon einem anderen Thread in einer Multithreadanwendung aufgerufen.
HY010 Funktionssequenzfehler (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungspunkt aufgerufen, der dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, wenn die SQLMoreResults-Funktion aufgerufen wurde.

(DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das StatementHandle aufgerufen und wurde noch ausgeführt, wenn diese Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für das 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.
HY013 Speicherverwaltungsfehler Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund niedriger Speicherbedingungen.
HY117 Die Verbindung wird aufgrund des unbekannten Transaktionszustands angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function.
HYT01 Verbindungstimeout abgelaufen Der Zeitüberschreitungszeitraum für die Verbindung ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitüberschreitungszeitraum für die Verbindung wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Treiber unterstützt diese Funktion nicht (DM) Der dem 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 auf diesem Handle abzuschließen. Wenn der vorherige Funktionsaufruf des Handles SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync auf dem Handle aufgerufen werden, um nach der Verarbeitung zu arbeiten und den Vorgang abzuschließen.

Kommentare

SELECT-Anweisungen geben Ergebnissätze zurück. UPDATE-, INSERT- und DELETE-Anweisungen geben eine Anzahl betroffener Zeilen zurück. Wenn eine dieser Anweisungen batchiert ist, mit Arrays von Parametern (in erhöhter Parameterreihenfolge nummeriert), in der Reihenfolge, in der sie im Batch angezeigt werden, oder in Prozeduren können mehrere Ergebnissätze oder Zeilenanzahlen zurückgegeben werden. Informationen zu Batches von Anweisungen und Arrays von Parametern finden Sie unter Batches von SQL Anweisungen und Arrays von Parameterwerten.

Nach dem Ausführen des Batches wird die Anwendung im ersten Resultset positioniert. Die Anwendung kann SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos und alle Metadatenfunktionen auf dem ersten oder allen nachfolgenden Resultsets aufrufen, genau wie bei einem einzigen Resultset. Sobald sie mit dem ersten Resultset abgeschlossen ist, ruft die Anwendung SQLMoreResults auf, um zum nächsten Resultset zu wechseln. Wenn ein anderer Ergebnissatz oder eine andere Anzahl verfügbar ist, gibt SQLMoreResults SQL_SUCCESS zurück und initialisiert den Resultset oder die Anzahl für zusätzliche Verarbeitung. Wenn zeilenzählungsgenerierte Anweisungen zwischen Ergebnissatz-Generieren-Anweisungen angezeigt werden, können sie durch Aufrufen von SQLMoreResults übersprungen werden. Nach dem Aufrufen von SQLMoreResults für UPDATE-, INSERT- oder DELETE-Anweisungen kann eine Anwendung SQLRowCount aufrufen.

Wenn ein aktueller Resultset mit nicht ausgeführten Zeilen vorhanden ist, verwirft SQLMoreResults diesen Resultset und stellt die nächste Ergebnismenge oder Anzahl zur Verfügung. Wenn alle Ergebnisse verarbeitet wurden, gibt SQLMoreResults SQL_NO_DATA zurück. Bei einigen Treibern sind Ausgabeparameter und Rückgabewerte erst verfügbar, wenn alle Ergebnissätze und Zeilenanzahlen verarbeitet wurden. Für solche Treiber werden Ausgabeparameter und Rückgabewerte verfügbar, wenn SQLMoreResults SQL_NO_DATA zurückgibt.

Alle Bindungen, die für den vorherigen Resultset eingerichtet wurden, bleiben weiterhin gültig. Wenn sich die Spaltenstrukturen für diesen Resultset unterscheiden, kann das Aufrufen von SQLFetch oder SQLFetchScroll zu einem Fehler oder einer Abkürzung führen. Um dies zu verhindern, muss die Anwendung SQLBindCol aufrufen, um es entsprechend explizit neu zu binden (oder dies durch Festlegen von Deskriptorfeldern). Alternativ kann die Anwendung SQLFreeStmt mit einer Option von SQL_UNBIND aufrufen, um alle Spaltenpuffer zu aufheben.

Die Werte von Anweisungsattributen, z. B. Cursortyp, Cursorkoncurrität, Keysetgröße oder maximale Länge, können sich ändern, wenn die Anwendung durch den Batch navigiert, indem Aufrufe von SQLMoreResults aufgerufen werden. Wenn dies der Fall ist, gibt SQLMoreResults SQL_SUCCESS_WITH_INFO und SQLSTATE 01S02 zurück (Option value has changed).

Das Aufrufen von SQLCloseCursor oder SQLFreeStmt mit einer Option von SQL_CLOSE verwirft alle Ergebnissätze und Zeilenanzahlen, die aufgrund der Ausführung des Batches verfügbar waren. Der Anweisungshandpunkt wird entweder an den zugewiesenen oder vorbereiteten Zustand zurückgegeben. Das Aufrufen von SQLCancel zum Abbrechen einer asynchron ausgeführten Funktion, wenn ein Batch ausgeführt wurde, und der Anweisungshandpunkt befindet sich im ausgeführten, cursorpositionierten oder asynchronen Zustand, führt zu allen Resultsets und Zeilenanzahlen, die vom Stapel verworfen werden, wenn der Abbrechenaufruf erfolgreich war. Die Anweisung gibt dann an den vorbereiteten oder zugewiesenen Zustand zurück.

Wenn ein Batch von Anweisungen oder eine Prozedur andere SQL Anweisungen mit SELECT, UPDATE, INSERT und DELETE-Anweisungen kombiniert, wirken sich diese anderen Anweisungen nicht auf SQLMoreResults aus.

Weitere Informationen finden Sie unter "Mehrere Ergebnisse".

Wenn ein durchsuchtes Update, Einfügen oder Löschen in einem Batch von Anweisungen keine Zeilen in der Datenquelle beeinflusst, gibt SQLMoreResults SQL_SUCCESS zurück. Dies unterscheidet sich von dem Fall eines durchsuchten Updates, Einfügens oder Löschens, die über SQLExecDirect, SQLExecute oder SQLParamData ausgeführt wird, die SQL_NO_DATA zurückgibt, wenn keine Zeilen an der Datenquelle betroffen sind. Wenn eine Anwendung SQLRowCount aufruft, um die Zeilenanzahl abzurufen, nachdem ein Aufruf von SQLMoreResults keine Zeilen betroffen hat, gibt SQLRowCount SQL_NO_DATA zurück.

Weitere Informationen zur gültigen Sequenzierung von Ergebnisverarbeitungsfunktionen finden Sie in Anhang B: ODBC-Statusübergangstabellen.

Weitere Informationen zu SQL_PARAM_DATA_AVAILABLE und streamenden Ausgabeparametern finden Sie unter Abrufen von Ausgabeparametern mithilfe von SQLGetData.

Verfügbarkeit von Zeilenanzahlen

Wenn ein Batch mehrere fortlaufende Zeilenanzahlsanweisungen enthält, ist es möglich, dass diese Zeilenanzahl in nur eine Zeilenanzahl gerollt wird. Wenn beispielsweise ein Batch fünf Insert-Anweisungen enthält, können bestimmte Datenquellen fünf einzelne Zeilenanzahlen zurückgeben. Bestimmte andere Datenquellen geben nur eine Zeilenanzahl zurück, die die Summe der fünf einzelnen Zeilenanzahl darstellt.

Wenn ein Batch eine Kombination aus Ergebnissatz generierenden und Zeilenanzahlsanweisungen enthält, können Zeilenanzahlen möglicherweise oder nicht überhaupt verfügbar sein. Das Verhalten des Treibers im Hinblick auf die Verfügbarkeit von Zeilenanzahlen wird im SQL_BATCH_ROW_COUNT Informationstyp aufgezählt, der über einen Aufruf von SQLGetInfo verfügbar ist. Angenommen, der Batch enthält eine SELECT, gefolgt von zwei INSERTs und einer anderen SELECT. Dann sind die folgenden Fälle möglich:

  • Die Zeile zählt, die den beiden INSERT-Anweisungen entspricht, ist überhaupt nicht verfügbar. Der erste Aufruf von SQLMoreResults positioniert Sie auf dem Ergebnissatz der zweiten SELECT-Anweisung .

  • Die Zeile zählt, die den beiden INSERT-Anweisungen entspricht, sind einzeln verfügbar. (Ein Aufruf von SQLGetInfo gibt das SQL_BRC_ROLLED_UP Bit für den SQL_BATCH_ROW_COUNT Informationstyp nicht zurück.) Der erste Aufruf von SQLMoreResults positioniert Sie in der Zeilenanzahl der ersten INSERT, und der zweite Aufruf positioniert Sie auf der Zeilenanzahl des zweiten INSERT. Der dritte Aufruf von SQLMoreResults positioniert Sie auf dem Ergebnissatz der zweiten SELECT-Anweisung .

  • Die Zeile zählt, die den beiden INSERTs entspricht, wird in eine einzelne Zeilenanzahl gerollt, die verfügbar ist. (Ein Aufruf von SQLGetInfo gibt das SQL_BRC_ROLLED_UP Bit für den SQL_BATCH_ROW_COUNT Informationstyp zurück.) Der erste Aufruf von SQLMoreResults positioniert Sie auf der Rollupzeilenanzahl, und der zweite Aufruf von SQLMoreResults positioniert Sie auf dem Ergebnissatz der zweiten SELECT.

Bestimmte Treiber stellen Zeilenanzahl nur für explizite Batches und nicht für gespeicherte Prozeduren zur Verfügung.

Informationen über Finden Sie unter
Abbrechen der Anweisungsverarbeitung SQLCancel-Funktion
Abrufen eines Datenblocks oder Scrollen durch einen Ergebnissatz SQLFetchScroll-Funktion
Abrufen einer einzelnen Zeile oder eines Datenblocks in einer vorwärtsgeschützten Richtung SQLFetch-Funktion
Abrufen eines Teils oder aller Datenspalten SQLGetData-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien
Abrufen von Ausgabeparametern mithilfe von SQLGetData