Signatur
Beschreibung
mqseries_back() führt einen Rollback aller seit dem letzten Synchronisierungspunkt innerhalb der aktuellen MQ-Einheit (Unit of Work) durchgeführten Nachrichten-Operationen durch. Das bedeutet, dass alle gesendeten und empfangenen Nachrichten, die seit dem letzten MQCMIT oder Verbindungsaufbau in der Transaktion aufgetreten sind, rückgängig gemacht werden.
Die Funktion ist der PHP-Wrapper für den nativen IBM MQ MQBACK-Aufruf und wird im Zusammenhang mit dem MQSeries-Messaging-System eingesetzt. Sie ist nur verfügbar, wenn die PECL-Erweiterung mqseries installiert ist.
Typischerweise wird mqseries_back() im Fehlerfall verwendet, wenn eine vorherige Operation (z. B. mqseries_put() oder mqseries_get()) fehlgeschlagen ist und alle Änderungen innerhalb der aktuellen Transaktion verworfen werden sollen. Der Erfolg oder Misserfolg des Aufrufs wird über die Parameter $compCode und $reason signalisiert.
Nach einem erfolgreichen mqseries_back() beginnt eine neue Einheit (Unit of Work). Um Transaktionen erfolgreich abzuschließen, wird stattdessen mqseries_cmit() verwendet.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $hconn Pflicht | resource | Das Verbindungs-Handle zu einem IBM MQ Queue Manager, wie es von mqseries_conn() oder mqseries_connx() zurückgegeben wurde. |
|
| $compCode Pflicht | resource | Wird nach dem Aufruf mit dem MQ-Completion-Code befüllt. MQCC_OK (0) signalisiert Erfolg, MQCC_WARNING (1) eine Warnung und MQCC_FAILED (2) einen Fehler. |
|
| $reason Pflicht | resource | Wird nach dem Aufruf mit dem MQ-Reason-Code befüllt, der den genauen Grund eines Fehlers oder einer Warnung beschreibt (z. B. MQRC_CONNECTION_BROKEN). |
Rückgabewert
$compCode und $reason kommuniziert.Beispiele
Transaktion zurücksetzen nach einem Fehler
<?php
// Verbindung zum Queue Manager herstellen
mqseries_conn('QUEUEMANAGER', $hconn, $compCode, $reason);
if ($compCode !== MQSERIES_MQCC_OK) {
die('Verbindung fehlgeschlagen. Reason: ' . $reason);
}
// Queue öffnen
mqseries_open(
$hconn,
['ObjectName' => 'TESTQUEUE'],
MQSERIES_MQOO_OUTPUT | MQSERIES_MQOO_FAIL_IF_QUIESCING,
$hobj,
$compCode,
$reason
);
if ($compCode !== MQSERIES_MQCC_OK) {
// Transaktion zurückrollen
mqseries_back($hconn, $compCode, $reason);
echo 'Rollback durchgeführt. Reason: ' . $reason . PHP_EOL;
mqseries_disc($hconn, $compCode, $reason);
exit;
}
// Nachricht senden
$md = [];
$pmo = ['Options' => MQSERIES_MQPMO_SYNCPOINT];
mqseries_put($hconn, $hobj, $md, $pmo, 'Testnachricht', $compCode, $reason);
if ($compCode !== MQSERIES_MQCC_OK) {
// Fehler: Alle Änderungen dieser Transaktion rückgängig machen
mqseries_back($hconn, $compCode, $reason);
echo 'Rollback erfolgreich. Reason Code: ' . $reason . PHP_EOL;
} else {
// Alles in Ordnung: Transaktion bestätigen
mqseries_cmit($hconn, $compCode, $reason);
echo 'Transaktion committed.' . PHP_EOL;
}
mqseries_close($hconn, $hobj, MQSERIES_MQCO_NONE, $compCode, $reason);
mqseries_disc($hconn, $compCode, $reason);Reason Code nach Rollback auswerten
<?php
// Bestehende Verbindung vorausgesetzt ($hconn)
mqseries_back($hconn, $compCode, $reason);
if ($compCode === MQSERIES_MQCC_OK) {
echo 'MQBACK erfolgreich – Transaktion wurde zurückgesetzt.' . PHP_EOL;
} elseif ($compCode === MQSERIES_MQCC_WARNING) {
echo 'MQBACK mit Warnung. Reason: ' . $reason . PHP_EOL;
} else {
echo 'MQBACK fehlgeschlagen. Reason: ' . $reason . PHP_EOL;
}// Wichtig · Fallstricke
Voraussetzungen: Die PHP-Erweiterung mqseries muss über PECL installiert sein und eine funktionierende IBM MQ-Installation muss auf dem System vorhanden sein. Die Erweiterung ist nicht Teil der Standard-PHP-Distribution.
Transaktionale Grenzen: mqseries_back() wirkt nur auf Operationen, die unter dem aktuellen Synchronisierungspunkt (Syncpoint) mit der Option MQPMO_SYNCPOINT (Senden) bzw. MQGMO_SYNCPOINT (Empfangen) durchgeführt wurden. Operationen ohne Syncpoint-Option sind von einem Rollback nicht betroffen.
Verbindungsstatus: Nach einem Verbindungsabbruch oder einer fehlerhaften Verbindung kann mqseries_back() ebenfalls fehlschlagen. In diesem Fall sollte die Verbindung mit mqseries_disc() sauber beendet werden.