mqseries_inq — Funktion · PHP-Referenz

Signatur

mqseries_inq(resource $hconn, resource $hobj, int $selectorCount, array $selectors, int $intAttrCount, mixed &$intAttrs, int $charAttrLength, mixed &$charAttrs, mixed &$compCode, mixed &$reason): void

Beschreibung

mqseries_inq ruft die IBM MQ-Funktion MQINQ auf und ermöglicht es, Attribute eines geöffneten MQ-Objekts – etwa einer Queue oder eines Queue-Managers – abzufragen. Die gewünschten Attribute werden über Selektorkonstanten (z. B. MQSERIES_MQIA_CURRENT_Q_DEPTH) angegeben.

Die Funktion liefert zwei Arten von Attributen: Integer-Attribute (z. B. aktuelle Queue-Tiefe, maximale Nachrichtenanzahl) werden im Array $intAttrs gespeichert, Zeichenkettenattribute (z. B. Queue-Beschreibung, Queue-Manager-Name) im Buffer $charAttrs. Beide Parameter werden als Referenz übergeben und von der Funktion befüllt.

Die Parameter $compCode (Completion Code) und $reason (Reason Code) geben Auskunft über Erfolg oder Fehlschlag des Aufrufs. Ein $compCode von MQSERIES_MQCC_OK zeigt Erfolg an. Bei Fehlern liefert $reason einen IBM-MQ-spezifischen Fehlercode zur weiteren Diagnose.

Diese Funktion ist Teil der PHP-Erweiterung mqseries und erfordert eine IBM MQ-Installation sowie eine geöffnete Verbindung ($hconn) und einen geöffneten Objekt-Handle ($hobj), die zuvor mit mqseries_conn bzw. mqseries_open erzeugt wurden.

Parameter

Name	Typ	Beschreibung
$hconn Pflicht	resource	Verbindungs-Handle zum IBM MQ Queue-Manager, erzeugt durch `mqseries_conn` oder `mqseries_connx`.
$hobj Pflicht	resource	Objekt-Handle des geöffneten MQ-Objekts (z. B. Queue), erzeugt durch `mqseries_open`.
$selectorCount Pflicht	int	Anzahl der Selektoren im Array `$selectors`, die abgefragt werden sollen.
$selectors Pflicht	array	Array von MQIA_- und MQCA_-Selektorkonstanten, die angeben, welche Attribute abgefragt werden sollen (z. B. `MQSERIES_MQIA_CURRENT_Q_DEPTH`).
$intAttrCount Pflicht	int	Anzahl der erwarteten Integer-Attribute (entspricht der Anzahl der MQIA_-Selektoren in `$selectors`).
$intAttrs Pflicht	mixed	Wird als Referenz übergeben und nach dem Aufruf mit einem Array der abgefragten Integer-Attributwerte befüllt.
$charAttrLength Pflicht	int	Gesamtlänge des Zeichenketten-Puffers für alle Zeichenkettenattribute. Muss ausreichend groß für alle MQCA_-Attributwerte zusammen sein.
$charAttrs Pflicht	mixed	Wird als Referenz übergeben und nach dem Aufruf mit einem String der verketteten Zeichenkettenattribute befüllt.
$compCode Pflicht	mixed	Wird als Referenz übergeben und enthält nach dem Aufruf den MQCC-Completion-Code (`MQSERIES_MQCC_OK`, `MQSERIES_MQCC_WARNING` oder `MQSERIES_MQCC_FAILED`).
$reason Pflicht	mixed	Wird als Referenz übergeben und enthält nach dem Aufruf den IBM-MQ-Reason-Code, der im Fehlerfall Auskunft über die Ursache gibt.

Rückgabewert

Typ

void

Beschreibung

Die Funktion hat keinen direkten Rückgabewert. Ergebnisse und Statusinformationen werden über die Referenzparameter $intAttrs, $charAttrs, $compCode und $reason zurückgegeben.

Beispiele

Aktuelle Queue-Tiefe einer IBM MQ Queue abfragen

