SQLRowCount-Funktion
Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92
Zusammenfassung
SQLRowCount gibt die Anzahl der Zeilen zurück, die von einer UPDATE-, INSERT- oder DELETE-Anweisung betroffen sind; ein SQL_ADD-, SQL_UPDATE_BY_BOOKMARK- oder SQL_DELETE_BY_BOOKMARK-Vorgang in SQLBulkOperations; oder ein SQL_UPDATE- oder SQL_DELETE-Vorgang in SQLSetPos.
Syntax
SQLRETURN SQLRowCount(
SQLHSTMT StatementHandle,
SQLLEN * RowCountPtr);
Argumente
StatementHandle
[Eingabe] Anweisungshandle.
RowCountPtr
[Ausgabe] Verweist auf einen Puffer, in dem eine Zeilenanzahl zurückgegeben werden soll. Für UPDATE-, INSERT- und DELETE-Anweisungen für die Vorgänge SQL_ADD, SQL_UPDATE_BY_BOOKMARK und SQL_DELETE_BY_BOOKMARK in SQLBulkOperations sowie für die SQL_UPDATE- oder SQL_DELETE Vorgänge in SQLSetPos ist der in *RowCountPtr zurückgegebene Wert entweder die Anzahl der Zeilen, die von der Anforderung betroffen sind, oder -1, wenn die Anzahl der betroffenen Zeilen nicht verfügbar ist.
Wenn SQLExecute, SQLExecDirect, SQLBulkOperations, SQLSetPos oder SQLMoreResults aufgerufen wird, wird das SQL_DIAG_ROW_COUNT Feld der Diagnosedatenstruktur auf die Zeilenanzahl festgelegt, und die Zeilenanzahl wird auf implementierungsabhängige Weise zwischengespeichert. SQLRowCount gibt den Wert der zwischengespeicherten Zeilenanzahl zurück. Der Wert für die Anzahl zwischengespeicherter Zeilen ist gültig, bis der Anweisungshandle auf den vorbereiteten oder zugewiesenen Zustand zurückgesetzt wird, die Anweisung erneut ausgeführt wird oder SQLCloseCursor aufgerufen wird. Wenn eine Funktion seit dem Festlegen des felds SQL_DIAG_ROW_COUNT aufgerufen wurde, unterscheidet sich der von SQLRowCount zurückgegebene Wert möglicherweise vom Wert im feld SQL_DIAG_ROW_COUNT, da das feld SQL_DIAG_ROW_COUNT durch einen Funktionsaufruf auf 0 zurückgesetzt wird.
Bei anderen Anweisungen und Funktionen kann der Treiber den in *RowCountPtr zurückgegebenen Wert definieren. Beispielsweise können einige Datenquellen möglicherweise die Anzahl der Zeilen zurückgeben, die von einer SELECT-Anweisung oder einer Katalogfunktion zurückgegeben werden, bevor die Zeilen abgerufen werden.
Hinweis
Viele Datenquellen können die Anzahl der Zeilen in einem Resultset nicht zurückgeben, bevor sie abgerufen werden. Für maximale Interoperabilität sollten Anwendungen nicht auf dieses Verhalten angewiesen sein.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnostik
Wenn SQLRowCount 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 SQLRowCount 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.
| SQLSTATE | Error | Beschreibung |
|---|---|---|
| 01000 | Allgemeiner Warnhinweis | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 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 speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen. |
| 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 SQLRowCount-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 Funktion wurde vor dem Aufrufen von SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos für die StatementHandle aufgerufen. (DM) Eine asynchron ausgeführte Funktion wurde für " 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. |
| HY013 | Speicherverwaltungsfehler | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen. |
| 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. |
| 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
Wenn die letzte SQL-Anweisung, die auf dem Anweisungshandle ausgeführt wurde, keine UPDATE-, INSERT- oder DELETE-Anweisung war oder das Argument Operation im vorherigen Aufruf von SQLBulkOperations nicht SQL_ADD, SQL_UPDATE_BY_BOOKMARK oder SQL_DELETE_BY_BOOKMARK war oder das Argument Operation im vorherigen Aufruf von SQLSetPos nicht SQL_UPDATE oder SQL_DELETE war, der Wert von *RowCountPtr ist treiberdefiniert. Weitere Informationen finden Sie unter Ermitteln der Anzahl betroffener Zeilen.
Verwandte Funktionen
| Weitere Informationen zu | Siehe |
|---|---|
| Ausführen einer SQL-Anweisung | SQLExecDirect-Funktion |
| Ausführen einer vorbereiteten SQL-Anweisung | SQLExecute-Funktion |