API-Exits konfigurieren

Ein API-Exit ist ein Codemodul (eine DLL-Datei), das von Ihnen bereitgestellt und unmittelbar vor oder nach einem MQI-Aufruf ausgeführt wird.

Informationen zu diesem Vorgang

Wenn IBM® MQ an einem seiner API-Eingangspunkte einen Aufruf aus einem Programm empfängt, ruft IBM MQ Ihren API-Exit auf. Ausgeführt wird der API-Exit entweder vor oder nach der MQI-Ausführung, je nachdem, wie der Exit von Ihnen konfiguriert wurde.

Sie können konfigurieren, dass kein Exit, ein Exit oder mehrere Exits aufgerufen werden. Im Falle mehrerer Exits können Sie zudem die Reihenfolge ihres Aufrufs konfigurieren. Unter Windows und Linux® (x86- und x86-64-Plattformen) können Sie die API-Exits mithilfe des IBM MQ Explorer konfigurieren. Die Konfigurationsdetails werden in INI-Dateien gespeichert.

  1. Konfigurieren Sie einen API-Exit in IBM MQ Explorer.
  2. Überschreiben Sie einen allgemeinen API-Exit mit einem lokalen API-Exit.
Es gibt die folgenden drei Definitionsarten für API-Exits:
Allgemein (ApiExitCommon)
Ein Set mit Definitionen pro Computer. Wenn der Warteschlangenmanager gestartet wird, werden die definierten API-Exits (sofern welche definiert wurden) gelesen und auf den Warteschlangenmanager angewendet. Allgemeine API-Exits werden im Eigenschaftendialog von IBM MQ konfiguriert. Angezeigt werden allgemeine Exits in der Tabelle Lokale API-Exits im Eigenschaftendialog des jeweiligen lokalen Warteschlangenmanagers.
Schablone (ApiExitTemplate)
Ein Set mit Definitionen pro Computer. Wenn ein Warteschlangenmanager erstellt wird, werden die hier definierten API-Exits (sofern welche definiert wurden) als lokale Exits in den neu erstellten Warteschlangenmanager kopiert. Die API-Exits des Typs 'Schablone' werden im Eigenschaftendialog von IBM MQ konfiguriert.
Lokal (ApiExitLocal)
Ein Set mit Definitionen pro Warteschlangenmanager. Wenn der Warteschlangenmanager gestartet wird, überschreiben die definierten API-Exits die allgemeinen Exits, vorausgesetzt, ihr Attribut Name stimmt jeweils überein und es wurde eine Überschreibung angegeben. Wenn ein allgemeiner API-Exit überschrieben wird, bleibt keines der Felder in der allgemeinen Definition erhalten, auch wenn dem optionalen Attribut Daten ein Wert zugewiesen ist. Lokale API-Exits konfigurieren Sie im Eigenschaftendialog des Warteschlangenmanagers.
Wenn Sie API-Exits in den Eigenschaftendialogen von IBM MQ und Warteschlangenmanagern konfigurieren, werden die Attributwerte zu den Zeilengruppen ApiExitCommon, ApiExitTemplate und ApiExitLocal in den Konfigurationsdateien oder in der Windows-Registrierung hinzugefügt.
Tabelle 1. Attribute für API-Exits
Attribut Bedeutung Zeilengruppenschlüssel
Name Gibt den beschreibenden Namen des API-Exits an, der im Feld 'ExitInfoName' der MQAXP-Struktur an den API-Exit übergeben wird. Dieser Name muss eindeutig sein und darf nur aus maximal 48 Zeichen bestehen; er darf nur Zeichen enthalten, die für IBM MQ-Objekte gültig sind (beispielsweise Warteschlangennamen). Name
Type Gibt die Art des Exits an: allgemein, Schablone, lokal oder überschreibend. (Dies ist kein separater Zeilengruppenschlüssel.)
Sequence Dieses Attribut ist ein numerischer Wert ohne Vorzeichen, der definiert, wann dieser API-Exit unter mehreren API-Exits aufgerufen wird. Ein API-Exit mit einer niedrigen Folgenummer wird vor einem API-Exit mit einer höheren Folgenummer aufgerufen. Die Reihenfolge, in der verschiedene API-Exits mit derselben Folgenummer aufgerufen werden, ist nicht definiert. Zwischen den Folgenummern der API-Exits, die für einen Warteschlangenmanager definiert sind, können auch Lücken bestehen. Sequence
Module Gibt das Modul an, das den Code für den API-Exit enthält. Falls dieses Feld den vollständigen Pfadnamen des Moduls enthält, wird dieser unverändert verwendet. Enthält dieses Feld jedoch nur den Modulnamen, wird das Modul mit derselben Methode wie bei Kanalexits gesucht; hierbei wird der Wert verwendet, der im Feld Standardpfad für Exit auf der Seite 'Exits' des Dialogs mit den Warteschlangenmanagereigenschaften angegeben ist. Module
Function Gibt den Namen des Eingangspunkts der Funktion in dem Modul an, das den Code für den API-Exit enthält. Bei diesem Eingangspunkt handelt es sich um die MQ_INIT_EXIT-Funktion. Die Feldlänge ist auf den Wert von MQ_EXIT_NAME_LENGTH beschränkt. Function
Data Falls dieses Attribut angegeben wird, werden führende und abschließende Leerzeichen entfernt, die verbleibende Zeichenfolge bei 32 Zeichen abgeschnitten und das Ergebnis an den Exit im Feld 'ExitData' der MQAXP-Struktur übergeben. Wird dieses Attribut nicht angegeben, wird der Standardwert (32 Leerzeichen) an den Exit im Feld 'ExitData' der MQAXP-Struktur übergeben. Data

