Signatur
Beschreibung
mqseries_conn stellt eine Verbindung zu einem IBM MQ (Message Queue) Queue-Manager her. Die Funktion ist der PHP-Wrapper für den nativen IBM MQ API-Aufruf MQCONN. Nach einem erfolgreichen Aufruf steht ein Verbindungs-Handle ($hconn) zur Verfügung, das für alle weiteren MQ-Operationen wie das Öffnen von Queues, das Senden und Empfangen von Nachrichten benötigt wird.
Der Verbindungsaufbau ist der erste Schritt in einem typischen IBM-MQ-Workflow: mqseries_conn → mqseries_open → mqseries_put/mqseries_get → mqseries_close → mqseries_disc. Die Verbindung sollte nach Abschluss der Arbeit immer mit mqseries_disc sauber getrennt werden, um Ressourcen freizugeben.
Der Erfolg oder Misserfolg des Aufrufs ist anhand der Ausgabeparameter $compCode (Completion Code) und $reason (Reason Code) zu prüfen. Ein $compCode von MQCC_OK (0) bedeutet Erfolg, während MQCC_WARNING (1) oder MQCC_FAILED (2) auf Probleme hinweisen. Weitere Details liefert dann der $reason-Code, der mit mqseries_strerror in einen lesbaren Text umgewandelt werden kann.
Die Funktion setzt die PHP-Erweiterung mqseries sowie eine installierte IBM MQ Client-Bibliothek auf dem Server voraus.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $qManagerName Pflicht | string | Name des Queue-Managers, zu dem die Verbindung hergestellt werden soll. Bei einer leeren Zeichenkette ('') wird der Standard-Queue-Manager der lokalen MQ-Installation verwendet. |
|
| $hconn Pflicht | resource | Ausgabe-Parameter (by Reference): Enthält nach einem erfolgreichen Aufruf das Verbindungs-Handle, das für alle weiteren MQ-Funktionsaufrufe benötigt wird. | |
| $compCode Pflicht | resource | Ausgabe-Parameter (by Reference): Enthält nach dem Aufruf den Completion Code (MQCC_OK, MQCC_WARNING oder MQCC_FAILED). |
|
| $reason Pflicht | resource | Ausgabe-Parameter (by Reference): Enthält nach dem Aufruf den Reason Code, der den Completion Code näher beschreibt. Mit mqseries_strerror($reason) kann ein lesbarer Fehlertext erzeugt werden. |
Rückgabewert
$compCode und $reason signalisiert.Beispiele
Verbindung zum Standard-Queue-Manager herstellen
<?php
// Verbindung zum Standard-Queue-Manager herstellen
mqseries_conn('', $hconn, $compCode, $reason);
if ($compCode !== MQCC_OK) {
printf(
"mqseries_conn Fehler: CompCode=%d, Reason=%d (%s)\n",
$compCode,
$reason,
mqseries_strerror($reason)
);
exit(1);
}
echo "Verbindung erfolgreich hergestellt. Handle: " . print_r($hconn, true) . "\n";
// ... weitere MQ-Operationen ...
// Verbindung sauber trennen
mqseries_disc($hconn, $compCode, $reason);
echo "Verbindung getrennt.\n";Verbindung zu einem benannten Queue-Manager und Nachricht senden
<?php
$qManagerName = 'MY.QMGR';
$queueName = 'MY.TEST.QUEUE';
// Schritt 1: Verbindung herstellen
mqseries_conn($qManagerName, $hconn, $compCode, $reason);
if ($compCode !== MQCC_OK) {
die(sprintf(
"Verbindungsfehler: Reason %d - %s\n",
$reason,
mqseries_strerror($reason)
));
}
// Schritt 2: Queue öffnen
$mqods = [
'ObjectName' => $queueName,
'ObjectQMgrName' => '',
];
mqseries_open(
$hconn,
$mqods,
MQOO_INPUT_AS_Q_DEF | MQOO_FAIL_IF_QUIESCING | MQOO_OUTPUT,
$hobj,
$compCode,
$reason
);
if ($compCode !== MQCC_OK) {
mqseries_disc($hconn, $compCode, $reason);
die(sprintf(
"Queue öffnen fehlgeschlagen: Reason %d - %s\n",
$reason,
mqseries_strerror($reason)
));
}
// Schritt 3: Nachricht senden
$mqmd = [];
$mqpmo = ['Options' => MQPMO_NEW_MSG_ID | MQPMO_NEW_CORREL_ID];
mqseries_put($hconn, $hobj, $mqmd, $mqpmo, 'Hallo, IBM MQ!', $compCode, $reason);
if ($compCode === MQCC_OK) {
echo "Nachricht erfolgreich gesendet.\n";
} else {
echo sprintf("Sende-Fehler: %d - %s\n", $reason, mqseries_strerror($reason));
}
// Aufräumen
mqseries_close($hconn, $hobj, MQCO_NONE, $compCode, $reason);
mqseries_disc($hconn, $compCode, $reason);
echo "Verbindung getrennt.\n";// Wichtig · Fallstricke
Voraussetzungen: Die PHP-Erweiterung mqseries muss installiert und aktiviert sein (extension=mqseries in der php.ini). Zusätzlich muss der IBM MQ Client auf dem System installiert sein und die Umgebungsvariablen (z. B. MQ_INSTALLATION_PATH) müssen korrekt gesetzt sein.
Ressourcen-Verwaltung: Jede mit mqseries_conn geöffnete Verbindung muss am Ende mit mqseries_disc explizit getrennt werden, da MQ-Verbindungen sonst bis zum Ablauf eines Timeouts auf dem Queue-Manager bestehen bleiben und Ressourcen belegen.
Fehlerbehandlung: Da die Funktion void zurückgibt, ist das Prüfen von $compCode und $reason nach jedem Aufruf zwingend erforderlich. Der Reason Code MQRC_Q_MGR_NOT_AVAILABLE (2059) ist ein häufiger Fehler und deutet darauf hin, dass der Queue-Manager nicht läuft oder nicht erreichbar ist.