Freigeben über

SQLMoreResults-Funktion

  • Artikel

Konformität
Version eingeführt: ODBC 1.0-Standardkonformität: 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, initialisiert die Verarbeitung für diese Ergebnisse.

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, OR SQL_PARAM_DATA_AVAILABLE.

Diagnose

Wenn SQLMoreResults SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle von StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLMoreResults zurückgegeben werden, und die einzelnen Werte werden 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.

SQLSTATE Fehler BESCHREIBUNG
01000 Allgemeine Warnung Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01S02 Der Optionswert wurde geändert. Der Wert eines Anweisungsattributs wurde während der Verarbeitung des Batches geändert. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
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.
40001 Serialisierungsfehler Für die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion ein Rollback ausgeführt.
40003 Anweisungsabschluss 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 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 seine Ursache.
HY001 Fehler bei der Speicherbelegung Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist.
HY008 Vorgang abgebrochen Die asynchrone Verarbeitung wurde für statementHandle aktiviert. Die SQLMoreResults-Funktion wurde aufgerufen, und vor Abschluss der Ausführung wurde SQLCancel oder SQLCancelHandle für die StatementHandle aufgerufen. Anschließend wurde die SQLMoreResults-Funktion für den StatementHandle erneut aufgerufen.

Die SQLMoreResults-Funktion wurde aufgerufen, und vor Abschluss der Ausführung wurde SQLCancel oder SQLCancelHandle für statementHandle aus 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 FUNKTION SQLMoreResults aufgerufen wurde.

