oci_get_implicit_resultset — Funktion · PHP-Referenz

Signatur

oci_get_implicit_resultset(resource $statement): resource|false

Beschreibung

oci_get_implicit_resultset() wird verwendet, um auf sogenannte Implicit Result Sets zuzugreifen, die Oracle-gespeicherte Prozeduren oder anonyme PL/SQL-Blöcke mit DBMS_SQL.RETURN_RESULT() (ab Oracle 12c) erzeugen. Dabei sendet die Prozedur Ergebnismengen implizit an den Aufrufer, ohne dass explizite REF CURSOR-Ausgabeparameter benötigt werden.

Der typische Ablauf ist: zunächst wird die gespeicherte Prozedur mit oci_execute() ausgeführt, und anschließend werden alle zurückgelieferten untergeordneten Statements durch wiederholten Aufruf von oci_get_implicit_resultset() in einer Schleife abgerufen, bis false zurückgegeben wird. Jedes zurückgegebene Statement-Handle kann dann mit oci_fetch_array() oder ähnlichen Fetch-Funktionen verarbeitet werden.

Diese Funktion ist besonders nützlich, wenn Oracle-Stored-Procedures auf die neue, simplere DBMS_SQL.RETURN_RESULT-API umgestellt wurden und mehrere Ergebnismengen aus einer einzigen Prozedur abzurufen sind, ohne den PHP-Code mit zahlreichen OUT-Parametern zu verkomplizieren.

Voraussetzung: Oracle Database 12c oder neuer sowie Oracle-Client-Bibliotheken ab Version 12.1 sind erforderlich.

Parameter

Name	Typ	Default	Beschreibung
$statement Pflicht	resource		Ein gültiges OCI8-Statement-Handle, das von `oci_parse()` erzeugt und mit `oci_execute()` ausgeführt wurde. Das Statement muss eine gespeicherte Prozedur aufgerufen haben, die `DBMS_SQL.RETURN_RESULT()` verwendet.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt ein Statement-Resource zurück, das die nächste untergeordnete Ergebnismenge repräsentiert. Wenn keine weiteren Implicit Result Sets vorhanden sind, wird false zurückgegeben. Das zurückgegebene Handle kann wie ein normales OCI8-Statement mit Fetch-Funktionen wie oci_fetch_array() verwendet werden.

Beispiele

Mehrere Implicit Result Sets aus einer Oracle-Prozedur abrufen

<?php
// Voraussetzung: Oracle 12c, Prozedur gibt zwei Result Sets zurück:
// CREATE OR REPLACE PROCEDURE multi_results AS
//   c1 SYS_REFCURSOR;
//   c2 SYS_REFCURSOR;
// BEGIN
//   OPEN c1 FOR SELECT 1 AS id, 'Alice' AS name FROM dual;
//   DBMS_SQL.RETURN_RESULT(c1);
//   OPEN c2 FOR SELECT 2 AS id, 'Bob' AS name FROM dual;
//   DBMS_SQL.RETURN_RESULT(c2);
// END;

$conn = oci_connect('user', 'password', 'localhost/XEPDB1');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

$stmt = oci_parse($conn, 'BEGIN multi_results(); END;');
oci_execute($stmt);

$setNumber = 1;
while (($child = oci_get_implicit_resultset($stmt)) !== false) {
    echo "Result Set #{$setNumber}:\n";
    while (($row = oci_fetch_array($child, OCI_ASSOC | OCI_RETURN_NULLS)) !== false) {
        echo '  ID: ' . $row['ID'] . ', Name: ' . $row['NAME'] . "\n";
    }
    $setNumber++;
}

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

Result Set #1: ID: 1, Name: Alice Result Set #2: ID: 2, Name: Bob

Implicit Result Sets in ein Array einlesen

<?php
$conn = oci_connect('user', 'password', 'localhost/XEPDB1');

$stmt = oci_parse($conn, 'BEGIN multi_results(); END;');
oci_execute($stmt);

$allResults = [];
while (($child = oci_get_implicit_resultset($stmt)) !== false) {
    $rows = [];
    while (($row = oci_fetch_array($child, OCI_ASSOC | OCI_RETURN_NULLS)) !== false) {
        $rows[] = $row;
    }
    $allResults[] = $rows;
}

oci_free_statement($stmt);
oci_close($conn);

// Verarbeitung der gesammelten Ergebnisse
foreach ($allResults as $index => $resultSet) {
    echo 'Ergebnismenge ' . ($index + 1) . ': ' . count($resultSet) . " Zeile(n)\n";
}
?>

Ergebnismenge 1: 1 Zeile(n) Ergebnismenge 2: 1 Zeile(n)

// Wichtig · Fallstricke

Versionsanforderung: Diese Funktion steht erst ab PHP 5.6.0 zur Verfügung und erfordert Oracle Database 12c sowie Oracle-Client-Bibliotheken der Version 12.1 oder höher. Bei älteren Oracle-Versionen ist die Verwendung von REF CURSOR-OUT-Parametern notwendig.

Ressourcenverwaltung: Die durch oci_get_implicit_resultset() zurückgegebenen untergeordneten Statement-Handles werden automatisch freigegeben, wenn das übergeordnete Statement-Handle mit oci_free_statement() geschlossen wird. Ein explizites Freigeben der Child-Statements ist daher nicht notwendig, aber auch nicht schädlich.

Reihenfolge: Die Ergebnismengen werden in der Reihenfolge zurückgegeben, in der die Prozedur DBMS_SQL.RETURN_RESULT() aufgerufen hat. Die Reihenfolge ist deterministisch und entspricht der Ausführungsreihenfolge in der Prozedur.

Siehe auch

oci_execute oci_fetch_array oci_parse oci_free_statement oci_new_cursor