Signatur
Beschreibung
oci_define_by_name() bindet eine PHP-Variable an eine benannte Spalte eines OCI-Ergebnissatzes. Nach dem Ausführen der Abfrage mit oci_execute() wird die Variable bei jedem Aufruf von oci_fetch() automatisch mit dem aktuellen Spaltenwert aktualisiert. Dies ist besonders nützlich, wenn man Zeile für Zeile verarbeiten möchte, ohne Hilfsfunktionen wie oci_fetch_assoc() zu verwenden.
Der Spaltenname ($column_name) muss in Großbuchstaben angegeben werden, da Oracle intern alle nicht in Anführungszeichen gesetzten Bezeichner in Großschreibung umwandelt. Bei Spalten, die in der SQL-Abfrage mit einem Alias definiert wurden, muss der Aliasname verwendet werden.
Der optionale Parameter $type erlaubt es, den Datentyp der Variable explizit festzulegen – beispielsweise SQLT_CHR für Zeichenketten oder OCI_B_CLOB für CLOB-Werte. Für normale Spalten ist der Standardwert 0 (automatische Erkennung) ausreichend.
Diese Funktion muss vor dem Aufruf von oci_execute() aufgerufen werden, damit die Bindung korrekt eingerichtet wird. Sie eignet sich besonders bei der Verarbeitung großer Ergebnismengen, da keine assoziativen Arrays alloziert werden müssen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $statement Pflicht | resource | Ein gültiges OCI-Statement-Handle, das durch oci_parse() erzeugt wurde. |
|
| $column_name Pflicht | string | Name der Spalte im Ergebnissatz, wie er in der SQL-Abfrage definiert ist – in Großbuchstaben. Bei Aliasnamen ebenfalls den Alias in Großbuchstaben angeben. | |
| $variable Pflicht | mixed | Die PHP-Variable (als Referenz), die mit dem Spaltenwert befüllt wird. Nach jedem oci_fetch()-Aufruf enthält sie den aktuellen Zeilenwert. |
|
| $type | int | 0 | Optionaler OCI-Datentyp der Spalte. Standardmäßig 0 (automatisch). Für LOB-Spalten z. B. OCI_B_CLOB oder OCI_B_BLOB angeben. |
Rückgabewert
true bei Erfolg zurück. Im Fehlerfall (z. B. ungültiges Statement-Handle) wird false zurückgegeben.Beispiele
Einfache Spaltenbindung und zeilenweise Verarbeitung
<?php
$conn = oci_connect('benutzer', 'passwort', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error($e['message'], E_USER_ERROR);
}
$sql = 'SELECT mitarbeiter_id, vorname, nachname FROM mitarbeiter ORDER BY nachname';
$stmt = oci_parse($conn, $sql);
// Variablen vor oci_execute() binden
oci_define_by_name($stmt, 'MITARBEITER_ID', $id);
oci_define_by_name($stmt, 'VORNAME', $vorname);
oci_define_by_name($stmt, 'NACHNAME', $nachname);
oci_execute($stmt);
while (oci_fetch($stmt)) {
echo "ID: $id | Name: $vorname $nachname\n";
}
oci_free_statement($stmt);
oci_close($conn);Alias-Spalte und expliziter Datentyp
<?php
$conn = oci_connect('benutzer', 'passwort', 'localhost/XE');
// Spalte mit Alias definieren
$sql = 'SELECT abteilung_id, COUNT(*) AS anzahl FROM mitarbeiter GROUP BY abteilung_id';
$stmt = oci_parse($conn, $sql);
// Alias-Name in GROSSBUCHSTABEN verwenden
oci_define_by_name($stmt, 'ABTEILUNG_ID', $abtId);
oci_define_by_name($stmt, 'ANZAHL', $anzahl, SQLT_INT);
oci_execute($stmt);
while (oci_fetch($stmt)) {
echo "Abteilung $abtId hat $anzahl Mitarbeiter.\n";
}
oci_free_statement($stmt);
oci_close($conn);// Wichtig · Fallstricke
Reihenfolge beachten: oci_define_by_name() muss vor oci_execute() aufgerufen werden, andernfalls werden die Bindings ignoriert und die Variablen nicht befüllt.
Groß-/Kleinschreibung: Oracle wandelt Spaltennamen intern in Großbuchstaben um. Der Parameter $column_name muss daher immer in Großbuchstaben übergeben werden, sonst schlägt die Bindung stillschweigend fehl.
LOB-Spalten: Bei CLOB- oder BLOB-Spalten sollte der Typ explizit als OCI_B_CLOB bzw. OCI_B_BLOB angegeben werden, und die gebundene Variable wird als OCI-LOB-Objekt befüllt, das mit ->load() ausgelesen werden kann.
Diese Funktion ist Teil der OCI8-Erweiterung und erfordert, dass PHP mit --with-oci8 kompiliert wurde oder die Erweiterung über extension=oci8 in der php.ini aktiviert ist.