(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 der Ausführungsparameter oder -spalten gesendet wurden.
HY013 Fehler bei der Speicherverwaltung Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen.
HY117 Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Treiber unterstützt diese Funktion nicht. (DM) Der Der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht.
IM017 Abruf ist im asynchronen Benachrichtigungsmodus deaktiviert. Wenn das Benachrichtigungsmodell verwendet wird, wird 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

SELECT-Anweisungen geben Resultsets zurück. UPDATE-, INSERT- und DELETE-Anweisungen geben die Anzahl der betroffenen Zeilen zurück. Wenn eine dieser Anweisungen in einer Batchverarbeitung, mit Arrays von Parametern (in zunehmender Parameterreihenfolge nummeriert, in der Reihenfolge, in der sie im Batch angezeigt werden) oder in Prozeduren übermittelt wird, können sie mehrere Resultsets oder Zeilenanzahlen zurückgeben. 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 für das erste oder alle nachfolgenden Resultsets aufrufen, genau wie bei einem einzelnen Resultset. Sobald dies mit dem ersten Resultset abgeschlossen ist, ruft die Anwendung SQLMoreResults auf, um zum nächsten Resultset zu wechseln. Wenn ein anderes Resultset oder eine andere Anzahl verfügbar ist, gibt SQLMoreResults SQL_SUCCESS zurück und initialisiert das Resultset oder die Anzahl für die zusätzliche Verarbeitung. Wenn zeilenzählungsgenerierende Anweisungen zwischen Resultset-generierenden Anweisungen angezeigt werden, können sie durch Aufrufen von SQLMoreResults übersprungen werden. Nach dem Aufruf von SQLMoreResults für UPDATE-, INSERT- oder DELETE-Anweisungen kann eine Anwendung SQLRowCount aufrufen.

Wenn ein aktuelles Resultset mit nicht abgerufenen Zeilen vorhanden ist, verwirft SQLMoreResults dieses Resultset und stellt das nächste Resultset oder die nächste 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 Resultsets und Zeilenzählungen 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 das vorherige Resultset eingerichtet wurden, bleiben weiterhin gültig. Wenn die Spaltenstrukturen für dieses Resultset unterschiedlich sind, kann der Aufruf von SQLFetch oder SQLFetchScroll zu einem Fehler oder einer Kürzung führen. Um dies zu verhindern, muss die Anwendung SQLBindCol aufrufen, um die Bindungen explizit nach Bedarf neu zu binden (oder dies durch Festlegen von Deskriptorfeldern). Alternativ kann die Anwendung SQLFreeStmt mit einer Option der SQL_UNBIND aufrufen, um die Bindung aller Spaltenpuffer aufzuheben.

Die Werte von Anweisungsattributen, z. B. Cursortyp, Cursorparallelität, Keysetgröße oder maximale Länge, können sich ändern, wenn die Anwendung durch Aufrufe von SQLMoreResults durch den Batch navigiert. In diesem Fall gibt SQLMoreResults SQL_SUCCESS_WITH_INFO und SQLSTATE 01S02 zurück (Der Optionswert wurde geändert).

Beim Aufrufen von SQLCloseCursor oder SQLFreeStmt mit einer Option von SQL_CLOSE werden alle Resultsets und Zeilenanzahlen verworfen, die als Ergebnis der Ausführung des Batches verfügbar waren. Das Anweisungshandle kehrt in den zugeordneten oder vorbereiteten Zustand zurück. Das Aufrufen von SQLCancel zum Abbrechen einer asynchron ausgeführten Funktion, wenn ein Batch ausgeführt wurde und sich das Anweisungshandle im ausgeführten, cursorpositionierten oder asynchronen Zustand befindet, führt dazu, dass alle Vom Batch generierten Resultsets und Zeilenanzahlen verworfen werden, wenn der Abbruchaufruf erfolgreich war. Die Anweisung kehrt dann in den vorbereiteten oder zugeordneten 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 eine durchsuchte Update-, Insert- oder Delete-Anweisung in einem Batch von Anweisungen keine Zeilen an der Datenquelle beeinflusst, gibt SQLMoreResults SQL_SUCCESS zurück. Dies unterscheidet sich vom Fall einer durchsuchten Update-, Insert- oder Delete-Anweisung, die über SQLExecDirect, SQLExecute oder SQLParamData ausgeführt wird, die SQL_NO_DATA zurückgibt, wenn sie sich nicht auf Zeilen an der Datenquelle auswirkt. Wenn eine Anwendung SQLRowCount aufruft, um die Zeilenanzahl abzurufen, nachdem ein Aufruf von SQLMoreResults keine Zeilen beeinflusst hat, gibt SQLRowCount SQL_NO_DATA zurück.

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

Weitere Informationen zum SQL_PARAM_DATA_AVAILABLE und gestreamten Ausgabeparametern finden Sie unter Abrufen von Ausgabeparametern mithilfe von SQLGetData.

Verfügbarkeit von Zeilenanzahlen

Wenn ein Batch mehrere aufeinanderfolgende Zeilenanzahl generierende Anweisungen enthält, ist es möglich, dass diese Zeilenanzahlen in nur eine Zeilenanzahl zusammengefasst werden. Wenn ein Batch beispielsweise über fünf Insert-Anweisungen verfügt, 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 Zeilenanzahlen darstellt.

Wenn ein Batch eine Kombination aus Resultset-generierenden und Zeilenanzahl generierenden Anweisungen enthält, sind zeilenanzahlen möglicherweise überhaupt nicht verfügbar. Das Verhalten des Treibers in Bezug auf die Verfügbarkeit von Zeilenzählungen wird im SQL_BATCH_ROW_COUNT Informationstyps aufgelistet, der über einen Aufruf von SQLGetInfo verfügbar ist. Angenommen, der Batch enthält ein SELECT, gefolgt von zwei INSERTs und einem weiteren SELECT. Dann sind die folgenden Fälle möglich:

  • Die Zeilenanzahl, die den beiden INSERT-Anweisungen entspricht, ist überhaupt nicht verfügbar. Beim ersten Aufruf von SQLMoreResults werden Sie im Resultset der zweiten SELECT-Anweisung positioniert.

  • Die Zeilenanzahlen, die den beiden INSERT-Anweisungen entsprechen, sind einzeln verfügbar. (Ein Aufruf von SQLGetInfo gibt nicht das SQL_BRC_ROLLED_UP Bit für den SQL_BATCH_ROW_COUNT Informationstyp zurück.) Beim ersten Aufruf von SQLMoreResults werden Sie nach der Zeilenanzahl des ersten INSERT positioniert, und der zweite Aufruf positioniert Sie auf der Zeilenanzahl der zweiten INSERT. Beim dritten Aufruf von SQLMoreResults werden Sie im Resultset der zweiten SELECT-Anweisung positioniert.

  • Die Zeilenanzahlen, die den beiden INSERTs entsprechen, werden in eine einzelne Zeilenanzahl zusammengefasst, 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.) Beim ersten Aufruf von SQLMoreResults werden Sie mit der Rollupzeilenanzahl positioniert, und beim zweiten Aufruf von SQLMoreResults werden Sie im Resultset des zweiten SELECT positioniert.

Bestimmte Treiber stellen Zeilenanzahlen 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 ein Resultset SQLFetchScroll-Funktion
Abrufen einer einzelnen Zeile oder eines Datenblocks in einer vorwärtsgerichteten Richtung SQLFetch-Funktion
Abrufen eines Teils oder des Gesamten einer Datenspalte SQLGetData-Funktion

Weitere Informationen

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