Signatur
Beschreibung
mqseries_cmit() schließt eine Arbeitseinheit (Unit of Work) auf einer IBM MQ-Verbindung ab, indem alle seit dem letzten Commit oder Rollback getätigten Nachrichten-Get- und Put-Operationen dauerhaft festgeschrieben werden. Dies entspricht dem nativen MQ-API-Aufruf MQCMIT.
Die Funktion gehört zur PHP-Extension mqseries, die eine prozedurale Schnittstelle zur IBM MQ (früher WebSphere MQ / MQSeries) Message-Queueing-Middleware bereitstellt. Sie wird typischerweise verwendet, wenn Nachrichten in einer Transaktion verarbeitet werden müssen und sichergestellt sein soll, dass entweder alle oder keine der Operationen dauerhaft wirksam werden.
Nach einem erfolgreichen mqseries_cmit() beginnt automatisch eine neue Arbeitseinheit. Im Fehlerfall sollte stattdessen mqseries_back() aufgerufen werden, um die Transaktion zurückzusetzen. Die Rückmeldungen über Erfolg oder Fehler erhält man über die Parameter $compCode (Completion Code) und $reason (Reason Code).
Der Einsatz von Transaktionen (Commit/Rollback) ist besonders wichtig in Szenarien, in denen Nachrichten-Verarbeitung und Datenbankoperationen atomar ausgeführt werden müssen, um Datenverlust oder Doppelverarbeitung zu vermeiden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $hconn Pflicht | resource | Das Verbindungs-Handle zur IBM MQ-Verbindung, wie es von mqseries_conn() oder mqseries_connx() zurückgegeben wurde. |
|
| $compCode Pflicht | resource | Ausgabe-Parameter (by reference): enthält nach dem Aufruf den MQ Completion Code (MQCC_OK, MQCC_WARNING oder MQCC_FAILED). |
|
| $reason Pflicht | resource | Ausgabe-Parameter (by reference): enthält nach dem Aufruf den MQ Reason Code, der genauere Informationen über den Erfolg oder den Fehlergrund liefert (z. B. MQRC_NONE bei Erfolg). |
Rückgabewert
$compCode und $reason kommuniziert.Beispiele
Nachrichten transaktional in eine Queue schreiben und committen
<?php
// Verbindung zur IBM MQ herstellen
mqseries_conn('QM_TEST', $hconn, $compCode, $reason);
if ($compCode !== MQSERIES_MQCC_OK) {
die("Verbindung fehlgeschlagen. Reason: $reason");
}
// Queue öffnen
mqseries_open(
$hconn,
['ObjectName' => 'TEST.QUEUE'],
MQSERIES_MQOO_OUTPUT | MQSERIES_MQOO_FAIL_IF_QUIESCING,
$hobj,
$compCode,
$reason
);
if ($compCode !== MQSERIES_MQCC_OK) {
mqseries_disc($hconn, $compCode, $reason);
die("Queue öffnen fehlgeschlagen. Reason: $reason");
}
// Nachricht in die Queue schreiben (innerhalb der Transaktion)
$md = [];
$pmo = ['Options' => MQSERIES_MQPMO_SYNCPOINT];
mqseries_put($hconn, $hobj, $md, $pmo, 'Hallo MQ!', $compCode, $reason);
if ($compCode !== MQSERIES_MQCC_OK) {
// Bei Fehler: Transaktion zurückrollen
mqseries_back($hconn, $compCode, $reason);
echo "Put fehlgeschlagen, Rollback durchgeführt. Reason: $reason\n";
} else {
// Transaktion bestätigen
mqseries_cmit($hconn, $compCode, $reason);
if ($compCode === MQSERIES_MQCC_OK) {
echo "Nachricht erfolgreich committed.\n";
} else {
echo "Commit fehlgeschlagen. Reason: $reason\n";
}
}
// Queue schließen und Verbindung trennen
mqseries_close($hconn, $hobj, MQSERIES_MQCO_NONE, $compCode, $reason);
mqseries_disc($hconn, $compCode, $reason);Fehlerbehandlung mit Completion Code und Reason Code auswerten
<?php
// Voraussetzung: $hconn ist eine gültige MQ-Verbindung
mqseries_cmit($hconn, $compCode, $reason);
switch ($compCode) {
case MQSERIES_MQCC_OK:
echo "Commit erfolgreich (CC: $compCode, Reason: $reason)\n";
break;
case MQSERIES_MQCC_WARNING:
echo "Commit mit Warnung abgeschlossen. Reason Code: $reason\n";
break;
case MQSERIES_MQCC_FAILED:
echo "Commit fehlgeschlagen! Reason Code: $reason\n";
// Hier ggf. Rollback oder Fehlerprotokollierung
break;
default:
echo "Unbekannter Completion Code: $compCode\n";
}// Wichtig · Fallstricke
Achtung: Die mqseries-Extension ist eine PECL-Extension und muss separat installiert und in der php.ini aktiviert werden. Außerdem wird eine funktionsfähige IBM MQ Client-Installation auf dem Server benötigt.
Wird mqseries_cmit() aufgerufen, ohne dass zuvor Operationen mit dem Sync-Point-Flag (MQPMO_SYNCPOINT bzw. MQGMO_SYNCPOINT) durchgeführt wurden, hat der Aufruf keinen Effekt, ist aber nicht fehlerhaft.
Im Fehlerfall (z. B. Verbindungsverlust zum Queue Manager) sollte stets mqseries_back() aufgerufen werden, um die Arbeitseinheit explizit zurückzusetzen und inkonsistente Zustände zu vermeiden.
Die Reason Codes (z. B. MQRC_CONNECTION_BROKEN) sind als Konstanten der mqseries-Extension verfügbar und sollten für robuste Fehlerbehandlung genutzt werden.