Signatur
Beschreibung
sqlsrv_cancel bricht die Ausführung eines SQLSRV-Statements ab und verwirft alle noch nicht abgerufenen Ergebniszeilen. Die Funktion ist besonders dann nützlich, wenn man nach dem Abrufen einer Teilmenge von Ergebnissen keine weiteren Zeilen mehr benötigt und Netzwerk- sowie Serverressourcen freigeben möchte, ohne das Statement vollständig zu schließen.
Im Gegensatz zu sqlsrv_free_stmt wird das Statement-Handle nach sqlsrv_cancel nicht ungültig. Es kann anschließend erneut mit sqlsrv_execute ausgeführt werden. Dies ist ein wesentlicher Unterschied: das Handle bleibt wiederverwendbar, lediglich die laufenden Ergebnisse werden verworfen.
Typische Anwendungsfälle sind: vorzeitiges Verlassen einer Ergebnis-Schleife nach Auffinden eines gesuchten Datensatzes, Abbruch bei Auftreten eines Fehlers in der Verarbeitungslogik oder einfach Ressourcenschonung bei großen Ergebnismengen, von denen nur ein Teil benötigt wird.
- Die Funktion wirkt nur auf Statements, die noch offene, nicht vollständig konsumierte Ergebnismengen besitzen.
- Nach
sqlsrv_cancelist das Handle für einen neuensqlsrv_execute-Aufruf bereit.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $stmt Pflicht | resource | Ein gültiges SQLSRV-Statement-Handle, das zuvor mit sqlsrv_query oder sqlsrv_prepare/sqlsrv_execute erstellt wurde. |
Rückgabewert
true zurück, wenn das Statement erfolgreich abgebrochen wurde. Gibt false zurück, wenn ein Fehler aufgetreten ist, z. B. wenn das Statement-Handle ungültig ist.Beispiele
Vorzeitiger Abbruch einer Ergebnis-Schleife
<?php
$serverName = 'localhost';
$connectionInfo = ['Database' => 'TestDB', 'UID' => 'sa', 'PWD' => 'geheim'];
$conn = sqlsrv_connect($serverName, $connectionInfo);
if (!$conn) {
die('Verbindung fehlgeschlagen: ' . print_r(sqlsrv_errors(), true));
}
$sql = 'SELECT id, name FROM produkte ORDER BY id';
$stmt = sqlsrv_query($conn, $sql);
if (!$stmt) {
die('Abfrage fehlgeschlagen: ' . print_r(sqlsrv_errors(), true));
}
// Nur den ersten passenden Datensatz verarbeiten
while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) {
echo 'Gefunden: ' . $row['name'] . PHP_EOL;
if ($row['id'] === 5) {
// Keine weiteren Zeilen abrufen — Statement abbrechen
sqlsrv_cancel($stmt);
break;
}
}
// Handle ist weiterhin gültig und kann erneut genutzt werden
sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);
?>Statement nach Abbruch erneut ausführen
<?php
$serverName = 'localhost';
$connectionInfo = ['Database' => 'TestDB', 'UID' => 'sa', 'PWD' => 'geheim'];
$conn = sqlsrv_connect($serverName, $connectionInfo);
$sql = 'SELECT TOP 100 id FROM bestellungen WHERE status = ?';
$params = ['offen'];
$stmt = sqlsrv_prepare($conn, $sql, $params);
sqlsrv_execute($stmt);
// Nur erste Zeile lesen, Rest abbrechen
$ersteZeile = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
echo 'Erste offene Bestellung: ' . $ersteZeile['id'] . PHP_EOL;
// Ausstehende Ergebnisse verwerfen
sqlsrv_cancel($stmt);
// Statement mit anderem Parameter wiederverwenden
$params = ['abgeschlossen'];
sqlsrv_execute($stmt);
$ersteAbgeschlossene = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
echo 'Erste abgeschlossene Bestellung: ' . $ersteAbgeschlossene['id'] . PHP_EOL;
sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);
?>// Wichtig · Fallstricke
Ressourcenmanagement: sqlsrv_cancel gibt lediglich die ausstehenden Ergebniszeilen auf Serverseite frei, schließt aber weder das Statement-Handle noch die Verbindung. Für eine vollständige Freigabe des Handles muss anschließend sqlsrv_free_stmt aufgerufen werden.
Kein Effekt bei vollständig konsumierten Ergebnissen: Wurden bereits alle Ergebniszeilen abgerufen, hat sqlsrv_cancel keinen nennenswerten Effekt, gibt aber dennoch true zurück.
Nicht für Transaktionen: sqlsrv_cancel betrifft ausschließlich das Statement und nicht laufende Datenbanktransaktionen. Zum Abbrechen von Transaktionen muss sqlsrv_rollback verwendet werden.