mqseries_begin — Funktion · PHP-Referenz

Signatur

mqseries_begin(resource $hconn, array $beginOptions, resource &$compCode, resource &$reason): void

Beschreibung

mqseries_begin ruft den IBM MQ-Befehl MQBEGIN auf und markiert den Beginn einer neuen Arbeitseinheit (Unit of Work) innerhalb einer bestehenden MQ-Verbindung. Alle nachfolgenden mqseries_put- und mqseries_get-Operationen werden in diese Transaktion einbezogen, bis sie entweder mit mqseries_cmit bestätigt oder mit mqseries_back zurückgerollt wird.

Diese Funktion wird typischerweise in Szenarien eingesetzt, in denen eine atomare Verarbeitung mehrerer Nachrichten erforderlich ist – etwa bei der Übertragung von Bestelldaten oder Finanztransaktionen, bei denen Teilerfolge verhindert werden müssen. Nur wenn alle Schritte erfolgreich sind, wird die gesamte Einheit mit mqseries_cmit committed.

Nach dem Aufruf sollten die Rückgabewerte $compCode und $reason immer geprüft werden: Ein Completion Code von MQCC_OK (0) signalisiert Erfolg, während MQCC_FAILED (2) auf einen Fehler hinweist. Der Reason Code liefert dann genauere Informationen zur Fehlerursache.

Die Funktion setzt voraus, dass eine aktive Verbindung zu einem IBM MQ Queue Manager besteht, die zuvor mit mqseries_conn oder mqseries_connx hergestellt wurde. Nicht alle Queue Manager oder Transaktions-Manager unterstützen MQBEGIN; in solchen Fällen liefert $reason einen entsprechenden Fehlercode.

Parameter

Name	Typ	Beschreibung
$hconn Pflicht	resource	Das Verbindungs-Handle zum IBM MQ Queue Manager, das von `mqseries_conn` oder `mqseries_connx` zurückgegeben wurde.
$beginOptions Pflicht	array	Ein assoziatives Array mit MQBO-Optionen (Begin Options). Für die meisten Anwendungsfälle kann ein leeres Array `[]` oder `array('Options' => MQSERIES_MQBO_NONE)` übergeben werden.
$compCode Pflicht	resource	Wird nach dem Aufruf mit dem Completion Code befüllt. Mögliche Werte: `MQCC_OK` (0), `MQCC_WARNING` (1) oder `MQCC_FAILED` (2).
$reason Pflicht	resource	Wird nach dem Aufruf mit dem Reason Code befüllt, der im Fehlerfall (`MQCC_FAILED`) die genaue Ursache beschreibt. Bei Erfolg enthält dieser `MQRC_NONE` (0).

Rückgabewert

Typ

void

Beschreibung

Diese Funktion gibt keinen Wert zurück. Der Erfolg oder Misserfolg wird ausschließlich über die Referenzparameter $compCode und $reason kommuniziert.

Beispiele

Transaktion starten, Nachrichten senden und bestätigen

<?php
// Verbindung zum Queue Manager herstellen
mqseries_conn('QM_TEST', $hconn, $compCode, $reason);

if ($compCode !== MQSERIES_MQCC_OK) {
    die("Verbindung fehlgeschlagen. Reason: $reason");
}

// Queue öffnen
$mdesc = [];
$odesc = ['ObjectName' => 'TEST.QUEUE'];
mqseries_open(
    $hconn,
    $odesc,
    MQSERIES_MQOO_OUTPUT,
    $hobj,
    $compCode,
    $reason
);

if ($compCode !== MQSERIES_MQCC_OK) {
    die("Queue öffnen fehlgeschlagen. Reason: $reason");
}

// Transaktion beginnen
mqseries_begin($hconn, [], $compCode, $reason);

if ($compCode !== MQSERIES_MQCC_OK) {
    echo "MQBEGIN fehlgeschlagen. CompCode: $compCode, Reason: $reason\n";
    mqseries_disc($hconn, $compCode, $reason);
    exit;
}

echo "Transaktion gestartet.\n";

// Nachricht in die Queue schreiben
$pmo = ['Options' => MQSERIES_MQPMO_SYNCPOINT];
mqseries_put($hconn, $hobj, $mdesc, $pmo, 'Testinhalt der Nachricht', $compCode, $reason);

if ($compCode !== MQSERIES_MQCC_OK) {
    echo "PUT fehlgeschlagen – Transaktion wird zurückgerollt. Reason: $reason\n";
    mqseries_back($hconn, $compCode, $reason);
} else {
    // Transaktion bestätigen
    mqseries_cmit($hconn, $compCode, $reason);
    echo "Transaktion erfolgreich committed.\n";
}

// Queue und Verbindung schließen
mqseries_close($hconn, $hobj, MQSERIES_MQCO_NONE, $compCode, $reason);
mqseries_disc($hconn, $compCode, $reason);

Transaktion gestartet. transaktion erfolgreich committed.

Fehlerbehandlung bei nicht unterstütztem MQBEGIN

<?php
mqseries_conn('QM_TEST', $hconn, $compCode, $reason);

// Transaktion beginnen und Fehlercode prüfen
mqseries_begin($hconn, ['Options' => MQSERIES_MQBO_NONE], $compCode, $reason);

switch ($compCode) {
    case MQSERIES_MQCC_OK:
        echo "MQBEGIN erfolgreich.\n";
        break;
    case MQSERIES_MQCC_WARNING:
        echo "MQBEGIN mit Warnung. Reason: $reason\n";
        break;
    case MQSERIES_MQCC_FAILED:
        echo "MQBEGIN fehlgeschlagen. Reason Code: $reason\n";
        // Typischer Fehler: MQRC_ENVIRONMENT_ERROR (2012)
        // wenn der Queue Manager keine externen Transaktionen unterstützt
        break;
}

mqseries_disc($hconn, $compCode, $reason);

MQBEGIN erfolgreich.

// Wichtig · Fallstricke

Wichtig: mqseries_begin erfordert, dass der Queue Manager und die Umgebung externe Transaktionskoordination (XA-Protokoll) unterstützen. Wird die Funktion auf einem Queue Manager aufgerufen, der dies nicht unterstützt, liefert $reason den Code MQRC_ENVIRONMENT_ERROR (2012).

Jede mit mqseries_begin gestartete Transaktion muss mit einem expliziten mqseries_cmit (Commit) oder mqseries_back (Rollback) abgeschlossen werden, bevor die Verbindung getrennt wird. Andernfalls rollt IBM MQ offene Transaktionen beim Trennen der Verbindung automatisch zurück.

Die Funktion steht nur zur Verfügung, wenn die PHP-MQSeries-Erweiterung (ext/mqseries) installiert und konfiguriert ist sowie die IBM MQ Client-Bibliotheken auf dem System vorhanden sind.

Siehe auch

mqseries_conn mqseries_connx mqseries_cmit mqseries_back mqseries_put mqseries_get mqseries_disc