Signatur
Beschreibung
oci_set_db_operation() weist der aktiven Oracle-Datenbankverbindung einen logischen Operationsnamen zu. Dieser Name wird in Oracle-internen Views wie V$SQL_MONITOR und V$SESSION sowie im Oracle Application Tracing (DBOP) angezeigt und erleichtert das Monitoring und die Fehlersuche erheblich.
Der gesetzte Operationsname hilft Oracle-Datenbankadministratoren, laufende SQL-Aktivitäten einer bestimmten PHP-Anwendungslogik zuzuordnen, ohne die eigentliche SQL-Abfrage anpassen zu müssen. Typische Anwendungsfälle sind das Markieren von Batch-Jobs, API-Endpunkten oder kritischen Geschäftsoperationen, um deren Performance-Metriken direkt im Oracle Enterprise Manager oder SQL Monitor zu verfolgen.
Die Funktion erfordert Oracle Database 12c (Release 1) oder neuer sowie die Oracle Client-Bibliothek ab Version 12.1. Der gesetzte Wert überschreibt einen zuvor gesetzten Operationsnamen und bleibt bis zum nächsten Aufruf von oci_set_db_operation() oder bis zum Ende der Verbindung aktiv.
Diese Funktion steht nur zur Verfügung, wenn PHP mit der OCI8-Erweiterung kompiliert wurde und Oracle Database 12.1 oder höher als Backend verwendet wird.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection Pflicht | resource | Eine gültige Oracle-Verbindungsressource, die mit oci_connect(), oci_pconnect() oder oci_new_connect() erstellt wurde. |
|
| $dbop Pflicht | string | Der Name der Datenbankoperation, der in Oracle-Diagnosesichten erscheinen soll. Ein leerer String setzt die aktuelle Operation zurück. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler, z. B. wenn die Oracle-Client-Bibliothek zu alt ist oder die Verbindungsressource ungültig ist.Beispiele
Operationsnamen für einen API-Endpunkt setzen
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Operationsnamen setzen, bevor die Abfrage ausgeführt wird
$result = oci_set_db_operation($conn, 'GET_EMPLOYEE_LIST');
if ($result) {
echo "Datenbankoperation erfolgreich gesetzt.\n";
}
$sql = 'SELECT employee_id, last_name FROM employees WHERE department_id = :dept_id';
$stid = oci_parse($conn, $sql);
oci_bind_by_name($stid, ':dept_id', $dept_id);
$dept_id = 10;
oci_execute($stid);
while ($row = oci_fetch_array($stid, OCI_ASSOC)) {
echo $row['EMPLOYEE_ID'] . ': ' . $row['LAST_NAME'] . "\n";
}
oci_free_statement($stid);
oci_close($conn);
?>Operationsnamen zwischen verschiedenen Verarbeitungsphasen wechseln
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}
// Phase 1: Daten laden
oci_set_db_operation($conn, 'BATCH_LOAD_PHASE1');
$stid = oci_parse($conn, 'INSERT INTO log_table (msg) VALUES (:msg)');
$msg = 'Phase 1 gestartet';
oci_bind_by_name($stid, ':msg', $msg);
oci_execute($stid);
echo "Phase 1 abgeschlossen.\n";
// Phase 2: Daten transformieren
oci_set_db_operation($conn, 'BATCH_TRANSFORM_PHASE2');
$stid2 = oci_parse($conn, 'UPDATE log_table SET msg = :msg WHERE ROWNUM = 1');
$msg = 'Phase 2 transformiert';
oci_bind_by_name($stid2, ':msg', $msg);
oci_execute($stid2);
echo "Phase 2 abgeschlossen.\n";
// Operationsnamen zurücksetzen
oci_set_db_operation($conn, '');
oci_commit($conn);
oci_close($conn);
?>// Wichtig · Fallstricke
Versionsanforderung: Diese Funktion ist nur verfügbar, wenn PHP mit OCI8 2.2.0+ kompiliert wurde und Oracle Database 12c Release 1 (12.1) oder neuer genutzt wird. Mit älteren Oracle-Versionen gibt die Funktion false zurück, ohne eine Fehlermeldung auszulösen.
Sichtbarkeit: Der gesetzte Operationsname erscheint in den Oracle-Views V$SQL_MONITOR.DBOP_NAME und V$SESSION.DBOP_NAME. Er ist nicht als SQL-Kommentar in der Abfrage selbst enthalten, sondern wird über die Oracle Call Interface (OCI) gesetzt.
Länge: Oracle begrenzt die Länge des Operationsnamens. Zu lange Zeichenketten können abgeschnitten werden. Es empfiehlt sich, Namen unter 64 Zeichen zu halten.