Signatur
Beschreibung
mqseries_put1 ist eine kombinierte Operation aus MQOPEN, MQPUT und MQCLOSE in einem einzigen Aufruf. Sie eignet sich ideal, wenn nur eine einzelne Nachricht in eine Queue gestellt werden soll, ohne dass eine langlebige Queue-Handle benötigt wird. Die Funktion ist Teil der PHP-Erweiterung mqseries, die die IBM MQ (früher MQSeries) Schnittstelle für PHP bereitstellt.
Im Gegensatz zu mqseries_put, das eine bereits geöffnete Queue-Handle erwartet, übernimmt mqseries_put1 das Öffnen und Schließen der Queue intern. Das reduziert den Code-Aufwand erheblich, wenn nur sporadisch oder einmalig Nachrichten produziert werden.
Die Parameter $objDesc (MQOD – Object Descriptor) und $msgDesc (MQMD – Message Descriptor) werden als Referenz übergeben und können vom MQ-System nach dem Aufruf aktualisierte Werte enthalten (z. B. die zugewiesene MsgId). Über $pmo (Put Message Options, MQPMO) lässt sich das Verhalten des Sendevorgangs steuern (z. B. Transaktionskontext).
Nach dem Aufruf sollten $compCode und $reason geprüft werden. Ein $compCode von MQCC_OK zeigt Erfolg an; bei MQCC_FAILED enthält $reason den MQ-Reason-Code zur Fehlerdiagnose.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $hconn Pflicht | resource | Die MQ-Verbindungs-Handle, die zuvor mit mqseries_conn oder mqseries_connx erzeugt wurde. |
|
| $objDesc Pflicht | array | Referenz auf den Object Descriptor (MQOD) als assoziatives Array. Enthält mindestens den Schlüssel ObjectName mit dem Namen der Ziel-Queue. Wird nach dem Aufruf ggf. vom System aktualisiert. |
|
| $msgDesc Pflicht | array | Referenz auf den Message Descriptor (MQMD) als assoziatives Array. Steuert Nachrichteneigenschaften wie MsgType, Persistence, MsgId und CorrelId. Nach dem Aufruf enthält es die vom System zugewiesene MsgId. |
|
| $pmo Pflicht | array | Referenz auf die Put Message Options (MQPMO) als assoziatives Array. Steuert z. B. Transaktionsverhalten über den Schlüssel Options (z. B. MQPMO_NO_SYNCPOINT). |
|
| $buffer Pflicht | string | Der Inhalt der Nachricht als Zeichenkette. Kann Text oder Binärdaten enthalten. | |
| $compCode Pflicht | resource | Referenz auf eine Variable, die nach dem Aufruf den Completion Code enthält. Typische Werte: MQCC_OK (0), MQCC_WARNING (1) oder MQCC_FAILED (2). |
|
| $reason Pflicht | resource | Referenz auf eine Variable, die nach dem Aufruf den MQ Reason Code enthält. Bei Erfolg ist der Wert MQRC_NONE (0). Im Fehlerfall identifiziert er die Ursache des Problems. |
Rückgabewert
$compCode und $reason signalisiert.Beispiele
Einzelne Textnachricht in eine Queue senden
<?php
// Verbindung zum Queue Manager herstellen
mqseries_conn('QM_TEST', $hconn, $compCode, $reason);
if ($compCode !== MQCC_OK) {
die("Verbindungsfehler. Reason: $reason");
}
// Object Descriptor: Ziel-Queue definieren
$objDesc = [
'ObjectName' => 'DEV.QUEUE.1',
'ObjectType' => MQOT_Q,
];
// Message Descriptor: Nachrichteneigenschaften
$msgDesc = [
'MsgType' => MQMT_DATAGRAM,
'Persistence' => MQPER_PERSISTENT,
'Expiry' => MQEI_UNLIMITED,
];
// Put Message Options
$pmo = [
'Options' => MQPMO_NO_SYNCPOINT,
];
$messageBody = 'Hallo MQ-Welt! Zeitstempel: ' . date('Y-m-d H:i:s');
// Nachricht senden (Queue wird intern geöffnet und geschlossen)
mqseries_put1($hconn, $objDesc, $msgDesc, $pmo, $messageBody, $compCode, $reason);
if ($compCode === MQCC_OK) {
echo "Nachricht erfolgreich gesendet.\n";
echo "MsgId: " . bin2hex($msgDesc['MsgId']) . "\n";
} else {
echo "Fehler beim Senden. CompCode: $compCode, Reason: $reason\n";
}
// Verbindung trennen
mqseries_disc($hconn, $compCode, $reason);Nachricht mit Korrelations-ID für Request/Reply senden
<?php
mqseries_conn('QM_PROD', $hconn, $compCode, $reason);
if ($compCode !== MQCC_OK) {
die("Verbindungsfehler. Reason: $reason");
}
$correlId = str_pad('REQ-' . uniqid(), 24, "\0");
$objDesc = [
'ObjectName' => 'APP.REQUEST.QUEUE',
'ObjectType' => MQOT_Q,
];
$msgDesc = [
'MsgType' => MQMT_REQUEST,
'CorrelId' => $correlId,
'ReplyToQ' => 'APP.REPLY.QUEUE',
];
$pmo = [
'Options' => MQPMO_NO_SYNCPOINT | MQPMO_NEW_MSG_ID,
];
$payload = json_encode(['action' => 'getUser', 'userId' => 42]);
mqseries_put1($hconn, $objDesc, $msgDesc, $pmo, $payload, $compCode, $reason);
if ($compCode !== MQCC_OK) {
echo "Sendefehler – CompCode: $compCode, Reason: $reason\n";
} else {
echo "Request gesendet. Warte auf Antwort mit CorrelId: " . bin2hex($correlId) . "\n";
}
mqseries_disc($hconn, $compCode, $reason);// Wichtig · Fallstricke
Performance-Hinweis: Wenn viele Nachrichten hintereinander in dieselbe Queue gesendet werden müssen, ist die Kombination aus mqseries_open, mehrfachem mqseries_put und mqseries_close effizienter, da das wiederholte Öffnen und Schließen der Queue entfällt. mqseries_put1 ist ausdrücklich für den Einmal-Versand konzipiert.
Transaktionen: Bei Verwendung von MQPMO_SYNCPOINT in den Put Message Options wird die Nachricht erst nach einem expliziten mqseries_cmit (Commit) dauerhaft in die Queue eingestellt. Ein mqseries_back (Rollback) macht den Vorgang rückgängig.
Fehlerbehandlung: Der Rückgabewert der Funktion ist immer null/void. Fehler werden ausschließlich über $compCode und $reason signalisiert – eine fehlende Prüfung dieser Werte führt zu schwer diagnostizierbaren Datenverlust-Szenarien.