Signatur
Beschreibung
mqseries_open() bildet den IBM MQSeries-API-Aufruf MQOPEN in PHP ab. Die Funktion öffnet ein zuvor definiertes MQ-Objekt (typischerweise eine Nachrichtenwarteschlange) über eine bereits bestehende Verbindungsressource und liefert ein Handle, das für nachfolgende Operationen wie mqseries_put() oder mqseries_get() benötigt wird.
Das Verhalten des Öffnens wird durch den Parameter option gesteuert. Typische Optionen sind MQSERIES_MQOO_OUTPUT zum Schreiben, MQSERIES_MQOO_INPUT_AS_Q_DEF zum Lesen oder eine Kombination beider Flags mittels bitweisem OR. Das Objekt-Deskriptor-Array objDesc beschreibt das zu öffnende MQ-Objekt, insbesondere den Warteschlangennamen (ObjectName) und gegebenenfalls den Queue-Manager-Namen (ObjectQMgrName).
Nach dem Aufruf enthalten compCode (Completion Code) und reason (Reason Code) Statusinformationen. Ein compCode von MQSERIES_MQCC_OK signalisiert Erfolg. Bei Fehlern sollte der reason-Code zur Diagnose herangezogen werden. Das erzeugte Handle hObj muss nach Verwendung mit mqseries_close() wieder freigegeben werden.
Diese Funktion setzt die Installation der PECL-Erweiterung mqseries sowie einen erreichbaren IBM MQ Queue Manager voraus. Sie eignet sich für PHP-Anwendungen, die direkt mit IBM MQ kommunizieren müssen, etwa in Enterprise-Integrationsszenarien.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $hConn Pflicht | resource | Verbindungshandle, das zuvor durch mqseries_conn() oder mqseries_connx() erzeugt wurde. |
|
| $objDesc Pflicht | array | Referenz auf ein assoziatives Array, das den Objekt-Deskriptor (MQOD) beschreibt. Pflichtschlüssel ist typischerweise ObjectName mit dem Namen der Warteschlange. Optional können weitere Felder wie ObjectQMgrName angegeben werden. |
|
| $option Pflicht | int | Bitmaske der Öffnungsoptionen, z. B. MQSERIES_MQOO_OUTPUT zum Schreiben, MQSERIES_MQOO_INPUT_AS_Q_DEF zum Lesen. Mehrere Optionen werden per bitweisem OR verknüpft. |
|
| $hObj Pflicht | resource | Referenz auf eine Variable, die nach erfolgreichem Aufruf das Handle des geöffneten MQ-Objekts enthält. Dieses Handle wird für mqseries_put(), mqseries_get() und mqseries_close() benötigt. |
|
| $compCode Pflicht | int | Referenz auf eine Variable, die nach dem Aufruf den Completion Code enthält. MQSERIES_MQCC_OK steht für Erfolg, MQSERIES_MQCC_FAILED für einen Fehler. |
|
| $reason Pflicht | int | Referenz auf eine Variable, die nach dem Aufruf den Reason Code enthält. Dieser Code liefert detaillierte Fehlerinformationen, falls compCode ungleich MQSERIES_MQCC_OK ist. |
Rückgabewert
compCode und reason kommuniziert.Beispiele
Warteschlange zum Schreiben öffnen und Nachricht senden
<?php
// Verbindung zum Queue Manager herstellen
mqseries_conn('QM_TEST', $hConn, $compCode, $reason);
if ($compCode !== MQSERIES_MQCC_OK) {
die("Verbindung fehlgeschlagen. Reason: $reason");
}
// Objekt-Deskriptor für die Ziel-Queue
$objDesc = [
'ObjectName' => 'TEST.QUEUE',
'ObjectQMgrName' => 'QM_TEST',
];
// Queue zum Schreiben öffnen
mqseries_open(
$hConn,
$objDesc,
MQSERIES_MQOO_OUTPUT | MQSERIES_MQOO_FAIL_IF_QUIESCING,
$hObj,
$compCode,
$reason
);
if ($compCode !== MQSERIES_MQCC_OK) {
die("MQOPEN fehlgeschlagen. Reason: $reason");
}
// Nachricht in die Queue schreiben
$msgDesc = [];
$pmo = ['Options' => MQSERIES_MQPMO_NO_SYNCPOINT];
mqseries_put($hConn, $hObj, $msgDesc, $pmo, 'Hallo MQ!', $compCode, $reason);
if ($compCode !== MQSERIES_MQCC_OK) {
echo "MQPUT fehlgeschlagen. Reason: $reason\n";
} else {
echo "Nachricht erfolgreich gesendet.\n";
}
// Queue-Handle schließen
mqseries_close($hConn, $hObj, MQSERIES_MQCO_NONE, $compCode, $reason);
// Verbindung trennen
mqseries_disc($hConn, $compCode, $reason);Warteschlange zum Lesen öffnen und Nachricht empfangen
<?php
mqseries_conn('QM_TEST', $hConn, $compCode, $reason);
if ($compCode !== MQSERIES_MQCC_OK) {
die("Verbindung fehlgeschlagen. Reason: $reason");
}
$objDesc = ['ObjectName' => 'TEST.QUEUE'];
// Queue zum Lesen öffnen
mqseries_open(
$hConn,
$objDesc,
MQSERIES_MQOO_INPUT_AS_Q_DEF | MQSERIES_MQOO_FAIL_IF_QUIESCING,
$hObj,
$compCode,
$reason
);
if ($compCode !== MQSERIES_MQCC_OK) {
die("MQOPEN zum Lesen fehlgeschlagen. Reason: $reason");
}
$msgDesc = [];
$gmo = ['Options' => MQSERIES_MQGMO_NO_WAIT];
$msg = '';
$datalen = 0;
mqseries_get($hConn, $hObj, $msgDesc, $gmo, 1024, $msg, $datalen, $compCode, $reason);
if ($compCode === MQSERIES_MQCC_OK) {
echo "Empfangene Nachricht: $msg\n";
} elseif ($reason === MQSERIES_MQRC_NO_MSG_AVAILABLE) {
echo "Keine Nachricht verfügbar.\n";
} else {
echo "MQGET fehlgeschlagen. Reason: $reason\n";
}
mqseries_close($hConn, $hObj, MQSERIES_MQCO_NONE, $compCode, $reason);
mqseries_disc($hConn, $compCode, $reason);// Wichtig · Fallstricke
Fehlerbehandlung: Da mqseries_open() keinen Rückgabewert liefert, muss nach jedem Aufruf zwingend compCode geprüft werden. Ein nicht behandelter Fehler führt dazu, dass das Handle hObj ungültig ist und nachfolgende Operationen fehlschlagen oder einen fatalen Fehler erzeugen.
Ressourcen-Management: Jedes erfolgreich mit mqseries_open() geöffnete Handle muss mit mqseries_close() geschlossen werden, um Queue-Manager-seitige Ressourcen freizugeben. Das Vergessen dieses Schritts kann zu Handle-Erschöpfung am Queue Manager führen.
Voraussetzungen: Die PECL-Erweiterung mqseries und der IBM MQ Client müssen installiert und korrekt konfiguriert sein. Die Erweiterung ist nicht im Standard-PHP-Paket enthalten und wird nicht aktiv weiterentwickelt; für neuere IBM-MQ-Versionen sollte die Kompatibilität sorgfältig geprüft werden.