Signatur
Beschreibung
oci_set_module_name() weist der aktuellen Oracle-Datenbankverbindung einen Modulnamen zu. Dieser Name erscheint anschließend in Oracle-internen Views wie V$SESSION oder V$SQLAREA in der Spalte MODULE und erleichtert so das Monitoring, die Diagnose und das Performance-Tuning auf Datenbankebene.
Die Funktion ist besonders nützlich in größeren Anwendungen oder Microservice-Architekturen, in denen mehrere Applikationen dieselbe Oracle-Datenbank nutzen. Durch das Setzen eines aussagekräftigen Modulnamens (z. B. "Bestellverwaltung") können Datenbankadministratoren Abfragen und Sessions eindeutig einer Anwendungskomponente zuordnen.
Der Modulname wird beim nächsten Roundtrip zur Datenbank übertragen. Er kann während der Laufzeit beliebig oft geändert werden, um verschiedene Phasen der Anwendung zu kennzeichnen. Zusammen mit oci_set_action() und oci_set_client_info() ermöglicht er eine feingranulare Kontextinformation für Oracle-Monitoring-Tools wie Oracle Enterprise Manager.
Der Name darf maximal 48 Bytes lang sein. Längere Strings werden von Oracle serverseitig abgeschnitten.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection Pflicht | resource | Eine gültige Oracle-Verbindungsressource, wie sie von oci_connect(), oci_pconnect() oder oci_new_connect() zurückgegeben wird. |
|
| $name Pflicht | string | Der zu setzende Modulname. Maximal 48 Bytes lang. Längere Werte werden von Oracle serverseitig auf 48 Bytes gekürzt. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige Verbindungsressource).Beispiele
Modulnamen für eine Verbindung setzen
<?php
$conn = oci_connect('benutzer', 'passwort', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}
// Modulnamen setzen – erscheint in V$SESSION.MODULE
oci_set_module_name($conn, 'Bestellverwaltung');
// Eine Abfrage ausführen – der Modulname wird beim nächsten Roundtrip übertragen
$stmt = oci_parse($conn, 'SELECT bestellnummer FROM bestellungen WHERE rownum <= 5');
oci_execute($stmt);
while ($row = oci_fetch_assoc($stmt)) {
echo 'Bestellung: ' . $row['BESTELLNUMMER'] . PHP_EOL;
}
oci_free_statement($stmt);
oci_close($conn);Kombination mit oci_set_action für feingranulares Monitoring
<?php
$conn = oci_connect('benutzer', 'passwort', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}
// Modul und Aktion setzen – beide erscheinen in V$SESSION
oci_set_module_name($conn, 'Webshop');
oci_set_action($conn, 'Warenkorb laden');
$stmt = oci_parse($conn, 'SELECT artikel_id, menge FROM warenkorb WHERE kunden_id = :kid');
oci_bind_by_name($stmt, ':kid', $kundenId);
$kundenId = 42;
oci_execute($stmt);
while ($row = oci_fetch_assoc($stmt)) {
echo 'Artikel ' . $row['ARTIKEL_ID'] . ' – Menge: ' . $row['MENGE'] . PHP_EOL;
}
// Aktion für den nächsten Schritt aktualisieren
oci_set_action($conn, 'Bestellung abschließen');
oci_free_statement($stmt);
oci_close($conn);// Wichtig · Fallstricke
Längengrenze: Oracle begrenzt den Modulnamen auf 48 Bytes. Mehrbyte-Zeichen (z. B. UTF-8-Umlaute) können die effektive Zeichenanzahl reduzieren. Verwende kurze, ASCII-basierte Namen, um Abschneidungen zu vermeiden.
Verfügbarkeit: Die Funktion steht nur zur Verfügung, wenn PHP mit der Oracle-Erweiterung OCI8 kompiliert wurde (--with-oci8). Sie ist ab PHP 5.3.2 und OCI8 1.4 verfügbar.
Persistente Verbindungen: Bei persistenten Verbindungen (oci_pconnect()) kann der Modulname von einem vorherigen Request noch gesetzt sein. Es empfiehlt sich, ihn zu Beginn jedes Requests explizit neu zu setzen.