mqseries_set — Funktion · PHP-Referenz

Signatur

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

Beschreibung

mqseries_set ist die PHP-Bindung für den IBM MQ-API-Aufruf MQSET. Mit dieser Funktion können Attribute eines geöffneten IBM MQ-Objekts (typischerweise einer Queue) zur Laufzeit verändert werden, ohne das Objekt schließen und neu öffnen zu müssen.

Üblicherweise werden damit steuerbare Attribute wie Inhibit-Flags (MQIA_INHIBIT_GET, MQIA_INHIBIT_PUT) einer Queue gesetzt. Ganzzahlige Attribute werden über $selectors und $intAttrs übergeben, zeichenbasierte Attribute über $charAttrs.

Die Funktion gibt keinen direkten Rückgabewert zurück; Erfolg oder Fehler werden durch die Ausgabeparameter $compCode (Completion Code) und $reason (Reason Code) signalisiert. Ein $compCode von MQCC_OK bedeutet Erfolg, MQCC_WARNING oder MQCC_FAILED weisen auf Probleme hin, die über $reason näher beschrieben werden.

Voraussetzung ist eine aktive Verbindung zum Queue Manager (via mqseries_conn oder mqseries_connx) sowie ein geöffnetes Objekt-Handle (via mqseries_open) mit der Option MQOO_SET.

Parameter

Name	Typ	Beschreibung
$hconn Pflicht	resource	Handle der Verbindung zum IBM MQ Queue Manager, wie von `mqseries_conn()` oder `mqseries_connx()` zurückgegeben.
$hobj Pflicht	resource	Handle des geöffneten IBM MQ-Objekts (z. B. einer Queue), das mit `mqseries_open()` und der Option `MQOO_SET` geöffnet worden sein muss.
$selectorCount Pflicht	int	Anzahl der Selektoren im Array `$selectors`, also die Anzahl der Attribute, die gesetzt werden sollen.
$selectors Pflicht	array	Array mit MQ-Attribut-Selektoren (Konstanten wie `MQIA_INHIBIT_GET`), die die zu setzenden Attribute identifizieren.
$intAttrCount Pflicht	int	Anzahl der ganzzahligen Attributwerte im Array `$intAttrs`.
$intAttrs Pflicht	array	Array mit ganzzahligen Attributwerten, die den Selektoren vom Typ `MQIA_*` entsprechen.
$charAttrLength Pflicht	int	Gesamtlänge der zeichenbasierten Attribute in Bytes, die in `$charAttrs` übergeben werden. Bei reinen ganzzahligen Attributen wird `0` übergeben.
$charAttrs Pflicht	array	Array mit zeichenbasierten Attributwerten, die den Selektoren vom Typ `MQCA_*` entsprechen. Bei reinen ganzzahligen Attributen wird ein leeres Array übergeben.
$compCode Pflicht	resource	Ausgabeparameter, der nach dem Aufruf den MQ-Completion-Code enthält (`MQCC_OK`, `MQCC_WARNING` oder `MQCC_FAILED`).
$reason Pflicht	resource	Ausgabeparameter, der nach dem Aufruf den MQ-Reason-Code enthält und bei Fehler oder Warnung die genaue Ursache beschreibt.

Rückgabewert

Typ

void

Beschreibung

Die Funktion gibt keinen Wert zurück. Ergebnis und Fehlerinformationen werden ausschließlich über die Ausgabeparameter $compCode und $reason mitgeteilt.

Beispiele

Get-Operationen für eine Queue sperren (MQIA_INHIBIT_GET)

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

// Queue öffnen mit MQOO_SET
$od = [
    'ObjectName' => 'TEST.QUEUE',
    'ObjectType' => MQOT_Q,
];
mqseries_open(
    $hconn,
    $od,
    MQOO_SET,
    $hobj,
    $compCode,
    $reason
);
if ($compCode !== MQCC_OK) {
    die("Queue öffnen fehlgeschlagen. Reason: $reason");
}

// Get-Operationen auf der Queue sperren
mqseries_set(
    $hconn,
    $hobj,
    1,                          // Anzahl Selektoren
    [MQIA_INHIBIT_GET],         // Selektor: Inhibit-Get-Attribut
    1,                          // Anzahl ganzzahliger Attribute
    [MQQA_GET_INHIBITED],       // Wert: Get gesperrt
    0,                          // Keine Zeichenattribute
    [],                         // Leeres Zeichenattribut-Array
    $compCode,
    $reason
);

if ($compCode === MQCC_OK) {
    echo "Get-Operationen für TEST.QUEUE erfolgreich gesperrt.\n";
} else {
    echo "Fehler beim Setzen des Attributs. CompCode: $compCode, Reason: $reason\n";
}

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

Get-Operationen für TEST.QUEUE erfolgreich gesperrt.

Get-Sperre aufheben (MQQA_GET_ALLOWED)

<?php
// Verbindung und Queue-Öffnung wie oben (MQOO_SET) vorausgesetzt...

// Get-Operationen wieder erlauben
mqseries_set(
    $hconn,
    $hobj,
    1,
    [MQIA_INHIBIT_GET],
    1,
    [MQQA_GET_ALLOWED],   // Wert: Get wieder erlaubt
    0,
    [],
    $compCode,
    $reason
);

if ($compCode === MQCC_OK) {
    echo "Get-Operationen für Queue wieder erlaubt.\n";
} else {
    echo "Fehler: CompCode=$compCode, Reason=$reason\n";
}
?>

Get-Operationen für Queue wieder erlaubt.

// Wichtig · Fallstricke

Wichtig: Die Queue (oder ein anderes MQ-Objekt) muss mit der Option MQOO_SET geöffnet worden sein, andernfalls schlägt mqseries_set mit einem entsprechenden Reason Code fehl (z. B. MQRC_NOT_AUTHORIZED oder MQRC_OPTION_NOT_VALID_FOR_TYPE).

Nicht alle MQ-Attribute sind über MQSET veränderbar. Statische Attribute (z. B. Queue-Name, Queue-Typ) können nur über MQ-Administrationswerkzeuge wie runmqsc geändert werden. Versuche, schreibgeschützte Attribute zu setzen, führen zu einem Fehler-Reason-Code.

Die PHP-Erweiterung mqseries ist nicht standardmäßig in PHP enthalten und muss separat installiert werden. Sie setzt das Vorhandensein der IBM MQ-Client-Bibliotheken auf dem System voraus.

Siehe auch

mqseries_conn mqseries_connx mqseries_open mqseries_close mqseries_inq mqseries_disc