Signatur
Beschreibung
mqseries_get liest eine Nachricht aus einer zuvor geöffneten IBM MQ-Queue. Die Funktion entspricht dem nativen MQGET-Aufruf der IBM MQ (früher WebSphere MQ) C-Bibliothek und wird über die PECL-Erweiterung mqseries bereitgestellt.
Vor dem Aufruf muss eine Verbindung zum Queue-Manager mit mqseries_conn oder mqseries_connx sowie eine geöffnete Queue mit mqseries_open (mit Leseberechtigung) vorliegen. Die Nachrichtenstruktur (Message Descriptor, $md) und die Get-Message-Optionen ($gmo) werden als assoziative Arrays übergeben und können nach dem Aufruf aktualisierte Werte enthalten.
Nach dem Aufruf sollten $compCode und $reason geprüft werden. Ein Completion Code von MQCC_OK (0) signalisiert Erfolg, MQCC_WARNING (1) eine Warnung, MQCC_FAILED (2) einen Fehler. Der Reason Code gibt nähere Auskunft – z. B. MQRC_NO_MSG_AVAILABLE (2033), wenn keine Nachricht in der Queue vorhanden ist.
Die Funktion ist besonders geeignet für Unternehmensanwendungen, die mit IBM MQ-Middleware kommunizieren müssen, etwa für asynchrone Nachrichtenverarbeitung, Workflow-Integration oder zuverlässige Punkt-zu-Punkt-Kommunikation.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $hConn Pflicht | resource | Verbindungs-Handle zum Queue-Manager, das von mqseries_conn oder mqseries_connx zurückgegeben wurde. |
|
| $hObj Pflicht | resource | Objekt-Handle der geöffneten Queue, das von mqseries_open mit Lesezugriff (MQOO_INPUT_AS_Q_DEF o. ä.) zurückgegeben wurde. |
|
| $md Pflicht | array | Referenz auf ein assoziatives Array, das den Message Descriptor (MQMD) beschreibt. Enthält nach dem Aufruf die Metadaten der empfangenen Nachricht, z. B. MsgId, CorrelId, Format. |
|
| $gmo Pflicht | array | Referenz auf ein assoziatives Array mit den Get-Message-Optionen (MQGMO), z. B. Options (MQGMO_WAIT, MQGMO_NO_WAIT), WaitInterval (Wartezeit in Millisekunden). |
|
| $bufferLength Pflicht | int | Referenz auf die maximale Größe des Empfangspuffers in Bytes. Ist die Nachricht größer als dieser Wert, schlägt der Aufruf mit MQRC_TRUNCATED_MSG_FAILED fehl. |
|
| $msg Pflicht | string | Referenz auf den String, in den der Nachrichteninhalt nach erfolgreichem Aufruf geschrieben wird. | |
| $dataLength Pflicht | int | Referenz auf einen Integer, der nach dem Aufruf die tatsächliche Länge der empfangenen Nachrichtendaten in Bytes enthält. | |
| $compCode Pflicht | resource | Referenz auf den Completion Code. Nach dem Aufruf enthält die Variable den Statuscode: MQCC_OK (0), MQCC_WARNING (1) oder MQCC_FAILED (2). |
|
| $reason Pflicht | resource | Referenz auf den Reason Code, der im Fehlerfall eine genauere Fehlerursache liefert, z. B. MQRC_NO_MSG_AVAILABLE (2033) wenn keine Nachricht verfügbar ist. |
Rückgabewert
$compCode und $reason signalisiert.Beispiele
Einfaches Lesen einer Nachricht aus einer MQ-Queue
<?php
// Verbindung zum Queue-Manager herstellen
mqseries_conn('QM_TEST', $hConn, $compCode, $reason);
if ($compCode !== MQCC_OK) {
echo "Verbindungsfehler. Reason: $reason\n";
exit;
}
// Queue öffnen (Lesezugriff)
$od = [
'ObjectName' => 'TEST.QUEUE',
'ObjectType' => MQOT_Q,
];
mqseries_open($hConn, $od, MQOO_INPUT_AS_Q_DEF | MQOO_FAIL_IF_QUIESCING, $hObj, $compCode, $reason);
if ($compCode !== MQCC_OK) {
echo "Queue-Open-Fehler. Reason: $reason\n";
mqseries_disc($hConn, $compCode, $reason);
exit;
}
// Nachricht empfangen
$md = ['Version' => MQMD_VERSION_1];
$gmo = ['Options' => MQGMO_NO_WAIT, 'Version' => MQGMO_VERSION_2];
$bufferLength = 10240;
$msg = '';
$dataLength = 0;
mqseries_get($hConn, $hObj, $md, $gmo, $bufferLength, $msg, $dataLength, $compCode, $reason);
if ($compCode === MQCC_OK) {
echo "Empfangene Nachricht ($dataLength Bytes): " . $msg . "\n";
} elseif ($reason === MQRC_NO_MSG_AVAILABLE) {
echo "Keine Nachricht in der Queue verfügbar.\n";
} else {
echo "Fehler beim Empfangen. CompCode: $compCode, Reason: $reason\n";
}
// Queue schließen und Verbindung trennen
mqseries_close($hConn, $hObj, MQCO_NONE, $compCode, $reason);
mqseries_disc($hConn, $compCode, $reason);Nachricht mit Wartezeit (MQGMO_WAIT) empfangen
<?php
// Verbindung und Queue-Open wie im obigen Beispiel (hier ausgelassen) ...
// GMO mit Wartezeit von 5 Sekunden (5000 ms)
$md = ['Version' => MQMD_VERSION_1];
$gmo = [
'Options' => MQGMO_WAIT,
'WaitInterval' => 5000,
'Version' => MQGMO_VERSION_2,
];
$bufferLength = 65536;
$msg = '';
$dataLength = 0;
mqseries_get($hConn, $hObj, $md, $gmo, $bufferLength, $msg, $dataLength, $compCode, $reason);
if ($compCode === MQCC_OK) {
echo "Nachricht erhalten: " . substr($msg, 0, $dataLength) . "\n";
echo "Message-ID: " . bin2hex($md['MsgId']) . "\n";
} elseif ($reason === MQRC_NO_MSG_AVAILABLE) {
echo "Timeout: Keine Nachricht innerhalb von 5 Sekunden eingegangen.\n";
} else {
echo "Fehler: CompCode=$compCode, Reason=$reason\n";
}// Wichtig · Fallstricke
Erweiterung erforderlich: mqseries_get ist Teil der PECL-Erweiterung mqseries, die separat installiert werden muss und eine installierte IBM MQ-Client-Bibliothek voraussetzt.
Puffergröße: Wenn $bufferLength kleiner als die tatsächliche Nachrichtengröße ist, schlägt der Aufruf mit Reason Code MQRC_TRUNCATED_MSG_FAILED (2079) fehl. Wähle den Puffer ausreichend groß oder reagiere auf diesen Reason Code mit einem erneuten Aufruf mit angepasster Puffergröße.
Transaktionssteuerung: Soll die Nachricht erst nach erfolgreicher Verarbeitung aus der Queue entfernt werden, nutze die Option MQGMO_SYNCPOINT in Kombination mit mqseries_back (Rollback) oder mqseries_cmit (Commit).
Kein direktes Fehler-Exception-Handling: Die Funktion wirft keine PHP-Exceptions. Prüfe immer $compCode und $reason nach jedem Aufruf.