ocinewcursor — Funktion · PHP-Referenz

Signatur

ocinewcursor(resource $connection): resource|false

Beschreibung

ocinewcursor() ist ein veralteter Alias für oci_new_cursor(). Die Funktion erzeugt einen neuen Oracle-Cursor-Handle (auch bekannt als Statement-Handle), der als REF-CURSOR-Parameter an gespeicherte Oracle-Prozeduren übergeben werden kann.

REF-CURSORs werden in Oracle verwendet, um aus gespeicherten Prozeduren Ergebnismengen zurückzugeben. Der mit ocinewcursor() erzeugte Cursor wird dabei zunächst als OUT-Parameter gebunden, von der Prozedur befüllt und kann anschließend mit ocifetch() bzw. oci_fetch_array() ausgelesen werden.

Da es sich um einen Alias handelt, ist die Verwendung von oci_new_cursor() vorzuziehen. Aliase der alten OCI-API (ohne Unterstrich) gelten seit PHP 5.4 als veraltet und könnten in zukünftigen PHP-Versionen entfernt werden.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	resource		Eine gültige Oracle-Verbindungsressource, die zuvor mit `ocilogon()`, `oci_connect()` oder einer ähnlichen Funktion erstellt wurde.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt im Erfolgsfall eine neue Cursor-Ressource zurück, die als REF-CURSOR-Parameter verwendet werden kann. Bei einem Fehler wird false zurückgegeben.

Beispiele

REF-CURSOR aus gespeicherter Oracle-Prozedur auslesen

<?php
// Verbindung zur Oracle-Datenbank herstellen
$conn = oci_connect('benutzer', 'passwort', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

// Neuen Cursor mit dem veralteten Alias erzeugen
$cursor = ocinewcursor($conn);

// Statement mit gespeicherter Prozedur, die einen REF-CURSOR befüllt
$stmt = oci_parse($conn, 'BEGIN get_mitarbeiter(:cur); END;');

// Cursor als OUT-Parameter binden
oci_bind_by_name($stmt, ':cur', $cursor, -1, OCI_B_CURSOR);

// Statement ausführen
oci_execute($stmt);

// Cursor ausführen und Ergebnisse abrufen
oci_execute($cursor);
while ($row = oci_fetch_array($cursor, OCI_ASSOC + OCI_RETURN_NULLS)) {
    echo 'Name: ' . $row['NAME'] . ', Abteilung: ' . $row['ABTEILUNG'] . PHP_EOL;
}

// Ressourcen freigeben
oci_free_statement($cursor);
oci_free_statement($stmt);
oci_close($conn);
?>

Name: Max Mustermann, Abteilung: Entwicklung Name: Erika Musterfrau, Abteilung: Vertrieb

Empfohlene moderne Variante mit oci_new_cursor()

<?php
// Moderne, bevorzugte Variante ohne veralteten Alias
$conn = oci_connect('benutzer', 'passwort', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

// Empfohlen: oci_new_cursor() statt ocinewcursor()
$cursor = oci_new_cursor($conn);

$stmt = oci_parse($conn, 'BEGIN get_produkte(:cur); END;');
oci_bind_by_name($stmt, ':cur', $cursor, -1, OCI_B_CURSOR);
oci_execute($stmt);
oci_execute($cursor);

while ($row = oci_fetch_array($cursor, OCI_ASSOC)) {
    echo $row['PRODUKTNAME'] . PHP_EOL;
}

oci_free_statement($cursor);
oci_free_statement($stmt);
oci_close($conn);
?>

Produkt A Produkt B Produkt C

// Wichtig · Fallstricke

Veraltet: ocinewcursor() ist ein Alias der alten OCI8-API und sollte in neuem Code nicht mehr verwendet werden. Die moderne und empfohlene Funktion ist oci_new_cursor(). Alte Alias-Funktionen ohne Unterstrich können in zukünftigen PHP-Versionen ohne weitere Ankündigung entfernt werden.

Der erzeugte Cursor muss nach der Verwendung mit oci_free_statement() freigegeben werden, um Speicherlecks zu vermeiden.

Siehe auch

oci_new_cursor oci_bind_by_name oci_execute oci_fetch_array oci_free_statement oci_connect