Signatur
Beschreibung
mqseries_put ist Teil der PHP-MQSeries-Erweiterung und ermöglicht das Senden einer Nachricht an eine IBM MQ (früher MQSeries) Queue. Die Funktion kapselt den nativen MQPUT-API-Aufruf und ist somit der zentrale Baustein für das Produzieren von Nachrichten in einem IBM-MQ-basierten Messaging-System.
Vor dem Aufruf muss eine Verbindung zur Queue-Manager-Instanz mit mqseries_conn oder mqseries_connx hergestellt und die Ziel-Queue mit mqseries_open geöffnet worden sein. Das Message-Descriptor-Array ($md) beschreibt Metadaten der Nachricht (z. B. Format, Persistenz, Priorität), während das Put-Message-Options-Array ($pmo) steuert, wie die Nachricht in die Queue gelegt wird (z. B. synchroner Commit).
Nach dem Aufruf sollten stets $compCode und $reason geprüft werden: $compCode gibt an, ob der Aufruf erfolgreich war (MQCC_OK), eine Warnung vorliegt (MQCC_WARNING) oder ein Fehler aufgetreten ist (MQCC_FAILED). Der $reason-Code liefert im Fehlerfall einen spezifischen IBM-MQ-Reason-Code zur Fehlerdiagnose.
Die Funktion eignet sich für alle Szenarien, in denen PHP-Anwendungen Nachrichten asynchron an Backend-Systeme oder andere Anwendungen über IBM MQ übergeben sollen, z. B. bei der Integration in Enterprise-Service-Bus-Architekturen oder bei der Kommunikation mit Mainframe-Systemen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $hConn Pflicht | resource | Verbindungs-Handle zur IBM MQ Queue-Manager-Instanz, wie es von mqseries_conn oder mqseries_connx zurückgegeben wird. |
|
| $hObj Pflicht | resource | Objekt-Handle der geöffneten Queue, wie es von mqseries_open zurückgegeben wird. Die Queue muss mit entsprechenden Schreibrechten geöffnet worden sein. |
|
| $md Pflicht | array | Message Descriptor (MQMD) als assoziatives Array. Enthält Nachrichtenmetadaten wie Format, MsgType, Persistence, Priority oder CorrelId. Wird nach dem Aufruf mit vom Queue-Manager gesetzten Werten (z. B. MsgId) aktualisiert. |
|
| $pmo Pflicht | array | Put Message Options (MQPMO) als assoziatives Array. Steuert das Verhalten beim Einreihen der Nachricht, z. B. ob die Operation unter einer Transaktion (MQPMO_SYNCPOINT) oder ohne (MQPMO_NO_SYNCPOINT) durchgeführt wird. |
|
| $message Pflicht | string | Der eigentliche Nachrichteninhalt (Payload) als String. Kann beliebige binäre oder textuelle Daten enthalten. | |
| $compCode Pflicht | int | Referenz-Variable, die nach dem Aufruf den Completion Code enthält. Mögliche Werte: MQCC_OK (0), MQCC_WARNING (1), MQCC_FAILED (2). |
|
| $reason Pflicht | int | Referenz-Variable, die nach dem Aufruf den IBM-MQ-Reason-Code enthält. Bei Erfolg ist der Wert MQRC_NONE (0). Im Fehlerfall gibt er den genauen Grund des Fehlers an. |
Rückgabewert
$compCode und $reason signalisiert.Beispiele
Einfache Nachricht an eine IBM MQ Queue senden
<?php
// Verbindung zum Queue-Manager herstellen
mqseries_conn('QM_TEST', $hConn, $compCode, $reason);
if ($compCode !== MQCC_OK) {
die("Verbindung fehlgeschlagen. Reason: $reason");
}
// Queue zum Schreiben öffnen
$openOptions = MQOO_OUTPUT | MQOO_FAIL_IF_QUIESCING;
mqseries_open(
$hConn,
['ObjectName' => 'DEV.QUEUE.1', 'ObjectType' => MQOT_Q],
$openOptions,
$hObj,
$compCode,
$reason
);
if ($compCode !== MQCC_OK) {
die("Queue öffnen fehlgeschlagen. Reason: $reason");
}
// Message Descriptor vorbereiten
$md = [
'Format' => MQFMT_STRING,
'Persistence' => MQPER_PERSISTENT,
'MsgType' => MQMT_DATAGRAM,
];
// Put Message Options festlegen
$pmo = [
'Options' => MQPMO_NO_SYNCPOINT | MQPMO_FAIL_IF_QUIESCING,
];
// Nachricht senden
$message = 'Hallo von PHP!';
mqseries_put($hConn, $hObj, $md, $pmo, $message, $compCode, $reason);
if ($compCode === MQCC_OK) {
echo "Nachricht erfolgreich gesendet. MsgId: " . bin2hex($md['MsgId']) . PHP_EOL;
} else {
echo "Fehler beim Senden. CompCode: $compCode, Reason: $reason" . PHP_EOL;
}
// Ressourcen freigeben
mqseries_close($hConn, $hObj, MQCO_NONE, $compCode, $reason);
mqseries_disc($hConn, $compCode, $reason);Nachricht mit Korrelations-ID und JSON-Payload senden
<?php
// Voraussetzung: $hConn und $hObj wurden bereits geöffnet (siehe erstes Beispiel)
$correlId = str_pad('REQ-20240101-001', 24, "\0");
$md = [
'Format' => MQFMT_STRING,
'Persistence' => MQPER_NOT_PERSISTENT,
'MsgType' => MQMT_REQUEST,
'CorrelId' => $correlId,
'ReplyToQ' => 'DEV.REPLY.QUEUE',
];
$pmo = [
'Options' => MQPMO_SYNCPOINT | MQPMO_FAIL_IF_QUIESCING,
];
$payload = json_encode([
'action' => 'getKundenDaten',
'kundeId' => 42,
]);
mqseries_put($hConn, $hObj, $md, $pmo, $payload, $compCode, $reason);
if ($compCode === MQCC_OK) {
// Transaktion committen
mqseries_cmit($hConn, $compCode, $reason);
echo "JSON-Nachricht gesendet und committet." . PHP_EOL;
} else {
// Transaktion zurückrollen
mqseries_back($hConn, $compCode, $reason);
echo "Fehler: CompCode=$compCode, Reason=$reason – Rollback durchgeführt." . PHP_EOL;
}// Wichtig · Fallstricke
Fehlerbehandlung: Da mqseries_put keinen Rückgabewert liefert, ist die Prüfung von $compCode und $reason nach jedem Aufruf zwingend erforderlich. Ohne diese Prüfung können fehlgeschlagene Sends unbemerkt bleiben.
Transaktionssicherheit: Wenn MQPMO_SYNCPOINT verwendet wird, muss nach erfolgreichem Senden mqseries_cmit aufgerufen werden, um die Nachricht tatsächlich in die Queue einzureihen. Bei einem Fehler sollte mqseries_back zum Rollback verwendet werden.
Ressourcen-Leaks: Handles ($hObj, $hConn) sollten nach der Verwendung immer mit mqseries_close und mqseries_disc freigegeben werden, auch im Fehlerfall – am besten über try/finally-Konstrukte.
Erweiterung: Die MQSeries-PHP-Erweiterung (mqseries) ist keine Core-Erweiterung und muss separat installiert werden (PECL). Sie ist eng an das IBM MQ Client-SDK gebunden, das ebenfalls auf dem System vorhanden sein muss.