Signatur
Beschreibung
cubrid_move_cursor() verschiebt den internen Cursor eines CUBRID-Ergebnis-Handles um $offset Zeilen relativ zur durch $origin angegebenen Ausgangsposition. Damit kann gezielt auf bestimmte Datensätze in einem Ergebnis zugegriffen werden, ohne alle vorherigen Zeilen sequenziell durchlaufen zu müssen.
Der Parameter $origin akzeptiert eine der drei Konstanten CUBRID_CURSOR_FIRST (Anfang des Ergebnisses), CUBRID_CURSOR_CURRENT (aktuelle Position) und CUBRID_CURSOR_LAST (Ende des Ergebnisses). Mit negativen Offset-Werten lässt sich der Cursor auch rückwärts bewegen.
Die Funktion ist besonders nützlich, wenn große Ergebnismengen seitenweise verarbeitet werden sollen oder wenn direkt auf einen bestimmten Datensatz zugegriffen werden muss, ohne das gesamte Ergebnis in den Speicher zu laden. Nach dem Positionieren des Cursors können Zeilen mit Funktionen wie cubrid_fetch() abgerufen werden.
Wird ein ungültiger Offset angegeben (z. B. über das Ende des Ergebnisses hinaus), gibt die Funktion false zurück. Eine erfolgreiche Cursorbewegung liefert true.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $req_identifier Pflicht | resource | Das Anfrage-Handle (Request-Identifier), das von Funktionen wie cubrid_execute() oder cubrid_query() zurückgegeben wurde. |
|
| $offset Pflicht | int | Anzahl der Zeilen, um die der Cursor verschoben werden soll. Positive Werte bewegen den Cursor vorwärts, negative Werte rückwärts. | |
| $origin | int | CUBRID_CURSOR_CURRENT | Ausgangspunkt für die Cursorbewegung. Mögliche Werte: CUBRID_CURSOR_FIRST (Anfang), CUBRID_CURSOR_CURRENT (aktuelle Position, Standard), CUBRID_CURSOR_LAST (Ende). |
Rückgabewert
true zurück, wenn der Cursor erfolgreich bewegt wurde. Gibt false zurück, wenn die Bewegung fehlschlägt, z. B. wenn der Offset außerhalb des gültigen Bereichs liegt oder das Handle ungültig ist.Beispiele
Cursor auf den ersten Datensatz setzen und Zeilen lesen
<?php
$conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
$req = cubrid_execute($conn, 'SELECT * FROM orders ORDER BY id');
// Cursor an den Anfang setzen
cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
$firstRow = cubrid_fetch($req, CUBRID_ASSOC);
echo 'Erster Datensatz: ' . $firstRow['id'] . PHP_EOL;
// Cursor ans Ende setzen
cubrid_move_cursor($req, 1, CUBRID_CURSOR_LAST);
$lastRow = cubrid_fetch($req, CUBRID_ASSOC);
echo 'Letzter Datensatz: ' . $lastRow['id'] . PHP_EOL;
cubrid_close_request($req);
cubrid_disconnect($conn);
?>Seitenweise Navigation durch Ergebnisse (Pagination)
<?php
$conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
$req = cubrid_execute($conn, 'SELECT id, name FROM products ORDER BY id');
$pageSize = 10;
$page = 3; // Dritte Seite abrufen
$startOffset = ($page - 1) * $pageSize + 1;
if (cubrid_move_cursor($req, $startOffset, CUBRID_CURSOR_FIRST)) {
for ($i = 0; $i < $pageSize; $i++) {
$row = cubrid_fetch($req, CUBRID_ASSOC);
if ($row === false) {
break; // Keine weiteren Datensätze
}
echo $row['id'] . ': ' . $row['name'] . PHP_EOL;
}
} else {
echo 'Seite nicht verfügbar.';
}
cubrid_close_request($req);
cubrid_disconnect($conn);
?>// Wichtig · Fallstricke
Hinweis zum Offset-Verhalten: Bei Verwendung von CUBRID_CURSOR_FIRST und CUBRID_CURSOR_LAST beginnt die Zählung bei 1, nicht bei 0. Ein Offset von 1 mit CUBRID_CURSOR_FIRST positioniert den Cursor auf den ersten Datensatz.
Bei CUBRID_CURSOR_LAST bewegt ein negativer Offset den Cursor rückwärts vom letzten Datensatz. So kann z. B. mit cubrid_move_cursor($req, -1, CUBRID_CURSOR_LAST) der vorletzte Datensatz angesteuert werden.
Die Funktion erfordert, dass das Ergebnis in einem scrollbaren Modus geöffnet wurde. Nicht alle CUBRID-Abfragetypen unterstützen scrollbare Cursor — prüfen Sie ggf. die CUBRID-Dokumentation für Ihren Anwendungsfall.