Vorgehensweise

  • [OPTION 1] Konfigurieren Sie einen API-Exit in IBM MQ Explorer.
    1. Öffnen Sie den betreffenden Eigenschaftendialog:
    2. Klicken Sie auf der Seite Exits auf Hinzufügen.... Daraufhin wird der Dialog API-Exit hinzufügen geöffnet.
    3. Geben Sie die erforderlichen Informationen in die Felder des Dialogs API-Exit hinzufügen ein.
    4. Klicken Sie auf OK, um den Exit zu erstellen und den Dialog API-Exit hinzufügen zu schließen.
    Die Eigenschaften des neuen API-Exits werden in der Tabelle auf der Seite 'Exits' angezeigt.
  • [OPTION 2] Überschreiben Sie einen allgemeinen API-Exit mit einem lokalen API-Exit.

    Wird auf einem Warteschlangenmanager ein lokaler API-Exit mit demselben Namen wie ein allgemeiner Exit definiert, wird der allgemeine Exit überschrieben, d. h. nicht der allgemeine Exit wird aufgerufen, sondern der überschreibende lokale Exit. Um ein versehentliches Überschreiben zu verhindern, sind zur Konfiguration einer Überschreibung in der Benutzerschnittstelle bewusst durchgeführte Aktionen erforderlich; so können Sie beispielsweise einen neuen Exit nicht hinzufügen, wenn bereits ein Exit mit demselben Namen vorhanden ist, und Sie können den Namen eines Exits nicht in den Namen eines bereits vorhandenen Exits ändern. Aber möglicherweise möchten Sie einen lokalen API-Exit zu einem Warteschlangenmanager hinzufügen, sodass nicht der allgemeine API-Exit, sondern der lokale API-Exit verwendet wird. In diesem Fall müssen Sie den allgemeinen API-Exit mit dem lokalen API-Exit überschreiben.

    1. Öffnen Sie im Eigenschaftenkatalog des Warteschlangenmanagers die Seite Exits.
    2. In der Tabelle Lokale API-Exits klicken Sie auf den allgemeinen Exit, die Sie überschreiben wollen.
    3. Klicken Sie auf Überschreiben.
      Daraufhin wird der Dialog API-Exit bearbeiten geöffnet, in dem der Name des allgemeinen API-Exits angezeigt wird.
    4. Geben Sie die Einzeldaten zum lokalen API-Exit im Dialog API-Exit bearbeiten ein und klicken Sie auf OK, um die Änderungen zu speichern.
    Damit überschreibt der lokale Exit den gleichnamigen allgemeinen Exit.