mqseries_close — Funktion · PHP-Referenz

Signatur

mqseries_close(resource $hconn, resource $hobj, int $options, int &$compCode, int &$reason): void

Beschreibung

mqseries_close() ruft die IBM MQ Funktion MQCLOSE auf und schließt ein zuvor mit mqseries_open() geöffnetes Objekt-Handle. Typischerweise handelt es sich dabei um eine Message Queue, ein Topic oder ein anderes MQSeries-Verwaltungsobjekt.

Die Funktion gibt Rückmeldung über den Erfolg oder mögliche Fehler über die Referenz-Parameter $compCode (Completion Code) und $reason (Reason Code). Diese entsprechen den Standard-IBM-MQ-Codes: Ein Completion Code von MQCC_OK (0) zeigt Erfolg an, während MQCC_WARNING (1) oder MQCC_FAILED (2) auf Probleme hinweisen, die über den Reason Code näher spezifiziert werden.

Über den Parameter $options können Optionen wie MQCO_DELETE oder MQCO_DELETE_PURGE übergeben werden, um ein temporäres dynamisches Objekt beim Schließen zu löschen. Für permanente Queues oder Standard-Anwendungsfälle wird typischerweise MQCO_NONE (0) verwendet.

Es ist wichtig, mqseries_close() vor mqseries_disc() aufzurufen, um Ressourcen korrekt freizugeben und keine offenen Handles zu hinterlassen. Eine korrekte Fehlerbehandlung nach dem Aufruf ist essentiell für robuste MQ-Anwendungen.

Parameter

Name	Typ	Beschreibung
$hconn Pflicht	resource	Das Verbindungs-Handle zur MQSeries-Verbindung, das zuvor mit `mqseries_conn()` oder `mqseries_connx()` erzeugt wurde.
$hobj Pflicht	resource	Das Objekt-Handle, das mit `mqseries_open()` geöffnet wurde und nun geschlossen werden soll.
$options Pflicht	int	Steuert das Verhalten beim Schließen. Mögliche Werte sind z. B. `MQCO_NONE` (0), `MQCO_DELETE` oder `MQCO_DELETE_PURGE` für dynamische Queues.
$compCode Pflicht	int	Wird per Referenz übergeben und enthält nach dem Aufruf den MQCC-Completion-Code: `0` = OK, `1` = Warnung, `2` = Fehler.
$reason Pflicht	int	Wird per Referenz übergeben und enthält nach dem Aufruf den MQRC-Reason-Code, der den Completion Code näher beschreibt. Bei Erfolg ist der Wert `MQRC_NONE` (0).

Rückgabewert

Typ

void

Beschreibung

Die Funktion gibt keinen Rückgabewert zurück. Ergebnis und Fehlerinformationen werden über die Referenzparameter $compCode und $reason kommuniziert.

Beispiele

Queue öffnen, Nachricht senden und Handle schließen

<?php
// Verbindung zum Queue Manager herstellen
mqseries_conn('QM_MYMANAGER', $hconn, $compCode, $reason);

if ($compCode !== MQCC_OK) {
    echo "Verbindungsfehler. Reason: $reason\n";
    exit;
}

// Queue öffnen
$od = [
    'ObjectName' => 'MY.QUEUE',
    'ObjectType' => MQOT_Q,
];

mqseries_open(
    $hconn,
    $od,
    MQOO_OUTPUT | MQOO_FAIL_IF_QUIESCING,
    $hobj,
    $compCode,
    $reason
);

if ($compCode !== MQCC_OK) {
    echo "Queue konnte nicht geöffnet werden. Reason: $reason\n";
    mqseries_disc($hconn, $compCode, $reason);
    exit;
}

// Nachricht einreihen (hier vereinfacht ausgelassen)
// ...

// Queue-Handle schließen
mqseries_close($hconn, $hobj, MQCO_NONE, $compCode, $reason);

if ($compCode !== MQCC_OK) {
    echo "Fehler beim Schließen der Queue. Reason: $reason\n";
} else {
    echo "Queue erfolgreich geschlossen.\n";
}

// Verbindung trennen
mqseries_disc($hconn, $compCode, $reason);
echo "Verbindung getrennt.\n";

Queue erfolgreich geschlossen. Verbindung getrennt.

Dynamische Queue beim Schließen löschen

<?php
// Verbindung herstellen
mqseries_conn('QM_MYMANAGER', $hconn, $compCode, $reason);

// Dynamische Queue öffnen
$od = [
    'ObjectName'         => 'MY.MODEL.QUEUE',
    'DynamicQName'       => 'MY.TEMP.*',
    'ObjectType'         => MQOT_Q,
];

mqseries_open(
    $hconn,
    $od,
    MQOO_INPUT_EXCLUSIVE | MQOO_FAIL_IF_QUIESCING,
    $hobj,
    $compCode,
    $reason
);

if ($compCode !== MQCC_OK) {
    echo "Fehler beim Öffnen der dynamischen Queue. Reason: $reason\n";
    mqseries_disc($hconn, $compCode, $reason);
    exit;
}

// Nachrichten verarbeiten ...
// ...

// Dynamische Queue beim Schließen löschen und restliche Nachrichten verwerfen
mqseries_close($hconn, $hobj, MQCO_DELETE_PURGE, $compCode, $reason);

if ($compCode === MQCC_OK) {
    echo "Dynamische Queue gelöscht und alle Nachrichten verworfen.\n";
} else {
    echo "Fehler: CompCode=$compCode, Reason=$reason\n";
}

mqseries_disc($hconn, $compCode, $reason);

Dynamische Queue gelöscht und alle Nachrichten verworfen.

// Wichtig · Fallstricke

Reihenfolge beachten: mqseries_close() muss vor mqseries_disc() aufgerufen werden. Das Trennen der Verbindung ohne vorheriges Schließen aller Handles kann zu Ressourcenlecks und unerwartetem Verhalten führen.

Optionen für dynamische Queues: MQCO_DELETE löscht eine leere temporäre dynamische Queue; MQCO_DELETE_PURGE löscht sie auch dann, wenn noch Nachrichten vorhanden sind. Bei permanenten Queues muss MQCO_NONE verwendet werden — andernfalls schlägt der Aufruf fehl.

Erweiterung erforderlich: Die mqseries_*-Funktionen erfordern die PHP-Erweiterung mqseries (PECL), die nicht zum PHP-Kern gehört und separat installiert werden muss. Außerdem muss der IBM MQ Client auf dem System installiert sein.

Siehe auch

mqseries_open mqseries_conn mqseries_connx mqseries_disc mqseries_put mqseries_get