mqseries_connx — Funktion · PHP-Referenz

Signatur

mqseries_connx(string $qManagerName, array &$connOptions, resource &$hconn, resource &$compCode, resource &$reason): void

Beschreibung

mqseries_connx() stellt eine Verbindung zu einem IBM MQ (früher WebSphere MQ) Queue-Manager her und entspricht dem nativen MQ-API-Aufruf MQCONNX. Im Gegensatz zu mqseries_conn() erlaubt diese Funktion die Übergabe eines Verbindungsoptionen-Arrays ($connOptions), über das erweiterte Parameter wie Kanäle, Verbindungs-Modi, Sicherheitsoptionen und Client-Definitionen konfiguriert werden können.

Die Verbindungsoptionen werden als assoziatives Array übergeben, das MQ-spezifische Strukturen wie MQCNO (Connection Options) abbildet. Über dieses Array lässt sich z. B. eine Client-Verbindung (MQCNO_CLIENT_BINDING) oder eine lokale Bindung (MQCNO_LOCAL_BINDING) erzwingen sowie eine MQCD-Struktur für Kanal-Details einbetten.

Nach einem erfolgreichen Aufruf enthält $hconn ein Connection-Handle, das für alle weiteren MQ-Operationen (z. B. mqseries_open(), mqseries_put(), mqseries_get()) benötigt wird. $compCode und $reason geben den Completion Code (0 = OK, 1 = Warning, 2 = Fehler) bzw. den Reason Code des MQ-Systems zurück und müssen nach jedem Aufruf überprüft werden.

Diese Funktion setzt die PHP-Erweiterung mqseries voraus, die gegen die IBM MQ Client-Bibliotheken kompiliert sein muss. Sie eignet sich besonders für Szenarien, in denen zur Laufzeit unterschiedliche Queue-Manager oder Kanaleinstellungen verwendet werden sollen.

Parameter

Name	Typ	Beschreibung
$qManagerName Pflicht	string	Name des IBM MQ Queue-Managers, zu dem die Verbindung hergestellt werden soll. Ein leerer String verbindet mit dem Standard-Queue-Manager.
$connOptions Pflicht	array	Assoziatives Array mit erweiterten Verbindungsoptionen (entspricht der MQ-Struktur `MQCNO`). Kann u. a. Schlüssel wie `Options`, `ClientConn` (für `MQCD`-Details wie `ChannelName`, `TransportType`, `ConnectionName`) enthalten. Wird als Referenz übergeben.
$hconn Pflicht	resource	Ausgabe-Parameter: Enthält nach erfolgreichem Aufruf das Connection-Handle (`MQHCONN`), das für alle nachfolgenden MQ-Operationen benötigt wird. Wird als Referenz übergeben.
$compCode Pflicht	resource	Ausgabe-Parameter: Enthält nach dem Aufruf den MQ Completion Code (`MQCC_OK` = 0, `MQCC_WARNING` = 1, `MQCC_FAILED` = 2). Wird als Referenz übergeben.
$reason Pflicht	resource	Ausgabe-Parameter: Enthält nach dem Aufruf den MQ Reason Code, der bei Fehlern oder Warnungen den genauen Grund angibt (z. B. `MQRC_Q_MGR_NOT_AVAILABLE`). Wird als Referenz übergeben.

Rückgabewert

Typ

void

Beschreibung

Die Funktion gibt keinen Rückgabewert zurück. Erfolg und Fehler werden ausschließlich über die Referenzparameter $compCode und $reason kommuniziert.

Beispiele

Lokale Verbindung zu einem Queue-Manager herstellen

<?php
// Verbindungsoptionen für eine lokale Bindung
$connOptions = [
    'Options' => MQSERIES_MQCNO_STANDARD_BINDING,
];

mqseries_connx(
    'MY.QMGR',
    $connOptions,
    $hconn,
    $compCode,
    $reason
);

if ($compCode !== MQSERIES_MQCC_OK) {
    printf(
        "Verbindung fehlgeschlagen: 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 trennen
mqseries_disc($hconn, $compCode, $reason);
?>

Verbindung erfolgreich hergestellt. Handle: Resource id #1

Client-Verbindung über Kanal und Hostname konfigurieren

<?php
// Client-Verbindung mit expliziter Kanal-Definition (MQCD)
$connOptions = [
    'Options'    => MQSERIES_MQCNO_CLIENT_BINDING,
    'ClientConn' => [
        'ChannelName'    => 'MY.SVRCONN',
        'TransportType'  => MQSERIES_MQXPT_TCP,
        'ConnectionName' => 'mq-server.example.com(1414)',
    ],
];

mqseries_connx(
    'REMOTE.QMGR',
    $connOptions,
    $hconn,
    $compCode,
    $reason
);

if ($compCode === MQSERIES_MQCC_OK) {
    echo "Client-Verbindung erfolgreich aufgebaut.\n";

    // Queue öffnen
    $mqOd = [
        'ObjectName'  => 'MY.QUEUE',
        'ObjectQMgrName' => '',
    ];
    mqseries_open(
        $hconn,
        $mqOd,
        MQSERIES_MQOO_INPUT_AS_Q_DEF | MQSERIES_MQOO_OUTPUT,
        $hobj,
        $compCode,
        $reason
    );

    if ($compCode === MQSERIES_MQCC_OK) {
        echo "Queue erfolgreich geöffnet.\n";
        mqseries_close($hconn, $hobj, MQSERIES_MQCO_NONE, $compCode, $reason);
    } else {
        echo "Fehler beim Öffnen der Queue: Reason=" . $reason . "\n";
    }

    mqseries_disc($hconn, $compCode, $reason);
} else {
    printf(
        "Verbindung fehlgeschlagen: CompCode=%d, Reason=%d (%s)\n",
        $compCode,
        $reason,
        mqseries_strerror($reason)
    );
}
?>

Client-Verbindung erfolgreich aufgebaut. Queue erfolgreich geöffnet.

// Wichtig · Fallstricke

Fehlerbehandlung: Da mqseries_connx() keinen Rückgabewert liefert, ist es zwingend erforderlich, nach jedem Aufruf $compCode und $reason zu prüfen. Mit mqseries_strerror($reason) lässt sich der Reason Code in einen lesbaren Text umwandeln.

Ressourcen-Verwaltung: Jede erfolgreich geöffnete Verbindung muss am Ende explizit mit mqseries_disc() geschlossen werden, um Ressourcen auf dem Queue-Manager freizugeben. Fehlende Trennungen können zu Verbindungslimits führen.

Sicherheit: Zugangsdaten (z. B. für gesicherte Kanäle) sollten niemals im Quellcode hart kodiert werden. Verwende Umgebungsvariablen oder einen sicheren Konfigurations-Store. Achte darauf, dass TLS/SSL-Kanaloptionen korrekt gesetzt sind, wenn sensible Daten übertragen werden.

Voraussetzungen: Die PHP-Erweiterung mqseries muss installiert und aktiviert sein. Die IBM MQ Client-Bibliotheken müssen auf dem System vorhanden sein. Auf einem Server ohne MQ-Installation sind die Konstanten wie MQSERIES_MQCNO_CLIENT_BINDING nicht verfügbar.

Siehe auch

mqseries_conn mqseries_disc mqseries_open mqseries_close mqseries_put mqseries_get mqseries_strerror