Signatur
Beschreibung
ocidefinebyname() ist ein veralteter Alias der Funktion oci_define_by_name() und gehört zur OCI8-Erweiterung für Oracle-Datenbanken. Die Funktion bindet eine PHP-Variable an eine Ergebnisspalte einer vorbereiteten Oracle-SQL-Abfrage, sodass die Variable bei jedem Aufruf von oci_fetch() automatisch mit dem aktuellen Spaltenwert befüllt wird.
Das Binden von Ausgabespalten ist besonders nützlich, wenn man Ergebnisse einer SELECT-Abfrage zeilenweise durchlaufen möchte, ohne jedes Mal ein assoziatives Array auslesen zu müssen. Nach dem Aufruf von ocidefinebyname() genügt ein wiederholter Aufruf von oci_fetch(), um die gebundenen Variablen automatisch zu aktualisieren.
Wichtig: Diese Funktion ist ein Alias und wird seit PHP 8.0 als veraltet betrachtet. In neuem Code sollte stets oci_define_by_name() verwendet werden. Der Spaltenname in $column_name wird von Oracle standardmäßig in Großbuchstaben umgewandelt, sofern er in der SQL-Abfrage nicht in Anführungszeichen steht.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $statement Pflicht | resource | Ein gültiges OCI-Statement-Handle, das mit oci_parse() erzeugt wurde. |
|
| $column_name Pflicht | string | Der Name der Ergebnisspalte in der SQL-Abfrage. Oracle gibt Spaltennamen standardmäßig in Großbuchstaben zurück, daher muss dieser Parameter ebenfalls großgeschrieben werden (z. B. 'EMPLOYEE_ID'). |
|
| $variable Pflicht | mixed | Die PHP-Variable (per Referenz), die an die Spalte gebunden wird. Sie wird bei jedem oci_fetch()-Aufruf automatisch mit dem Spaltenwert befüllt. |
|
| $type | int | 0 | Optionaler Datentyp der Rückgabe. Mögliche Werte sind OCI-Konstanten wie SQLT_CHR, SQLT_BIN oder OCI_B_CLOB. Der Standardwert 0 wählt automatisch den passenden Typ. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiges Statement-Handle oder unbekannter Spaltenname).Beispiele
Spaltenwerte mit ocidefinebyname() zeilenweise lesen
<?php
// Datenbankverbindung herstellen
$conn = oci_connect('benutzer', 'passwort', 'localhost/XEPDB1');
if (!$conn) {
$e = oci_error();
trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}
$sql = 'SELECT employee_id, last_name FROM employees WHERE rownum <= 5';
$stmt = oci_parse($conn, $sql);
// Variablen an Spalten binden (Spaltennamen in Großbuchstaben)
ocidefinebyname($stmt, 'EMPLOYEE_ID', $empId);
ocidefinebyname($stmt, 'LAST_NAME', $lastName);
oci_execute($stmt);
while (oci_fetch($stmt)) {
echo "ID: $empId – Name: $lastName\n";
}
oci_free_statement($stmt);
oci_close($conn);Bevorzugte moderne Variante mit oci_define_by_name()
<?php
// Empfohlene Schreibweise in neuem Code
$conn = oci_connect('benutzer', 'passwort', 'localhost/XEPDB1');
$sql = 'SELECT department_id, department_name FROM departments WHERE rownum <= 3';
$stmt = oci_parse($conn, $sql);
// oci_define_by_name() statt veraltetem ocidefinebyname()
oci_define_by_name($stmt, 'DEPARTMENT_ID', $deptId);
oci_define_by_name($stmt, 'DEPARTMENT_NAME', $deptName);
oci_execute($stmt);
while (oci_fetch($stmt)) {
printf("Abt. %d: %s\n", $deptId, $deptName);
}
oci_free_statement($stmt);
oci_close($conn);// Wichtig · Fallstricke
Veraltet: ocidefinebyname() ist ein alter Alias aus der Zeit vor dem OCI8-API-Umbau in PHP 5. Seit PHP 8.0 gelten solche Aliasfunktionen als offiziell veraltet und können in zukünftigen PHP-Versionen entfernt werden. Verwende stets oci_define_by_name().
Der Spaltenname muss exakt dem entsprechen, wie Oracle ihn zurückgibt – standardmäßig in Großbuchstaben. Falls in der SQL-Abfrage ein Alias mit Kleinbuchstaben in Anführungszeichen verwendet wird (z. B. SELECT employee_id AS "empId"), muss der Parameterwert ebenfalls 'empId' lauten.
Die gebundene Variable darf erst nach oci_execute() und oci_fetch() ausgelesen werden – sie ist vor dem ersten Fetch nicht befüllt.