sqlsrv_fetch — Funktion · PHP-Referenz

Signatur

sqlsrv_fetch(resource $stmt, int $scrollType = SQLSRV_SCROLL_NEXT, int $offset = 0): bool|null

Beschreibung

sqlsrv_fetch() bewegt den internen Zeiger eines Ergebnis-Cursors auf die nächste (oder eine explizit angegebene) Zeile und gibt true zurück, wenn die Zeile erfolgreich geladen wurde. Die eigentlichen Spaltenwerte werden anschließend mit sqlsrv_get_field() einzeln abgerufen. Diese Kombination eignet sich besonders, wenn nur bestimmte Spalten einer Zeile benötigt werden oder der Speicherverbrauch minimiert werden soll.

Im Gegensatz zu sqlsrv_fetch_array() oder sqlsrv_fetch_object() liefert sqlsrv_fetch() selbst keine Daten zurück – es bereitet lediglich die aktuelle Zeile vor. Das macht es flexibel, wenn man mit großen Ergebnismengen arbeitet und nur einzelne Felder benötigt.

Der Parameter $scrollType steuert, wie der Cursor verschoben wird. Standardmäßig wird SQLSRV_SCROLL_NEXT verwendet (vorwärts), weitere Optionen wie SQLSRV_SCROLL_PRIOR, SQLSRV_SCROLL_FIRST, SQLSRV_SCROLL_LAST, SQLSRV_SCROLL_ABSOLUTE oder SQLSRV_SCROLL_RELATIVE ermöglichen Navigation in scrollbaren Cursorn.

Gibt null zurück, wenn keine weiteren Zeilen vorhanden sind, und false im Fehlerfall. Dieser Rückgabewert muss daher mit striktem Vergleich (=== false oder === null) geprüft werden.

Parameter

Name	Typ	Default	Beschreibung
$stmt Pflicht	resource		Eine gültige Statement-Ressource, die durch `sqlsrv_query()` oder `sqlsrv_execute()` erzeugt wurde.
$scrollType	int	SQLSRV_SCROLL_NEXT	Gibt an, wie der Cursor verschoben werden soll. Mögliche Werte: `SQLSRV_SCROLL_NEXT`, `SQLSRV_SCROLL_PRIOR`, `SQLSRV_SCROLL_FIRST`, `SQLSRV_SCROLL_LAST`, `SQLSRV_SCROLL_ABSOLUTE`, `SQLSRV_SCROLL_RELATIVE`. Erfordert einen scrollbaren Cursor (bei der Statement-Erstellung mit `array('Scrollable' => 'buffered')` o. ä. angegeben).
$offset	int	0	Zeilenversatz für `SQLSRV_SCROLL_ABSOLUTE` und `SQLSRV_SCROLL_RELATIVE`. Wird bei anderen Scroll-Typen ignoriert.

Rückgabewert

Typ

bool|null

Beschreibung

Gibt true zurück, wenn die Zeile erfolgreich zum Lesen bereit gestellt wurde. Gibt null zurück, wenn keine weiteren Zeilen im Ergebnissatz vorhanden sind. Gibt false zurück, wenn ein Fehler aufgetreten ist.

Beispiele

Zeilenweise Verarbeitung mit sqlsrv_get_field

<?php
$serverName = 'localhost';
$connectionInfo = ['Database' => 'TestDB', 'UID' => 'sa', 'PWD' => 'geheim'];
$conn = sqlsrv_connect($serverName, $connectionInfo);

if ($conn === false) {
    die(print_r(sqlsrv_errors(), true));
}

$sql  = "SELECT id, name, email FROM users";
$stmt = sqlsrv_query($conn, $sql);

if ($stmt === false) {
    die(print_r(sqlsrv_errors(), true));
}

while (sqlsrv_fetch($stmt) === true) {
    $id    = sqlsrv_get_field($stmt, 0); // Spalte 0: id
    $name  = sqlsrv_get_field($stmt, 1); // Spalte 1: name
    $email = sqlsrv_get_field($stmt, 2); // Spalte 2: email
    echo "ID: $id | Name: $name | E-Mail: $email\n";
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

ID: 1 | Name: Max Mustermann | E-Mail: max@example.com ID: 2 | Name: Erika Muster | E-Mail: erika@example.com

Scrollbarer Cursor: erste und letzte Zeile abrufen

<?php
$serverName = 'localhost';
$connectionInfo = ['Database' => 'TestDB', 'UID' => 'sa', 'PWD' => 'geheim'];
$conn = sqlsrv_connect($serverName, $connectionInfo);

$sql     = "SELECT id, name FROM products ORDER BY id";
$options = ['Scrollable' => SQLSRV_CURSOR_STATIC];
$stmt    = sqlsrv_query($conn, $sql, [], $options);

if ($stmt === false) {
    die(print_r(sqlsrv_errors(), true));
}

// Erste Zeile
sqlsrv_fetch($stmt, SQLSRV_SCROLL_FIRST);
$firstName = sqlsrv_get_field($stmt, 1);
echo "Erster Eintrag: $firstName\n";

// Letzte Zeile
sqlsrv_fetch($stmt, SQLSRV_SCROLL_LAST);
$lastName = sqlsrv_get_field($stmt, 1);
echo "Letzter Eintrag: $lastName\n";

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

Erster Eintrag: Produkt A Letzter Eintrag: Produkt Z

// Wichtig · Fallstricke

Rückgabewert prüfen: Da sqlsrv_fetch() sowohl false (Fehler) als auch null (kein weiterer Datensatz) zurückgeben kann, muss strikter Vergleich mit === false verwendet werden, um Fehler von einem normalen Schleifenende zu unterscheiden. Eine einfache while (sqlsrv_fetch($stmt))-Schleife bricht sowohl bei false als auch bei null ab.

Scrollbare Cursor: Navigation mit anderen Scroll-Typen als SQLSRV_SCROLL_NEXT erfordert, dass das Statement mit einem explizit scrollbaren Cursor (SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC oder SQLSRV_CURSOR_KEYSET) erstellt wurde, da Vorwärts-Cursor (SQLSRV_CURSOR_FORWARD) keine Rückwärtsnavigation unterstützen.

Speicherprofil: sqlsrv_fetch() in Kombination mit sqlsrv_get_field() kann für sehr große Ergebnismengen speichereffizienter sein als sqlsrv_fetch_array(), da nicht alle Spaltenwerte sofort in ein Array kopiert werden.

Siehe auch

sqlsrv_get_field sqlsrv_fetch_array sqlsrv_fetch_object sqlsrv_query sqlsrv_free_stmt sqlsrv_errors