<?php
// Verbindung zum Queue-Manager herstellen
mqseries_conn('QM_TEST', $hconn, $compCode, $reason);
if ($compCode !== MQSERIES_MQCC_OK) {
    die("Verbindung fehlgeschlagen. Reason: $reason");
}

// Queue öffnen (nur zum Abfragen von Attributen)
$mqod = [
    'ObjectName'  => 'TEST.QUEUE',
    'ObjectType'  => MQSERIES_MQOT_Q,
];
mqseries_open(
    $hconn,
    $mqod,
    MQSERIES_MQOO_INQUIRE,
    $hobj,
    $compCode,
    $reason
);
if ($compCode !== MQSERIES_MQCC_OK) {
    die("Queue öffnen fehlgeschlagen. Reason: $reason");
}

// Aktuelle Queue-Tiefe (Integer-Attribut) abfragen
$selectors  = [MQSERIES_MQIA_CURRENT_Q_DEPTH];
mqseries_inq(
    $hconn,
    $hobj,
    1,           // 1 Selektor
    $selectors,
    1,           // 1 Integer-Attribut erwartet
    $intAttrs,
    0,           // keine Zeichenkettenattribute
    $charAttrs,
    $compCode,
    $reason
);

if ($compCode === MQSERIES_MQCC_OK) {
    echo "Aktuelle Queue-Tiefe: " . $intAttrs[0] . PHP_EOL;
} else {
    echo "Fehler beim Abfragen. CompCode: $compCode, Reason: $reason" . PHP_EOL;
}

// Queue schließen und Verbindung trennen
mqseries_close($hconn, $hobj, MQSERIES_MQCO_NONE, $compCode, $reason);
mqseries_disc($hconn, $compCode, $reason);
?>

Aktuelle Queue-Tiefe: 42

Queue-Beschreibung (Zeichenkettenattribut) abfragen

<?php
// Voraussetzung: $hconn und $hobj wurden bereits geöffnet (s. Beispiel 1)

// Zeichenkettenattribut: Queue-Beschreibung (MQCA_Q_DESC hat max. 64 Zeichen)
$selectors = [MQSERIES_MQCA_Q_DESC];
mqseries_inq(
    $hconn,
    $hobj,
    1,           // 1 Selektor
    $selectors,
    0,           // keine Integer-Attribute
    $intAttrs,
    64,          // Puffergröße für Zeichenkettenattribut
    $charAttrs,
    $compCode,
    $reason
);

if ($compCode === MQSERIES_MQCC_OK) {
    echo "Queue-Beschreibung: " . trim($charAttrs) . PHP_EOL;
} else {
    echo "Fehler. CompCode: $compCode, Reason: $reason" . PHP_EOL;
}
?>

Queue-Beschreibung: Meine Testqueue

// Wichtig · Fallstricke

Selektoren und Attributtypen: MQIA_-Selektoren liefern Integer-Attribute, MQCA_-Selektoren Zeichenkettenattribute. Integer- und Zeichenkettenselektoren können in einem Aufruf gemischt werden, müssen aber korrekt auf $intAttrCount und $charAttrLength aufgeteilt werden.

Puffergröße: Der Parameter $charAttrLength muss die Summe der maximalen Längen aller angeforderten Zeichenkettenattribute betragen. Ist der Puffer zu klein, gibt IBM MQ den Reason Code MQRC_CHAR_ATTR_LENGTH_ERROR zurück.

Fehlerbehandlung: Überprüfe nach jedem Aufruf sowohl $compCode als auch $reason. Die Reason Codes sind in der IBM MQ-Dokumentation beschrieben. Ein $compCode von MQSERIES_MQCC_WARNING kann auf teilweise erfolgreiche Abfragen hinweisen.

Erweiterungsverfügbarkeit: Die mqseries-Erweiterung ist nicht standardmäßig in PHP enthalten und erfordert eine separate Installation sowie eine IBM MQ Client-Bibliothek auf dem System.

Siehe auch

mqseries_conn mqseries_connx mqseries_open mqseries_close mqseries_disc mqseries_set